Logging Rotation and Retention

Logging, Rotation and Retention

Type: Operator Reference · Last reviewed for terminology: v1.220.1 Terminology: Glossary & Vocabulary · Paths: FHS Compliance

NFTBan writes both filesystem logs and journald-only records. The authoritative log inventory lives in code (internal/.../logs.go LogInventory()), and a drift test proves every inventoried /var/log/nftban log is covered by the shipped logrotate config. Rotation is by explicit stanza, not a *.log wildcard — a new log must be added to both the inventory and the logrotate config or it will not be rotated.

Record inventory

Record	Path / journal	Producer	Format	Owner:group · mode	Rotation authority	Sensitive?
Main app log	/var/log/nftban/nftban.log	daemon + scripts	text	nftban:nftban	logrotate (copytruncate, weekly ×4)	IPs, hostnames
Login-monitor log	/var/log/nftban/login-monitor.log	loginmon	text	nftban:nftban	logrotate (copytruncate)	auth events, IPs
Service alerts	/var/log/nftban/service-alerts.log	maintenance/health	text	nftban:nftban	logrotate	service state
Permissions audit	/var/lib/nftban/permissions_audit.log	FHS/permissions	text	root-owned	logrotate (weekly ×12)	path/owner data
Reports	/var/lib/nftban/reports/*	report generators	HTML/JSON/text	nftban:nftban (0750)	logrotate (monthly ×3)	findings, IPs
Communication delivery log	/var/log/nftban/communication/delivery.jsonl	central mail authority	JSONL	nftban:nftban	app-managed bounded (NFTBAN_MAIL_DELIVERY_LOG_MAX)	recipient (redacted), reason
Mail emulate sink	<data>/mail/test-delivery.jsonl	mail emulate mode	JSONL	nftban:nftban	app-managed	recipient (redacted)
Metrics textfile	/var/lib/nftban/metrics/*.prom	unified exporter	Prometheus	nftban:nftban	overwritten each run	none
Snapshots / rollback	/var/lib/nftban/snapshots/*	snapshot timer	text/json	nftban:nftban	count-bounded	ruleset state
Update forensic records	per-run update dir	updater	JSONL	root-owned	app/package	version/host metadata
Watchdog flight recorder	/var/lib/nftban/reports/watchdog/*	watchdog	json	nftban:nftban	bounded	resource metrics
Daemon runtime log	journald: nftband.service	daemon	journal	—	journald	IPs, events
Maintenance / feeds / geoip / health / etc.	journald: nftban-<unit>.service	each unit	journal	—	journald	varies
Suricata logs	/var/log/nftban/suricata/* + /var/log/suricata/*	Suricata	text/EVE JSON	—	separate logrotate.d/nftban-suricata	alerts, IPs

Values above are the shipped defaults; the generated FHS spec (build/fhs-spec.yaml) is authoritative for owner/mode. Confirm on-host with the commands below.

Rotation authority — be explicit

Every record has a named authority: logrotate (/etc/logrotate.d/nftban, copytruncate because these files have multiple writers that do not all reopen on reload), journald (journal-only units), app-managed bounded retention (delivery log, metrics textfile, snapshots), or the package lifecycle. There is intentionally no catch-all /var/log/nftban/*.log stanza — it would double-rotate and mask a missing inventory entry.

Validation

# What logrotate would do (safe, read-only)
logrotate --debug /etc/logrotate.d/nftban

# Force a rotation — MUTATING, controlled administrative test only
sudo logrotate --force /etc/logrotate.d/nftban

# journald rotation + usage
systemctl status logrotate.timer
journalctl -u logrotate.service
journalctl --disk-usage

# Ownership / mode / size / age of records
find /var/log/nftban /var/lib/nftban /run/nftban -maxdepth 4 -type f \
  -printf '%M %u:%g %s %TY-%Tm-%Td %p\n'

# Package ownership of a path
dpkg -S /var/log/nftban/nftban.log     # Debian family
rpm  -qf /var/log/nftban/nftban.log    # EL family

Retention periods are set in the shipped logrotate config (weekly ×4, weekly ×12 for the permissions audit, monthly ×3 for reports) — do not hard-code other numbers; read the config.

Confidentiality

Filesystem logs and reports may contain IP addresses (IPv4/IPv6), hostnames, authentication events, security findings, and (in the delivery log) SMTP results and redacted recipients. NFTBAN_SMTP_PASS and recipient local-parts are redacted where they appear; the support bundle applies additional redaction (nftban_redact.sh), though full support-bundle redaction is tracked as a separate security lane. nftban-auditor group members have read access to the report/log surfaces; root-owned forensic records stay root-only.

See Communications & Notifications for the delivery log and Audit Reports & Compliance for report retention/integrity.