Blackbox Exporter

Last reviewed Sep 13, 2026 · 796 words

If Prometheus is already scraping your homelab, Blackbox Exporter gets you HTTP, TCP, DNS and ping checks plus TLS certificate expiry for every service you run, in one 32 MB container, with alerts through the Alertmanager you already have. That is a complete Pingdom replacement for zero extra services. If Prometheus is not already running, do not start here; Uptime Kuma gives you the same checks with a UI in 5 minutes, and Gatus does the same with a status page on top.

The scrape config is the entire learning curve

Blackbox Exporter does nothing on its own. It listens on port 9115 and, when Prometheus hits /probe?module=http_2xx&target=https://example.com, it performs the probe and returns metrics about it. The trick is a relabeling block that turns a list of targets into that URL, and everyone copies it once and never thinks about it again:

scrape_configs:
  - job_name: blackbox-http
    metrics_path: /probe
    params:
      module: [http_2xx]
    static_configs:
      - targets:
          - https://vault.example.com
          - https://photos.example.com
          - https://git.example.com
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: blackbox:9115

Three relabel rules: the target goes into the target query parameter, the same value becomes the instance label so graphs are readable, and the actual scrape address is redirected to the exporter. Add a second job with module: [icmp] and IP addresses for the ping view, a third with tcp_connect for things like your SMTP or SSH ports. The exporter's own blackbox.yml defines the modules; the defaults cover the common cases and you rarely edit it beyond adding a module that accepts a 401 or follows no redirects.

The metrics that matter

Every probe returns probe_success (1 or 0), probe_duration_seconds, and for HTTP probe_http_status_code plus probe_ssl_earliest_cert_expiry when the target is TLS. Those four lines feed the two alert rules that justify the whole exercise:

groups:
  - name: blackbox
    rules:
      - alert: EndpointDown
        expr: probe_success == 0
        for: 3m
        labels: {severity: page}
      - alert: CertExpiringSoon
        expr: (probe_ssl_earliest_cert_expiry - time()) / 86400 < 14
        for: 1h
        labels: {severity: warn}

The for: 3m is not decoration. A scrape interval of 30 seconds with a 3-minute hold means a single dropped ping or a container restart does not wake you. Fourteen days on certificates is enough time to notice a broken ACME renewal before it matters. Route both through Alertmanager to whatever already pages you.

ICMP needs a capability, and DNS probes lie without a resolver

Ping probes require raw sockets. In Docker that means --cap-add NET_RAW or running as root, and on hosts with a restrictive net.ipv4.ping_group_range the unprivileged path fails silently with probe_success 0 and no obvious error. Check the exporter's log with --log.level=debug before assuming the target is down.

DNS probes resolve using the machine's resolver by default, so a DNS check for your internal domain from a container with Docker's embedded DNS can succeed while your real clients fail. Set the dns module's query_name and point the probe target at the specific resolver's IP and port 53, not at the name you want resolved.

Run it from where your users are

Blackbox measures reachability from wherever the exporter runs. On the same host as the services it will never notice that your router dropped the port forward. Run one instance inside the LAN for internal checks and, if you care about public reachability, a second on a cheap VPS scraped over Tailscale. Prometheus can scrape both with different job names and the instance label distinguishes them. This is the one thing the SaaS uptime products do for you that self-hosting makes you think about, and the monitoring stack piece goes into where each check should live.

Dashboards are a solved problem

Grafana's dashboard library has several community Blackbox dashboards; import one by ID, point it at your Prometheus datasource, and you get a status grid, latency per target and certificate countdowns without building anything. Add a stat panel of count(probe_success == 0) to the top of whatever Grafana home dashboard you look at daily and the exporter is fully earning its 32 MB.

What I'd do

Deploy the prom/blackbox-exporter image beside Prometheus, copy the scrape block above with every URL you would be annoyed to find down, add icmp for the router and NAS, wire the two alert rules through Alertmanager, and import a community dashboard. Then put a second exporter on a VPS for the services that face the internet. Total time about 45 minutes. If you find yourself wanting a status page for other people to look at, that is the point to add Gatus in front rather than to replace any of this.