]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - contrib/bind9/bin/dig/dig.docbook
This commit was generated by cvs2svn to compensate for changes in r135923,
[FreeBSD/FreeBSD.git] / contrib / bind9 / bin / dig / dig.docbook
1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2 <!--
3  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
4  - Copyright (C) 2000-2003  Internet Software Consortium.
5  -
6  - Permission to use, copy, modify, and distribute this software for any
7  - purpose with or without fee is hereby granted, provided that the above
8  - copyright notice and this permission notice appear in all copies.
9  -
10  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
11  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
12  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
13  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
14  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
15  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
16  - PERFORMANCE OF THIS SOFTWARE.
17 -->
18
19 <!-- $Id: dig.docbook,v 1.4.2.7.4.9 2004/06/23 04:19:41 marka Exp $ -->
20
21 <refentry>
22
23 <refentryinfo>
24 <date>Jun 30, 2000</date>
25 </refentryinfo>
26
27 <refmeta>
28 <refentrytitle>dig</refentrytitle>
29 <manvolnum>1</manvolnum>
30 <refmiscinfo>BIND9</refmiscinfo>
31 </refmeta>
32
33 <refnamediv>
34 <refname>dig</refname>
35 <refpurpose>DNS lookup utility</refpurpose>
36 </refnamediv>
37
38 <refsynopsisdiv>
39 <cmdsynopsis>
40 <command>dig</command>
41 <arg choice=opt>@server</arg>
42 <arg><option>-b <replaceable class="parameter">address</replaceable></option></arg>
43 <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
44 <arg><option>-f <replaceable class="parameter">filename</replaceable></option></arg>
45 <arg><option>-k <replaceable class="parameter">filename</replaceable></option></arg>
46 <arg><option>-p <replaceable class="parameter">port#</replaceable></option></arg>
47 <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
48 <arg><option>-x <replaceable class="parameter">addr</replaceable></option></arg>
49 <arg><option>-y <replaceable class="parameter">name:key</replaceable></option></arg>
50 <arg><option>-4</option></arg>
51 <arg><option>-6</option></arg>
52 <arg choice=opt>name</arg>
53 <arg choice=opt>type</arg>
54 <arg choice=opt>class</arg>
55 <arg choice=opt rep=repeat>queryopt</arg>
56 </cmdsynopsis>
57
58 <cmdsynopsis>
59 <command>dig</command>
60 <arg><option>-h</option></arg>
61 </cmdsynopsis>
62
63 <cmdsynopsis>
64 <command>dig</command>
65 <arg choice=opt rep=repeat>global-queryopt</arg>
66 <arg choice=opt rep=repeat>query</arg>
67 </cmdsynopsis>
68 </refsynopsisdiv>
69
70 <refsect1>
71 <title>DESCRIPTION</title>
72 <para>
73 <command>dig</command> (domain information groper) is a flexible tool
74 for interrogating DNS name servers.  It performs DNS lookups and
75 displays the answers that are returned from the name server(s) that
76 were queried.  Most DNS administrators use <command>dig</command> to
77 troubleshoot DNS problems because of its flexibility, ease of use and
78 clarity of output.  Other lookup tools tend to have less functionality
79 than <command>dig</command>.
80 </para>
81
82 <para>
83 Although <command>dig</command> is normally used with command-line
84 arguments, it also has a batch mode of operation for reading lookup
85 requests from a file.  A brief summary of its command-line arguments
86 and options is printed when the <option>-h</option> option is given.
87 Unlike earlier versions, the BIND9 implementation of
88 <command>dig</command> allows multiple lookups to be issued from the
89 command line.
90 </para>
91
92 <para>
93 Unless it is told to query a specific name server,
94 <command>dig</command> will try each of the servers listed in
95 <filename>/etc/resolv.conf</filename>.
96 </para>
97
98 <para>
99 When no command line arguments or options are given, will perform an
100 NS query for "." (the root).
101 </para>
102
103 <para>
104 It is possible to set per-user defaults for <command>dig</command> via
105 <filename>${HOME}/.digrc</filename>.  This file is read and any options in it
106 are applied before the command line arguments.
107 </para>
108
109 </refsect1>
110
111 <refsect1>
112 <title>SIMPLE USAGE</title>
113
114 <para>
115 A typical invocation of <command>dig</command> looks like:
116 <programlisting> dig @server name type </programlisting> where:
117
118 <variablelist>
119
120 <varlistentry><term><constant>server</constant></term>
121 <listitem><para>
122 is the name or IP address of the name server to query.  This can be an IPv4
123 address in dotted-decimal notation or an IPv6
124 address in colon-delimited notation.  When the supplied
125 <parameter>server</parameter> argument is a hostname,
126 <command>dig</command> resolves that name before querying that name
127 server.  If no <parameter>server</parameter> argument is provided,
128 <command>dig</command> consults <filename>/etc/resolv.conf</filename>
129 and queries the name servers listed there.  The reply from the name
130 server that responds is displayed.
131 </para></listitem></varlistentry>
132
133 <varlistentry><term><constant>name</constant></term>
134 <listitem><para>
135 is the name of the resource record that is to be looked up.
136 </para></listitem></varlistentry>
137
138 <varlistentry><term><constant>type</constant></term>
139 <listitem><para>
140 indicates what type of query is required &mdash;
141 ANY, A, MX, SIG, etc.
142 <parameter>type</parameter> can be any valid query type.  If no
143 <parameter>type</parameter> argument is supplied,
144 <command>dig</command> will perform a lookup for an A record.
145 </para></listitem></varlistentry>
146
147 </variablelist>
148 </para>
149
150 </refsect1>
151
152 <refsect1>
153 <title>OPTIONS</title>
154
155 <para>
156 The <option>-b</option> option sets the source IP address of the query
157 to <parameter>address</parameter>.  This must be a valid address on
158 one of the host's network interfaces or "0.0.0.0" or "::".  An optional port
159 may be specified by appending "#&lt;port&gt;"
160 </para>
161
162 <para>
163 The default query class (IN for internet) is overridden by the
164 <option>-c</option> option.  <parameter>class</parameter> is any valid
165 class, such as HS for Hesiod records or CH for CHAOSNET records.
166 </para>
167
168 <para>
169 The <option>-f</option> option makes <command>dig </command> operate
170 in batch mode by reading a list of lookup requests to process from the
171 file <parameter>filename</parameter>.  The file contains a number of
172 queries, one per line.  Each entry in the file should be organised in
173 the same way they would be presented as queries to
174 <command>dig</command> using the command-line interface.
175 </para>
176
177 <para>
178 If a non-standard port number is to be queried, the
179 <option>-p</option> option is used.  <parameter>port#</parameter> is
180 the port number that <command>dig</command> will send its queries
181 instead of the standard DNS port number 53.  This option would be used
182 to test a name server that has been configured to listen for queries
183 on a non-standard port number.
184 </para>
185
186 <para>
187 The <option>-4</option> option forces <command>dig</command> to only
188 use IPv4 query transport.  The <option>-6</option> option forces
189 <command>dig</command> to only use IPv6 query transport.
190 </para>
191
192 <para>
193 The <option>-t</option> option sets the query type to
194 <parameter>type</parameter>.  It can be any valid query type which is
195 supported in BIND9.  The default query type "A", unless the
196 <option>-x</option> option is supplied to indicate a reverse lookup.
197 A zone transfer can be requested by specifying a type of AXFR.  When
198 an incremental zone transfer (IXFR) is required,
199 <parameter>type</parameter> is set to <literal>ixfr=N</literal>.
200 The incremental zone transfer will contain the changes made to the zone
201 since the serial number in the zone's SOA record was
202 <parameter>N</parameter>.
203 </para>
204
205 <para>
206 Reverse lookups - mapping addresses to names - are simplified by the
207 <option>-x</option> option.  <parameter>addr</parameter> is an IPv4
208 address in dotted-decimal notation, or a colon-delimited IPv6 address.
209 When this option is used, there is no need to provide the
210 <parameter>name</parameter>, <parameter>class</parameter> and
211 <parameter>type</parameter> arguments.  <command>dig</command>
212 automatically performs a lookup for a name like
213 <literal>11.12.13.10.in-addr.arpa</literal> and sets the query type and
214 class to PTR and IN respectively.  By default, IPv6 addresses are
215 looked up using nibble format under the IP6.ARPA domain.
216 To use the older RFC1886 method using the IP6.INT domain 
217 specify the <option>-i</option> option.  Bit string labels (RFC2874)
218 are now experimental and are not attempted.
219 </para>
220
221 <para>
222 To sign the DNS queries sent by <command>dig</command> and their
223 responses using transaction signatures (TSIG), specify a TSIG key file
224 using the <option>-k</option> option.  You can also specify the TSIG
225 key itself on the command line using the <option>-y</option> option;
226 <parameter>name</parameter> is the name of the TSIG key and
227 <parameter>key</parameter> is the actual key.  The key is a base-64
228 encoded string, typically generated by <citerefentry>
229 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
230 </citerefentry>.
231
232 Caution should be taken when using the <option>-y</option> option on
233 multi-user systems as the key can be visible in the output from
234 <citerefentry> <refentrytitle>ps</refentrytitle><manvolnum>1
235 </manvolnum> </citerefentry> or in the shell's history file.  When
236 using TSIG authentication with <command>dig</command>, the name
237 server that is queried needs to know the key and algorithm that is
238 being used.  In BIND, this is done by providing appropriate
239 <command>key</command> and <command>server</command> statements in
240 <filename>named.conf</filename>.
241 </para>
242
243 </refsect1>
244
245 <refsect1>
246 <title>QUERY OPTIONS</title>
247
248 <para>
249 <command>dig</command> provides a number of query options which affect
250 the way in which lookups are made and the results displayed.  Some of
251 these set or reset flag bits in the query header, some determine which
252 sections of the answer get printed, and others determine the timeout
253 and retry strategies.
254 </para>
255
256 <para>
257 Each query option is identified by a keyword preceded by a plus sign
258 (<literal>+</literal>).  Some keywords set or reset an option.  These may be preceded
259 by the string <literal>no</literal> to negate the meaning of that keyword.  Other
260 keywords assign values to options like the timeout interval.  They
261 have the form <option>+keyword=value</option>.
262 The query options are:
263
264 <variablelist>
265
266 <varlistentry><term><option>+[no]tcp</option></term>
267 <listitem><para>
268 Use [do not use] TCP when querying name servers.  The default
269 behaviour is to use UDP unless an AXFR or IXFR query is requested, in
270 which case a TCP connection is used.
271 </para></listitem></varlistentry>
272
273 <varlistentry><term><option>+[no]vc</option></term>
274 <listitem><para>
275 Use [do not use] TCP when querying name servers.  This alternate
276 syntax to <parameter>+[no]tcp</parameter> is provided for backwards
277 compatibility.  The "vc" stands for "virtual circuit".
278 </para></listitem></varlistentry>
279
280 <varlistentry><term><option>+[no]ignore</option></term>
281 <listitem><para>
282 Ignore truncation in UDP responses instead of retrying with TCP.  By
283 default, TCP retries are performed.
284 </para></listitem></varlistentry>
285
286 <varlistentry><term><option>+domain=somename</option></term>
287 <listitem><para>
288 Set the search list to contain the single domain
289 <parameter>somename</parameter>, as if specified in a
290 <command>domain</command> directive in
291 <filename>/etc/resolv.conf</filename>, and enable search list
292 processing as if the <parameter>+search</parameter> option were given.
293 </para></listitem></varlistentry>
294
295 <varlistentry><term><option>+[no]search</option></term>
296 <listitem><para>
297 Use [do not use] the search list defined by the searchlist or domain
298 directive in <filename>resolv.conf</filename> (if any).
299 The search list is not used by default.
300 </para></listitem></varlistentry>
301
302 <varlistentry><term><option>+[no]defname</option></term>
303 <listitem><para>
304 Deprecated, treated as a synonym for <parameter>+[no]search</parameter>
305 </para></listitem></varlistentry>
306
307 <varlistentry><term><option>+[no]aaonly</option></term>
308 <listitem><para>
309 Sets the "aa" flag in the query.
310 </para></listitem></varlistentry>
311
312 <varlistentry><term><option>+[no]aaflag</option></term>
313 <listitem><para>
314 A synonym for <parameter>+[no]aaonly</parameter>.
315 </para></listitem></varlistentry>
316
317 <varlistentry><term><option>+[no]adflag</option></term>
318 <listitem><para>
319 Set [do not set] the AD (authentic data) bit in the query.  The AD bit
320 currently has a standard meaning only in responses, not in queries,
321 but the ability to set the bit in the query is provided for
322 completeness.
323 </para></listitem></varlistentry>
324
325 <varlistentry><term><option>+[no]cdflag</option></term>
326 <listitem><para>
327 Set [do not set] the CD (checking disabled) bit in the query.  This
328 requests the server to not perform DNSSEC validation of responses.
329 </para></listitem></varlistentry>
330
331 <varlistentry><term><option>+[no]cl</option></term>
332 <listitem><para>
333 Display [do not display] the CLASS when printing the record.
334 </para></listitem></varlistentry>
335
336 <varlistentry><term><option>+[no]ttlid</option></term>
337 <listitem><para>
338 Display [do not display] the TTL when printing the record.
339 </para></listitem></varlistentry>
340
341 <varlistentry><term><option>+[no]recurse</option></term>
342 <listitem><para>
343 Toggle the setting of the RD (recursion desired) bit in the query.
344 This bit is set by default, which means <command>dig</command>
345 normally sends recursive queries.  Recursion is automatically disabled
346 when the <parameter>+nssearch</parameter> or
347 <parameter>+trace</parameter> query options are used.
348 </para></listitem></varlistentry>
349
350 <varlistentry><term><option>+[no]nssearch</option></term>
351 <listitem><para>
352 When this option is set, <command>dig</command> attempts to find the
353 authoritative name servers for the zone containing the name being
354 looked up and display the SOA record that each name server has for the
355 zone.
356 </para></listitem></varlistentry>
357
358 <varlistentry><term><option>+[no]trace</option></term>
359 <listitem><para>
360 Toggle tracing of the delegation path from the root name servers for
361 the name being looked up.  Tracing is disabled by default.  When
362 tracing is enabled, <command>dig</command> makes iterative queries to
363 resolve the name being looked up.  It will follow referrals from the
364 root servers, showing the answer from each server that was used to
365 resolve the lookup.
366 </para></listitem></varlistentry>
367
368 <varlistentry><term><option>+[no]cmd</option></term>
369 <listitem><para>
370 toggles the printing of the initial comment in the output identifying
371 the version of <command>dig</command> and the query options that have
372 been applied.  This comment is printed by default.
373 </para></listitem></varlistentry>
374
375 <varlistentry><term><option>+[no]short</option></term>
376 <listitem><para>
377 Provide a terse answer.  The default is to print the answer in a
378 verbose form.
379 </para></listitem></varlistentry>
380
381 <varlistentry><term><option>+[no]identify</option></term>
382 <listitem><para>
383 Show [or do not show] the IP address and port number that supplied the
384 answer when the <parameter>+short</parameter> option is enabled.  If
385 short form answers are requested, the default is not to show the
386 source address and port number of the server that provided the answer.
387 </para></listitem></varlistentry>
388
389 <varlistentry><term><option>+[no]comments</option></term>
390 <listitem><para>
391 Toggle the display of comment lines in the output.  The default is to
392 print comments.
393 </para></listitem></varlistentry>
394
395 <varlistentry><term><option>+[no]stats</option></term>
396 <listitem><para>
397 This query option toggles the printing of statistics: when the query
398 was made, the size of the reply and so on.  The default behaviour is
399 to print the query statistics.
400 </para></listitem></varlistentry>
401
402 <varlistentry><term><option>+[no]qr</option></term>
403 <listitem><para>
404 Print [do not print] the query as it is sent.
405 By default, the query is not printed.
406 </para></listitem></varlistentry>
407
408 <varlistentry><term><option>+[no]question</option></term>
409 <listitem><para>
410 Print [do not print] the question section of a query when an answer is
411 returned.  The default is to print the question section as a comment.
412 </para></listitem></varlistentry>
413
414 <varlistentry><term><option>+[no]answer</option></term>
415 <listitem><para>
416 Display [do not display] the answer section of a reply.  The default
417 is to display it.
418 </para></listitem></varlistentry>
419
420 <varlistentry><term><option>+[no]authority</option></term>
421 <listitem><para>
422 Display [do not display] the authority section of a reply.  The
423 default is to display it.
424 </para></listitem></varlistentry>
425
426 <varlistentry><term><option>+[no]additional</option></term>
427 <listitem><para>
428 Display [do not display] the additional section of a reply.
429 The default is to display it.
430 </para></listitem></varlistentry>
431
432 <varlistentry><term><option>+[no]all</option></term>
433 <listitem><para>
434 Set or clear all display flags.
435 </para></listitem></varlistentry>
436
437 <varlistentry><term><option>+time=T</option></term>
438 <listitem><para>
439
440 Sets the timeout for a query to
441 <parameter>T</parameter> seconds.  The default time out is 5 seconds.
442 An attempt to set <parameter>T</parameter> to less than 1 will result
443 in a query timeout of 1 second being applied.
444 </para></listitem></varlistentry>
445
446 <varlistentry><term><option>+tries=T</option></term>
447 <listitem><para>
448 Sets the number of times to try UDP queries to server to
449 <parameter>T</parameter> instead of the default, 3.  If
450 <parameter>T</parameter> is less than or equal to zero, the number of
451 tries is silently rounded up to 1.
452 </para></listitem></varlistentry>
453
454 <varlistentry><term><option>+retry=T</option></term>
455 <listitem><para>
456 Sets the number of times to retry UDP queries to server to
457 <parameter>T</parameter> instead of the default, 2.  Unlike
458 <parameter>+tries</parameter>, this does not include the initial
459 query.
460 </para></listitem></varlistentry>
461
462 <varlistentry><term><option>+ndots=D</option></term>
463 <listitem><para>
464 Set the number of dots that have to appear in
465 <parameter>name</parameter> to <parameter>D</parameter> for it to be
466 considered absolute.  The default value is that defined using the
467 ndots statement in <filename>/etc/resolv.conf</filename>, or 1 if no
468 ndots statement is present.  Names with fewer dots are interpreted as
469 relative names and will be searched for in the domains listed in the
470 <option>search</option> or <option>domain</option> directive in
471 <filename>/etc/resolv.conf</filename>.
472 </para></listitem></varlistentry>
473
474 <varlistentry><term><option>+bufsize=B</option></term>
475 <listitem><para>
476 Set the UDP message buffer size advertised using EDNS0 to
477 <parameter>B</parameter> bytes.  The maximum and minimum sizes of this
478 buffer are 65535 and 0 respectively.  Values outside this range are
479 rounded up or down appropriately.
480 </para>
481 </listitem></varlistentry>
482
483 <varlistentry><term><option>+[no]multiline</option></term>
484 <listitem><para>
485 Print records like the SOA records in a verbose multi-line
486 format with human-readable comments.  The default is to print
487 each record on a single line, to facilitate machine parsing 
488 of the <command>dig</command> output.
489 </para></listitem></varlistentry>
490
491 <varlistentry><term><option>+[no]fail</option></term>
492 <listitem><para>
493 Do not try the next server if you receive a SERVFAIL.  The default is
494 to not try the next server which is the reverse of normal stub resolver
495 behaviour.
496 </para></listitem></varlistentry>
497
498 <varlistentry><term><option>+[no]besteffort</option></term>
499 <listitem><para>
500 Attempt to display the contents of messages which are malformed.
501 The default is to not display malformed answers.
502 </para></listitem></varlistentry>
503
504 <varlistentry><term><option>+[no]dnssec</option></term>
505 <listitem><para>
506 Requests DNSSEC records be sent by setting the DNSSEC OK bit (DO)
507 in the OPT record in the additional section of the query.
508 </para></listitem></varlistentry>
509
510 <varlistentry><term><option>+[no]sigchase</option></term>
511 <listitem><para>
512 Chase DNSSEC signature chains.  Requires dig be compiled with
513 -DDIG_SIGCHASE.
514 </para></listitem></varlistentry>
515
516 <varlistentry><term><option>+trusted-key=####</option></term>
517 <listitem><para>
518 Specify a trusted key to be used with <option>+sigchase</option>.
519 Requires dig be compiled with -DDIG_SIGCHASE.
520 </para></listitem></varlistentry>
521
522 <varlistentry><term><option>+[no]topdown</option></term>
523 <listitem><para>
524 When chasing DNSSEC signature chains perform a top down validation.
525 Requires dig be compiled with -DDIG_SIGCHASE.
526 </para></listitem></varlistentry>
527
528
529
530 </variablelist>
531
532 </para>
533 </refsect1>
534
535 <refsect1>
536 <title>MULTIPLE QUERIES</title>
537
538 <para>
539 The BIND 9 implementation of <command>dig </command> supports
540 specifying multiple queries on the command line (in addition to
541 supporting the <option>-f</option> batch file option).  Each of those
542 queries can be supplied with its own set of flags, options and query
543 options.
544 </para>
545
546 <para>
547 In this case, each <parameter>query</parameter> argument represent an
548 individual query in the command-line syntax described above.  Each
549 consists of any of the standard options and flags, the name to be
550 looked up, an optional query type and class and any query options that
551 should be applied to that query.
552 </para>
553
554 <para>
555 A global set of query options, which should be applied to all queries,
556 can also be supplied.  These global query options must precede the
557 first tuple of name, class, type, options, flags, and query options
558 supplied on the command line.  Any global query options (except
559 the <option>+[no]cmd</option> option) can be
560 overridden by a query-specific set of query options.  For example:
561 <programlisting>
562 dig +qr www.isc.org any -x 127.0.0.1 isc.org ns +noqr
563 </programlisting>
564 shows how <command>dig</command> could be used from the command line
565 to make three lookups: an ANY query for <literal>www.isc.org</literal>, a
566 reverse lookup of 127.0.0.1 and a query for the NS records of
567 <literal>isc.org</literal>.
568
569 A global query option of <parameter>+qr</parameter> is applied, so
570 that <command>dig</command> shows the initial query it made for each
571 lookup.  The final query has a local query option of
572 <parameter>+noqr</parameter> which means that <command>dig</command>
573 will not print the initial query when it looks up the NS records for
574 <literal>isc.org</literal>.
575 </para>
576
577 </refsect1>
578
579 <refsect1>
580 <title>FILES</title>
581 <para>
582 <filename>/etc/resolv.conf</filename>
583 </para>
584 <para>
585 <filename>${HOME}/.digrc</filename>
586 </para>
587 </refsect1>
588
589 <refsect1>
590 <title>SEE ALSO</title>
591 <para>
592 <citerefentry>
593 <refentrytitle>host</refentrytitle><manvolnum>1</manvolnum>
594 </citerefentry>,
595 <citerefentry>
596 <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
597 </citerefentry>,
598 <citerefentry>
599 <refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
600 </citerefentry>,
601 <citetitle>RFC1035</citetitle>.
602 </para>
603 </refsect1>
604
605 <refsect1>
606 <title>BUGS </title>
607 <para>
608 There are probably too many query options. 
609 </para>
610 </refsect1>
611 </refentry>