Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

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

And 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:

  1. dynamic configuration of targets on Prometheus side
  2. different query/check interval of queries for different targets (e.g. to work around strict rate limits of the DNSBL)
  3. 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.

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.

Deployment

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

Standalone binary

Releases are available for Mac, Linux and FreeBSD.

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

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

As option you can configure exporter to run as systemd service.

Container

Docker/OCI images are available in the container registry:

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

Please note: The latest is not provided. 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 installed into the pod alongside the exporter. This unbound acts as a local DNS server to send queries to. You may turn this off with 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

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