Configuration

Virtualization Agent configuration

Purpose #

Configure an enforcement-capable Agent on a KVM/libvirt host so it can register with the Manager, attach XDP/TC firewall programs, and synchronize rules.

Audience #

Operators of hypervisor nodes. This is not the Hosting observation profile.

Edition #

SHARED runtime. Enterprise unit paths: /opt/zcs/bin/zwall-agent --config /etc/zcs/agent.yml. Community: built bin/agent and typically /etc/zcs/agent.yml. Path prefixes are not unified with Hosting or Manager.

Status #

SUPPORTED for keys in configs/agent.example.yml with the qualifiers in this file. UID/GID filtering is implemented with an incomplete ABI. Edge mode is not a public certified product. protection_model: hybrid is an example that can mislead.

Prerequisites #

• Root on the hypervisor (non-Hosting Agent fatals if geteuid != 0)
• Manager URL with server.verify_tls: true
• eBPF objects firewall.o and firewall_egress.o
• KVM/libvirt if you need VM inventory

Required permissions #

Root to run zwall-agent.service. Admin on the Manager to pre-register and assign rules.

Dependencies #

Linux eBPF/XDP/TC. Example ebpf.min_kernel_version: "5.8.0" with strict_kernel_version_check: true. Community README also mentions 4.15+ / 5.4+. This package does not certify a single matrix.

Configuration #

File (Enterprise unit): /etc/zcs/agent.yml
Example: configs/agent.example.yml

Agent flags: -config (default configs/agent.yml), -version, -build-info-json, -verbose, -debug, -log-file, plus Hosting-only preflight flags that you should not use as a Virtualization workflow.

server #

agent #

ebpf #

virtualization #

Other hypervisor strings in comments (proxmox, xen) are future notes, not shipping integrations.

rules / detection #

rules.block_bpdu, mac_spoofing, port_scan, dhcp_guard as in the example. Port-scan control_source_allowlist is a reserved control-path bypass of local tracker mitigation only; explicit blocks still apply.

detection.* feature flags default false; shadow_mode: true. Warning: example detection.profiles is a YAML list while Go tags expect a map — do not document the example list as a guaranteed load.

What to leave off this node #

Do not enable hosting.enabled. Do not point this unit at /etc/zwall-hosting/agent.yml. Do not use Hosting loader units as an enforcement path.

Optional Agent metrics bind 127.0.0.1:9090 when enabled; example Hosting profile forbids Agent metrics entirely. On Virtualization they stay disabled unless you explicitly enable them.

Procedure #

1. Copy configs/agent.example.yml to /etc/zcs/agent.yml.
2. Set server.manager_url, agent.hostname, verify_tls: true.
3. Set agent.protection_model: virtualization unless you have a written exception for the example hybrid value.
4. Keep operating_mode: host.
5. Confirm eBPF object paths and verify_artifact_integrity: true.
6. Enable virtualization.enabled and libvirt.uri: qemu:///system for KVM inventory.
7. If you need a supported policy contract, set enable_uid_gid_filtering: false until a stable customer contract is published.
8. Enroll, then systemctl enable --now zwall-agent.
9. Restart the unit after YAML changes. SIGHUP may apply some live-safe fields and reject others with restart_required — do not treat SIGHUP as a complete live-reload.

Verification #

See Verification.

Expected result #

Root Agent online in the Manager, XDP/TC objects loaded from /opt/zcs/ebpf/, libvirt inventory when enabled, rules assignable (unlike Hosting).

Failure modes #

Troubleshooting #

Troubleshooting.

Security considerations #

• Keep verify_tls: true and allow_unsigned_artifacts: false.
• Bootstrap token in environment, persist locally, do not leave JWTs in YAML.
• allow_insecure_remote_tls is break-glass only.

Limitations #

• kernel matrix unresolved.
• UID/GID not a customer contract.
• hybrid example may mislead.
• edge mode not certified.
• detection profiles list vs map.

Related documentation #

• Install
• Agent configuration reference
• Enforcement
• XDP/TC