NetBSD/usr.sbin/named/man/host.1

.\"	$NetBSD: host.1,v 1.3 1997/10/04 15:11:35 mrg Exp $
.\"
.\"	@(#)host.1              e07@nikhef.nl (Eric Wassenaar) 961010
.\"
.\" ++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--
.\" from: Id: host.1,v 8.1 1994/12/15 06:24:10 vixie Exp 
.TH HOST 1
.SH NAME
host \- query nameserver about domain names and zones
.SH SYNOPSIS 
.na
.nf
\fBhost\fP [\fB\-v\fP] [\fB\-a\fP] [\fB\-t\fP \fIquerytype\fP] [\fIoptions\fP]  \fIname\fP  [\fIserver\fP] 
.br
\fBhost\fP [\fB\-v\fP] [\fB\-a\fP] [\fB\-t\fP \fIquerytype\fP] [\fIoptions\fP]  \fB\-l\fP \fIzone\fP  [\fIserver\fP] 
.br
\fBhost\fP [\fB\-v\fP] [\fIoptions\fP] \fB\-H\fP [\fB\-D\fP] [\fB\-E\fP] [\fB\-G\fP] \fIzone\fP
.br
\fBhost\fP [\fB\-v\fP] [\fIoptions\fP] \fB\-C\fP \fIzone\fP
.br
\fBhost\fP [\fB\-v\fP] [\fIoptions\fP] \fB\-A\fP \fIhost\fP
.sp
\fBhost\fP [\fIoptions\fP] \fB\-x\fP [\fIname\fP ...]
.br
\fBhost\fP [\fIoptions\fP] \fB\-X\fP \fIserver\fP [\fIname\fP ...]
.SH DESCRIPTION 
.I host
looks for information about Internet hosts and domain names.
It gets this information from a set of interconnected servers
that are spread across the world. The information is stored
in the form of "resource records" belonging to hierarchically
organized "zones".
.PP
By default, the program simply converts between host names and Internet
addresses. However, with the \fB\-t\fP, \fB\-a\fP and \fB\-v\fP
options, it can be used to find all of the information about
domain names that is maintained by the domain nameserver system.
The information printed consists of various fields of the
associated resource records that were retrieved.
.PP
The arguments can be either host names (domain names) or numeric
Internet addresses.
.PP
A numeric Internet address consists of four decimal numbers
separated by dots, e.g. \fB192.16.199.1\fP, representing the
four bytes of the 32-bit address.
.br
The default action is to look up the associated host name.
.PP
A host name or domain name consists of component names (labels)
separated by dots, e.g. \fBnikhefh.nikhef.nl\fP
.br
The default action is to look up all of its Internet addresses.
.PP
For single names without a trailing dot, the local domain is
automatically tacked on the end.
Thus a user in domain "nikhef.nl" can say "host nikhapo",
and it will actually look up "nikhapo.nikhef.nl".
In all other cases, the name is tried unchanged.
Single names with trailing dot are considered top-level domain
specifications, e.g. "nl."
.PP
Note that the usual lookup convention for any name that does not end
with a trailing dot is to try first with the local domain appended,
and possibly other search domains.
This convention is not used by this program.
.PP
The actual suffix to tack on the end is usually the local domain
as specified in the \fB/etc/resolv.conf\fP file, but this can be
overridden.
See below for a description of how to customize the host name lookup.
.SH ARGUMENTS
The first argument is normally the host name (domain name) for which
you want to look up the requested information.
If the first argument is an Internet address, a query is done on the
special "reverse mapping" domain to look up its associated host name.
.PP
If the \fB\-l\fP option is given, the first argument is a domain zone
name for which a complete listing is given. The program enters a
special zone listing mode which has several variants (see below).
.PP
The second argument is optional. It allows you to specify a particular
server to query.  If you don't specify this argument, default servers
are used, as defined by the \fB/etc/resolv.conf\fP file.
.SS "EXTENDED SYNTAX"
If the \fB\-x\fP option is given, it extends the syntax in the sense
that multiple arguments are allowed on the command line. An optional
explicit server must now be specified using the \fB\-X\fP option as it
cannot be given as an ordinary argument any more. The \fB\-X\fP
option implies \fB\-x\fP.
.sp
The extended syntax allows no arguments at all, in which case the
arguments will be read from standard input. This can be a pipe,
redirection from a file, or an interactive terminal. Note that
these arguments are the names to be queried, and not command options.
Everything that appears after a '#' or ';' on an input line will be
skipped. Multiple arguments per line are allowed.
.SS OPTIONS
There are a number of options that can be used before the specified
arguments.  Some of these options are meaningful only to the people
who maintain the domain database zones.
The first options are the regularly used ones.
.TP 4
.B \-v
causes printout to be in a "verbose" format.
All resource record fields are printed.
Without this option, the ttl and class fields are not shown.
Also the contents of the "additional information" and "authoritative
nameservers" sections in the answer from the nameserver are printed,
if present.  Normally these sections are not shown.
In addition, the verbose option prints extra information about the
various actions that are taken by the program.
Note that \fB\-vv\fP is "very verbose". This generates a lot of output.
.TP
.BI \-t " querytype"
allows you to specify a particular type of resource record information
to be looked up.  Supported types are listed below.
The wildcard may be written as either \fBANY\fP or \fB*\fP.
Types may be given in upper or lower case.
The default is type \fBA\fP for regular lookups,
and \fBA\fP, \fBNS\fP, and \fBPTR\fP for zone listings.
.TP
.B \-a
is equivalent to \fB\-t ANY\fP.
Note that this gives you "anything available" (currently cached) and
not "all defined data" if a non-authoritative server is queried.
.SS "SPECIAL MODES"
The following options put the program in a special mode.
.TP 4
.BI \-l " zone"
generates the listing of an entire zone.
.sp
E.g. the command
.br
	\fBhost \-l nikhef.nl\fP
