diff --git a/awl.1.md b/awl.1.md index 68ad7d3..5b56f0c 100644 --- a/awl.1.md +++ b/awl.1.md @@ -4,194 +4,259 @@ awl - DNS lookup tool # SYNOPSIS -_awl_ \[ _OPTIONS_ \] _name_ \[ _@server_ \] \[ _type_ \], where +**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_) +*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** (**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. _awl_ is still heavily Work-In-Progress so -some features may get added or removed. +**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 -Dig-like +\[no\]flags are supported, see dig(1) +Anything in \[brackets\] is optional. -_-D_, _--dnssec_, _+dnssec_ +**-D**, **--dnssec**, **+dnssec** > Enable DNSSEC. This needs to be manually enabled. -_-v_ _value_ +**-v**\[=*int*\] -> Set verbosity (currently WIP) +> 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. -_-V_ +Setting a value lower than 0 disables logging entirely. + +**-V** > Print the version and exit. -_-h_ +**-h** > Show a "short" help message. ## Query Options -_-4_ +**-4** > Only make query over IPv4 -_-6_ +**-6** > Only make query over IPv6 -_-p_, _--port_ _port_ +**-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_ +> - *53* for **UDP** and **TCP** +> +> - *853* for **TLS** and **QUIC** +> +> - *443* for **HTTPS** -_-q_, _--query_ _domain_ +**-q**, **--query** *domain* > Domain to query (eg. example.com) -_-c_, _--class_ _class_ +**-c**, **--class** *class* -> DNS class to query (eg. IN, CH) +> DNS class to query (eg. IN, CH) The default is IN. -_-t_, _--qType_ _type_ +**-t**, **--qType** *type* -> DNS type to query (eg. A, NS) +> DNS type to query (eg. A, AAAA, NS) The default is A. -_--no-truncate_, _+ignore_ +**--no-truncate**, **+ignore** -> Ignore UDP truncation (by default, awl _retries with TCP_) +> Ignore UDP truncation (by default, awl **retries with TCP**). -_--tcp_, _+tcp_, _+vc_ +**--tcp**, **+tcp**, **+vc** -> Use TCP for the query (see _RFC 7766_) +> Use TCP for the query (see **RFC 7766**). -_--dnscrypt_, _+dnscrypt_ +**--dnscrypt**, **+dnscrypt** -> Use DNSCrypt +> Use DNSCrypt. -_-T_, _--tls_, _+tls_ +**-T**, **--tls**, **+tls** -> Use DNS-over-TLS, implies _--tcp_ (see _RFC 7858_) +> Use DNS-over-TLS, implies *--tcp* (see **RFC 7858**) -_--tls-host_ _string_ +**--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. +> 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_ +**--tls-no-verify** > Ignore TLS validation when performing a DNS query. -_-H_. _--https_, _+https_ +**-H**. **--https**, **+https** -> Use DNS-over-HTTPS (see _RFC 8484_) +> Use DNS-over-HTTPS (see **RFC 8484**). -_-Q_. _--quic_, _+quic_ +**-Q**. **--quic**, **+quic** -> Use DNS-over-QUIC (see _RFC 9250_) +> Use DNS-over-QUIC (see **RFC 9250**). -_-x_, _--reverse_ +**-x**, **--reverse** -> Do a reverse lookup. Sets default _type_ to PTR.\ -> _awl_ automatically makes an IP or phone number canonical. +> Do a reverse lookup. Sets default **type** to PTR. **awl** +> automatically makes an IP or phone number canonical. -_--timeout_ _seconds_, _+timeout=seconds_ +**--timeout** *seconds*, **+timeout**=*seconds* -> Set the timeout period. Floating point numbers are accepted.\ -> 0.5 seconds is the minimum. +> Set the timeout period. Floating point numbers are accepted. 0.5 +> seconds is the minimum. -_--retries_ _int_, _+tries_=_int_, _+ retry_=_int_ +**--retries** *int*, **+tries**=*int*, **+retry**=*int* -> Set the number of retries. Retry is one more than tries, dig style +> Set the number of retries. Retry is one more than tries, dig style. ## DNS Flags -_--aa=\[false\]_, _+\[no\]aaflag_ +**--aa**=\[*false*\], **+\[no\]aaflag** -> (Set, Unset) AA (Authoritative Answer) flag +> (Set, Unset) AA (Authoritative Answer) flag. -_--ad=\[false\]_, _+\[no\]adflag_ +**--ad**=\[*false*\], **+\[no\]adflag** -> (Set, Unset) AD (Authenticated Data) flag +> (Set, Unset) AD (Authenticated Data) flag. -_--tc=\[false\]_, _+\[no\]tcflag_ +**--tc**=\[*false*\], **+\[no\]tcflag** > (Set, Unset) TC (TrunCated) flag -_-z=\[false\]_, _+\[no\]zflag_ +**-z**=\[*false*\], **+\[no\]zflag** -> (Set, Unset) Z (Zero) flag +> (Set, Unset) Z (Zero) flag. -_--cd=\[false\]_, _+\[no\]cdflag_ +**--cd**=\[*false*\], **+\[no\]cdflag** -> (Set, Unset) CD (Checking Disabled) flag +> (Set, Unset) CD (Checking Disabled) flag. -_--qr=\[false\]_, _+\[no\]qrflag_ +**--qr**=\[*false*\], **+\[no\]qrflag** -> (Set, Unset) QR (QueRy) flag +> (Set, Unset) QR (QueRy) flag. -_--rd=\[true\]_, _+\[no\]rdflag_ +**--rd**=\[*true*\], **+\[no\]rdflag** -> (Set, Unset) RD (Recursion Desired) flag +> (Set, Unset) RD (Recursion Desired) flag. -_--ra=\[false\]_, _+\[no\]raflag_ +**--ra**=\[*false*\], **+\[no\]raflag** -> (Set, Unset) RA (Recursion Available) flag +> (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_, _+noquestion_ +**--no-question**, **+\[no\]question** -> Do not display the Question section +> Toggle the display of the Question section. -_--no-answer_, _+noanswer_ +**--no-answer**, **+\[no\]answer** -> Do not display the Answer section +> Toggle the display of the Answer section. -_--no-answer_, _+noanswer_ +**--no-answer**, **+\[no\]answer** -> Do not display the Answer section +> Toggle the display of the Answer section. -_--no-authority_, _+noauthority_ +**--no-authority**, **+\[no\]authority** -> Do not display the Authority section +> Toggle the display of the Authority section. -_--no-additional_, _+noadditional_ +**--no-additional**, **+\[no\]additional** -> Do not display the Additional section +> Toggle the display of the Additional section. -_--no-statistics_, _+nostats_ +**--no-statistics**, **+\[no\]stats** -> Do not display the Statistics (additional comments) section +> Toggle the display of the Statistics (additional comments) section. ## Output Formats -_-j_, _--json_, _+json_ +**-j**, **--json**, **+json** > Print the query results as JSON. -_-X_, _--xml_, _+xml_ +**-X**, **--xml**, **+xml** > Print the query results as XML. -_-y_, _--yaml_, _+yaml_ +**-y**, **--yaml**, **+yaml** > Print the query results as YAML. -_-s_, _--short_, _+short_ +**-s**, **--short**, **+short** > Print just the address of the answer. @@ -199,12 +264,13 @@ _-s_, _--short_, _+short_ 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. +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 +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 @@ -212,4 +278,11 @@ Query dns.google over TLS for the PTR record to the IP address 8.8.4.4 # SEE ALSO -_drill_(1), _dig_(1), the many DNS RFCs +**drill**(1), **dig**(1), the many DNS RFCs +(https://www.statdns.com/rfc/) + +# BUGS + +Likely numerous, report them either to +https://git.froth.zone/sam/awl/issues or via email +\~sammefishe/awl-dev@lists.sr.ht