Server shows offline

Diagnose a red offline dot: agent stopped, metrics disabled, wrong URL or port, a whitelist that misses the console, or a bad key.

Last updated

On this page

A red offline dot means the console's poll of your agent's metrics API is failing. Work through the checks in order — each one names the command or error that decides whether you move on.

Run the checks in order

  1. Check the agent is running. On the server, run systemctl status openshield and openshield status. If the unit is stopped, nothing can answer the console — bring the agent up first.

  2. Check metrics are enabled and reloaded. metrics.enabled must be true in /etc/openshield/openshield.yaml, and the console only sees the running config — run openshield reload after every edit. See Enabling metrics.

  3. Check the URL and port. The Metrics API URL saved in the console must match metrics.listen (host), and that port must be listening and reachable from outside. openshield key prints the exact URL and key the agent expects.

  4. Check the whitelist covers the console. A 403 means "this dashboard's IP is not in the server's metrics whitelist (403)". Add a CIDR to metrics.whitelist that covers the console's egress IP, then openshield reload.

  5. Check the key. A 401 means "invalid API key (401) — check the key on the server with: openshield key". Re-copy the key into the console and save. 401 is the key; 403 is your IP — do not mix up the fixes.

  6. Rule out slow responses. A timeout (20s) means the server is offline, is blocking the dashboard's IPs, or is busy applying a large geo/feed update. If timeouts persist, set auto_fetch.mode: 'dedicated' and confirm the port is reachable.

Open a ticket if every check passes

If the row is still red, open a ticket and include the server name as shown in the console, the exact error the dashboard reports (401, 403, timeout, or 502), the output of openshield status and openshield key, and the metrics.listen and metrics.whitelist lines from your config.

Next steps