.br
will give a listing of all hosts in the "nikhef.nl" zone.
The \fB\-t\fP option is used to filter what information is
extracted, as you would expect. The default is address
information from A records, supplemented with data from PTR
and NS records.
.sp
The command
.br
	\fBhost \-Z \-a \-l nikhef.nl\fP
.br
will give a complete download of the zone data for "nikhef.nl",
in the official master file format.
.TP 4
.B \-H
can be specified instead of the \fB\-l\fP option. It will print
the count of the unique hostnames (names with an A record)
encountered within the zone.
It will not count pseudo names like "localhost", nor addresses
associated with the zone name itself. Neither are counted the
"glue records" that are necessary to define nameservers for
the zone and its delegated zones.
.sp
By default, this option will not print any resource records.
.sp
Combined with the \fB\-S\fP option, it will give a complete
statistics survey of the zone.
.sp
The host count may be affected by duplicate hosts (see below).
To compute the most realistic value, subtract the duplicate
host count from the total host count.
.TP
.B \-G
implies \fB\-H\fP, but lists the names of gateway hosts.
These are the hosts that have more than one address.
Gateway hosts are not checked for duplicate addresses.
.TP
.B \-E
implies \fB\-H\fP, but lists the names of extrazone hosts.
An extrazone host in zone "foo.bar" is of the form
"host.xxx.foo.bar" where "xxx.foo.bar" is not defined as
a delegated zone with an NS record.
This may be intentional, but also may be an error.
.TP
.B \-D
implies \fB\-H\fP, but lists the names of duplicate hosts.
These are hosts with only one address, which is known to
have been defined also for another host with a different name,
possibly even in a different zone.
This may be intentional, but also may be an error.
.TP
.B \-C
can be specified instead of the \fB\-l\fP option. It causes the SOA
records for the specified zone to be compared as found at each of
the authoritative nameservers for the zone (as listed in the NS records).
Nameserver recursion is turned off, and it will be checked whether
the answers are really authoritative. If a server cannot provide an
authoritative SOA record, a lame delegation of the zone to that server
is reported.
Discrepancies between the records are reported. Various sanity checks
are performed.
.TP
.B \-A
enters a special address check mode.
.sp
If the first argument is a host name, its addresses will be retrieved,
and for each of the addresses it will be checked whether they map back
to the given host.
.sp
If the first argument is a dotted quad Internet address, its name will
be retrieved, and it will be checked whether the given address is listed
among the known addresses belonging to that host.
.sp
If the \fB\-A\fP flag is specified along with any zone listing option,
a reverse lookup of the address in each encountered A record is performed,
and it is checked whether it is registered and maps back to the name of
the A record.
.SS "SPECIAL OPTIONS"
The following options apply only to the special zone listing modes.
.TP 4
.BI \-L " level"
Recursively generate zone listings up to this level deep.
Level 1 traverses the parent zone and all of its delegated zones.
Each additional level descends into another layer of delegated zones.
.TP
.B \-S
prints statistics about the various types of resource records found
during zone listings, the number of various host classifications,
the number of delegated zones, and some total statistics after
recursive listings.
.TP
.B \-p
causes only the primary nameserver of a zone to be contacted for zone
transfers during zone listings. Normally, zone transfers are obtained
from any one of the authoritative servers that responds.
The primary nameserver is obtained from the SOA record of the zone.
If a specific server is given on the command line, this option will
query that server for the desired nameservers of the zone. This can be
used for testing purposes in case the zone has not been registered yet.
.TP
.BI \-P " prefserver"
gives priority for zone transfers to preferred servers residing in
domains given by the comma-separated list \fIprefserver\fP. The more
domain component labels match, the higher the priority.
If this option is not present, priority is given to servers within
your own domain or parent domains.
The order in which NS records are issued may be unfavorable if they
are subject to BIND 4.9 round-robin reshuffling.
.TP
.BI \-N " skipzone"
prohibits zone transfers for the zones given by the comma-separated
list \fIskipzone\fP. This may be used during recursive zone listings
when certain zones are known to contain bogus information which
should be excluded from further processing.
.SS "COMMON OPTIONS"
The following options can be used in both normal mode and domain
listing mode.
.TP 4
.B \-d
turns on debugging.  Nameserver transactions are shown in detail.
Note that \fB\-dd\fP prints even more debugging output.
.TP
.BI \-f " filename"
writes the resource record output to the given logfile as well as
to standard output.
.TP
.BI \-F " filename"
same as \fB\-f\fP, but exchange the role of stdout and logfile.
All stdout output (including verbose and debug printout) goes to
the logfile, and stdout gets only the extra resource record output
(so that it can be used in pipes).
.TP
.BI \-I " chars"
suppresses warning messages about illegal domain names containing
invalid characters, by specifying such characters in the string
\fIchars\fP. The underscore is a good candidate.
.TP
.B \-i
constructs a query for the "reverse mapping" \fBin-addr.arpa\fP
domain in case a numeric (dotted quad) address was specified.
Useful primarily for zone listing mode, since for numeric regular
lookups such query is done anyway (but with \-i you see the actual
PTR resource record outcome).
.TP
.B \-n
constructs a query for the "reverse mapping" \fBnsap.int\fP
domain in case an nsap address was specified.
This can be used to look up the names associated with nsap addresses,
or to list reverse nsap zones.
An nsap address consists of an even number of hexadecimal digits,
with a maximum of 40, optionally separated by interspersed dots.
An optional prefix "0x" is skipped.
If this option is used, all reverse nsap.int names are by default
printed in forward notation, only to improve readability.
The \fB\-Z\fP option forces the output to be in the official zone
file format.
.TP
.B \-q
be quiet and suppress various warning messages (the ones preceded
by " !!! ").
Serious error messages (preceded by " *** ") are never suppressed.
.TP
.B \-T
prints the time-to-live values during non-verbose output.
By default the ttl is shown only in verbose mode.
.TP
.B \-Z
prints the selected resource record output in full zone file format,
including trailing dot in domain names, plus ttl value and class name.
.SS "OTHER OPTIONS"
The following options are used only in special circumstances.
.TP 4
.BI \-c " class"
allows you to specify a particular resource record class.
Supported are
\fBIN\fP, \fBINTERNET\fP, \fBCS\fP, \fBCSNET\fP, \fBCH\fP, \fBCHAOS\fP,
\fBHS\fP, \fBHESIOD\fP, and the wildcard \fBANY\fP or \fB*\fP.
The default class is \fBIN\fP.
.TP
.B \-e
excludes information about names that are not residing within
the given zone during zone listings, such as some glue records.
For regular queries, it suppresses the printing of the "additional
information" and "authoritative nameserver" sections in the answer
from the nameserver.
.TP
.B \-m
is equivalent to \fB\-t MAILB\fP, which filters
any of types \fBMB\fP, \fBMR\fP, \fBMG\fP, or \fBMINFO\fP.
In addition, \fBMR\fP and \fBMG\fP records will be recursively
expanded into \fBMB\fP records.
.TP
.B \-o
suppresses the resource record output to stdout. Can be used in
combination with the \fB\-f\fP option to separate the resource
record output from verbose and debug comments and error messages.
.TP
.B \-r
causes nameserver recursion to be turned off in the request.
This means that the contacted nameserver will return only data
it has currently cached in its own database.
It will not ask other servers to retrieve the information.
Note that nameserver recursion is always turned off when checking
SOA records using the \fB\-C\fP option. Authoritative servers
should have all relevant information available.
.TP
.B \-R
Normally querynames are assumed to be fully qualified and are
tried as such, unless it is a single name, which is always tried
(and only once) in the default domain.
This option simulates the default BIND behavior by qualifying
any specified name by repeatedly adding search domains, with
the exception that the search terminates immediately if the name
exists but does not have the desired querytype.
The default search domains are constructed from the default domain
by repeatedly peeling off the first component, until a final domain
with only one dot remains.
.TP
.BI \-s " seconds"
specifies a new nameserver timeout value. The program will wait
for a nameserver reply in two attempts of this number of seconds.
Normally it does 2 attempts of 5 seconds per nameserver address tried.
The actual timeout algorithm is slightly more complicated, extending
the timeout value dynamically depending on the number of tries and
the number of nameserver addresses.
.TP
.B \-u
forces the use of virtual circuits (TCP) instead of datagrams (UDP) when
issuing nameserver queries. This is slower, but potentially more reliable.
Note that a virtual circuit is automatically chosen in case a query
exceeds the maximum datagram packet size. Also if a datagram answer
turns out to be truncated, the query is retried using virtual circuit.
A zone transfer is always done via a virtual circuit.
.TP
.B \-w
causes the program to retry forever if the response to a regular query
times out. Normally it will time out after some 10 seconds per
nameserver address tried.
.TP
.B \-V
prints just the version number of the \fBhost\fP program, and exits.
.SS "DEFAULT OPTIONS"
Default options and parameters can be preset in an environment
variable \fBHOST_DEFAULTS\fP using the same syntax as on the command
line. They will be evaluated before the command line arguments.
.SH QUERYTYPES
The following querytypes (resource record types) are supported.
Indicated within parentheses are the various kinds of data fields.
.TP 10
.B A
Host address (dotted quad)
.TP
.B NS
Authoritative nameserver (domain name)
.TP
.B MD
Mail destination (domain name)
.TP
.B MF
Mail forwarder (domain name)
.TP
.B CNAME
Canonical name for an alias (domain name)
.TP
.B SOA
Marks the start of a zone of authority
(domain name of primary, domain name of hostmaster,
serial, refresh, retry, expiration, default ttl)
.TP
.B MB
Mailbox domain name (domain name)
.TP
.B MG
Mail group member (domain name)
.TP
.B MR
Mail rename domain name (domain name)
.TP
.B NULL
Null resource record (no format or data)
.TP
.B WKS
Well-known service description (dotted quad, protocol name, list of services)
.TP
.B PTR
Domain name pointer (domain name)
.TP
.B HINFO
Host information (CPU type string, OS type string)
.TP
.B MINFO
Mailbox or mail list information (request domain name, error domain name)
.TP
.B MX
Mail exchanger (preference value, domain name)
.TP
.B TXT
Descriptive text (one or more strings)
.TP
.B UINFO
User information (string)
.TP
.B UID
User identification (number)
.TP
.B GID
Group identification (number)
.TP
.B UNSPEC
Unspecified binary data (data)
.TP
.B ANY
Matches information of any type available.
.TP
.B MAILB
Matches any of types \fBMB\fP, \fBMR\fP, \fBMG\fP, or \fBMINFO\fP.
.TP
.B MAILA
Matches any of types \fBMD\fP, or \fBMF\fP.
.PP
The following types have been defined in RFC 1183, but
are not yet in general use. They are recognized by this program.
.TP 10
.B RP
Responsible person (domain name for MB, domain name for TXT)
.TP
.B AFSDB
AFS database location (type, domain name)
.TP
.B X25
X25 address (address string)
.TP
.B ISDN
ISDN address (address string, optional subaddress string)
.TP
.B RT
Route through host (preference value, domain name)
.PP
The following types have been defined in RFC 1348, but
are not yet in general use. They are recognized by this program.
RFC 1348 has already been obsoleted by RFC 1637 and RFC 1706,
which defines a new experimental usage of NSAP records.
This program has now hooks to manipulate them.
.TP 10
.B NSAP
NSAP address (encoded address)
.TP
.B NSAP-PTR
NSAP pointer (domain name)
.PP
The following are new types as per RFC 1664 and RFC 1712.
Note that the GPOS type has been withdrawn already, and will be
superseded by the LOC type.
.TP 10
.B PX
X400 to RFC822 mapping (preference value, rfc822 domain, x400 domain)
.TP
.B GPOS
Geographical position (longitude string, latitude string, altitude string)
.PP
The following types have already been reserved in RFC 1700, but are
not yet implemented.
.TP 10
.B SIG
Security signature
.TP
.B KEY
Security key
.PP
The IP v6 address architecture and DNS extensions are defined in
RFC 1884 and RFC 1886.
.TP 10
.B AAAA
IP v6 address (address spec with colons)
.PP
The following type is documented in RFC 1876.
.TP 10
.B LOC
Geographical location (latitude, longitude, altitude, precision)
.PP
The following types have been proposed, but are still in draft.
.TP 10
.B NXT
Next valid record
.TP
.B EID
Endpoint identifier
.TP
.B NIMLOC
Nimrod locator
.TP
.B SRV
Internet service information
.TP
.B ATMA
ATM address
.TP
.B NAPTR
Naming authority URN
.SH EXAMPLES
A very good summary and validation of an entire zone can be obtained
with the following command:
.sp
	\fBhost \-G \-S \-C \-A \-L 1\fP \fIzone\fP
