mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-05 09:14:03 +00:00
379 lines
16 KiB
Groff
379 lines
16 KiB
Groff
.\" ++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 "April 17, 1993"
|
|
.UC 4
|
|
.SH NAME
|
|
named \- Internet domain name server
|
|
.SH SYNOPSIS
|
|
.B named
|
|
[
|
|
.B \-d
|
|
.I debuglevel
|
|
] [
|
|
.B \-p
|
|
.I port#
|
|
] [{\-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 a different port number. The default is the standard port number
|
|
as returned by getservbyname(3) for service ``domain''.
|
|
.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.
|
|
.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.
|
|
.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'forwarders\ '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 . named.root
|
|
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
|
|
; slave
|
|
|
|
.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 ``named.root'' 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 ``named.root'' is
|
|
in the same format as ``berkeley.edu.zone''. There can be more than one
|
|
``cache'' file specified. The ``named.root'' 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 RFC883. 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 ``slave'' 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 access directly to the
|
|
Internet, but wish to act as though they do.
|
|
.LP
|
|
The ``slave'' line (shown commented out) is used to put the server in slave
|
|
mode. In this mode, the server will only make queries to forwarders. This
|
|
option is normally used on machine that wish to run a server but for
|
|
physical or administrative reasons cannot be given access to the Internet,
|
|
but have access to a host that does have access.
|
|
.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 primative
|
|
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, interrim 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 ``max-fetch'' directive (not shown) can be used to override the default
|
|
limit (which is 10) to the number of named-xfer subprocesses which \s-1BIND\s+1
|
|
can spawn at any one time.
|
|
.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 RFC883)).
|
|
.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. (
|
|
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 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 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 -DSTATS. Statistics data is appended to the file.
|
|
.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(3)
|
|
(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 (/var/run/named.pid on newer systems)
|
|
/var/tmp/named.run debug output
|
|
/var/tmp/named_dump.db dump of the name server database
|
|
/var/tmp/named.stats nameserver statistics data
|
|
.fi
|
|
.SH "SEE ALSO"
|
|
kill(1), gethostbyname(3), signal(3),
|
|
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
|