Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Concepts › Observation vs Enforcement

Observation vs Enforcement

SharedStatus: SUPPORTEDAudience: every technical operator

Purpose

State the product split that every other Zwall document depends on: Hosting observation passes traffic and exports bounded telemetry; Virtualization firewall programs can pass or drop. Mixing those jobs on a shared hosting node is an operational error.

Concept

Zwall is one platform with two Agent jobs.

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

JobKernel programsPacket dropTypical node
Hosting Agenthosting_observe.o via privileged loaderProhibited (XDP pass / TC OK)shared / panel host
Virtualization Agentfirewall.o (XDP) + firewall_egress.o (TC)Intended capabilityKVM/libvirt host

The shared Agent binary (zwall-agent) implements both profiles. hosting.enabled plus fail-closed flags select observation. Active packet enforcement requires root and the Virtualization objects.

A config leaf agent.protection_model of virtualization, hosting, or hybrid exists. That leaf is not the same thing as the Enterprise Hosting Agent profile identity (hosting-plesk-observe-v2). Example hybrid can mislead (the hybrid example misleads vs Hosting identity).

Data/control flow

  1. Operators create rules, blocks, GeoIP, and detection settings on the Manager.
  2. Agents authenticate and synchronize those objects.
  3. Enforcement Agents program eBPF maps. XDP/TC then pass or drop.
  4. Hosting Agents do not use those programs to drop packets. They tail logs and poll a UNIX socket of category-safe network metadata. Assigning rules or restart commands to them returns HTTP 409.
  5. Telemetry (security logs, Hosting events, heartbeats, VM inventory) flows Agent → Manager. Policy flows Manager → assigned Virtualization Agents.

Testing / non-enforcing mode (zwallctl test-flush*, /api/v1/maintenance/testing-mode) lets operators inspect before they enforce. It is not a benchmark and not a Hosting feature.

Boundaries

  • Hosting hosting.enforcement must be false; audit_only and log_only must be true when enabled.
  • Hosting Agent: empty capabilities, user zwall-hosting. Loader: root, pass-only object, socket /run/zwall-hosting-ebpf/observer.sock.
  • Virtualization Agent: root, CAP_NET_ADMIN among others, unit zwall-agent.service.
  • UID/GID cgroup filtering is not Hosting, and is not a stable Virtualization customer contract.
  • AI Preview drafts cannot become live rules through AI routes.
  • Do not claim lossless event delivery.

Edition differences

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

TopicCommunityEnterprise
Virtualization enforcement Agentyes (source)yes (unit /opt/zcs/bin/zwall-agent)
Hosting observation profile + loadernoyes
Hosting status/events APIsnoyes
3-Agent capyeslicense-defined, not this concept

Common misconceptions

  • “Hosting Agent is a silent firewall.” No. If it drops, that is a defect.
  • “Turn on hybrid to get both jobs on a panel host.” No. Hosting validation requires protection_model: hosting and rejects enforcement-capable features.
  • “Assign rules to every Agent.” Hosting returns 409.
  • “zwallctl start/stop enforces remotely.” Not implemented; use systemd.
  • “UID/GID filtering is how Hosting isolates customers.” It is not.