Scout — logging

Scout logs to two places at once, from the same stream of records:

• journald — the systemd journal, via stderr. journalctl -u cyphers-scout works the way it always has. Human-readable text.
• A product-owned log file — /var/log/cyphers-scout/scout.log, structured JSON, one record per line. This is the canonical location for support bundles and machine analysis.

Levels

Level	Meaning
error	Operator action likely required.
warn	Degraded, retried, or refused by policy — self-healing or fail-closed by design.
info	Lifecycle landmarks only: start, enroll, connect, command received/completed, rotation, policy apply. Steady state is quiet.
debug	Internal decisions and their inputs.
trace	Per-message flow: handshake steps, every publish/receive, collector walks, timings.

At debug and trace every record also carries its source file:line.

Flags

Flag	Default	Meaning
--log-level	info	trace|debug|info|warn|error — an unknown value refuses startup
--log-format	text	stderr format (text|json); the file is always JSON
--log-file	/var/log/cyphers-scout/scout.log	none disables the file sink
--log-max-size-mb	20	rotation threshold
--log-max-backups	5	rotated files kept (worst case ≈ 120 MB)

The file sink runs in agent mode only — one-shot scan and ct log to stderr alone.

Location, permissions, rotation

The scout creates and enforces /var/log/cyphers-scout/ at mode 0700 (root) and scout.log at 0600 on every start, re-tightening drifted permissions and refusing a symlinked path outright. The systemd unit additionally provisions the directory (LogsDirectory=cyphers-scout; see Install → The service). When scout.log crosses the size threshold it rotates to scout.log.1 (older backups shift up; the oldest beyond the keep-count is deleted; backups are 0600).

A failing file sink never stops the agent: on a write error (disk full, directory removed) the scout logs one warning to journald, continues on stderr alone, and retries the file once a minute.

What is never logged

Tokens, private keys, passphrases, and any other secret material never appear in scout logs — at any level, including trace. Sensitive values are typed so they render as [redacted], and a build-failing lint test keeps raw secrets from ever being added to a log call.

Recipes

• Follow live: journalctl -u cyphers-scout -f
• Temporarily raise verbosity: systemctl edit cyphers-scout, override ExecStart adding --log-level trace, systemctl restart cyphers-scout — revert when done.
• Support bundle: copy /var/log/cyphers-scout/scout.log* and journalctl -u cyphers-scout --since "-2 hours" > journal.txt.