Configuration

Reference for /etc/openshield/openshield.yaml — metrics endpoint settings, auto_fetch mode, mitigation profile, and how to apply changes.

Last updated

On this page

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

/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.

Key reference

KeyDefaultPurpose
metrics.enabledfalseTurns 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