Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Hosting Agent › Operational Caveats

Operational Caveats

Hosting Agent operational caveats

Purpose

State the fail-closed rules that keep Hosting observation from becoming accidental enforcement, and the engineering gaps that operators must not paper over.

Audience

Anyone who will copy YAML, join UNIX groups, or mix Agent units on a panel host.

Edition

ENTERPRISE_ONLY.

Status

These caveats are binding. Where a complete safe procedure cannot be written, the gap is classified instead of being called complete.

Caveats

Observation only

hosting.enforcement must stay false. audit_only and log_only must stay true when Hosting is enabled. Validation rejects the profile otherwise. There is no Hosting “drop packet” API.

No rule assignment, no remote restart

Hosting observation Agents cannot receive rules (409). They cannot receive Manager restart commands (409). Use systemd on the node. zwallctl start / stop are not implemented remotely. zwallctl restart --agent will 409 on this profile.

Do not mix Virtualization enforcement on the same shared hosting node

zwall-agent.service (root, firewall.o) is the drop-capable unit. Do not run it as a substitute for Hosting observation on a customer-shared node. If you need packet policy for the estate, put it on Virtualization Agents, not on the panel host.

Privilege

Agent: CapabilityBoundingSet empty, AmbientCapabilities empty, user zwall-hosting. Never add net-admin capabilities to the Agent. Never join a customer-content group.

v1 unit supplementary groups: adm psaserv.
v2 unit: adm only; Plesk/site sources remain permission_blocked until exact-path ACLs.

Production permissions are operator-owned

No shipped universal ACL. Several collectors are IMPLEMENTED_REQUIRES_PRODUCTION_PERMISSION. Grant read on the exact files you configured. Do not chmod 777 /var/log.

SOURCE_NOT_PRESENT is a valid outcome

PHP-FPM and alternate MariaDB files may be absent. Pointing the example PHP path at a missing file is not a defect.

ModSecurity is global metadata only

Per-site audit files are not this inventory. Do not describe Hosting as a ModSecurity WAF controller.

Certificate expiry is loopback metadata

Example 127.0.0.1:8443 is TLS expiry of that address, not a full PKI inventory of customer certificates.

Hosting sources and AI Preview

Hosting sources are ineligible for automatic/provider AI. Do not expect AI Preview to analyze Hosting collectors.

protection_model vs Hosting profile

agent.protection_model: hybrid in the generic Agent example is not the Hosting profile. Hosting requires protection_model: hosting and hosting.enabled: true. Copying hybrid onto a panel host is misleading and will fail validation if Hosting is enabled.

Public name: Hosting Agent. Internal profile identity hosting-plesk-observe-v2 is not a customer SKU.

UID/GID filtering is not a Hosting feature

Do not document or enable enable_uid_gid_filtering here. Hosting validation rejects it. On Virtualization it is implemented with an incomplete ABI and is not a stable customer contract.

Kernel matrix is not certified

Isolated 5.4 attach tests are evidence of an isolated test. Community README mentions 4.15+ / 5.4+. Virtualization example YAML uses min_kernel_version: 5.8.0. This package does not pick one as certified.

Edge mode is not this profile

operating_mode: edge is rejected for Hosting. It is not a public certified product.

Path prefixes are not unified

Hosting uses /etc/zwall-hosting, /opt/zwall-hosting, /var/lib/zwall-hosting. Virtualization uses /etc/zcs, /opt/zcs. Manager uses /etc/zwall-manager or /etc/zcs. Follow the unit.

Event delivery is not lossless

Do not claim exactly-once or compliance-grade immutable audit for Hosting events.

SIGHUP vs restart

Generic Agent SIGHUP exists. Hosting live-reload of every key is not certified. Restart the Hosting unit after YAML changes. Stop Agent then loader (--detach) when tearing down network observation.

Updater on the Hosting example

Example YAML names updater.service_name: zwall-hosting-agent-v2. The in-product updater is not the supported production upgrade path. Use Hosting upgrade preflight instead of updater campaigns:

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 (UPGRADE_INVALID_REQUEST, UPGRADE_CONFIG_INCOMPATIBLE, UPGRADE_ARTIFACT_MISMATCH, UPGRADE_IDENTITY_INCOMPATIBLE, UPGRADE_RELEASE_MISMATCH, UPGRADE_AUTHENTICATION_FAILED, …).