System Architecture & Engine
Axonwall replaces the 20-year-old FreeBSD pf model with the modern Linux 6.12 LTS networking stack, pure nftables + Ring-0 eBPF XDP packet processing, 12 declarative YAML domain manifests, unbrickable A/B Dual-Root & ZFSBootMenu updates, and Junos-style transactional commit-confirm.
Linux nftables vs FreeBSD pf
Traditional open-source firewalls are constrained by the legacy FreeBSD pf packet filter. Under symmetrical 10G/25G/100G loads and high connection churn, BSD pf suffers from severe global mutex lock contention.
Legacy FreeBSD pf
- Single-Threaded State Table: Multi-core CPUs bottle-neck on global state table insertion locks.
- Driver & Hardware Lag: Wi-Fi 7, modern 5G modems, and multi-queue 25G/100G NICs (Intel E810, Mellanox) often lack FreeBSD drivers.
- Container Incompatibility: Cannot coexist natively inside Linux network namespaces, Kubernetes CNI, or Docker.
- Monolithic PHP Re-renders: Entire rulesets are recompiled and rewritten via PHP scripts during any rule toggle.
Axonwall Modern Linux (nftables + eBPF)
- Lockless Multi-Core RSS: Linux Netfilter distributes connection tracking (conntrack) and packet evaluation across all CPU cores.
- Day-One Hardware Acceleration: Full in-tree Linux kernel driver support for all 2.5G/10G/25G/100G NICs and optical transceivers.
- Zero-Conflict Table Isolation: Operates entirely inside
table inet axonwallwithout disturbing Docker or Kubernetes CNI. - Atomic Incremental Rulesets: Atomic transactions prevent packet drops and micro-blackouts during policy updates.
Isolated nftables Table & Full Enterprise NAT/NGFW Parity
Axonwall encapsulates all routing, NAT, and filtering policies within table inet axonwall without disturbing co-located K3s or LXC workloads—compiling stateful filter rules (inbound/outbound/both directionality, source/destination negation, floating multi-interface rules, DSCP marking, per-rule PPS rate limits, and Multi-WAN fwmark gateway groups), a complete NAT engine (DNAT + Hairpin NAT Reflection, SNAT, Masquerade, 1:1 Bi-Directional BINAT, and Stateless IPv6 NPTv6 prefix translation), Kea DHCPv4/DHCPv6 IA_NA/IA_PD + radvd SLAAC, OpenVPN ovpn-dco kernel TLS offload, Avahi mDNS reflection, and miniupnpd UPnP/NAT-PMP:
table inet axonwall {
# Dynamic interval sets for high-speed IP blocklists
set threat_feed_ips {
type ipv4_addr
flags interval
auto-merge
}
chain prerouting {
type filter hook prerouting priority -150; policy accept;
# Early line-rate drop for known malicious threat intelligence feeds
ip saddr @threat_feed_ips counter drop
}
chain input {
type filter hook input priority 0; policy drop;
ct state established,related accept
iif "lo" accept
tcp dport 2966 accept # Web Console
tcp dport 22 accept # SSH Administration
}
chain forward {
type filter hook forward priority 0; policy drop;
ct state established,related accept
# Dynamic egress policies compiled from Axonwall JSON intent
iifname "lan0" oifname "wan0" accept
}
chain postrouting {
type nat hook postrouting priority 100; policy accept;
oifname "wan0" masquerade
}
}12-Domain Declarative YAML Configuration
Axonwall decomposes its entire appliance state into 12 canonical YAML domain files inside /etc/axonwall/, merged deterministically with optional lexical drop-in overrides in /etc/axonwall/conf.d/*.yaml and compiled into a validated runtime snapshot at /etc/axonwall/state.json. On A/B Dual-Root appliances, /etc/axonwall/ is bidirectionally synchronized to persistent storage at /mnt/axonwall-data/etc-axonwall/ so configurations survive slot switches seamlessly.
| # | Canonical File | Top-Level DesiredState Keys |
|---|---|---|
| 1 | /etc/axonwall/system.yaml | version, capabilities, system, plugins, ai, eluvix, observability, snmp, ups, acme |
| 2 | /etc/axonwall/interfaces.yaml | interfaces, vlans, bridges, bonds, virtualIps, vrfs |
| 3 | /etc/axonwall/firewall.yaml | aliases, rules, nat, trafficShaper |
| 4 | /etc/axonwall/routing.yaml | gateways, gatewayGroups, routes, frr |
| 5 | /etc/axonwall/services.yaml | dhcp, dns, captivePortal, haproxy, freeradius |
| 6 | /etc/axonwall/vpn.yaml | wireguard, rosenpass, ipsec, openvpn, headscale |
| 7 | /etc/axonwall/security.yaml | suricata, crowdsec, geoip, zeroTrust, sso, tlsDecryption, hostDefense |
| 8 | /etc/axonwall/ha.yaml | ha, fleet |
| 9 | /etc/axonwall/storage.yaml | nas |
| 10 | /etc/axonwall/k3s.yaml | k3s, vow |
| 11 | /etc/axonwall/virt.yaml | virt, hostedEdge |
| 12 | /etc/axonwall/vigilante.yaml | vigilante |
Junos-Style Commit-Confirm State Machine
The single most catastrophic risk in network administration is applying a firewall or routing change that inadvertently cuts off your own management session. Axonwall eliminates administrative lockouts by incorporating a strict Junos-style transactional commit-confirm state machine.
1. [INTENT] User, TUI, or API generates proposed DesiredState bundle from /etc/axonwall/*.yaml.
2. [LINT] Privileged agent executes pre-flight syntax validation: nft -c -f /tmp/proposed.nft
3. [APPLY & ARM] Rules applied atomically to kernel; watchdog timer armed (default: 60–120s; axonwallctl apply defaults to 120s).
4. [QUORUM CHECK] Browser client or axonwallctl confirm sends explicit confirmation.
5. [COMMIT OR REVERT] If confirmed, bundle is persisted & committed to GitOps; if session drops, daemon reverts to last-known-good.nft automatically.
Three Boot & Update Architectures: A/B Dual-Root, ZFSBootMenu & Rolling
Axonwall supports three installation and firmware lifecycle architectures selectable in axonwall-console --install:
Two identical ext4 partitions (axon_root_a and axon_root_b, optionally mirrored via mdadm RAID-1) with background OTA staging (axonwallctl update) and GRUB bootcount fallback.
Boots directly from zroot/ROOT/* OpenZFS Boot Environments across Stripe, Mirror, RAID-Z, or dRAID topologies with zero-copy snapshot clones (axonwallctl zbm) and pre-boot watchdog revert.
Traditional single-partition Debian/Ubuntu Linux layout (axonwallctl update --apt) for operators managing standard VM templates or package-driven fleets.
+-----------------------------------------------------------------------------------------+ | Partition 1: EFI System Partition (ESP) | /boot/efi | FAT32 | 512 MB | +-----------------------------------------------------------------------------------------+ | Partition 2: rootfsA (Active / Standby) | / | ext4 | 8-32 GB [axon_root_a]| +-----------------------------------------------------------------------------------------+ | Partition 3: rootfsB (Active / Standby) | /mnt/standby | ext4 | 8-32 GB [axon_root_b]| +-----------------------------------------------------------------------------------------+ | Partition 4: Swap (Optional) | [SWAP] | swap | 0-8 GB | +-----------------------------------------------------------------------------------------+ | Partition 5: Persistent Data & Logs | /var/lib/axonwall| ext4 | Rest of Disk [axon_data]| +-----------------------------------------------------------------------------------------+
During ISO installation, the administrator chooses the rootfs size per slot:
- Compact (8 GB per slot): 16 GB total system allocation; ideal for eMMC, embedded CFast, and small 32 GB disks.
- Standard (16 GB per slot): 32 GB total system allocation; default for modern SSDs with room for IDS rules and updates.
- Expanded (32 GB per slot): 64 GB total system allocation; designed for enterprise appliances with container engines.
- Custom: User-defined size in gigabytes (minimum 6 GB).
Three-Step Autonomous Health Quorum
Upon booting an upgraded rootfs slot or ZFS Boot Environment, the privileged daemon axonwalld validates three critical subsystem health checks before committing the boot slot:
- Network Carrier Status: Loopback (
lo) and physical link carrier states. - nftables Subsystem: Kernel netfilter tables and rule compilation health.
- Control Plane IPC Quorum: Local Unix socket responsiveness (
/run/axonwall/agent.sockand/run/axonwall/agent-api.sock).
If any check fails or the system experiences a kernel panic during boot, GRUB or ZFSBootMenu increments bootcount. After 3 failed attempts, the bootloader automatically falls back to the previous healthy slot or Boot Environment.
Privileged Go Daemon (axonwalld), IPC Security & Ring-0 eBPF
Security best practices dictate that web applications should never run as root. The Next.js Web Console and Node.js controller run with restricted unprivileged credentials (axonwall-api group) and communicate with axonwalld exclusively over isolated Unix domain sockets:
/run/axonwall/agent-api.sock (mode 0660 root:axonwall-api, authenticated via 32-byte /etc/axonwall/agent.token in X-Axonwall-Agent-Token)/run/axonwall/agent.sock (high-throughput local control-plane RPC & CLI bridge)/run/axonwall/ha.sock (mode 0600 root:root, isolated for Keepalived/VRRP state transitions)In addition to atomic nftables compilation, HWMON sensor polling, optical DOM reads, OpenZFS /proc/spl/kstat/zfs ARC/L2ARC/ZIL telemetry, and Etckeeper GitOps commits, axonwalld attaches native Dual-Stack IPv4/IPv6 + 802.1Q/802.1ad QinQ VLAN XDP programs (BPF_MAP_TYPE_LRU_HASH flow tables, BPF_MAP_TYPE_LPM_TRIE CIDR subnet + exact-host monotonic TTL XDP_DROP blocklists, and per-source Ring-0 TCP SYN-flood PPS rate limiting before sk_buff allocation), alongside 5 CO-RE BPF-LSM kernel hooks (lsm/socket_bind, lsm/bpf, lsm/uring_sqpoll, lsm/bpf_token_create, lsm/bpf_token_cmd) guarding AF_ALG, BPF_PROG_LOAD, io_uring SQPOLL, and Linux 6.9+ unprivileged BPF_TOKEN_CREATE UserNS delegation.