Axonwall Documentation
Welcome to the official Axonwall documentation. Axonwall is an enterprise-grade open-source router, Next-Generation Firewall (NGFW), Zero-Surface Edge UKI, OpenZFS NAS, Sovereign AI Gateway, and K3s SecOps platform engineered on modern Linux, nftables, Post-Quantum Dual-KEM cryptography, and Ring-0 eBPF telemetry.
Explore Core Subsystems & Setup Guides
Zero-surface perimeter UKI running axonwall-satellite as pure-Go PID 1 with CONFIG_MODULES=n, zero shell/userland, sub-1.2s RAM boot, pure-Go Cloud-Init, Dual-Stack IPv6, and Active-Standby Edge HA.
Universal Linux 6.12 LTS KSPP + k3s + OpenZFS + nftables + eBPF kernels, live host hardware inventory, 25-check kernel posture audit (/boot/config-* & /proc/config.gz), hardware-locked localmodconfig stripped builds, and ZFSBootMenu / A-B safe staging.
Switchyard 4-tier local/frontier model routing, PrivacyGuard reversible PII & secret tokenization before cloud egress, PromptGuard injection filter, and 8 autonomous agent harnesses.
Step-by-step 2-host walkthrough: Keepalived VRRP, conntrackd FTFW sync, mTLS HA PKI enrollment, Chrony NTP peering, OpenLDAP syncrepl, SQLite WAL streaming, and ZFS Send/Recv.
8-engine malware suite (rkhunter, chkrootkit, ClamAV, AIDE, YARA, Lynis, unhide, debsums) paired with 5-hook CO-RE BPF-LSM Ring-0 containment, Linux 6.9+ BPF_TOKEN UserNS mediation, /proc/kcore prog_idr diffing, and Silicon PMU LBR.
Opt-in Ring-0 TCX flow sketches, sched_process_exec / memfd_create lineage, guarded TLS uprobes, mandatory pre-disk DLP redaction, Crypto-PAn anonymization, and Dual-Track SFT/RLVR ChatML JSONL + Apache Parquet corpus export.
Hybrid Classic McEliece 460896 + ML-KEM-512 (Kyber-512) key exchange rotating kernel WireGuard Pre-Shared Keys every 120 seconds against Harvest-Now-Decrypt-Later quantum threats.
Hyperfocused Lua form TUI (axonwall-config) with native Vim motions across 12 domains, standalone axonwall-tui NastyMap topology simulator, and Oh My Zsh + Starship workstation.
Turnkey K3s DevSecOps & GitOps stack (Argo CD / Flux, Gitea, Tekton, Vault, DefectDojo, Wazuh, Cilium, Tetragon) with zero-touch OpenLDAP RBAC provisioning.
Unified Cyber Operations platform (core-vigilante): BattleStation live triage, Attack Graph correlation, Cyber Deception honeynets, Purple Team adversary emulation, and SOAR playbooks.
Native core-virt hypervisor orchestrating ZFS zvol-backed QEMU/KVM virtual machines, unprivileged LXC containers with Linux 6.9+ BPF_TOKEN delegation, IOMMU PCIe/GPU VFIO passthrough, vnet/tap telemetry, and HTML5 noVNC consoles.
Compose all 5 Core Roles (core-firewall, core-nas, core-k3s, core-virt, core-vigilante) and 18 sandboxed extension plugins (with SHA-256 bundled binaries and Minimal on-demand installation)—from pure Host-Mode ZFS NAS to hyper-converged bare metal.
Disabled-by-default MCP server (/api/v1/mcp & axonwallctl mcp) exposing 16 capability scopes, 16 resources, and 25 guardrailed tools across Firewall, Ring-0 eBPF & BPF_TOKEN, KVM/LXC, K3s, OpenZFS NAS, and 9-Vendor Migration.
Embedded N-Way Multi-Provider OpenLDAP directory, FreeRADIUS 802.1X WPA-Enterprise, OIDC/SAML2 SSO, FIDO2 WebAuthn passkeys, and zero-trust RBAC across VPN, SMB, VOW, and Eluvix.
OpenZFS Stripe/Mirror/RAID-Z/dRAID pools, SPL kstat ARC/L2ARC/ZIL telemetry, Samba SMB3 with VSS shadow copies, NFSv4/iSCSI, and SeaweedFS S3 Vault with B-14 Internal PKI CA.
WireGuard flannel mesh, 2-node HA auto-join, axonwall-kubeconfig --vip sync, Linux 6.9+ UserNamespacesSupport (hostUsers: false) with BPF_TOKEN profiles, and OpenEBS ZFS-LocalPV & Mayastor NVMe-oF.
Choose between ZFSBootMenu v3.1.x Root-on-ZFS Boot Environments, in-kernel Btrfs + Snapper Root (single-disk or native RAID-1), mdadm RAID-1 A/B Dual-Root slots, or Standard Single-Root rolling Linux mode.
Why Linux multi-core line-rate scaling replaces FreeBSD pf, A/B dual-root unbrickable updates, N-port Multi-WAN/Multi-LAN fabric, and Junos-style commit-confirm.
Dynamic IP blocklist sets with CIDR interval minimization, and Unbound RPZ sinkhole compiler with subdomain pruning.
Consolidate pfSense, OPNsense, Proxmox VE 8.x, TrueNAS SCALE, Cisco ASA/FTD, VyOS, MikroTik RouterOS, iptables, and firewalld with rule shadowing audits and non-destructive merge.
Zero-instrumentation Ring-0 telemetry: Dual-Stack IPv4/IPv6 + QinQ VLAN XDP fast-drop, Linux 6.9+ BPF_TOKEN_CREATE delegation, Coroot eBPF APM, OpenZFS ARC/ZIL kstats, and live NFLOG/SSE packet streams.
Linux hwmon thermal/voltage telemetry, SFP+/QSFP28 Optical DOM dBm transceiver diagnostics, RBAC Console Command Runner, KVM noVNC consoles, and physical TUI shell.
Immutable Git-backed YAML revision history (/var/lib/axonwall/gitops), side-by-side structural diffs, instant rollback, and Etckeeper host /etc configuration versioning.
Programmatic OpenAPI / REST endpoints, SSE streams, Fleet & MCP APIs, privileged Unix socket IPC, and official Terraform / OpenTofu provider.
Customize Web Console palettes, import Winnegans-compatible theme manifests and Git repositories, and style ZFSBootMenu pre-boot UEFI splash and ANSI palettes.
Installation & Deployment
Axonwall can be installed as bare-metal appliance firmware via bootable UEFI/BIOS ISO (available in both Debian 13 Trixie and lightweight Alpine Linux flavors—with all four appliance editions unified directly inside axonwall-debian13-amd64.iso and selectable from the bootloader menu or installer TUI as axonwall (Converged NGFW), minimal (Reduced Attack Surface), vault (Immutable S3 Backup), or k3s-storage (Barebones K3s + OpenZFS/OpenEBS Storage Host)), deployed inside virtualization platforms (Proxmox VE, KVM, ESXi), or installed on existing Debian/Ubuntu systems via .deb.
Option 1: Bare Metal UEFI Appliance (Recommended)
Flash the Axonwall ISO to a USB flash drive using BalenaEtcher, Rufus (DD mode), or the Linux dd utility:
# Download and verify the unified v0.13.0 Debian 13 (NGFW, Minimal, Vault & K3s-Storage) ISO wget https://github.com/axonwall/axonwall/releases/download/v0.13.0/axonwall-debian13-amd64.iso wget https://github.com/axonwall/axonwall/releases/download/v0.13.0/axonwall-debian13-amd64.iso.sha256 sha256sum -c axonwall-debian13-amd64.iso.sha256 # Replace /dev/sdX with your destination USB drive sudo dd if=axonwall-debian13-amd64.iso of=/dev/sdX bs=4M status=progress conv=fsync
--unattended / cloud-init preseed / GRUB & ISOLINUX boot menu), select the axonwall Converged NGFW edition, the minimal Reduced Attack Surface edition, the vault Immutable S3 Backup edition, or the k3s-storage Barebones K3s + OpenZFS/OpenEBS Storage Host edition, and choose between four partitioning layouts:- A/B Dual-Root Appliance Mode (Default): Allocates two identical root slots (
axon_root_aandaxon_root_b—8 GB, 16 GB, 32 GB, or custom) with hardware watchdog fallback and dedicated persistent data (/var/lib/axonwall). - ZFSBootMenu Root-on-ZFS Mode (
zbm): Boots directly from an OpenZFS root pool (zroot/ROOT/*) across Stripe, Mirror, RAID-Z, or dRAID topologies with zero-copy snapshot Boot Environments and pre-boot watchdog auto-revert. - Btrfs + Snapper Root Mode (
btrfs): In-kernel Copy-on-Write alternative to ZBM with flat subvolumes (@,@snapshots,@var_log,@var_lib_axonwall), single-diskzstdor native Btrfs RAID-1, pre/post Snapper pairs, and bootable GRUB2 snapshot rollback. - Standard Linux Single-Root Rolling Mode (
rolling): Traditional single root filesystem for operators who prefer standardaptrolling upgrades on large single disks.
Option 2: Proxmox VE / KVM Cloud QCOW2 Image & Edge UKI
Import the pre-built Cloud-Init QCOW2 image (axonwall-debian13-amd64-cloud.qcow2) or boot the stateless axonwall-edge-sku-vm-virtio.efi Unified Kernel Image directly into RAM:
wget https://github.com/axonwall/axonwall/releases/download/v0.13.0/axonwall-debian13-amd64-cloud.qcow2 qm create 9000 --name axonwall-ngfw --memory 4096 --cores 4 --net0 virtio,bridge=vmbr0 --net1 virtio,bridge=vmbr1 qm importdisk 9000 axonwall-debian13-amd64-cloud.qcow2 local-zfs qm set 9000 --scsihw virtio-scsi-single --scsi0 local-zfs:vm-9000-disk-0,discard=on --ide2 local-zfs:cloudinit --boot c --bootdisk scsi0
Option 3: Debian / Ubuntu Packages (.deb)
For existing Debian 12 (Bookworm) / 13 (Trixie) or Ubuntu 24.04 LTS servers, install Axonwall directly using the official standalone package (edition packages axonwall-minimal, axonwall-vault, and axonwall-k3s-storage are also published per release):
# Download the latest .deb release artifact from GitHub Releases wget https://github.com/axonwall/axonwall/releases/download/v0.13.0/axonwall_0.13.0_amd64.deb wget https://github.com/axonwall/axonwall/releases/download/v0.13.0/axonwall_0.13.0_amd64.deb.sha256 sha256sum -c axonwall_0.13.0_amd64.deb.sha256 # Install package with dependencies sudo apt-get update sudo apt-get install -y ./axonwall_0.13.0_amd64.deb # Verify running services sudo systemctl status axonwalld axonwall-ui axonwall-controller
Option 4: Docker Compose Testing Container
services:
axonwall:
image: ghcr.io/axonwall/axonwall:v0.13.0
cap_add:
- NET_ADMIN
- NET_RAW
network_mode: host
volumes:
- /etc/axonwall:/etc/axonwall
- /run/axonwall:/run/axonwall
restart: unless-stoppedQuickstart & First Boot
Upon initial startup, Axonwall configures the primary Ethernet adapter as LAN with DHCP server enabled and starts the TLS-multiplexed Web Console on port 2966:
https://192.168.1.1:2966
Username: admin | Password: axonwall
axonwall-config
axonwallctl apply arms a 120-second confirmation window by default unless --no-confirm is explicitly passed). If your changes interrupt connectivity, the system automatically rolls back to the previous verified configuration bundle without locking you out.Hardware Compatibility & Sizing
| Deployment Tier | Throughput Target | Processor | Memory | NIC Architecture |
|---|---|---|---|---|
| Edge / Satellite | Up to 1 Gbps | Quad-Core ARM64 or Intel N100 / J4125 | 2 GB - 4 GB | Realtek 8125B / Intel i225-V |
| SMB / Branch Office | 2.5 Gbps - 10 Gbps | Intel Core i3/i5 12th+ Gen or AMD Ryzen 5 | 8 GB - 16 GB | Intel i226-V (2.5G) / Intel X520 (10G SFP+) |
| Enterprise Core / Datacenter | 10 Gbps - 100 Gbps line-rate | Intel Xeon Gold / AMD EPYC (8 - 32 cores) | 32 GB - 128 GB ECC | Intel E810 / Mellanox ConnectX-5/6 (eBPF/XDP) |