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

Verification

Virtualization Agent verification

Purpose

Prove the Virtualization Agent is online, attached, and able to receive policy before you enforce on a live path.

Audience

Deployment engineers signing off a KVM host.

Edition

SHARED. GET /api/v1/dashboard/ebpf-health is Enterprise in the v1 router.

Status

SUPPORTED as an operator checklist. Not a performance proof.

Prerequisites

  • zwall-agent.service installed from the admitted release (or Community bin/agent)
  • Manager ready
  • Admin credentials
  • libvirt workloads if you want a non-empty VM list

Required permissions

Root on the hypervisor. Admin on the Manager. Hosting 409s are expected if you point these checks at a Hosting Agent — use this checklist only on zwall-agent.service.

Procedure

  1. Unit and identity
systemctl is-active zwall-agent
systemctl show zwall-agent -p User -p ExecStart -p CapabilityBoundingSet

Expect User=root, ExecStart=/opt/zcs/bin/zwall-agent --config /etc/zcs/agent.yml on Enterprise, capabilities including CAP_NET_ADMIN CAP_NET_RAW CAP_SYS_ADMIN.

  1. Manager inventory
zwallctl login --manager-url https://manager.example.com:8443 --username admin
zwallctl list-agents
zwallctl status --agent ID

GET /api/v1/agents lists the Agent online. Community: a fourth Agent is rejected.

  1. Virtualization inventory

GET /api/v1/virtualization/vms
GET /api/v1/virtualization/interfaces

Non-empty on a libvirt host that has workloads. Empty on a host with no domains is not a failure.

  1. eBPF health

GET /api/v1/dashboard/ebpf-health (Enterprise admin). Confirm firewall programs, not Hosting observe.

  1. Testing mode before first drop
zwallctl test-flush-status
zwallctl test-flush

Inspect. A test rule in testing mode does not drop. An explicit block on this enforcement node does, after you disable testing mode when intended.

  1. Policy path

Assign a rule to this Agent id. Confirm sync (zwallctl list-rules). If you receive 409 cannot receive rules, the target is Hosting — stop.

  1. Process control

Use systemd to start/stop/restart. Do not expect zwallctl start / stop to work remotely.

Verification table

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

CheckPass
Unit active as rootactive
Agent in GET /api/v1/agentsonline
VMs/interfaceslist or empty-with-reason
eBPF health (Enterprise)firewall programs attached
Testing mode understoodstatus matches intent
Hosting units not used as drop engine on a panel hostN/A here; do not mix

Expected result

Enforcement-capable Agent registered, programs attached, inventory visible, policy assignable. First drop only after testing mode is deliberately disabled.

Failure modes

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

ResultMeaning
Unit inactivejournal; kernel preflight; config
Agent offlineenrollment/TLS/heartbeat (agents.timeout example 2m)
eBPF health emptyattach/integrity; wrong profile
409 on rulesHosting Agent id
VM list empty on busy hypervisorlibvirt URI / virtualization.enabled

Troubleshooting

Troubleshooting.

Security considerations

Do not disable TLS verification or artifact integrity to pass the checklist.

Limitations

Does not certify kernel matrix, UID/GID, edge mode, or HA Manager failover.