diff options
Diffstat (limited to 'network/dog/dog.1')
| -rw-r--r-- | network/dog/dog.1 | 268 |
1 files changed, 268 insertions, 0 deletions
diff --git a/network/dog/dog.1 b/network/dog/dog.1 new file mode 100644 index 000000000000..bf9b516b8620 --- /dev/null +++ b/network/dog/dog.1 @@ -0,0 +1,268 @@ +.\" Automatically generated by Pandoc 3.1.6 +.\" +.\" Define V font for inline verbatim, using C font in formats +.\" that render this, and otherwise B font. +.ie "\f[CB]x\f[]"x" \{\ +. ftr V B +. ftr VI BI +. ftr VB B +. ftr VBI BI +.\} +.el \{\ +. ftr V CR +. ftr VI CI +. ftr VB CB +. ftr VBI CBI +.\} +.TH "dog" "1" "" "v0.1.0" "" +.hy +.SH NAME +.PP +dog \[em] a command-line DNS client +.SH SYNOPSIS +.PP +\f[V]dog [options] [domains...]\f[R] +.PP +\f[B]dog\f[R] is a command-line DNS client. +It has colourful output, supports the DNS-over-TLS and DNS-over-HTTPS +protocols, and can emit JSON. +.SH EXAMPLES +.TP +\f[V]dog example.net\f[R] +Query the \f[V]A\f[R] record of a domain using default settings +.TP +\f[V]dog example.net MX\f[R] +\&...looking up \f[V]MX\f[R] records instead +.TP +\f[V]dog example.net MX \[at]1.1.1.1\f[R] +\&...using a specific nameserver instead +.TP +\f[V]dog example.net MX \[at]1.1.1.1 -T\f[R] +\&...using TCP rather than UDP +.TP +\f[V]dog -q example.net -t MX -n 1.1.1.1 -T\f[R] +As above, but using explicit arguments +.SH QUERY OPTIONS +.TP +\f[V]-q\f[R], \f[V]--query=HOST\f[R] +Host name or domain name to query. +.TP +\f[V]-t\f[R], \f[V]--type=TYPE\f[R] +Type of the DNS record being queried (\f[V]A\f[R], \f[V]MX\f[R], +\f[V]NS\f[R]\&...) +.TP +\f[V]-n\f[R], \f[V]--nameserver=ADDR\f[R] +Address of the nameserver to send packets to. +.TP +\f[V]--class=CLASS\f[R] +Network class of the DNS record being queried (\f[V]IN\f[R], +\f[V]CH\f[R], \f[V]HS\f[R]) +.PP +By default, dog will request A records using the system default +resolver. +At least one domain name must be passed \[em] dog will not automatically +query the root nameservers. +.PP +Query options passed in using a command-line option, such as +`\f[V]--query lookup.dog\f[R]' or `\f[V]--type MX\f[R]', or as plain +arguments, such as `\f[V]lookup.dog\f[R]' or `\f[V]MX\f[R]'. +dog will make an intelligent guess as to what plain arguments mean +(\f[V]MX\f[R] is quite clearly a type), which makes it easier to compose +ad-hoc queries quickly. +If precision is desired, use the long-form options. +.PP +If more than one domain, type, nameserver, or class is specified, dog +will perform one query for each combination, and display the combined +results in a table. +For example, passing three type arguments and two domain name arguments +will send six requests. +.PP +DNS traditionally uses port 53 for both TCP and UDP. +To use a resolver with a different port, include the port number after a +colon (\f[V]:\f[R]) in the nameserver address. +.SH SENDING OPTIONS +.TP +\f[V]--edns=SETTING\f[R] +Whether to opt in to DNS. +This can be `\f[V]disable\f[R]', `\f[V]hide\f[R]', or `\f[V]show\f[R]'. +.TP +\f[V]--txid=NUMBER\f[R] +Set the transaction ID to a specific value. +.TP +\f[V]-Z=TWEAKS\f[R] +Set uncommon protocol-level tweaks. +.SH TRANSPORT OPTIONS +.TP +\f[V]-U\f[R], \f[V]--udp\f[R] +Use the DNS protocol over UDP. +.TP +\f[V]-T\f[R], \f[V]--tcp\f[R] +Use the DNS protocol over TCP. +.TP +\f[V]-S\f[R], \f[V]--tls\f[R] +Use the DNS-over-TLS protocol. +.TP +\f[V]-H\f[R], \f[V]--https\f[R] +Use the DNS-over-HTTPS protocol. +.PP +By default, dog will use the UDP protocol, automatically re-sending the +request using TCP if the response indicates that the message is too +large for UDP. +Passing \f[V]--udp\f[R] will only use UDP and will fail in this case; +passing \f[V]--tcp\f[R] will use TCP by default. +.PP +The DNS-over-TLS (DoT) and DNS-over-HTTPS (DoH) protocols are available +with the \f[V]--tls\f[R] and \f[V]--https\f[R] options. +Bear in mind that the system default resolver is unlikely to respond to +requests using these protocols. +.PP +Note that if a hostname or domain name is given as a nameserver, rather +than an IP address, the resolution of that host is performed by the +operating system, \f[I]not\f[R] by dog. +.PP +Unlike the others, the HTTPS transport type requires an entire URL, +complete with protocol, domain name, and path. +.SH OUTPUT OPTIONS +.TP +\f[V]-1\f[R], \f[V]--short\f[R] +Short mode: display nothing but the first result. +.TP +\f[V]-J\f[R], \f[V]--json\f[R] +Display the output as JSON. +.TP +\f[V]--color\f[R], \f[V]--colour=WHEN\f[R] +When to colourise the output. +This can be `\f[V]always\f[R]', `\f[V]automatic\f[R]', or +`\f[V]never\f[R]'. +.TP +\f[V]--seconds\f[R] +Do not format durations as hours and minutes; instead, display them as +seconds. +.TP +\f[V]--time\f[R] +Print how long the response took to arrive. +.SH META OPTIONS +.TP +\f[V]--help\f[R] +Displays an overview of the command-line options. +.TP +\f[V]--version\f[R] +Displays the version of dog being invoked. +.SH ENVIRONMENT VARIABLES +.PP +dog responds to the following environment variables: +.SS \f[V]DOG_DEBUG\f[R] +.PP +Set this to any non-empty value to have dog emit debugging information +to standard error. +For more in-depth output, set this to the exact string +`\f[V]trace\f[R]'. +.SH RECORD TYPES +.PP +dog understands and can interpret the following record types: +.TP +\f[V]A\f[R] +IPv4 addresses +.TP +\f[V]AAAA\f[R] +IPv6 addresses +.TP +\f[V]CAA\f[R] +permitted certificate authorities +.TP +\f[V]CNAME\f[R] +canonical domain aliases +.TP +\f[V]HINFO\f[R] +system information and, sometimes, forbidden request explanations +.TP +\f[V]LOC\f[R] +location information +.TP +\f[V]MX\f[R] +e-mail server addresses +.TP +\f[V]NAPTR\f[R] +DDDS rules +.TP +\f[V]NS\f[R] +domain name servers +.TP +\f[V]OPT\f[R] +extensions to the DNS protocol +.TP +\f[V]PTR\f[R] +pointers to canonical names, usually for reverse lookups +.TP +\f[V]SOA\f[R] +administrative information about zones +.TP +\f[V]SRV\f[R] +IP addresses with port numbers +.TP +\f[V]SSHFP\f[R] +SSH key fingerprints +.TP +\f[V]TLSA\f[R] +TLS certificates, public keys, and hashes +.TP +\f[V]TXT\f[R] +arbitrary textual information +.PP +When a response DNS packet contains a record of one of these known +types, dog will display it in a table containing the type name and a +human-readable summary of its contents. +.PP +Records with a type number that does not map to any known record type +will still be displayed. +As they cannot be interpreted, their contents will be displayed as a +series of numbers instead. +.PP +dog also contains a list of record type names that it knows the type +number of, but is not able to interpret, such as \f[V]IXFR\f[R] or +\f[V]ANY\f[R] or \f[V]AFSDB\f[R]. +These are acceptable as command-line arguments, meaning you can send an +AFSDB request with `\f[V]dog AFSDB\f[R]'. +However, their response contents will still be displayed as numbers. +They may be supported in future versions of dog. +.SH PROTOCOL TWEAKS +.PP +The \f[V]-Z\f[R] command-line argument can be used one or more times to +set some protocol-level options in the DNS queries that get sent. +It accepts the following values: +.TP +\f[V]aa\f[R] +Sets the \f[V]AA\f[R] (Authoritative Answers) bit in the query. +.TP +\f[V]ad\f[R] +Sets the \f[V]AD\f[R] (Authentic Data) bit in the query. +.TP +\f[V]bufsize=NUM\f[R] +Sets the UDP payload size field in the OPT field in the query. +This has no effect if EDNS is diabled. +.TP +\f[V]cd\f[R] +Sets the \f[V]CD\f[R] (Checking Disabled) bit in the query. +.SH EXIT STATUSES +.TP +0 +If everything goes OK. +.TP +1 +If there was a network, I/O, or TLS error during operation. +.TP +2 +If there is no result from the server when running in short mode. +This can be any received server error, not just NXDOMAIN. +.TP +3 +If there was a problem with the command-line arguments. +.SH AUTHOR +.PP +dog is maintained by Benjamin `ogham' Sago. +.PP +\f[B]Website:\f[R] \f[V]https://dns.lookup.dog/\f[R] +.PD 0 +.P +.PD +\f[B]Source code:\f[R] \f[V]https://github.com/ogham/dog\f[R] |