444 lines
20 KiB
Groff
444 lines
20 KiB
Groff
.\" $NetBSD: named.8,v 1.4 1997/06/08 05:44:15 lukem Exp $
|
|
.\"
|
|
.\" ++Copyright++ 1985
|
|
.\" -
|
|
.\" Copyright (c) 1985
|
|
.\" 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--
|
|
.\"
|
|
.\" @(#)named.8 6.6 (Berkeley) 2/14/89
|
|
.\"
|
|
.TH NAMED 8 "June 20, 1995"
|
|
.UC 4
|
|
.SH NAME
|
|
named \- Internet domain name server
|
|
.SH SYNOPSIS
|
|
.B named
|
|
[
|
|
.B \-d
|
|
.I debuglevel
|
|
] [
|
|
.B \-p
|
|
.IR port# [\fB/\fP\fIlocalport#\fP]
|
|
] [{\-b}
|
|
.I bootfile
|
|
] [
|
|
.B \-q
|
|
] [
|
|
.B \-r
|
|
]
|
|
.SH DESCRIPTION
|
|
.I Named
|
|
is the Internet domain name server.
|
|
See RFC's 1033, 1034, and 1035 for more information on the Internet
|
|
name-domain system. Without any arguments,
|
|
.I named
|
|
will read the default boot file
|
|
.IR /etc/named.boot ,
|
|
read any initial data and listen for queries.
|
|
.PP
|
|
Options are:
|
|
.TP
|
|
.B \-d
|
|
Print debugging information.
|
|
A number after the ``d'' determines the level of
|
|
messages printed.
|
|
.TP
|
|
.B \-p
|
|
Use nonstandard port numbers. The default is the standard port number
|
|
as returned by getservbyname(3) for service ``domain''.
|
|
The argument can specify two port numbers separated by a slash (``\fB/\fP'')
|
|
in which case the first port is that used when contacting remote servers,
|
|
and the second one is the service port bound by the local instance of
|
|
.IR named .
|
|
This is used mostly for debugging purposes.
|
|
.TP
|
|
.B \-b
|
|
Use an alternate boot file. This is optional and allows you to
|
|
specify a file with a leading dash.
|
|
.TP
|
|
.B \-q
|
|
Trace all incoming queries if \fInamed\fP has been compiled with
|
|
\fIQRYLOG\fP defined. \fINOTE:\fP this option is deprecated in favour
|
|
of the boot file directive ``options query-log''.
|
|
.TP
|
|
.B \-r
|
|
Turns recursion off in the server. Answers can come only from local
|
|
(primary or secondary) zones. This can be used on root servers.
|
|
\fINOTE:\fP this option is deprecated in favour
|
|
of the boot file directive ``options no-recursion''.
|
|
.PP
|
|
Any additional argument is taken as the name of the boot file.
|
|
If multiple boot files are specified, only the last is used.
|
|
.PP
|
|
The boot file contains information about where the name server is to get
|
|
its initial data.
|
|
Lines in the boot file cannot be continued on subsequent lines.
|
|
The following is a small example:
|
|
.in +2m
|
|
.nf
|
|
|
|
;
|
|
; boot file for name server
|
|
;
|
|
directory /usr/local/adm/named
|
|
|
|
.ta \w'check-names\ 'u +\w'6.32.128.IN-ADDR.ARPA\ 'u +\w'128.32.137.8 128.32.137.3\ 'u
|
|
; type domain source host/file backup file
|
|
|
|
cache . root.cache
|
|
primary Berkeley.EDU berkeley.edu.zone
|
|
primary 32.128.IN-ADDR.ARPA ucbhosts.rev
|
|
secondary CC.Berkeley.EDU 128.32.137.8 128.32.137.3 cc.zone.bak
|
|
secondary 6.32.128.IN-ADDR.ARPA 128.32.137.8 128.32.137.3 cc.rev.bak
|
|
primary 0.0.127.IN-ADDR.ARPA localhost.rev
|
|
forwarders 10.0.0.78 10.2.0.78
|
|
limit transfers-in 10
|
|
limit datasize 64M
|
|
limit files 256
|
|
options forward-only query-log fake-iquery
|
|
check-names primary fail
|
|
check-names secondary warn
|
|
check-names response ignore
|
|
|
|
.DT
|
|
.fi
|
|
.in
|
|
The ``directory'' line causes the server to change its working directory to
|
|
the directory specified. This can be important for the correct processing
|
|
of \s-1$INCLUDE\s+1 files in primary zone files.
|
|
.LP
|
|
The ``cache'' line specifies that data in ``root.cache'' is to be placed in
|
|
the backup cache. Its main use is to specify data such as locations of root
|
|
domain servers. This cache is not used during normal operation, but is used
|
|
as ``hints'' to find the current root servers. The file ``root.cache'' is
|
|
in the same format as ``berkeley.edu.zone''. There can be more than one
|
|
``cache'' file specified. The ``root.cache'' file should be retrieved
|
|
periodically from \s-1FTP.RS.INTERNIC.NET\s+1 since it contains a list of
|
|
root servers, and this list changes periodically.
|
|
.LP
|
|
The first example ``primary'' line states that the file
|
|
``berkeley.edu.zone'' contains authoritative data for the ``Berkeley.EDU''
|
|
zone. The file ``berkeley.edu.zone'' contains data in the master file
|
|
format described in RFC 883. All domain names are relative to the origin, in
|
|
this case, ``Berkeley.EDU'' (see below for a more detailed description).
|
|
The second ``primary'' line states that the file ``ucbhosts.rev'' contains
|
|
authoritative data for the domain ``32.128.IN-ADDR.ARPA,'' which is used to
|
|
translate addresses in network 128.32 to hostnames. Each master file should
|
|
begin with an SOA record for the zone (see below).
|
|
.LP
|
|
The first example ``secondary'' line specifies that all authoritative data
|
|
under ``CC.Berkeley.EDU'' is to be transferred from the name server at
|
|
128.32.137.8. If the transfer fails it will try 128.32.137.3 and continue
|
|
trying the addresses, up to 10, listed on this line. The secondary copy is
|
|
also authoritative for the specified domain. The first non-dotted-quad
|
|
address on this line will be taken as a filename in which to backup the
|
|
transferred zone. The name server will load the zone from this backup file
|
|
if it exists when it boots, providing a complete copy even if the master
|
|
servers are unreachable. Whenever a new copy of the domain is received by
|
|
automatic zone transfer from one of the master servers, this file will be
|
|
updated. If no file name is given, a temporary file will be used, and will
|
|
be deleted after each successful zone transfer. This is not recommended
|
|
since it is a needless waste of bandwidth. The second example ``secondary''
|
|
line states that the address-to-hostname mapping for the subnet 128.32.136
|
|
should be obtained from the same list of master servers as the previous zone.
|
|
.LP
|
|
The ``forwarders'' line specifies the addresses of sitewide servers that
|
|
will accept recursive queries from other servers. If the boot file
|
|
specifies one or more forwarders, then the server will send all queries for
|
|
data not in the cache to the forwarders first. Each forwarder will be asked
|
|
in turn until an answer is returned or the list is exhausted. If no answer
|
|
is forthcoming from a forwarder, the server will continue as it would have
|
|
without the forwarders line unless it is in ``forward-only'' mode. The
|
|
forwarding facility is useful to cause a large sitewide cache to be
|
|
generated on a master, and to reduce traffic over links to outside servers.
|
|
It can also be used to allow servers to run that do not have direct access
|
|
to the Internet, but wish to look up exterior names anyway.
|
|
.LP
|
|
The ``slave'' line (deprecated) is allowed for backward compatibility. Its
|
|
meaning is identical to ``options forward-only''.
|
|
.LP
|
|
The ``sortlist'' line can be used to indicate networks that are to be
|
|
preferred over other networks. Queries for host addresses from hosts on the
|
|
same network as the server will receive responses with local network
|
|
addresses listed first, then addresses on the sort list, then other
|
|
addresses.
|
|
.LP
|
|
The ``xfrnets'' directive (not shown) can be used to implement primitive
|
|
access control. If this directive is given, then your name server will
|
|
only answer zone transfer requests from hosts which are on networks listed
|
|
in your ``xfrnets'' directives. This directive may also be given as
|
|
``tcplist'' for compatibility with older, interim servers.
|
|
.LP
|
|
The ``include'' directive (not shown) can be used to process the contents
|
|
of some other file as though they appeared in place of the ``include''
|
|
directive. This is useful if you have a lot of zones or if you have
|
|
logical groupings of zones which are maintained by different people.
|
|
The ``include'' directive takes one argument, that being the name of the
|
|
file whose contents are to be included. No quotes are necessary around
|
|
the file name.
|
|
.LP
|
|
The ``bogusns'' directive (not shown) tells \s-1BIND\s+1 that no queries
|
|
are to be sent to the specified name server addresses (which are specified
|
|
as dotted quads, not as domain names). This is useful when you know that
|
|
some popular server has bad data in a zone or cache, and you want to avoid
|
|
contamination while the problem is being fixed.
|
|
.LP
|
|
The ``limit'' directive can be used to change \s-1BIND\s+1's internal limits,
|
|
some of which (\fBdatasize\fP, for example) are implemented by the system and
|
|
others (like \fBtransfers-in\fP) by \s-1BIND\s+1 itself. The number following
|
|
the limit name can be scaled by postfixing a ``k,'' ``m,'' or ``g'' for
|
|
kilobytes, megabytes, and gigabytes respectively.
|
|
\fBdatasize\fP's argument sets the process data size enforced by the kernel.
|
|
\fINote:\fP not all systems provide a call to implement this -- on such
|
|
systems, the use of the \fBdatasize\fP parameter of ``limit'' will result in
|
|
a warning message.
|
|
\fBtransfers-in\fP's argument is the number of \fInamed-xfer\fP subprocesses
|
|
which \s-1BIND\s+1 will spawn at any one time.
|
|
\fBtransfers-per-ns\fP's argument is the maximum number of zone transfers to
|
|
be simultaneously initiated to any given remote name server.
|
|
\fBfiles\fP's argument sets the number of file descriptors available to
|
|
the process. \fINote:\fP not all systems provide a call to implement
|
|
this -- on such systems, the use of the \fBfiles\fP parameter of ``limit''
|
|
will result in a warning message.
|
|
.LP
|
|
The ``options'' directive introduces a boolean specifier that changes the
|
|
behaviour of \s-1BIND\s+1. More than one option can be specified in a single
|
|
directive. The currently defined options are as follows:
|
|
\fBno-recursion\fP, which will cause \s-1BIND\s+1 to answer with a referral
|
|
rather than actual data whenever it receives a query for a name it is not
|
|
authoritative for -- don't set this on a server that is listed in any host's
|
|
\fIresolv.conf\fP file;
|
|
\fBno-fetch-glue\fP, which keeps \s-1BIND\s+1 from fetching missing glue when
|
|
constructing the ``additional data'' section of a response; this can be used
|
|
in conjunction with \fBno-recursion\fP to prevent \s-1BIND\s+1's cache from
|
|
ever growing in size or becoming corrupted;
|
|
\fBquery-log\fP, which causes all queries to be logged via
|
|
syslog(8) -- this is a lot of data, don't turn it on lightly;
|
|
\fBforward-only\fP, which causes the server to query only its forwarders --
|
|
this option is normally used on machine that wishes to run a server but for
|
|
physical or administrative reasons cannot be given access to the Internet;
|
|
and \fBfake-iquery\fP, which tells \s-1BIND\s+1 to send back a useless and
|
|
bogus reply to ``inverse queries'' rather than responding with an error --
|
|
this is helpful if you have a lot of microcomputers or SunOS hosts or both.
|
|
.LP
|
|
The ``check-names'' directive tells \s-1BIND\s+1 to check names in either
|
|
``primary'' or ``secondary'' zone files, or in messages (``response'')
|
|
received during recursion (for example, those which would be forwarded back
|
|
to a firewalled requestor). For each type of name,
|
|
\s-1BIND\s+1 can be told to ``fail'', such that a zone would not be loaded
|
|
or a response would not be cached or forwarded, or merely ``warn'' which
|
|
would cause a message to be emitted in the system operations logs, or to
|
|
``ignore'' the badness of a name and process it in the traditional fashion.
|
|
Names are considered good if they match RFC 952's expectations (if they are
|
|
host names), or if they consist only of printable \s-1ASCII\s+1 characters
|
|
(if they are not host names).
|
|
.LP
|
|
The ``max-fetch'' directive (not shown) is allowed for backward compatibility;
|
|
its meaning is identical to ``limit transfers-in''.
|
|
.PP
|
|
The master file consists of control information and a list of resource
|
|
records for objects in the zone of the forms:
|
|
.RS
|
|
.nf
|
|
|
|
$INCLUDE <filename> <opt_domain>
|
|
$ORIGIN <domain>
|
|
<domain> <opt_ttl> <opt_class> <type> <resource_record_data>
|
|
|
|
.fi
|
|
.RE
|
|
where
|
|
.I domain
|
|
is "." for root, "@" for the current origin, or a standard domain
|
|
name. If
|
|
.I domain
|
|
is a standard domain name that does not end with ``.'', the current origin
|
|
is appended to the domain. Domain names ending with ``.'' are
|
|
unmodified.
|
|
The
|
|
.I opt_domain
|
|
field is used to define an origin for the data in an included file.
|
|
It is equivalent to placing a $ORIGIN statement before the first
|
|
line of the included file. The field is optional.
|
|
Neither the
|
|
.I opt_domain
|
|
field nor $ORIGIN statements in the included file modify the current origin
|
|
for this file.
|
|
The
|
|
.I opt_ttl
|
|
field is an optional integer number for the time-to-live field.
|
|
It defaults to zero, meaning the minimum value specified in the SOA
|
|
record for the zone.
|
|
The
|
|
.I opt_class
|
|
field is the object address type; currently only one type is supported,
|
|
.BR IN ,
|
|
for objects connected to the DARPA Internet.
|
|
The
|
|
.I type
|
|
field contains one of the following tokens; the data expected in the
|
|
.I resource_record_data
|
|
field is in parentheses.
|
|
.TP "\w'MINFO 'u"
|
|
A
|
|
a host address (dotted quad)
|
|
.IP NS
|
|
an authoritative name server (domain)
|
|
.IP MX
|
|
a mail exchanger (domain), preceded by a preference value (0..32767),
|
|
with lower numeric values representing higher logical preferences.
|
|
.IP CNAME
|
|
the canonical name for an alias (domain)
|
|
.IP SOA
|
|
marks the start of a zone of authority (domain of originating host,
|
|
domain address of maintainer, a serial number and the following
|
|
parameters in seconds: refresh, retry, expire and minimum TTL (see RFC 883)).
|
|
.IP NULL
|
|
a null resource record (no format or data)
|
|
.IP RP
|
|
a Responsible Person for some domain name (mailbox, TXT-referral)
|
|
.IP PTR
|
|
a domain name pointer (domain)
|
|
.IP HINFO
|
|
host information (cpu_type OS_type)
|
|
.PP
|
|
Resource records normally end at the end of a line,
|
|
but may be continued across lines between opening and closing parentheses.
|
|
Comments are introduced by semicolons and continue to the end of the line.
|
|
.PP
|
|
Note that there are other resource record types, not shown here. You should
|
|
consult the \s-1BIND\s+1 Operations Guide (``\s-1BOG\s+1'') for the complete
|
|
list. Some resource record types may have been standardized in newer RFC's
|
|
but not yet implemented in this version of \s-1BIND\s+1.
|
|
.PP
|
|
Each master zone file should begin with an SOA record for the zone.
|
|
An example SOA record is as follows:
|
|
.LP
|
|
.nf
|
|
@ IN SOA ucbvax.Berkeley.EDU. rwh.ucbvax.Berkeley.EDU. (
|
|
.ta \w'x\ IN\ SOA\ 'u +\w'1989020501\ 'u
|
|
1989020501 ; serial
|
|
10800 ; refresh
|
|
3600 ; retry
|
|
3600000 ; expire
|
|
86400 ) ; minimum
|
|
.fi
|
|
.LP
|
|
The SOA specifies a serial number, which should be changed each time the
|
|
master file is changed. Note that the serial number can be given as a
|
|
dotted number, but this is a \fIvery\fP unwise thing to do since the
|
|
translation to normal integers is via concatenation rather than
|
|
multiplication and addition. You can spell out the year, month, day of
|
|
month, and 0..99 version number and still fit inside the unsigned 32-bit
|
|
size of this field. It's true that we will have to rethink this strategy in
|
|
the year 4294 (Greg.) but we're not worried about it. Secondary servers
|
|
check the serial number at intervals specified by the refresh time in
|
|
seconds; if the serial number changes, a zone transfer will be done to load
|
|
the new data. If a master server cannot be contacted when a refresh is due,
|
|
the retry time specifies the interval at which refreshes should be attempted.
|
|
If a master server cannot be contacted within the interval given by the
|
|
expire time, all data from the zone is discarded by secondary servers. The
|
|
minimum value is the time-to-live (``\s-1TTL\s+1'') used by records in the
|
|
file with no explicit time-to-live value.
|
|
.SH NOTES
|
|
The boot file directives ``domain'' and ``suffixes'' have been
|
|
obsoleted by a more useful resolver-based implementation of
|
|
suffixing for partially qualified domain names. The prior mechanisms
|
|
could fail under a number of situations, especially when then local
|
|
nameserver did not have complete information.
|
|
.sp
|
|
The following signals have the specified effect when sent to the
|
|
server process using the
|
|
.IR kill (1)
|
|
command.
|
|
.IP SIGHUP
|
|
Causes server to read named.boot and reload the database. If the server
|
|
is built with the FORCED_RELOAD compile-time option, then SIGHUP will
|
|
also cause the server to check the serial number on all secondary zones.
|
|
Normally the serial numbers are only checked at the SOA-specified intervals.
|
|
.IP SIGINT
|
|
Dumps the current data base and cache to /var/tmp/named_dump.db
|
|
.IP SIGIOT
|
|
Dumps statistics data into /var/tmp/named.stats if the server is
|
|
compiled with -DSTATS. Statistics data is appended to the file. Some
|
|
systems use SIGABRT rather than SIGIOT for this.
|
|
.IP SIGSYS
|
|
Dumps the profiling data in /var/tmp if the server is compiled
|
|
with profiling (server forks, chdirs and exits).
|
|
.IP SIGTERM
|
|
Dumps the primary and secondary database files.
|
|
Used to save modified data on shutdown if the
|
|
server is compiled with dynamic updating enabled.
|
|
.IP SIGUSR1
|
|
Turns on debugging; each SIGUSR1 increments debug level.
|
|
(SIGEMT on older systems without SIGUSR1)
|
|
.IP SIGUSR2
|
|
Turns off debugging completely.
|
|
(SIGFPE on older systems without SIGUSR2)
|
|
.IP SIGWINCH
|
|
Toggles logging of all incoming queries via syslog(8)
|
|
(requires server to have been built with the QRYLOG option).
|
|
.SH FILES
|
|
.nf
|
|
.ta \w'/var/tmp/named_dump.db 'u
|
|
/etc/named.boot name server configuration boot file
|
|
/etc/named.pid the process id (on older systems)
|
|
/var/run/named.pid the process id (on newer systems)
|
|
/var/tmp/named_dump.db dump of the name server database
|
|
/var/tmp/named.run debug output
|
|
/var/tmp/named.stats nameserver statistics data
|
|
.fi
|
|
.SH "SEE ALSO"
|
|
kill(1), gethostbyname(3), signal(2),
|
|
resolver(3), resolver(5), hostname(7),
|
|
RFC 882, RFC 883, RFC 973, RFC 974, RFC 1033, RFC 1034, RFC 1035, RFC 1123,
|
|
\fIName Server Operations Guide for \s-1BIND\s+1\fR
|