Signal Classes
Hosting signal classes
Purpose
List the Hosting source identifiers operators configure, what each class is, and which ones are expected to stay blocked or absent until you change the host.
Audience
Operators filling hosting.sources[] and reading Log Sources / Hosting status.
Edition
ENTERPRISE_ONLY.
Status
SUPPORTED as the v2 example inventory plus the Hosting capability matrix completeness labels. Paths in the example are examples. Events the Manager shows are category-safe: no raw payload or customer IPs in Hosting event APIs.
Prerequisites
hosting.enabled: true and a source id the parser bundle knows. The UI does not define parsers.
Required permissions
Exact-path read for zwall-hosting on every file you expect to be COLLECTING / active. No shipped universal ACL.
Source inventory
From configs/agent.hosting-plesk-observe-v2.example.yml and the Hosting v2 matrix.
Scroll sideways to see the full table. Use the arrow keys when focused.
| Source id | Class | Example path | Completeness |
|---|---|---|---|
hosting.ssh.auth.v1 | SSH authentication | /var/log/auth.log | implemented and tested |
hosting.ftp.auth.v1 | FTP authentication | /var/log/auth.log | implemented and tested (fixed transfer log absent) |
hosting.mail.auth.v1 | SMTP/mail authentication | /var/log/mail.log | implemented and tested |
hosting.plesk.panel.v1 | Plesk panel authentication | /var/log/plesk/panel.log | REQUIRES_PRODUCTION_PERMISSION (example state: permission_blocked) |
hosting.nginx.access.v1 | Nginx access | /var/log/nginx/access.log | REQUIRES_PRODUCTION_PERMISSION |
hosting.nginx.error.v1 | Nginx error | /var/log/nginx/error.log | REQUIRES_PRODUCTION_PERMISSION |
hosting.apache.access.v1 | Apache access | /var/log/apache2/access.log | implemented and tested |
hosting.apache.error.v1 | Apache error | /var/log/apache2/error.log | implemented and tested |
hosting.php_fpm.error.v1 | PHP-FPM | /var/log/php8.3-fpm.log | SOURCE_NOT_PRESENT (parser exists; no approved fixed production path in the matrix) |
hosting.mysql.error.v1 | MySQL | /var/log/mysql/error.log | implemented and tested |
hosting.mariadb.error.v1 | MariaDB alternate file | /var/log/mariadb/mariadb.log | SOURCE_NOT_PRESENT (MySQL-compatible source exists) |
hosting.fail2ban.observe.v1 | Fail2Ban observe | /var/log/fail2ban.log | rotation-safe permission contract; example still permission_blocked |
hosting.dns.error.v1 | DNS | /var/log/syslog | implemented and tested |
hosting.modsecurity.global.metadata.v1 | ModSecurity global metadata only | /var/log/modsec_audit.log | GLOBAL_METADATA_ONLY — not per-site audit files |
Also implemented, not as hosting.sources[] file tails:
Scroll sideways to see the full table. Use the arrow keys when focused.
| Signal | Example | Notes |
|---|---|---|
| Certificate-expiry metadata | hosting.certificates[] 127.0.0.1:8443 | loopback TLS expiry, not a PKI inventory; names/SANs/bytes never leave the host |
| Service health | hosting.services[] (ssh.service, nginx.service, apache2.service, mariadb.service, postfix.service, dovecot.service, xinetd.service, named.service, fail2ban.service, sw-cp-server.service) | unit names are examples |
| Disk / inode snapshots | host state | category-safe |
| Source / parser health | Hosting status | includes parser_unsupported and related states |
| Network observation | loader + hosting.network | see Network observation |
hosting.sites[] maps id, document_root, system_user for local identity. Those paths are not copied into events.
Source states you will see
Hosting health accepts states including:
active, available_but_disabled, source_not_present, permission_blocked, parser_unsupported, degraded, failed
Permission status values include readable, not_required, permission_blocked, operator_approval_required, source_not_present.
Example YAML pre-marks Plesk/nginx/Fail2Ban as permission_blocked / permission_denied, and PHP-FPM/MariaDB as source_not_present / not_present. That is the intended default, not a crash.
Procedure
- Diff the example
idlist against logs that exist on this OS (Debian Apache vs RHELhttpd, Plesk vs none). - Point
pathat the real file. Do not create fake logs to satisfy the example. - Grant exact-path read to
zwall-hosting(and, if you run the v1 unit,adm/psaservas shipped — v2 isadmonly). - For Fail2Ban, the example permission helper uses owner
root, groupzwall-hosting, mode0640, rotation-safe create policy — still operator-owned. - Accept
SOURCE_NOT_PRESENTfor PHP-FPM and alternate MariaDB unless you have a real file and an approved path. - Treat ModSecurity as global metadata only unless per-site audit files are separately in scope (they are not in this inventory).
Verification
GET /api/v1/agents/:id/hosting/status — per-source state / permission_status / parser version.
GET /api/v1/agents/:id/hosting/events — projection only:
event_id, source, category, severity, timestamp, parser, contract_version, review_state
Optional limit query 1..100 (default 50).
Log Sources UI: collector state, lag, permission reason.
Expected result
SSH/FTP/mail/Apache/MySQL/DNS collectors can become active once paths and ACLs match. Plesk/nginx stay blocked until production ACLs. PHP-FPM/MariaDB alternate may remain absent. Events in the Manager omit raw bodies and customer IPs.
Failure modes
Scroll sideways to see the full table. Use the arrow keys when focused.
| State | Meaning | Action |
|---|---|---|
permission_blocked | file exists; zwall-hosting cannot read | exact-path ACL; do not chmod 777 |
source_not_present | path not on this host | retarget or accept absence |
parser_unsupported | id not in parser bundle | do not invent parser ids |
operator_approval_required | production permission gate | owner ACL decision |
| Empty hosting events | no Hosting log types ingested | status first, then events |
Troubleshooting
See Troubleshooting. Parser health and heartbeat observation_only belong in the same diagnosis as source state.
Security considerations
- Hosting sources are excluded from automatic/provider AI analysis.
- Do not ship customer log bodies in tickets; status reasons are enough.
- Fail2Ban observe is observation of Fail2Ban’s own log, not Zwall becoming Fail2Ban.
Limitations
- Not a universal log shipper.
- Not per-site ModSecurity WAF management.
- Certificate helper is loopback expiry, not inventory of every vhost certificate.
- Completeness labels are matrix facts, not SLAs.
Related documentation
- Configuration
- Validation. Hosting status/events HTTP APIs are provided separately to Enterprise customers.
- Hosting telemetry
- Event model