Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Operations › Logs

Logs

SharedStatus: SUPPORTED for journald and configured log files. Event-delivery exactly-once is NOT claimed.Audience: operator, incident responder

Purpose

Find Manager, Agent, and security-event logs without treating them as a lossless SIEM contract.

Prerequisites

  • journalctl for systemd units
  • Permission to read the unit journal and any logging.file path

Where logs go

systemd journal 

journalctl -u zwall-manager -e
journalctl -u zwall-agent -e
journalctl -u zwall-hosting-agent -e
journalctl -u zwall-hosting-agent-v2 -e
journalctl -u zwall-hosting-ebpf-loader -e

Follow: journalctl -u zwall-manager -f.

Hosting units set LogRateLimitIntervalSec / LogRateLimitBurst (Agent 30s/200, loader 30s/100). Burst suppression can hide a flood; that is a hardening control, not a bug.

Configured files (examples)

Scroll sideways to see the full table. Use the arrow keys when focused.

ComponentExample YAML logging.file / agent.log_fileUnit ReadWritePaths
Manager/var/log/zcs/firewall-manager.log/var/log/zwall-manager
Virtualization Agent/var/log/zcs/firewall-agent.log/var/log/zcs
Hosting AgentHosting example / journalHosting unit does not grant /var/log/zcs; prefer journal

If YAML points at a path the unit cannot write (ProtectSystem=strict + ReadWritePaths), the process logs elsewhere or fails. Confirm with systemctl cat and the live YAML.

Manager flags -log-file, -verbose, -debug override when used on the command line. The Enterprise unit does not pass those flags.

Security events in the Manager

Operators read events via:

zwallctl log --lines 50
zwallctl list-events --hours 24 --limit 100
zwallctl grep 203.0.113.10

API: GET /api/v1/security-logs with limit (default 100), offset (default 0), filters log_id, log_type, agent_id, severity, action, source_ip, destination_ip, start_time, end_time.

zwallctl log --follow prints that follow is not implemented.

Hosting observation events: GET /api/v1/agents/:id/hosting/events. Those payloads are category-safe; do not expect raw log lines or customer IPs.

Verification

  • Journal shows the unit started without repeating crash loops.
  • GET /api/v1/security-logs returns 200 for an admin (empty list is valid).
  • Hosting: parser/source health in hosting status, not silence in nginx access logs on the Manager.

Failure modes

Scroll sideways to see the full table. Use the arrow keys when focused.

SymptomMeaningAction
no file at YAML pathunit cannot write, or logging.file unusedjournal + ReadWritePaths
empty security-logsAgents offline, filters too tight, or Hosting category-safe pathMissing telemetry
journal rate-limitedHosting LogRateLimitinspect loader/Agent status rather than flooding journal
lossless delivery assumeddelivery gap opendo not claim exactly-once

Security considerations

  • Journals and dump files may contain source IPs, hostnames, usernames (Virtualization path). Hosting path is category-safe by design.
  • Do not paste JWT, license keys, backup passphrases, or 2FA secrets into tickets.
  • AI Preview redaction is a separate path; keep ai.redact.enabled true when AI is enabled.
  • export_audit_logs.sh exists for PostgreSQL export; treat output as confidential.

Limitations

  • No public log-retention SLA.
  • Community vs Enterprise log directory names differ.
  • WebSocket dashboard is not a public streaming product.