Network Observation

Hosting network observation

Purpose #

Describe how Hosting network telemetry is attached, what operators can see, and why drops are a defect rather than a tuning knob.

Audience #

Operators who will start zwall-hosting-ebpf-loader.service and interpret Hosting Network Security UI / status counters.

Edition #

ENTERPRISE_ONLY. Virtualization XDP/TC firewall programs are a different object family (firewall.o / firewall_egress.o) and must not be loaded on a shared hosting node as a substitute.

Status #

SUPPORTED as pass-only observation. Isolated attach evidence in the Hosting matrix used Ubuntu 20.04 kernel 5.4.0-216-generic. That is an isolated test, not a certified OS/kernel matrix.

Prerequisites #

• hosting.network.enabled: true
• hosting.network.socket_path: "/run/zwall-hosting-ebpf/observer.sock" (example)
• Loader env ZWALL_HOSTING_EBPF_SHA256 and ZWALL_HOSTING_INTERFACES
• Agent user zwall-hosting can connect to the socket; it does not need CAP_NET_ADMIN or CAP_NET_RAW

Required permissions #

Root to run the loader. The Agent must remain unprivileged. A Hosting network preflight that observes CAP_NET_ADMIN or CAP_NET_RAW on the Agent prints INCOMPATIBLE.

Dependencies #

Kernel XDP/TC attach on the listed physical interfaces. Loader CapabilityBoundingSet=CAP_CHOWN CAP_SYS_ADMIN CAP_NET_ADMIN. The Agent reads category-safe pages from the UNIX socket only.

Configuration #

Loader ExecStart (unit):

/opt/zwall-hosting/bin/zwall-hosting-ebpf-loader \
  --object /opt/zwall-hosting/ebpf/hosting_observe.o \
  --sha256 ${ZWALL_HOSTING_EBPF_SHA256} \
  --interfaces ${ZWALL_HOSTING_INTERFACES} \
  --run-user zwall-hosting \
  --run-group zwall-hostingCopy

ExecStop is --detach (exact loader-owned programs only).

Agent hosting.network example:

Do not point ebpf.program_path at firewall.o on this profile. Hosting example leaves program paths empty and enable_uid_gid_filtering: false.

Procedure #

1. Write /etc/zwall-hosting/hosting-ebpf.env with the object digest and comma-separated physical interfaces. Do not list customer TAP/veth names as a substitute for the Virtualization inventory API.
2. systemctl enable --now zwall-hosting-ebpf-loader
3. Confirm the socket: /run/zwall-hosting-ebpf/observer.sock
4. Start the Hosting Agent unit after the loader.
5. Optional read-only preflight from the Agent binary:

zwall-agent --hosting-network-preflight-url https://manager.example.com:8443 \
  --hosting-network-preflight-id PREFLIGHT1Copy

Prints COMPATIBLE or INCOMPATIBLE with a reason (INCOMPATIBLE_INTERFACE_DISCOVERY, INCOMPATIBLE_NETWORK_CAPABILITIES, INCOMPATIBLE_MANAGER_REACHABILITY). The probe GETs /api/v1/health?hosting_preflight=ID and asserts the Agent has no CAP_NET_ADMIN / CAP_NET_RAW.

What operators see #

Bounded packet metadata and counters, not payload. Detector version hosting-network-detectors.v1. Conservative classes (logged only; action must be logged):

Hosting network events must not carry unrestricted packet fields (source_ip, destination_ip, MACs, raw ports, rule_id, …) on the security-log request. Prefix identifiers in details are category-safe. Do not expect customer IPs in Hosting event APIs.

Drops are prohibited. Observation programs pass (XDP pass / TC OK). If pass-only programs drop traffic, treat it as a product defect. Do not “fix” it by loading Virtualization firewall objects on that node.

Verification #

• systemctl is-active zwall-hosting-ebpf-loader
• Socket present and owned for zwall-hosting
• Hosting status runtime_available: true and network attach lists populated for the interfaces you passed
• UI / status: observation counters; drops remain zero
• Packet path still forwards

Expected result #

Category-safe network signals in the Hosting Agent story. Enforcement, if required for the estate, belongs on Virtualization Agents — not on this node.

Failure modes #

Troubleshooting #

1. journalctl -u zwall-hosting-ebpf-loader -u zwall-hosting-agent-v2 -n 200
2. ls -l /run/zwall-hosting-ebpf/observer.sock
3. Hosting status network fields: XDPAttachedInterfaces, TCAttachedInterfaces, EligibleInterfaces, ScanEventCounts
4. Confirm observation_only on heartbeat / profile — not an enforcement Agent

Security considerations #

• Loader is root with a reduced capability set, then the Agent receives none.
• --detach on stop removes loader-owned programs only.
• Do not document UID/GID cgroup filtering as a Hosting network control. It is not.
• Do not publish PPS or latency numbers.

Limitations #

• Not a firewall.
• Not payload capture.
• Not a certified kernel matrix.
• Closed-port emits only when inferable.
• Hosting sources remain ineligible for automatic/provider AI.

Related documentation #

• Purpose
• Validation
• Hosting telemetry interpretation
• Observation vs enforcement
• Virtualization XDP/TC