dig.docbook revision 1ae75c1024eb0475c2be352b8707772e16332ad0
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews - Copyright (C) 2000-2003 Internet Software Consortium.
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews - Permission to use, copy, modify, and distribute this software for any
40f53fa8d9c6a4fc38c0014495e7a42b08f52481David Lawrence - purpose with or without fee is hereby granted, provided that the above
15a44745412679c30a6d022733925af70a38b715David Lawrence - copyright notice and this permission notice appear in all copies.
15a44745412679c30a6d022733925af70a38b715David Lawrence - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
15a44745412679c30a6d022733925af70a38b715David Lawrence - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
15a44745412679c30a6d022733925af70a38b715David Lawrence - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
15a44745412679c30a6d022733925af70a38b715David Lawrence - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
15a44745412679c30a6d022733925af70a38b715David Lawrence - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
15a44745412679c30a6d022733925af70a38b715David Lawrence - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
f31f0b63cbe841720f154c570bcdede9d79e64b8Michael Graff<!-- $Id: dig.docbook,v 1.19 2004/04/13 02:39:34 marka Exp $ -->
854d0238dbc2908490197984b3b9d558008a53dfMark Andrews<refentryinfo>
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews</refentryinfo>
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews</refnamediv>
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<refsynopsisdiv>
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<cmdsynopsis>
deaaf94332abbfdb3aff53675546acfed16e5eb6Mark Andrews<arg><option>-b <replaceable class="parameter">address</replaceable></option></arg>
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<arg><option>-f <replaceable class="parameter">filename</replaceable></option></arg>
6d12fdf96621801e80f3f4c2a8a569fe48766a20David Lawrence<arg><option>-k <replaceable class="parameter">filename</replaceable></option></arg>
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<arg><option>-p <replaceable class="parameter">port#</replaceable></option></arg>
251705f6831d3d1357627ba2d54fc898487dec09Mark Andrews<arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
251705f6831d3d1357627ba2d54fc898487dec09Mark Andrews<arg><option>-x <replaceable class="parameter">addr</replaceable></option></arg>
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<arg><option>-y <replaceable class="parameter">name:key</replaceable></option></arg>
add4043305ca411202ed9cf1929a4179016515ceBrian Wellington</cmdsynopsis>
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<arg choice=opt rep=repeat>global-queryopt</arg>
419590499823ce15b5d2ad4fe71eaf04bd5a86c0Michael Graff</cmdsynopsis>
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews</refsynopsisdiv>
34b394b43e2207e8f8f3703f0402422121455638David Lawrence<command>dig</command> (domain information groper) is a flexible tool
add4043305ca411202ed9cf1929a4179016515ceBrian Wellingtonfor interrogating DNS name servers. It performs DNS lookups and
add4043305ca411202ed9cf1929a4179016515ceBrian Wellingtondisplays the answers that are returned from the name server(s) that
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewswere queried. Most DNS administrators use <command>dig</command> to
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewstroubleshoot DNS problems because of its flexibility, ease of use and
5d15501996f597d9bbb734d88d4549828e28000bMark Andrewsclarity of output. Other lookup tools tend to have less functionality
419590499823ce15b5d2ad4fe71eaf04bd5a86c0Michael GraffAlthough <command>dig</command> is normally used with command-line
df7f20ae77fbe03d2973d1768d6a68da1063af84Andreas Gustafssonarguments, it also has a batch mode of operation for reading lookup
34b394b43e2207e8f8f3703f0402422121455638David Lawrencerequests from a file. A brief summary of its command-line arguments
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsand options is printed when the <option>-h</option> option is given.
44a966dff66061ac3f266c6b451a70733eb78e82Mark AndrewsUnlike earlier versions, the BIND9 implementation of
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<command>dig</command> allows multiple lookups to be issued from the
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewscommand line.
44a966dff66061ac3f266c6b451a70733eb78e82Mark AndrewsUnless it is told to query a specific name server,
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<command>dig</command> will try each of the servers listed in
44a966dff66061ac3f266c6b451a70733eb78e82Mark AndrewsWhen no command line arguments or options are given, will perform an
251705f6831d3d1357627ba2d54fc898487dec09Mark AndrewsNS query for "." (the root).
251705f6831d3d1357627ba2d54fc898487dec09Mark AndrewsIt is possible to set per-user defaults for <command>dig</command> via
251705f6831d3d1357627ba2d54fc898487dec09Mark Andrews<filename>${HOME}/.digrc</filename>. This file is read and any options in it
251705f6831d3d1357627ba2d54fc898487dec09Mark Andrewsare applied before the command line arguments.
251705f6831d3d1357627ba2d54fc898487dec09Mark AndrewsA typical invocation of <command>dig</command> looks like:
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<programlisting> dig @server name type </programlisting> where:
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<variablelist>
419590499823ce15b5d2ad4fe71eaf04bd5a86c0Michael Graff<varlistentry><term><constant>server</constant></term>
34b394b43e2207e8f8f3703f0402422121455638David Lawrenceis the name or IP address of the name server to query. This can be an IPv4
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsaddress in dotted-decimal notation or an IPv6
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsaddress in colon-delimited notation. When the supplied
f31f0b63cbe841720f154c570bcdede9d79e64b8Michael Graff<parameter>server</parameter> argument is a hostname,
19c5c23ef6e38965949c996592bd92478da0612cMark Andrews<command>dig</command> resolves that name before querying that name
f31f0b63cbe841720f154c570bcdede9d79e64b8Michael Graffserver. If no <parameter>server</parameter> argument is provided,
34b394b43e2207e8f8f3703f0402422121455638David Lawrence<command>dig</command> consults <filename>/etc/resolv.conf</filename>
34b394b43e2207e8f8f3703f0402422121455638David Lawrenceand queries the name servers listed there. The reply from the name
34b394b43e2207e8f8f3703f0402422121455638David Lawrenceserver that responds is displayed.
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<varlistentry><term><constant>name</constant></term>
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsis the name of the resource record that is to be looked up.
6d12fdf96621801e80f3f4c2a8a569fe48766a20David Lawrence<varlistentry><term><constant>type</constant></term>
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsindicates what type of query is required —
44a966dff66061ac3f266c6b451a70733eb78e82Mark AndrewsANY, A, MX, SIG, etc.
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<parameter>type</parameter> can be any valid query type. If no
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<parameter>type</parameter> argument is supplied,
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<command>dig</command> will perform a lookup for an A record.
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews</variablelist>
44a966dff66061ac3f266c6b451a70733eb78e82Mark AndrewsThe <option>-b</option> option sets the source IP address of the query
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsto <parameter>address</parameter>. This must be a valid address on
df7f20ae77fbe03d2973d1768d6a68da1063af84Andreas Gustafssonone of the host's network interfaces or "0.0.0.0" or "::". An optional port
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsmay be specified by appending "#<port>"
deaaf94332abbfdb3aff53675546acfed16e5eb6Mark AndrewsThe default query class (IN for internet) is overridden by the
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<option>-c</option> option. <parameter>class</parameter> is any valid
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsclass, such as HS for Hesiod records or CH for CHAOSNET records.
deaaf94332abbfdb3aff53675546acfed16e5eb6Mark AndrewsThe <option>-f</option> option makes <command>dig </command> operate
deaaf94332abbfdb3aff53675546acfed16e5eb6Mark Andrewsin batch mode by reading a list of lookup requests to process from the
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsfile <parameter>filename</parameter>. The file contains a number of
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsqueries, one per line. Each entry in the file should be organised in
f31f0b63cbe841720f154c570bcdede9d79e64b8Michael Graffthe same way they would be presented as queries to
419590499823ce15b5d2ad4fe71eaf04bd5a86c0Michael Graff<command>dig</command> using the command-line interface.
6d12fdf96621801e80f3f4c2a8a569fe48766a20David LawrenceIf a non-standard port number is to be queried, the
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<option>-p</option> option is used. <parameter>port#</parameter> is
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsthe port number that <command>dig</command> will send its queries
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsinstead of the standard DNS port number 53. This option would be used
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsto test a name server that has been configured to listen for queries
d981ca645597116d227a48bf37cc5edc061c854dBob Halleyon a non-standard port number.
63cef8bde8b92aeb30ccdcf21d4e44c9be9cc6e3Andreas GustafssonThe <option>-4</option> option forces <command>dig</command> to only
63cef8bde8b92aeb30ccdcf21d4e44c9be9cc6e3Andreas Gustafssonuse IPv4 query transport. The <option>-6</option> option forces
6e49e91bd08778d7eae45a2229dcf41ed97cc636David Lawrence<command>dig</command> to only use IPv6 query transport.
419590499823ce15b5d2ad4fe71eaf04bd5a86c0Michael GraffThe <option>-t</option> option sets the query type to
df7f20ae77fbe03d2973d1768d6a68da1063af84Andreas Gustafsson<parameter>type</parameter>. It can be any valid query type which is
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewssupported in BIND9. The default query type "A", unless the
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<option>-x</option> option is supplied to indicate a reverse lookup.
419590499823ce15b5d2ad4fe71eaf04bd5a86c0Michael GraffA zone transfer can be requested by specifying a type of AXFR. When
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsan incremental zone transfer (IXFR) is required,
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<parameter>type</parameter> is set to <literal>ixfr=N</literal>.
44a966dff66061ac3f266c6b451a70733eb78e82Mark AndrewsThe incremental zone transfer will contain the changes made to the zone
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewssince the serial number in the zone's SOA record was
3ddd814a97de1d152ba0913c592d6e6dc83d38a6Michael GraffReverse lookups - mapping addresses to names - are simplified by the
6d12fdf96621801e80f3f4c2a8a569fe48766a20David Lawrence<option>-x</option> option. <parameter>addr</parameter> is an IPv4
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsaddress in dotted-decimal notation, or a colon-delimited IPv6 address.
44a966dff66061ac3f266c6b451a70733eb78e82Mark AndrewsWhen this option is used, there is no need to provide the
f31f0b63cbe841720f154c570bcdede9d79e64b8Michael Graff<parameter>name</parameter>, <parameter>class</parameter> and
f31f0b63cbe841720f154c570bcdede9d79e64b8Michael Graff<parameter>type</parameter> arguments. <command>dig</command>
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsautomatically performs a lookup for a name like
d981ca645597116d227a48bf37cc5edc061c854dBob Halley<literal>11.12.13.10.in-addr.arpa</literal> and sets the query type and
b589e90689c6e87bf9608424ca8d99571c18bc61Mark Andrewsclass to PTR and IN respectively. By default, IPv6 addresses are
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewslooked up using nibble format under the IP6.ARPA domain.
44a966dff66061ac3f266c6b451a70733eb78e82Mark AndrewsTo use the older RFC1886 method using the IP6.INT domain
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsspecify the <option>-i</option> option. Bit string labels (RFC2874)
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsare now experimental and are not attempted.
44a966dff66061ac3f266c6b451a70733eb78e82Mark AndrewsTo sign the DNS queries sent by <command>dig</command> and their
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsresponses using transaction signatures (TSIG), specify a TSIG key file
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsusing the <option>-k</option> option. You can also specify the TSIG
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewskey itself on the command line using the <option>-y</option> option;
d981ca645597116d227a48bf37cc5edc061c854dBob Halley<parameter>name</parameter> is the name of the TSIG key and
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<parameter>key</parameter> is the actual key. The key is a base-64
d981ca645597116d227a48bf37cc5edc061c854dBob Halleyencoded string, typically generated by <citerefentry>
b589e90689c6e87bf9608424ca8d99571c18bc61Mark Andrews<refentrytitle>dnssec-keygen</refentrytitle><manvolnum>8</manvolnum>
b589e90689c6e87bf9608424ca8d99571c18bc61Mark Andrews</citerefentry>.
44a966dff66061ac3f266c6b451a70733eb78e82Mark AndrewsCaution should be taken when using the <option>-y</option> option on
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsmulti-user systems as the key can be visible in the output from
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews<citerefentry> <refentrytitle>ps</refentrytitle><manvolnum>1
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrews</manvolnum> </citerefentry> or in the shell's history file. When
44a966dff66061ac3f266c6b451a70733eb78e82Mark Andrewsusing TSIG authentication with <command>dig</command>, the name
3ddd814a97de1d152ba0913c592d6e6dc83d38a6Michael Graffserver that is queried needs to know the key and algorithm that is
6d12fdf96621801e80f3f4c2a8a569fe48766a20David Lawrencebeing used. In BIND, this is done by providing appropriate
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrews<command>key</command> and <command>server</command> statements in
63cef8bde8b92aeb30ccdcf21d4e44c9be9cc6e3Andreas Gustafsson<command>dig</command> provides a number of query options which affect
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrewsthe way in which lookups are made and the results displayed. Some of
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrewsthese set or reset flag bits in the query header, some determine which
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrewssections of the answer get printed, and others determine the timeout
373ce67419680a398ba3dc51a14a486caaf0afb0Mark Andrewsand retry strategies.
6d12fdf96621801e80f3f4c2a8a569fe48766a20David LawrenceEach query option is identified by a keyword preceded by a plus sign
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrews(<literal>+</literal>). Some keywords set or reset an option. These may be preceded
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrewsby the string <literal>no</literal> to negate the meaning of that keyword. Other
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrewskeywords assign values to options like the timeout interval. They
44a966dff66061ac3f266c6b451a70733eb78e82Mark AndrewsThe query options are:
b589e90689c6e87bf9608424ca8d99571c18bc61Mark Andrews<variablelist>
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrews<varlistentry><term><option>+[no]tcp</option></term>
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark AndrewsUse [do not use] TCP when querying name servers. The default
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrewsbehaviour is to use UDP unless an AXFR or IXFR query is requested, in
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrewswhich case a TCP connection is used.
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrews<varlistentry><term><option>+[no]vc</option></term>
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark AndrewsUse [do not use] TCP when querying name servers. This alternate
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrewssyntax to <parameter>+[no]tcp</parameter> is provided for backwards
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrewscompatibility. The "vc" stands for "virtual circuit".
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrews<varlistentry><term><option>+[no]ignore</option></term>
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark AndrewsIgnore truncation in UDP responses instead of retrying with TCP. By
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrewsdefault, TCP retries are performed.
94a3bcd132e515b4baa0884ba9dd0f361d2e17bcMark Andrews<varlistentry><term><option>+domain=somename</option></term>
6d12fdf96621801e80f3f4c2a8a569fe48766a20David LawrenceSet the search list to contain the single domain
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrews<parameter>somename</parameter>, as if specified in a
94a3bcd132e515b4baa0884ba9dd0f361d2e17bcMark Andrews<filename>/etc/resolv.conf</filename>, and enable search list
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrewsprocessing as if the <parameter>+search</parameter> option were given.
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrews<varlistentry><term><option>+[no]search</option></term>
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark AndrewsUse [do not use] the search list defined by the searchlist or domain
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark Andrewsdirective in <filename>resolv.conf</filename> (if any).
5159c427839689d5070e2f9c6c9a0168dd9f6583Mark AndrewsThe search list is not used by default.
d981ca645597116d227a48bf37cc5edc061c854dBob Halley<varlistentry><term><option>+[no]defname</option></term>
6d12fdf96621801e80f3f4c2a8a569fe48766a20David LawrenceDeprecated, treated as a synonym for <parameter>+[no]search</parameter>
f31f0b63cbe841720f154c570bcdede9d79e64b8Michael Graff<varlistentry><term><option>+[no]aaonly</option></term>
d981ca645597116d227a48bf37cc5edc061c854dBob HalleyThis option does nothing. It is provided for compatibility with old
d981ca645597116d227a48bf37cc5edc061c854dBob Halleyversions of <command>dig</command> where it set an unimplemented
d981ca645597116d227a48bf37cc5edc061c854dBob Halleyresolver flag.
d981ca645597116d227a48bf37cc5edc061c854dBob Halley<varlistentry><term><option>+[no]adflag</option></term>
6d12fdf96621801e80f3f4c2a8a569fe48766a20David LawrenceSet [do not set] the AD (authentic data) bit in the query. The AD bit
20dbb03b72d786d37ead9156f2884322d2743a3aBob Halleycurrently has a standard meaning only in responses, not in queries,
20dbb03b72d786d37ead9156f2884322d2743a3aBob Halleybut the ability to set the bit in the query is provided for
20dbb03b72d786d37ead9156f2884322d2743a3aBob Halleycompleteness.
20dbb03b72d786d37ead9156f2884322d2743a3aBob Halley<varlistentry><term><option>+[no]cdflag</option></term>
20dbb03b72d786d37ead9156f2884322d2743a3aBob HalleySet [do not set] the CD (checking disabled) bit in the query. This
20dbb03b72d786d37ead9156f2884322d2743a3aBob Halleyrequests the server to not perform DNSSEC validation of responses.