NetBSD/dist/bind/man/named.conf.5

.\"     $NetBSD: named.conf.5,v 1.2 1999/11/29 18:28:18 christos Exp $
.\"
.\" Copyright (c) 1999 by Internet Software Consortium
.\"
.\" 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.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS
.\" ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE
.\" CONSORTIUM 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.

.Dd January 7, 1999
.Dt NAMED.CONF 5
.Os BSD 4

.Sh NAME
.Nm named.conf
.Nd configuration file for
.Xr named 8

.Sh OVERVIEW

BIND 8 is much more configurable than previous release of BIND.  There
are entirely new areas of configuration, such as access control lists
and categorized logging.  Many options that previously applied to all
zones can now be used selectively.  These features, plus a
consideration of future configuration needs led to the creation of a
new configuration file format.

.Ss General Syntax

A BIND 8 configuration consists of two general features, statements
and comments.  All statements end with a semicolon.  Many statements
can contain substatements, which are each also terminated with a
semicolon.

.Pp
The following statements are supported:
.Bl -tag -width 1
.It Ic logging
specifies what the server logs, and where the log messages are sent

.It Ic options
controls global server configuration options and sets defaults for other
statements

.It Ic zone
defines a zone

.It Ic acl
defines a named IP address matching list, for access control and other uses

.It Ic key
specifies key information for use in authentication and authorization

.It Ic trusted-keys
defines DNSSEC keys that are preconfigured into the server and implicitly
trusted

.It Ic server
sets certain configuration options for individual remote servers

.It Ic controls
declares control channels to be used by the
.Nm ndc
utility

.It Ic include
includes another file

.El

The
.Ic logging
and
.Ic options
statements may only occur once per configuration, while the rest may
appear numerous times.  Further detail on each statement is provided
in individual sections below.

Comments may appear anywhere that whitespace may appear in a BIND
configuration file.  To appeal to programmers of all kinds, they can
be written in C, C++, or shell/perl constructs.

C-style comments start with the two characters
.Li /*
(slash, star) and end with
.Li */
(star, slash).
Because they are completely delimited with these characters,
they can be used to comment only a portion of a line or to span
multiple lines.

C-style comments cannot be nested.  For example, the following is
not valid because the entire comment ends with the first
.Li */ :

.Bd -literal -offset indent
/* This is the start of a comment.
   This is still part of the comment.
/* This is an incorrect attempt at nesting a comment. */
   This is no longer in any comment. */
.Ed

C++-style comments start with the two characters
.Li //
(slash, slash) and continue to the end of the physical line.
They cannot be continued across multiple physical lines; to have
one logical comment span multiple lines, each line must use the
.Li //
pair.  For example:

.Bd -literal -offset indent
// This is the start of a comment.  The next line
// is a new comment, even though it is logically
// part of the previous comment.
.Ed

Shell-style (or perl-style, if you prefer) comments start with the
character
.Li #
(hash or pound or number or octothorpe or whatever) and continue to
the end of the physical line, like C++ comments.  For example:

.Bd -literal -offset indent
# This is the start of a comment.  The next line
# is a new comment, even though it is logically
# part of the previous comment.
.Ed

.Em WARNING:
you cannot use the
.Li ;
(semicolon) character to start a comment such as you would in a zone
file.  The semicolon indicates the end of a configuration statement,
so whatever follows it will be interpreted as the start of the next
statement.

.Ss Converting from BIND 4.9.x

.Pp
BIND 4.9.x configuration files can be converted to the new format
by using
.Pa src/bin/named/named-bootconf ,
a shell script that is part of the BIND 8.2.x source kit.

.Sh DOCUMENTATION DEFINITIONS

Described below are elements used throughout the BIND configuration
file documentation.  Elements which are only associated with one
statement are described only in the section describing that statement.

.Bl -tag -width 1
.It Va acl_name
The name of an
.Va address_match_list
as defined by the
.Ic acl
statement.

.It Va address_match_list
A list of one or more
.Va ip_addr ,
.Va ip_prefix ,
.Va key_id ,
or
.Va acl_name
elements, as described in the
.Sx ADDRESS MATCH LISTS
section.

.It Va dotted-decimal
One or more integers valued 0 through 255 separated only by dots
(``.''), such as
.Li 123 ,
.Li 45.67
or
.Li 89.123.45.67 .

.It Va domain_name
A quoted string which will be used as a DNS name, for example
.Qq Li my.test.domain .

.It Va path_name
A quoted string which will be used as a pathname, such as
.Qq Li zones/master/my.test.domain .

.It Va ip_addr
An IP address in with exactly four elements in
.Va dotted-decimal
notation.

.It Va ip_port
An IP port
.Va number .
.Va number is limited to
.Li 0
through
.Li 65535 ,
with values below 1024 typically restricted to
root-owned processes.  In some cases an asterisk (``*'') character
can be used as a placeholder to select a random high-numbered port.

.It Va ip_prefix
An IP network specified in
.Va dotted-decimal
form, followed by  ``/''
and then the number of bits in the netmask.  E.g.
.Li 127/8
is
the network
.Li 127.0.0.0
with netmask
.Li 255.0.0.0 .
.Li 1.2.3.0/28
is network
.Li 1.2.3.0
with netmask
.Li 255.255.255.240.

.It Va key_name
A string representing the name of a shared key, to be used for transaction
security.

.It Va number
A non-negative integer with an entire range limited by the range of a
C language signed integer (2,147,483,647 on a machine with 32 bit
integers).  Its acceptable value might further be limited by the
context in which it is used.

.It Va size_spec
A
.Va number ,
the word
.Li unlimited ,
or the word
.Li default .

.Pp
The maximum value of
.Va size_spec
is that of unsigned long integers on the machine.
.Li unlimited
requests unlimited use, or the maximum available amount.
.Li default
uses the limit that was in force when the server was started.

.Pp
A
.Va number
can optionally be followed by a scaling factor:
.Li K
or
.Li k
for kilobytes,
.Li M
or
.Li m
for megabytes, and
.Li G
or
.Li g
for gigabytes, which scale by 1024, 1024*1024, and 1024*1024*1024
respectively.

.Pp
Integer storage overflow is currently silently ignored during
conversion of scaled values, resulting in values less than intended,
possibly even negative.  Using
.Li unlimited
is the best way to safely set a really large number.

.It Va yes_or_no
Either
.Li yes
or
.Li no .
The words
.Li true
and
.Li false
are also accepted, as are the numbers
.Li 1 and
.Li 0 .

.El

.Sh ADDRESS MATCH LISTS
.Ss Syntax

.Bd -literal
\fIaddress_match_list\fR    = 1\&*\fIaddress_match_element\fR

\fIaddress_match_element\fR = [ \&"!\&" ] ( \fIaddress_match_list\fR /
                                  \fIip_address\fR / \fIip_prefix\fR /
                                  \fIacl_name\fR / \&"key \&" \fIkey_id\fR ) \&";\&"
.Ed

.Ss Definition and Usage

Address match lists are primarily used to determine access control for
various server operations.  They are also used to define priorities
for querying other nameservers and to set the addresses on which
.Nm named
will listen for queries.
The elements which constitute an address match list can be any
of the following:

