REST, Fleet/MCP, Agent Socket & Terraform Reference
Automate Axonwall through standardized OpenAPI REST endpoints, real-time Server-Sent Events (SSE) telemetry streams, Fleet & Model Context Protocol (MCP) APIs, privileged Unix domain sockets, and the official Terraform / OpenTofu provider.
Authentication
All HTTPS API requests to port 2966 must supply an RBAC-scoped API token generated in System > Access > API Keys via the HTTP Authorization header:
Authorization: Bearer axw_live_9f82c3e4a1b74d6e9012f
1. Console REST & OpenAPI Endpoints
The Next.js Console exposes a versioned OpenAPI 3.1 specification at /api/v1/openapi.json alongside transactional DesiredState and Commit-Confirm endpoints:
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/openapi.json | Machine-readable OpenAPI 3.1 specification for SDK generation and API clients. |
| GET | /api/v1/status | Appliance health, version (0.13.0), active boot slot/BE/snapshot, and Commit-Confirm timer state. |
| GET / PUT | /api/v1/state | Read or stage the merged DesiredState across all 12 /etc/axonwall/*.yaml domains. |
| POST | /api/v1/apply | Validate (nft -c), apply DesiredState bundle, and arm Commit-Confirm watchdog (60–120s). |
| POST | /api/v1/confirm | Confirm active Commit-Confirm transaction, disarm timer, and persist GitOps revision. |
| POST | /api/v1/rollback | Immediately revert to last-known-good state or a specified GitOps revision SHA. |
| POST | /api/v1/import | Parse & analyze legacy configs (vendor: pfsense, opnsense, proxmox, truenas, cisco-asa, vyos, mikrotik, iptables, firewalld). |
| GET / POST | /api/v1/vpn/mesh/* | Manage sovereign Headscale/Tailscale mesh nodes, pre-auth keys, routes, and Rosenpass PQ peers. |
| GET | /api/v1/ebpf/overview | Unified Ring-0 eBPF status: Dual-Stack IPv4/IPv6 + VLAN XDP flow/drop counters, 5-hook CO-RE BPF-LSM state, Linux 6.9+ BPF_TOKEN mounts, cross-duty ARC/ZIL & KVM telemetry, and live kernel BPF program/map inventory (bpfInventory). |
| GET / POST / DELETE | /api/v1/ebpf/xdp/block | Inspect or mutate monotonic TTL-bounded IPv4/IPv6 XDP_DROP entries (blocklist_map / blocklist6_map) with RFC 1918 / anti-lockout guards. |
| GET / POST / DELETE | /api/v1/ebpf/tokens | List, mount, render K3s hostUsers: false YAML manifests, or unmount isolated Linux 6.9+ /run/axonwall/bpffs-tokens/<profile> superblocks. |
| GET / POST | /api/v1/system/etckeeper/* | Inspect /etc Git status, initialize Etckeeper, update .gitignore / autoCommitOnApply, commit snapshots, and fetch unified commit diffs. |
| GET / POST | /api/system/kernel | Custom Kernel Studio: detect host hardware & active modules, audit kernel posture (25 checks including /proc/config.gz fallback), synthesize hardened Kconfig fragments, launch async builds, and safely stage/install built .deb kernels via ZBM, Btrfs + Snapper, or GRUB. |
| GET / POST | /api/system/update | Release check, OTA updates (update / activate / verify), ZFSBootMenu (zbm-*), and Btrfs + Snapper (btrfs-snapshot, btrfs-delete-snapshot, btrfs-rollback-snapshot, btrfs-sync-grub). |
| GET / POST | /api/k3s & /api/k3s/logs/stream | Query K3s runtime & etcd snapshots, trigger cluster HA join or etcd save/restore, and stream live pod/container SSE logs for Browser K9s Live Explorer. |
| GET / POST | /api/v1/security/threat-harvester/* | Axonwall Blackbox Threat-LLM Harvester: inspect TCX/tracepoint/uprobe telemetry (status), filter/review/Teacher-LLM-annotate/simulate episodes (episodes), stream Crypto-PAn anonymized Dual-Track .tar.zst bundles (export), and upload via AWS SigV4 (ship). |
/api/v1/events/packets
Establishes a persistent Server-Sent Events (SSE) stream delivering real-time parsed packet events directly from the Linux kernel Netfilter / NFLOG & XDP tap.
| Query Param | Type | Description |
|---|---|---|
| iface | string | Filter by interface name (e.g., wan0, lan0). |
| proto | string | Filter by protocol: tcp, udp, icmp. |
| port | number | Filter by source or destination port (e.g. 443). |
2. Controller Fleet Satellite & MCP Security AI APIs
Remote Edge UKI satellites and AI SecOps agents integrate via dedicated fleet enrollment and Model Context Protocol (MCP) endpoints:
/api/v1/fleet/enroll & /api/v1/fleet/heartbeat
Zero-Touch Provisioning (ZTP) CSR enrollment and periodic mTLS telemetry/policy heartbeat endpoints for distributed axonwall-satellite Edge UKI appliances declared under fleet.nodes in /etc/axonwall/ha.yaml.
/api/v1/mcp & /api/v1/mcp/sse
Streamable HTTP JSON-RPC 2.0 and SSE Model Context Protocol endpoints exposing 16 granular capability scopes, 16 read-only resources, and 25 guardrailed tools across Firewall, Ring-0 eBPF & BPF_TOKEN_CREATE, KVM/LXC Virtualization, K3s Kubernetes, OpenZFS NAS, and 9-Vendor Migration. See /docs/mcp-ai-control.
3. Privileged Agent Socket IPC (axonwalld)
Internal controllers and CLI tools communicate with axonwalld over three specialized Unix domain sockets in /run/axonwall/, authenticated with the 32-byte local token at /etc/axonwall/agent.token:
# Query daemon status & Commit-Confirm watchdog timer: sudo curl -s --unix-socket /run/axonwall/agent-api.sock \ -H "X-Axonwall-Agent-Token: $(sudo cat /etc/axonwall/agent.token)" \ http://localhost/v1/status | jq . # Query HA Sync Trust & ECDSA P-256 PKI enrollment state: sudo curl -s --unix-socket /run/axonwall/agent-api.sock \ -H "X-Axonwall-Agent-Token: $(sudo cat /etc/axonwall/agent.token)" \ http://localhost/v1/ha/sync-trust | jq .
// 1. /run/axonwall/agent-api.sock (0660 root:axonwall-api, HTTP/SSE + X-Axonwall-Agent-Token)
// GET /v1/status -> Daemon health, active bundle hash, pending Commit-Confirm job
// POST /v1/apply -> Compile & apply nftables + daemon configs with Commit-Confirm
// POST /v1/confirm -> Confirm pending jobId and disarm rollback timer
// POST /v1/rollback -> Immediately revert to last-known-good bundle
// GET /v1/ebpf/overview -> Dual-Stack VLAN XDP stats, 5-hook BPF-LSM, BPF_TOKEN mounts & kernel BPF inventory (bpfInventory)
// POST /v1/ebpf/xdp/block -> Monotonic TTL XDP_DROP IPv4/IPv6 blocklist (GET/POST/DELETE)
// POST /v1/ebpf/tokens -> Mount/unmount Linux 6.9+ bpffs delegate_* token superblocks
// GET /v1/ebpf/tokens/render-k3s -> Render K3s hostUsers:false Pod/DaemonSet BPF_TOKEN manifest
// GET /v1/nas/telemetry -> OpenZFS /proc/spl/kstat/zfs ARC/L2ARC, ZIL/SLOG & pool ZIO queues
// GET /v1/virt/telemetry -> KVM vnet/tap interface RX/TX/drop stats, IOMMU & LXC BPF_TOKEN state
// GET /v1/k3s/telemetry -> K3s UserNamespacesSupport, CNI/WireGuard interfaces & pod BPF_TOKENs
// POST /v1/k3s/nodes/scheduling -> Merge-patch K3s node roles, labels & edge taints (NoSchedule/NoExecute)
// GET /v1/k3s/{pulse,api-resources,namespaces,resources,resource/inspect,logs/stream} & POST /v1/k3s/action -> Browser K9s Explorer
// POST /v1/terminal/exec -> RBAC-gated Console Command Runner execution
// GET /v1/virt/console/ws -> WebSocket proxy for KVM guest HTML5 noVNC consoles
// GET /v1/system/btrfs -> Btrfs + Snapper list & status; POST list/snapshot/delete-snapshot/rollback-snapshot/sync-grub
// GET /v1/system/plugins & POST /v1/system/plugins/action -> On-demand role/plugin install & SHA-256 bundled binary lifecycle
// GET /v1/system/etckeeper/* -> Host /etc Git status, init, config, commit, history & diff
// GET /v1/system/kernel/studio -> Live hardware inventory, lsmod, running kernel config & build jobs
// POST /v1/system/kernel/build -> Start async Universal or localmodconfig stripped kernel build
// POST /v1/system/kernel/install -> Safe stage/install via ZBM clone, Btrfs pre-snapshot + GRUB sync, or dpkg + update-grub
// GET /v1/security/threat-harvester/status -> Blackbox TCX/tracepoint/uprobe status, redactions & ZFS spool quota
// POST /v1/security/threat-harvester/config -> Apply live ThreatHarvesterConfig updates to Ring-0 collector
// GET /v1/security/threat-harvester/episodes -> Filter captured Causal Threat Episodes by tier & reviewStatus
// POST /v1/security/threat-harvester/episodes/{review,annotate,simulate} -> Curate, Teacher-LLM annotate, or synthesize episodes
// GET /v1/security/threat-harvester/export -> Stream Dual-Track SFT/RLVR JSONL + Apache Parquet .tar.zst bundle
// POST /v1/security/threat-harvester/ship -> Ship Crypto-PAn anonymized bundle to S3 / Vault via AWS SigV4
// GET /v1/ha/sync-trust -> HA PKI enrollment, effective transport (mtls), SHA-256 fingerprints
// GET /v1/system/telemetry/hardware -> HWMON thermal/fan/voltage sensors & SFP+/QSFP optical DOM
// 2. /run/axonwall/agent.sock -> Internal gRPC control-plane socket
// 3. /run/axonwall/ha.sock -> 0600 root:root SO_PEERCRED Keepalived MASTER/BACKUP/FAULT hook 4. Official Terraform & OpenTofu Provider (terraform-provider-axonwall)
Manage fleets of bare-metal, Proxmox/KVM, and Cloud Edge UKI Axonwall appliances declaratively from Infrastructure-as-Code pipelines using the official Go Plugin Framework provider (terraform-provider-axonwall):
terraform {
required_providers {
axonwall = {
source = "axonwall/axonwall"
version = "~> 0.13.0"
}
}
}
provider "axonwall" {
endpoint = "https://10.0.10.1:2966"
api_token = var.axonwall_api_token
insecure_skip_verify = false
}
# Generate a pure-Go Edge UKI / Appliance NoCloud user-data seed
data "axonwall_cloudinit_config" "branch_edge" {
hostname = "edge-fw-denver-01"
hub_url = "wss://10.0.10.1:2966/ws/satellite"
sku = "sku-x86-intel-n100-i226"
}
# Reconcile declarative DesiredState with transactional Commit-Confirm auto-confirmation
resource "axonwall_desired_state" "core_cluster" {
auto_confirm = true
confirm_timeout_sec = 120
firewall_yaml = file("${path.module}/axonwall/firewall.yaml")
interfaces_yaml = file("${path.module}/axonwall/interfaces.yaml")
vpn_yaml = file("${path.module}/axonwall/vpn.yaml")
}