.sp
.SH DIAGNOSTICS
.SS "FAILURE MESSAGES"
The following messages are printed to show the reason
of failure for a particular query. The name of an explicit
server, if specified, may be included. If a special class
was requested, it is also shown.
.TP 4
Nameserver [\fIserver\fP] not running
The contacted server host does not have a nameserver running.
.TP
Nameserver [\fIserver\fP] not responding
The nameserver at the contacted server host did not give a reply
within the specified time frame.
.TP
Nameserver [\fIserver\fP] not reachable
The network route to the intended server host is blocked.
.TP
\fIname\fP does not exist [at \fIserver\fP] (Authoritative answer)
The queryname does definitely not exist at all.
.TP
\fIname\fP does not exist [at \fIserver\fP], try again
The queryname does not exist, but the answer was not authoritative,
so it is still undecided.
.TP
\fIname\fP has no \fItype\fP record [at \fIserver\fP] (Authoritative answer)
The queryname is valid, but the specified type does not exist.
This status is here returned only in case authoritative.
.TP
\fIname\fP \fItype\fP record currently not present [at \fIserver\fP]
The specified type does not exist, but we don't know whether
the queryname is valid or not. The answer was not authoritative.
Perhaps recursion was off, and no data was cached locally.
.TP
\fIname\fP \fItype\fP record not found [at \fIserver\fP], try again
Some intermediate failure, e.g. timeout reaching a nameserver.
.TP
\fIname\fP \fItype\fP record not found [at \fIserver\fP], server failure
Some explicit nameserver failure to process the query, due to internal
or forwarding errors. This may also be returned if the zone data has
expired at a secondary server, of when the server is not authoritative
for some class.
.TP
\fIname\fP \fItype\fP record not found [at \fIserver\fP], no recovery
Some irrecoverable format error, or server refusal.
.TP
\fIname\fP \fItype\fP record query refused [by \fIserver\fP]
The contacted nameserver explicitly refused to answer the query.
Some nameservers are configured to refuse zone transfer requests
that come from arbitrary clients.
.TP
\fIname\fP \fItype\fP record not found [at \fIserver\fP]
The exact reason for failure could not be determined.
(This should not happen).
.TP
\fIzone\fP has lame delegation to \fIserver\fP
If we query a supposedly authoritative nameserver for the SOA record
of a zone, the information should be available and the answer should
be authoritative. If not, a lame delegation is flagged. This is also
done if the server turns out not to exist at all. Ditto if we ask for
a zone transfer and the server cannot provide it.
.TP
No nameservers for \fIzone\fP found
It was not possible to retrieve the name of any nameserver
for the desired zone, in order to do a zone transfer.
.TP
No addresses of nameservers for \fIzone\fP found
We got some nameserver names, but it was not possible to retrieve
addresses for any of them.
.TP
No nameservers for \fIzone\fP responded
When trying all nameservers in succession to do a zone transfer,
none of them were able or willing to provide it.
.SS "WARNING AND ERROR MESSAGES"
Miscellaneous warning messages may be generated.
They are preceded by " !!! " and indicate some non-fatal condition,
usually during the interpretation of the retrieved data.
These messages can be suppressed with the \-q command line option.
.sp
Error messages are preceded by " *** " and indicate a serious problem,
such as format errors in the answers to queries, but also major
violations of the specifications.
Those messages cannot be suppressed.
.TP 4
\fIzone\fP has only one nameserver \fIserver\fP
When retrieving the nameservers for a zone, it appears that only one
single nameserver exists.  This is against the recommendations.
.TP
\fIzone\fP nameserver \fIserver\fP is not canonical (\fIrealserver\fP)
When retrieving the nameservers for a zone, the name of the specified
server appears not to be canonical. This may cause serious operational
problems. The canonical name is given between parentheses.
.TP
empty zone transfer for \fIzone\fP from \fIserver\fP
The zone transfer from the specified server contained no data, perhaps
only the SOA record. This could happen if we query the victim of a
lame delegation which happens to have the SOA record in its cache.
.TP
extraneous NS record for \fIname\fP within \fIzone\fP from \fIserver\fP
During a zone transfer, an NS record appears for a name which is not
a delegated subzone of the current zone.
.TP
extraneous SOA record for \fIname\fP within \fIzone\fP from \fIserver\fP
During a zone transfer, an SOA record appears for a name which is
not the name of the current zone.
.TP
extraneous glue record for \fIname\fP within \fIzone\fP from \fIserver\fP
During a zone transfer, a glue record is included for a name which
is not part of the zone or its delegated subzones. This is done in some
older versions of BIND. It is undesirable since unauthoritative, or even
incorrect, information may be propagated.
.TP
incomplete \fItype\fP record for \fIname\fP
When decoding the resource record data from the answer to a query,
not all required data fields were present. This is frequently the case
for HINFO records of which only one of the two data field is encoded.
.TP
\fIname\fP has both NS and A records within \fIzone\fP from \fIserver\fP
An A record has been defined for the delegated zone \fIname\fP. This is
signalled only during the transfer of the parent \fIzone\fP. It is not
an error, but the overall hostcount may be wrong, since the A record
is counted as a host in the parent zone. This A record is not included
in the hostcount of the delegated zone.
.TP
\fIname\fP \fItype\fP records have different ttl within \fIzone\fP from \fIserver\fP
Resource records of the same name/type/class should have the same ttl value
in zone listings. This is sometimes not the case, due to the independent
definition of glue records or other information in the parent zone, which
is not kept in sync with the definition in the delegated zone.
.TP
\fIname\fP \fItype\fP record has illegal name
The name of an A or MX record contains invalid characters.
Only alphanumeric characters and hyphen '-' are valid in
components (labels) between dots.
.TP
\fIname\fP \fItype\fP host \fIserver\fP has illegal name
The name of an NS or MX target host contains invalid characters.
Only alphanumeric characters and hyphen '-' are valid in
components (labels) between dots.
.TP
\fIname\fP \fItype\fP host \fIserver\fP does not exist
The NS or MX target host \fIserver\fP does not exist at all.
In case of NS, a lame delegation of \fIname\fP to \fIserver\fP
is flagged.
.TP
\fIname\fP \fItype\fP host \fIserver\fP has no A record
The NS or MX target host \fIserver\fP has no address.
In case of NS, a lame delegation of \fIname\fP to \fIserver\fP
is flagged.
.TP
\fIname\fP \fItype\fP host \fIserver\fP is not canonical
The NS or MX target host \fIserver\fP is not a canonical name.
This may cause serious operational problems during domain data
retrieval, or electronic mail delivery.
.TP
\fIname\fP address \fIA.B.C.D\fP is not registered
The reverse lookup of the address of an A record failed in an
authoritative fashion. It was not present in the corresponding
in-addr.arpa zone.
.TP
\fIname\fP address \fIA.B.C.D\fP maps to \fIrealname\fP
The reverse lookup of the address of an A record succeeded,
but it did not map back to the name of the A record.
There may be A records with different names for the same address.
In the reverse in-addr.arpa zone there is usually only one PTR to
the ``official'' host name.
.TP
\fIzone\fP SOA record at \fIserver\fP is not authoritative
When checking the SOA for a zone at one of its supposedly
authoritative nameservers, the SOA information turns out
to be not authoritative.  This could be determined by making
a query without nameserver recursion turned on.
.TP
\fIzone\fP SOA primary \fIserver\fP is not advertised via NS
The primary nameserver is not among the list of nameservers
retrieved via NS records for the zone.
This is not an error per se, since only publicly accessible
nameservers may be advertised, and others may be behind a
firewall.
.TP
\fIzone\fP SOA primary \fIserver\fP has illegal name
The name of the primary nameserver contains invalid characters.
.TP
\fIzone\fP SOA hostmaster \fImailbox\fP has illegal mailbox
The name of the hostmaster mailbox contains invalid characters.
A common mistake is to use an RFC822 email address with a ``@'',
whereas the at-sign should have been replaced with a dot.
.TP
\fIzone\fP SOA serial has high bit set
Although the serial number is an unsigned 32-bit value, overflow
into the high bit can inadvertently occur by making inappropriate
use of the dotted decimal notation in the zone file. This may lead
to synchronization failures between primary and secondary servers.
.TP
\fIzone\fP SOA retry exceeds refresh
A failing refresh would be retried after it is time for the
next refresh.
.TP
\fIzone\fP SOA refresh+retry exceeds expire
The retry after a failing refresh would be done after the data
has already expired.
.TP
\fIserver1\fP and \fIserver2\fP have different primary for \fIzone\fP
If the SOA record is different, the zone data is probably different
as well. What you get depends on which server you happen to query.
.TP
\fIserver1\fP and \fIserver2\fP have different hostmaster for \fIzone\fP
If the SOA record is different, the zone data is probably different
as well. What you get depends on which server you happen to query.
.TP
\fIserver1\fP and \fIserver2\fP have different serial for \fIzone\fP
This is usually not an error, but happens during the period after the
primary server has updated its zone data, but before a secondary
performed a refresh. Nevertheless there could be an error if a mistake
has been made in properly adapting the serial number.
.TP
\fIserver1\fP and \fIserver2\fP have different refresh for \fIzone\fP
If the SOA record is different, the zone data is probably different
as well. What you get depends on which server you happen to query.
.TP
\fIserver1\fP and \fIserver2\fP have different retry for \fIzone\fP
If the SOA record is different, the zone data is probably different
as well. What you get depends on which server you happen to query.
.TP
\fIserver1\fP and \fIserver2\fP have different expire for \fIzone\fP
If the SOA record is different, the zone data is probably different
as well. What you get depends on which server you happen to query.
.TP
\fIserver1\fP and \fIserver2\fP have different defttl for \fIzone\fP
If the SOA record is different, the zone data is probably different
as well. What you get depends on which server you happen to query.
.SH "EXIT STATUS"
The program returns a zero exit status if the requested information
could be retrieved successfully, or in case zone listings or SOA
checks were performed without any serious error.
Otherwise it returns a non-zero exit status.
.SH ENVIRONMENT
.SS "CUSTOMIZING HOST NAME LOOKUP"
In general, if the name supplied by the user does not have any dots
in it, a default domain is appended to the end. This domain is usually
defined in the \fB/etc/resolv.conf\fP file. If not, it is derived by
taking the local hostname and taking everything after its first dot.
.PP
.fw LOCALDOMAIN
The user can override this, and specify a different default domain,
by defining it in the environment variable \fILOCALDOMAIN\fP.
.PP
.fw HOSTALIASES
In addition, the user can supply his own single-word abbreviations
for host names. They should be in a file consisting of one line per
abbreviation. Each line contains an abbreviation, white space, and
then the fully qualified host name. The name of this file must be
specified in the environment variable \fIHOSTALIASES\fP.
.SH "SPECIAL CONSIDERATIONS"
The complete set of resource record information for a domain name
is available from an authoritative nameserver only. Therefore,
if you query another server with the "-a" option, only a subset
of the data may be presented, since this option asks for any data
that the latter server currently knows about, not all data that
may possibly exist.  Note that the "-v" option shows whether an
answer is authoritative or not.
.PP
When listing a zone with the "-l" option, information will be fetched
from authoritative nameservers for that zone. This is implemented by
doing a complete zone transfer and then filtering out the information
that you have asked for.
Note that direct contact with such nameservers must be possible for
this option to work.
This option should be used with caution. Servers may be configured
to refuse zone transfers if they are flooded with requests.
.SH "RELATED DOCUMENTATION"
rfc883, Domain names - implementation and specification
.br
rfc920, Domain requirements
.br
rfc952, DOD Internet host table specification
.br
rfc974, Mail routing and the domain system
.br
rfc1032, Domain administrators guide
.br
rfc1033, Domain administrators operations guide
.br
rfc1034, Domain names - concepts and facilities
.br
rfc1035, Domain names - implementation and specification
.br
rfc1101, DNS encoding of network names and other types
.br
rfc1123, Requirements for Internet hosts - application
.br
rfc1183, New DNS RR definitions
.br
rfc1348, DNS NSAP RRs
.br
rfc1535, A security problem and proposed correction
.br
rfc1536, Common DNS implementation errors
.br
rfc1537, Common DNS data file configuration errors
.br
rfc1591, Domain Name System structure and delegation
.br
rfc1637, DNS NSAP resource records
.br
rfc1664, Using DNS to distribute X.400 address mappings
.br
rfc1700, Assigned numbers
.br
rfc1706, DNS NSAP resource records
.br
rfc1712, DNS encoding of geographical location
.br
rfc1713, Tools for DNS debugging
.br
rfc1794, DNS support for load balancing
.br
rfc1876, Expressing location information in the DNS
.br
rfc1884, IP v6 addressing architecture
.br
rfc1886, DNS extensions to support IP v6
.br
rfc1912, Common DNS operational and configuration errors
.br
rfc1982, Serial number arithmetic
.br
rfc1995, Incremental zone transfer in DNS
.br
rfc1996, Prompt notification of zone changes
.SH AUTHOR
This program is originally from Rutgers University.
.br
Rewritten by Eric Wassenaar, NIKHEF, <e07@nikhef.nl>
.SH "SEE ALSO"
named(8), resolv.conf(5), resolver(3)
named (8)
.SH BUGS
Unexpected effects can happen when you type a name that is not
part of the local domain.  Please always keep in mind the
fact that the local domain name is tacked onto the end of every
name, unless it ends in a dot.  Only if this fails is the name
used unchanged.
.PP
The -l option only tries the first name server listed for the
domain that you have requested.  If this server is dead, you
may need to specify a server manually. E.g. to get a listing
of foo.edu, you could try "host -t ns foo.edu" to get a list
of all the name servers for foo.edu, and then try "host -l foo.edu xxx"
for all xxx on the list of name servers, until you find one that
works.