Enforcement

Virtualization enforcement

Purpose #

Explain how packet policy reaches a KVM host: Manager objects → Agent sync → XDP ingress / TC egress maps. This profile may drop. It is not Hosting observation.

Audience #

Operators who will assign rules or blocks to a Virtualization Agent.

Edition #

SHARED. Hosting-specific 409 behavior is Enterprise and is listed here so you do not aim enforcement APIs at the wrong Agent.

Status #

SUPPORTED as the implemented enforcement path. Testing mode is for inspection before first drop, not a benchmark. UID/GID enforcement is not a stable contract.

Prerequisites #

• Virtualization Agent online as root (zwall-agent.service)
• eBPF objects firewall.o and firewall_egress.o with integrity verification on
• Administrator session
• A non-production or explicitly consented path for first-drop tests

Required permissions #

Admin to create/assign rules and blocks. Root on the node to attach programs. Hosting Agents cannot receive rules (HTTP 409).

Dependencies #

Manager policy store (PostgreSQL). Agent sync routes (POST /api/v1/agents/sync and capability-scoped sync, /api/v1/agent-rules/:agent_id, /api/v1/agent-policy/:agent_id, /api/v1/agent-blocked-ips, /api/v1/agent-geoip-rules). Pin directory example /sys/fs/bpf (zwallctl default pin_dir: /sys/fs/bpf/fw).

Configuration #

Programs:

ebpf.xdp_attach_mode: auto|native|generic|offload.

Policy objects originate on the Manager: /api/v1/rules (including assign-to-agent), CIDR, DNS (implemented, not a resolver WAF), blocked IPs, GeoIP rules, detection settings, agent policy upsert. See Policy model.

Procedure — inspect before enforce #

1. Confirm the Agent is Virtualization, not Hosting (protection_model, unit zwall-agent.service, user root).
2. Enable testing / non-enforcing mode:

zwallctl test-flush
zwallctl test-flush-statusCopy

These call POST / GET /api/v1/maintenance/testing-mode. Optional interval argument (10m or seconds) exists on test-flush.

3. Create or assign a rule (zwallctl allow / deny, or console). Confirm the Agent syncs (zwallctl list-rules, Agent status).
4. Only when intended, zwallctl test-flush-disable (DELETE /api/v1/maintenance/testing-mode) so maps enforce.
5. An explicit block on this node does drop. Do not run this first-drop on a Hosting profile — it will not drop and must not be forced to.

zwallctl restart --agent ID calls POST /api/v1/agents/:id/restart. On Hosting that is 409. On Virtualization the handler sends a restart request; the Agent acts on a later cycle. It is not a guaranteed SIGTERM from the Manager.

zwallctl start / stop print that remote start/stop is not implemented. Use systemd.

Verification #

• GET /api/v1/dashboard/ebpf-health (Enterprise admin) shows attach health
• GET /api/v1/virtualization/vms and /interfaces populate on a libvirt host with workloads
• zwallctl status --agent ID (and zwallctl ping)
• Testing mode on: no unintended drop; testing mode off + explicit block: drop on this node

Expected result #

Rules and blocks from the Manager appear in Agent maps. Ingress XDP and egress TC implement that policy. Hosting Agents on other nodes remain observation-only.

Failure modes #

Troubleshooting #

Troubleshooting, Enforcement troubleshooting, eBPF.

Security considerations #

• Testing mode is still a control-plane change; use it deliberately.
• zwallctl flush removes rules — not a health check.
• Do not publish PPS or latency numbers.
• Coexistence with nftables/iptables is not a certified matrix.

Limitations #

• Not a Hosting observation substitute.
• UID/GID socket authorization is not production-complete.
• DNS rules are not a hosted DNS WAF.
• Edge fail-open is not a certified product.
• Event delivery is not exactly-once.

Related documentation #

• Rules
• Blocks
• Testing mode
• CLI rule workflows
• Observation vs enforcement