# Configuration

> Reference for /etc/openshield/openshield.yaml — metrics endpoint settings, auto_fetch mode, mitigation profile, and how to apply changes.
>
> Canonical: https://xdp.network/docs/openshield-xdp/configuration · Updated 2026-08-09

The OpenShield agent is configured through a single YAML file,
`/etc/openshield/openshield.yaml`. This page explains each key and how to apply changes
without restarting the agent.

## Annotated example

```yaml title="/etc/openshield/openshield.yaml"
metrics:
  enabled: true            # expose the metrics API (default: false)
  listen: 0.0.0.0:9100     # host:port the metrics API binds to
  whitelist:               # CIDRs allowed to query metrics
    - 203.0.113.0/24       # replace with the console egress range from your dashboard

auto_fetch:
  mode: dedicated          # run feed/geo updates in a dedicated process (recommended)

profile: game-udp          # mitigation preset; see openshield profile list
```

## Apply changes with openshield reload

After editing the file, apply it without dropping the XDP attach:

```bash
openshield reload
```

Then confirm the agent picked the change up with `openshield status`.

## Choose an auto_fetch mode

`auto_fetch.mode: dedicated` is recommended. Geo and feed updates can be large; in
dedicated mode they run in a separate process, so a big refresh does not make the agent
slow to respond on its metrics endpoint while it works.

## Restrict the metrics whitelist

`metrics.whitelist` lists the CIDR ranges allowed to query the metrics API. Callers from
any other address get a 403.

:::warning
Without a `metrics.whitelist` entry your metrics endpoint is open to anyone who can reach
the port. Always restrict it before exposing the listen address beyond localhost.
:::

## Key reference

| Key | Default | Purpose |
| --- | --- | --- |
| `metrics.enabled` | `false` | Turns the metrics endpoint on |
| `metrics.listen` | — | `host:port` the metrics API binds to |
| `metrics.whitelist` | — | CIDR list allowed to query metrics |
| `auto_fetch.mode` | — | Update strategy; `dedicated` recommended |
| `profile` | — | Mitigation preset, e.g. `game-udp` |

Run `openshield profile list` to see the presets installed on your server.

## Next steps

- [Enabling metrics](/docs/openshield-xdp/enabling-metrics)
- [Tuning profiles](/docs/openshield-xdp/tuning-profiles)
- [Getting credentials](/docs/openshield-xdp/getting-credentials)