From 064f55bfa226c18dd0479717179fff53dc07c29d Mon Sep 17 00:00:00 2001 From: Sam Therapy Date: Thu, 15 Dec 2022 20:03:29 +0100 Subject: [PATCH] docs(man): overhaul the manpage Make everything alphabetical, make it look more like dig and kdig Signed-off-by: Sam Therapy --- doc/awl.1.scd | 265 ++++++++++++++++++++++++-------------------------- 1 file changed, 129 insertions(+), 136 deletions(-) diff --git a/doc/awl.1.scd b/doc/awl.1.scd index 3035adf..44b73f6 100644 --- a/doc/awl.1.scd +++ b/doc/awl.1.scd @@ -29,14 +29,34 @@ If one cannot be found, *awl* will query the localhost. # OPTIONS -Anything in [brackets] is optional. -Many options are inherited from *dig*(1). +*-4* + Force only IPv4 -*-D*, *--dnssec*, *+dnssec*, *+do* - Enable DNSSEC. This needs to be manually enabled. +*-6* + Force only IPv6 + +*-c*, *--class* _class_ + DNS class to query (eg. IN, CH) + The default is IN. + +*-h* + Show a "short" help message. + +*-p*, *--port* *port* + Sets the port to query. Default ports listed below. + - _53_ for *UDP* and *TCP* + - _853_ for *TLS* and *QUIC* + - _443_ for *HTTPS* + +*-q*, *--query* _domain_ + Explicitly set a domain to query (eg. example.com) + +*-t*, *--qType* _type_ + Explicitly set a DNS type to query (eg. A, AAAA, NS) + The default is A. *-v*[=_int_] - Set verbosity + Set verbosity of output Accepted values are as follows: - _0_: Only log errors. - _1_: Log warnings. *This is the default.* @@ -47,50 +67,122 @@ Many options are inherited from *dig*(1). By default, specifying just *-v* sets the verbosity to 2 (info). +*-x*, *--reverse* + Do a reverse lookup. Sets default *type* to PTR. + *awl* automatically makes an IP or phone number canonical. + *-V* Print the version and exit. -*-h* - Show a "short" help message. +# QUERY OPTIONS -## Query Options +Anything in [brackets] is optional. +Many options are inherited from *dig*(1). -*-4* - Only make query over IPv4 +*--aa*[=_bool_], *+*[no]*aaflag*, *+*[no]*aaonly* + Sets the AA (Authoritative Answer) flag. -*-6* - Only make query over IPv6 +*--ad*[=_bool_], *+*[no]*adflag* + Sets the AD (Authenticated Data) flag. -*-p*, *--port* *port* - Sets the port to query. Default ports listed below. - - _53_ for *UDP* and *TCP* - - _853_ for *TLS* and *QUIC* - - _443_ for *HTTPS* +*--no-additional*, *+*[no]*additional* + Toggle the display of the Additional section. -*-q*, *--query* _domain_ - Domain to query (eg. example.com) +*--no-answer*, *+*[no]*answer* + Toggle the display of the Answer section. -*-c*, *--class* _class_ - DNS class to query (eg. IN, CH) - The default is IN. +*--no-authority*, *+*[no]*authority* + Toggle the display of the Authority section. -*-t*, *--qType* _type_ - DNS type to query (eg. A, AAAA, NS) - The default is A. +*--no-bad-cookie*, *+*[no]*badcookie* + \[Do not\] ignore BADCOOKIE responses + +*--buffer-size* _int_, *+bufize*=_int_ + Set the UDP message buffer size, using EDNS. + Max is 65535, minimum is zero. + The default value is 1232. + +*--cd*[=_bool_], *+*[no]*cdflag* + (Set, Unset) CD (Checking Disabled) flag. + +*--no-cookie*, *+*[no]*cookie*[=_string_] + Send an EDNS cookie. + This is enabled by default with a random string. + +*-D*, *--dnssec*, *+dnssec*, *+do* + Request DNSSEC records as well. + This sets the DNSSEC OK bit (DO) + +*--dnscrypt*, *+*[no]*dnscrypt* + Use DNSCrypt. + +*--expire*. *+*[no]*expire* + Send an EDNS Expire. + + +*--edns-ver*, *+edns*[=_int_] + Enable EDNS and set EDNS version. + The maximum value is 255, and the minimum (default) value is 0. + +*--no-edns*, *+noedns* + Disable EDNS. + +*-H*, *--https*, *+*[no]*https*[=_endpoint_], *+*[no]*https-post*[=_endpoint_] + Use DNS-over-HTTPS (see RFC 8484). + The default endpoint is _/dns-query_ + +*+*[no]*https-get*[=_endpoint_] + Use an HTTP GET instead of an HTTP POST when making a DNS-over-HTTPS query. + +*+*[no]*idnout* + Converts [or leaves] punycode on output. + Input is automatically translated to punycode. *--no-truncate*, *+ignore* Ignore UDP truncation (by default, awl *retries with TCP*). -*--no-bad-cookie*, *+[no]badcookie* - \[Do not\] ignore BADCOOKIE responses +*-j*, *--json*, *+*[no]*json* + Print the query results as JSON. + The result is *not* in compliance with RFC 8427. -*--tcp*, *+[no]tcp*, *+[no]vc* +*--keep-alive*, *+*[no]*keepalive*, *+*[no]*keepopen* + Send an EDNS keep-alive. + This does nothing unless using TCP. + +*--nsid*, *+*[no]*nsid* + Send an EDNS name server ID request. + +*--qr*[=_bool_], *+*[no]*qrflag* + Sets the QR (QueRy) flag. + +*--no-question*, *+*[no]*question* + Toggle the display of the Question section. + +*-Q*. *--quic*, *+*[no]*quic* + Use DNS-over-QUIC (see RFC 9250). + +*-s*, *--short*, *+*[no]*short* + Print just the address of the answer. + +*--no-statistics*, *+*[no]*stats* + Toggle the display of the Statistics (additional comments) section. + +*--subnet* _ip_[_/prefix_], *+*[no]*subnet*[=_ip_[_/prefix_]] + Send an EDNS Client Subnet option with the specified address. + + Like *dig*(1), setting the IP to _0.0.0.0/0_, _::/0_ or _0_ will signal the resolver to not use any client information when returning the query. + +*--tc*[=_bool_], *+*[no]*tcflag* + Sets the TC (TrunCated) flag + +*--tcp*, *+*[no]*tcp*, *+*[no]*vc* Use TCP for the query (see RFC 7766). -*--dnscrypt*, *+[no]dnscrypt* - Use DNSCrypt. +*--timeout* _seconds_, *+timeout*=_seconds_ + Set the timeout period. Floating point numbers are accepted. + 0.5 seconds is the minimum. -*-T*, *--tls*, *+[no]tls* +*-T*, *--tls*, *+*[no]*tls* Use DNS-over-TLS, implies *--tcp* (see RFC 7858) *--tls-host* _string_ @@ -100,20 +192,6 @@ Many options are inherited from *dig*(1). *--tls-no-verify* Ignore TLS validation when performing a DNS query. -*-H*. *--https*, *+[no]https* - Use DNS-over-HTTPS (see RFC 8484). - -*-Q*. *--quic*, *+[no]quic* - Use DNS-over-QUIC (see RFC 9250). - -*-x*, *--reverse* - Do a reverse lookup. Sets default *type* to PTR. - *awl* automatically makes an IP or phone number canonical. - -*--timeout* _seconds_, *+timeout*=_seconds_ - Set the timeout period. Floating point numbers are accepted. - 0.5 seconds is the minimum. - *--trace*, *+trace* Trace the path of the query from the root, acting like its own resolver. This option enables DNSSEC. @@ -123,105 +201,20 @@ Many options are inherited from *dig*(1). Set the number of retries. Retry is one more than tries, dig style. -## DNS Flags +*-X*, *--xml*, *+*[no]*xml* + Print the query results as XML. -*--aa*[=_bool_], *+[no]aaflag* - (Set, Unset) AA (Authoritative Answer) flag. +*-y*, *--yaml*, *+*[no]*yaml* + Print the query results as YAML. -*--ad*[=_bool_], *+[no]adflag* - (Set, Unset) AD (Authenticated Data) flag. - -*--tc*[=_bool_], *+[no]tcflag* - (Set, Unset) TC (TrunCated) flag - -*-z*[=_bool_], *+[no]zflag* - (Set, Unset) Z (Zero) flag. - -*--cd*[=_bool_], *+[no]cdflag* - (Set, Unset) CD (Checking Disabled) flag. - -*--qr*[=_bool_], *+[no]qrflag* - (Set, Unset) QR (QueRy) flag. - -*--rd*[=_bool_], *+[no]rdflag* - (Set, Unset) RD (Recursion Desired) flag. - -*--ra*[=_bool_], *+[no]raflag* - (Set, Unset) RA (Recursion Available) flag. - -## EDNS -All of these options except disabling EDNS imply *+edns*. - -*--no-edns*, *+noedns* - Disable EDNS. - -*--edns-ver*, *+edns*[=_int_] - Enable EDNS and set EDNS version. - The maximum value is 255, and the minimum (default) value is 0. - -*--expire*. *+[no]expire* - Send an EDNS Expire. - -*--nsid*, *+[no]nsid* - Send an EDNS name server ID request. - -*--no-cookie*, *+[no]cookie*[=_string_] - Send an EDNS cookie. - This is enabled by default with a random string. - -*--keep-alive*, *+[no]keepalive*, *+[no]keepopen* - Send an EDNS keep-alive. - This does nothing unless using TCP. - -*--buffer-size* _int_, *+bufize*=_int_ - Set the UDP message buffer size, using EDNS. - Max is 65535, minimum is zero. - The default value is 1232. +*-z*[=_bool_], *+*[no]*zflag* + Sets the Z (Zero) flag. *--zflag* _int_, *+ednsflags*=_int_ Set the must-be-zero EDNS flags. Decimal, hexadecimal and octal are supported. Trying to set DO will be ignored. -*--subnet* _ip_[_/prefix_], *+[no]subnet*=_ip_[_/prefix_] - Send an EDNS Client Subnet option with the specified address. - - Like *dig*(1), setting the IP to _0.0.0.0/0_, _::/0_ or _0_ will signal the resolver to not use any client information when returning the query. - -## Output Display - -*--no-question*, *+[no]question* - Toggle the display of the Question section. - -*--no-answer*, *+[no]answer* - Toggle the display of the Answer section. - -*--no-answer*, *+[no]answer* - Toggle the display of the Answer section. - -*--no-authority*, *+[no]authority* - Toggle the display of the Authority section. - -*--no-additional*, *+[no]additional* - Toggle the display of the Additional section. - -*--no-statistics*, *+[no]stats* - Toggle the display of the Statistics (additional comments) section. - -## Output Formats - -*-j*, *--json*, *+[no]json* - Print the query results as JSON. - -*-X*, *--xml*, *+[no]xml* - Print the query results as XML. - -*-y*, *--yaml*, *+[no]yaml* - Print the query results as YAML. - -*-s*, *--short*, *+[no]short* - Print just the address of the answer. - # EXIT STATUS The exit code is 0 when a query is successfully made and received.