Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Virtualization Agent › KVM and Libvirt

KVM and Libvirt

KVM/libvirt model

Purpose

Describe how the Virtualization Agent discovers VMs and interfaces on a KVM/libvirt host, and which APIs operators use to inspect that inventory.

Audience

Hypervisor operators who expect VM names and TAP/bridge topology in the Manager.

Edition

SHARED. Agent upload POST /api/v1/virtualization/vm-data uses Agent JWT plus virtualization capability.

Status

SUPPORTED for KVM/libvirt. Kubernetes is planned, not shipping. Other hypervisors are not shipping integrations.

Prerequisites

  • libvirt reachable at the configured URI
  • virtualization.enabled: true on the Agent
  • virtualization.platform: kvm
  • Agent running as root (typical qemu:///system)

Required permissions

Host: membership/access consistent with qemu:///system (the unit runs as root). Manager: admin for inventory GETs.

Dependencies

libvirt. Example URI qemu:///system. qemu:///session and qemu+ssh://… appear as comments in the example; they are not a certified remote-libvirt product.

Configuration

From configs/agent.example.yml:

Scroll sideways to see the full table. Use the arrow keys when focused.

KeyExampleNotes
virtualization.enabledexample falseset true on the KVM host
virtualization.platformkvmcurrent shipping value
virtualization.libvirt.uriqemu:///systemtypical
virtualization.libvirt.read_onlyfalseread-only cannot modify VMs, only discover
virtualization.discovery.interval30s
virtualization.discovery.cache_ttl60s
virtualization.events.enabledtruedomain start/stop
virtualization.events.auto_apply_rulestrueapply firewall rules when a VM starts
agent.vm_bridge_nameviifbr0example bridge for TAP/XDP/TC topology discovery — not a required global name

Traffic collection excludes many virtual NICs by default (lo, veth*, docker*, virbr*, viifbr*, viif*, vnet*, tap*, tun*, …). That filter is for accounting, not a claim that XDP never attaches to VM taps. Do not double-count bridge mirrors.

Procedure

  1. Install libvirt/KVM as you already operate it. Zwall does not replace libvirt.
  2. Set virtualization.enabled: true and libvirt.uri: qemu:///system.
  3. Set agent.vm_bridge_name to your VM bridge if you use that discovery path.
  4. Restart zwall-agent.
  5. Confirm the Agent posts VM data and the Manager lists it.

Admin inventory:

  • GET /api/v1/virtualization/vms
  • GET /api/v1/virtualization/vms/:vm_id
  • GET /api/v1/virtualization/vms/:vm_id/rules
  • GET /api/v1/virtualization/vms/:vm_id/interfaces
  • GET /api/v1/virtualization/interfaces
  • GET /api/v1/virtualization/interfaces/:name
  • GET /api/v1/virtualization/interfaces/:name/stats
  • GET /api/v1/virtualization/summary
  • POST /api/v1/virtualization/discovery (license-gated writes on Enterprise)

Agent: POST /api/v1/virtualization/vm-data.

Do not invent VMware/Hyper-V fields.

Verification

On a libvirt host that has workloads, VM and interface lists are non-empty. An empty list on a host with no domains is expected. Console virtualization pages should match virsh list --all at a coarse level (names/interfaces), not as a second hypervisor.

Expected result

Manager shows KVM domains and interfaces the Agent discovered. Packet policy still comes from Manager rules assigned to the Agent, not from libvirt network XML.

Failure modes

Scroll sideways to see the full table. Use the arrow keys when focused.

SymptomCauseAction
No VMsvirtualization.enabled false; not KVM; wrong URIenable; qemu:///system; confirm libvirt
Wrong topologyvm_bridge_name does not match the hostset the real bridge
Discovery 403/licenseEnterprise license gate on writesinventory GETs may still work
Hosting node emptyHosting profile rejects virtualization featuresuse a Virtualization Agent

Troubleshooting

journalctl -u zwall-agent for libvirt connect errors. virsh -c qemu:///system list --all independently of Zwall.

Security considerations

  • Prefer read-only libvirt if you only need inventory and your process allows it.
  • VM data uploaded to the Manager is operational inventory, not a reason to expose libvirt on the network.

Limitations

  • KVM/libvirt only as a shipping integration.
  • Kubernetes NOT_SUPPORTED.
  • Example viifbr0 is not mandatory.
  • Hardware sizing is not certified.