Configuration¶

The OPNsense Exporter follows standard Prometheus ecosystem conventions. It can be configured using command-line flags, environment variables, or a combination of both. Environment variables take the prefix OPNSENSE_EXPORTER_ unless noted otherwise.

The flag tables on this page are generated from the exporter's own flag definitions by make docs, so they always match the binary.

OPNsense connection¶

These settings control how the exporter connects to the OPNsense API.

File-based secrets¶

For secure credential management in containers and orchestrated environments, credentials can be read from files:

Exporter settings¶

Health endpoints & scrape filtering¶

The exporter serves two probe endpoints alongside /metrics:

Note: if you configure basic_auth_users in the exporter-toolkit web config file (--web.config.file), authentication applies to all endpoints including /-/healthy and /-/ready — Kubernetes probes cannot easily send basic-auth credentials, so prefer network-level protection over basic auth when probes are in use.

/metrics supports node_exporter-style per-scrape collector filtering:

curl 'http://localhost:8080/metrics?collect[]=gateways&collect[]=interfaces'
curl 'http://localhost:8080/metrics?exclude[]=firewall_rule'

collect[] and exclude[] are mutually exclusive (400 if both are given); unknown collector names return 400 listing the valid names (the subsystem names of the collectors enabled in this instance). The always-on metrics (opnsense_up, health/status, opnsense_exporter_*) are emitted regardless of filtering.

The exporter also honors the X-Prometheus-Scrape-Timeout-Seconds header sent by Prometheus: the collector fan-out runs under a deadline of the header value minus --exporter.scrape-timeout-offset, so a slow firewall endpoint produces a partial-but-successful scrape (with the affected collector's opnsense_exporter_scrape_collector_success = 0) instead of a wholesale scrape failure.

Continuous profiling (Pyroscope)¶

The exporter can push continuous profiles to Grafana Cloud Pyroscope using the pyroscope-go SDK. Profiling is disabled by default and activates only when --pyroscope.server-address (env OPNSENSE_EXPORTER_PYROSCOPE_SERVER_ADDRESS) is set. There are no unauthenticated /debug/pprof/* endpoints.

File-based secrets¶

Like the OPNsense API credentials, the auth user and password can be read from files instead of flags/env vars: set PYROSCOPE_AUTH_USER_FILE and/or PYROSCOPE_AUTH_PASSWORD_FILE to a path whose first line holds the value. The file value takes precedence over the corresponding flag/env var when present and non-empty.

Profiles are tagged with instance (the resolved instance label) and version.

OTLP metrics export¶

In addition to the /metrics pull endpoint, the exporter can push the exact same metrics to an OpenTelemetry (OTLP) endpoint. A Prometheus-bridge producer reads the existing registry on each export tick, so OTLP metric names, labels and values are identical to what /metrics exposes (no native renaming) — existing dashboards keep working against either backend. Export is disabled by default and activates only when --otlp.enabled (env OPNSENSE_EXPORTER_OTLP_ENABLED) is set. The pull endpoint is unaffected whether or not OTLP is enabled.

Any field left empty falls through to the corresponding standard OpenTelemetry environment variable (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_METRIC_EXPORT_INTERVAL, OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES, …) read natively by the OTEL SDK. Explicit --otlp.* flags take precedence over those env vars.

The metric set exported over OTLP is byte-for-byte the same as the Prometheus catalogue (see the metrics reference); enabling OTLP adds no new metric names.

Grafana Cloud shortcut¶

Setting --otlp.grafana-cloud-instance-id, --otlp.grafana-cloud-token and --otlp.grafana-cloud-endpoint together synthesizes the Authorization: Basic base64(instanceID:token) header and uses the gateway URL as the endpoint, so you do not have to assemble the basic-auth header yourself. An explicit --otlp.endpoint or Authorization header always wins over the shortcut. The instance ID and token also support *_FILE secret variants (OPNSENSE_EXPORTER_OTLP_GRAFANA_CLOUD_INSTANCE_ID_FILE, OPNSENSE_EXPORTER_OTLP_GRAFANA_CLOUD_TOKEN_FILE), whose file contents take precedence over the flag/env value, mirroring the OPNsense API credentials.

Temporality¶

Exported metrics are always cumulative, and this is not configurable. They are sourced from the Prometheus registry via a bridge producer, so they arrive already aggregated as cumulative (Prometheus' model) and are exported as-is — exactly the temporality Grafana Cloud's metrics backend (Mimir) and Prometheus' OTLP ingest require. An exporter-side temporality selector cannot re-aggregate producer-supplied metrics, so no delta option is offered.

Collector switches¶

All collectors are enabled by default unless noted otherwise. Each can be individually disabled or enabled using CLI flags or environment variables.

Enabled by default (disable with flag)¶

Disabled by default (opt-in with flag)¶

These collectors are disabled by default because they make additional API calls per scrape. Enable them only if you need the data.

High-cardinality detail options¶

These flags enable per-item detail metrics that can produce a large number of time series. Each unique label combination creates a separate time series in Prometheus.

Full flag reference¶

Every flag the exporter accepts, generated from the binary's own flag definitions (--help shows the same set):