mirror of https://github.com/getdnsapi/getdns.git
Move documentation to separate files
Prepare it to look like manual page. Allow generating decent manual pages from them by asciidoctor, while also having it in similar way inside README.adoc
This commit is contained in:
Petr Menšík
parent
f8c95b4f15
commit
35f8bc9cf8
|
|
@ -2,262 +2,9 @@
|
||||||
|
|
||||||
This directory contains some tools based on `getdns`.
|
This directory contains some tools based on `getdns`.
|
||||||
|
|
||||||
* `getdns_query` - a command line wrapper for `getdns`.
|
* <<_getdns_query1>> - a command line wrapper for `getdns`.
|
||||||
* `getdns_server_mon` - test DNS server function and capabilities.
|
* <<_getdns_server_mon1>> - test DNS server function and capabilities.
|
||||||
|
|
||||||
== `getdns_query`
|
include::getdns_query.adoc[leveloffset=+1]
|
||||||
|
include::getdns_server_mon.adoc[leveloffset=+1]
|
||||||
|
|
||||||
`getdns_query` is a command line wrapper for `getdns` exposing the
|
|
||||||
features of this implementation (both in the official API and the
|
|
||||||
additional API functions).
|
|
||||||
|
|
||||||
=== Usage
|
|
||||||
|
|
||||||
----
|
|
||||||
usage: getdns_query [<option> ...] \
|
|
||||||
[@<upstream> ...] [+<extension> ...] ['{ <settings> }'] [<name>] [<type>]
|
|
||||||
|
|
||||||
default mode: recursive, synchronous resolution of NS record
|
|
||||||
using UDP with TCP fallback
|
|
||||||
|
|
||||||
upstreams: @<ip>[%<scope_id>][@<port>][#<tls port>][~<tls name>][^<tsig spec>]
|
|
||||||
<ip>@<port> may be given as <IPv4>:<port>
|
|
||||||
or '['<IPv6>[%<scope_id>]']':<port> too
|
|
||||||
|
|
||||||
tsig spec: [<algorithm>:]<name>:<secret in Base64>
|
|
||||||
|
|
||||||
extensions:
|
|
||||||
+add_warning_for_bad_dns
|
|
||||||
+dnssec_return_status
|
|
||||||
+dnssec_return_only_secure
|
|
||||||
+dnssec_return_all_statuses
|
|
||||||
+dnssec_return_validation_chain
|
|
||||||
+dnssec_return_full_validation_chain
|
|
||||||
+dnssec_roadblock_avoidance
|
|
||||||
+edns_cookies
|
|
||||||
+return_both_v4_and_v6
|
|
||||||
+return_call_reporting
|
|
||||||
+sit=<cookie> Send along cookie OPT with value <cookie>
|
|
||||||
+specify_class=<class>
|
|
||||||
+0 Clear all extensions
|
|
||||||
|
|
||||||
settings in json dict format (like outputted by -i option).
|
|
||||||
|
|
||||||
options:
|
|
||||||
-a Perform asynchronous resolution (default = synchronous)
|
|
||||||
-A address lookup (<type> is ignored)
|
|
||||||
-B Batch mode. Schedule all messages before processing responses.
|
|
||||||
-b <bufsize> Set edns0 max_udp_payload size
|
|
||||||
-c Send Client Subnet privacy request
|
|
||||||
-C <filename>
|
|
||||||
Read settings from config file <filename>
|
|
||||||
The getdns context will be configured with these settings
|
|
||||||
The file must be in YAML format (with extension of '.yml')
|
|
||||||
or JSON dict format (with extension '.conf')
|
|
||||||
-D Set edns0 do bit
|
|
||||||
-d clear edns0 do bit
|
|
||||||
-e <idle_timeout> Set idle timeout in milliseconds
|
|
||||||
-F <filename> read the queries from the specified file
|
|
||||||
-f <filename> Read DNSSEC trust anchors from <filename>
|
|
||||||
-G general lookup
|
|
||||||
-H hostname lookup. (<name> must be an IP address; <type> is ignored)
|
|
||||||
-h Print this help
|
|
||||||
-i Print api information
|
|
||||||
-I Interactive mode (> 1 queries on same context)
|
|
||||||
-j Output json response dict
|
|
||||||
-J Pretty print json response dict
|
|
||||||
-k Print root trust anchors
|
|
||||||
-K <pin> Pin a public key for TLS connections (can repeat)
|
|
||||||
(should look like 'pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g="')
|
|
||||||
-m Set TLS authentication mode to REQUIRED
|
|
||||||
-n Set TLS authentication mode to NONE (default)
|
|
||||||
-o <filename> Set resolver configuration file path
|
|
||||||
(default = /etc/resolv.conf)
|
|
||||||
-p Pretty print response dict (default)
|
|
||||||
-P <blocksize> Pad TLS queries to a multiple of blocksize
|
|
||||||
(special values: 0: no padding, 1: sensible default policy)
|
|
||||||
-q Quiet mode - don't print response
|
|
||||||
-r Set recursing resolution type
|
|
||||||
-R <filename> Read root hints from <filename>
|
|
||||||
-s Set stub resolution type(default = recursing)
|
|
||||||
-S service lookup (<type> is ignored)
|
|
||||||
-t <timeout> Set timeout in milliseconds
|
|
||||||
-v Print getdns release version
|
|
||||||
-V Increase verbosity (may be used more than once)
|
|
||||||
-x Do not follow redirects
|
|
||||||
-X Follow redirects (default)
|
|
||||||
-0 Append suffix to single label first (default)
|
|
||||||
-W Append suffix always
|
|
||||||
-1 Append suffix only to single label after failure
|
|
||||||
-M Append suffix only to multi label name after failure
|
|
||||||
-N Never append a suffix
|
|
||||||
-Z <suffixes> Set suffixes with the given comma separated list
|
|
||||||
-T Set transport to TCP only
|
|
||||||
-O Set transport to TCP only keep connections open
|
|
||||||
-L Set transport to TLS only keep connections open
|
|
||||||
-E Set transport to TLS with TCP fallback only keep connections open
|
|
||||||
-u Set transport to UDP with TCP fallback (default)
|
|
||||||
-U Set transport to UDP only
|
|
||||||
-l <transports> Set transport list. List can contain 1 of each of the characters
|
|
||||||
U T L for UDP, TCP or TLS e.g 'UT' or 'LTU'
|
|
||||||
-z <listen address>
|
|
||||||
Listen for DNS requests on the given IP address
|
|
||||||
<listen address> is in the same format as upstreams.
|
|
||||||
This option can be given more than once.
|
|
||||||
----
|
|
||||||
|
|
||||||
== `getdns_server_mon`
|
|
||||||
|
|
||||||
`getdns_server_mon` is a collection of DNS server tests. The tests examine
|
|
||||||
both server function and server capability.
|
|
||||||
|
|
||||||
`get_server_mon` can optionally be run in Monitoring mode. In this mode,
|
|
||||||
the tool output is modified to enable it to function as a plugin for
|
|
||||||
popular monitoring systems such as https://www.icinga.org[Icinga],
|
|
||||||
http://naemon.github.io/[Naemon], http://www.nagios.org[Nagios],
|
|
||||||
http://www.shinken-monitoring.org/[Shinken], http://sensuapp.org/[Sensu]
|
|
||||||
and others.
|
|
||||||
|
|
||||||
=== Usage
|
|
||||||
|
|
||||||
----
|
|
||||||
Usage: getdns_server_mon [-M] [-E] [(-u|-t|-T)] [-S] [-K <spki-pin>]
|
|
||||||
[-v [-v [-v]]] [-V] @upstream testname [<test args>]
|
|
||||||
-M|--monitoring Make output suitable for monitoring tools
|
|
||||||
-E|--fail-on-dns-errors Fail on DNS error (NXDOMAIN, SERVFAIL)
|
|
||||||
-u|--udp Use UDP transport
|
|
||||||
-t|--tcp Use TCP transport
|
|
||||||
-T|--tls Use TLS transport
|
|
||||||
-S|--strict-usage-profile Use strict profile (require authentication)
|
|
||||||
-K|--spki-pin <spki-pin> SPKI pin for TLS connections (can repeat)
|
|
||||||
-v|--verbose Increase output verbosity
|
|
||||||
-D|--debug Enable debugging output
|
|
||||||
-V|--version Report GetDNS version
|
|
||||||
|
|
||||||
spki-pin: Should look like 'pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g="'
|
|
||||||
|
|
||||||
upstream: @<ip>[%<scope_id][@<port>][#<tls_port>][~tls name>][^<tsig spec>]
|
|
||||||
<ip>@<port> may be given as <IPv4>:<port> or
|
|
||||||
'['<IPv6>[%<scope_id>]']':<port>
|
|
||||||
|
|
||||||
tsig spec: [<algorithm>:]<name>:<secret in Base64>
|
|
||||||
|
|
||||||
Tests:
|
|
||||||
lookup [<name> [<type>]] Check lookup on server
|
|
||||||
keepalive <timeout-ms> [<name> [<type>]]
|
|
||||||
Check server support for EDNS0 keepalive in
|
|
||||||
TCP or TLS connections
|
|
||||||
Timeout of 0 is off.
|
|
||||||
OOOR Check whether server delivers responses out of
|
|
||||||
query order on a TCP or TLS connection
|
|
||||||
qname-min Check whether server supports QNAME minimisation
|
|
||||||
rtt [warn-ms,crit-ms] [<name> [<type>]]
|
|
||||||
Check if server round trip time exceeds
|
|
||||||
thresholds (default 250,500)
|
|
||||||
|
|
||||||
dnssec-validate Check whether server does DNSSEC validation
|
|
||||||
|
|
||||||
tls-auth [<name> [<type>]] Check authentication of TLS server
|
|
||||||
If both a SPKI pin and authentication name are
|
|
||||||
provided, both must authenticate for this test
|
|
||||||
to pass.
|
|
||||||
tls-cert-valid [warn-days,crit-days] [<name> [type]]
|
|
||||||
Check server certificate validity, report
|
|
||||||
warning or critical if days to expiry at
|
|
||||||
or below thresholds (default 14,7).
|
|
||||||
tls-padding <blocksize> [<name> [<type>]]
|
|
||||||
Check server support for EDNS0 padding in TLS
|
|
||||||
Special blocksize values are 0 = off,
|
|
||||||
1 = sensible default.
|
|
||||||
tls-1.3 Check whether server supports TLS 1.3
|
|
||||||
|
|
||||||
Enabling monitoring mode ensures output messages and exit statuses conform
|
|
||||||
to the requirements of monitoring plugins (www.monitoring-plugins.org).
|
|
||||||
----
|
|
||||||
|
|
||||||
Note that the server must currently be specified with an IPv4 or an IPv6 address.
|
|
||||||
|
|
||||||
=== The tests
|
|
||||||
|
|
||||||
Several tests take optional name and RR type parameters. If these are not supplied,
|
|
||||||
default values of `getdnsapi.net` and `AAAA` are used. If the lookup returns no
|
|
||||||
answering records, `getdns_server_mon` reports a status of WARNING.
|
|
||||||
|
|
||||||
[cols="1,3a,1" options="header"]
|
|
||||||
|===
|
|
||||||
| Test name | Test description | Default connection type
|
|
||||||
| `lookup`
|
|
||||||
| Check a name lookup succeeds.
|
|
||||||
| UDP with TCP fallback
|
|
||||||
|
|
||||||
| `keepalive`
|
|
||||||
| See if the server supports EDNS0 keepalive in TCP or TLS
|
|
||||||
connections. Specify a non-zero timeout to set the keepalive timeout
|
|
||||||
in milliseconds, or 0 to disable it.
|
|
||||||
| TCP
|
|
||||||
|
|
||||||
| `OOOR`
|
|
||||||
| Out Of Order Responses. See if the server will send responses to
|
|
||||||
multiple queries in a single TCP or TLS connection in a different
|
|
||||||
order to the order of queries.
|
|
||||||
|
|
||||||
This test is currently experimental, and may give false negative results.
|
|
||||||
| TCP
|
|
||||||
|
|
||||||
| `qname-min`
|
|
||||||
| Does the server support QNAME minimisation?
|
|
||||||
| UDP with TCP fallback
|
|
||||||
|
|
||||||
|`rtt`
|
|
||||||
| Check a lookup round trip time exceeds warning and critical levels in milliseconds.
|
|
||||||
If thresholds are not specified, defaults of 500ms (critical) and 250ms (warning) are used.
|
|
||||||
| UDP with TCP fallback
|
|
||||||
|
|
||||||
|`dnssec-validate`
|
|
||||||
| See if the server is doing DNSSEC validation.
|
|
||||||
| UDP with TCP fallback
|
|
||||||
|
|
||||||
|`tls-auth`
|
|
||||||
| Check if a TLS lookup authenticates successfully. You must specify
|
|
||||||
either a SPKI pin, an authentication name, or both. If you supply
|
|
||||||
both, both must authenticate for the test to succeed.
|
|
||||||
| TLS
|
|
||||||
|
|
||||||
|`tls-cert-valid`
|
|
||||||
| Check the server certificate against warning and critical days to
|
|
||||||
expiry. If thresholds are not specified, defaults of 7 days
|
|
||||||
(critical) and 14 days (warning) are used.
|
|
||||||
| TLS
|
|
||||||
|
|
||||||
|`tls-padding`
|
|
||||||
| Does the server support EDNS0 padding? Specify a non-zero blocksize to set
|
|
||||||
the padding. A padding size of 1 specifies padding of a sensible default size.
|
|
||||||
| TLS
|
|
||||||
|
|
||||||
|`tls-1.3`
|
|
||||||
| Does the server support TLS 1.3? To enable this test,
|
|
||||||
`getdns_server_mon` must be compiled with OpenSSL v1.1.1 or later.
|
|
||||||
|
|
||||||
This test is currently experimental, and may give false negative results.
|
|
||||||
| TLS
|
|
||||||
|===
|
|
||||||
=== Exit status
|
|
||||||
|
|
||||||
[cols="^1,^1,3a" options="header"]
|
|
||||||
|===
|
|
||||||
| Numeric value | Service Status | Status Description
|
|
||||||
| 0
|
|
||||||
| OK
|
|
||||||
| The service was functioning properly
|
|
||||||
|
|
||||||
| 1
|
|
||||||
| WARNING
|
|
||||||
| The service fell below a warning threshold
|
|
||||||
|
|
||||||
|2
|
|
||||||
| CRITICAL
|
|
||||||
| The service was not working or fell below a critical threshold
|
|
||||||
|
|
||||||
|3
|
|
||||||
| UNKNOWN | Invalid arguments or an internal low-level failure
|
|
||||||
|===
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,114 @@
|
||||||
|
= getdns_query(1)
|
||||||
|
:doctype: manpage
|
||||||
|
:manmanual: getdns
|
||||||
|
|
||||||
|
== Name
|
||||||
|
|
||||||
|
getdns_query - a command line wrapper for _getdns_ library
|
||||||
|
|
||||||
|
== Synopsis
|
||||||
|
|
||||||
|
*getdns_query* [<option> ...] \
|
||||||
|
[@<upstream> ...] [+<extension> ...] ['{ <settings> }'] [<name>] [<type>]
|
||||||
|
|
||||||
|
default mode: recursive, synchronous resolution of NS record
|
||||||
|
using UDP with TCP fallback
|
||||||
|
|
||||||
|
upstreams: @<ip>[%<scope_id>][@<port>][#<tls port>][~<tls name>][^<tsig spec>]
|
||||||
|
<ip>@<port> may be given as <IPv4>:<port>
|
||||||
|
or '['<IPv6>[%<scope_id>]']':<port> too
|
||||||
|
|
||||||
|
tsig spec: [<algorithm>:]<name>:<secret in Base64>
|
||||||
|
|
||||||
|
== Description
|
||||||
|
|
||||||
|
`getdns_query` is a command line wrapper for `getdns` exposing the
|
||||||
|
features of this implementation (both in the official API and the
|
||||||
|
additional API functions).
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
== Extensions
|
||||||
|
|
||||||
|
// TODO: Get descriptions for each extension and use ::
|
||||||
|
----
|
||||||
|
+add_warning_for_bad_dns Warn on bad DNS
|
||||||
|
+dnssec_return_status Include dnssec_status
|
||||||
|
+dnssec_return_only_secure
|
||||||
|
+dnssec_return_all_statuses
|
||||||
|
+dnssec_return_validation_chain
|
||||||
|
+dnssec_return_full_validation_chain
|
||||||
|
+dnssec_roadblock_avoidance
|
||||||
|
+edns_cookies
|
||||||
|
+return_both_v4_and_v6
|
||||||
|
+return_call_reporting
|
||||||
|
+sit=<cookie> Send along cookie OPT with value <cookie>
|
||||||
|
+specify_class=<class>
|
||||||
|
+0
|
||||||
|
Clear all extensions
|
||||||
|
----
|
||||||
|
|
||||||
|
settings in json dict format (like outputted by -i option).
|
||||||
|
|
||||||
|
== Options
|
||||||
|
|
||||||
|
*-a*:: Perform asynchronous resolution (default = synchronous)
|
||||||
|
*-A*:: address lookup (<type> is ignored)
|
||||||
|
*-B*:: Batch mode. Schedule all messages before processing responses.
|
||||||
|
*-b <bufsize>*:: Set edns0 max_udp_payload size
|
||||||
|
*-c*:: Send Client Subnet privacy request
|
||||||
|
*-C <filename>*::
|
||||||
|
Read settings from config file <filename>
|
||||||
|
The getdns context will be configured with these settings
|
||||||
|
The file must be in YAML format (with extension of '.yml')
|
||||||
|
or JSON dict format (with extension '.conf')
|
||||||
|
*-D*:: Set edns0 do bit
|
||||||
|
*-d*:: clear edns0 do bit
|
||||||
|
*-e <idle_timeout>*:: Set idle timeout in milliseconds
|
||||||
|
*-F <filename>*:: read the queries from the specified file
|
||||||
|
*-f <filename>*:: Read DNSSEC trust anchors from <filename>
|
||||||
|
*-G*:: general lookup
|
||||||
|
*-H*:: hostname lookup. (<name> must be an IP address; <type> is ignored)
|
||||||
|
*-h*:: Print this help
|
||||||
|
*-i*:: Print api information
|
||||||
|
*-I*:: Interactive mode (> 1 queries on same context)
|
||||||
|
*-j*:: Output json response dict
|
||||||
|
*-J*:: Pretty print json response dict
|
||||||
|
*-k*:: Print root trust anchors
|
||||||
|
*-K <pin>*:: Pin a public key for TLS connections (can repeat)
|
||||||
|
(should look like 'pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g="')
|
||||||
|
*-m*:: Set TLS authentication mode to REQUIRED
|
||||||
|
*-n*:: Set TLS authentication mode to NONE (default)
|
||||||
|
*-o <filename>*:: Set resolver configuration file path
|
||||||
|
(default = /etc/resolv.conf)
|
||||||
|
*-p*:: Pretty print response dict (default)
|
||||||
|
*-P <blocksize>*:: Pad TLS queries to a multiple of blocksize
|
||||||
|
(special values: 0: no padding, 1: sensible default policy)
|
||||||
|
*-q*:: Quiet mode - don't print response
|
||||||
|
*-r*:: Set recursing resolution type
|
||||||
|
*-R <filename>*:: Read root hints from <filename>
|
||||||
|
*-s*:: Set stub resolution type(default = recursing)
|
||||||
|
*-S*:: service lookup (<type> is ignored)
|
||||||
|
*-t <timeout>*:: Set timeout in milliseconds
|
||||||
|
*-v*:: Print getdns release version
|
||||||
|
*-V*:: Increase verbosity (may be used more than once)
|
||||||
|
*-x*:: Do not follow redirects
|
||||||
|
*-X*:: Follow redirects (default)
|
||||||
|
*-0*:: Append suffix to single label first (default)
|
||||||
|
*-W*:: Append suffix always
|
||||||
|
*-1*:: Append suffix only to single label after failure
|
||||||
|
*-M*:: Append suffix only to multi label name after failure
|
||||||
|
*-N*:: Never append a suffix
|
||||||
|
*-Z <suffixes>*:: Set suffixes with the given comma separated list
|
||||||
|
*-T*:: Set transport to TCP only
|
||||||
|
*-O*:: Set transport to TCP only keep connections open
|
||||||
|
*-L*:: Set transport to TLS only keep connections open
|
||||||
|
*-E*:: Set transport to TLS with TCP fallback only keep connections open
|
||||||
|
*-u*:: Set transport to UDP with TCP fallback (default)
|
||||||
|
*-U*:: Set transport to UDP only
|
||||||
|
*-l <transports>*:: Set transport list. List can contain 1 of each of the characters
|
||||||
|
U T L for UDP, TCP or TLS e.g 'UT' or 'LTU'
|
||||||
|
*-z <listen address>*::
|
||||||
|
Listen for DNS requests on the given IP address
|
||||||
|
<listen address> is in the same format as upstreams.
|
||||||
|
This option can be given more than once.
|
||||||
|
|
@ -0,0 +1,163 @@
|
||||||
|
= getdns_server_mon(1)
|
||||||
|
:doctype: manpage
|
||||||
|
:manmanual: getdns
|
||||||
|
|
||||||
|
== Name
|
||||||
|
|
||||||
|
getdns_server_mon - a collection of DNS server tests
|
||||||
|
|
||||||
|
== Synopsis
|
||||||
|
|
||||||
|
*getdns_server_mon* [-M] [-E] [(-u|-t|-T)] [-S] [-K <spki-pin>]
|
||||||
|
[-v [-v [-v]]] [-V] @upstream testname [<test args>]
|
||||||
|
|
||||||
|
spki-pin: Should look like 'pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g="'
|
||||||
|
|
||||||
|
upstream: @<ip>[%<scope_id][@<port>][#<tls_port>][~tls name>][^<tsig spec>]
|
||||||
|
<ip>@<port> may be given as <IPv4>:<port> or
|
||||||
|
'['<IPv6>[%<scope_id>]']':<port>
|
||||||
|
|
||||||
|
tsig spec: [<algorithm>:]<name>:<secret in Base64>
|
||||||
|
|
||||||
|
== Description
|
||||||
|
|
||||||
|
The tests examine both server function and server capability.
|
||||||
|
|
||||||
|
`get_server_mon` can optionally be run in Monitoring mode. In this mode,
|
||||||
|
the tool output is modified to enable it to function as a plugin for
|
||||||
|
popular monitoring systems such as https://www.icinga.org[Icinga],
|
||||||
|
http://naemon.github.io/[Naemon], http://www.nagios.org[Nagios],
|
||||||
|
http://www.shinken-monitoring.org/[Shinken], http://sensuapp.org/[Sensu]
|
||||||
|
and others.
|
||||||
|
|
||||||
|
== Options
|
||||||
|
|
||||||
|
-M|--monitoring:: Make output suitable for monitoring tools
|
||||||
|
-E|--fail-on-dns-errors:: Fail on DNS error (NXDOMAIN, SERVFAIL)
|
||||||
|
-u|--udp:: Use UDP transport
|
||||||
|
-t|--tcp:: Use TCP transport
|
||||||
|
-T|--tls:: Use TLS transport
|
||||||
|
-S|--strict-usage-profile:: Use strict profile (require authentication)
|
||||||
|
-K|--spki-pin <spki-pin>:: SPKI pin for TLS connections (can repeat)
|
||||||
|
-v|--verbose:: Increase output verbosity
|
||||||
|
-D|--debug:: Enable debugging output
|
||||||
|
-V|--version:: Report GetDNS version
|
||||||
|
|
||||||
|
=== Test parameters
|
||||||
|
lookup [<name> [<type>]]:: Check lookup on server
|
||||||
|
keepalive <timeout-ms> [<name> [<type>]]::
|
||||||
|
Check server support for EDNS0 keepalive in
|
||||||
|
TCP or TLS connections
|
||||||
|
Timeout of 0 is off.
|
||||||
|
OOOR:: Check whether server delivers responses out of
|
||||||
|
query order on a TCP or TLS connection
|
||||||
|
qname-min:: Check whether server supports QNAME minimisation
|
||||||
|
rtt [warn-ms,crit-ms] [<name> [<type>]]::
|
||||||
|
Check if server round trip time exceeds
|
||||||
|
thresholds (default 250,500)
|
||||||
|
|
||||||
|
dnssec-validate:: Check whether server does DNSSEC validation
|
||||||
|
|
||||||
|
tls-auth [<name> [<type>]]:: Check authentication of TLS server
|
||||||
|
If both a SPKI pin and authentication name are
|
||||||
|
provided, both must authenticate for this test
|
||||||
|
to pass.
|
||||||
|
tls-cert-valid [warn-days,crit-days] [<name> [type]]::
|
||||||
|
Check server certificate validity, report
|
||||||
|
warning or critical if days to expiry at
|
||||||
|
or below thresholds (default 14,7).
|
||||||
|
tls-padding <blocksize> [<name> [<type>]]::
|
||||||
|
Check server support for EDNS0 padding in TLS
|
||||||
|
Special blocksize values are 0 = off,
|
||||||
|
1 = sensible default.
|
||||||
|
tls-1.3:: Check whether server supports TLS 1.3
|
||||||
|
|
||||||
|
Enabling monitoring mode ensures output messages and exit statuses conform
|
||||||
|
to the requirements of monitoring plugins (www.monitoring-plugins.org).
|
||||||
|
|
||||||
|
Note that the server must currently be specified with an IPv4 or an IPv6 address.
|
||||||
|
|
||||||
|
=== The tests
|
||||||
|
|
||||||
|
Several tests take optional name and RR type parameters. If these are not supplied,
|
||||||
|
default values of `getdnsapi.net` and `AAAA` are used. If the lookup returns no
|
||||||
|
answering records, `getdns_server_mon` reports a status of WARNING.
|
||||||
|
|
||||||
|
[cols="1,3a,1" options="header"]
|
||||||
|
|===
|
||||||
|
| Test name | Test description | Default connection type
|
||||||
|
| `lookup`
|
||||||
|
| Check a name lookup succeeds.
|
||||||
|
| UDP with TCP fallback
|
||||||
|
|
||||||
|
| `keepalive`
|
||||||
|
| See if the server supports EDNS0 keepalive in TCP or TLS
|
||||||
|
connections. Specify a non-zero timeout to set the keepalive timeout
|
||||||
|
in milliseconds, or 0 to disable it.
|
||||||
|
| TCP
|
||||||
|
|
||||||
|
| `OOOR`
|
||||||
|
| Out Of Order Responses. See if the server will send responses to
|
||||||
|
multiple queries in a single TCP or TLS connection in a different
|
||||||
|
order to the order of queries.
|
||||||
|
|
||||||
|
This test is currently experimental, and may give false negative results.
|
||||||
|
| TCP
|
||||||
|
|
||||||
|
| `qname-min`
|
||||||
|
| Does the server support QNAME minimisation?
|
||||||
|
| UDP with TCP fallback
|
||||||
|
|
||||||
|
|`rtt`
|
||||||
|
| Check a lookup round trip time exceeds warning and critical levels in milliseconds.
|
||||||
|
If thresholds are not specified, defaults of 500ms (critical) and 250ms (warning) are used.
|
||||||
|
| UDP with TCP fallback
|
||||||
|
|
||||||
|
|`dnssec-validate`
|
||||||
|
| See if the server is doing DNSSEC validation.
|
||||||
|
| UDP with TCP fallback
|
||||||
|
|
||||||
|
|`tls-auth`
|
||||||
|
| Check if a TLS lookup authenticates successfully. You must specify
|
||||||
|
either a SPKI pin, an authentication name, or both. If you supply
|
||||||
|
both, both must authenticate for the test to succeed.
|
||||||
|
| TLS
|
||||||
|
|
||||||
|
|`tls-cert-valid`
|
||||||
|
| Check the server certificate against warning and critical days to
|
||||||
|
expiry. If thresholds are not specified, defaults of 7 days
|
||||||
|
(critical) and 14 days (warning) are used.
|
||||||
|
| TLS
|
||||||
|
|
||||||
|
|`tls-padding`
|
||||||
|
| Does the server support EDNS0 padding? Specify a non-zero blocksize to set
|
||||||
|
the padding. A padding size of 1 specifies padding of a sensible default size.
|
||||||
|
| TLS
|
||||||
|
|
||||||
|
|`tls-1.3`
|
||||||
|
| Does the server support TLS 1.3? To enable this test,
|
||||||
|
`getdns_server_mon` must be compiled with OpenSSL v1.1.1 or later.
|
||||||
|
|
||||||
|
This test is currently experimental, and may give false negative results.
|
||||||
|
| TLS
|
||||||
|
|===
|
||||||
|
=== Exit status
|
||||||
|
|
||||||
|
[cols="^1,^1,3a" options="header"]
|
||||||
|
|===
|
||||||
|
| Numeric value | Service Status | Status Description
|
||||||
|
| 0
|
||||||
|
| OK
|
||||||
|
| The service was functioning properly
|
||||||
|
|
||||||
|
| 1
|
||||||
|
| WARNING
|
||||||
|
| The service fell below a warning threshold
|
||||||
|
|
||||||
|
|2
|
||||||
|
| CRITICAL
|
||||||
|
| The service was not working or fell below a critical threshold
|
||||||
|
|
||||||
|
|3
|
||||||
|
| UNKNOWN | Invalid arguments or an internal low-level failure
|
||||||
|
|===
|
||||||
Loading…
Reference in New Issue