Usage Guide

Usage Guide

Complete command reference for all 21 CLI commands and the interactive menu system.

CLI Quick Reference

Command	Description	Example
detect	Detect OS and firewalls	sudo python3 apotropaios.py detect
status	Show firewall service state	sudo python3 apotropaios.py status
add-rule	Create and apply a rule	sudo python3 apotropaios.py add-rule --dst-port 443 --action accept
remove-rule	Remove rule by UUID	sudo python3 apotropaios.py remove-rule <UUID>
activate-rule	Re-activate deactivated rule	sudo python3 apotropaios.py activate-rule <UUID>
deactivate-rule	Deactivate (keep in index)	sudo python3 apotropaios.py deactivate-rule <UUID>
list-rules	Show Apotropaios-tracked rules	sudo python3 apotropaios.py list-rules
system-rules	Show native firewall rules	sudo python3 apotropaios.py system-rules
block-all	Block ALL traffic	sudo python3 apotropaios.py block-all
allow-all	Allow ALL traffic	sudo python3 apotropaios.py allow-all
import	Import rules from file	sudo python3 apotropaios.py import rules.conf --dry-run
export	Export rules to file	sudo python3 apotropaios.py export rules.conf
backup	Create configuration backup	sudo python3 apotropaios.py backup pre-deploy
restore	Restore from backup	sudo python3 apotropaios.py restore <backup-file>
install	Install a firewall package	sudo python3 apotropaios.py install nftables
update	Update a firewall package	sudo python3 apotropaios.py update iptables
help	Show help (no init needed)	python3 apotropaios.py help
menu	Launch interactive menu	sudo python3 apotropaios.py menu

Global Options

All global options work before or after the command (position-independent):

# These are equivalent:
sudo python3 apotropaios.py --log-level info detect
sudo python3 apotropaios.py detect --log-level info

# These are equivalent:
sudo python3 apotropaios.py --backend firewalld status
sudo python3 apotropaios.py status --backend firewalld

Option	Default	Description
--log-level LEVEL	warning	Console verbosity: trace, debug, info, warning, error, critical, none
--backend NAME	auto-detect	Firewall backend: iptables, nftables, firewalld, ufw, ipset
--interactive	off	Launch interactive menu
--non-interactive	off	Disable prompts (for scripting). Destructive commands such as reset proceed without their confirmation prompt.
--help / -h	--	Show help (global or per-command)
--version / -v	--	Show version

add-rule Options

Option	Default	Description
--direction	inbound	Traffic direction: inbound, outbound, forward
--protocol	tcp	Protocol: tcp, udp, icmp, icmpv6, sctp, all
--src-ip	any	Source IP or CIDR (e.g., 10.0.0.1, 192.168.0.0/24)
--dst-ip	any	Destination IP or CIDR
--src-port	any	Source port or range (e.g., 8080, 8080-8090)
--dst-port	any	Destination port or range
--action	accept	accept, drop, reject, log, masquerade, or compound (log,drop)
--interface	any	Network interface (e.g., eth0, ens3)
--duration	permanent	permanent or temporary
--ttl	0	Seconds for temporary rules (60-2592000, i.e., 1min to 30days)
--description	empty	Human-readable description (max 256 chars)
--conn-state	none	Conntrack: new,established,related,invalid
--log-prefix	none	Syslog prefix (max 29 chars)
--log-level	none	Syslog: emerg, alert, crit, err, warning, notice, info, debug
--limit	none	Rate limit: N/second, N/minute, N/hour, N/day
--limit-burst	none	Max burst before rate limit kicks in
--zone	public	Firewalld zone name
--chain	auto	iptables/nftables chain (auto: inbound→INPUT, outbound→OUTPUT)
--table	filter	iptables table: filter, nat, mangle, raw, security

Import File Format

Key-value blocks separated by blank lines:

direction=inbound
protocol=tcp
dst_port=443
action=accept
description=HTTPS traffic

direction=inbound
protocol=tcp
dst_port=22
src_ip=10.0.0.0/24
action=accept
description=SSH admin only

If a SHA-256 sidecar file exists (rules.conf.sha256), the checksum is verified before importing.

Interactive Menu Structure

Ctrl+C inside the menu aborts the operation in progress and returns to the menu; the Install & Update submenu recovers in place. Ctrl+C never terminates the application from within the menu. In headless CLI use, Ctrl+C performs cleanup and exits with status 130. Package install and update operations announce themselves with a status line, run fully non-interactively (no prompts can block them), and are bounded by the long-operation timeout.

Main Menu
├── 1. Firewall Management
│   ├── 1. Select backend
│   ├── 2. Show service status (running/enabled/version)
│   ├── 3. Enable/start service
│   ├── 4. Disable/stop service
│   ├── 5. List system rules (<backend>)
│   ├── 6. Reset firewall to defaults
│   └── 7. Back
├── 2. Rule Management
│   ├── 1. Create new rule (wizard with duration/TTL prompts)
│   ├── 2. List Apotropaios rules
│   ├── 3. List system rules -- <backend>
│   ├── 4. Remove rule (by UUID)
│   ├── 5. Activate rule
│   ├── 6. Deactivate rule
│   ├── 7. Import rules (with dry-run option)
│   ├── 8. Export rules
│   └── 9. Back
├── 3. Quick Actions
│   ├── 1. Block ALL traffic (with confirmation + backend name)
│   ├── 2. Allow ALL traffic (with confirmation)
│   ├── 3. Reset firewall (with confirmation + backend name)
│   └── 4. Back
├── 4. Backup & Recovery
├── 5. System Information (full OS + FW detection display)
├── 6. Install & Update
├── 7. Help & Documentation (8-option submenu with all command help)
└── 8. Exit

Cancel any prompt: q, quit, cancel, back, b

Key Differences: status vs system-rules vs list-rules

Command	Shows	Scope
status	Service state (running/enabled/version/binary)	Active backend + all backends summary
system-rules	Native firewall rules dump	ALL rules in the backend (not just ours)
list-rules	Apotropaios-tracked rules table	Only rules created through this framework