XDP and TC

XDP and TC on the Virtualization Agent

Purpose #

Document how the Virtualization Agent attaches firewall.o (XDP ingress) and firewall_egress.o (TC egress), which attach modes exist, and which related programs are not a customer contract.

Audience #

Operators who will interpret attach failures and ebpf-health.

Edition #

SHARED. Hosting uses a different object (hosting_observe.o) loaded by a separate privileged process. Do not mix them.

Status #

SUPPORTED for xdp_attach_mode values in configs/agent.example.yml. UID/GID cgroup programs are implemented with incomplete ABI/lifecycle. Do not document them as production-complete. Isolated Hosting 5.4 tests are irrelevant to certifying this firewall profile.

Prerequisites #

• Root Agent with CapabilityBoundingSet=CAP_DAC_READ_SEARCH CAP_IPC_LOCK CAP_NET_ADMIN CAP_NET_RAW CAP_SYS_ADMIN CAP_SYS_RESOURCE
• ReadWritePaths including /sys/fs/bpf
• Objects at /opt/zcs/ebpf/firewall.o and /opt/zcs/ebpf/firewall_egress.o
• ebpf.verify_artifact_integrity: true and checksum manifest /opt/zcs/ebpf/ebpf_checksums.txt

Required permissions #

Root. Non-Hosting Agents refuse to start without it.

Dependencies #

Kernel XDP/TC. Example min_kernel_version: "5.8.0" and strict_kernel_version_check: true. Community README 4.15+ / 5.4+ is a different statement. OWNER must publish one matrix. This document does not pick a certified minimum.

Configuration #

XDP can sit earlier than netfilter. Coexistence with a conventional host firewall is not a certified matrix.

UID/GID: example sets enable_uid_gid_filtering: true and cgroup_program_path: /opt/zcs/ebpf/uid_gid_filter_v3.o. That path authorizes covered TCP/UDP socket operations by real UID / primary real GID. It is not packet filtering. All five V3 hooks must be healthy for that path — and the ABI is incomplete. Do not enable this as a supported customer feature. Set enable_uid_gid_filtering: false until a stable customer contract is published.

Do not attach Hosting hosting_observe.o with this unit.

Procedure #

1. Confirm objects and ebpf_checksums.txt match the admitted release.
2. Leave allow_unsigned_artifacts: false.
3. Start with xdp_attach_mode: auto.
4. If native attach fails on a given NIC, a controlled fallback to generic is the documented next mode. offload requires hardware that actually offloads; it is not a default recovery.
5. Inspect GET /api/v1/dashboard/ebpf-health (Enterprise) and journalctl -u zwall-agent.
6. Use testing mode before first drop (Enforcement).

zwallctl map ls uses --pin-dir (default /sys/fs/bpf/fw). Do not document folklore firewall list / map dump — those are not cobra commands.

Verification #

• Agent unit active as root
• GET /api/v1/dashboard/ebpf-health reports programs attached (Enterprise)
• Maps pinned when enable_pinned_maps is true
• Hosting observation drops-zero check does not apply; this profile may drop when policy says so
• dmesg / journal has no repeating attach errors

Expected result #

Ingress XDP and egress TC loaded from the Virtualization objects. Policy maps update from Manager sync. Restarts reuse pinned maps when enabled.

Failure modes #

Troubleshooting #

Troubleshooting, eBPF troubleshooting.

Security considerations #

• Artifact integrity stays on.
• Pin dir is runtime state; treat it like policy.
• Do not publish PPS or latency numbers.

Limitations #

• No certified nftables coexistence matrix.
• No certified kernel/OS matrix.
• UID/GID not a customer contract.
• SMTP mark/NAT companion (smtp_dnat / smtp_proxy) is a specialized path, disabled in the example, not this document’s default.

Related documentation #

• Configuration
• Enforcement
• Verification