Maintenance and Scheduled Operations

Maintenance and Scheduled Operations

Type: Operator Reference · Last reviewed for terminology: v1.220.1 Terminology: Glossary & Vocabulary · Units: Systemd Units & Timers

This page inventories NFTBan's recurring and maintenance operations. Schedules are taken from the shipped install/systemd/*.timer units — regenerate them rather than hand-editing.

There is no nftban maintenance CLI command. Maintenance runs as a systemd timer/service. Use systemctl for direct inspection and nftban services / nftban health / nftban validate for state. Do not document a CLI wrapper that does not dispatch.

Scheduled-operation inventory

Operation	Timer	Schedule	Persistent (catch-up)	Failure impact
Safety checks + housekeeping	nftban-maintenance.timer	every 15 min (*:0/15)	yes	stale housekeeping only; kernel enforcement unaffected
Threat-feed sync	nftban-core-feeds.timer	daily 03:20 (+15 min boot)	yes	feed blacklists go stale; existing bans still enforce
GeoIP DB update	nftban-core-geoip.timer	Sun 02:30	yes	GeoIP DB ages; GeoBan uses last DB
GeoBan refresh	nftban-geoban-refresh.timer	Mon 03:30	yes	country sets not refreshed
Queue processing	nftban-queue.timer	5 min active (3 min boot)	yes	queued tasks delayed
Health cache generation	nftban-health.timer	daily 03:00	yes	health cache ages; live nftban health still works
Watchdog (pressure)	nftban-watchdog.timer	120 s	yes	no adaptive resource control
Unified metrics export	nftban-unified-exporter.timer	60 s active (45 s boot)	yes	Prometheus textfile goes stale
Snapshot	nftban-snapshot.timer	hourly	yes	fewer restore points
Rollback monitoring	nftban-rollback.timer	event-driven (30 s jitter)	—	rollback deadline handling
Rebuild recovery	nftban-rebuild-recovery.timer	60 s after boot (no catch-up)	no	boot-time rebuild recovery only
BotScan collection	nftban-botscan-collector.timer	5 min active (2 min boot)	yes	access-log spool not collected
BotScan scanning	nftban-botscan.timer	10 min active (5 min boot)	yes	exploit scan delayed; no new BotScan bans
RBL check	nftban-rbl-check.timer	02:00 + 14:00	yes	reputation not re-checked (observe-only)
Suricata rule update	nftban-suricata-update.timer	Sun 03:40	yes	Suricata rules age
DNS tunnel scan	nftban-tunnel.timer	every 5 min (*:0/5)	yes	advisory only; no enforcement change
Daily report	nftban-report-daily.timer	daily 06:00	yes	no daily report generated
Update check	nftban-update-check.timer	daily 03:30	yes	update availability not refreshed
Update apply (if enabled)	nftban-update-apply.timer	Sun 04:00	yes	auto-update deferred
Pro: license / inventory / community-stats	nftban-pro-*.timer	6-hourly / 04:00 / daily	yes	Pro telemetry only

All timers carry RandomizedDelaySec (jitter) to avoid thundering-herd. Persistent=true means missed runs execute after a reboot; nftban-rebuild-recovery is Persistent=false (no catch-up — it is a boot-only recovery).

Truth distinctions (do not conflate)

• Scheduled (timer enabled) ≠ ran (last activation) ≠ succeeded (exit 0) ≠ output fresh (state file mtime).
• A stopped maintenance timer does not remove kernel enforcement — the loaded nftables ruleset keeps enforcing. It causes stale data / missed future processing only.
• Maintenance failure ≠ validator DEGRADED. The validator (nftban validate) reports kernel/structure truth; timer liveness is a separate axis (VAL-TIMER-001).

Validation commands (supported)

# Timer inventory + next runs (authoritative)
systemctl list-timers 'nftban-*' --no-legend
systemctl list-unit-files 'nftban-*'

# One timer's exact schedule
systemctl show nftban-maintenance.timer \
  -p OnCalendar -p OnBootUSec -p OnUnitActiveUSec -p RandomizedDelayUSec -p Persistent

# Service state + last run + logs
systemctl status nftban-maintenance.service
systemctl cat nftban-maintenance.service
journalctl -u nftban-maintenance.service --since "1 day ago"

# NFTBan surfaces (no dedicated maintenance CLI)
nftban services        # NFTBan service/timer roll-up
nftban health          # four-axis truth (incl. timer liveness finding)
nftban validate        # kernel/structure truth

See Logging, Rotation & Retention for where each operation writes, and Systemd Units & Timers for the full unit inventory.