From bb4da3e4553d63538af417792b3f384d6a505a88 Mon Sep 17 00:00:00 2001 From: Sam Therapy Date: Mon, 3 Oct 2022 18:15:18 +0200 Subject: [PATCH] Update manpage Signed-off-by: Sam Therapy --- awl/man.txt | 252 ++++++++++++++++++++++++++++++++-------------------- 1 file changed, 157 insertions(+), 95 deletions(-) diff --git a/awl/man.txt b/awl/man.txt index d2fc04c..7b73817 100644 --- a/awl/man.txt +++ b/awl/man.txt @@ -1,163 +1,225 @@ -awl(1) awl(1) +awl(1) General Commands Manual awl(1) NAME 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) DESCRIPTION - awl (awls want licorice) 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 (awls want licorice) 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 fea‐ - tures 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 - Enable DNSSEC. This needs to be manually enabled. + -D, --dnssec, +dnssec + Enable DNSSEC. This needs to be manually enabled. - -v value - Set verbosity (currently WIP) + -v[=int] + Set verbosity Accepted values are as follows: + o 0: Only log errors. + o 1: Log warnings. This is the default. + o 2: Log information Default when specifying just -v. + o 3: Log information useful for debugging. - -V - Print the version and exit. + Setting a value lower than 0 disables logging entirely. - -h - Show a "short" help message. + 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 + -4 + Only make query over IPv4 - -6 - Only make query over IPv6 + -6 + Only make query over IPv6 - -p, --port port - Sets the port to query. + -p, --port port + Sets the port to query. Default ports listed below. + o 53 for UDP and TCP + o 853 for TLS and QUIC + o 443 for HTTPS - Default Ports: - • 53 for UDP and TCP - • 853 for TLS and QUIC - • 443 for HTTPS + -q, --query domain + Domain to query (eg. example.com) - -q, --query domain - Domain to query (eg. example.com) + -c, --class class + DNS class to query (eg. IN, CH) The default is IN. - -c, --class class - DNS class to query (eg. IN, CH) + -t, --qType type + DNS type to query (eg. A, AAAA, NS) The default is A. - -t, --qType type - DNS type to query (eg. A, NS) + --no-truncate, +ignore + Ignore UDP truncation (by default, awl retries with TCP). - --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) + --tcp, +tcp, +vc + Use TCP for the query (see RFC 7766). - --dnscrypt, +dnscrypt - Use DNSCrypt + --dnscrypt, +dnscrypt + Use DNSCrypt. - -T, --tls, +tls - Use DNS-over-TLS, implies --tcp (see RFC 7858) + -T, --tls, +tls + Use DNS-over-TLS, implies --tcp (see RFC 7858) - -H. --https, +https - Use DNS-over-HTTPS (see RFC 8484) + --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. - -Q. --quic, +quic - Use DNS-over-QUIC (see RFC 9250) + --tls-no-verify + Ignore TLS validation when performing a DNS query. - -x, --reverse - Do a reverse lookup. Sets default type to PTR. - awl automatically makes an IP or phone number canonical. + -H. --https, +https + Use DNS-over-HTTPS (see RFC 8484). - --timeout seconds, +timeout=seconds - Set the timeout period. Floating point numbers are accepted. - 0.5 seconds is the minimum. + -Q. --quic, +quic + Use DNS-over-QUIC (see RFC 9250). - --retries int, +tries=int, + retry=int - Set the number of retries. - Retry is one more than tries, dig style + -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=[false], +[no]aaflag - (Set, Unset) AA (Authoritative Answer) flag + --aa[=bool], +[no]aaflag + (Set, Unset) AA (Authoritative Answer) flag. - --ad=[false], +[no]adflag - (Set, Unset) AD (Authenticated Data) flag + --ad[=bool], +[no]adflag + (Set, Unset) AD (Authenticated Data) flag. - --tc=[false], +[no]tcflag - (Set, Unset) TC (TrunCated) flag + --tc[=bool], +[no]tcflag + (Set, Unset) TC (TrunCated) flag - -z=[false], +[no]zflag - (Set, Unset) Z (Zero) flag + -z[=bool], +[no]zflag + (Set, Unset) Z (Zero) flag. - --cd=[false], +[no]cdflag - (Set, Unset) CD (Checking Disabled) flag + --cd[=bool], +[no]cdflag + (Set, Unset) CD (Checking Disabled) flag. - --qr=[false], +[no]qrflag - (Set, Unset) QR (QueRy) flag + --qr[=bool], +[no]qrflag + (Set, Unset) QR (QueRy) flag. - --rd=[true], +[no]rdflag - (Set, Unset) RD (Recursion Desired) flag + --rd[=bool], +[no]rdflag + (Set, Unset) RD (Recursion Desired) flag. - --ra=[false], +[no]raflag - (Set, Unset) RA (Recursion Available) 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, +noquestion - Do not display the Question section + --no-question, +[no]question + Toggle the display of the Question section. - --no-answer, +noanswer - Do not display the Answer section + --no-answer, +[no]answer + Toggle the display of the Answer section. - --no-answer, +noanswer - Do not display the Answer section + --no-answer, +[no]answer + Toggle the display of the Answer section. - --no-authority, +noauthority - Do not display the Authority section + --no-authority, +[no]authority + Toggle the display of the Authority section. - --no-additional, +noadditional - Do not display the Additional section + --no-additional, +[no]additional + Toggle the display of the Additional section. - --no-statistics, +nostats - Do not display the Statistics (additional comments) 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. + -j, --json, +json + Print the query results as JSON. - -X, --xml, +xml - Print the query results as XML. + -X, --xml, +xml + Print the query results as XML. - -y, --yaml, +yaml - Print the query results as YAML. + -y, --yaml, +yaml + Print the query results as YAML. - -s, --short, +short - Print just the address of the answer. + -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. + + 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), the many DNS RFCs + drill(1), dig(1) - awl(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 + + 2022-09-24 awl(1)