man_kdig.rst 8.95 KB
Newer Older
1 2
.. highlight:: console

3 4
kdig – Advanced DNS lookup utility
==================================
Jan Včelák's avatar
Jan Včelák committed
5 6 7 8 9 10

Synopsis
--------

:program:`kdig` [*common-settings*] [*query* [*settings*]]...

11
:program:`kdig` **-h**
Jan Včelák's avatar
Jan Včelák committed
12 13 14 15 16 17 18 19

Description
-----------

This utility sends one or more DNS queries to a nameserver. Each query can have
individual *settings*, or it can be specified globally via *common-settings*,
which must precede *query* specification.

Daniel Salzman's avatar
Daniel Salzman committed
20 21 22
Parameters
..........

Jan Včelák's avatar
Jan Včelák committed
23
*query*
24
  *name* | **-q** *name* | **-x** *address* | **-G** *tapfile*
Jan Včelák's avatar
Jan Včelák committed
25 26

*common-settings*, *settings*
Libor Peltan's avatar
Libor Peltan committed
27
  [*query_class*] [*query_type*] [**@**\ *server*]... [*options*]
Jan Včelák's avatar
Jan Včelák committed
28 29 30 31 32 33 34 35 36 37

*name*
  Is a domain name that is to be looked up.

*server*
  Is a domain name or an IPv4 or IPv6 address of the nameserver to send a query
  to. An additional port can be specified using address:port ([address]:port
  for IPv6 address), address@port, or address#port notation. If no server is
  specified, the servers from :file:`/etc/resolv.conf` are used.

Daniel Salzman's avatar
Daniel Salzman committed
38
If no arguments are provided, :program:`kdig` sends NS query for the root
39
zone.
Jan Včelák's avatar
Jan Včelák committed
40

Libor Peltan's avatar
Libor Peltan committed
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
Query classes
.............

A *query_class* can be either a DNS class name (IN, CH) or generic class
specification **CLASS**\ *XXXXX* where *XXXXX* is a corresponding decimal
class number. The default query class is IN.

Query types
...........

A *query_type* can be either a DNS resource record type
(A, AAAA, NS, SOA, DNSKEY, ANY, etc.) or one of the following:

**TYPE**\ *XXXXX*
  Generic query type specification where *XXXXX* is a corresponding decimal
  type number.

**AXFR**
  Full zone transfer request.

**IXFR=**\ *serial*
  Incremental zone transfer request for specified starting SOA serial number.

**NOTIFY=**\ *serial*
  Notify message with a SOA serial hint specified.

**NOTIFY**
  Notify message with a SOA serial hint unspecified.

The default query type is A.

Jan Včelák's avatar
Jan Včelák committed
72
Options
Daniel Salzman's avatar
Daniel Salzman committed
73
.......
Jan Včelák's avatar
Jan Včelák committed
74

75
**-4**
76
  Use the IPv4 protocol only.
Jan Včelák's avatar
Jan Včelák committed
77

78
**-6**
79
  Use the IPv6 protocol only.
Jan Včelák's avatar
Jan Včelák committed
80

81 82
**-b** *address*
  Set the source IP address of the query to *address*. The address must be a
83 84
  valid address for local interface or :: or 0.0.0.0. An optional port
  can be specified in the same format as the *server* value.
Jan Včelák's avatar
Jan Včelák committed
85

86
**-c** *class*
Libor Peltan's avatar
Libor Peltan committed
87
  An explicit *query_class* specification. See possible values above.
Jan Včelák's avatar
Jan Včelák committed
88

89
**-d**
Daniel Salzman's avatar
Daniel Salzman committed
90
  Enable debug messages.
Jan Včelák's avatar
Jan Včelák committed
91

92
**-h**, **--help**
93
  Print the program help.
Jan Včelák's avatar
Jan Včelák committed
94

95
**-k** *keyfile*
96 97
  Use the TSIG key stored in a file *keyfile* to authenticate the request. The
  file must contain the key in the same format as accepted by the
98
  **-y** option.
Jan Včelák's avatar
Jan Včelák committed
99

