Connecting a server to the dashboard
Add your OpenShield server in the console, test the connection against /health, understand each failure, and read live metrics.
Last updated
On this page
Once the agent is installed and metrics are enabled, you connect the server in the console so the dashboard can poll it. The whole flow takes about a minute per server.
Add the server in the console
- Open your product page in the dashboard and choose Add server.
- Enter a name, the Metrics API URL, and the API key — both printed by
openshield keyon the server. - Click Test connection. The console calls
/healthon the agent from the server side, using your key. - When the test passes, click Save.
What each test failure means
| Failure | Cause | Fix |
|---|---|---|
| Unreachable | The console cannot open a connection to the URL | Check the URL, and that the metrics.listen port is reachable from outside |
| 401 | Invalid key | Re-copy the key from openshield key |
| 403 | Caller IP not whitelisted | Add the console egress range to metrics.whitelist and run openshield reload |
| Timeout | The agent accepted the connection but answered too slowly | Set auto_fetch.mode: dedicated so large updates do not stall responses, and confirm the port is reachable |
After the server connects
Within a few seconds of saving, the server row turns green and the live metrics tab starts filling in: traffic, attack forensics, bans, and geo analytics. The console polls the agent from the server side; your API key is stored server-side and never shown to browsers.
If the row stays grey or flips back to offline, work through the troubleshooting guide.