Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Integrations › libvirt

libvirt

libvirt / KVM integration

Status: SUPPORTED for inventory and interface mapping on Virtualization AgentsAudience: virtualization operator

What it does

The Virtualization Agent connects to libvirt (qemu:///system by default), discovers VMs and TAP/bridge interfaces, and reports them to the Manager (POST /api/v1/virtualization/vm-data on heartbeat/discovery). Operators list VMs via /api/v1/virtualization/vms.

Edition

SHARED. Hosting Agents keep virtualization.enabled: false.

Prerequisites

  • KVM/libvirt on the Agent host
  • Agent unit capabilities including CAP_NET_ADMIN / CAP_SYS_ADMIN as shipped
  • virtualization.enabled: true
  • Manager admin JWT to read inventory

Required permissions / credentials

  • Permission to open virtualization.libvirt.uri (typically UNIX /var/run/libvirt/libvirt-sock)
  • Root Agent (virt unit User=root)
  • No Zwall-specific libvirt password in YAML (URI may include one — treat as secret)

Configuration

Agent YAML virtualization.*: enabled, platform (kvm), libvirt.uri, libvirt.read_only, discovery.interval / cache_ttl, events.enabled, events.auto_apply_rules. Also agent.vm_bridge_name, agent.interfaces.

See Virtualization Behavior.

Setup

  1. Confirm virsh list --all works as root on the host.
  2. Set virtualization.enabled: true and the bridge name you actually use (example viifbr0 is not mandatory).
  3. Restart zwall-agent.service.
  4. GET /api/v1/virtualization/vms as admin.

Verification

  • Agent heartbeat includes vms when inventory is healthy
  • GET /api/v1/virtualization/interfaces non-empty on a host with TAP devices
  • POST /api/v1/virtualization/discovery refreshes

Expected signals / results

VM start events can trigger rule apply when auto_apply_rules is true on enforcement Agents. Isolation APIs operate on this inventory.

Failure modes

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

SymptomMeaning
503 Virtualization service not initializedManager virt service nil
empty VM listAgent not reporting / libvirt down
404 VM not foundstale id

Troubleshooting

  • systemctl status libvirtd
  • Socket permissions
  • Wrong vm_bridge_name
  • Hosting profile will not attach XDP drop programs

Security considerations

libvirt access is host-root equivalent. Read-only URI reduces accidental VM control but inventory still exposes MAC/IP. Do not publish VM names as public telemetry.

Limitations

  • KVM/libvirt is the documented path; proxmox/xen strings are not certified products
  • Not a VMware/Hyper-V integration
  • No published VM scale