Virtualization Agent Install

Virtualization Agent installation

Purpose #

Install an enforcement-capable Agent on a KVM/libvirt host. This unit may drop traffic. Do not install it as a drop engine on a shared hosting node; use the Hosting Agent there.

Audience #

Hypervisor operators.

Edition #

SHARED runtime. Enterprise systemd zwall-agent.service. Community: scripts/setup.sh Agent Only, or bin/agent -config ….

Status #

SUPPORTED. Kernel minimum is not a single certified number. UID/GID filtering is not a customer contract. Edge mode is not a public certified product.

Prerequisites #

• Manager ready and reachable
• Root on the KVM host
• eBPF objects firewall.o and firewall_egress.o plus checksum manifest
• libvirt if you need VM inventory
• Pre-register/create completed (Enrollment)

Required permissions #

Root to run the unit. Admin to enroll and assign rules.

Dependencies #

XDP/TC. Example YAML ebpf.min_kernel_version: "5.8.0" with strict_kernel_version_check: true. Community README also mentions Linux 4.15+ (5.4+ recommended). This page does not pick one as certified.

Configuration #

Unit zwall-agent.service:

Copy configs/agent.example.yml and set:

• server.manager_url (example https://manager.example.com:8443)
• server.verify_tls: true
• agent.hostname
• agent.protection_model: virtualization unless you have a written exception — the example hybrid can mislead (the hybrid example is for a different profile)
• agent.operating_mode: host (not edge)
• agent.vm_bridge_name if you use the VM bridge discovery path (example viifbr0 is not mandatory)
• ebpf.program_path / tc_program_path
• ebpf.verify_artifact_integrity: true
• ebpf.enable_uid_gid_filtering: false until a stable customer contract is published (example enables it — do not treat as supported)
• virtualization.enabled: true, platform: kvm, libvirt.uri: qemu:///system for inventory

Do not enable allow_unsigned_artifacts except break-glass. Do not enable hosting.enabled on this unit.

Procedure #

1. Install Agent binary and eBPF objects (firewall.o, firewall_egress.o) from the admitted release (Enterprise) or go build + ebpf/make (Community).
2. Write /etc/zcs/agent.yml (Enterprise example path) or the Community path you actually use. Do not copy the stale /etc/zwall/agent.yml string if you see it in messages.
3. Enroll (Agent enrollment) — AGENT_TOKEN once, YAML token empty.
4. systemctl enable --now zwall-agent
5. Confirm the Agent is root: non-hosting Agent fatals otherwise.

Community Agent-only path: scripts/setup.sh Agent Only mode, or run the built bin/agent -config ....

zwallctl start / stop print not implemented. Use systemd.

Verification #

See Virtualization verification.

• Agent appears in GET /api/v1/agents / console
• GET /api/v1/virtualization/vms and /interfaces return inventory after libvirt discovery
• XDP/TC attach: GET /api/v1/dashboard/ebpf-health (Enterprise admin)
• A test rule in testing mode does not drop; an explicit block on this node does after testing mode is disabled when intended
• Assigning the same rule to a Hosting Agent returns 409 — that is correct

Expected result #

Root Virtualization Agent online, programs attached, policy assignable. Packet drops only from this profile’s maps, not from Hosting observe.

Failure modes #

Troubleshooting #

Virtualization troubleshooting, eBPF, Enforcement.

Security considerations #

Keep TLS verify and artifact integrity on. Do not mix this unit onto a customer-shared hosting node.

Limitations #

Unresolved: kernel matrix, UID/GID contract, hybrid example, edge mode, remote start/stop, stale path string.

Related documentation #

• Enforcement
• XDP/TC
• KVM/libvirt
• Configuration
• Hosting install (do not mix)