Purpose
Hosting Agent purpose
Purpose
On a shared or panel-managed Linux host you need authentication, web, mail, certificate-expiry, disk, and service-health evidence without attaching a drop-capable firewall to the same node customers share.
The Hosting Agent is that observation profile. It is a Zwall Enterprise capability. Zwall Community does not ship it.
This document answers the operational questions that define the profile. Procedures live in the sibling files.
Audience
Operators of Plesk-shaped or similar shared hosting nodes who will install two processes: a privileged pass-only loader and an unprivileged Agent.
Edition
ENTERPRISE_ONLY. Do not copy these units onto a Community source install.
Status
SUPPORTED as unit/config/API facts. Collectors that need production file ACLs are not “broken”; they stay permission_blocked until you grant exact-path read. PHP-FPM and alternate MariaDB files may be source_not_present.
What it observes
Scroll sideways to see the full table. Use the arrow keys when focused.
| Class | How | Packet drop |
|---|---|---|
| Hosting logs (SSH, FTP, mail, panel, web, database, DNS, Fail2Ban, ModSecurity global metadata) | unprivileged zwall-hosting reads operator-granted paths | never |
| Certificate expiry metadata | loopback TLS example 127.0.0.1:8443 | never |
| Service health, disk/inode, source/parser health | host state snapshots | never |
| Network observation | privileged loader attaches hosting_observe.o; Agent reads a UNIX socket | prohibited (pass / TC OK only) |
Network observation is a socket consumer, not an attach/drop surface on the Agent.
What it never does
- Enforce.
hosting.enforcementmust befalse. When Hosting is enabled, validation requireshosting.audit_only: true,hosting.log_only: true, andhosting.enforcement: false. - Receive firewall rules. Assigning rules to a Hosting observation Agent returns 409
Hosting observation Agents cannot receive rules. - Accept remote restart from the Manager.
POST /api/v1/agents/:id/restartreturns 409Hosting observation Agents cannot receive restart commands. - Join a customer-content group. The Agent never becomes a member of a site-content UNIX group.
- Load Virtualization firewall objects (
firewall.o,firewall_egress.o) or UID/GID cgroup programs. UID/GID filtering is not a Hosting feature (and is not a stable customer contract even on Virtualization). - Feed Hosting sources into automatic/provider AI analysis under the current Hosting contract.
Privilege model
Two processes, two identities.
Unprivileged Agent
Scroll sideways to see the full table. Use the arrow keys when focused.
| Item | Value |
|---|---|
| User / Group | zwall-hosting |
CapabilityBoundingSet | empty |
AmbientCapabilities | empty |
NoNewPrivileges | true |
| Binary | /opt/zwall-hosting/bin/zwall-agent |
Supplementary groups differ by unit:
zwall-hosting-agent.service(v1):SupplementaryGroups=adm psaservzwall-hosting-agent-v2.service:SupplementaryGroups=admonly. Comments in the unit state that Plesk/site sources remainpermission_blockeduntil operator ACLs.
Use the unit names shipped in the admitted release. Do not add extra groups to “make collectors work.”
Privileged loader
Scroll sideways to see the full table. Use the arrow keys when focused.
| Item | Value |
|---|---|
| Unit | zwall-hosting-ebpf-loader.service |
| User | root |
| Object | /opt/zwall-hosting/ebpf/hosting_observe.o |
| ExecStart | zwall-hosting-ebpf-loader --object … --sha256 ${ZWALL_HOSTING_EBPF_SHA256} --interfaces ${ZWALL_HOSTING_INTERFACES} --run-user zwall-hosting --run-group zwall-hosting |
| ExecStop | same binary --detach |
CapabilityBoundingSet | CAP_CHOWN CAP_SYS_ADMIN CAP_NET_ADMIN |
| Socket | /run/zwall-hosting-ebpf/observer.sock |
The unprivileged Agent reads that socket via hosting.network. It has no attach/drop surface.
Relation to the Virtualization Agent
They share an Agent runtime. They do not share a job.
Scroll sideways to see the full table. Use the arrow keys when focused.
| Hosting Agent | Virtualization Agent | |
|---|---|---|
| Node | shared/panel host | KVM/libvirt host |
| Unit | zwall-hosting-agent.service or zwall-hosting-agent-v2.service | zwall-agent.service |
| User | zwall-hosting | root |
| Programs | hosting_observe.o via loader | firewall.o + firewall_egress.o |
| Drop | prohibited | intended |
Do not run zwall-agent.service as a drop engine on the same shared hosting node as a substitute for Hosting observation.
agent.protection_model may be virtualization, hosting, or hybrid on the shared Agent. The Hosting profile requires hosting. Example YAML that sets hybrid is for a different profile and will mislead if copied here. Public docs say Hosting Agent; internal profile identity hosting-plesk-observe-v2 is not a SKU name.
Operator-owned ACLs
There is no shipped universal ACL. Collectors need operator-granted read on the exact log paths configured in hosting.sources[]. Example paths (/var/log/auth.log, /var/log/nginx/access.log, …) are examples. An example helper JSON exists at deploy/agent-systemd/hosting-source-permissions.v1.example.json for Fail2Ban rotation-safe mode 0640 root:zwall-hosting — it is not a host-wide permission manifest.
Until those ACLs exist, Hosting status will show permission_blocked or source_not_present. That is expected, not a product outage.
Events you will see
Events the Manager exposes for Hosting are category-safe. Do not expect raw payload or customer IPs in Hosting event APIs (GET /api/v1/agents/:id/hosting/events projection: event_id, source, category, severity, timestamp, parser, contract_version, review_state).
Heartbeat evidence includes observation_only. Drops remain zero for observation programs.