Security¶

This guide covers secure configuration of opnsense2otel, including API key management, TLS, and least-privilege access.

OPNsense API key creation¶

1. Log in to the OPNsense web UI.
2. Navigate to System > Access > Users.
3. Create a dedicated monitoring user (do not use the root account).
4. Assign the user to a group with only the required permissions.
5. Scroll to the API keys section and click + to generate a new key pair.
6. Save the downloaded file - it contains the key and secret.

OPNsense user permissions¶

Create a group (for example, monitoring) and grant the ACL units from the generated matrix for every collector you enable. The matrix covers every registered exporter endpoint, including non-collector health and log-shipping calls; status unknown is an explicit result and must not be replaced with a guessed narrower permission.

Generated collector-to-ACL matrix¶

Generated from the endpoint ACL map, OPNsense core 26.7.1 and 26.1.11, and github.com/opnsense/plugins @ b59cf8e (2026-07-12) (re-derived 2026-07-25).

Status is known, plugin-dependent, or unknown. Unknown is an audited result, not an omitted recommendation. plugin-gated means this endpoint is treated as absent when its plugin route returns 404.

401 and 403 remediation¶

For a 401 or 403, the exporter log and operator console identify the collector, endpoint, and likely privilege from this matrix. Grant the indicated privilege to the API key's user, then check System > Access > Users > Effective Privileges. The guidance never includes an API key, secret, authorization header, or response body.

TLS configuration¶

Using OPNsense with HTTPS¶

The exporter connects to OPNsense via HTTPS by default when --opnsense.protocol=https is set. For OPNsense instances using a certificate signed by a public CA, no additional configuration is needed.

Self-signed or private-CA certificates¶

If your OPNsense uses a self-signed certificate or one issued by a private CA, trust the CA where the exporter can see it. The recommended approach depends on how the exporter runs.

Host / bare binary (recommended for non-container installs)

On a normal Linux host the exporter uses the OS trust store. Add the OPNsense CA to it and refresh the bundle:

sudo cp opnsense-ca.crt /usr/local/share/ca-certificates/opnsense-ca.crt
sudo update-ca-certificates

This works only where update-ca-certificates (or your distro's equivalent) merges that directory into the system bundle. It does not apply to the official container image.

Container (official distroless image)

The official runtime image is distroless: it has no update-ca-certificates and does not merge /usr/local/share/ca-certificates into Go's trust roots, so mounting a certificate there leaves it untrusted. Instead mount the CA bundle at any path and point Go's TLS stack at it with SSL_CERT_FILE:

services:
  opnsense2otel:
    image: ghcr.io/rknightion/opnsense2otel:latest
    environment:
      SSL_CERT_FILE: /certs/opnsense-ca.pem
    volumes:
      - ./opnsense-ca.pem:/certs/opnsense-ca.pem:ro

See Custom CA certificates in the Docker deployment guide for the full example.

Disable TLS verification (not recommended)

--opnsense.insecure

Or via environment variable:

OPN2OTEL_OPS_INSECURE=true

Exporter TLS (web config)¶

The exporter itself can serve metrics over HTTPS using the Prometheus exporter toolkit's web configuration:

--web.config.file=/path/to/web-config.yml

Example web config:

tls_server_config:
  cert_file: /path/to/cert.pem
  key_file: /path/to/key.pem

Avoid enabling the exporter toolkit's rate_limit option in the web config on listeners reachable by untrusted peers: it is a single pre-authentication global bucket, so any one client can exhaust it and starve legitimate Prometheus scrapes.

File-based secrets¶

For production deployments, avoid passing API credentials as command-line flags or plain environment variables. Instead, use file-based secrets:

The exporter reads the first line of each file. File-based secrets take precedence over flag/env var values when set.

Docker secrets example¶

services:
  opnsense2otel:
    image: ghcr.io/rknightion/opnsense2otel:latest
    environment:
      OPS_API_KEY_FILE: /run/secrets/opnsense-api-key
      OPS_API_SECRET_FILE: /run/secrets/opnsense-api-secret
    secrets:
      - opnsense-api-key
      - opnsense-api-secret

Kubernetes secrets example¶

env:
  - name: OPS_API_KEY_FILE
    value: /etc/opnsense2otel/creds/api-key
  - name: OPS_API_SECRET_FILE
    value: /etc/opnsense2otel/creds/api-secret
volumeMounts:
  - name: api-key-vol
    mountPath: /etc/opnsense2otel/creds
    readOnly: true

Systemd with file permissions¶

# Create credential files
# The exporter service user needs read access; unrelated users do not.
sudo install -d -o root -g opnsense2otel -m 0710 /etc/opnsense2otel
printf '%s\n' 'your-api-key' | sudo install -o root -g opnsense2otel -m 0640 /dev/stdin /etc/opnsense2otel/api-key
printf '%s\n' 'your-api-secret' | sudo install -o root -g opnsense2otel -m 0640 /dev/stdin /etc/opnsense2otel/api-secret

The directory's 0710 mode lets the service group traverse directly to the named files without listing the directory. Each 0640 file is readable only by root and the opnsense2otel group; unrelated users cannot traverse the directory.

OPNsense settings¶

One collector needs an extra OPNsense setting enabled:

• Unbound DNS collector: Enable Unbound DNS > Advanced > Extended Statistics in the OPNsense web UI for full DNS metrics.

Container security¶

The official container image is hardened:

• Distroless base image - minimal attack surface with no shell, package manager, or unnecessary binaries
• Non-root execution - runs as UID 65532 (nonroot)
• Read-only root filesystem - supported in Kubernetes and Docker
• No capabilities - all Linux capabilities are dropped in the Kubernetes deployment manifest
• Static binary - no runtime dependencies, CGO disabled

The /metrics endpoint requires no authentication by default, so restrict who can reach it at the network layer. On Kubernetes, a sample NetworkPolicy limiting ingress on the metrics port to Prometheus is provided at deploy/k8s/networkpolicy.yaml.