path: root/network/dog/dog.1

.\" 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]