diff options
author | des <des@FreeBSD.org> | 2004-09-24 19:48:50 +0000 |
---|---|---|
committer | des <des@FreeBSD.org> | 2004-09-24 19:48:50 +0000 |
commit | bd20f820eed84d93e9324f7de3865ce58a0c7731 (patch) | |
tree | bb3edb8dcc07615d426eb359f46c1741e4c22575 /contrib/bind/doc/man/named.conf.5 | |
parent | 3fe60073ff63db1d6dc640928a53105d35a80da4 (diff) | |
download | FreeBSD-src-bd20f820eed84d93e9324f7de3865ce58a0c7731.zip FreeBSD-src-bd20f820eed84d93e9324f7de3865ce58a0c7731.tar.gz |
Retire the BIND 8 sources.
Diffstat (limited to 'contrib/bind/doc/man/named.conf.5')
-rw-r--r-- | contrib/bind/doc/man/named.conf.5 | 2145 |
1 files changed, 0 insertions, 2145 deletions
diff --git a/contrib/bind/doc/man/named.conf.5 b/contrib/bind/doc/man/named.conf.5 deleted file mode 100644 index 2d7e627..0000000 --- a/contrib/bind/doc/man/named.conf.5 +++ /dev/null @@ -1,2145 +0,0 @@ -.\" Copyright (c) 1999-2000 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 0n -.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 -.Pp -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. -.Pp -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. -.Pp -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. -.Pp -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 -.Pp -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 -.Pp -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 -.Pp -.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 -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 0n -.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 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 -.Pp -\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 ); -.Pp - [ 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; ] - }; ] -.Pp - [ 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 -.Pp -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 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 -.Pp -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 -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 - }; -.Pp - 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 - }; -.Pp - 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 - }; -.Pp - channel null { - null; # toss anything sent to this channel - }; -.Ed -.Pp -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 -.Pp -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 -.Pp -To discard all messages in a category, specify the -.Li null -channel: -.Bd -literal - category lame-servers { null; }; - category cname { null; }; -.Ed -.Pp -The following categories are available: -.Bl -tag -width 0n -.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 update-security -Denied dynamic updates due to access controls. -.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 { - [ hostname \fIhostname_string\fR; ] - [ 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; ] - [ host-statistics-max \fInumber\fR; ] - [ multiple-cnames \fIyes_or_no\fR; ] - [ notify ( \fIyes_or_no\fR | explicit ); ] - [ suppress-initial-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 ; ... ] }; ] - [ preferred-glue ( A | AAAA ); ] - [ edns-udp-size \fInumber\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 Server Information -.Bl -tag -width 0n -.It Ic hostname -This defaults to the hostname of the machine hosting the nameserver as found by gethostname(). -Its prime purpose is to be able to identify which of a number of anycast -servers is actually answering your queries by sending a txt query for -.Pa hostname.bind -in class chaos to the anycast server and geting back a unique name. -Setting -the hostname to a empty string ("") will disable processing of the queries. -.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 the server, -but some server operators prefer the string ( -.Ic surely you must be joking -). -.El -.Ss Pathnames -.Bl -tag -width 0n -.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 0n -.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 no . -Turning -.Lc auth-nxdomain -will allow older clients that require -.Li AA -to be set to accept -.Dv NXDOMAIN -responses to work. -.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 ; -.Pp -The use of -.Ic has-old-clients -with -.Ic auth-nxdomain , -.Ic maintain-ixfr-base , -and -.Ic rfc2308-type1 -is order dependent. -.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 , -a IXFR database file is kept for all dynamically updated zones. -This enables the server to answer IXFR queries which can speed up -zone transfers enormously. -The default is -.Li no . -.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. -If -.Li explicit , -the DNS NOTIFY messages will only be sent to the addresses in the -.Ic also-notify -list. -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 suppress-initial-notify -If -.Li yes , -suppress the initial notify messages when the server first loads. -The default is -.Li no . -.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 -.Pp -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 -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 0n -.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 0n -.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 -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 0n -.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 to allow queries -from all hosts. -.Bl -tag -width 0n -.It Ic allow-recursion -Specifies which hosts are allowed to ask recursive questions. -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 -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 -.Pp -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 -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 0n -.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 overridden on a per-zone basis by including a -.Nm transfer-source -statement within the zone block in the configuration file. -.El -.Ss Resource Limits -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 0n -.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 0n -.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 -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 -.Pp -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 -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. -.Pp -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. -.Pp -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. -.Pp -The -.Ic sortlist -statement takes an address match list and interprets it even more -specially than the -.Ic topology -statement does. -.Pp -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. -.Pp -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. -.Pp -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 -.Pp -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 -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). -.Pp -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 -.Pp -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 "*". -.Pp -The legal values for -.Ic ordering -are: -.Bl -tag -width indent -.It Ic fixed -Records are returned in the order they are defined in the zone file. -.It Ic random -Records are returned in some random order. -.It Ic cyclic -Records are returned in a round-robin order. -.El -.Pp -For example: -.Bd -literal - rrset-order { - class IN type A name "rc.vix.com" order random; - order cyclic; - }; -.Ed -.Pp -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. -.Pp -If multiple -.Ic rrset-order -statements appear, they are not combined--the last one applies. -.Pp -If no -.Ic rrset-order -statement is specified, a default one of: -.Bd -literal - rrset-order { class ANY type ANY name "*" order cyclic ; }; -.Ed -.Pp -is used. -.Ss Glue Ordering -When running a root nameserver it is sometimes necessary to ensure that other -nameservers that are priming are successful. -This requires that glue A records for at least of the nameservers are returned -in the answer to a priming query. -This can be achieved by setting -.Ic preferred-glue A; -which will add A records before other types in the additional section. -.Ss EDNS -Some firewalls fail to pass EDNS/UDP messages that are larger than -certain size, 512 or the UDP reassembly buffer. -To allow EDNS to -work across such firewalls it is necessary to advertise a EDNS -buffer size that is small enough to not trigger failures. -.Ic edns-udp-size -can be use to adjust the advertised size. -Values less than 512 will be increased to 512 and values greater than -4096 will be truncated to 4096. -.Ss Tuning -.Bl -tag -width 0n -.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 }; ] - [ forward ( only | first ); ] - [ forwarders { [ \fIip_addr\fR ; [ \fIip_addr\fR ; ... ] ] }; ] - [ dialup \fIyes_or_no\fR; ] - [ notify ( \fIyes_or_no\fR | explicit ); ] - [ also-notify { \fIip_addr\fR; [ \fIip_addr\fR; ... ] }; - [ pubkey \fInumber\fR \fInumber\fR \fInumber\fR \fIstring\fR; ] -}; -.Pp -zone \fIdomain_name\fR [ ( in | hs | hesiod | chaos ) ] { - type ( slave | stub ); - [ file \fIpath_name\fR; ] - masters [ port \fIip_port\fR ] { \fIip_addr\fR [ key \fIkey_id\fR ]; [ ... ] }; - [ check-names ( warn | fail | ignore ); ] - [ allow-update { \fIaddress_match_list\fR }; ] - [ allow-query { \fIaddress_match_list\fR }; ] - [ allow-transfer { \fIaddress_match_list\fR }; ] - [ forward ( only | first ); ] - [ forwarders { [ \fIip_addr\fR ; [ \fIip_addr\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; ] -}; -.Pp -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 ); ] -}; -.Pp -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 0n -.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 0n -.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 0n -.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 { - [ edns \fIyes_or_no\fR; ] - [ bogus \fIyes_or_no\fR; ] - [ support-ixfr \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 does not support EDNS you can prevent -named making EDNS queries to it by specifying -.Ic edns -.Ic no; . -The default value of -.Ic edns -is -.Ic yes . -.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 -If the server supports IXFR you can tell named to attempt to -perform a IXFR style zone transfer by specifing -.Ic support-ixfr -.Li yes . -The default value of -.Ic support-ixfr -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 -statement 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 -.Pp -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 -.Pp -Here's a more typical real-world example. -.Bd -literal -/* - * A simple BIND 8 configuration - */ -.Pp -logging { - category lame-servers { null; }; - category cname { null; }; -}; -.Pp -options { - directory \&"/var/named\&"; -}; -.Pp -controls { - inet * port 52 allow { any; }; // a bad idea - unix \&"/var/run/ndc\&" perm 0600 owner 0 group 0; // the default -}; -.Pp -zone \&"isc.org\&" in { - type master; - file \&"master/isc.org\&"; -}; -.Pp -zone \&"vix.com\&" in { - type slave; - file \&"slave/vix.com\&"; - masters { 10.0.0.53; }; -}; -.Pp -zone \&"0.0.127.in-addr.arpa\&" in { - type master; - file \&"master/127.0.0\&"; -}; -.Pp -zone \&".\&" in { - type hint; - file \&"root.cache\&"; -}; -.Ed -.Sh FILES -.Bl -tag -width 0n -compact -.It Pa /etc/named.conf -The BIND 8 -.Nm named -configuration file. -.El -.Sh SEE ALSO -.Xr named 8 , -.Xr ndc 8 |