100
**-p** *port*
101
  Set the nameserver port number or service name to send a query to. The default
Daniel Salzman's avatar
Daniel Salzman committed
102
  port is 53.
Jan Včelák's avatar
Jan Včelák committed
103

104
**-q** *name*
105 106
  Set the query name. An explicit variant of *name* specification. If no *name*
  is provided, empty question section is set.
Jan Včelák's avatar
Jan Včelák committed
107

108
**-t** *type*
Libor Peltan's avatar
Libor Peltan committed
109
  An explicit *query_type* specification. See possible values above.
Jan Včelák's avatar
Jan Včelák committed
110

111
**-V**, **--version**
112
  Print the program version.
Jan Včelák's avatar
Jan Včelák committed
113

114
**-x** *address*
115
  Send a reverse (PTR) query for IPv4 or IPv6 *address*. The correct name, class
116
  and type is set automatically.
Jan Včelák's avatar
Jan Včelák committed
117

Daniel Salzman's avatar
Daniel Salzman committed
118
**-y** [*alg*:]\ *name*:*key*
119
  Use the TSIG key named *name* to authenticate the request. The *alg*
120
  part specifies the algorithm (the default is hmac-sha256) and *key* specifies
121
  the shared secret encoded in Base64.
Jan Včelák's avatar
Jan Včelák committed
122

123
**-E** *tapfile*
Jan Včelák's avatar
Jan Včelák committed
124
  Export a dnstap trace of the query and response messages received to the
125
  file *tapfile*.
Jan Včelák's avatar
Jan Včelák committed
126

127 128
**-G** *tapfile*
  Generate message output from a previously saved dnstap file *tapfile*.
Jan Včelák's avatar
Jan Včelák committed
129

130
**+**\ [\ **no**\ ]\ **multiline**
Jan Včelák's avatar
Jan Včelák committed
131 132
  Wrap long records to more lines and improve human readability.

133
**+**\ [\ **no**\ ]\ **short**
Jan Včelák's avatar
Jan Včelák committed
134 135
  Show record data only.

136 137 138 139
**+**\ [\ **no**\ ]\ **generic**
  Use the generic representation format when printing resource record types
  and data.

140 141 142
**+**\ [\ **no**\ ]\ **crypto**
  Display the DNSSEC keys and signatures values in hexdump, instead of omitting them.

143
**+**\ [\ **no**\ ]\ **aaflag**
144
  Set the AA flag.
Jan Včelák's avatar
Jan Včelák committed
145

146
**+**\ [\ **no**\ ]\ **tcflag**
147
  Set the TC flag.
Jan Včelák's avatar
Jan Včelák committed
148

149
**+**\ [\ **no**\ ]\ **rdflag**
150
  Set the RD flag.
Jan Včelák's avatar
Jan Včelák committed
151

152 153
**+**\ [\ **no**\ ]\ **recurse**
  Same as **+**\ [\ **no**\ ]\ **rdflag**
Jan Včelák's avatar
Jan Včelák committed
154

155
**+**\ [\ **no**\ ]\ **raflag**
156
  Set the RA flag.
Jan Včelák's avatar
Jan Včelák committed
157

158
**+**\ [\ **no**\ ]\ **zflag**
159
  Set the zero flag bit.
Jan Včelák's avatar
Jan Včelák committed
160

161
**+**\ [\ **no**\ ]\ **adflag**
162
  Set the AD flag.
Jan Včelák's avatar
Jan Včelák committed
163

164
**+**\ [\ **no**\ ]\ **cdflag**
165
  Set the CD flag.
Jan Včelák's avatar
Jan Včelák committed
166

167
**+**\ [\ **no**\ ]\ **dnssec**
168
  Set the DO flag.
Jan Včelák's avatar
Jan Včelák committed
169

170
**+**\ [\ **no**\ ]\ **all**
Jan Včelák's avatar
Jan Včelák committed
171 172
  Show all packet sections.

173
**+**\ [\ **no**\ ]\ **qr**
174
  Show the query packet.
Jan Včelák's avatar
Jan Včelák committed
175

