From: Conor Broderick Date: Mon, 3 Jul 2017 14:58:18 +0000 (+0100) Subject: updated docs for blackbox exporter (#177) X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=349a5568bd015f1b465a227e7adb036a5268d610;p=blackbox_exporter.git updated docs for blackbox exporter (#177) --- diff --git a/CONFIGURATION.md b/CONFIGURATION.md new file mode 100644 index 0000000..20c665a --- /dev/null +++ b/CONFIGURATION.md @@ -0,0 +1,183 @@ +# Blackbox exporter configuration + +The file is written in [YAML format](http://en.wikipedia.org/wiki/YAML), defined by the scheme described below. +Brackets indicate that a parameter is optional. +For non-list parameters the value is set to the specified default. + +Generic placeholders are defined as follows: + +* ``: a boolean that can take the values `true` or `false` +* ``: a duration matching the regular expression `[0-9]+(ms|[smhdwy])` +* ``: a valid path in the current working directory +* ``: a regular string +* ``: a regular string that is a secret, such as a password +* ``: a regular expression + +The other placeholders are specified separately. + +### Module +```yml + + # The protocol over which the probe will take place (http, tcp, dns, icmp). + prober: + + # How long the probe will wait before giving up. + [ timeout: ] + + # The specific probe configuration - at most one of these should be specified. + [ http: ] + [ tcp: ] + [ dns: ] + [ icmp: ] + +``` + +### +```yml + + # Accepted status codes for this probe. Defaults to 2xx. + [ valid_status_codes: , ... | default = "2xx" ] + + # The HTTP method the probe will use. + [ method: | default = "GET" ] + + # The HTTP headers set for the probe. + headers: + [ : ... ] + + # Whether or not the probe will follow any redirects. + [ no_follow_redirects: | default = false ] + + # Probe fails if SSL is present. + [ fail_if_ssl: | default = false ] + + # Probe fails if SSL is not present. + [ fail_if_not_ssl: | default = false ] + + # Probe fails if response matches regex. + fail_if_matches_regexp: + [ - , ... ] + + # Probe fails if response does not match regex + fail_if_not_matches_regexp: + [ - , ... ] + + # Configuration for TLS protocol of HTTP probe. + tls_config: + [ ] + + # The HTTP basic authentication credentials for the targets. + basic_auth: + [ username: ] + [ password: ] + + # The bearer token for the targets. + [ bearer_token: ] + + # The bearer token file for the targets. + [ bearer_token_file: ] + + # HTTP proxy server to use to connect to the targets. + [ proxy_url: ] + + # The preferred IP protocol of the HTTP probe (ip4, ip6). + [ preferred_ip_protocol: | default = "ip6" ] + + # The body of the HTTP request used in probe. + body: [ ] + + +``` + +### + +```yml + +# The preferred IP protocol of the TCP probe (ip4, ip6). +[ preferred_ip_protocol: | default = "ip6" ] + +# The query sent in the TCP probe and the expected associated response. +query_response: + [ - [ [ expect: ], [ send: ] ], ... ] + +# Whether or not TLS is used. +[ tls: ] + +# Configuration for TLS protocol of TCP probe. +tls_config: + [ ] + +``` + +### + +```yml + +# The preferred IP protocol of the DNS probe (ip4, ip6). +[ preferred_ip_protocol: | default = "ip6" ] + +[ transport_protocol: | default = "udp" ] # udp, tcp + +query_name: + +[ query_type: | default = "ANY" ] + +# List of valid response codes. +valid_rcodes: + [ - ... | default = "NOERROR" ] + +validate_answer_rrs: + + fail_if_matches_regexp: + [ - , ... ] + + fail_if_not_matches_regexp: + [ - , ... ] + +validate_authority_rrs: + + fail_if_matches_regexp: + [ - , ... ] + + fail_if_not_matches_regexp: + [ - , ... ] + +validate_additional_rrs: + + fail_if_matches_regexp: + [ - , ... ] + + fail_if_not_matches_regexp: + [ - , ... ] + +``` + +### + +```yml + +# The preferred IP protocol of the ICMP probe (ip4, ip6). +[ preferred_ip_protocol: | default = "ip6" ] + +``` + +### + +```yml + +# Disable target certificate validation. +[ insecure_skip_verify: | default = false ] + +# The CA cert to use for the targets. +[ ca_file: ] + +# The client cert file for the targets. +[ cert_file: ] + +# The client key file for the targets. +[ key_file: ] + +# Used to verify the hostname for the targets. +[ server_name: ] + +``` diff --git a/README.md b/README.md index f113853..3e7cbce 100644 --- a/README.md +++ b/README.md @@ -24,90 +24,17 @@ will return metrics for a HTTP probe against google.com. The `probe_success` met ## Configuration -A configuration showing all options is below: -```yml -modules: - http_2xx_example: - prober: http - timeout: 5s - http: - valid_status_codes: [] # Defaults to 2xx - method: GET - headers: - Host: vhost.example.com - Accept-Language: en-US - no_follow_redirects: false - fail_if_ssl: false - fail_if_not_ssl: false - fail_if_matches_regexp: - - "Could not connect to database" - fail_if_not_matches_regexp: - - "Download the latest version here" - tls_config: - insecure_skip_verify: false - preferred_ip_protocol: "ip4" # defaults to "ip6" - http_post_2xx: - prober: http - timeout: 5s - http: - method: POST - headers: - Content-Type: application/json - body: '{}' - http_basic_auth_example: - prober: http - timeout: 5s - http: - method: POST - headers: - Host: "login.example.com" - basic_auth: - username: "username" - password: "mysecret" - tcp_connect_example: - prober: tcp - timeout: 5s - irc_banner_example: - prober: tcp - timeout: 5s - tcp: - query_response: - - send: "NICK prober" - - send: "USER prober prober prober :prober" - - expect: "PING :([^ ]+)" - send: "PONG ${1}" - - expect: "^:[^ ]+ 001" - icmp_example: - prober: icmp - timeout: 5s - icmp: - preferred_ip_protocol: "ip4" - dns_udp_example: - prober: dns - timeout: 5s - dns: - query_name: "www.prometheus.io" - query_type: "A" - valid_rcodes: - - NOERROR - validate_answer_rrs: - fail_if_matches_regexp: - - ".*127.0.0.1" - fail_if_not_matches_regexp: - - "www.prometheus.io.\t300\tIN\tA\t127.0.0.1" - validate_authority_rrs: - fail_if_matches_regexp: - - ".*127.0.0.1" - validate_additional_rrs: - fail_if_matches_regexp: - - ".*127.0.0.1" - dns_tcp_example: - prober: dns - dns: - protocol: "tcp" # defaults to "udp" - preferred_ip_protocol: "ip4" # defaults to "ip6" - query_name: "www.prometheus.io" -``` +Blackbox exporter is configured via a configuration file and command-line flags (such as what configuration file to load, what port to listen on, and the logging format and level). + +Blackbox exporter can reload its configuration file at runtime. If the new configuration is not well-formed, the changes will not be applied. +A configuration reload is triggered by sending a `SIGHUP` to the Blackbox exporter process or by sending a HTTP POST request to the `/-/reload` endpoint. + +To view all available command-line flags, run `./blackbox_exporter -h`. + +To specify which configuration file to load, use the `-config.file` flag. +The file is written in [YAML format](https://en.wikipedia.org/wiki/YAML), defined by the scheme described which can be found [here.](https://github.com/prometheus/blackbox_exporter/configuration.md) + +Additionally, an [example configuration](https://github.com/prometheus/blackbox_exporter/example.yml) is also available. HTTP, HTTPS (via the `http` prober), DNS, TCP socket and ICMP (see permissions section) are currently supported. Additional modules can be defined to meet your needs. diff --git a/example.yml b/example.yml new file mode 100644 index 0000000..b2bcc46 --- /dev/null +++ b/example.yml @@ -0,0 +1,81 @@ +modules: + http_2xx_example: + prober: http + timeout: 5s + http: + valid_status_codes: [] # Defaults to 2xx + method: GET + headers: + Host: vhost.example.com + Accept-Language: en-US + no_follow_redirects: false + fail_if_ssl: false + fail_if_not_ssl: false + fail_if_matches_regexp: + - "Could not connect to database" + fail_if_not_matches_regexp: + - "Download the latest version here" + tls_config: + insecure_skip_verify: false + preferred_ip_protocol: "ip4" # defaults to "ip6" + http_post_2xx: + prober: http + timeout: 5s + http: + method: POST + headers: + Content-Type: application/json + body: '{}' + http_basic_auth_example: + prober: http + timeout: 5s + http: + method: POST + headers: + Host: "login.example.com" + basic_auth: + username: "username" + password: "mysecret" + tcp_connect_example: + prober: tcp + timeout: 5s + irc_banner_example: + prober: tcp + timeout: 5s + tcp: + query_response: + - send: "NICK prober" + - send: "USER prober prober prober :prober" + - expect: "PING :([^ ]+)" + send: "PONG ${1}" + - expect: "^:[^ ]+ 001" + icmp_example: + prober: icmp + timeout: 5s + icmp: + preferred_ip_protocol: "ip4" + dns_udp_example: + prober: dns + timeout: 5s + dns: + query_name: "www.prometheus.io" + query_type: "A" + valid_rcodes: + - NOERROR + validate_answer_rrs: + fail_if_matches_regexp: + - ".*127.0.0.1" + fail_if_not_matches_regexp: + - "www.prometheus.io.\t300\tIN\tA\t127.0.0.1" + validate_authority_rrs: + fail_if_matches_regexp: + - ".*127.0.0.1" + validate_additional_rrs: + fail_if_matches_regexp: + - ".*127.0.0.1" + dns_tcp_example: + prober: dns + dns: + protocol: "tcp" # defaults to "udp" + preferred_ip_protocol: "ip4" # defaults to "ip6" + query_name: "www.prometheus.io"