Introduction

Welcome to the dnsbl-exporter documentation.

Usage

Learn how to configure the dnsbl-exporter.

Configuration

See rbls.ini and targets.ini files in the repository for examples.

The files follow the Nagios format as this exporter is meant to be a drop-in replacement so you can factor out Nagios, one (simple) step at a time. 😊

Otherwise:

$ dnsbl-exporter -h
...
--config.dns-resolver value  IP address of the resolver to use. (default: "127.0.0.1:53")
--config.rbls value          Configuration file which contains RBLs (default: "./rbls.ini")
--config.targets value       Configuration file which contains the targets to check. (default: "./targets.ini")
--config.domain-based        RBLS are domain instead of IP based blocklists (default: false)
--web.listen-address value   Address to listen on for web interface and telemetry. (default: ":9211")
--web.telemetry-path value   Path under which to expose metrics. (default: "/metrics")
--log.debug                  Enable more output in the logs, otherwise INFO.
--log.output value           Destination of our logs: stdout, stderr (default: "stdout")
--help, -h                   show help
--version, -V                Print the version information.

System resolver

The dnsbl-exporter can use your system resolver from /etc/resolv.conf automatically.

Please note: The dnsbl-exporter needs read permissions to /etc/resolv.conf file for this feature to work.

Configure resolver as an argument:

--config.dns-resolver=system

Configure resolver as an environment variable:

DNSBL_EXP_RESOLVER=system

Please see DNS for further details.

Not every resolver is compatible with most RBLs.

Metrics returned by exporter

The individual configured servers and their status are represented by a gauge:

luzilla_rbls_ips_blacklisted{hostname="mail.gmx.net",ip="212.227.17.168",rbl="ix.dnsbl.manitu.net"} 0

This represents the server’s hostname and the DNSBL in question:

0 (zero) for unlisted
1 (one) for listed

Requests to the DNSBL happen in real-time and are not cached. Take this into account and use accordingly.

If the exporter is configured for DNS based blocklists, the ip label represents the return code of the blocklist.

You are listed!

If you happen to be listed — inspect the exporter’s logs as they will contain a reason.

DNS

In order to use the dnsbl-exporter, you need a DNS resolver to query the RBLs directly.

Using public resolvers such as Google, Cloudflare, OpenDNS, Quad9 etc. will likely not work as often a NXDOMAIN response is treated different by these providers.

The recommendation is to setup a private resolver, such as Unbound without forwarding, which means you will use root NS.

Important

Please note: If you have local copy (mirror) of RBL zone synced over rsync or other channels you can configure local rbldnsd to serve this zone and configure Unbound query this zone from rbldnsd.

To install unbound on a Mac, follow these steps:

$ brew install unbound
...
$ sudo unbound -d -vvvv

Tip

Leave the Terminal open — there will be ample queries and data for you to see and learn from.

An alternative to Homebrew is to use Docker; an example image is provided in this repository, it contains a working configuration — ymmv.

docker run -p 53:5353/udp ghcr.io/luzilla/unbound:v0.7.0-rc3

Verify Unbound works:

 $ dig +short @127.0.0.1 spamhaus.org
192.42.118.104

Exporter operation modes

Exporter can work in 2 modes:

classic:
- targets are configured in targets.ini
- /metrics endpoint is used to receive metrics
prober:
- targets are configured on the Prometheus side
- /prober&target= is used
- targets.ini should be empty

Each operation mode requires an rbl.ini, for example:

[rbl]
server=ix.dnsbl.manitu.net

Prober mode provides additional features over classic:

dynamic configuration of targets on Prometheus side
different query/check interval of queries for different targets (e.g. to work around strict rate limits of the DNSBL)
~~set different query settings by utilizing probes modules~~ (not yet implemented)

classic

The following examples configure scraping of metrics from this exporter in classic mode.

Example for a targets.ini:

[targets]
server=smtp.fastmail.com

Prometheus

scrape_configs:
  - job_name: 'dnsbl-exporter'
    metrics_path: /metrics
    static_configs:
      - targets: ['127.0.0.1:9211']

For more details, see the Prometheus scrape config documentation.

Prometheus Operator

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: dnsbl-exporter
  namespace: dnsbl-exporter
spec:
  endpoints:
    - interval: 30s
      port: http-9211
      scrapeTimeout: 5s
  jobLabel: dnsbl-exporter
  namespaceSelector:
    matchNames:
      - dnsbl-exporter
  selector:
    matchLabels:
      app.kubernetes.io/instance: dnsbl-exporter
      app.kubernetes.io/name: dnsbl-exporter

You can use a ServiceMonitor or PodMonitor, for more details, see the Operator ServiceMonitor documentation or Operator PodMonitor documentation.

prober

The following examples configure scraping of metrics from this exporter in prober mode.

Prometheus

scrape_configs:
  - job_name: 'dnsbl-exporter-prober'
    metrics_path: /prober
    params:
      module: [ips]
    static_configs:
      - targets:
        - smtp.fastmail.com
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9211 # The dnsbl exporter's real hostname:port.
  - job_name: 'dnsbl-exporter-metrics' # collect dnsbl exporter's operational metrics.
    static_configs:
      - targets: ['127.0.0.1:9211']

For more details, see the Prometheus scrape config documentation.

Prometheus Operator

apiVersion: monitoring.coreos.com/v1
kind: Probe
metadata:
  name: dnsbl-exporter-prober
  namespace: dnsbl-exporter
spec:
  interval: 30s
  jobName: dnsbl-exporter-prober
  module: ips
  prober:
    path: /prober
    scheme: http
    url: dnsbl-exporter.dnsbl-exporter.svc:9211 # Kubernetes dnsbl exporter's service
  scrapeTimeout: 5s
  targets:
    staticConfig:
      static:
        - smtp.fastmail.com