176
**+**\ [\ **no**\ ]\ **header**
177
  Show the packet header.
Jan Včelák's avatar
Jan Včelák committed
178

179 180 181
**+**\ [\ **no**\ ]\ **comments**
  Show commented section names.

182
**+**\ [\ **no**\ ]\ **opt**
183
  Show the EDNS pseudosection.
Jan Včelák's avatar
Jan Včelák committed
184

185
**+**\ [\ **no**\ ]\ **question**
186
  Show the question section.
Jan Včelák's avatar
Jan Včelák committed
187

188
**+**\ [\ **no**\ ]\ **answer**
189
  Show the answer section.
Jan Včelák's avatar
Jan Včelák committed
190

191
**+**\ [\ **no**\ ]\ **authority**
192
  Show the authority section.
Jan Včelák's avatar
Jan Včelák committed
193

194
**+**\ [\ **no**\ ]\ **additional**
195
  Show the additional section.
Jan Včelák's avatar
Jan Včelák committed
196

197
**+**\ [\ **no**\ ]\ **tsig**
198
  Show the TSIG pseudosection.
Jan Včelák's avatar
Jan Včelák committed
199

200
**+**\ [\ **no**\ ]\ **stats**
Jan Včelák's avatar
Jan Včelák committed
201 202
  Show trailing packet statistics.

203
**+**\ [\ **no**\ ]\ **class**
204
  Show the DNS class.
Jan Včelák's avatar
Jan Včelák committed
205

206
**+**\ [\ **no**\ ]\ **ttl**
207
  Show the TTL value.
Jan Včelák's avatar
Jan Včelák committed
208

209
**+**\ [\ **no**\ ]\ **tcp**
210
  Use the TCP protocol (default is UDP for standard query and TCP for AXFR/IXFR).
Jan Včelák's avatar
Jan Včelák committed
211

212 213 214
**+**\ [\ **no**\ ]\ **fastopen**
  Use TCP Fast Open (default with TCP).

215
**+**\ [\ **no**\ ]\ **ignore**
216
  Don't use TCP automatically if a truncated reply is received.
Jan Včelák's avatar
Jan Včelák committed
217

218
**+**\ [\ **no**\ ]\ **tls**
219
  Use TLS with the Opportunistic privacy profile (:rfc:`7858#section-4.1`).
220 221

**+**\ [\ **no**\ ]\ **tls-ca**\[\ =\ *FILE*\]
222 223 224
  Use TLS with a certificate validation. Certification authority certificates
  are loaded from the specified PEM file (default is system certificate storage
  if no argument is provided).
225 226
  Can be specified multiple times. If the +tls-hostname option is not provided,
  the name of the target server (if specified) is used for strict authentication.
227 228

**+**\ [\ **no**\ ]\ **tls-pin**\ =\ *BASE64*
229 230 231
  Use TLS with the Out-of-Band key-pinned privacy profile (:rfc:`7858#section-4.2`).
  The PIN must be a Base64 encoded SHA-256 hash of the X.509 SubjectPublicKeyInfo.
  Can be specified multiple times.
232 233 234 235

**+**\ [\ **no**\ ]\ **tls-hostname**\ =\ *STR*
  Use TLS with a remote server hostname check.

236 237 238
**+**\ [\ **no**\ ]\ **tls-sni**\ =\ *STR*
  Use TLS with a Server Name Indication.

239
**+**\ [\ **no**\ ]\ **nsid**
240
  Request the nameserver identifier (NSID).
Jan Včelák's avatar
Jan Včelák committed
241

242
**+**\ [\ **no**\ ]\ **bufsize**\ =\ *B*
243
  Set EDNS buffer size in bytes (default is 512 bytes).
Jan Včelák's avatar
Jan Včelák committed
244

245 246 247 248 249 250
**+**\ [\ **no**\ ]\ **padding**\[\ =\ *B*\]
  Use EDNS(0) padding option to pad queries, optionally to a specific
  size. The default is to pad queries with a sensible amount when using
  +tls, and not to pad at all when queries are sent without TLS.  With
  no argument (i.e., just +padding) pad every query with a sensible
  amount regardless of the use of TLS. With +nopadding, never pad.
