Core Subsystems • v0.13.0

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 axonwall without 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:

/etc/nftables/axonwall.nft
nftables
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 FileTop-Level DesiredState Keys
1/etc/axonwall/system.yamlversion, capabilities, system, plugins, ai, eluvix, observability, snmp, ups, acme
2/etc/axonwall/interfaces.yamlinterfaces, vlans, bridges, bonds, virtualIps, vrfs
3/etc/axonwall/firewall.yamlaliases, rules, nat, trafficShaper
4/etc/axonwall/routing.yamlgateways, gatewayGroups, routes, frr
5/etc/axonwall/services.yamldhcp, dns, captivePortal, haproxy, freeradius
6/etc/axonwall/vpn.yamlwireguard, rosenpass, ipsec, openvpn, headscale
7/etc/axonwall/security.yamlsuricata, crowdsec, geoip, zeroTrust, sso, tlsDecryption, hostDefense
8/etc/axonwall/ha.yamlha, fleet
9/etc/axonwall/storage.yamlnas
10/etc/axonwall/k3s.yamlk3s, vow
11/etc/axonwall/virt.yamlvirt, hostedEdge
12/etc/axonwall/vigilante.yamlvigilante

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.

COMMIT-CONFIRM LIFECYCLE:

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.

Fail-Safe Verification
Even if an administrator makes a mistake that drops all WAN/LAN connections, simply waiting 60–120 seconds guarantees that the firewall will cleanly roll back to the previously functioning ruleset without needing physical console access.

Three Boot & Update Architectures: A/B Dual-Root, ZFSBootMenu & Rolling

Axonwall supports three installation and firmware lifecycle architectures selectable in axonwall-console --install:

1. A/B Dual-Root Slots (Default)

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.

2. ZFSBootMenu Root-on-ZFS

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.

3. Rolling Single-Root

Traditional single-partition Debian/Ubuntu Linux layout (axonwallctl update --apt) for operators managing standard VM templates or package-driven fleets.

A/B Dual-Root Disk Partition Scheme
text
+-----------------------------------------------------------------------------------------+
| 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]|
+-----------------------------------------------------------------------------------------+
Installer Partition Sizing Profiles

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:

  1. Network Carrier Status: Loopback (lo) and physical link carrier states.
  2. nftables Subsystem: Kernel netfilter tables and rule compilation health.
  3. Control Plane IPC Quorum: Local Unix socket responsiveness (/run/axonwall/agent.sock and /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:

HTTP/SSE REST Socket: /run/axonwall/agent-api.sock (mode 0660 root:axonwall-api, authenticated via 32-byte /etc/axonwall/agent.token in X-Axonwall-Agent-Token)
Internal gRPC Socket: /run/axonwall/agent.sock (high-throughput local control-plane RPC & CLI bridge)
Root-Only HA Control Socket: /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.