Notification and Report Templates

Notification and Report Templates

Type: Operator Reference · Last reviewed for terminology: v1.220.1 Terminology: Glossary & Vocabulary · Delivery: Communications & Notifications

NFTBan ships HTML templates for mail notifications and HTML reports. They are package-managed (installed under /usr/share/nftban/templates/) and rendered by the central mail library (nftban_mail_load_template + nftban_mail_template_replace).

Template inventory (shipped)

Template	Runtime path	Producer / event	Transport
header_default.html / footer_default.html	/usr/share/nftban/templates/mail/	wrap every HTML mail	mail
alert.html	mail/	generic alert	mail
test_email.html	mail/	nftban mail test	mail
stats_email.html	mail/	stats/daily summary email	mail
service_failure.html	mail/	service-failure alert	mail
rbl_alert.html	mail/	RBL listed/degraded alert	mail
login_alert.html	mail/	LoginMon alert	mail
daily.html	/usr/share/nftban/templates/reports/	daily report	report file / mail
stats_dashboard.html	reports/	stats dashboard	report file
fhs_report.html	reports/	FHS compliance report	report file
module_report.html	reports/	per-module report	report file

Zabbix templates ship separately under /usr/share/nftban/templates/zabbix/ (monitoring integration, not mail).

Template authority

Templates are package-managed and installed to /usr/share/nftban/. Treat them as owned by the package — an upgrade may replace them. There is no documented /etc-based operator-override precedence for the HTML bodies; do not tell operators to edit /usr/share copies expecting persistence. (Company/logo customization is via config vars, not template edits — see below.)

Variables (actual syntax: {TOKEN})

Substitution is single-brace uppercase tokens replaced by nftban_mail_template_replace. Common tokens (validate against the specific template before relying on one):

{HOSTNAME} · {SERVER_IP} · {DATE} · {NFTBAN_VERSION} · {ALERT_TITLE} · {ALERT_TYPE} · {ALERT_MESSAGE} · {ALERT_SEVERITY_CLASS} · {ALERT_DETAILS_ROWS} · {ALERT_ACTIONS_HTML} · {ALERT_EXTRA_HTML} · {ACTIVE_BANS} · {HEALTH_STATUS}.

Do not invent {{mustache}}-style placeholders — the engine uses {TOKEN}. Header/footer also honor config vars: NFTBAN_COMPANY_NAME, NFTBAN_LOGO_LOCATION, NFTBAN_VERSION_INCLUDE.

Rendering validation

There is no dedicated render-only lint command; validate via the emulate/dry-run path so nothing is sent:

# Render the full central flow WITHOUT sending (emulate transport)
NFTBAN_MAIL_METHOD=emulate nftban mail test     # writes an ATTEMPT to test-delivery.jsonl
nftban mail test --dry-run                       # validate config only

# Inspect a rendered report file offline
xdg-open /var/lib/nftban/reports/daily/<file>.html   # or open in a browser

When validating rendered output, check for: unexpanded {TOKEN} placeholders, valid HTML + UTF-8 encoding, correct HTML escaping of user-controlled values (reasons, hostnames), correct IPv6 formatting (not truncated), no secret exposure, and reasonable message size (NFTBAN_MAIL_MAX_FILE_SIZE).

HTML report properties

Reports are UTF-8, self-contained (inline styling, no external CDN), and safe to open offline in a browser. Generated HTML lives under /var/lib/nftban/reports/. Confirm on-host whether a given generator escapes all user-controlled values before treating a report as attachment-safe.

See Audit Reports & Compliance for report storage, retention, and integrity boundaries.