unbound_exporter

To run the exporter on the same machine as Unbound, connect via a Unix socket.

1. Ensure your unbound.conf has remote control enabled on a socket:

   remote-control:
     control-enable: yes
     control-interface: /run/unbound.ctl

2. Run the exporter pointing to that socket. Use empty strings for -unbound.ca and -unbound.cert when using a local Unix socket without TLS.

Metrics are served on port 9167 at the /metrics endpoint.

unbound_exporter -unbound.ca "" -unbound.cert "" -unbound.host "unix:///run/unbound.ctl"

Modern versions of Go (1.15+) no longer treat the CommonName field in X.509 certificates as a hostname if Subject Alternative Names (SANs) are missing. Because the default unbound-control-setup provided with Unbound generates problematic keypairs that may fail in Go-based applications (like unbound_exporter), use the provided unbound-control-setup.sh script to generate a compatible keypair.

$ bash unbound-control-setup.sh

Install the unbound_exporter binary using go install. The binary will be placed in $GOBIN or $HOME/go/bin if $GOBIN is not set. Requires Go 1.24 or above.

go install github.com/letsencrypt/unbound_exporter@latest

To run the exporter on a separate host from Unbound, you must configure Unbound's control-interface with a TLS certificate from a private CA.

You must provide the following flags to unbound_exporter to point to the valid certificate files required to trust the Unbound server and be trusted by it:

# Example flag usage (replace with actual file paths)
unbound_exporter -unbound.ca /path/to/ca.pem -unbound.cert /path/to/cert.pem -unbound.key /path/to/key.pem -unbound.host "tls://unbound-host:port"

After generating the new keypair using unbound-control-setup.sh, update your /etc/unbound/unbound.conf to point to the newly generated server and control certificate/key files. Ensure control-enable and control-use-cert are both set to yes.

remote-control:
    control-enable: yes
    control-use-cert: yes
    server-key-file: "/etc/unbound/unbound_server_ec.key"
    server-cert-file: "/etc/unbound/unbound_server_ec.pem"
    control-key-file: "/etc/unbound/unbound_control_ec.key"
    control-cert-file: "/etc/unbound/unbound_control_ec.pem"

By default, Unbound only collects total query counts. To collect more granular metrics (such as query types), enable extended-statistics in your unbound.conf:

server:
    extended-statistics: yes

Once configured, verify that you can communicate with Unbound using unbound-control. Running unbound-control stats_noreset should return metrics, confirming that the exporter and control interface are working correctly.

$ unbound-control stats_noreset
thread0.num.queries=35
thread0.num.queries_ip_ratelimited=0
thread0.num.cachehits=25
thread0.num.cachemiss=10
thread0.num.prefetch=0
thread0.num.expired=0
...

The following flags are used to configure the connection to the Unbound control interface:

- `-unbound.host`: The address of the Unbound control interface (e.g., `unix:///run/unbound.ctl` or `tls://<host>:<port>`).
- `-unbound.ca`: Path to the CA certificate file used to verify the Unbound server's certificate.
- `-unbound.cert`: Path to the client certificate file.
- `-unbound.key`: Path to the client private key file.

The following command-line flags are available for configuring the unbound_exporter binary.

-web.listen-address
    Address to listen on for web interface and telemetry. (default ":9167")
-web.telemetry-path
    Path under which to expose metrics. (default "/metrics")
-web.health-path
    Path under which to expose healthcheck. (default "/_healthz")
-unbound.host
    Unix or TCP address of Unbound control socket. (default "tcp://localhost:8953")
-unbound.ca
    Unbound server certificate. (default "/etc/unbound/unbound_server.pem")
-unbound.cert
    Unbound client certificate. (default "/etc/unbound/unbound_control.pem")
-unbound.key
    Unbound client key. (default "/etc/unbound/unbound_control.key")

The unbound_exporter is configured via command-line flags that define how the exporter connects to the Unbound control socket and how it exposes its own telemetry.

Web Server Configuration

Use these flags to configure the Prometheus metrics endpoint and the health check endpoint.

Unbound Connection Configuration

Use these flags to specify the address of the Unbound control socket (Unix or TCP) and the TLS certificates required for a secure connection.

# Example usage with custom addresses and TLS certificates
./unbound_exporter \
  -web.listen-address ":9167" \
  -web.telemetry-path "/metrics" \
  -unbound.host "tcp://127.0.0.1:8953" \
  -unbound.ca "/path/to/ca.pem" \
  -unbound.cert "/path/to/client.pem" \
  -unbound.key "/path/to/client.key"