.Bl -bullet
.It
an
.Va ip-address
(in
.Va dotted-decimal
notation,
.It
an
.Va ip-prefix
(in the '/'-notation),
.It
A
.Va key_id ,
as defined by the
.Ic key
statement,
.It
the name of an address match list previously defined with
the
.Ic acl
statement, or
.It
another
.Va address_match_list .
.El

.Pp
Elements can be negated with a leading exclamation mark (``!''), and
the match list names
.Li any ,
.Li none ,
.Li localhost
and
.Li localnets
are predefined.  More information on those names can be found in the
description of the
.Ic acl
statement.

.Pp
The addition of the
.Ic key
clause made the name of this syntactic element something of a
misnomer, since security keys can be used to validate access without
regard to a host or network address.  Nonetheless, the term ``address
match list'' is still used throughout the documentation.

.Pp
When a given IP address or prefix is compared to an address match
list, the list is traversed in order until an element matches.  The
interpretation of a match depends on whether the list is being used
for access control, defining
.Ic listen-on
ports, or as a topology, and whether the element was
negated.

.Pp
When used as an access control list, a non-negated match allows access
and a negated match denies access.  If there is no match at all in the
list, access is denied.  The clauses
.Ic allow-query ,
.Ic allow-transfer ,
.Ic allow-update ,
.Ic allow-recursion ,
and
.Ic blackhole
all use address match lists like this.  Similarly, the
.Ic listen-on
option will cause the server to not accept queries on any of the
machine's addresses which do not match the list.

.Pp
When used with the
.Ic topology
option, a non-negated match returns a distance based on its position on
the list (the closer the match is to the start of the list, the
shorter the distance is between it and the server).  A negated match
will be assigned the maximum distance from the server.  If there is no
match, the address will get a distance which is further than any
non-negated list element, and closer than any negated element.

.Pp
Because of the first-match aspect of the algorithm, an element that
defines a subset of another element in the list should come before the
broader element, regardless of whether either is negated.  For
example, in
.Dl 1.2.3/24; !1.2.3.13
the 1.2.3.13 element is completely useless, because the algorithm will
match any lookup for 1.2.3.13 to the 1.2.3/24 element.  Using
.Dl !1.2.3.13; 1.2.3/24
fixes that problem by having 1.2.3.13 blocked by the negation but all
other 1.2.3.* hosts fall through.

.Sh THE LOGGING STATEMENT
.Ss Syntax

.Bd -literal
logging {
  [ channel \fIchannel_name\fR {
    ( file \fIpath_name\fR
       [ versions ( \fInumber\fR | unlimited ) ]
       [ size \fIsize_spec\fR ]
     | syslog ( kern | user | mail | daemon | auth | syslog | lpr |
                news | uucp | cron | authpriv | ftp |
                local0 | local1 | local2 | local3 |
                local4 | local5 | local6 | local7 )
     | null );

    [ severity ( critical | error | warning | notice |
                 info  | debug [ \fIlevel\fR ] | dynamic ); ]
    [ print-category \fIyes_or_no\fR; ]
    [ print-severity \fIyes_or_no\fR; ]
    [ print-time \fIyes_or_no\fR; ]
  }; ]

  [ category \fIcategory_name\fR {
    \fIchannel_name\fR; [ \fIchannel_name\fR; ... ]
  }; ]
  ...
};
.Ed

.Ss Definition and Usage

The
.Ic logging
statement configures a wide variety of logging options for the nameserver.
Its
.Ic channel
phrase associates output methods, format options and
severity levels with a name that can then be used with the
.Ic category
phrase to select how various classes of messages are logged.

.Pp
Only one
.Ic logging
statement is used to define as many channels and categories as are wanted.
If there are multiple logging statements in a configuration, the first
defined determines the logging, and warnings are issued for the
others.  If there is no logging statement, the logging configuration
will be:

.Bd -literal
    logging {
        category default { default_syslog; default_debug; };
        category panic { default_syslog; default_stderr; };
        category packet { default_debug; };
        category eventlib { default_debug; };
    };
.Ed

The logging configuration is established as soon as the
.Ic logging
statement is parsed.  If you want to redirect
messages about processing of the entire configuration file, the
.Ic logging
statement must appear first.  Even if you do not
redirect configuration file parsing messages, we recommend
always putting the
.Ic logging
statement first so that this rule need not be consciously recalled if
you ever do need want the parser's messages relocated.

.Ss The channel phrase

All log output goes to one or more ``channels''; you can make as many
of them as you want.

.Pp
Every channel definition must include a clause that says whether
messages selected for the channel go to a file, to a particular syslog
facility, or are discarded.  It can optionally also limit the message
severity level that will be accepted by the channel (default is
.Li info ) ,
and whether to include a time stamp generated by
.Nm named ,
the category name, or severity level.  The default is not to include
any of those three.

.Pp
The word
.Li null
as the destination option for the
channel will cause all messages sent to it to be discarded; other
options for the channel are meaningless.

.Pp
The
.Ic file
clause can include limitations both on how
large the file is allowed to become, and how many versions of the file
will be saved each time the file is opened.

.Pp
The
.Ic size
option for files is simply a hard ceiling on
log growth.  If the file ever exceeds the size, then
.Nm named
will just not write anything more to it until the file is reopened;
exceeding the size does not automatically trigger a reopen.  The
default behavior is to not limit the size of the file.

.Pp
If you use the
.Ic version
logfile option, then
.Nm named
will retain that many backup versions of the file
by renaming them when opening.  For example, if you choose to keep 3
old versions of the file lamers.log then just before it is opened
lamers.log.1 is renamed to lames.log.2, lamers.log.0 is renamed to
lamers.log.1, and lamers.log is renamed to lamers.log.0.  No rolled
versions are kept by default; any existing log file is simply appended.
The
.Li unlimited
keyword is synonymous with
.Li 99
in current BIND releases.  Example usage of size and versions options:

.Bd -literal
    channel an_example_level {
        file "lamers.log" versions 3 size 20m;
        print-time yes;
        print-category yes;
    };
.Ed

.Pp
The argument for the
.Ic syslog
clause is a syslog facility as described in the
.Xr syslog 3
manual page.  How
.Nm syslogd
will handle messages sent to this facility is described in the
.Xr syslog.conf 5
manual page.  If you have a system which uses a very old version of
syslog that only uses two arguments to the
.Fn openlog()
function, then this clause is silently ignored.

.Pp
The
.Ic severity
clause works like syslog's ``priorities'', except that they can also be
used if you are writing straight to a file rather than using
syslog.  Messages  which are not at least of the severity level given
will not be selected for the channel; messages of higher severity
levels will be accepted.

.Pp
If you are using syslog, then the
.Pa syslog.conf
priorities will also determine what eventually passes through.
For example, defining a channel facility and severity as
.Li daemon
and
.Li debug
but only logging
.Li daemon.warning
via
.Pa syslog.conf
will cause messages of severity
.Li info
and
.Li notice
to be dropped.  If the situation were reversed, with
.Nm named
writing messages of only
.Li warning
or higher, then
.Nm syslogd
would print all messages it received from the channel.

.Pp
The server can supply extensive debugging information when it is in
debugging mode.  If the server's global debug level is greater than
zero, then debugging mode will be active.  The global debug level is
set either by starting the
.Nm named
server with the
.Fl d
flag followed by a positive integer, or by sending the running server the
.Dv SIGUSR1
signal (for example, by using
.Ic ndc trace ) .
The global debug level can be set to
zero, and debugging mode turned off, by sending the server the
.Dv SIGUSR2
signal (as with
.Ic ndc notrace ) .
All debugging messages in the server have a
debug level, and higher debug levels give more more detailed output.
Channels that specify a specific debug severity, e.g.

.Bd -literal
    channel specific_debug_level {
        file \&"foo\&";
        severity debug 3;
    };
.Ed

will get debugging output of level 3 or less any time the
server is in debugging mode, regardless of the global debugging level.
Channels with
.Li dynamic
severity use the server's global level to determine what messages to
print.

.Pp
If
.Ic print-time
has been turned on, then the date and time will be logged.
.Ic  print-time
may be specified for a syslog channel, but is usually pointless since
syslog also prints the date and time.
If
.Ic print-category
is requested, then the category of the message will be logged as well.
Finally, if
.Ic print-severity
is on, then the severity level of the message will be logged.  The
.Ic print-
options may be used
in any combination, and will always be printed in the following order:
time, category, severity.  Here is an example where all three
.Ic print-
options are on:

.Bd -literal
    28-Apr-1997 15:05:32.863 default: notice: Ready to answer queries.
.Ed

.Pp
There are four predefined channels that are used for
.Nm named 's
default logging as follows.  How they are used
used is described in the next section,
.Sx The category phrase.

.Bd -literal
    channel default_syslog {
        syslog daemon;       # send to syslog's daemon facility
        severity info;       # only send priority info and higher
    };

    channel default_debug {
        file \&"named.run\&";    # write to named.run in the working directory
                             # Note: stderr is used instead of \&"named.run\&"
                             # if the server is started with the -f option.
        severity dynamic;    # log at the server's current debug level
    };

    channel default_stderr { # writes to stderr
        file \&"<stderr>\&";     # this is illustrative only; there's currently
                             # no way of specifying an internal file
                             # descriptor in the configuration language.
        severity info;       # only send priority info and higher
    };

    channel null {
        null;                # toss anything sent to this channel
    };
.Ed

Once a channel is defined, it cannot be redefined.  Thus you cannot
alter the built-in channels directly, but you can modify the default
logging by pointing categories at channels you have defined.

.Ss The category phrase

There are many categories, so you can send the logs you want to see
wherever you want, without seeing logs you don't want.  If you don't
specify a list of channels for a category, then log messages in that
category will be sent to the
.Li default
category instead.
If you don't specify a default category, the following ``default
default'' is used:

.Bd -literal
    category default { default_syslog; default_debug; };
.Ed

As an example, let's say you want to log security events to a file,
but you also want keep the default logging behavior.  You'd specify
the following:

.Bd -literal
    channel my_security_channel {
        file \&"my_security_file\&";
        severity info;
    };
    category security { my_security_channel; 
                        default_syslog; default_debug; };
.Ed

To discard all messages in a category, specify the
.Li null
channel:

.Bd -literal
    category lame-servers { null; };
    category cname { null; };
.Ed

The following categories are available:

.Bl -tag -width 1
.It Ic default
The catch-all.  Many things still aren't classified into categories,
and they all end up here.  Also, if you don't specify any channels for
a category, the default category is used instead.  If you do not
define the default category, the following definition is used:
.Dl category default { default_syslog; default_debug; };

.It Ic config
High-level configuration file processing.

.It Ic parser
Low-level configuration file processing.

.It Ic queries
A short log message is generated for every query the server receives.

.It Ic lame-servers
Messages like ``Lame server on ...''

.It Ic statistics
Statistics.

.It Ic panic
If the server has to shut itself down due to an internal problem, it
will log the problem in this category as well as in the problem's native
category.  If you do not define the panic category, the following definition
is used:
.Dl category panic { default_syslog; default_stderr; };

.It Ic update
Dynamic updates.

.It Ic ncache
Negative caching.

.It Ic xfer-in
Zone transfers the server is receiving.

.It Ic xfer-out
Zone transfers the server is sending.

.It Ic db
All database operations.

.It Ic eventlib
Debugging info from the event system.  Only one channel may be specified for
this category, and it must be a file channel.  If you do not define the
eventlib category, the following definition is used:
.Dl category eventlib { default_debug; };

.It Ic packet
Dumps of packets received and sent.  Only one channel may be specified for
this category, and it must be a file channel.  If you do not define the
packet category, the following definition is used:
.Dl category packet { default_debug; };

.It Ic notify
The NOTIFY protocol.

.It Ic cname
Messages like ``... points to a CNAME''.

.It Ic security
Approved/unapproved requests.

.It Ic os
Operating system problems.

.It Ic insist
Internal consistency check failures.

.It Ic maintenance
Periodic maintenance events.

.It Ic load
Zone loading messages.

.It Ic response-checks
Messages arising from response checking, such as
``Malformed response ...'', ``wrong ans. name ...'',
``unrelated additional info ...'', ``invalid RR type ...'',
and ``bad referral ...''.

.El

.Sh THE OPTIONS STATEMENT
.Ss Syntax

.Bd -literal
options {
  [ version \fIversion_string\fR; ]
  [ directory \fIpath_name\fR; ]
  [ named-xfer \fIpath_name\fR; ]
  [ dump-file \fIpath_name\fR; ]
  [ memstatistics-file \fIpath_name\fR; ]
  [ pid-file \fIpath_name\fR; ]
  [ statistics-file \fIpath_name\fR; ]
  [ auth-nxdomain \fIyes_or_no\fR; ]
  [ deallocate-on-exit \fIyes_or_no\fR; ]
  [ dialup \fIyes_or_no\fR; ]
  [ fake-iquery \fIyes_or_no\fR; ]
  [ fetch-glue \fIyes_or_no\fR; ]
  [ has-old-clients \fIyes_or_no\fR; ]
  [ host-statistics \fIyes_or_no\fR; ]
  [ multiple-cnames \fIyes_or_no\fR; ]
  [ notify \fIyes_or_no\fR; ]
  [ recursion \fIyes_or_no\fR; ]
  [ rfc2308-type1 \fIyes_or_no\fR; ]
  [ use-id-pool \fIyes_or_no\fR; ]
  [ treat-cr-as-space \fIyes_or_no\fR; ]
  [ also-notify \fIyes_or_no\fR; ]
  [ forward ( only | first ); ]
  [ forwarders { [ \fIin_addr\fR ; [ \fIin_addr\fR ; ... ] ] }; ]
  [ check-names ( master | slave | response ) ( warn | fail | ignore); ]
  [ allow-query { \fIaddress_match_list\fR }; ]
  [ allow-recursion { \fIaddress_match_list\fR }; ]
  [ allow-transfer { \fIaddress_match_list\fR }; ]
  [ blackhole { \fIaddress_match_list\fR }; ]
  [ listen-on [ port \fIip_port\fR ] { \fIaddress_match_list\fR }; ]
  [ query-source [ address ( \fIip_addr\fR | * ) ]
                 [ port ( \fIip_port\fR | * ) ] ; ]
  [ lame-ttl \fInumber\fR; ]
  [ max-transfer-time-in \fInumber\fR; ]
  [ max-ncache-ttl \fInumber\fR; ]
  [ min-roots \fInumber\fR; ]
  [ serial-queries \fInumber\fR; ]
  [ transfer-format ( one-answer | many-answers ); ]
  [ transfers-in  \fInumber\fR; ]
  [ transfers-out \fInumber\fR; ]
  [ transfers-per-ns \fInumber\fR; ]
  [ transfer-source \fIip_addr\fR; ]
  [ maintain-ixfr-base \fIyes_or_no\fR; ]
  [ max-ixfr-log-size \fInumber\fR; ]
  [ coresize \fIsize_spec\fR ; ]
  [ datasize \fIsize_spec\fR ; ]
  [ files \fIsize_spec\fR ; ]
  [ stacksize \fIsize_spec\fR ; ]
  [ cleaning-interval \fInumber\fR; ]
  [ heartbeat-interval \fInumber\fR; ]
  [ interface-interval \fInumber\fR; ]
  [ statistics-interval \fInumber\fR; ]
  [ topology { \fIaddress_match_list\fR }; ]
  [ sortlist { \fIaddress_match_list|fR }; ]
  [ rrset-order { \fIorder_spec\fR ; [ \fIorder_spec\fR ; ... [ [ };
};
.Ed

.Ss Definition and Usage

The options statement sets up global options to be used by
BIND. This statement may appear at only once in a
configuration file; if more than one occurrence is found, the
first occurrence determines the actual options used,
and a warning will be generated.  If there is no options statement,
an options block with each option set to its default will be used.

.Ss Pathnames

.Bl -tag -width 1

.It Ic version
The version the server should report via the ndc command or via a query of 
name 
.Pa version.bind 
in class chaos. The default is the real version number of ths server, 
but some server operators prefer the string (
.Ic surely you must be joking 
).

.It Ic directory
The working directory of the server.  Any non-absolute
pathnames in the configuration file will be taken as relative to this
directory.  The default location for most server output files
(e.g.
.Pa named.run )
is this directory.  If a directory is not
specified, the working directory defaults to
.Pa . ,
the directory from which the
server was started.  The directory specified should be an absolute path.

.It Ic named-xfer
The pathname to the named-xfer program that the server uses for
inbound zone transfers.  If not specified, the default is
system dependent (e.g.
.Pa /usr/sbin/named-xfer 
).

.It Ic dump-file
The pathname of the file the server dumps the database to when it
receives
.Dv SIGINT
signal (as sent by
.Ic ndc dumpdb 
). If not specified, the default is
.Pa named_dump.db .

.It Ic memstatistics-file
The pathname of the file the server writes memory usage statistics to
on exit, if
.Ic deallocate-on-exit
is
.Li yes .
If not specified, the default is
.Pa named.memstats .

.It Ic pid-file
The pathname of the file the server writes its process ID in.  If not
specified, the default is operating system dependent, but is usually
.Pa /var/run/named.pid
or
.Pa /etc/named.pid .
The pid-file is used by programs like
.Nm ndc
that want to send signals to the running nameserver.

.It Ic statistics-file
The pathname of the file the server appends statistics to when it
receives
.Dv SIGILL
signal (from
.Ic ndc stats ) .
If not specified, the default is
.Pa named.stats .
.El

.Ss Boolean Options

.Bl -tag -width 1
.It Ic auth-nxdomain
If
.Li yes ,
then the
.Li AA
bit is always set on
.Dv NXDOMAIN
responses, even if the server is not actually authoritative.
The default is
.Li yes .
Do not turn off
.Ic auth-nxdomain
unless you are sure you know what you are
doing, as some older software won't like it.

.It Ic deallocate-on-exit
If
.Li yes ,
then when the server exits it will painstakingly deallocate every
object it allocated, and then write a memory usage report to the
.Ic memstatistics-file .
The default is
.Li no ,
because it is faster to let the operating system clean up.
.Ic deallocate-on-exit
is handy for detecting memory leaks.

.It Ic dialup
If
.Li yes ,
then the server treats all zones as if they are doing zone transfers
across a dial on demand dialup link, which can be brought up by
traffic originating from this server.  This has different effects
according to zone type and concentrates the zone maintenance so that
it all happens in a short interval, once every
.Ic heartbeat-interval
and hopefully during the one call.
It also suppresses some of the normal zone maintenance traffic.
The default is
.Li no .
The
.Ic dialup
option may also be specified in the
.Ic zone
statement, in which
case it overrides the
.Ic options dialup
statement.

.Pp
If the zone is a
.Ic master
then the server will send out
.Dv NOTIFY
request to all the slaves.
This will trigger the zone up to date checking in the slave (providing
it supports
.Dv NOTIFY )
allowing  the slave
to verify the zone while the call us up.

.Pp
If the zone is a
.Ic slave
or
.Ic stub
then the server will suppress the zone regular zone up to date queries
and only perform the when the
.Ic heartbeat-interval
expires.

.It Ic fake-iquery
If
.Li yes ,
the server will simulate the obsolete DNS query type
.Dv IQUERY .
The default is
.Li no .

.It Ic fetch-glue
If
.Li yes
(the default), the server will fetch ``glue'' resource
records it doesn't have when constructing the additional data section of
a response.
.Ic fetch-glue no
can be used in conjunction with
.Ic recursion no
to prevent the server's cache from growing or
becoming corrupted (at the cost of requiring more work from the client).

.It Ic has-old-clients
Setting the option to
.Li yes ,
is equivalent to setting the following three options: 
.Ic auth-nxdomain yes ;,
.Ic maintain-ixfr-base yes ;,
and 
.Ic rfc2308-type1 no ;
. The use of 
.Ic has-old-clients
with
.Ic auth-nxdomain , 
.Ic maintain-ixfr-base ,
and 
.Ic rfc2308-type1 
is order dependant. 

.It Ic host-statistics
If
.Li yes ,
then statistics are kept for every host that the the nameserver
interacts with.  The default is
.Li no .
.Em Note:
turning on
.Ic host-statistics
can consume huge amounts of memory.

.It Ic maintain-ixfr-base
If
.Li yes ,
statistics are kept for every host that the nameserver interacts with.  The default is
.Li no .
.Em Note:
turning on 
.Li host-statistics
can consume huge amounts of memory.

.It Ic multiple-cnames
If
.Li yes ,
then multiple CNAME resource records will be
allowed for a domain name.  The default is
.Li no .
Allowing multiple CNAME records is against standards and is not recommended.
Multiple CNAME support is available because previous versions of BIND
allowed multiple CNAME records, and these records have been used for load
balancing by a number of sites.

.It Ic notify
If
.Li yes
(the default), DNS NOTIFY messages are sent when a
zone the server is authoritative for changes.  The use of NOTIFY
speeds convergence between the master and its slaves.  Slave servers
that receive a NOTIFY message and understand it will contact the
master server for the zone and see if they need to do a zone transfer, and
if they do, they will initiate it immediately.  The
.Ic notify
option may also be specified in the
.Ic zone
statement, in which case it overrides the
.Ic options notify
statement.

.It Ic recursion
If
.Li yes ,
and a DNS query requests recursion, then the
server will attempt to do all the work required to answer the query.
If recursion is not on, the server will return a referral to the
client if it doesn't know the answer.  The default is
.Li yes .
See also
.Ic fetch-glue
above.

.It Ic rfc2308-type1
If
.Li yes, 
the server will send NS records along with the SOA record for negative 
answers.  You need to set this to no if you have an old BIND server using 
you as a forwarder that does not understand negative answers which contain 
both SOA and NS records or you have an old version of sendmail.  The correct 
fix is to upgrade the broken server or sendmail.  The default is 
.Li no .

.It Ic use-id-pool
If
.Li yes,
the server will keep track of its own outstanding query ID's to avoid duplication
and increase randomness.  This will result in 128KB more memory being consumed 
by the server.  The default is
.Li no .

.It Ic treat-cr-as-space
If 
.Li yes, 
the server will treat CR characters the same way it treats a space
or tab.  This may be necessary when loading zone files on a UNIX system
that were generated on an NT or DOS machine.  The default is 
.Li no .


.El

.Ss Also-Notify

.Ic also-notify

Defines a global list of IP addresses that also get sent NOTIFY messages 
whenever a fresh copy of the zone is loaded. This helps to ensure that copies of 
the zones will quickly converge on ``stealth'' servers.  If an 
.Ic also-notify 
list is given in a 
.Ic zone 
statement, it will override the 
.Ic options also-notify 
statement. When a 
.Ic zone notify 
statement is set to 
.Ic no ,
the IP addresses in 
the global 
.Ic also-notify
list will not get sent NOTIFY messages for that zone. 
The default is the empty list (no global notification list). 

.Ss Forwarding

.Pp
The forwarding facility can be used to create a large site-wide
cache on a few servers, reducing traffic over links to external
nameservers.  It can also be used to allow queries by servers that do
not have direct access to the Internet, but wish to look up exterior
names anyway.  Forwarding occurs only on those queries for which the
server is not authoritative and does not have the answer in its cache.

.Bl -tag -width 1
.It Ic forward
This option is only meaningful if the
.Ic forwarders
list is
not empty.  A value of
.Li first ,
the default, causes the
server to query the forwarders first, and if that doesn't answer the
question the server will then look for the answer itself.  If
.Li only
is specified, the server will only query the forwarders.

.It Ic forwarders
Specifies the IP addresses to be used for forwarding.  The default is the
empty list (no forwarding).
.El

.Pp
Forwarding can also be configured on a per-zone basis, allowing for
the global forwarding options to be overridden in a variety of ways.
You can set particular zones to use different forwarders, or have
different
.Ic forward only/first
behavior, or to not forward
at all.  See
.Sx THE ZONE STATEMENT
section for more information.

.Pp
Future versions of BIND 8 will provide a more powerful forwarding
system.  The syntax described above will continue to be supported.

.Ss Name Checking

The server can check domain names based upon their expected client contexts.
For example, a domain name used as a hostname can be checked for compliance
with the RFCs defining valid hostnames.

.Pp
Three checking methods are available:

.Bl -tag -width 1
.It Ic ignore
No checking is done.

.It Ic warn
Names are checked against their expected client contexts.  Invalid names are
logged, but processing continues normally.

.It Ic fail
Names are checked against their expected client contexts.  Invalid names are
logged, and the offending data is rejected.
.El

.Pp
The server can check names three areas: master zone files, slave
zone files, and in responses to queries the server has initiated.  If
.Ic check-names response fail
has been specified, and
answering the client's question would require sending an invalid name
to the client, the server will send a
.Dv REFUSED
response code to the client.

.Pp
The defaults are:

.Bd -literal
    check-names master fail;
    check-names slave warn;
    check-names response ignore;
.Ed

.Pp
.Ic check-names
may also be specified in the
.Ic zone
statement, in which case it overrides the
.Ic options check-names
statement.  When used in a
.Ic zone
statement, the area is not specified (because it can be deduced from
the zone type).

.Ss Access Control

.Pp
Access to the server can be restricted based on the IP address of the
requesting system or via shared secret keys.  See
.Sx ADDRESS MATCH LISTS
for details on how to specify access criteria.

.Bl -tag -width 1
.It Ic allow-query
Specifies which hosts are allowed to ask ordinary questions.
.Ic allow-query
may also be specified in the
.Ic zone
statement, in which case it overrides the
.Ic options allow-query
statement.  If not specified, the default is

.Bl -tag -width 1 
.It Ic allow-recursion
Specifies which hosts are allowed to ask recursive questions.
.Ic allow-recursion
may also be specified in the
.Ic zone
statement, in which case it overrides the
.Ic options allow-recursion 
statement.  If not specified, the default is to allow recursive queries 
from all hosts.

.It Ic allow-transfer
Specifies which hosts are allowed to receive zone transfers from the
server.
.Ic allow-transfer
may also be specified in the
.Ic zone
statement, in which case it overrides the
.Ic options allow-transfer
statement.  If not specified, the default
is to allow transfers from all hosts.

.It Ic blackhole
Specifies a list of addresses that the server will not accept queries from
or use to resolve a query.  Queries from these addresses will not be
responded to.
.El
.El

.Ss Interfaces

.Pp
The interfaces and ports that the server will answer queries from may
be specified using the
.Ic listen-on
option.
.Ic listen-on
takes an optional port, and an address match list.
The server will listen on all interfaces allowed by the address match
list.  If a port is not specified, port 53 will be used.

.Pp
Multiple
.Ic listen-on
statements are allowed.  For example,

.Bd -literal
    listen-on { 5.6.7.8; };
    listen-on port 1234 { !1.2.3.4; 1.2/16; };
.Ed

will enable the nameserver on port 53 for the IP address 5.6.7.8, and
on port 1234 of an address on the machine in net 1.2 that is not
1.2.3.4.

.Pp
If no
.Ic listen-on
is specified, the server will listen on port
53 on all interfaces.

.Ss Query Address

.Pp
If the server doesn't know the answer to a question, it will query
other nameservers.
.Ic query-source
specifies the address and port used for such queries.  If
.Ic address
is
.Li *
or is omitted, a wildcard IP address
(
.Dv INADDR_ANY )
will be used.  If
.Va port
is
.Li *
or is omitted, a random unprivileged port will be used.
The default is
.Dl query-source address * port *;

.Pp
Note:
.Ic query-source
currently applies only to UDP queries;
TCP queries always use a wildcard IP address and a random unprivileged
port.

.Ss Zone Transfers

.Bl -tag -width 1
.It Ic max-transfer-time-in
Inbound zone transfers (
.Nm named-xfer
processes) running
longer than this many minutes will be terminated.
The default is 120 minutes (2 hours).

.It Ic transfer-format
The server supports two zone transfer methods.
.Li one-answer
uses one DNS message per resource record
transferred.
.Li many-answers
packs as many resource records
as possible into a message.
.Li many-answers
is more efficient, but is only known to be understood by BIND 8.1 and
patched versions of BIND 4.9.5.  The default is
.Li one-answer .
.Ic transfer-format
may be overridden on a per-server basis by using the
.Ic server
statement.

.It Ic transfers-in
The maximum number of inbound zone transfers that can be running
concurrently.  The default value is 10.  Increasing
.Ic transfers-in
may speed up the convergence of slave zones,
but it also may increase the load on the local system.

.It Ic transfers-out
This option will be used in the future to limit the number of
concurrent outbound zone transfers.  It is checked for syntax, but is
otherwise ignored.

.It Ic transfers-per-ns
The maximum number of inbound zone transfers (
.Nm named-xfer
processes) that can be concurrently transferring from a given remote
nameserver.  The default value is 2.  Increasing
.Ic transfers-per-ns
may speed up the convergence of slave zones, but it also may increase
the load on the remote nameserver.
.Ic transfers-per-ns
may be overridden on a per-server basis by using the
.Ic transfers
phrase of the
.Ic server
statement.

.It Ic transfer-source
.Nm transfer-source
determines which local address will be bound to the TCP connection used to fetch all zones
transferred inbound by the server.  If not set, it defaults to a system controlled value which will usually be the address of the interface ``closest to`` the remote end.  This
address must appear in the remote end's 
.Nm allow-transfer
option for the zones being transferred, if one is specified.  This statement sets the
.Nm transfer-source
for all zones, but can be overriden on a per-zone basis by includinga 
.Nm transfer-source
statement within the zone block in the configuration file.
.El

.Ss Resource Limits

.Pp
The server's usage of many system resources can be limited.  Some
operating systems don't support some of the limits.  On such systems,
a warning will be issued if the unsupported limit is used.  Some
operating systems don't support limiting resources, and on these systems
a
.D1 cannot set resource limits on this system
message will
be logged.

.Pp
Scaled values are allowed when specifying resource limits.  For
example,
.Li 1G
can be used instead of
.Li 1073741824
to specify a limit of one gigabyte.
.Li unlimited
requests unlimited use, or the maximum
available amount.
.Li default
uses the limit that was in
force when the server was started.
See the definition of
.Va size_spec
in the
.Sx DOCUMENTATION DEFINITIONS
section for more details.

.Bl -tag -width 1
.It Ic coresize
The maximum size of a core dump.  The default value is
.Li default .

.It Ic datasize
The maximum amount of data memory the server may use.  The default
value is
.Li default .

.It Ic files
The maximum number of files the server may have open concurrently.
The default value is
.Li unlimited .
Note that on some operating systems the server cannot set an unlimited
value and cannot determine the maximum number of open files the kernel
can support.  On such systems, choosing
.Li unlimited
will cause the server to use
the larger of the
.Va rlim_max
from
.Fn getrlimit RLIMIT_NOFILE
and the value returned by
.Fn sysconf _SC_OPEN_MAX .
If the
actual kernel limit is larger than this value, use
.Ic limit files
to specify the limit explicitly.

.It Ic max-ixfr-log-size
The
.Li max-ixfr-log-size 
will be used in a future release of the server to limit the size of the transaction
log kept for Incremental Zone Transfer.

.It Ic stacksize
The maximum amount of stack memory the server may use.  The default value is
.Li default .
.El

.Ss Periodic Task Intervals

.Bl -tag -width 1
.It Ic cleaning-interval
The server will remove expired resource records from the cache every

.Ic cleaning-interval
minutes.  The default is 60 minutes.  If set
to 0, no periodic cleaning will occur.

.It Ic heartbeat-interval
The server will perform zone maintenance tasks for all zones marked
.Ic dialup yes
whenever this interval expires.
The default is 60 minutes. Reasonable values are up to 1 day (1440 minutes).
If set to 0, no zone maintenance for these zones will occur.

.It Ic interface-interval
The server will scan the network interface list every
.Ic interface-interval
minutes.  The default is 60 minutes.
If set to 0, interface scanning will only occur when the configuration
file is loaded.  After the scan, listeners will be started on any new
interfaces (provided they are allowed by the
.Ic listen-on
configuration).  Listeners on interfaces that have gone away will be
cleaned up.

.It Ic statistics-interval
Nameserver statistics will be logged every
.Ic statistics-interval
minutes.  The default is 60.  If set to 0, no statistics will be logged.
.El

.Ss Topology

.Pp
All other things being equal, when the server chooses a nameserver
to query from a list of nameservers, it prefers the one that is
topologically closest to itself.  The
.Ic topology
statement takes an address match list and interprets it in a special way.
Each top-level list element is assigned a distance.
Non-negated elements get a distance based on
their position in the list, where the closer the match is to the start
of the list, the shorter the distance is between it and the server.  A
negated match will be assigned the maximum distance from the server.
If there is no match, the address will get a distance which is further
than any non-negated list element, and closer than any negated
element.  For example,

.Bd -literal
    topology {
        10/8;
        !1.2.3/24;
        { 1.2/16; 3/8; };
    };
.Ed

will prefer servers on network 10 the most, followed by hosts on
network 1.2.0.0 (netmask 255.255.0.0) and network 3, with the exception
of hosts on network 1.2.3 (netmask 255.255.255.0), which is preferred least
of all.

.Pp
The default topology is
.Dl topology { localhost; localnets; };

.Ss Resource Record sorting
  
.Pp 
When returning multiple RRs, the nameserver will normally return them in
.Ic Round Robin ,
i.e. after each request, the first RR is put to the end of the list.
As the order of RRs is not defined, this should not cause any problems.

The client resolver code should re-arrange the RRs as appropriate, i.e. using
any addresses on the local net in preference to other addresses. However, not all
resolvers can do this, or are not correctly configured. 

When a client is using a local server, the sorting can be performed in the server,
based on the client's address. This only requires configuring the nameservers,
not all the clients. 

The 
.Ic sortlist
statement takes an address match list and interprets it even more
specially than the 
.Ictopology 
statement does. 

Each top level statement in the sortlist must itself be an explicit address match
list with one or two elements. The first element (which may be an IP address,
an IP prefix, an ACL name or nested address match list) of each top level list is
checked against the source address of the query until a match is found. 

Once the source address of the query has been matched, if the top level
statement contains only one element, the actual primitive element that
matched the source address is used to select the address in the response to
move to the beginning of the response. If the statement is a list of two elements,
the second element is treated like the address match list in a topology
statement. Each top level element is assigned a distance and the address in the
response with the minimum distance is moved to the beginning of the response.

In the following example, any queries received from any of the addresses of the
host itself will get responses preferring addresses on any of the locally
connected networks. Next most preferred are addresses on the 192.168.1/24
network, and after that either the 192.168.2/24 or 192.168.3/24 network with no
preference shown between these two networks. Queries received from a host on
the 192.168.1/24 network will prefer other addresses on that network to the
192.168.2/24 and 192.168.3/24 networks. Queries received from a host on the
192.168.4/24 or the 192.168.5/24 network will only prefer other addresses on
their directly connected networks. 

.Bd -literal
sortlist {
           { localhost;         // IF   the local host
             { localnets;       // THEN first fit on the
               192.168.1/24;    //      following nets
               { 192,168.2/24; 192.168.3/24; }; }; };
           { 192.168.1/24;      // IF   on class C 192.168.1
             { 192.168.1/24;    // THEN use .1, or .2 or .3
               { 192.168.2/24; 192.168.3/24; }; }; };
           { 192.168.2/24;      // IF   on class C 192.168.2
             { 192.168.2/24;    // THEN use .2, or .1 or .3
               { 192.168.1/24; 192.168.3/24; }; }; };
           { 192.168.3/24;      // IF   on class C 192.168.3
             { 192.168.3/24;    // THEN use .3, or .1 or .2
               { 192.168.1/24; 192.168.2/24; }; }; };
           { { 192.168.4/24; 192.168.5/24; }; // if .4 or .5, prefer that net
           };
};
.Ed

The following example will give reasonable behaviour for the local host and
hosts on directly connected networks. It is similar to the behavior of the
address sort in BIND 4.9.x. Responses sent to queries from the local host will
favor any of the directly connected networks. Responses sent to queries from
any other hosts on a directly connected network will prefer addresses on that
same network. Responses to other queries will not be sorted.

.Bd -literal
sortlist {
            { localhost; localnets; };
            { localnets; };
};
.Ed

.Ss RRset Ordering

.Pp
When multiple records are returned in an answer it may be useful to configure
the order the records are placed into the response. For example the records for
a zone might be configured to always be returned in the order they are defined
in the zone file. Or perhaps a random shuffle of the records as they are
returned is wanted. The rrset-order statement permits configuration of the
ordering made of the records in a multiple record response. The default, if no
ordering is defined, is a cyclic ordering (round robin). 

An 
.Ic order_spec
is defined as follows: 

.Bd -literal
  [ \fIclass class_name\fR ][ \fItype type_name\fR ][ \fIname\fR "FQDN" ] \fIorder\fR ordering
.Ed

If no class is specified, the default is 
.Ic ANY .
If no 
.Li Ictype 
is specified, the default is
.Ic ANY . 
If no name is specified, the default is "*". 

The legal values for 
.Ic ordering 
are: 

.Bd -literal
.Ic fixed 
     Records are returned in the order they are defined in the zone file. 
.Ic random 
     Records are returned in some random order. 
.Ic cyclic 
     Records are returned in a round-robin order. 

For example: 

    rrset-order {
        class IN type A name "rc.vix.com" order random;
        order cyclic;
    };
.Ed

will cause any responses for type A records in class IN that have "rc.vix.com" as
a suffix, to always be returned in random order. All other records are returned
in cyclic order. 

If multiple 
.Ic rrset-order
statements appear, they are not combined--the last one applies. 

If no 
.Ic rrset-order
statement is specified, a default one of: 

.Bd -literal
    rrset-order { class ANY type ANY name "*" order cyclic ; };
.Ed

is used. 

.Ss Tuning

.Bl -tag -width 1
.It Ic lame-ttl
Sets the number of seconds to cache a lame server indication.  0 disables
caching.  Default is 600 (10 minutes).  Maximum value is 1800 (30 minutes)
.It Ic max-ncache-ttl
To reduce network traffic and increase performance the server store negative
answers.
.Ic max-ncache-ttl
is used to set a maximum retention time
for these answers in the server is seconds.  The default
.Ic max-ncache-ttl
is 10800 seconds (3 hours).
.Ic max-ncache-ttl
cannot exceed the maximum retention time for ordinary (positive)
answers (7 days) and will be silently truncated to 7 days if set to a
value which is greater that 7 days.
.It Ic min-roots
The minimum number of root servers that is required for a request for the root
servers to be accepted.  Default is 2.
.El

.Sh THE ZONE STATEMENT
.Ss Syntax

.Bd -literal
zone \fIdomain_name\fR [ ( in | hs | hesiod | chaos ) ] {
  type master;
  file \fIpath_name\fR;
  [ check-names ( warn | fail | ignore ); ]
  [ allow-update { \fIaddress_match_list\fR }; ]
  [ allow-query { \fIaddress_match_list\fR }; ]
  [ allow-transfer { \fIaddress_match_list\fR }; ]
  [ dialup \fIyes_or_no\fR; ]
  [ notify \fIyes_or_no\fR; ]
  [ also-notify { \fIip_addr\fR; [ \fIip_addr\fR; ... ] };
  [ pubkey \fInumber\fR \fInumber\fR \fInumber\fR \fIstring\fR; ]
};

zone \fIdomain_name\fR [ ( in | hs | hesiod | chaos ) ] {
  type ( slave | stub );
  [ file \fIpath_name\fR; ]
  masters [ port \fIip_port\fR ] { \fIip_addr\fR; [ \fIip_addr\fR; ... ] };
  [ check-names ( warn | fail | ignore ); ]
  [ allow-update { \fIaddress_match_list\fR }; ]
  [ allow-query { \fIaddress_match_list\fR }; ]
  [ allow-transfer { \fIaddress_match_list\fR }; ]
  [ transfer-source \fIip_addr\fR; ]
  [ max-transfer-time-in \fInumber\fR; ]
  [ notify \fIyes_or_no\fR; ]
  [ also-notify { \fIip_addr\fR; [ \fIip_addr\fR; ... ] };
  [ pubkey \fInumber\fR \fInumber\fR \fInumber\fR \fIstring\fR; ]
};

zone \fIdomain_name\fR [ ( in | hs | hesiod | chaos ) ] {
  type forward;
  [ forward ( only | first ); ]
  [ forwarders { [ \fIip_addr\fR ; [ \fIip_addr\fR ; ... ] ] }; ]
  [ check-names ( warn | fail | ignore ); ]
};

zone \&".\&" [ ( in | hs | hesiod | chaos ) ] {
  type hint;
  file \fIpath_name\fR;
  [ check-names ( warn | fail | ignore ); ]
};
.Ed

.Ss Definition and Usage

The
.Ic zone
statement is used to define how information about particular DNS zones
is managed by the server.  There are five different zone types.

.Bl -tag -width 1
.It Ic master
The server has a master copy of the data for the zone and will be able
to provide authoritative answers for it.

.It Ic slave
A
.Ic slave
zone is a replica of a master zone.  The
.Ic masters
list specifies one or more IP addresses that the slave contacts to
update its copy of the zone.  If a
.Ic port
is specified then checks to see if the zone is current and zone transfers
will be done to the port given. If
.Ic file
is specified, then the replica will be written to the named file.
Use of the
.Ic file
clause is highly recommended, since it often speeds server startup
and eliminates a needless waste of bandwidth.

.It Ic stub
A
.Ic stub
zone is like a slave zone, except that it replicates
only the NS records of a master zone instead of the entire zone.

.It Ic forward
A
.Ic forward
zone is used to direct all queries in it to other servers, as described in
.Sx THE OPTIONS STATEMENT
section.  The specification of options in such a zone will override
any global options declared in the
.Ic options
statement.

.Pp
If either no
.Ic forwarders
clause is present in the zone or an empty list for
.Ic forwarders
is given, then no forwarding will be done for the zone, cancelling the
effects of any
.Ic forwarders
in the
.Ic options
statement.
Thus if you want to use this type of zone to change only the behavior of
the global
.Ic forward
option, and not the servers used, then you also need to respecify the
global forwarders.

.It Ic hint
The initial set of root nameservers is specified using a
.Ic hint
zone.  When the server starts up, it uses the root hints
to find a root nameserver and get the most recent list of root nameservers.
.El

.Pp
Note: previous releases of BIND used the term
.Ic primary
for a master zone,
.Ic secondary
for a slave zone, and
.Ic cache
for a hint zone.

.Ss Classes

The zone's name may optionally be followed by a class.  If a class is not
specified, class
.Ic in
(for "internet"), is assumed.  This is correct for the vast majority
of cases.

.Pp
The
.Ic hesiod
class is for an information service from MIT's Project Athena.  It is
used to share information about various systems databases, such as
users, groups, printers and so on.  More information can be found at
ftp://athena-dist.mit.edu/pub/ATHENA/usenix/athena_changes.PS.
The keyword
.Ic hs
is a synonym for
.Ic hesiod .

.Pp
Another MIT development was CHAOSnet, a LAN protocol created in the
mid-1970s.  It is still sometimes seen on LISP stations and other
hardware in the AI community, and zone data for it can be specified
with the
.Ic chaos
class.

.Ss Options

.Bl -tag -width 1
.It Ic check-names
See the subsection on
.Sx Name Checking
in
.Sx THE OPTIONS STATEMENT .

.It Ic allow-query
See the description of
.Ic allow-query
in the
.Sx Access Control
subsection of
.Sx THE OPTIONS STATEMENT .

.It Ic allow-update
Specifies which hosts are allowed to submit Dynamic DNS updates to the
server.  The default is to deny updates from all hosts.

.It Ic allow-transfer
See the description of
.Ic allow-transfer
in the
.Sx Access Control
subsection of
.Sx THE OPTIONS STATEMENT .

.It Ic transfer-source
.Ic transfer-source
determines which local address will be bound to the TCP connection
used to fetch this zone.  If not set, it defaults to a system
controlled value which will usually be the address of the interface
``closest to'' the remote end.  This address must appear in the remote end's
.Ic allow-transfer
option for this zone if one is specified.

.It Ic max-transfer-time-in
See the description of
.Ic max-transfer-time-in
in the
.Sx Zone Transfers
subsection of
.Sx THE OPTIONS STATEMENT .

.It Ic dialup
See the description of
.Ic dialup
in the
.Sx Boolean Options
subsection of
.Sx THE OPTIONS STATEMENT .

.It Ic notify
See the description of
.Sx notify
in the
.Sx Boolean Options
subsection of the
.Sx THE OPTIONS STATEMENT .

.It Ic also-notify
.Ic also-notify
is only meaningful if
.Ic notify
is active for this zone.
The set of machines that will receive a DNS NOTIFY message for this
zone is made up of all the listed nameservers for the zone (other than
the primary master) plus any IP addresses specified with
.Ic also-notify .
.Ic also-notify
is not meaningful for
.Ic stub
zones.  The default is the empty list.

.It Ic forward
.Ic forward
is only meaningful if the zone has a
.Ic forwarders
list. The
.Ic only
value causes the lookup to fail after trying the
.Ic forwarders
and getting no answer, while
.Ic first
would allow a normal lookup to be tried.

.It Ic forwarders
The
.Ic forwarders
option in a zone is used to override the list of global forwarders.
If it is not specified in a zone of type
.Ic forward ,
.Em no
forwarding is done for the zone; the global options are not used.

.It Ic pubkey
The DNSSEC flags, protocol, and algorithm are specified, as well as a base-64
encoded string representing the key.
.El

.Sh THE ACL STATEMENT
.Ss Syntax

.Bd -literal
acl \fIname\fR {
  \fIaddress_match_list\fR
};
.Ed

.Ss Definition and Usage

The
.Ic acl
statement creates a named address match list.
It gets its name from a primary use of address match lists:  Access
Control Lists (ACLs).

.Pp
Note that an address match list's name must be defined with
.Ic acl
before it can be used elsewhere; no forward
references are allowed.

.Pp
The following ACLs are built-in:

.Bl -tag -width 1
.It Ic any
Allows all hosts.
.It Ic none
Denies all hosts.
.It Ic localhost
Allows the IP addresses of all interfaces on the system.
.It Ic localnets
Allows any host on a network for which the system has an interface.
.El

.Sh THE KEY STATEMENT
.Ss Syntax

.Bd -literal
key \fIkey_id\fR {
  algorithm \fIalgorithm_id\fR;
  secret \fIsecret_string\fR;
};
.Ed

.Ss Definition and Usage

The
.Ic key
statement defines a key ID which can be used in a
.Ic server
statement to associate a method of authentication with a particular
name server that is more rigorous than simple IP address matching.
A key ID must be created with the
.Ic key
statement before it can be used in a
.Ic server
definition or an address match list.

.Pp
The
.Va algorithm_id
is a string that specifies a
security/authentication algorithm.
.Va secret_string
is the secret to be used by the algorithm,
and is treated as a base-64 encoded string.
It should go without saying, but probably can't,
that if you have
.Va secret_string 's
in your
.Pa named.conf ,
then it should not be readable by anyone but the superuser.

.Sh THE TRUSTED-KEYS STATEMENT
.Ss Syntax

.Bd -literal
trusted-keys {
  [ \fIdomain_name\fR \fIflags\fR \fIprotocol\fR \fIalgorithm\fR \fIkey\fR; ]
};
.Ed

.Ss Definition and Usage

The
.Ic trusted-keys
statement is for use with DNSSEC-style security, originally specified
in RFC 2065.  DNSSEC is meant to
provide three distinct services: key distribution, data origin
authentication, and transaction and request authentication.  A
complete description of DNSSEC and its use is beyond the scope of this
document, and readers interested in more information should start with
RFC 2065 and then continue with the Internet Drafts available at
http://www.ietf.org/ids.by.wg/dnssec.html.

.Pp
Each trusted key is associated with a domain name.  Its attributes are
the non-negative integral
.Va flags ,
.Va protocol ,
and
.Va algorithm ,
as well as a base-64 encoded string representing the
.Va key .

.Pp
Any number of trusted keys can be specified.

.Sh THE SERVER STATEMENT
.Ss Syntax

.Bd -literal
server \fIip_addr\fR {
  [ bogus \fIyes_or_no\fR; ]
  [ transfers \fInumber\fR; ]
  [ transfer-format ( one-answer | many-answers ); ]
  [ keys { \fIkey_id\fR [ \fIkey_id\fR ... ] }; ]
};
.Ed

.Ss Definition and Usage

The server statement defines the characteristics to be
associated with a remote name server.

.Pp
If you discover that a server is giving out bad data, marking it as
.Ic bogus
will prevent further queries to it.  The default value of
.Ic bogus
is
.Li no .

.Pp
The server supports two zone transfer methods.  The first,
.Ic one-answer ,
uses one DNS message per resource record transferred.
.Ic many-answers
packs as many resource records as possible into a message.
.Ic many-answers
is more efficient, but is only known to be understood by BIND 8.1 and
patched versions of BIND 4.9.5.  You can specify which method to use
for a server with the
.Ic transfer-format
option.  If
.Ic transfer-format
is not specified, the
.Ic transfer-format
specified by the
.Ic options
statement will be used.

.Pp
The
.Ic transfers
will be used in a future release of the server to limit the number of
concurrent in-bound zone transfers from the specified server.  It is
checked for syntax but is otherwise ignored.

.Pp
The
.Ic keys
clause is used to identify a 
.Va key_id
defined by the
.Ic key
statement, to be used for transaction security when talking to the
remote server.
The
.Ic key
statememnt must come before the
.Ic server
statement that references it.

.Pp
The
.Ic keys
statement is intended for future use by the
server.  It is checked for syntax but is otherwise ignored.

.Sh THE CONTROLS STATEMENT
.Ss Syntax

.Bd -literal
controls {
  [ inet \fIip_addr\fR
    port \fIip_port\fR
    allow { \fIaddress_match_list\fR; }; ]
  [ unix \fIpath_name\fR
    perm \fInumber\fR
    owner \fInumber\fR
    group \fInumber\fR; ]
};
.Ed

.Ss Definition and Usage

The
.Ic controls
statement declares control channels to be used by system
administrators to affect the operation of the local name server.
These control channels are used by the
.Nm ndc
utility to send commands
to and retrieve non-DNS results from a name server.

.Pp
A
.Ic unix
control channel is a FIFO in the file system, and access to it is
controlled by normal file system permissions.  It is created by
.Nm named
with the specified file mode bits (see
.Xr chmod 1 ) ,
user and group owner.  Note that, unlike
.Nm chmod ,
the mode bits specified for
.Ic perm
will normally have a leading
.Li 0
so the number is interpreted as octal.  Also note that the user and
group ownership specified as
.Ic owner
and
.Ic group
must be given as numbers, not names.
It is recommended that the
permissions be restricted to administrative personnel only, or else any
user on the system might be able to manage the local name server.

.Pp
An
.Ic inet
control channel is a TCP/IP socket accessible to the Internet, created
at the specified
.Va ip_port
on the specified
.Va ip_addr .
Modern
.Nm telnet
clients are capable of speaking directly to these
sockets, and the control protocol is ARPAnet-style text.
It is recommended that 127.0.0.1 be the only
.Va ip_addr
used, and this only if you trust all non-privileged users on the local
host to manage your name server.

.Sh THE INCLUDE STATEMENT
.Ss Syntax

.Bd -literal
include \fIpath_name\fR;
.Ed

.Ss Definition and Usage

The
.Ic include
statement inserts the specified file at the point that the
.Ic include
statement is encountered.  It cannot be used within another statement,
though, so a line such as
.Dl acl internal_hosts { include "internal_hosts.acl"; };
is not allowed.

.Pp
Use
.Ic include
to break the configuration up into easily-managed chunks.
For example:

.Bd -literal
include "/etc/security/keys.bind";
include "/etc/acls.bind";
.Ed

could be used at the top of a BIND configuration file in order to
include any ACL or key information.

.Pp
Be careful not to type
``#include'', like you would in a C program, because
``#'' is used to start a comment.

.Sh EXAMPLES

The simplest configuration file that is still realistically useful is
one which simply defines a hint zone that has a full path to the root
servers file.
.Bd -literal
zone \&".\&" in {
        type hint;
        file \&"/var/named/root.cache\&";
};
.Ed

Here's a more typical real-world example.

.Bd -literal
/*
 * A simple BIND 8 configuration
 */

logging {
	category lame-servers { null; };
	category cname { null; };
};

options {
	directory \&"/var/named\&";
};

controls {
	inet * port 52 allow { any; };			// a bad idea
	unix \&"/var/run/ndc\&" perm 0600 owner 0 group 0;	// the default
};

zone \&"isc.org\&" in {
	type master;
	file \&"master/isc.org\&";
};

zone \&"vix.com\&" in {
	type slave;
	file \&"slave/vix.com\&";
	masters { 10.0.0.53; };
};

zone \&"0.0.127.in-addr.arpa\&" in {
	type master;
	file \&"master/127.0.0\&";
};

zone \&".\&" in {
	type hint;
	file \&"root.cache\&";
};
.Ed

.Sh FILES
.Bl -tag -width 1 -compact
.It Pa /etc/named.conf
The BIND 8
.Nm named
configuration file.
.El

.Sh SEE ALSO
.Xr named 8 ,
.Xr ndc 8