Validation

Hosting Agent validation

Purpose #

Prove a Hosting Agent is observing — units up, status in the Manager, collectors explained, network programs pass-only — before you call the install complete.

Audience #

Deployment engineers signing off a panel host.

Edition #

ENTERPRISE_ONLY.

Status #

SUPPORTED. A source that remains permission_blocked after you skipped ACLs is not a failed product; it is an incomplete operator grant.

Prerequisites #

• Manager ready
• Hosting Agent enrolled (Enrollment) with Hosting profile identity (observation_only / hosting-plesk-observe-v2 as shipped)
• Admin JWT
• zwallctl pointed at the real Manager URL (not the unconfigured http://localhost:8080 default)

Required permissions #

Admin role for Hosting APIs. Root on the node for systemctl and socket inspection.

Procedure #

1. Units #

systemctl is-active zwall-hosting-ebpf-loader
systemctl is-active zwall-hosting-agent
# or, if the admitted release enabled v2:
systemctl is-active zwall-hosting-agent-v2Copy

Loader must be active before you treat network observation as in scope. Confirm you did not enable zwall-agent.service on this shared hosting node.

2. Socket and identity #

ls -l /run/zwall-hosting-ebpf/observer.sock
systemctl show zwall-hosting-agent-v2 -p User -p SupplementaryGroups -p ExecStartCopy

User must be zwall-hosting. Capabilities must remain empty. v2 supplementary group is adm only.

3. Manager inventory #

zwallctl login --manager-url https://manager.example.com:8443 --username admin
zwallctl list-agentsCopy

GET /api/v1/agents shows the Agent online. Heartbeat continues (console agent status / last_heartbeat).

4. Hosting status #

GET /api/v1/agents/:id/hosting/status (admin).

When no runtime snapshot has been stored yet, the handler may return runtime_available: false with collection_status: COLLECTING and review_readiness: continued_observation_required. After a validated heartbeat:

• runtime_available: true
• profile durable Hosting identity
• status includes sources, network attach lists, scan counters, delivery lag
• capability contract is observation-only

Confirm intended sources: active vs permission_blocked vs source_not_present. Confirm parser health fields. Confirm observation_only.

5. Hosting events #

GET /api/v1/agents/:id/hosting/events (optional limit=1..100).

Projection keys only: event_id, source, category, severity, timestamp, parser, contract_version, review_state.

If you see customer IPs or raw log bodies in this API, that is a contract bug — not something to “enable” in config.

6. Network observation #

Network Security UI / status: observation counters; drops remain zero. Packet forwarding still works.

Optional:

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

Expect COMPATIBLE.

7. Negative tests (prove fail-closed) #

• POST /api/v1/agents/:id/restart → 409 Hosting observation Agents cannot receive restart commands
• Assign a firewall rule to this Agent → 409 cannot receive rules
• zwallctl start / stop print not implemented — use systemd

8. Upgrade preflight (when changing profile in place) #

zwall-agent --hosting-upgrade-preflight --config /etc/zwall-hosting/agent-v2.yml \
  --expected-agent-id N \
  --compatibility-manifest-sha256 DIGEST \
  --agent-artifact-sha256 DIGESTCopy

Expect UPGRADE_COMPATIBLE or a named UPGRADE_* category. Digests are 64 hex characters; agent id must be positive.

Verification checklist #

Expected result #

An observation-only Agent whose missing collectors are explained by permission_blocked or source_not_present, not by a silent failure. Network programs pass.

Failure modes #

Troubleshooting #

Troubleshooting.

Security considerations #

Validation traffic should use TLS and an admin JWT. Do not paste bootstrap tokens into the checklist record.

Limitations #

This procedure does not certify an OS/kernel matrix and does not grant log ACLs for you.

Related documentation #

• Install
• First verification
• Hosting status/events and Agent HTTP details are provided separately to Enterprise customers.