Notifications

Overview

Email notifications are event-driven, triggered by audit events recorded in the sftp_audit database table. This means JDBC audit must be enabled for notifications to function — the notification engine reads directly from the audit table to determine which events require alerting.

Three rule types cover different alerting patterns: simple (one email per event), threshold (fires after N events in a time window), and batch (accumulates events per user, sends a digest).

SMTP Configuration

Add a <notifications> block to conf/sftp-server.xml with the SMTP server details and one or more notification rules:

<notifications>
    <smtp>
        <host>mail.example.com</host>
        <port>587</port>
        <starttls>true</starttls>
        <username>alerts@example.com</username>
        <password>appPassword</password>
        <from>noreply@example.com</from>
    </smtp>
    <rules>
        <!-- rules here -->
    </rules>
</notifications>

Testing SMTP Connectivity

Use the admin CLI to verify that the SMTP configuration is correct before deploying notification rules:

admin test-email --to admin@example.com

This sends a test message using the configured SMTP settings. If delivery fails, the error message will indicate the cause (connection refused, authentication failure, TLS handshake error, etc.).

Rule Types

All rules are defined inside the <rules> element. Each <rule> specifies an event type and a recipient address. The rule type is determined by which additional attributes are present.

1. Simple Rule

Sends one email immediately for each matching event. Use this for critical events that require instant notification.

<rule event="UPLOAD_COMPLETE" to="ops@example.com" />

In this example, every completed upload triggers an email to the operations team.

2. Threshold Rule

Fires after a specified number of matching events occur within a time window. Use this for anomaly detection — situations where a single event is normal but a burst indicates a problem.

<rule event="AUTH_FAILURE" to="sec@example.com" threshold="5" window="PT5M" />

In this example, the security team is alerted when 5 authentication failures occur within 5 minutes. The window attribute uses ISO 8601 duration format (e.g. PT5M = 5 minutes, PT1H = 1 hour).

3. Batch Rule

Accumulates events per username and sends a single digest email after a configurable window. Use this to avoid email storms from high-volume operations like bulk file transfers.

<rule event="UPLOAD_COMPLETE" to="ops@example.com" batch-window="PT30S" />

In this example, uploads are grouped by username. After 30 seconds of inactivity (no new uploads from that user), one email is sent containing a CSV manifest of all uploads in the batch. The batch-window attribute uses ISO 8601 duration format.

Supported Events for Rules

The following audit event types can be used in notification rules:

Email Format

Each notification email contains two parts:

• Text body — a human-readable summary of the event or batch of events.
• CSV attachment — a machine-readable file suitable for import into spreadsheets, SIEM tools, or ticketing systems.

CSV Columns

For batch emails, the CSV contains multiple rows — one per event in the batch, grouped by username. The CSV attachment filename follows the pattern:

{event-type}-{username}-{timestamp}.csv

For example: UPLOAD_COMPLETE-alice-20260317T143022.csv

Architecture

Understanding the notification pipeline helps with troubleshooting and performance tuning.

Processing Pipeline

SmtpNotificationSink is part of the CompoundAuditSink chain. When an audit event arrives, the sink signals the notification thread but performs no database work in the event path itself. The notification thread then:

1. Waits 500 milliseconds after the signal to allow JdbcAuditSink to flush its asynchronous batch to the database.
2. Queries the sftp_audit table for unprocessed rows using a LEFT JOIN against sftp_notification_log.
3. Evaluates each unprocessed event against the configured rules.
4. Sends emails for any rules that match.
5. Records sent notifications in sftp_notification_log to prevent duplicate delivery.

Reliability Features

• Deduplication — the sftp_notification_log table uses a composite primary key of audit_id + rule_key, ensuring that each event is processed at most once per rule.
• Safety wake-up — a 30-second periodic timer triggers the notification thread even if no signal was received, catching any events that might have been missed.
• Startup catch-up — when the server starts, the notification engine processes any events that occurred while the server was down, ensuring no alerts are lost during maintenance windows.

Dependencies

Email delivery uses Eclipse Angus Mail 2.0.3, the reference implementation of the Jakarta Mail API. This library is licensed under EPL-2.0 with a GPLv2 Classpath Exception, which permits linking without GPL obligations.

User Email Addresses

Each SFTP user and admin user can have an email address associated with their account. Emails are stored in separate tables (sftp_user_emails and sftp_admin_emails) and can be managed from all admin surfaces:

• Web Admin — email field in the user detail panel (General tab) and admin users table.
• CLI — get-email <name>, set-email <name> [email], get-admin-email <name>, set-admin-email <name> [email].
• Swing — email field in the user detail panel and admin users panel.

Admin email addresses are used as recipients for critical server alerts.

Critical Server Alerts

The admin alert system sends email notifications to all admin users (who have an email address configured) when critical server events occur. Unlike rule-based notifications, alerts are triggered directly by server components and do not require the JDBC audit sink.

Configuration

Add an <admin-alerts> block inside <notifications> in conf/sftp-server.xml:

<notifications>
    <smtp>
        <!-- SMTP config (required) -->
    </smtp>
    <admin-alerts enabled="true">
        <events>DISK_LOW,DISK_CRITICAL,CERT_EXPIRING,LICENSE_EXPIRING</events>
    </admin-alerts>
</notifications>

Alert Types

Behaviour

• Alerts are sent asynchronously on a dedicated daemon thread.
• A 30-minute cooldown per alert type prevents duplicate emails for most alerts (disk, brute force, DB, lifecycle).
• Escalating schedule for expiry alerts (CERT_EXPIRING, LICENSE_EXPIRING):

  Days Remaining	Alert Frequency
  30–7	Once per day
  6–1	Every 6 hours
  0 (expired)	Every hour

• Recipients are all enabled admin users who have an email address configured.
• If no admin emails are configured, alerts are silently skipped.
• SMTP configuration is shared with the notification rules engine.