| blob | 294436e3684afe9f4c18724c81d6d7e6cd213df3 |
1 .\" Automatically generated by Pandoc 2.17.1.1
2 .\"
3 .\" Define V font for inline verbatim, using C font in formats
4 .\" that render this, and otherwise B font.
5 .ie "\f[CB]x\f[]"x" \{\
6 . ftr V B
7 . ftr VI BI
8 . ftr VB B
9 . ftr VBI BI
10 .\}
11 .el \{\
12 . ftr V CR
13 . ftr VI CI
14 . ftr VB CB
15 . ftr VBI CBI
16 .\}
17 .TH "dog" "1" "" "v0.1.0" ""
18 .hy
19 .SH NAME
20 .PP
21 dog \[em] a command-line DNS client
22 .SH SYNOPSIS
23 .PP
24 \f[V]dog [options] [domains...]\f[R]
25 .PP
26 \f[B]dog\f[R] is a command-line DNS client.
27 It has colourful output, supports the DNS-over-TLS and DNS-over-HTTPS
28 protocols, and can emit JSON.
29 .SH EXAMPLES
30 .TP
31 \f[V]dog example.net\f[R]
32 Query the \f[V]A\f[R] record of a domain using default settings
33 .TP
34 \f[V]dog example.net MX\f[R]
35 \&...looking up \f[V]MX\f[R] records instead
36 .TP
37 \f[V]dog example.net MX \[at]1.1.1.1\f[R]
38 \&...using a specific nameserver instead
39 .TP
40 \f[V]dog example.net MX \[at]1.1.1.1 -T\f[R]
41 \&...using TCP rather than UDP
42 .TP
43 \f[V]dog -q example.net -t MX -n 1.1.1.1 -T\f[R]
44 As above, but using explicit arguments
45 .SH QUERY OPTIONS
46 .TP
47 \f[V]-q\f[R], \f[V]--query=HOST\f[R]
48 Host name or domain name to query.
49 .TP
50 \f[V]-t\f[R], \f[V]--type=TYPE\f[R]
51 Type of the DNS record being queried (\f[V]A\f[R], \f[V]MX\f[R],
52 \f[V]NS\f[R]\&...)
53 .TP
54 \f[V]-n\f[R], \f[V]--nameserver=ADDR\f[R]
55 Address of the nameserver to send packets to.
56 .TP
57 \f[V]--class=CLASS\f[R]
58 Network class of the DNS record being queried (\f[V]IN\f[R],
59 \f[V]CH\f[R], \f[V]HS\f[R])
60 .PP
61 By default, dog will request A records using the system default
62 resolver.
63 At least one domain name must be passed \[em] dog will not automatically
64 query the root nameservers.
65 .PP
66 Query options passed in using a command-line option, such as
67 `\f[V]--query lookup.dog\f[R]' or `\f[V]--type MX\f[R]', or as plain
68 arguments, such as `\f[V]lookup.dog\f[R]' or `\f[V]MX\f[R]'.
69 dog will make an intelligent guess as to what plain arguments mean
70 (\f[V]MX\f[R] is quite clearly a type), which makes it easier to compose
71 ad-hoc queries quickly.
72 If precision is desired, use the long-form options.
73 .PP
74 If more than one domain, type, nameserver, or class is specified, dog
75 will perform one query for each combination, and display the combined
76 results in a table.
77 For example, passing three type arguments and two domain name arguments
78 will send six requests.
79 .PP
80 DNS traditionally uses port 53 for both TCP and UDP.
81 To use a resolver with a different port, include the port number after a
82 colon (\f[V]:\f[R]) in the nameserver address.
83 .SH SENDING OPTIONS
84 .TP
85 \f[V]--edns=SETTING\f[R]
86 Whether to opt in to DNS.
87 This can be `\f[V]disable\f[R]', `\f[V]hide\f[R]', or `\f[V]show\f[R]'.
88 .TP
89 \f[V]--txid=NUMBER\f[R]
90 Set the transaction ID to a specific value.
91 .TP
92 \f[V]-Z=TWEAKS\f[R]
93 Set uncommon protocol-level tweaks.
94 .SH TRANSPORT OPTIONS
95 .TP
96 \f[V]-U\f[R], \f[V]--udp\f[R]
97 Use the DNS protocol over UDP.
98 .TP
99 \f[V]-T\f[R], \f[V]--tcp\f[R]
100 Use the DNS protocol over TCP.
101 .TP
102 \f[V]-S\f[R], \f[V]--tls\f[R]
103 Use the DNS-over-TLS protocol.
104 .TP
105 \f[V]-H\f[R], \f[V]--https\f[R]
106 Use the DNS-over-HTTPS protocol.
107 .PP
108 By default, dog will use the UDP protocol, automatically re-sending the
109 request using TCP if the response indicates that the message is too
110 large for UDP.
111 Passing \f[V]--udp\f[R] will only use UDP and will fail in this case;
112 passing \f[V]--tcp\f[R] will use TCP by default.
113 .PP
114 The DNS-over-TLS (DoT) and DNS-over-HTTPS (DoH) protocols are available
115 with the \f[V]--tls\f[R] and \f[V]--https\f[R] options.
116 Bear in mind that the system default resolver is unlikely to respond to
117 requests using these protocols.
118 .PP
119 Note that if a hostname or domain name is given as a nameserver, rather
120 than an IP address, the resolution of that host is performed by the
121 operating system, \f[I]not\f[R] by dog.
122 .PP
123 Unlike the others, the HTTPS transport type requires an entire URL,
124 complete with protocol, domain name, and path.
125 .SH OUTPUT OPTIONS
126 .TP
127 \f[V]-1\f[R], \f[V]--short\f[R]
128 Short mode: display nothing but the first result.
129 .TP
130 \f[V]-J\f[R], \f[V]--json\f[R]
131 Display the output as JSON.
132 .TP
133 \f[V]--color\f[R], \f[V]--colour=WHEN\f[R]
134 When to colourise the output.
135 This can be `\f[V]always\f[R]', `\f[V]automatic\f[R]', or
136 `\f[V]never\f[R]'.
137 .TP
138 \f[V]--seconds\f[R]
139 Do not format durations as hours and minutes; instead, display them as
140 seconds.
141 .TP
142 \f[V]--time\f[R]
143 Print how long the response took to arrive.
144 .SH META OPTIONS
145 .TP
146 \f[V]--help\f[R]
147 Displays an overview of the command-line options.
148 .TP
149 \f[V]--version\f[R]
150 Displays the version of dog being invoked.
151 .SH ENVIRONMENT VARIABLES
152 .PP
153 dog responds to the following environment variables:
154 .SS \f[V]DOG_DEBUG\f[R]
155 .PP
156 Set this to any non-empty value to have dog emit debugging information
157 to standard error.
158 For more in-depth output, set this to the exact string
159 `\f[V]trace\f[R]'.
160 .SH RECORD TYPES
161 .PP
162 dog understands and can interpret the following record types:
163 .TP
164 \f[V]A\f[R]
165 IPv4 addresses
166 .TP
167 \f[V]AAAA\f[R]
168 IPv6 addresses
169 .TP
170 \f[V]CAA\f[R]
171 permitted certificate authorities
172 .TP
173 \f[V]CNAME\f[R]
174 canonical domain aliases
175 .TP
176 \f[V]HINFO\f[R]
177 system information and, sometimes, forbidden request explanations
178 .TP
179 \f[V]LOC\f[R]
180 location information
181 .TP
182 \f[V]MX\f[R]
183 e-mail server addresses
184 .TP
185 \f[V]NAPTR\f[R]
186 DDDS rules
187 .TP
188 \f[V]NS\f[R]
189 domain name servers
190 .TP
191 \f[V]OPT\f[R]
192 extensions to the DNS protocol
193 .TP
194 \f[V]PTR\f[R]
195 pointers to canonical names, usually for reverse lookups
196 .TP
197 \f[V]SOA\f[R]
198 administrative information about zones
199 .TP
200 \f[V]SRV\f[R]
201 IP addresses with port numbers
202 .TP
203 \f[V]SSHFP\f[R]
204 SSH key fingerprints
205 .TP
206 \f[V]TLSA\f[R]
207 TLS certificates, public keys, and hashes
208 .TP
209 \f[V]TXT\f[R]
210 arbitrary textual information
211 .PP
212 When a response DNS packet contains a record of one of these known
213 types, dog will display it in a table containing the type name and a
214 human-readable summary of its contents.
215 .PP
216 Records with a type number that does not map to any known record type
217 will still be displayed.
218 As they cannot be interpreted, their contents will be displayed as a
219 series of numbers instead.
220 .PP
221 dog also contains a list of record type names that it knows the type
222 number of, but is not able to interpret, such as \f[V]IXFR\f[R] or
223 \f[V]ANY\f[R] or \f[V]AFSDB\f[R].
224 These are acceptable as command-line arguments, meaning you can send an
225 AFSDB request with `\f[V]dog AFSDB\f[R]'.
226 However, their response contents will still be displayed as numbers.
227 They may be supported in future versions of dog.
228 .SH PROTOCOL TWEAKS
229 .PP
230 The \f[V]-Z\f[R] command-line argument can be used one or more times to
231 set some protocol-level options in the DNS queries that get sent.
232 It accepts the following values:
233 .TP
234 \f[V]aa\f[R]
235 Sets the \f[V]AA\f[R] (Authoritative Answers) bit in the query.
236 .TP
237 \f[V]ad\f[R]
238 Sets the \f[V]AD\f[R] (Authentic Data) bit in the query.
239 .TP
240 \f[V]bufsize=NUM\f[R]
241 Sets the UDP payload size field in the OPT field in the query.
242 This has no effect if EDNS is diabled.
243 .TP
244 \f[V]cd\f[R]
245 Sets the \f[V]CD\f[R] (Checking Disabled) bit in the query.
246 .SH EXIT STATUSES
247 .TP
248 0
249 If everything goes OK.
250 .TP
251 1
252 If there was a network, I/O, or TLS error during operation.
253 .TP
254 2
255 If there is no result from the server when running in short mode.
256 This can be any received server error, not just NXDOMAIN.
257 .TP
258 3
259 If there was a problem with the command-line arguments.
260 .SH AUTHOR
261 .PP
262 dog is maintained by Benjamin `ogham' Sago.
263 .PP
264 \f[B]Website:\f[R] \f[V]https://dns.lookup.dog/\f[R]
265 .PD 0
266 .P
267 .PD
268 \f[B]Source code:\f[R] \f[V]https://github.com/ogham/dog\f[R]