Core Role: core-virt • Type-1 KVM/QEMU & LXC Engine

Axonwall Hypervisor: KVM/QEMU VMs, LXC & Hosted Edge UKI

Enabling the core-virt Core Role transforms any Axonwall appliance into a converged Type-1 KVM/QEMU and LXC virtualization platform backed directly by OpenZFS storage and stateful nftables microsegmentation. Every VM, system container, PCIe passthrough binding, VXLAN overlay fabric, Hosted Edge NGFW micro-VM, and backup schedule is declared in /etc/axonwall/virt.yaml and reconciled atomically by axonwalld.

1. Type-1 KVM/QEMU Virtual Machines

The VirtManager engine (engine/virt.go) compiles each VirtualMachineSchema entry (vmid 100–99999) into deterministic QEMU hardware topologies without heavy middleware daemons, persisting runtime specs at /var/lib/axonwall/virt-specs.json and guarding concurrent lifecycle transitions with Proxmox-style asynchronous UPID task tracking (/var/log/axonwall/tasks).

OVMF UEFI, Secure Boot & TPM 2.0

Choose bios: "ovmf" (UEFI with persistent NVRAM efivars) or legacy seabios, enable secureBoot: true, and attach an emulated swtpm TPM 2.0 socket (tpm2: true) for Windows 11, BitLocker, and measured-boot Linux guests alongside host or x86-64-v2-AES CPU passthrough and virtio memory ballooning.

OpenZFS ZVOL Backing Disks & QoS

Each virtual disk (VmDiskSchema) auto-provisions a raw OpenZFS ZVOL on the target pool (virtio, scsi, nvme, sata, or ide) with native TRIM/UNMAP (discard: true), cache mode control, and per-disk read/write IOPS throttling (iopsReadLimit / iopsWriteLimit).

Multi-Mode NICs, Guest Agent & Cloud-Init

Attach virtio, vmxnet3, or e1000e NICs via Linux bridges (with 802.1Q vlanTag, per-VNIC firewall, and rateLimitMbps), macvtap-passthru, or direct vfio. Per-VM cloudInit injects SSH keys, static/DHCP networking, and custom user-data while QEMU Guest Agent (agent: true) provides clean fsfreeze snapshots and live IP discovery.

HTML5 noVNC & Serial WebSocket Console

Zero external TCP VNC ports are ever opened on the host. Instead, QEMU binds local Unix domain sockets under /run/axonwall/vnc/vm-<vmid>.sock and /run/axonwall/serial/vm-<vmid>.sock, and ConsoleProxy (engine/novnc.go) streams authenticated RFC 6455 WebSocket frames over /v1/virt/console/ws with strict same-origin verification.

Enterprise Proxmox & Libvirt Parity: VirtioFS, Clones, Live Migration & XML

Axonwall matches and surpasses dedicated Type-1 hypervisors by integrating zero-copy OpenZFS primitives, vhost-user shared memory filesystems, canonical Libvirt XML compilation, and per-VNIC stateful Netfilter microsegmentation:

VirtioFS Host ZFS Shares

Declare virtioFsShares[] (tag, hostPath, cacheMode) to mount host OpenZFS datasets directly inside Linux & Windows VMs via virtiofsd vhost-user shared memory—bypassing SMB/NFS network overhead completely.

CPU Pinning, NUMA & Hugepages

Pin vCPU threads to physical cores (cpuAffinity), expose guest NUMA topologies (numaEnabled: true), and back guest RAM with 2M or 1G Hugepages for deterministic latency.

Zero-Copy ZFS Linked Clones

Clone any VM template in milliseconds via zfs snapshot + zfs clone (axonwallctl virt clone), consuming zero additional ZFS blocks until copy-on-write divergence.

QMP + ZFS Live Migration

Migrate running VMs across clustered Axonwall nodes (axonwallctl virt migrate) combining incremental ZFS ZVOL streaming with QEMU QMP RAM dirty-page convergence.

Per-VM nftables Security Groups

Attach reusable vmSecurityGroups[] directly to each VM NIC (tap<vmid>i<idx>), enforcing East-West zero-trust microsegmentation even between VMs on the same L2 bridge.

Libvirt Domain XML Compiler

