Enabling metrics

Turn on the OpenShield agent's metrics API, restrict it with a whitelist, and verify it with curl — plus what 401 and 403 responses mean.

Last updated

On this page

The console reads your server through the agent's metrics API. This page shows you how to enable it safely and confirm it answers before you add the server to the dashboard.

What the metrics endpoint is

The agent serves a small HTTP API on the address set by metrics.listen:

  • GET /metrics — the JSON metrics payload: live traffic, attack forensics, bans, and license info.
  • GET /health — a lightweight liveness check the console uses for Test connection.

Both require an Authorization: Bearer osk_… header.

Why metrics are off by default

metrics.enabled defaults to false. The endpoint exposes operational detail about your server, so the agent only opens it when you explicitly opt in — and only to the networks you name in metrics.whitelist.

Enable metrics in the agent config

Edit /etc/openshield/openshield.yaml:

/etc/openshield/openshield.yaml
metrics:
  enabled: true
  listen: 0.0.0.0:9100
  whitelist:
    - 203.0.113.0/24   # replace with the console egress range from your dashboard

Apply the change:

bash
openshield reload

Verify the endpoint with curl

From a host inside the whitelisted range, call /health with your API key:

bash
curl -H "Authorization: Bearer osk_…" http://server:9100/health

A successful response means the console will be able to connect. Run openshield key on the server to print the URL and key to use.

What 401 and 403 mean

  • 401 Unauthorized — the key is wrong or missing. Re-check the Bearer value against openshield key output.
  • 403 Forbidden — the key is fine, but the caller's IP is not in metrics.whitelist. Add the caller's CIDR and run openshield reload again.

Next steps