Blackbox Exporter

You can reload the Blackbox exporter configuration at runtime without restarting the process. If the new configuration is invalid, the changes will not be applied.

To trigger a reload, you can:

1. Send a SIGHUP signal to the process.
2. Send an HTTP POST request to the /-/reload endpoint.

Alternatively, you can enable automatic configuration reloading using the --config.enable-auto-reload flag. When enabled, the exporter checks for changes at an interval defined by --config.auto-reload-interval (defaults to 30 seconds).

Run the exporter as a Docker container. Ensure you mount your configuration directory (containing blackbox.yml) to the /config directory inside the container.

Note: You may need to enable IPv6 in your Docker configuration for certain probes.

docker run --rm \
  -p 9115/tcp \
  --name blackbox_exporter \
  -v $(pwd):/config \
  quay.io/prometheus/blackbox-exporter:latest --config.file=/config/blackbox.yml

You can manually trigger a probe by visiting the /probe endpoint. Use the target parameter for the URL/address to probe and the module parameter for the configuration module defined in blackbox.yml.

• Success Metric: probe_success indicates if the probe succeeded.
• Debug Mode: Adding debug=true to the query parameters returns detailed debug information for that probe.
• Timing Metrics: The exporter returns timing metrics. To calculate the ratio of remaining probe timeout, use the query: probe_duration_seconds / probe_timeout_seconds.
• Exporter Metrics: Internal metrics for the exporter itself are available at /metrics.

You can build the software locally using make or build a Docker image after a successful local build.

Local Build:

make

Docker Build:

docker build -t blackbox_exporter .

Download the appropriate binary from the GitHub releases page and execute it with any required flags.

./blackbox_exporter <flags>

Each module must specify a prober (the protocol to use) and can optionally specify a timeout. You must provide exactly one specific probe configuration (e.g., http, tcp, dns, icmp, grpc, unix, or websocket).

Supported Probers: http, tcp, dns, icmp, grpc, unix, websocket.

The Blackbox exporter configuration is written in YAML. The top-level structure defines modules, where each module contains a prober and specific probe settings.

Common Placeholders:

• <boolean>: true or false
• <int>: integer
• <duration>: e.g., 10s, 500ms
• <string>: regular string
• <regex>: regular expression
• <filename>: path in the current working directory
• <secret>: sensitive string

The tcp probe allows testing raw TCP connections.

Key Options:

• preferred_ip_protocol: ip4 or ip6 (defaults to ip6).
• ip_protocol_fallback: If true, allows falling back to the other protocol.
• source_ip_address: The source IP to use.
• tls: Boolean to indicate if TLS is used.
• tls_config: Configuration for the TLS protocol.
• query_response: A list of expected interactions. Supports expect (regex), expect_bytes (exact match), send (data to transmit), and labels (to export metadata).

The tls_config object is used across multiple probes (HTTP, TCP, DNS, gRPC, etc.) to define how TLS connections are handled.

Key Options:

• insecure_skip_verify: Disable target certificate validation.
• ca_file: Path to the CA certificate.
• cert_file: Path to the client certificate.
• key_file: Path to the client key.
• server_name: Hostname used to verify the target.
• min_version: Minimum TLS version (e.g., TLS12).
• max_version: Maximum TLS version (e.g., TLS13).

The dns probe tests DNS resolution.

Key Options:

• query_name: The domain name to query.
• query_type: DNS record type (e.g., A, AAAA, MX). Defaults to ANY.
• transport_protocol: udp or tcp (defaults to udp).
• dns_over_tls: Boolean to enable DoT (requires tcp).
• valid_rcodes: List of accepted response codes (defaults to NOERROR).
• validate_answer_rrs: Options to fail if answer RRs match/don't match specific regexes.
• validate_authority_rrs: Options to fail if authority RRs match/don't match specific regexes.
• validate_additional_rrs: Options to fail if additional RRs match/don't match specific regexes.

The oauth2 configuration uses the client credentials grant type. Note: This is currently experimental.

Key Options:

• client_id: The OAuth2 client ID.
• client_secret: The client secret, or client_secret_file for a path to the secret.
• token_url: The URL to fetch the token from.
• scopes: List of requested scopes.
• endpoint_params: Key-value pairs to append to the token URL.