From 777e4ebd785728883744ee6d2afc6172b0c58268 Mon Sep 17 00:00:00 2001 From: Sam Therapy Date: Fri, 21 Oct 2022 03:39:47 +0200 Subject: [PATCH] update manpage Signed-off-by: Sam Therapy --- awl.1.md | 618 +++++++++++++++++++++++++++---------------------------- 1 file changed, 308 insertions(+), 310 deletions(-) diff --git a/awl.1.md b/awl.1.md index 38918a4..3680129 100644 --- a/awl.1.md +++ b/awl.1.md @@ -1,310 +1,308 @@ -# NAME - -awl - DNS lookup tool - -# SYNOPSIS - -**awl** \[ _OPTIONS_ \] _name_ \[ _@server_ \] \[ _type_ \], where - -_name_ is the query to make (example: froth.zone) -_@server_ is the server to query (example: dns.froth.zone) -_type_ is the DNS resource type (example: AAAA) - -# DESCRIPTION - -**awl** (**a**wls **w**ant **l**icorice) is a simple tool designed to -make DNS queries, much like the venerable **dig**(1). An awl is a tool -used to make small holes, typically used in leatherworking. - -**awl** is designed to be a more "modern" version of **drill**(1) by -including some more recent RFCs and output options. - -When no arguments are given, **awl** will perform an _NS_ query on the -root ('_._'). - -When a nameserver is not given, **awl** will query a random system -nameserver. If one cannot be found, **awl** will query localhost. - -# OPTIONS - -Anything in \[brackets\] is optional. - -**-D**, **--dnssec**, **+dnssec** - -> Enable DNSSEC. This needs to be manually enabled. - -**-v**\[=_int_\] - -> Set verbosity Accepted values are as follows: -> -> - _0_: Only log errors. -> -> - _1_: Log warnings. **This is the default.** -> -> - _2_: Log information **Default when specifying just** _-v_. -> -> - _3_: Log information useful for debugging. -> -> Setting a value lower than 0 disables logging entirely. -> -> By default, specifying just **-v** sets the verbosity to 2 (info). - -**-V** - -> Print the version and exit. - -**-h** - -> Show a "short" help message. - -## Query Options - -**-4** - -> Only make query over IPv4 - -**-6** - -> Only make query over IPv6 - -**-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_ - -> Domain to query (eg. example.com) - -**-c**, **--class** _class_ - -> DNS class to query (eg. IN, CH) The default is IN. - -**-t**, **--qType** _type_ - -> DNS type to query (eg. A, AAAA, NS) The default is A. - -**--no-truncate**, **+ignore** - -> Ignore UDP truncation (by default, awl **retries with TCP**). - -**--no-bad-cookie**, **+\[no\]badcookie** - -> \[Do not\] ignore BADCOOKIE responses - -**--tcp**, **+tcp**, **+vc** - -> Use TCP for the query (see RFC 7766). - -**--dnscrypt**, **+dnscrypt** - -> Use DNSCrypt. - -**-T**, **--tls**, **+tls** - -> Use DNS-over-TLS, implies **--tcp** (see RFC 7858) - -**--tls-host** _string_ - -> Set hostname to use for TLS certificate validation. Default is the -> name of the domain when querying over TLS, and empty for IPs. - -**--tls-no-verify** - -> Ignore TLS validation when performing a DNS query. - -**-H**. **--https**, **+https** - -> Use DNS-over-HTTPS (see RFC 8484). - -**-Q**. **--quic**, **+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. - -**--retries** _int_, **+tries**=_int_, **+retry**=_int_ - -> Set the number of retries. Retry is one more than tries, dig style. - -## DNS Flags - -**--aa**\[=_bool_\], **+\[no\]aaflag** - -> (Set, Unset) AA (Authoritative Answer) flag. - -**--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. - -**--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**, **+json** - -> Print the query results as JSON. - -**-X**, **--xml**, **+xml** - -> Print the query results as XML. - -**-y**, **--yaml**, **+yaml** - -> Print the query results as YAML. - -**-s**, **--short**, **+short** - -> Print just the address of the answer. - -# EXIT STATUS - -The exit code is 0 when a query is successfully made and received. This -includes SERVFAILs, NOTIMPL among others. - -# EXAMPLES - - awl grumbulon.xyz -j +cd - -Run a query of your local resolver for the A records of grumbulon.xyz, -print them as JSON and disable DNSSEC verification. - - awl +short example.com AAAA @1.1.1.1 - -Query 1.1.1.1 for the AAAA records of example.com, print just the -answers - - awl -xT PTR 8.8.4.4 @dns.google - -Query dns.google over TLS for the PTR record to the IP address 8.8.4.4 - -# SEE ALSO - -**drill**(1), **dig**(1) - -# STANDARDS - -RFC 1034,1035 (UDP), 7766 (TCP), 7858 (TLS), 8484 (HTTPS), 9230 (QUIC) - -Probably more, *https://www.statdns.com/rfc* - -# BUGS - -OPT records are only printed when using a standard output, not -JSON/XML/YAML. - -Full parity with **dig**(1) is not complete. - -This man page is probably not complete. - -Likely numerous more, report them either to the tracker -*https://git.froth.zone/sam/awl/issues* or via email -_\~sammefishe/awl-dev@lists.sr.ht_ +# NAME + +awl - DNS lookup tool + +# SYNOPSIS + +**awl** \[ *OPTIONS* \] *name* \[ *@server* \] \[ *type* \], where + +*name* is the query to make (example: froth.zone) +*@server* is the server to query (example: dns.froth.zone) +*type* is the DNS resource type (example: AAAA) + +# DESCRIPTION + +**awl** (**a**wls **w**ant **l**icorice) is a simple tool designed to +make DNS queries, much like the venerable **dig**(1). An awl is a tool +used to make small holes, typically used in leatherworking. + +**awl** is designed to be a more "modern" version of **drill**(1) by +including some more recent RFCs and output options. + +When no arguments are given, **awl** will perform an *NS* query on the +root ('*.*'). + +When a nameserver is not given, **awl** will query a random system +nameserver. If one cannot be found, **awl** will query the localhost. + +# OPTIONS + +Anything in \[brackets\] is optional. Many options are inherited from +**dig**(1). + +**-D**, **--dnssec**, **+dnssec**, **+do** + +> Enable DNSSEC. This needs to be manually enabled. + +**-v**\[=*int*\] + +> Set verbosity Accepted values are as follows: +> +> - *0*: Only log errors. +> +> - *1*: Log warnings. **This is the default.** +> +> - *2*: Log information **Default when specifying just** *-v*. +> +> - *3*: Log information useful for debugging. +> +> Setting a value lower than 0 disables logging entirely. +> +> By default, specifying just **-v** sets the verbosity to 2 (info). + +**-V** + +> Print the version and exit. + +**-h** + +> Show a "short" help message. + +## Query Options + +**-4** + +> Only make query over IPv4 + +**-6** + +> Only make query over IPv6 + +**-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* + +> Domain to query (eg. example.com) + +**-c**, **--class** *class* + +> DNS class to query (eg. IN, CH) The default is IN. + +**-t**, **--qType** *type* + +> DNS type to query (eg. A, AAAA, NS) The default is A. + +**--no-truncate**, **+ignore** + +> Ignore UDP truncation (by default, awl **retries with TCP**). + +**--no-bad-cookie**, **+\[no\]badcookie** + +> \[Do not\] ignore BADCOOKIE responses + +**--tcp**, **+\[no\]tcp**, **+\[no\]vc** + +> Use TCP for the query (see RFC 7766). + +**--dnscrypt**, **+\[no\]dnscrypt** + +> Use DNSCrypt. + +**-T**, **--tls**, **+\[no\]tls** + +> Use DNS-over-TLS, implies **--tcp** (see RFC 7858) + +**--tls-host** *string* + +> Set hostname to use for TLS certificate validation. Default is the +> name of the domain when querying over TLS, and empty for IPs. + +**--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. + +**--retries** *int*, **+tries**=*int*, **+retry**=*int* + +> Set the number of retries. Retry is one more than tries, dig style. + +## DNS Flags + +**--aa**\[=*bool*\], **+\[no\]aaflag** + +> (Set, Unset) AA (Authoritative Answer) flag. + +**--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. + +**--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. This +includes SERVFAILs, NOTIMPL among others. + +# EXAMPLES + + awl grumbulon.xyz -j +cd + +Run a query of your local resolver for the A records of grumbulon.xyz, +print them as JSON and disable DNSSEC verification. + + awl +short example.com AAAA @1.1.1.1 + +Query 1.1.1.1 for the AAAA records of example.com, print just the +answers + + awl -xT PTR 8.8.4.4 @dns.google + +Query dns.google over TLS for the PTR record to the IP address 8.8.4.4 + +# SEE ALSO + +**drill**(1), **dig**(1) + +# STANDARDS + +RFC 1034,1035 (UDP), 7766 (TCP), 7858 (TLS), 8484 (HTTPS), 9230 (QUIC) + +Probably more, *https://www.statdns.com/rfc* + +# BUGS + +Full parity with **dig**(1) is not complete. + +This man page is probably not complete. + +Likely numerous more, report them either to the tracker +*https://git.froth.zone/sam/awl/issues* or via email +*\~sammefishe/awl-dev@lists.sr.ht*