Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Concepts › Hosting Agent

Hosting Agent

Hosting Agent (concept)

EnterpriseStatus: SUPPORTED with qualifiers (observation-first; not Community)Audience: hosting operator, Manager administrator

Purpose

Define the Hosting Agent as an observation profile for Linux hosting environments, including Plesk-shaped hosts: collect service and panel signals and observe the network without dropping packets.

Concept

Two processes on the hosting node:

  1. Unprivileged Agent — zwall-hosting-agent.service or zwall-hosting-agent-v2.service, user zwall-hosting, binary /opt/zwall-hosting/bin/zwall-agent with --config /etc/zwall-hosting/agent.yml or agent-v2.yml. CapabilityBoundingSet and AmbientCapabilities empty. v1 supplementary groups adm psaserv; v2 adm only (Plesk/site sources stay permission_blocked until operator ACLs). The Agent never joins a customer-content group.
  2. Privileged loader — zwall-hosting-ebpf-loader.service as root, loads hosting_observe.o with --object --sha256 --interfaces --run-user zwall-hosting --run-group zwall-hosting. ExecStop --detach. Capabilities bounded to CAP_CHOWN CAP_SYS_ADMIN CAP_NET_ADMIN. UNIX socket /run/zwall-hosting-ebpf/observer.sock.

The Agent does not receive CAP_NET_ADMIN / CAP_SYS_ADMIN. Network attach is not the Agent’s job. hosting.network is a socket client.

Fail-closed YAML: hosting.enabled: true, agent.protection_model: hosting, hosting.enforcement: false, audit_only and log_only true. Example profile identity hosting-plesk-observe-v2 is not a public SKU.

Collectors are path- and permission-dependent. Several example sources are permission_blocked or source_not_present by default. There is no shipped universal ACL.

Data/control flow

  • Logs, cert expiry metadata, service/disk/parser health: Agent reads local state → category-safe events → Manager.
  • Network: loader attaches pass-only programs → Agent polls socket → category-safe detector classes → Manager.
  • Heartbeat: observation_only plus Hosting status.
  • Control plane: enroll like any Agent; cannot receive rules or restart APIs (409). systemd on the node for process control.

Preflight: --hosting-network-preflight-url / --hosting-network-preflight-id prints COMPATIBLE or INCOMPATIBLE. Upgrade preflight prints UPGRADE_COMPATIBLE or UPGRADE_*.

Boundaries

  • Never drop, redirect, or rewrite forwarding.
  • No VM topology enrichment claim.
  • No Hosting sources into automatic/provider AI.
  • No UID/GID filtering feature.
  • No mixing zwall-agent.service as a drop engine on the same shared hosting node.
  • protection_model: hybrid is the wrong concept for this profile (the hybrid example misleads vs Hosting identity).
  • Events in Hosting APIs are category-safe: no raw payload or customer IPs.

Edition differences

Enterprise only. Community has no Hosting units, loader, or Hosting APIs.

Common misconceptions

  • “Add the Agent to the site group so nginx logs work.” Never join a customer-content group; grant exact-path ACLs.
  • “v2 adm is enough for Plesk panel.log.” The unit comments say otherwise until operator ACLs.
  • “Enable enforcement flags for protection.” Validation rejects that.
  • “Hosting Agent v2 is a different product SKU.” Public name remains Hosting Agent.