mirror of https://github.com/getdnsapi/getdns.git
Merge a1aa77a322 into f8c95b4f15
This commit is contained in:
Petr Menšík
GitHub
commit
91b1c4e13c
|
|
@ -158,6 +158,7 @@ option(BUILD_DOXYGEN "Build source documentation." OFF)
|
||||||
option(BUILD_EXAMPLES "Compile the example programs." OFF)
|
option(BUILD_EXAMPLES "Compile the example programs." OFF)
|
||||||
option(BUILD_GETDNS_QUERY "Compile and install the getdns_query tool." ON)
|
option(BUILD_GETDNS_QUERY "Compile and install the getdns_query tool." ON)
|
||||||
option(BUILD_GETDNS_SERVER_MON "Compile and install the getdns_server_mon tool." ON)
|
option(BUILD_GETDNS_SERVER_MON "Compile and install the getdns_server_mon tool." ON)
|
||||||
|
option(BUILD_TOOL_MANUALS "Build manuals for tools." OFF)
|
||||||
option(BUILD_STUBBY "Compile and install stubby, the (stub) resolver daemon." OFF)
|
option(BUILD_STUBBY "Compile and install stubby, the (stub) resolver daemon." OFF)
|
||||||
|
|
||||||
option(BUILD_LIBEV "Build libev support library if available." ON)
|
option(BUILD_LIBEV "Build libev support library if available." ON)
|
||||||
|
|
@ -1178,3 +1179,40 @@ if (BUILD_DOXYGEN)
|
||||||
COMMENT "Generating Doxygen docs.")
|
COMMENT "Generating Doxygen docs.")
|
||||||
add_custom_target(doc ALL DEPENDS doc/html/index.html)
|
add_custom_target(doc ALL DEPENDS doc/html/index.html)
|
||||||
endif ()
|
endif ()
|
||||||
|
|
||||||
|
if (BUILD_TOOL_MANUALS)
|
||||||
|
find_program(ASCIIDOCTOR asciidoctor)
|
||||||
|
if (NOT ASCIIDOCTOR)
|
||||||
|
message(SEND_ERROR "Failed to find asciidoctor")
|
||||||
|
else()
|
||||||
|
set(ASCIIDOCTOR_MAN ${ASCIIDOCTOR} -d manpage -b manpage -D ${CMAKE_CURRENT_BINARY_DIR}/man1)
|
||||||
|
set(ASCIIDOCTOR_HTML ${ASCIIDOCTOR} -D ${CMAKE_CURRENT_BINARY_DIR}/doc/html)
|
||||||
|
set(SRC_TOOLS ${CMAKE_CURRENT_SOURCE_DIR}/src/tools)
|
||||||
|
if (BUILD_GETDNS_QUERY)
|
||||||
|
add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/man1/getdns_query.1
|
||||||
|
COMMAND ${ASCIIDOCTOR_MAN} ${SRC_TOOLS}/getdns_query.adoc
|
||||||
|
-o ${CMAKE_CURRENT_BINARY_DIR}/man1/getdns_query.1
|
||||||
|
VERBATIM DEPENDS ${SRC_TOOLS}/getdns_query.adoc)
|
||||||
|
endif()
|
||||||
|
if (BUILD_GETDNS_SERVER_MON)
|
||||||
|
add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/man1/getdns_server_mon.1
|
||||||
|
COMMAND ${ASCIIDOCTOR_MAN} ${SRC_TOOLS}/getdns_server_mon.adoc
|
||||||
|
-o ${CMAKE_CURRENT_BINARY_DIR}/man1/getdns_server_mon.1
|
||||||
|
VERBATIM DEPENDS ${SRC_TOOLS}/getdns_server_mon.adoc)
|
||||||
|
add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doc/html/getdns_server_mon.html
|
||||||
|
COMMAND ${ASCIIDOCTOR_HTML} ${SRC_TOOLS}/getdns_server_mon.adoc
|
||||||
|
-o ${CMAKE_CURRENT_BINARY_DIR}/doc/html/getdns_server_mon.html
|
||||||
|
VERBATIM DEPENDS ${SRC_TOOLS}/getdns_server_mon.adoc)
|
||||||
|
endif()
|
||||||
|
add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doc/html/tools.html
|
||||||
|
COMMAND ${ASCIIDOCTOR_HTML} ${SRC_TOOLS}/README.adoc
|
||||||
|
-o ${CMAKE_CURRENT_BINARY_DIR}/doc/html/tools.html
|
||||||
|
VERBATIM DEPENDS ${SRC_TOOLS}/README.adoc)
|
||||||
|
add_custom_target(man1 ALL DEPENDS
|
||||||
|
${CMAKE_CURRENT_BINARY_DIR}/man1/getdns_server_mon.1
|
||||||
|
${CMAKE_CURRENT_BINARY_DIR}/man1/getdns_query.1
|
||||||
|
${CMAKE_CURRENT_BINARY_DIR}/doc/html/tools.html)
|
||||||
|
|
||||||
|
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/man1 DESTINATION ${CMAKE_INSTALL_MANDIR})
|
||||||
|
endif()
|
||||||
|
endif()
|
||||||
|
|
|
||||||
|
|
@ -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