---
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: dnsbl-exporter-metrics # collect dnsbl exporter's operational metrics.
  namespace: dnsbl-exporter
spec:
  endpoints:
    - interval: 30s
      port: http-9211
      scrapeTimeout: 5s
  jobLabel: dnsbl-exporter-metrics
  namespaceSelector:
    matchNames:
      - dnsbl-exporter
  selector:
    matchLabels:
      app.kubernetes.io/instance: dnsbl-exporter
      app.kubernetes.io/name: dnsbl-exporter

For more details, see the Operator Probe documentation.

In addition, you can use a ServiceMonitor or PodMonitor to monitor the dnsbl-exporter’s operational metrics, for more details, see the Operator ServiceMonitor documentation or Operator PodMonitor documentation.

Alerting

The following example alerts use the available metrics from the exporter.

Listing

To determine if your host/ip is listed, use one of the following.

Prometheus

alerts:
  groups:
  - name: dnsbl-exporter
    rules:
    - alert: DnsblRblListed
      expr: luzilla_rbls_ips_blacklisted > 0
      for: 15m
      labels:
        severity: critical
      annotations:
        description: {{ $labels.hostname }} ({{ $labels.ip }}) has been blacklisted in {{ $labels.rbl }} for more than 15 minutes.
        summary: Endpoint {{ $labels.hostname }} is blacklisted
        runbook_url: https://example.org/wiki/runbooks

For more details, see the Prometheus Alerting documentation.

Prometheus Operator

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: dnsbl-rules
spec:
  groups:
  - name: dnsbl-exporter
    rules:
      - alert: DnsblRblListed
        expr: luzilla_rbls_ips_blacklisted > 0
        for: 15m
        labels:
          severity: critical
        annotations:
          description: {{ $labels.hostname }} ({{ $labels.ip }}) has been blacklisted in {{ $labels.rbl }} for more than 15 minutes.
          summary: Endpoint {{ $labels.hostname }} is blacklisted
          runbook_url: https://example.org/wiki/runbooks

For more details, see the Operator Alerting documentation.

Errors

Tip

New in v0.13.0.

The exporter now returns a per-target luzilla_rbls_errors gauge with the same (rbl, ip, hostname) labels as luzilla_rbls_ips_blacklisted: 1 if the most recent check failed, 0 otherwise.

To collapse it to one alert per RBL, aggregate to a scalar:

- alert: DnsblRblErrors
  expr: sum by (rbl)(luzilla_rbls_errors) > 0
  for: 15m
  labels:
    severity: warning
  annotations:
    summary: RBL {{ $labels.rbl }} is returning errors

Deployment

The dnsbl-exporter can be deployed (or installed) as a stand-alone binary, container or on Kubernetes using Helm.

Standalone

Releases are available for Mac, Linux and FreeBSD.

Go to release and download a binary for your system/platform.
Get rbls.ini and put it next to the binary.
Get targets.ini, and customize. Or use the defaults.
./dnsbl-exporter

Tip

Example config files are provided on GitHub.

Go to http://127.0.0.1:9211/ in your browser.

Managing the exporter

Tip

Check out Packages.

As option you can configure exporter to run as systemd service. Consider using a package instead.

packages

Tip

New in version v0.13.0.

Each (GitHub) release also contains:

rpm
deb (jammy, noble, bookworm)
sysext

The package will setup default configuration in /etc/dnsbl-exporter and includes a systemd unit to manage the exporter as well.

$ systemctl enable dnsbl-exporter
$ systemctl start dnsbl-exporter
$ systemctl status dnsbl-exporter

Container

Docker/OCI images are available in the container registry:

$ docker pull ghcr.io/luzilla/dnsbl_exporter:vX.Y.Z
...

The image works with podman and docker as the exporter runs rootless (user nobody).

Caution

The latest tag is not provided. Please pick an explicit version.

The images expect target.ini and rbls.ini in the following location:

Either start the container and supply the contents, or build your own image:

docker run \
    --rm \
    -e DNSBL_EXP_RESOLVER=your.resolver:53 \
    -p 9211:9211 \
    -v ./conf:/etc/dnsbl-exporter \
    ghcr.io/luzilla/dnsbl_exporter:vA.B.C

FROM ghcr.io/luzilla/dnsbl_exporter:vA.B.C

ADD my-target.ini /target.ini
ADD my-rbls.ini /rbls.ini

Helm

Additionally, a helm chart is provided to run the dnsbl-exporter on Kubernetes.

To get started quickly, an unbound container is included as a sidecar in the pod alongside the exporter.

This unbound acts as a local DNS server to send queries to.

Tip

To disable the included, use unbound.enabled=false and provide your own resolver (via config.resolver: an.ip.address:port).

To configure the chart, copy chart/values.yaml to values.local.yaml.

Another useful option to add our chart as dependency to your own chart:

dependencies:
  - name: dnsbl-exporter
    repository: oci://ghcr.io/luzilla/charts
    version: 0.1.0

Caution

Please adjust the chart version.

The sources for the helm chart are in chart, to install it, you can inspect the Chart.yaml for the version, check the helm chart repository or check out artifact hub.

The following command creates a dnsbl-exporter release which is installed into a namespace called my-namespace:

helm upgrade --install \
    --namespace my-namespace \
    -f ./chart/values.yaml \
    -f ./values.local.yaml \
    dnsbl-exporter oci://ghcr.io/luzilla/charts/dnsbl-exporter --version 0.1.0

Keyboard shortcuts

dnsbl-exporter