Developer, IaC & Automation • v0.13.0

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:

HTTP Header
http
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:

MethodEndpointDescription
GET/api/v1/openapi.jsonMachine-readable OpenAPI 3.1 specification for SDK generation and API clients.
GET/api/v1/statusAppliance health, version (0.13.0), active boot slot/BE/snapshot, and Commit-Confirm timer state.
GET / PUT/api/v1/stateRead or stage the merged DesiredState across all 12 /etc/axonwall/*.yaml domains.
POST/api/v1/applyValidate (nft -c), apply DesiredState bundle, and arm Commit-Confirm watchdog (60–120s).
POST/api/v1/confirmConfirm active Commit-Confirm transaction, disarm timer, and persist GitOps revision.
POST/api/v1/rollbackImmediately revert to last-known-good state or a specified GitOps revision SHA.
POST/api/v1/importParse & 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/overviewUnified 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/blockInspect 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/tokensList, 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/kernelCustom 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/updateRelease 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/streamQuery 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).
GET

/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 ParamTypeDescription
ifacestringFilter by interface name (e.g., wan0, lan0).
protostringFilter by protocol: tcp, udp, icmp.
portnumberFilter 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:

Agent HTTP API Socket (/run/axonwall/agent-api.sock)
bash
# 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 .
IPC Sockets & Endpoints Summary
typescript
// 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):

main.tf — Declarative DesiredState & Zero-Touch Cloud-Init Generation
hcl
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")
}