# 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.
>
> Canonical: https://xdp.network/docs/openshield-xdp/enabling-metrics · Updated 2026-08-09

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`:

```yaml title="/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
```

:::warning
Without a `metrics.whitelist` entry your metrics endpoint is open to anyone who can reach
the port. Always restrict it.
:::

## 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

- [Getting credentials](/docs/openshield-xdp/getting-credentials)
- [Connecting a server to the dashboard](/docs/openshield-xdp/connecting-a-server)
- [Configuration](/docs/openshield-xdp/configuration)