Agents

Troubleshooting

Where to look when a machine doesn't show up, goes offline, or won't run what you send it.

Where the agent logs

• Linux: journalctl -u cermm-agent -f.
• macOS: sudo launchctl print system/cermm-agent shows whether it’s running and its last exit.
• Windows: C:\ProgramData\CERMM\agent.log, the last 1 MB and the one before it (agent.log.1). Windows services have nowhere else to write.

cermm-agent inventory prints what the agent would send, as JSON. cermm-agent health prints pending reboots, failed services and updates. cermm-agent version prints its build.

The install fails

• Expired or wrong token: tokens last 24 hours. Make a new line in Add device. Nothing was installed.
• Run it as root / Run PowerShell as Administrator: the installer needs to put a service in place.
• install.ps1 did not match this line: the server's installer changed since the line was made (the server was updated). Copy a new line.
• Unsupported CPU or No agent built for …: there's no build for that machine on the server. Builds exist for Linux amd64, arm64 and arm; Windows amd64 and arm64; macOS amd64 and arm64.
• curl can't connect: the machine can't reach the server's address and port. Check from the machine with curl -k https://SERVER:4800/api/agent/ping.

It shows offline

A device is offline when it hasn't reported for 90 seconds. Workstations going offline isn't an alert; servers are, after a few minutes (Settings → Alerts).

• Is the service running? systemctl status cermm-agent, or Services on Windows (CERMM Agent).
• Can the machine reach the server? Agents keep the address they were installed with: if the server's address changed, set CERMM_URL or give it the old one back.
• A report loop stuck for 10 minutes makes the agent exit so the service manager starts it again. A start that fails is logged and retried every 30 seconds.
• Just after boot, Windows can take a minute to start PowerShell. The agent reports anyway; the inventory and health check follow when ready.

The server's key isn't the one this agent was installed with

The agent pinned the server's key at install, and the server now has a different one: its tls/ folder was lost or replaced, or it was given a custom certificate. Put the old key back from a backup, or install the agent again with a new line. See HTTPS.

A job is refused

Refusals arrive in the Run drawer at once, with the reason:

• Bad signature: the job wasn't signed by the key the agent pinned. Same cause as above.
• Expired: jobs expire 10 minutes after they're made. Check the machine's clock.
• Wrong device: the job was addressed to another machine.
• Commands off: the machine was installed monitor-only (how to change it).

A job the agent took but never finished is failed with the reason after its time limit (or after 90 seconds if it never started).

Agent says behind

Its build is older than the server's. See Agent updates, or run the Add device line again on the machine.