Export or inspect canonical <domain type='kvm'> Libvirt XML (axonwallctl virt xml <vmid> / axonwall://virt/libvirt-domains) for full virsh ecosystem compatibility.

2. Lightweight LXC System Containers

For near-zero overhead Linux system services that share the hardened Axonwall kernel while retaining full systemd / OpenRC init userlands, LxcContainerSchema provisions isolated containers (ctid 100–99999) directly onto native OpenZFS filesystem datasets:

Schema FieldDefaultIsolation & Storage Behavior
unprivilegedtrueMaps container UID 0 into an unprivileged high UID/GID range via Linux user namespaces, neutralizing root-escape vectors.
rootfsPool / rootfsSizeGb"tank" / 8 GiBCreates a dedicated ZFS dataset with refquota enforcement, instant copy-on-write snapshots, and lz4/zstd compression.
mountPoints[][]Declarative host-to-container bind mounts (hostPath → mountPath) with optional readOnly: true enforcement for shared ZFS NAS datasets.
features[]["nesting"]Fine-grained capability toggles (nesting, keyctl, fuse) for running nested Podman/Docker engines or FUSE filesystems safely inside LXC.

3. PCIe VFIO Passthrough, SR-IOV & VXLAN SDN

Hardware accelerators (GPUs/NPUs for local AI inference, NVMe controllers, and 10G/25G/100G NICs) and multi-node Layer-2 tenant networks are first-class citizens in virt.yaml:

IOMMU & vfio-pci Binding

engine/vfio.go enumerates /sys/kernel/iommu_groups, verifies clean IOMMU group isolation for each PCI bdf (0000:xx:xx.x), and dynamically unbinds host drivers to bind vfio-pci.

SR-IOV Virtual Functions

Setting sriovNumVfs on Intel X710/E810 or Mellanox ConnectX physical functions programs sriov_numvfs in sysfs so VMs receive line-rate hardware Virtual Functions with near-zero CPU interrupt overhead.

VXLAN EVPN/SDN Overlay

VxlanZoneSchema stretches isolated Layer-2 segments across HA or branch Axonwall nodes using 24-bit VNIs (1–16777215) over UDP 4789 (unicast peers or multicast) with automatic 1450 MTU clamping.

4. Hosted Virtual Edge NGFW UKI (hostedEdge)

For maximum perimeter isolation on a single physical box, /etc/axonwall/virt.yaml includes the hostedEdge stanza (HostedEdgeConfigSchema). When enabled, the host places its physical WAN interface into wan-delegated mode (an isolated br-wan bridge, macvtap-passthru, or direct vfio PCI passthrough with zero host IPv4/IPv6 addresses) and boots the Super-Slim Edge NGFW UEFI UKI (axonwall-satellite as pure-Go PID 1 with CONFIG_MODULES=n and zero shells) inside a diskless RAM-only front-door micro-VM.

Dual A/B UKI Slots & Delegated-WAN Blast Containment
Untrusted internet frames terminate inside the stateless 256 MiB micro-VM before ever reaching the host Linux network stack. Upgrades toggle cleanly between ukiSlot: "A" and ukiSlot: "B" with hardware i6300esb watchdog auto-reset and optional Active-Standby Edge HA over transit VLANs 4000/4001.

5. Deduplicated Backups & Appliance Cloud-Init Export

Axonwall pairs scheduled workload disaster recovery (WorkloadBackupJobSchema) with full-appliance #cloud-config Golden Image cloning:

ZFS, S3 & Proxmox Backup Server (PBS)

Schedule cron jobs targeting all or selected VMIDs/CTIDs with QEMU Guest Agent fsfreeze, zstd compression, optional client-side encryption, and Grandfather-Father-Son (GFS) retention (keepLast, keepDaily, keepWeekly, keepMonthly) to local-zfs, S3-compatible object storage (s3), or Proxmox Backup Server (pbs).

Full-Appliance Cloud-Init Import & Export

axonwallctl cloudinit export serializes the running appliance's entire DesiredState (including VMs, containers, ZFS topology, and OS users) into a portable #cloud-config seed or bootable ISO9660 NoCloud cidata.iso—redacting passwords, WireGuard keys, and tokens by default (--redact) or stripping MAC/disk serials via --template.

/etc/axonwall/virt.yaml
yaml
virt:
  enabled: true
  defaultPool: "tank"
  isoPool: "tank"

  pciDevices:
    - bdf: "0000:03:00.0"
      iommuGroup: 14
      driver: "vfio-pci"
      sriovNumVfs: 4
      description: "Intel E810-XXVDA2 25GbE SR-IOV PF0"

  vxlanZones:
    - name: "vx-dmz-east"
      vni: 10400
      peers: ["10.255.0.2"]
      underlayInterface: "lan"
      port: 4789
      bridge: "br-vx400"
      mtu: 1450
      enabled: true

  vms:
    - vmid: 101
      name: "win11-secops-wks"
      osType: "windows"
      bios: "ovmf"
      secureBoot: true
      tpm2: true
      sockets: 1
      cores: 8
      cpuType: "host"
      memoryMb: 16384
      balloonMinMb: 8192
      watchdog: "i6300esb"
      agent: true
      autostart: true
      haManaged: true
      disks:
        - name: "disk0"
          pool: "tank"
          sizeGb: 128
          bus: "nvme"
          cache: "none"
          discard: true
          iopsReadLimit: 50000
          iopsWriteLimit: 25000
          backup: true
      nics:
        - bridge: "br-vx400"
          model: "virtio"
          vlanTag: 40
          firewall: true
          queues: 4
      cloudInit:
        user: "secadmin"
        ipConfig: "10.40.0.25/24"
        gateway: "10.40.0.1"
        nameservers: ["10.40.0.1"]
        sshAuthorizedKeys:
          - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleSecOpsAdminKey secops@axonwall"

  containers:
    - ctid: 201
      hostname: "netbox-ipam"
      template: "debian-12-standard"
      unprivileged: true
      cores: 2
      memoryMb: 2048
      swapMb: 512
      rootfsPool: "tank"
      rootfsSizeGb: 16
      features: ["nesting", "keyctl"]
      mountPoints:
        - hostPath: "/mnt/tank/backups/netbox"
          mountPath: "/var/backups/netbox"
          readOnly: false
      nics:
        - bridge: "br0"
          model: "virtio"
          firewall: true
      bpfToken:
        enabled: true
        preset: "networking-safe"
      autostart: true

  backupJobs:
    - name: "nightly-vault-s3"
      scheduleCron: "0 1 * * *"
      targetType: "all"
      storagePool: "tank"
      destinationType: "s3"
      s3Endpoint: "https://s3.axonwall.lan:9000"
      s3Bucket: "axonwall-vm-backups"
      compression: "zstd"
      retention:
        keepLast: 5
        keepDaily: 7
        keepWeekly: 4
        keepMonthly: 12
      enabled: true

hostedEdge:
  enabled: true
  placement: "hosted"
  ukiSlot: "A"
  skuProfile: "sku-vm-virtio"
  vcpus: 2
  memoryMiB: 256
  wan:
    hostDevice: "eth0"
    bridgeName: "br-wan"
    attachMode: "bridge"
    ipv4Mode: "dhcp"
    ipv6Mode: "auto"
    ipv6RequestPrefix: 56
  lan:
    bridgeName: "br-lan"
    edgeAddress: "10.0.0.1/24"
    hostAddress: "10.0.0.2/24"
    ipv6Mode: "delegated"
CLI, Cloud-Init Seed ISO Generation & Operator TUI Commands
bash
# Validate, diff, and apply /etc/axonwall/virt.yaml changes
axonwallctl validate
axonwallctl diff
axonwallctl apply

# Export the running appliance (with secrets redacted & hardware-agnostic template mode)
# to both #cloud-config YAML and a bootable NoCloud cidata.iso seed image
axonwallctl cloudinit export --template -o seed.yaml --iso cidata.iso

# Reconcile an inbound #cloud-config user-data seed into /etc/axonwall/conf.d/99-cloudinit.yaml
axonwallctl cloudinit /etc/axonwall/cloud-config.yaml

# Open the interactive TUI directly on Tab [7] (Compute & SOC) or edit virt.yaml in Neovim
axonwall-tui
axonwall-config virt
Manage via Web Console, Neovim TUI, or SSH Operator Console
Inspect live VM/LXC CPU & memory telemetry, launch HTML5 noVNC consoles, configure SR-IOV/VFIO bindings, and trigger on-demand ZFS/PBS backups from the Web Console under /compute/vms and /compute/containers, or from Tab [7] Compute & SOC in axonwall-tui.

Unprivileged LXC `BPF_TOKEN` Delegation (`CLONE_NEWUSER`) & MCP Hypervisor Control

When an unprivileged LXC container (unprivileged: true with lxc.idmap = u 0 100000 65536) enables bpfToken.enabled: true in /etc/axonwall/virt.yaml, Axonwall's LXC compiler automatically injects a dedicated Linux 6.9+ delegated bpffs mount and LIBBPF_BPF_TOKEN_PATH=/sys/fs/bpf while rejecting any Ring-0 tracing/kernel-memory program types (kprobe, tracepoint, lsm) both at schema compile time and in Ring-0 via BPF-LSM:

Compiled /var/lib/lxc/201/config Excerpt (networking-safe BPF_TOKEN)
ini
# Linux 6.9+ Unprivileged UserNS BPF_TOKEN Delegation (Ring-0 kprobe/lsm blocked)
lxc.mount.entry = bpffs sys/fs/bpf bpf rw,nosuid,nodev,noexec,relatime,create=dir,delegate_cmds=prog_load:map_create:map_lookup_elem:map_update_elem:map_delete_elem:link_create,delegate_progs=socket_filter:sched_cls:sched_act:xdp:cgroup_skb:sk_skb:sk_msg:sock_ops,delegate_maps=hash:array:percpu_hash:percpu_array:lru_hash:lru_percpu_hash:ringbuf:lpm_trie,delegate_attachs=xdp:cgroup_inet_ingress:cgroup_inet_egress:sk_skb_stream_parser:sk_skb_stream_verdict 0 0
lxc.environment = LIBBPF_BPF_TOKEN_PATH=/sys/fs/bpf

All KVM/LXC hypervisor telemetry (axonwall://virt/workloads, mcp_inspect_virt_workloads), lifecycle operations (mcp_control_virt_workload), and declarative LXC token bindings (mcp_configure_lxc_bpf_token) are exposed via the Axonwall MCP server under mcp:virt:read and mcp:virt:manage.