Common issues

On this page

• Server shows offline
• Firewall metrics not appearing
• Common error messages
• Open a ticket
• Next steps

Match your symptom to a section below and work through the checks in order. Most problems come down to the fleet daemon on the server, the metrics key saved in the console, or network reachability between the two.

Server shows offline#

A fleet server shows offline when its daemon hasn't checked in for over two minutes — the daemon (xdpd) normally reports every ~15 seconds, and an offline server's health score is capped at 50. Work through these in order:

1. Check the daemon on the box. Run systemctl status xdpd on the server. If the service is stopped or failed, start it there — nothing in the console can reach a dead daemon.
2. Check outbound connectivity. The daemon polls the console over HTTPS, so the server needs outbound access to it. A firewall or DNS regression on the box looks exactly like a daemon crash from the dashboard.
3. Restart a live-but-stuck daemon from the console. On the server's Products tab, under Server actions, Restart cycles the xdpd service; reporting resumes within ~30 seconds. Queued actions only run when the daemon checks in, so this helps a flaky daemon, not a stopped one.
4. Re-enroll when the enrollment itself is broken. Also under Server actions, Re-enroll mints a fresh single-use enroll command — use it after wiping the daemon config or moving the box. Run the command on the server as root; the token expires shortly after and is never shown again. The current enrollment keeps working until the command runs, so minting one is safe.

If the server still shows offline after all four, open a ticket with the server label, the output of systemctl status xdpd, and when the box was last reachable.

Firewall metrics not appearing#

The OpenShield-XDP product console polls the agent's metrics API on your server with a stored osk_… key. The failure mode tells you which side to fix:

• invalid API key (401) — the key saved in the console no longer matches the agent. Run openshield key on the server to print the current key, then update the saved one with Rotate key in the server row's menu on the product page.
• this dashboard's IP is not in the server's metrics whitelist (403) — the key is valid but the console's egress IP is outside metrics.whitelist in /etc/openshield/openshield.yaml. Add a covering CIDR, then openshield reload.
• Timeout after 20 seconds — the server is offline, blocking the console's IPs, or busy applying a large geo/feed update. If timeouts persist, set auto_fetch.mode: 'dedicated' and confirm the metrics port is reachable.
• 502 — the console's metrics proxy couldn't get an answer from the agent. Check the agent on the server with openshield status, then openshield reload if the config changed.

If the server row is healthy but some panels are empty, the agent is omitting those sections: make sure metrics.enabled: true is set, run openshield reload after every config edit, and update the agent if it predates the panel — older agents simply don't send newer sections. If a teammate sees data you don't, your account lacks the analytics grant — ask an admin; nothing on the server needs to change.

Common error messages#

Match the message verbatim, then apply the fix. The Test connection button reports ok, invalid API key (401), source IP not allowed (403), server returned <status>, or unreachable — the same fixes apply.

On the public REST API, the three failures to know are 401 (missing, revoked, or disabled-account token), 404 (unknown id — or a resource owned by someone else, by design), and 429 (over the 120 requests/minute per-token limit; wait the Retry-After seconds).

Open a ticket#

When every check passes and the problem persists, open a ticket from My tickets in the console sidebar. Copy the error message verbatim — the wording identifies which component rejected the request — and include the server name as shown in the console.

Next steps#

• Console REST API
• OpenShield-XDP
• What is XDP.NETWORK