path: root/contrib/bind/doc/man/dig.1

.\" $FreeBSD$
.\" $Id: dig.1,v 8.4 1999/10/15 21:29:58 vixie Exp $
.\"
.\" ++Copyright++ 1993
.\" -
.\" Copyright (c) 1993
.\"    The Regents of the University of California.  All rights reserved.
.\" 
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\" 	This product includes software developed by the University of
.\" 	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\" -
.\" Portions Copyright (c) 1993 by Digital Equipment Corporation.
.\" 
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies, and that
.\" the name of Digital Equipment Corporation not be used in advertising or
.\" publicity pertaining to distribution of the document or software without
.\" specific, written prior permission.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP. DISCLAIMS ALL
.\" WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS.   IN NO EVENT SHALL DIGITAL EQUIPMENT
.\" CORPORATION BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
.\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
.\" SOFTWARE.
.\" -
.\" --Copyright--
.\"
.\" Distributed with 'dig' version 2.0 from University of Southern
.\" California Information Sciences Institute (USC-ISI).
.\"
.\"       dig.1   2.0 (USC-ISI) 8/30/90
.\"
.Dd August 30, 1990
.Dt DIG @CMD_EXT_U@
.Os BSD 4
.Sh NAME
.Nm dig
.Nd send domain name query packets to name servers
.Sh SYNOPSIS
.Nm dig 
.Op Ic @ Ns Ar server
.Ar domain
.Op Aq Ar query-type
.Op Aq Ar query-class
.Op Ic + Ns Aq Ar query-option
.Op Fl Aq Ar dig-option
.Op Ar %comment
.Sh DESCRIPTION
.Ic Dig
(domain information groper) is a flexible command line tool
which can be used to gather information from the Domain
Name System servers. 
.Ic Dig
has two modes: simple interactive mode
for a single query, and batch mode which executes a query for
each in a list of several query lines. All query options are
accessible from the command line.
.Pp
The usual simple use of 
.Ic dig
will take the form:
.Pp
.Bd -ragged -offset indent-two
.Ic dig @ Ns Ar server  domain   query-type  query-class
.Ed
.Pp
where:
.Bl -tag -width Fl
.It Ar server
may be either a domain name or a dot-notation
Internet address. If this optional field is omitted, 
.Ic dig
will attempt to use the default name server for your machine.
.Pp
.Em Note:
If a domain name is specified, this will be resolved
using the domain name system resolver (i.e., BIND). If your
system does not support DNS, you may 
.Em have
to specify a
dot-notation address.  Alternatively, if there is a server
at your disposal somewhere,  all that is required is that
.Pa /etc/resolv.conf 
be present and indicate where the default
name servers reside,  so that  
.Ar server 
itself can be resolved. See 
.Xr resolver @FORMAT_EXT@
for information on 
.Pa /etc/resolv.conf .
.Sy WARNING: 
Changing 
.Pa /etc/resolv.conf 
will affect both the standard resolver library and 
.Pq potentially 
several programs which use it.
As an option, the user may set the
environment variable 
.Ev LOCALRES 
to name a file which is to
be used instead of 
.Pa /etc/resolv.conf 
.Ns Ev (LOCALRES 
is specific to the 
.Ic dig
resolver and is not referenced by the standard resolver).
If the 
.Ev LOCALRES 
variable is not set or the specified file
is not readable, then 
.Pa /etc/resolv.conf 
will be used.
.It Ar domain
is the domain name for which you are requesting information.
See the 
.Fl x 
option (documented in the
.Sx OTHER OPTIONS 
subsection of this section) for convenient way to specify inverse address
query.
.It Ar query-type
is the type of information (DNS query type) that
you are requesting. If omitted, the default is 
.Dq Ar a 
.Pq Dv T_A = Ar address .
The following types are recognized:
.Pp
.Bl -hang -width "hinfo  T_HINFO   " -compact
.It Ar a\ \ \ \ \ \  Dv T_A
network address
.It Ar any\ \ \ \  Dv T_ANY
all/any information about specified domain
.It Ar mx\ \ \ \ \  Dv T_MX
mail exchanger for the domain
.It Ar ns\ \ \ \ \  Dv T_NS
name servers
.It Ar soa\ \ \ \  Dv T_SOA
zone of authority record
.It Ar hinfo\ \  Dv T_HINFO
host information
.It Ar axfr\ \ \  Dv T_AXFR
zone transfer (must ask an authoritative server)
.It Ar txt\ \ \ \  Dv T_TXT
arbitrary number of strings
.El
.Pp
(See RFC 1035 for the complete list.)
.It Ar query-class
is the network class requested in the query. If
omitted, the default is 
.Dq Ar in 
.Pq Dv C_IN = Ar Internet .
The following classes are recognized:
.Pp
.Bl -tag -width "hinfo  T_HINFO   " -compact
.It Ar in\ \ \ \ \  Dv C_IN
Internet class domain
.It Ar any\ \ \ \  Dv C_ANY
all/any class information
.El
.Pp
(See RFC 1035 for the complete list.)
.Pp
.Em Note:
.Dq Ar Any
can be used to specify a 
.Em class 
and/or a 
.Em type 
of query. 
.Ic Dig
will parse the first occurrence of 
.Dq Ar any
to mean 
.Ar query-type = Dv T_ANY . 
To specify 
.Ar query-class = Dv C_ANY ,
you must either specify 
.Dq any 
twice, or set
.Ar query-class 
using the 
.Fl c 
option (see below).
.El
.Ss OTHER OPTIONS
.Bl -tag -width Fl
.It % Ns Ar ignored-comment
.Dq % 
is used to included an argument that is simply not
parsed.  This may be useful  if running 
.Ic dig
in batch
mode. Instead of resolving every 
.Ar @server-domain-name 
in a list of queries, you can avoid the overhead of doing
so, and still have the domain name on the command line
as a reference. Example:
.Pp
.Bd -ragged -offset indent-two
.Ic dig  @128.9.0.32  %venera.isi.edu  mx  isi.edu
.Ed
.Pp
.It Fl Aq Ar dig option
.Dq Fl
is used to specify an option which affects the operation of 
.Ic dig . 
The following options are currently
available (although not guaranteed to be useful):
.Bl -tag -width Fl
.It Fl x Ar dot-notation-address
Convenient form to specify inverse address mapping.
Instead of 
.Dq Ic dig 32.0.9.128.in-addr.arpa , 
one can simply 
.Dq Ic dig -x 128.9.0.32 .
.It Fl f Ar file
File for 
.Ic dig
batch mode. The file contains a list
of query specifications
(
.Ns Ic dig 
command lines) which are to be executed successively.  Lines beginning with 
.Sq \&; ,
.Sq # ,
or
.Sq \en 
are ignored.  Other options
may still appear on command line, and will be in
effect for each batch query.
.It Fl T Ar time
Time in seconds between start of successive
queries when running in batch mode. Can be used
to keep two or more batch 
.Ic dig
commands running
roughly in sync.  Default is zero.
.It Fl p Ar port
Port number. Query a name server listening to a
non-standard port number.  Default is 53.
.It Fl P Ns Bq Ar ping-string
After query returns, execute a 
.Xr ping @SYS_OPS_EXT@
command for response time comparison.  This rather
unelegantly makes a call to the shell.  The last
three lines of statistics is printed for the
command:
.Pp
.Bd -ragged -offset indent-two
.Ic ping Fl s server_name 56 3
.Ed 
.Pp
If the optional 
.Dq Ar ping_string 
is present, it
replaces 
.Dq Ic ping Fl s 
in the shell command.
.It Fl t Ar query-type
Specify type of query.  May specify either an
integer value to be included in the type field
or use the abbreviated mnemonic as discussed
above (i.e., 
.Ar mx  = Dv T_MX ) .
.It Fl c Ar query-class
Specify class of query. May specify either an
integer value to be included in the class field
or use the abbreviated mnemonic as discussed
above (i.e., in = C_IN).
.It Fl k Ar keydir:keyname
Sign the query with the TSIG key named keyname
that is in the directory keydir.
.It Fl envsav
This flag specifies that the 
.Ic dig
environment
(defaults, print options, etc.), after
all of the arguments are parsed, should be saved
to a file to become the default environment.
This is useful if you do not like the standard set of
defaults and do not desire to include a
large number of options each time 
.Ic dig
is used.  The environment consists of resolver state
variable flags, timeout, and retries as well as the flags detailing 
.Ic dig
output (see below).
If the shell environment variable 
.Ev LOCALDEF 
is set to the name of a file, this is where the default
.Ic dig
environment is saved.  If not, the file
.Dq Pa DiG.env 
is created in the current working directory.
.Pp
.Em Note: 
.Ev LOCALDEF 
is specific to the 
.Ic dig
resolver,
and will not affect operation of the standard
resolver library.
.Pp
Each time 
.Ic dig
is executed, it looks for 
.Dq Pa ./DiG.env
or the file specified by the shell environment variable
.Ev LOCALDEF . 
If such file exists and is readable, then the
environment is restored from this file before any arguments are parsed.
.It Fl envset
This flag only affects batch query runs. When 
.Dq Fl envset 
is specified on a line in a 
.Ic dig
batch file, the 
.Ic dig
environment after the arguments are parsed
becomes the default environment for the duration of
the batch file, or until the next line which specifies
.Dq Fl envset .
.It Xo
.Fl Op Cm no 
.Ns Cm stick
.Xc
This flag only affects batch query runs.
It specifies that the 
.Ic dig
environment (as read initially
or set by 
.Dq Fl envset 
switch) is to be restored before each query (line) in a 
.Ic dig
batch file.
The default 
.Dq Fl nostick 
means that the 
.Ic dig
environment does not stick, hence options specified on a single line
in a 
.Ic dig
batch file will remain in effect for
subsequent lines (i.e. they are not restored to the 
.Dq sticky 
default).
.El
.It Ic + Ns Aq Ar query-option
.Dq +
is used to specify an option to be changed in the query packet or to change 
.Ic dig
output specifics. Many of these are the same parameters accepted by 
.Xr nslookup @SYS_OPS_EXT@ .
If an option requires a parameter, the form is as follows:
.Pp
.Bd -ragged -offset indent-two
.Ic + 
.Ns Ar keyword 
.Ns Op = Ns Ar value
.Ed
.Pp
Most keywords can be abbreviated.  Parsing of the 
.Dq +
options  is very  simplistic \(em a value must not be
separated from its keyword by white space. The following
keywords are currently available:
.Pp
Keyword      Abbrev.  Meaning [default]
.Pp
.Bl -tag -width "[no]primary  (ret)    " -compact
.It Xo
.Op Cm no 
.Ns Cm debug\ \ \ \ 
.Pq Cm deb
.Xc
turn on/off debugging mode 
.Bq Cm deb
.It Xo
.Op Cm no 
.Ns Cm d2\ \ \ \ \ \ \ \ \ \ 
.Xc
turn on/off extra debugging mode 
.Bq Cm nod2
.It Xo
.Op Cm no 
.Ns Cm recurse\ \ 
.Pq Cm rec
.Xc
use/don't use recursive lookup 
.Bq Cm rec
.It Xo
.Cm retry= Ns Ar #
.Cm \ \ \ \ \ 
.Pq Cm ret
.Xc 
set number of retries to # 
.Bq 4
.It Xo
.Cm time= Ns Ar #
.Cm \ \ \ \ \ \ 
.Pq Cm ti
.Xc
set timeout length to # seconds 
.Bq 4
.It Xo
.Op Cm no 
.Ns Cm ko
.Xc
keep open option (implies vc) 
.Bq Cm noko
.It Xo
.Op Cm no 
.Ns Cm vc
.Xc
use/don't use virtual circuit 
.Bq Cm novc
.It Xo
.Op Cm no 
.Ns Cm defname\ \ 
.Pq Cm def
.Xc
use/don't use default domain name 
.Bq Cm def
.It Xo
.Op Cm no 
.Ns Cm search\ \ \ 
.Pq Cm sea
.Xc
use/don't use domain search list 
.Bq Cm sea
.It Xo
.Cm domain= Ns Ar NAME\ \ 
.Pq Cm do
.Xc
set default domain name to 
.Ar NAME
.It Xo
.Op Cm no 
.Ns Cm ignore\ \ \ 
.Pq Cm i
.Xc
ignore/don't ignore trunc. errors 
.Bq Cm noi
.It Xo
.Op Cm no 
.Ns Cm primary\ \ 
.Pq Cm pr
.Xc
use/don't use primary server 
.Bq Cm nopr
.It Xo
.Op Cm no 
.Ns Cm aaonly\ \ \ 
.Pq Cm aa
.Xc
authoritative query only flag 
.Bq Cm noaa
.It Xo
.Op Cm no 
.Ns Cm cmd
.Xc
echo parsed arguments 
.Bq Cm cmd
.It Xo
.Op Cm no 
.Ns Cm stats\ \ \ \ 
.Pq Cm st
.Xc
print query statistics 
.Bq Cm st
.It Xo
.Op Cm no 
.Ns Cm Header\ \ \ 
.Pq Cm H
.Xc
print basic header 
.Bq Cm H
.It Xo
.Op Cm no 
.Ns Cm header\ \ \ 
.Pq Cm he
.Xc
print header flags 
.Bq Cm he
.It Xo
.Op Cm no 
.Ns Cm ttlid\ \ \ \ 
.Pq Cm tt
.Xc
print TTLs 
.Bq Cm tt
.It Xo
.Op Cm no 
.Ns Cm cl
.Xc
print class info 
.Bq Cm nocl
.It Xo
.Op Cm no 
.Ns Cm qr
.Xc
print outgoing query 
.Bq Cm noqr
.It Xo
.Op Cm no 
.Ns Cm reply\ \ \ \ 
.Pq Cm rep
.Xc
print reply 
.Bq Cm rep
.It Xo
.Op Cm no 
.Ns Cm ques\ \ \ \ \ 
.Pq Cm qu
.Xc
print question section 
.Bq Cm qu
.It Xo
.Op Cm no 
.Ns Cm answer\ \ \ 
.Pq Cm an
.Xc
print answer section 
.Bq Cm an
.It Xo
.Op Cm no 
.Ns Cm author\ \ \ 
.Pq Cm au
.Xc
print authoritative section 
.Bq Cm au
.It Xo
.Op Cm no 
.Ns Cm addit\ \ \ \ 
.Pq Cm ad
.Xc
print additional section 
.Bq Cm ad
.It Cm pfdef 
set to default print flags
.It Cm pfmin 
set to minimal default print flags
.It Cm pfset= Ns Ar # 
set print flags to #
(# can be hex/octal/decimal)
.It Cm pfand= Ns Ar #
bitwise and print flags with #
.It Cm pfor= Ns Ar #
bitwise or print flags with #
.El
.Pp
The 
.Cm retry 
and 
.Cm time 
options affect the retransmission strategy used by the resolver 
library when sending datagram queries.  The algorithm is as follows:
.Pp
.Bd -literal -offset indent
for i = 0 to retry - 1
    for j = 1 to num_servers
	send_query
	wait((time * (2**i)) / num_servers)
    end
end
.Ed
.Pp
(Note: 
.Ic dig
always uses a value of 1 for 
.Dq Li num_servers . ) 
.El
.Ss DETAILS
.Ic Dig
once required a slightly modified version of the BIND 
.Xr resolver @LIB_NETWORK_EXT@
library.  As of BIND 4.9, BIND's resolver has been augmented to work
properly with 
.Ic dig .  
Essentially, 
.Ic dig
is a straight-forward
(albeit not pretty) effort of parsing arguments and setting appropriate
parameters.  
.Ic Dig
uses 
.Xr resolver @LIB_NETWORK_EXT@
routines 
.Fn res_init , 
.Fn res_mkquery ,
.Fn res_send 
as well as accessing the 
.Ft _res 
structure. 
.Sh ENVIRONMENT
.Bl -tag -width "LOCALRES  " -compact
.It Ev LOCALRES
file to use in place of 
.Pa /etc/resolv.conf
.It Ev LOCALDEF
default environment file
.El
.Pp
See also the explanation of the
.Fl envsav ,
.Fl envset , 
and
.Xo
.Fl Op Cm no 
.Ns Cm stick
.Xc
options, above.
.Sh FILES
.Bl -tag -width "/etc/resolv.conf  " -compact
.It Pa /etc/resolv.conf	
initial domain name and name server addresses
.It Pa \./DiG.env
default save file for default options
.El
.Sh SEE ALSO
.Xr @INDOT@named @SYS_OPS_EXT@ , 
.Xr resolver @LIB_NETWORK_EXT@ , 
.Xr resolver @FORMAT_EXT@ ,  
.Xr nslookup @SYS_OPS_EXT@ . 
.Sh STANDARDS
RFC 1035.
.Sh AUTHOR
Steve Hotz 
hotz@isi.edu
.Sh ACKNOWLEDGMENTS
.Ic Dig
uses functions from 
.Xr nslookup @SYS_OPS_EXT@
authored by Andrew Cherenson.
.Sh BUGS
.Ic Dig
has a serious case of "creeping featurism" -- the result of
considering several potential uses during it's development.  It would
probably benefit from a rigorous diet.  Similarly, the print flags
and granularity of the items they specify make evident their
rather ad hoc genesis.
.Pp
.Ic Dig
does not consistently exit nicely (with appropriate status)
when a problem occurs somewhere in the resolver 
.Po Sy NOTE: 
most of the common exit cases are handled
.Pc .  
This is particularly annoying when running in
batch mode.  If it exits abnormally (and is not caught), the entire
batch aborts; when such an event is trapped, 
.Ic dig
simply
continues with the next query.