From f964573ccad2472166e2931164cb2ad04734c383 Mon Sep 17 00:00:00 2001 From: Sam Date: Wed, 28 Sep 2022 18:34:47 +0000 Subject: [PATCH] update_doc --- awl.1.md | 620 +++++++++++++++++++++++++++---------------------------- 1 file changed, 310 insertions(+), 310 deletions(-) diff --git a/awl.1.md b/awl.1.md index a2db7e9..38918a4 100644 --- a/awl.1.md +++ b/awl.1.md @@ -1,310 +1,310 @@ -# 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 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_