Systemd Units Overview

Systemd Units & Timers

Type: Architecture (Operator Reference) Scope: All systemd services and timers, dependencies, schedules Terminology: Glossary & Vocabulary

---

Purpose

See also: Architecture | Configuration

This page lists all NFTBan systemd units, their purpose, scheduling, and dependencies. NFTBan uses 28 services and 19 timers.

---

Role in System Architecture

Systemd services are the execution layer — they maintain and operate the system. They do NOT define system state.

Layer	Role
Kernel	Enforcement authority (packet decisions)
Validator	Truth verification (reads kernel)
Systemd	Execution layer (maintenance, sync, automation)

A running daemon does NOT guarantee protection. Only kernel structure + validator status define system state.

• nftband stopped → existing kernel rules still enforce
• Timers stopped → system degrades over time (stale feeds, no health cache)
• Kernel broken → system DOWN regardless of service status

Operators must rely on validator output (nftban-validate), not service status.

Failure propagation: Timer stops → feeds become stale → blacklist data outdated → enforcement degrades over time. This is why the validator checks timer liveness (VAL-TIMER-001).

---

Core Services

nftband.service — Go daemon

Property	Value
Description	NFTBan Daemon (Single nftables Writer)
User	root
ExecStart	/usr/lib/nftban/bin/nftband
After	network.target, nftables.service, nftban-firewall-init.service
Wants	nftables.service
Type	notify
Role	Ban/unban execution, LoginMon pipeline, BotGuard scoring, IPC

This is the primary Go daemon. It writes to kernel sets. If it stops, daemon-dependent modules (BotGuard, LoginMon) cannot issue new protection actions. Kernel-only modules (DDoS, Portscan) continue enforcing.

nftban-firewall-init.service — Boot-time schema load

Property	Value
Type	oneshot
When	Boot (before nftband)
Role	Loads nftables schema at boot if not already present

---

Timer-Driven Services

Maintenance cycle

Timer	Service	Schedule	Jitter	User	Purpose
nftban-maintenance.timer	nftban-maintenance.service	Every 15 min (*:0/15)	5 min	root	Safety checks, housekeeping (10 steps)
nftban-watchdog.timer	nftban-watchdog.service	Every 120s	—	root	System pressure monitoring
nftban-queue.timer	nftban-queue.service	Variable	—	root	Task queue processing
nftban-health.timer	nftban-health.service	Daily	—	root	Health cache update

Maintenance does NOT rotate logs. Log rotation is handled by OS logrotate.timer reading /etc/logrotate.d/nftban. The maintenance service runs safety checks, cleanup, and state verification.

Data sync

Timer	Service	Schedule	Purpose
nftban-core-feeds.timer	nftban-core-feeds.service	Daily ~03:34	Threat feed sync
nftban-core-geoip.timer	nftban-core-geoip.service	Weekly	GeoIP database update
nftban-unified-exporter.timer	nftban-unified-exporter.service	~60s intervals	Metrics export (Prometheus textfile + JSON)

Module timers

Timer	Service	Purpose
nftban-botscan.timer	nftban-botscan.service	L7 batch bot scanning
nftban-tunnel.timer	nftban-tunnel.service	DNS tunnel suspicion scanning
nftban-rbl-check.timer	nftban-rbl-check.service	RBL/DNSBL monitoring
nftban-suricata-update.timer	nftban-suricata-update.service	Suricata rule updates

System management

Timer	Service	Purpose
nftban-update-check.timer	nftban-update-check.service	Check for new NFTBan version
nftban-update-apply.timer	nftban-update-apply.service	Auto-apply updates (if configured)
nftban-snapshot.timer	nftban-snapshot.service	State snapshots
nftban-rollback.timer	nftban-rollback.service	Rollback monitoring
nftban-report-daily.timer	nftban-report-daily.service	Daily report generation

Pro tier (optional)

Timer	Service	Purpose
nftban-pro-license.timer	nftban-pro-license.service	License check
nftban-pro-inventory.timer	nftban-pro-inventory.service	Inventory upload
nftban-community-stats.timer	nftban-community-stats.service	Community statistics

---

Non-Timer Services

Service	Type	Purpose
nftban-api.service	long-running	REST API endpoint
nftban-suricata.service	long-running	Suricata integration
nftban-suricata-stats.service	oneshot	Suricata statistics
nftban-health-fix.service	oneshot	Auto-heal runner
nftban-alert@.service	template	Alert notification

Historical note (≤ v1.100.0). Releases up to v1.100.0 also shipped nftban-ui.service, nftban-ui-auth.service, and nftban-ui-auth.socket (Web GUI + PAM auth). All three were retired in v1.100.1b.A and removed entirely by v1.100.1b.D. On upgrade from a pre-v1.100.1b.A install, package prerm / %pre hooks stop, disable, mask, and remove the orphaned units. See archive/Web-GUI-and-nftban-ui-retired.

---

Timer Liveness (Validator Check)

Since v1.83.0, the Go validator checks timer liveness:

Finding	Severity	Meaning
VAL-TIMER-001	warn	Zero nftban timers active
VAL-TIMER-002	error	Timer query failed

If no timers are active, maintenance, feed sync, and metrics export do not run. The system may function structurally but operational health degrades over time (stale feeds, no health cache updates).

---

Dependencies

nftables.service
    ↑ Wants
nftban-firewall-init.service
    ↑ After
nftband.service (daemon)
    ↑ After
nftban-maintenance.timer (safety checks)
nftban-watchdog.timer (pressure monitoring)
nftban-unified-exporter.timer (metrics)
nftban-core-feeds.timer (feed sync)

All timers depend on nftband being available but do NOT require it to be running. Timer services handle daemon-down gracefully.

---

Management Commands

# Check all NFTBan timers
systemctl list-timers 'nftban-*' --no-legend

# Check daemon status
systemctl status nftband

# Restart daemon
systemctl restart nftband

# Check specific timer
systemctl show nftban-maintenance.timer --property=NextElapseUSecRealtime

# View service logs
journalctl -u nftband --since "1 hour ago"
journalctl -u nftban-maintenance --since "1 hour ago"

---

Verification (MANDATORY)

# Check all timers are active
systemctl list-timers 'nftban-*' --no-legend | wc -l
# Expected: 10+ timers (depends on enabled modules)

# Check daemon is running
systemctl is-active nftband
# Expected: "active"

# Check validator timer finding
nftban-validate --json | jq '.findings[] | select(.code | startswith("VAL-TIMER"))'
# Empty = no timer issues

# Check maintenance ran recently
journalctl -u nftban-maintenance --since "30 min ago" --no-pager | tail -3

---

Limitations

• Maintenance does NOT rotate logs. This is handled by OS logrotate. The old wiki incorrectly stated maintenance performs log rotation.
• Maintenance runs as root (not as nftban user). The old wiki incorrectly stated User=nftban.
• Maintenance schedule is every 15 minutes (OnCalendar=*:0/15 with 5min jitter), not daily. The old wiki stated incorrect cadence.
• Watchdog timer is 120s, not configurable via config files.
• Timer liveness is checked by validator but individual timer health is not. A specific timer can be stopped without triggering a finding — only zero total timers triggers VAL-TIMER-001.