Operations

Operations

tfps_ctl is the operational interface. Block commands access the live kernel map. Learned state comes from the latest SQLite checkpoint, and the output reports the snapshot age.

tfps_ctl status                       running state, blocks, and state freshness
tfps_ctl stats                        kernel, traffic, and calibration counters
tfps_ctl banned [--why]               active blocks, expiry, and reason
tfps_ctl unban <ip>... | --all        remove blocks immediately
tfps_ctl ban <ip> [--ttl N]           add a manual block
tfps_ctl sources [--peer --country]   learned sources and destinations
tfps_ctl source <peer>                detail about one source
tfps_ctl peers                        sources ordered by country breadth
tfps_ctl log [--limit N] [--ip IP]    block audit log

Commands that read or change the XDP map require root or CAP_BPF.

Verify a deployment

1. Follow the live log with journalctl -u tfps -f.
2. Confirm packets and sip rise while traffic is present.
3. Confirm the reported interface and watched ports.
4. Check that trusted sources are exempt and cannot be blocked.
5. Compare XDP: dropped with known scanner traffic. Dropped packets should largely vanish from sngrep and tcpdump on the host.
6. Investigate warnings about IPv6, TCP, silence, unparsed traffic, or rules that never match. They identify coverage gaps.

Block lifecycle

Perimeter blocks expire after block_ttl seconds—one hour by default. A returning scanner can be condemned again. APIBAN entries are retained for seven days as a rolling feed.

Use tfps_ctl banned --why before removing an unfamiliar block. An unban affects the next packet because it edits the live map. The audit log records why and when blocks were added; the unban rate is the practical false-positive signal.

Persistence and upgrades

The default SQLite database is /var/lib/tfps/tfps.db. Behavioural learning, checkpoints, the audit log, and APIBAN cursor survive restarts. Perimeter working state rebuilds from traffic.

For an upgrade, build the new revision and run sudo ./packaging/install.sh again. It is idempotent and preserves /etc/tfps/config.json. Confirm the status and XDP counters after restart.