Hosting Agent Configuration
Hosting Agent configuration reference
Files. /etc/zwall-hosting/agent.yml (v1 unit); /etc/zwall-hosting/agent-v2.yml (v2 unit); /etc/zwall-hosting/hosting-ebpf.env (loader)
Source authority. HostingObservationConfig + configs/agent.hosting-plesk-observe-v2.example.yml
Fail-closed observation. hosting.enforcement must stay false. The Agent never joins a customer-content group; Plesk/site sources stay permission_blocked until exact-path ACLs.
Server/agent keys (server.manager_url, agent.hostname, agent.protection_model: hosting) follow Agent Configuration with Hosting paths.
hosting
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
hosting.enabled | Hosting Agent | Master switch | bool | yes for profile | true in example | true/false | true | no | restart | ENTERPRISE | hosting example | |
hosting.platform | Hosting Agent | Platform id | string | no | plesk | string | plesk | no | restart | ENTERPRISE | hosting example | |
hosting.profile_version | Hosting Agent | Profile identity | string | no | hosting-plesk-observe-v2 | hosting-plesk-observe-v2 | no | restart | ENTERPRISE | pre-register profile_version | hosting example | |
hosting.audit_only | Hosting Agent | Audit-only collectors | bool | no | true | true/false | true | no | restart | ENTERPRISE | hosting example | |
hosting.log_only | Hosting Agent | Log-only | bool | no | true | true/false | true | no | restart | ENTERPRISE | hosting example | |
hosting.enforcement | Hosting Agent | Must stay false | bool | no | false | false | false | no | restart | ENTERPRISE | 409 on rules/restart | hosting example |
hosting.checkpoint_path | Hosting Agent | Checkpoint file | path | no | /var/lib/zwall-hosting/hosting-checkpoints.json | path | no | restart | ENTERPRISE | hosting example | ||
hosting.poll_interval | Hosting Agent | Source poll | duration | no | 2s | 2s | no | restart | ENTERPRISE | hosting example | ||
hosting.poll_max_bytes | Hosting Agent | Per-poll bytes | int | no | 1048576 | 1048576 | no | restart | ENTERPRISE | hosting example | ||
hosting.poll_max_lines | Hosting Agent | Per-poll lines | int | no | 4096 | 4096 | no | restart | ENTERPRISE | hosting example | ||
hosting.poll_max_events | Hosting Agent | Per-poll events | int | no | 2048 | 2048 | no | restart | ENTERPRISE | hosting example | ||
hosting.poll_max_sink_submissions | Hosting Agent | Sink cap | int | no | 4096 | 4096 | no | restart | ENTERPRISE | hosting example | ||
hosting.poll_max_duration | Hosting Agent | Poll deadline | duration | no | 30s | 30s | no | restart | ENTERPRISE | slow hosts | hosting example | |
hosting.checkpoint_bytes | Hosting Agent | Checkpoint size | int | no | 262144 | 262144 | no | restart | ENTERPRISE | hosting example | ||
hosting.checkpoint_records | Hosting Agent | Checkpoint records | int | no | 512 | 512 | no | restart | ENTERPRISE | hosting example | ||
hosting.checkpoint_interval | Hosting Agent | Checkpoint period | duration | no | 250ms | 250ms | no | restart | ENTERPRISE | hosting example | ||
hosting.service_interval | Hosting Agent | systemd service poll | duration | no | 30s | 30s | no | restart | ENTERPRISE | services[] | hosting example | |
hosting.identity_interval | Hosting Agent | Identity refresh | duration | no | 5m | 5m | no | restart | ENTERPRISE | hosting example | ||
hosting.auth_rate_threshold | Hosting Agent | Auth-rate observe | int | no | 10 | 10 | no | restart | ENTERPRISE | not enforcement | hosting example | |
hosting.auth_rate_window | Hosting Agent | Auth-rate window | duration | no | 5m | 5m | no | restart | ENTERPRISE | hosting example | ||
hosting.auth_rate_cooldown | Hosting Agent | Auth-rate cooldown | duration | no | 15m | 15m | no | restart | ENTERPRISE | hosting example |
hosting.network
Connects the unprivileged Agent to the privileged loader. No attach/drop surface.
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
hosting.network.enabled | Hosting Agent | UNIX observer client | bool | no | true | true/false | true | no | restart | ENTERPRISE | loader must run first | HostingNetworkConfig |
hosting.network.socket_path | Hosting Agent | Observer socket | path | no | /run/zwall-hosting-ebpf/observer.sock | UNIX path | /run/zwall-hosting-ebpf/observer.sock | no | restart | ENTERPRISE | loader RuntimeDirectory | hosting example |
hosting.network.poll_interval | Hosting Agent | Socket poll | duration | no | 5s | 5s | no | restart | ENTERPRISE | hosting example | ||
hosting.network.max_response_bytes | Hosting Agent | Max read | int | no | 1048576 | 1048576 | no | restart | ENTERPRISE | hosting example | ||
hosting.network.max_events_per_poll | Hosting Agent | Event cap | int | no | 64 | 64 | no | restart | ENTERPRISE | hosting example | ||
hosting.network.request_timeout | Hosting Agent | Request deadline | duration | no | 20s | 20s | no | restart | ENTERPRISE | hosting example | ||
hosting.network.read_timeout | Hosting Agent | Read deadline | duration | no | 2s | 2s | no | restart | ENTERPRISE | hosting example | ||
hosting.network.write_timeout | Hosting Agent | Write deadline | duration | no | 2s | 2s | no | restart | ENTERPRISE | hosting example |
hosting.sources
Each element (HostingSourceConfig):
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
hosting.sources[].id | Hosting Agent | Parser id | string | yes | server-owned ids | hosting.ssh.auth.v1 | no | restart | ENTERPRISE | parsers never from UI | HostingSourceConfig | |
hosting.sources[].path | Hosting Agent | Exact log path | path | yes | allowlisted path | /var/log/auth.log | no | restart | ENTERPRISE | operator ACLs required | HostingSourceConfig | |
hosting.sources[].site_id | Hosting Agent | Optional site bind | string | no | no | restart | ENTERPRISE | sites[].id | HostingSourceConfig | |||
hosting.sources[].state | Hosting Agent | Inventory state | string | no | permission_blocked / source_not_present / empty=collect | permission_blocked | no | restart | ENTERPRISE | example YAML | hosting example | |
hosting.sources[].reason | Hosting Agent | Why blocked | string | no | permission_denied / not_present | permission_denied | no | restart | ENTERPRISE | hosting example |
Example ids: hosting.ssh.auth.v1, hosting.ftp.auth.v1, hosting.mail.auth.v1, hosting.plesk.panel.v1, hosting.nginx.access.v1, hosting.nginx.error.v1, hosting.apache.access.v1, hosting.apache.error.v1, hosting.php_fpm.error.v1, hosting.mysql.error.v1, hosting.mariadb.error.v1, hosting.fail2ban.observe.v1, hosting.dns.error.v1, hosting.modsecurity.global.metadata.v1.
ModSecurity collector is global metadata only — not full WAF payload.
hosting.services
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
hosting.services | Hosting Agent | systemd unit names to observe | string[] | no | example list | unit names | ssh.service | no | restart | ENTERPRISE | service_interval | hosting example |
Example list: ssh.service, nginx.service, apache2.service, mariadb.service, postfix.service, dovecot.service, xinetd.service, named.service, fail2ban.service, sw-cp-server.service. Observation of unit active state, not start/stop control.
hosting.sites
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
hosting.sites[].id | Hosting Agent | Category-safe site id | string | yes | opaque id | site-safe-id | no | restart | ENTERPRISE | never copy path into events | HostingSiteConfig | |
hosting.sites[].document_root | Hosting Agent | Local docroot | path | yes | /var/www/vhosts/SAFE_SITE_NAME/httpdocs | no | restart | ENTERPRISE | local only | HostingSiteConfig | ||
hosting.sites[].system_user | Hosting Agent | Account name | string | yes | SAFE_SITE_USER | no | restart | ENTERPRISE | not copied into events | HostingSiteConfig |
hosting.certificates
Scroll sideways to see the full table. Use the arrow keys when focused.
| Key | Component | Description | Type | Required | Default | Allowed values | Example | Secret/sensitive | Restart/reload | Edition | Interactions | Source authority |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
hosting.certificates[].id | Hosting Agent | Local cert label | string | yes | plesk-panel | no | restart | ENTERPRISE | expiry-only metadata | HostingCertificateConfig | ||
hosting.certificates[].address | Hosting Agent | Loopback TLS endpoint | string | yes | host:port | 127.0.0.1:8443 | no | restart | ENTERPRISE | names/SANs/bytes never leave host | HostingCertificateConfig |