wik e

Signed-off-by: Sam Therapy <sam@samtherapy.net>
2022-08-06 01:46:46 +02:00 · 2022-08-06 01:46:46 +02:00 · 59537b97c2
commit 59537b97c2
parent 35f462a9ba
8 changed files with 387 additions and 108 deletions
--- a/Compatibility/Compatibility.md
+++ b/Compatibility/Compatibility.md
@ -0,0 +1 @@
+Awl aims to be compatible with the littany of DNS tools available.
--- a/Compatibility/Dig.md
+++ b/Compatibility/Dig.md
@ -0,0 +1,81 @@
+# Dig Compatibility
+
+awl is designed to be compatible with dig.
+
+Flags and `-flags` taken from the
+[OpenBSD manpage](https://man.openbsd.org/dig.1)
+
+## Regular POSIX flags
+
+| Flag | Supported              |
+| ---- | ---------------------- |
+| `-4` | Yes, 0.2.0 and newer   |
+| `-6` | Yes, 0.2.0 and newer   |
+| `-b` | No                     |
+| `-c` | Yes, 0.2.0 and newer   |
+| `-f` | No                     |
+| `-h` | Yes, 0.2.0 and newer   |
+| `-i` | No, obsolete           |
+| `-k` | No                     |
+| `-p` | Yes, 0.2.0 and newer   |
+| `-q` | Yes, 0.2.0 and newer   |
+| `-t` | Yes, 0.2.0 and newer   |
+| `-u` | No, automatically done |
+| `-x` | Yes, 0.2.0 and newer   |
+| `-y` | No                     |
+
+## Dig +[no]flags
+
+| d-opt             | Supported                           |
+| ----------------- | ----------------------------------- |
+| `+[no]aaflag`     | Yes, 0.2.0 and newer                |
+| `+[no]aaonly`     | Yes, 0.2.0 and newer                |
+| `+[no]additional` | Yes, 0.2.0 and newer                |
+| `+[no]adflag`     | Yes, 0.2.0 and newer                |
+| `+[no]all`        | Yes,                                |
+| `+[no]adflag`     | Yes, 0.2.0 and newer                |
+| `+[no]authority`  | Yes, 0.2.0 and newer                |
+| `+[no]badcookie`  | No                                  |
+| `+[no]besteffort` | No                                  |
+| `+bufsize`        | Yes,                                |
+| `+[no]cdflag`     | Yes, 0.2.0 and newer                |
+| `+[no]class`      | No                                  |
+| `+[no]cmd`        | No                                  |
+| `+[no]comments`   | Yes,                                |
+| `+[no]cookie`     | Yes,                                |
+| `+[no]crypto`     | No                                  |
+| `+[no]defname`    | No                                  |
+| `+[no]dnssec`     | Yes, 0.2.0 and newer                |
+| `+[no]domain`     | No                                  |
+| `+[no]edns`       | Yes, setting versions as well       |
+| `+ednsflags`      | Yes                                 |
+| `+[no]expire`     | Yes, not displayed                  |
+| `+[no]fail`       | No, will not query more on SERVFAIL |
+| `+[no]idnout`     | Somewhat, only JSON/XML/YAML        |
+| `+[no]ignore`     | Yes, 0.2.0 and newer                |
+| `+[no]keepopen`   | Yes,                                |
+| `+[no]multiline`  | No                                  |
+| `+ndots`          | No                                  |
+| `+[no]nsid`       | Yes,                                |
+| `+[no]nssearch`   | No                                  |
+| `+[no]onesoa`     | No                                  |
+| `+[no]opcode`     | No                                  |
+| `+[no]qr`         | Yes,                                |
+| `+[no]question`   | Yes, 0.2.0 and newer                |
+| `+[no]rdflag`     | Yes, 0.2.0 and newer                |
+| `+[no]recurse`    | Yes, 0.2.0 and newer                |
+| `+[no]retry`      | Yes, 0.2.0 and newer                |
+| `+[no]rrcomments` | No                                  |
+| `+[no]search`     | No                                  |
+| `+[no]short`      | Yes, 0.2.0 and newer                |
+| `+[no]showsearch` | No                                  |
+| `+[no]split`      | No                                  |
+| `+[no]stats`      | Yes, 0.2.0 and newer                |
+| `+[no]subnet`     | Yes                                 |
+| `+[no]tcp`        | Yes, 0.2.0 and newer                |
+| `+timeout`        | Yes, 0.2.0 and newer                |
+| `+[no]trace`      | No                                  |
+| `+tries`          | Yes, 0.2.0 and newer                |
+| `+[no]ttlid`      | Somewhat, only JSON/XML/YAML        |
+| `+[no]ttlunits`   | Yes,                                |
+| `+[no]vc`         | Yes, 0.2.0 and newer                |
--- a/Compatibility/Dog.md
+++ b/Compatibility/Dog.md
@ -0,0 +1,41 @@
+# Dog Compatibility
+
+[Dog](https://github.com/ogham/dog) is another DNS tool
+
+### Query Options
+
+| Option           | Supported?           |
+| ---------------- | -------------------- |
+| -q, --query      | Yes, 0.2.0 and newer |
+| -t, --type       | Yes, 0.2.0 and newer |
+| -n, --nameserver | No                   |
+| --class          | Yes, 0.2.0 and newer |
+
+### Sending Options
+
+| Option | Supported?                |
+| ------ | ------------------------- |
+| --edns | No, follows dig instead   |
+| --txid | No                        |
+| -Z     | No, This isn't documented |
+
+### Protocol Options
+
+| Option      | Supported?                       |
+| ----------- | -------------------------------- |
+| -U, --udp   | Default, no                      |
+| -T, --tcp   | Yes, --tcp only: 0.2.0 and newer |
+| -S, --tls   | Yes, -T, --tls:0.2.0 and newer   |
+| -H, --https | Yes, 0.2.0 and newer             |
+
+### Output Options
+
+| Option            | Supported?                                   |
+| ----------------- | -------------------------------------------- |
+| -1, --short       | Yes, -s. --short, +short: 0.2.0 and newer    |
+| -J, --json        | Yes, -j, --json, +json: Yes, 0.2.0 and newer |
+| --color, --colour | NO                                           |
+| --seconds         | No                                           |
+| --time            | No                                           |
+
+(Meta options omitted)
--- a/Compatibility/Doggo.md
+++ b/Compatibility/Doggo.md
@ -0,0 +1,34 @@
+# Doggo Compatibility
+
+[Doggo](https://github.com/mr-karan/doggo) is another DNS tool
+
+### Query Options
+
+| Option               | Supported?                                |
+| -------------------- | ----------------------------------------- |
+| `-q`, `--query`      | Yes, 0.2.0 and newer                      |
+| `-t`, `--type`       | Yes, as `--q`, `--qType`, 0.2.0 and newer |
+| `-n`, `--nameserver` | No                                        |
+| `-c`, `--class`      | Yes, 0.2.0 and newer                      |
+| `-x`, `--reverse`    | Yes, 0.2.0 and newer                      |
+
+### Resolver Options
+
+| Option                         | Supported?           |
+| ------------------------------ | -------------------- |
+| `--strategy`                   | No, only random      |
+| `--ndots`                      | No                   |
+| `--search`                     | No                   |
+| `--timeout`                    | Yes, 0.2.0 and newer |
+| `--tls-hostname`               | No                   |
+| `--skip-hostname-verification` | No                   |
+
+### Output Options
+
+| Option        | Supported?                                 |
+| ------------- | ------------------------------------------ |
+| `-J`, `-json` | Yes, `-j`,instead of `-J`, 0.2.0 and newer |
+| `--short`     | Yes, 0.2.0 and newer                       |
+| `--color`     | NO                                         |
+| `--debug`     | No, use `-v` for verbosity instead         |
+| `--time`      | No                                         |
--- a/Compatibility/Drill.md
+++ b/Compatibility/Drill.md
@ -0,0 +1,41 @@
+# Drill compatibility
+
+As awl was designed to be like dig, it supports many similar features to drill.
+
+Drill flags taken from [this manpage](https://linux.die.net/man/1/drill).
+
+## Regular Options
+
+| Flag | Supported?                                                                  |
+| ---- | --------------------------------------------------------------------------- |
+| `-D` | Yes, 0.2.0 and newer                                                        |
+| `-T` | No                                                                          |
+| `-S` | No                                                                          |
+| `-V` | Somewhat, `-v` sets verbosity from WARN to DEBUG and `+qr` prints the query |
+| `-Q` | See above                                                                   |
+| `-f` | No                                                                          |
+| `-i` | No                                                                          |
+| `-w` | No                                                                          |
+| `-q` | No                                                                          |
+
+## Regular Options
+
+| Flag | Supported?                                               |
+| ---- | -------------------------------------------------------- |
+| `-4` | Yes, 0.2.0 and newer                                     |
+| `-6` | Yes, 0.2.0 and newer                                     |
+| `-a` | No, use +ignore for truncation instead                   |
+| `-b` | Yes                                                      |
+| `-c` | No                                                       |
+| `-d` | No                                                       |
+| `-t` | Yes                                                      |
+| `-k` | No                                                       |
+| `-o` | No, use Dig's [DNS flags](../awl.1.md#dns-flags) instead |
+| `-p` | Yes                                                      |
+| `-r` | No                                                       |
+| `-s` | No                                                       |
+| `-u` | No, enabled by default                                   |
+| `-w` | No                                                       |
+| `-x` | Yes                                                      |
+| `-y` | No                                                       |
+| `-z` | No                                                       |
--- a/Compatibility/Q.md
+++ b/Compatibility/Q.md
@ -0,0 +1,35 @@
+# q
+
+[q](https://github.com/natesales/q) is another DNS client
+
+## Application Flags
+
+| Flag            | Supported?                                                       |
+| --------------- | ---------------------------------------------------------------- |
+| `-q`            | Yes, 0.2.0 and newer                                             |
+| `-s`            | No                                                               |
+| `-t`            | Yes, 0.2.0 and newer                                             |
+| `-x`            | Yes, 0.2.0 and newer                                             |
+| `-d`            | Yes, as -D, 0.2.0 and newer                                      |
+| `-n`            | Yes                                                              |
+| `--subnet`      | Yes, as `+subnet`                                                |
+| `-c`            | No, use `-t` CH instead                                          |
+| `-p`            | No                                                               |
+| `--timeout`     | Yes, 0.2.0 and newer                                             |
+| `--pad`         | Yes                                                              |
+| `-f`            | No, use `--json`/`--xml`/`--yaml` instead                        |
+| `--pretty-ttls` | No                                                               |
+| `--color`       | NO                                                               |
+| `--question`    | Yes, inverted: use `--no-question` to disable, 0.2.0 and newer   |
+| `--answer`      | Yes, inverted: use `--no-answer` to disable, 0.2.0 and newer     |
+| `--authority`   | Yes, inverted: use `--no-authority` to disable, 0.2.0 and newer  |
+| `--additional`  | Yes, inverted: use `--no-additional` to disable, 0.2.0 and newer |
+| `--stats`       | Yes, inverted: use `--no-stats` to disable, 0.2.0 and newer      |
+| `--all`         | Yes, as `+[no]all`                                               |
+| `--aa`          | Yes, 0.2.0 and newer                                             |
+| `--ad`          | Yes, 0.2.0 and newer                                             |
+| `--cd`          | Yes, 0.2.0 and newer                                             |
+| `--rd`          | Yes, 0.2.0 and newer                                             |
+| `--ra`          | Yes, 0.2.0 and newer                                             |
+| `--z`           | Yes, as `-z`, 0.2.0 and newer                                    |
+| `--t`           | Yes, as `--tc`, 0.2.0 and newer                                  |
--- a/_Sidebar.md
+++ b/_Sidebar.md
@ -1,2 +1,2 @@
-[Manpage](./awl.1) \
-[Feature List](./Supported)
+[Manpage](./awl.1)\
+[Feature List](./Supported)
--- a/awl.1.md
+++ b/awl.1.md
@ -1,169 +1,215 @@
-awl(1)
-
 # 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*)
+_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_ (**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. _awl_ is still heavily Work-In-Progress so
+some features may get added or removed.

 # OPTIONS
-	Dig-like +[no]flags are supported, see dig(1)

-	*-D*, *--dnssec*, *+dnssec*++
-	Enable DNSSEC. This needs to be manually enabled.
+Dig-like +\[no\]flags are supported, see dig(1)

-	*-v* _value_++
-	Set verbosity (currently WIP)
+_-D_, _--dnssec_, _+dnssec_

-	*-V*++
-	Print the version and exit.
+> Enable DNSSEC. This needs to be manually enabled.

-	*-h*++
-	Show a "short" help message.
+_-v_ _value_
+
+> Set verbosity (currently WIP)
+
+_-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
+_-4_

-	*-p*, *--port* _port_++
-	Sets the port to query.++
-	++
-_Default Ports_:
-		- _53_ for *UDP* and *TCP*
-		- _853_ for *TLS* and *QUIC*
-		- _443_ for *HTTPS*
+> Only make query over IPv4

-	*-q*, *--query* _domain_++
-	Domain to query (eg. example.com)
+_-6_

-	*-c*, *--class* _class_++
-	DNS class to query (eg. IN, CH)
+> Only make query over IPv6

-	*-t*, *--qType* _type_++
-	DNS type to query (eg. A, NS)
+_-p_, _--port_ _port_

-	*--no-truncate*, *+ignore*++
-	Ignore UDP truncation (by default, awl _retries with TCP_)
+> Sets the port to query. Default ports listed below.
+>
+> - _53_ for _UDP_ and _TCP_
+> - _853_ for _TLS_ and _QUIC_
+> - _443_ for _HTTPS_

-	*--tcp*, *+tcp*, *+vc*++
-	Use TCP for the query (see _RFC 7766_)
+_-q_, _--query_ _domain_

-	*--dnscrypt*, *+dnscrypt*++
-	Use DNSCrypt
+> Domain to query (eg. example.com)

-	*-T*, *--tls*, *+tls*++
-	Use DNS-over-TLS, implies *--tcp* (see _RFC 7858_)
+_-c_, _--class_ _class_

-	*-H*. *--https*, *+https*++
-	Use DNS-over-HTTPS (see _RFC 8484_)
+> DNS class to query (eg. IN, CH)

-	*-Q*. *--quic*, *+quic*++
-	Use DNS-over-QUIC (see _RFC 9250_)
+_-t_, _--qType_ _type_

-	*-x*, *--reverse*++
-	Do a reverse lookup. Sets default _type_ to PTR.++
-	*awl* automatically makes an IP or phone number canonical.
+> DNS type to query (eg. A, NS)

-	*--timeout* _seconds_, *+timeout=*_seconds_++
-	Set the timeout period. Floating point numbers are accepted.++
-	0.5 seconds is the minimum.
+_--no-truncate_, _+ignore_

-	*--retries* _int_, *+tries*=_int_, *+ retry*=_int_++
-	Set the number of retries.++
-	Retry is one more than tries, dig style
+> Ignore UDP truncation (by default, awl _retries with TCP_)
+
+_--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=[false]*, *+[no]aaflag*++
-	(Set, Unset) AA (Authoritative Answer) flag
+_--aa=\[false\]_, _+\[no\]aaflag_

-	*--ad=[false]*, *+[no]adflag*++
-	(Set, Unset) AD (Authenticated Data) flag
+> (Set, Unset) AA (Authoritative Answer) flag

-	*--tc=[false]*, *+[no]tcflag*++
-	(Set, Unset) TC (TrunCated) flag
+_--ad=\[false\]_, _+\[no\]adflag_

-	*-z=[false]*, *+[no]zflag*++
-	(Set, Unset) Z (Zero) flag
+> (Set, Unset) AD (Authenticated Data) flag

-	*--cd=[false]*, *+[no]cdflag*++
-	(Set, Unset) CD (Checking Disabled) flag
+_--tc=\[false\]_, _+\[no\]tcflag_

-	*--qr=[false]*, *+[no]qrflag*++
-	(Set, Unset) QR (QueRy) flag
+> (Set, Unset) TC (TrunCated) flag

-	*--rd=[true]*, *+[no]rdflag*++
-	(Set, Unset) RD (Recursion Desired) flag
+_-z=\[false\]_, _+\[no\]zflag_

-	*--ra=[false]*, *+[no]raflag*++
-	(Set, Unset) RA (Recursion Available) flag
+> (Set, Unset) Z (Zero) flag
+
+_--cd=\[false\]_, _+\[no\]cdflag_
+
+> (Set, Unset) CD (Checking Disabled) flag
+
+_--qr=\[false\]_, _+\[no\]qrflag_
+
+> (Set, Unset) QR (QueRy) flag
+
+_--rd=\[true\]_, _+\[no\]rdflag_
+
+> (Set, Unset) RD (Recursion Desired) flag
+
+_--ra=\[false\]_, _+\[no\]raflag_
+
+> (Set, Unset) RA (Recursion Available) flag

 ## Output Display
-	*--no-question*, *+noquestion*++
-	Do not display the Question section

-	*--no-answer*, *+noanswer*++
-	Do not display the Answer section
+_--no-question_, _+noquestion_

-	*--no-answer*, *+noanswer*++
-	Do not display the Answer section
+> Do not display the Question section

-	*--no-authority*, *+noauthority*++
-	Do not display the Authority section
+_--no-answer_, _+noanswer_

-	*--no-additional*, *+noadditional*++
-	Do not display the Additional section
+> Do not display the Answer section

-	*--no-statistics*, *+nostats*++
-	Do not display the Statistics (additional comments) section
+_--no-answer_, _+noanswer_
+
+> Do not display the Answer section
+
+_--no-authority_, _+noauthority_
+
+> Do not display the Authority section
+
+_--no-additional_, _+noadditional_
+
+> Do not display the Additional section
+
+_--no-statistics_, _+nostats_
+
+> Do not display 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.
+_-j_, _--json_, _+json_

-	*-y*, *--yaml*, *+yaml*++
-	Print the query results as YAML.
+> Print the query results as JSON.

-	*-s*, *--short*, *+short*++
-	Print just the address of the answer.
+_-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.

 # EXAMPLES
-```
-awl grumbulon.xyz -j +cd
-```
+
+    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
-```
+    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
-```
+    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), the many DNS RFCs
				`@ -0,0 +1 @@`
				`Awl aims to be compatible with the littany of DNS tools available.`