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

Hosting Agent Install

Hosting Agent installation

EnterpriseStatus: SUPPORTED as unit/config facts. Production log ACLs remain operator-owned.Audience: hosting operator, deployment engineer

Purpose

Install the observation-only Hosting profile. This is not Community.

Components

  1. zwall-hosting-ebpf-loader.service (root) loads hosting_observe.o
  2. zwall-hosting-agent.service (user zwall-hosting) runs the Agent

Loader ExecStart (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-hosting

ExecStop is the same binary with --detach.

Environment file: /etc/zwall-hosting/hosting-ebpf.env.

Agent unit:

  • User=zwall-hosting
  • ExecStart=/opt/zwall-hosting/bin/zwall-agent --config /etc/zwall-hosting/agent.yml
  • ZWALL_AGENT_STATE_DIR=/var/lib/zwall-hosting
  • ZWALL_AGENT_CREDENTIAL_PATH=/var/lib/zwall-hosting/agent.identity
  • SupplementaryGroups=adm psaserv
  • No ambient capabilities

There is also zwall-hosting-agent-v2.service in the same directory; the loader unit Before= that v2 unit. Use the unit names shipped in the admitted release. Do not mix Virtualization zwall-agent.service on the same node as a drop engine for a shared hosting node.

Configuration

Start from configs/agent.hosting-plesk-observe-v2.example.yml:

  • hosting.enabled: true
  • hosting.enforcement: false
  • hosting.network.socket_path: "/run/zwall-hosting-ebpf/observer.sock"
  • Source list with explicit state: permission_blocked / source_not_present where the example says so

Do not copy example log paths as if every host had them.

Procedure

  1. Install release artifacts for Hosting Agent + loader + hosting_observe.o
  2. Render /etc/zwall-hosting/agent.yml and /etc/zwall-hosting/hosting-ebpf.env
  3. Resolve source file read ACLs for each collector you expect to be COLLECTING
  4. Enable loader, then Agent
  5. Enroll the Agent (Hosting bootstrap unsets AGENT_PRE_TOKEN / AGENT_TOKEN from the process environment after load)

Verification

  • systemctl is-active zwall-hosting-ebpf-loader
  • systemctl is-active zwall-hosting-agent (or the v2 unit name actually installed)
  • Manager GET /api/v1/agents/:id/hosting/status
  • Hosting UI pages show drops fixed at zero for observation programs
  • Packet path still forwards (this is an observation profile)

Agent also supports read-only:

zwall-agent --hosting-network-preflight-url URL --hosting-network-preflight-id ID

prints COMPATIBLE or INCOMPATIBLE.

In-place profile transition preflight:

zwall-agent --hosting-upgrade-preflight --config PATH --expected-agent-id N --compatibility-manifest-sha256 DIGEST --agent-artifact-sha256 DIGEST

prints UPGRADE_COMPATIBLE or a failure category.