Configuration

Hosting Agent configuration

Purpose #

Render the Hosting Agent YAML and loader environment so the unprivileged Agent can collect where you grant paths, and so the privileged loader can attach pass-only programs.

Audience #

Operators installing or changing zwall-hosting-agent.service / zwall-hosting-agent-v2.service and zwall-hosting-ebpf-loader.service.

Edition #

ENTERPRISE_ONLY.

Status #

SUPPORTED as keys present in configs/agent.hosting-plesk-observe-v2.example.yml and the shipped units. Production file ACLs are operator-owned.

Prerequisites #

• Admitted Hosting artifacts: zwall-agent, zwall-hosting-ebpf-loader, hosting_observe.o
• SHA-256 of the object file for ZWALL_HOSTING_EBPF_SHA256
• Physical interface names eligible for observation
• Manager URL the Agent will use (example file uses https://manager.example.invalid:9443 — that host and port are examples, not a second canonical Manager port)

Required permissions #

Root to write /etc/zwall-hosting/ and to manage units. Runtime Agent user zwall-hosting must be able to read each log path you expect to leave permission_blocked.

Dependencies #

• Manager reachable with server.verify_tls: true
• Loader unit before the v2 Agent (Before=zwall-hosting-agent-v2.service on the loader; v2 Agent After= the loader)
• UNIX socket directory /run/zwall-hosting-ebpf (unit RuntimeDirectory)

Configuration files #

Use the filename the installed unit names in ExecStart. Do not mix Virtualization /etc/zcs/agent.yml on this node.

Example source: configs/agent.hosting-plesk-observe-v2.example.yml.

Agent unit environment #

Both Hosting Agent units set:

v1 ExecStart: /opt/zwall-hosting/bin/zwall-agent --config /etc/zwall-hosting/agent.yml
v2 ExecStart: /opt/zwall-hosting/bin/zwall-agent --config /etc/zwall-hosting/agent-v2.yml

Loader environment #

/etc/zwall-hosting/hosting-ebpf.env must supply:

Loader flags from the 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

Default socket if not overridden: /run/zwall-hosting-ebpf/observer.sock. ExecStop is --detach.

Required Hosting keys #

When hosting.enabled: true, validation requires:

The profile rejects enforcement-capable Agent features: SMTP proxy, GeoIP, local detection, virtualization integration, UID/GID filtering, port-scan/MAC/DHCP rules, and metrics.enabled (Hosting exposes no metrics listener).

Selected example keys:

hosting.network is how the Agent polls the loader. It is not an XDP attach API.

hosting.sources[] #

Do not copy example log paths as if every OS used them.

Bootstrap token #

Set AGENT_TOKEN or AGENT_PRE_TOKEN in the environment for one-time registration. The Hosting-enabled Agent unsets both from the process environment after config load. Persist identity at ZWALL_AGENT_CREDENTIAL_PATH. Do not keep steady-state JWTs in YAML.

Procedure #

1. Copy the v2 example to the path the unit will read.
2. Set server.manager_url to your Manager (typically https://manager.example.com:8443). Keep verify_tls: true.
3. Keep enforcement flags false. Keep protection_model: hosting.
4. Edit hosting.sources[] paths to files that exist on this host. Leave state: permission_blocked until ACLs exist.
5. Write hosting-ebpf.env with the object digest and interfaces.
6. Grant exact-path read to zwall-hosting for collectors you expect to be active. Do not chmod 777 /var/log.
7. Enable loader, then Agent. Restart the Agent after YAML changes.

SIGHUP reload exists on the generic Agent binary; Hosting-specific live-reload of every key is not a certified contract. Prefer systemctl restart of the Hosting Agent unit after config changes. Restarting the loader detaches via --detach then re-attaches.

Verification #

See Validation. Minimum:

systemctl is-active zwall-hosting-ebpf-loader
systemctl is-active zwall-hosting-agent    # or zwall-hosting-agent-v2Copy

GET /api/v1/agents/:id/hosting/status as admin.

Expected result #

Loader owns pass-only programs. Agent runs as zwall-hosting with no capabilities. Collectors you ACL’d leave permission_blocked. Network socket exists. Heartbeat is observation-only.

Failure modes #

Troubleshooting #

Troubleshooting.

Security considerations #

• Empty Agent capabilities. Do not add CAP_NET_ADMIN to the Agent to “fix” observation.
• Never join a customer-content group.
• MemoryDenyWriteExecute=true on the Agent units; loader has a reduced syscall filter including bpf.
• Tokens live in /var/lib/zwall-hosting/agent.identity, not YAML.

Limitations #

• No shipped universal ACL.
• protection_model vs Hosting profile identity is a known profile-identity mismatch — do not copy Virtualization hybrid.
• Edge mode is rejected on this profile.
• UID/GID filtering is disabled and rejected when Hosting is enabled.
• Example Manager URL port 9443 is not a product-wide Manager port.

Related documentation #

• Purpose
• Signal classes
• Hosting Agent configuration reference
• Install
• systemd units