251 252 253 254 255

**+**\ [\ **no**\ ]\ **alignment**\[\ =\ *B*\]
  Align the query to B\-byte-block message using the EDNS(0) padding option
  (default is no or 128 if no argument is specified).

256 257
**+**\ [\ **no**\ ]\ **subnet**\ =\ *SUBN*
  Set EDNS(0) client subnet SUBN=addr/prefix.
Jan Včelák's avatar
Jan Včelák committed
258

259 260 261
**+**\ [\ **no**\ ]\ **edns**\[\ =\ *N*\]
  Use EDNS version (default is 0).

262
**+**\ [\ **no**\ ]\ **timeout**\ =\ *T*
263 264
  Set the wait-for-reply interval in seconds (default is 5 seconds). This timeout
  applies to each query attempt.
Jan Včelák's avatar
Jan Včelák committed
265

266
**+**\ [\ **no**\ ]\ **retry**\ =\ *N*
267
  Set the number (>=0) of UDP retries (default is 2). This doesn't apply to
Jan Včelák's avatar
Jan Včelák committed
268 269
  AXFR/IXFR.

Mark Karpilovskij's avatar
Mark Karpilovskij committed
270 271 272 273 274 275
**+**\ [\ **no**\ ]\ **cookie**\ =\ *HEX*
   Attach EDNS(0) cookie to the query.

**+**\ [\ **no**\ ]\ **badcookie**
  Repeat a query with the correct cookie.

276 277 278
**+**\ [\ **no**\ ]\ **ednsopt**\[\ =\ *CODE*\[:*HEX*\]\]
  Send custom EDNS option. The *CODE* is EDNS option code in decimal, *HEX*
  is an optional hex encoded string to use as EDNS option value. This argument
Daniel Salzman's avatar
Daniel Salzman committed
279
  can be used multiple times. +noednsopt clears all EDNS options specified by
280 281
  +ednsopt.

282 283 284
**+noidn**
  Disable the IDN transformation to ASCII and vice versa. IDNA2003 support depends
  on libidn availability during project building!
Jan Včelák's avatar
Jan Včelák committed
285 286 287 288

Notes
-----

289
Options **-k** and **-y** can not be used simultaneously.
Jan Včelák's avatar
Jan Včelák committed
290

291 292
Dnssec-keygen keyfile format is not supported. Use :manpage:`keymgr(8)` instead.

Jan Včelák's avatar
Jan Včelák committed
293 294 295
Examples
--------

296
1. Get A records for example.com::
Jan Včelák's avatar
Jan Včelák committed
297

298
     $ kdig example.com A
Jan Včelák's avatar
Jan Včelák committed
299

300
2. Perform AXFR for zone example.com from the server 192.0.2.1::
Jan Včelák's avatar
Jan Včelák committed
301

302
     $ kdig example.com -t AXFR @192.0.2.1
Jan Včelák's avatar
Jan Včelák committed
303

304 305
3. Get A records for example.com from 192.0.2.1 and reverse lookup for address
   2001:DB8::1 from 192.0.2.2. Both using the TCP protocol::
Jan Včelák's avatar
Jan Včelák committed
306

307
     $ kdig +tcp example.com -t A @192.0.2.1 -x 2001:DB8::1 @192.0.2.2
Jan Včelák's avatar
Jan Včelák committed
308

309 310 311 312 313 314 315
4. Get SOA record for example.com, use TLS, use system certificates, check
   for specified hostname, check for certificate pin, and print additional
   debug info::

     $ kdig -d @185.49.141.38 +tls-ca +tls-host=getdnsapi.net \
       +tls-pin=foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc9S= soa example.com

Jan Včelák's avatar
Jan Včelák committed
316 317 318 319 320 321 322 323
Files
-----

:file:`/etc/resolv.conf`

See Also
--------

324
:manpage:`khost(1)`, :manpage:`knsupdate(1)`, :manpage:`keymgr(8)`.