Communications and Notifications

Communications and Notifications

Type: Operator Reference · Last reviewed for terminology: v1.220.1 Terminology: Glossary & Vocabulary · Config: Configuration Reference

All NFTBan outbound notifications flow through one central communication authority (core/nftban_mail.sh). No protection or monitoring module owns its own transport — a module emits an event/finding, and the central path resolves the recipient, renders the template, selects a transport, attempts delivery, and records the result. This is enforced by a CI guard (check-comms-direct-send.sh) that fails any direct sendmail/mail/mailx/msmtp/curl-SMTP outside the central library.

Central path

Module event / finding
  → nftban_mail_alert / nftban_mail_send        (single entry points)
  → nftban_mail_resolve_recipient               (override → NFTBAN_MAIL_RECIPIENT)
  → template render (header/footer + body)      (HTML or plain)
  → transport selection (nftban_mail_detect_mta / NFTBAN_MAIL_METHOD)
  → delivery attempt (+ retry)
  → delivery result → /var/log/nftban/communication/delivery.jsonl + last-failure state

Transport inventory (implemented)

Transport	Selected when	Dependency	Auth / TLS	Delivery evidence
Local MTA (sendmail/mail/mailx/s-nail/msmtp)	a local MTA is present and no explicit SMTP forced	local MTA binary	as configured on host	delivery.jsonl
Direct SMTP via curl	NFTBAN_SMTP_HOST set (prefer-explicit-SMTP)	curl (hard dep)	NFTBAN_SMTP_USER/PASS, STARTTLS on :587	delivery.jsonl
emulate (test substrate)	NFTBAN_MAIL_METHOD=emulate	none	none	records ATTEMPT to test-delivery.jsonl, no network
disabled / no delivery	NFTBAN_MAIL_ENABLED="NO"	—	—	no send

Daemonless by design: a local mail server is not mandatory. With NFTBAN_SMTP_HOST set, curl-SMTP is first-class and requires no local MTA.

Mail configuration keys (conf.d/mail.conf, .local override)

Key	Default	Meaning
NFTBAN_MAIL_ENABLED	"NO"	master enable
NFTBAN_MAIL_RECIPIENT	""	global recipient
NFTBAN_MAIL_SUBJECT_PREFIX	"[NFTBan]"	subject prefix
NFTBAN_MAIL_METHOD	""	force a transport (emulate for tests)
NFTBAN_SMTP_HOST / _PORT	"" / 587	direct SMTP endpoint
NFTBAN_SMTP_USER / _PASS	""	SMTP auth (secret; redacted in logs/support)
NFTBAN_MAIL_USE_HTML	"YES"	HTML vs plain-text
NFTBAN_MAIL_VALIDATE_RECIPIENTS	"YES"	recipient validation
NFTBAN_MAIL_ALLOWED_PATHS	/var/lib/nftban:/var/log/nftban	attachment path allowlist
NFTBAN_MAIL_MAX_FILE_SIZE	10240	attachment size cap (KB)
NFTBAN_MAIL_ON_BAN / _ON_HEALTH_CRITICAL / _ON_LOGIN_ALERT / _DAILY_REPORT	"NO"	per-event gates
NFTBAN_MAIL_ALERT_SEVERITY	"warning"	minimum alert severity

Use placeholders in examples — never real credentials: alerts@example.net, smtp.example.net. Module-specific override keys (e.g. NFTBAN_RBL_ALERT_EMAIL, NFTBAN_TUNNEL_ALERT_EMAIL) fall back to NFTBAN_MAIL_RECIPIENT.

Secret & config boundaries

conf.d/mail.conf = package default; mail.conf.local = operator override (survives upgrades); NFTBAN_SMTP_PASS is the secret-bearing value (redacted in delivery log and support bundle). Delivery log at /var/log/nftban/communication/delivery.jsonl (nftban:nftban).

End-to-end test workflow (supported commands)

# 1. Validate config only — never sends, never records
nftban mail test --dry-run

# 2. Send a controlled test message
nftban mail test

# 3. Inspect delivery result (transport, recipient, spool, last success/failure)
nftban mail status

There is no nftban communication ... command — the surface is nftban mail. --dry-run validates recipient + transport prerequisites and returns non-zero / INVALID when no transport is configured (that is a truthful no-transport result, not a defect).

Exit code 0 is not proof of delivery. After nftban mail test, confirm with the intended recipient:

• correct recipient, sender, and subject ([NFTBan] prefix);
• HTML and/or plain-text rendered correctly;
• no secret leakage (no NFTBAN_SMTP_PASS);
• expected hostname and IPv4/IPv6 formatting;
• a row appended to delivery.jsonl;
• and that failure is visible (nftban mail status shows last-failure) when the transport is unavailable — try with no MTA and no NFTBAN_SMTP_HOST to see the failure surface.

Communication health is folded into nftban health (the Communication (central-comms) component) and nftban stats comms.

See Notification & Report Templates for the rendered bodies and Security Architecture for secret handling.