updated docs for blackbox exporter (#177)

diff --git a/CONFIGURATION.md b/CONFIGURATION.md
new file mode 100644 (file)
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:
+
+* `<boolean>`: a boolean that can take the values `true` or `false`
+* `<duration>`: a duration matching the regular expression `[0-9]+(ms|[smhdwy])`
+* `<filename>`: a valid path in the current working directory
+* `<string>`: a regular string
+* `<secret>`: a regular string that is a secret, such as a password
+* `<regex>`: 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: <prober_string>
+
+  # How long the probe will wait before giving up.
+  [ timeout: <duration> ]
+
+  # The specific probe configuration - at most one of these should be specified.
+  [ http: <http_probe> ]
+  [ tcp: <tcp_probe> ]
+  [ dns: <dns_probe> ]
+  [ icmp: <icmp_probe> ]
+
+```
+
+### <http_probe>
+```yml
+
+  # Accepted status codes for this probe. Defaults to 2xx.
+  [ valid_status_codes: <string>, ... | default = "2xx" ]
+
+  # The HTTP method the probe will use.
+  [ method: <string> | default = "GET" ]
+
+  # The HTTP headers set for the probe.
+  headers:
+    [ <string>: <string> ... ]
+
+  # Whether or not the probe will follow any redirects.
+  [ no_follow_redirects: <boolean> | default = false ]
+
+  # Probe fails if SSL is present.
+  [ fail_if_ssl: <boolean> | default = false ]
+
+  # Probe fails if SSL is not present.
+  [ fail_if_not_ssl: <boolean> | default = false ]
+
+  # Probe fails if response matches regex.
+  fail_if_matches_regexp:
+    [ - <regex>, ... ]
+
+  # Probe fails if response does not match regex
+  fail_if_not_matches_regexp:
+    [ - <regex>, ... ]
+
+  # Configuration for TLS protocol of HTTP probe.
+  tls_config:
+    [ <tls_config> ]
+
+  # The HTTP basic authentication credentials for the targets.
+  basic_auth:
+    [ username: <string> ]
+    [ password: <secret> ]
+
+  # The bearer token for the targets.
+  [ bearer_token: <secret> ]
+
+  # The bearer token file for the targets.
+  [ bearer_token_file: <filename> ]
+
+  # HTTP proxy server to use to connect to the targets.
+  [ proxy_url: <string> ]
+
+  # The preferred IP protocol of the HTTP probe (ip4, ip6).
+  [ preferred_ip_protocol: <string> | default = "ip6" ]
+
+  # The body of the HTTP request used in probe.
+  body: [ <string> ]
+
+
+```
+
+### <tcp_probe>
+
+```yml
+
+# The preferred IP protocol of the TCP probe (ip4, ip6).
+[ preferred_ip_protocol: <string> | default = "ip6" ]
+
+# The query sent in the TCP probe and the expected associated response.
+query_response:
+  [ - [ [ expect: <string> ], [ send: <string> ] ], ... ]
+
+# Whether or not TLS is used.
+[ tls: <boolean | default = false> ]
+
+# Configuration for TLS protocol of TCP probe.
+tls_config:
+  [ <tls_config> ]
+
+```
+
+### <dns_probe>
+
+```yml
+
+# The preferred IP protocol of the DNS probe (ip4, ip6).
+[ preferred_ip_protocol: <string> | default = "ip6" ]
+
+[ transport_protocol: <string> | default = "udp" ] # udp, tcp
+
+query_name: <string>
+
+[ query_type: <string> | default = "ANY" ]
+
+# List of valid response codes.
+valid_rcodes:
+  [ - <string> ... | default = "NOERROR" ]
+
+validate_answer_rrs:
+
+  fail_if_matches_regexp:
+    [ - <regex>, ... ]
+
+  fail_if_not_matches_regexp:
+    [ - <regex>, ... ]
+
+validate_authority_rrs:
+
+  fail_if_matches_regexp:
+    [ - <regex>, ... ]
+
+  fail_if_not_matches_regexp:
+    [ - <regex>, ... ]
+
+validate_additional_rrs:
+
+  fail_if_matches_regexp:
+    [ - <regex>, ... ]
+
+  fail_if_not_matches_regexp:
+    [ - <regex>, ... ]
+
+```
+
+### <icmp_probe>
+
+```yml
+
+# The preferred IP protocol of the ICMP probe (ip4, ip6).
+[ preferred_ip_protocol: <string> | default = "ip6" ]
+
+```
+
+### <tls_config>
+
+```yml
+
+# Disable target certificate validation.
+[ insecure_skip_verify: <boolean> | default = false ]
+
+# The CA cert to use for the targets.
+[ ca_file: <filename> ]
+
+# The client cert file for the targets.
+[ cert_file: <filename> ]
+
+# The client key file for the targets.
+[ key_file: <filename> ]
+
+# Used to verify the hostname for the targets.
+[ server_name: <string> ]
+
+```

diff --git a/README.md b/README.md
index f11385364e9dfa98fbdf6d7b05313376fce8867b..3e7cbce1b2c36db83d54fc8f30a53bd3699a9863 100644 (file)
--- 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 (file)
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"