From 35f8bc9cf81191007bd758eceb7f7210599fee9b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Petr=20Men=C5=A1=C3=ADk?= <pemensik@redhat.com>
Date: Tue, 11 Jul 2023 12:53:19 +0200
Subject: [PATCH] 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
---
 src/tools/README.adoc            | 261 +------------------------------
 src/tools/getdns_query.adoc      | 114 ++++++++++++++
 src/tools/getdns_server_mon.adoc | 163 +++++++++++++++++++
 3 files changed, 281 insertions(+), 257 deletions(-)
 create mode 100644 src/tools/getdns_query.adoc
 create mode 100644 src/tools/getdns_server_mon.adoc

diff --git a/src/tools/README.adoc b/src/tools/README.adoc
index 2f2389eb..ff740878 100644
--- a/src/tools/README.adoc
+++ b/src/tools/README.adoc
@@ -2,262 +2,9 @@
 
 This directory contains some tools based on `getdns`.
 
-* `getdns_query` - a command line wrapper for `getdns`.
-* `getdns_server_mon` - test DNS server function and capabilities.
+* <<_getdns_query1>> - a command line wrapper for `getdns`.
+* <<_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
-|===
diff --git a/src/tools/getdns_query.adoc b/src/tools/getdns_query.adoc
new file mode 100644
index 00000000..e4e00d6b
--- /dev/null
+++ b/src/tools/getdns_query.adoc
@@ -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.
diff --git a/src/tools/getdns_server_mon.adoc b/src/tools/getdns_server_mon.adoc
new file mode 100644
index 00000000..215147cc
--- /dev/null
+++ b/src/tools/getdns_server_mon.adoc
@@ -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
+|===