How to Install Prometheus Blackbox Exporter on Ubuntu: A Step-by-Step Guide

Prometheus Blackbox Exporter is a powerful tool used to probe endpoints over various protocols like HTTP, HTTPS, DNS, TCP, and ICMP. It integrates seamlessly with Prometheus, allowing you to monitor and alert based on the availability and performance of your services. This guide will walk you through installing and configuring the Prometheus Blackbox Exporter on an Ubuntu system.

Prerequisites

An Ubuntu server (20.04 or later recommended).
Root or sudo privileges.
Prometheus installed and configured.

Step 1: Update Your System

Before installing any software, ensure your system is updated.

sudo apt update && sudo apt upgrade -y

Step 2: Download the Blackbox Exporter

Visit the Prometheus Blackbox Exporter GitHub releases page to find the latest version. Download the latest release (replace the version number with the latest one):

wget https://github.com/prometheus/blackbox_exporter/releases/download/v0.24.0/blackbox_exporter-0.24.0.linux-amd64.tar.gz

Step 3: Extract the Archive

Extract the downloaded tarball:

tar -xvzf blackbox_exporter-0.24.0.linux-amd64.tar.gz

Move into the extracted directory:

cd blackbox_exporter-0.24.0.linux-amd64

Step 4: Install the Blackbox Exporter

Copy the binary to /usr/local/bin to make it accessible system-wide:

sudo mv blackbox_exporter /usr/local/bin/

Ensure the binary is executable:

sudo chmod +x /usr/local/bin/blackbox_exporter

Step 5: Create a Blackbox Exporter User

For security, run the exporter as a non-root user:

sudo useradd --no-create-home --shell /bin/false blackbox_exporter

Step 6: Configure the Systemd Service

Create a systemd service file for the Blackbox Exporter:

sudo nano /etc/systemd/system/blackbox_exporter.service

Add the following content to the file:

[Unit]
Description=Prometheus Blackbox Exporter
After=network.target

[Service]
User=blackbox_exporter
Group=blackbox_exporter
Type=simple
ExecStart=/usr/local/bin/blackbox_exporter --config.file=/etc/blackbox_exporter/config.yml
Restart=always

[Install]
WantedBy=multi-user.target

Save and exit (Ctrl+O, Ctrl+X).

Step 7: Configure Blackbox Exporter

Create a configuration directory and file:

sudo mkdir /etc/blackbox_exporter
sudo nano /etc/blackbox_exporter/config.yml

Add a basic configuration like this:

modules:
  http_2xx:
    prober: http
    timeout: 5s
    http:
      method: GET
      fail_if_ssl: false
  tcp_connect:
    prober: tcp
    timeout: 10s
    tcp:
      preferred_ip_protocol: "ip4"

Save and exit.

Step 8: Start and Enable the Service

Reload the systemd daemon:
Start the Blackbox Exporter service:
Enable it to start on boot:
Check the service status to confirm it is running:

sudo systemctl daemon-reload
sudo systemctl start blackbox_exporter
sudo systemctl enable blackbox_exporter
sudo systemctl status blackbox_exporter

Step 9: Configure Prometheus to Use Blackbox Exporter

Edit your Prometheus configuration file (e.g., prometheus.yml):

sudo nano /etc/prometheus/prometheus.yml

Add a job for the Blackbox Exporter under scrape_configs:

scrape_configs:
  - job_name: 'blackbox'
    metrics_path: /probe
    params:
      module: [http_2xx] # Choose the module defined in config.yml
    static_configs:
      - targets:
        - http://example.com
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: localhost:9115 # Blackbox Exporter address

Replace the localhost with your IP Address. Save and exit.

Restart Prometheus:

sudo systemctl restart prometheus

Allow Port 9115 in the Firewall

If your server uses a firewall (e.g., UFW), you’ll need to allow traffic on port 9115. Run the following command:

sudo ufw allow 9115
sudo ufw reload

To verify that the rule is active:

sudo ufw status

You should see an entry for port 9115 allowing TCP connections.

Step 10: Verify the Setup

Verify that the Blackbox Exporter is running by visiting http://<your_server_ip>:9115/metrics.
Check Prometheus targets at http://<your_prometheus_server_ip>:9090/targets to see if the Blackbox Exporter is listed and active.

Conclusion

You now have the Prometheus Blackbox Exporter installed and configured on your Ubuntu server. By monitoring endpoints with Blackbox Exporter, you can ensure your systems and services are reachable and performant.