Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Concepts › Virtualization Agent

Virtualization Agent

Virtualization Agent (concept)

SharedStatus: SUPPORTED with qualifier: current virtualization support is KVM/libvirtAudience: virtualization/KVM operator

Purpose

Define the Agent profile that discovers interfaces and KVM/libvirt VMs and can attach XDP on ingress and TC on egress. Rules and blocks come from the Manager. This is the profile that is allowed to drop traffic.

Concept

Enterprise unit zwall-agent.service:

  • User: root
  • ExecStart=/opt/zcs/bin/zwall-agent --config /etc/zcs/agent.yml
  • CapabilityBoundingSet=CAP_DAC_READ_SEARCH CAP_IPC_LOCK CAP_NET_ADMIN CAP_NET_RAW CAP_SYS_ADMIN CAP_SYS_RESOURCE
  • ReadWritePaths include /sys/fs/bpf

The Virtualization Agent requires root unless Hosting is enabled. Hosting is a different job.

Example Agent settings from configs/agent.example.yml: server.manager_url, verify_tls: true, agent.vm_bridge_name example viifbr0, protection_model example hybrid (do not copy blindly — it does not match the Hosting profile), ebpf.program_path /opt/zcs/ebpf/firewall.o, tc_program_path /opt/zcs/ebpf/firewall_egress.o, xdp_attach_mode: auto, min_kernel_version: "5.8.0".

virtualization.platform: kvm and libvirt.uri: qemu:///system are typical when inventory is enabled.

Data/control flow

Manager rules/blocks/GeoIP/detection → Agent sync → XDP/TC maps.
Agent libvirt discovery → POST /api/v1/virtualization/vm-data → admin GETs under /api/v1/virtualization/*.
Security logs → Manager.
Testing mode on the Manager inspects before enforce.

zwallctl start / stop are not implemented; systemd owns process lifecycle. Restart API requests a later cycle, not a guaranteed SIGTERM.

Boundaries

  • Distinct from Hosting: different unit, user, objects, drop policy.
  • Kubernetes and non-KVM hypervisors are not shipping integrations.
  • UID/GID filtering: implemented, incomplete ABI — not a stable customer contract. Example YAML enables it; operators who need a supported contract should leave it off.
  • operating_mode: edge is not a public certified product.
  • Kernel 5.8.0 in example vs Community README 4.15+/5.4+ is an unresolved kernel-matrix gap — not resolved here.
  • Do not mix this drop-capable unit onto a shared hosting node as a Hosting substitute.

Edition differences

Community builds the same Agent from source (3-Agent cap). Enterprise ships zwall-agent.service and eBPF health dashboard. Hosting rejection of rules is Enterprise Hosting profile behavior.

Common misconceptions

  • “One Agent unit does observation and drop on the panel host.” Use Hosting units there.
  • “hybrid is required.” It is an example value, not a requirement.
  • “zwallctl start brings the firewall up.” Use systemd.
  • “offload mode is the default recovery.” auto then controlled generic.