Logs and diagnostics

Where each component writes its log on the host, how rotation and retention work, and what the log actually tells you.

The event log records what happened; the host's own log records how. The exact output of a reload command, the path a file was written to, the raw response from a DNS provider's API - none of that goes to the control plane, and all of it is here.

This matters most on Windows, where a service process's stderr goes nowhere.

Where the logs are

Each component writes to logs/ inside its own state directory, one file per UTC day.

Component	Linux	Windows
Fleet agent	`/etc/aethercert-agent/agent/logs/`	`C:\ProgramData\aethercert\agent\logs\`
CA connector	not applicable	`C:\ProgramData\aethercert\ca-connector\logs\`
Update Service	`/var/lib/aethercert-agent/main/logs/`	`C:\ProgramData\aethercert\main\logs\`
Tray	not applicable	`C:\ProgramData\aethercert\tray\logs\`
Installer	`/var/lib/aethercert-agent/setup/logs/`	`C:\ProgramData\aethercert\setup\logs\`

Today's file is <YYYY-MM-DD>.log. Yesterday's is compressed into logs/archive/<YYYY-MM-DD>.tar.gz at the first write after midnight UTC.

The installer's log sits outside the agent's and the connector's own state directories on purpose: an uninstall that deletes those must not also delete the log explaining what it just removed, and an install that fails before either directory exists still needs somewhere to write.

On Linux, run also writes to stderr, so the systemd journal has the same lines:

journalctl -u aethercertagent -f

Retention

Archives older than the retention window are pruned on every rotation. The window comes from the control plane on each check-in, derived from the plan and the agent's own setting:

Plan	Local log retention
Free	7 days, fixed
Standard, MSP, MSP Plus	Up to 30 days
Pro	Up to 90 days

Set it per agent under Manage > Agents > Manage > Settings. Until a first successful check-in the agent assumes 7 days, rather than keeping everything forever. A plan downgrade prunes immediately at the next check-in rather than waiting for the next day's rotation.

Reading it

Every line carries a level, so a first pass is a grep:

grep '\[ERROR\]' /etc/aethercert-agent/agent/logs/2026-09-06.log
grep '\[WARN\]'  /etc/aethercert-agent/agent/logs/2026-09-06.log

Timestamps are UTC, to microsecond precision, matching the UTC date the file is named for

so a line written near local midnight cannot end up carrying a date the file disagrees with.

What the agent log covers:

each check-in: the interval it was given, whether a job or an update was waiting
every job claimed, and its outcome
which challenge type and which authority an issuance used
the deploy step, including a reload command's own output
the local certificate scan, when it runs

That is enough to answer the two questions worth asking first: is this agent checking in at all, and if it is, why did a given job stall.

No secrets in the log

Key material, bearer tokens and API keys never reach a log line, including inside an error string. A script's output is truncated before it is carried into a job result, and a private key's contents are never logged at all.

From the tray

On Windows, the tray icon's Open logs opens the log directory of whichever backend is installed - or offers both as a submenu when the agent and the connector are on the same host. Sync now forces an immediate check-in, which also forces a certificate scan rather than waiting out its six-hour interval. Check for updates asks the Update Service to run a cycle now.

Checking what is installed

aethercert-installer status

prints each component, its version, its service state, whether its binary and config are present, and the control plane it points at. It exits 0 either way.

When the log is not enough

aethercert-ca-connector preflight is a read-only readiness check for a CA connector: the service account, the Windows service, CA reachability, and the template's issuable status and permissions. It changes nothing and names the exact step still missing. See The CA connector.