269 lines
7.3 KiB
Groff
269 lines
7.3 KiB
Groff
.\" 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]
|