Documentation Portal • v0.13.0

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

Super-Slim Edge NGFW (Single-File UEFI UKI)

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.

Custom Hardened Kernels & Hardware Studio

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.

Eluvix Sovereign AI Router & DLP Guard

Switchyard 4-tier local/frontier model routing, PrivacyGuard reversible PII & secret tokenization before cloud egress, PromptGuard injection filter, and 8 autonomous agent harnesses.

High Availability & 2-Host Setup Guide

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.

Ghost-in-the-Ring & 5-Hook BPF-LSM Guard

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.

Axonwall Blackbox: eBPF Threat-LLM Harvester

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.

Post-Quantum Rosenpass Dual-KEM VPN

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.

Neovim Super Configurator & ZSH Shell

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.

Vigilant Octo Waffle (VOW) DevSecOps

Turnkey K3s DevSecOps & GitOps stack (Argo CD / Flux, Gitea, Tekton, Vault, DefectDojo, Wazuh, Cilium, Tetragon) with zero-touch OpenLDAP RBAC provisioning.

Vigilante Autonomous SOC & SOAR

Unified Cyber Operations platform (core-vigilante): BattleStation live triage, Attack Graph correlation, Cyber Deception honeynets, Purple Team adversary emulation, and SOAR playbooks.

KVM/QEMU Hypervisor, LXC & VFIO

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.

Modular Core Roles (5 Core Roles + 18 Plugins)

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.

MCP Security AI Server & Tactical Leases

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.

Unified Identity, OpenLDAP & Enterprise SSO

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.

ZFS NAS Storage & Axonwall Vault

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.

Kubernetes (K3s) & OpenEBS

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.

Multi-Disk RAID, Btrfs & ZFSBootMenu Install

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.

Architecture & nftables

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.

Threat Feeds & DNS RPZ

Dynamic IP blocklist sets with CIDR interval minimization, and Unbound RPZ sinkhole compiler with subdomain pruning.

Migration Studio (9 Vendor Importers)

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.

eBPF & Kubernetes Observability

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.

Hardware Sensors, Optical DOM & Web Shell

Linux hwmon thermal/voltage telemetry, SFP+/QSFP28 Optical DOM dBm transceiver diagnostics, RBAC Console Command Runner, KVM noVNC consoles, and physical TUI shell.

GitOps Revisions & Etckeeper /etc Audit

Immutable Git-backed YAML revision history (/var/lib/axonwall/gitops), side-by-side structural diffs, instant rollback, and Etckeeper host /etc configuration versioning.

REST, Agent Socket & Terraform Reference

Programmatic OpenAPI / REST endpoints, SSE streams, Fleet & MCP APIs, privileged Unix socket IPC, and official Terraform / OpenTofu provider.

Theme Engine & Custom Repositories

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:

Flash ISO to USB Drive & Verify SHA-256
bash
# 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
Four Editions & Four Partitioning Modes: A/B Dual-Root, ZFSBootMenu (ZBM), Btrfs + Snapper, or Rolling Single-Root
During installation (or via --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_a and axon_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-disk zstd or 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 standard apt rolling 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:

Proxmox VE Cloud-Init QCOW2 Import
bash
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):

Install Debian Package
bash
# 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

compose.yaml
yaml
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-stopped

Quickstart & 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:

Default Web Console:

https://192.168.1.1:2966

Default Credentials:

Username: admin | Password: axonwall

Neovim Super Configurator:

axonwall-config

Commit-Confirm Safety (60–120s Auto-Revert)
Whenever you modify interface assignments, IP addresses, or firewall rules in the console or CLI, Axonwall initiates a 60–120 second Commit-Confirm timer (the Web Console defaults to 60–120s, while 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 TierThroughput TargetProcessorMemoryNIC Architecture
Edge / SatelliteUp to 1 GbpsQuad-Core ARM64 or Intel N100 / J41252 GB - 4 GBRealtek 8125B / Intel i225-V
SMB / Branch Office2.5 Gbps - 10 GbpsIntel Core i3/i5 12th+ Gen or AMD Ryzen 58 GB - 16 GBIntel i226-V (2.5G) / Intel X520 (10G SFP+)
Enterprise Core / Datacenter10 Gbps - 100 Gbps line-rateIntel Xeon Gold / AMD EPYC (8 - 32 cores)32 GB - 128 GB ECCIntel E810 / Mellanox ConnectX-5/6 (eBPF/XDP)