7. 'named.conf' Configuration

This chapter describes the BIND 9 named.conf file which controls the behaviour and functionality of BIND. named.conf is the only file which is used by BIND - confusingly there are still many references to boot.conf which was used by BIND 4 - ignore 'em.

The named.conf file can exist is a confusing number of places depending on your OS. For FreeBSD it's typically in /etc/namedb (or for a non-base install /usr/local/etc), for the *nixes it's typically in /etc and for Windows it's in \Program Files\ISC BIND 9\etc (ancient version installed to \Windows/Winnt\system32\dns\etc).

BIND releases include a list of the latest statements and options supported. This list is available in /usr/share/docs/bind-version/misc/options (FC) or /usr/src/contrib/bind9/doc/misc/options (FreeBSD) and if you are using the Windows version it ain't there!.

BIND allows a daunting list of configuration entities. Panic not: you only need a small subset to get operational. Read the first two sections (named.conf format, structure and overview and named.conf required zone files) to get a feel for the things you need, it identifies the MINIMAL values (depending on your requirement). Check the samples section for configuration specific examples.

Note: We got fed-up with inconsistent terminology so we use the term clause to describe the structure that group together a set of related statements. We don't call 'em options or substatements(!) or phrases - just clauses and statements. Period. If you want to read more about our reasons.

clauses supported by BIND are:

acl	Access Control Lists. Defines one of more access control lists, groups of hosts or users identified by keys, that may be referenced in view and other clauses or statements.
controls	Describes and controls access to the control channel used by the remote administrator when using the rndc utility.
dlz	Defines Dynamically Loaded Zones. Beta (9.7) feature.
include	Neither a statement nor a clause. Included here for no particularly good reason. include can appear anywhere in a named.conf file either inside or outside a clause. Allows inclusion of external files into named.conf for administrative convenience or security reasons.
key	Defines shared keys used to control and authenticate operations such as Dynamic DNS (DDNS) and the remote control channel (the controls clause). May be nested in a view clause.
logging	Configures the location, level and type of logging that BIND performs. Unless you are using syslog you need a logging statement for BIND.
lwres	Defines the properties of BIND when running as a lightweight resolver.
managed-keys	Defines DNSSEC trusted-anchors that are dynamically managed by RFC 5011 compliant procedures.
masters	Defines a list of one or more masters that may be referenced from a masters statement in a zone clause of type slave or an also-notify statement in a zone clause of type master. Note: Somewhat confusing because the name, masters, is used for both the free-standing clause and a statement within a zone clause.
options	Groups statements that control generic or global behavior and that have scope for all zones and views unless overridden within a zone, views or other clause.
server	Defines the properties or behavior this server will use when accessing or responding to a defined remote server. May be nested in a view clause.
statistics-channels	Defines access to XML (browser) statistics.
trusted-keys	Statically managed trusted-anchors for DNSSEC. May be nested in a view clause.
view	Controls BIND functionality and behaviour based on the host address(es).
zone	Defines the specific zones that your name server will support. In addition there are a number of special zones that you may need to include. May be nested in a view clause.

Statements Classification

We have also classified all the statements into the following groups:

Queries - statements controlling query behavior
Transfer - statements controlling zone transfer and DDNS behavior
Operations - statements controlling operational behavior
Security - statements controlling security behavior
Statistics - statements controlling statistical logging behavior

A full list of all statements is here.

named.conf format, structure and overview

A named.conf file can contain comments and will contain a number of clauses which group together related statements which control the functionality and security of the BIND server.

BIND provides a number of comment formats as follows:

/* C style comment format needs opening and closing markers
** but allows multiple lines or */
/* single lines */
// C++ style comments single line format no closing required
# PERL/SHELL style comments single lines no closing required

The whole named.conf file is parsed for completeness and correctness before use - this is a major change from previous releases of BIND. Prior to the availability of (or in the absence of) a valid logging clause failures use syslogd and are (depending on your syslog.conf file) typically written to /var/log/messages thereafter failures are written to any file(s) defined in your logging clause. There are some rules defined for the clause order for BIND 9. The general clause layout of a named.conf file is usually:

 // acl clause if required 
 // defining first avoids forward name references
 acl "name" {...}; 
 logging {...};
 // usually requires at least a file statement
 // unless you are using the system log
 options {...};
 // other clauses/statements (as required)
 // zones clauses including 'required' zones
 zone {...};
 ....
 zone {...};

If you are using view clause the order changes significantly:

// key clauses if required 
 // defined first to avoid forward name references from acls
 key "name" {
  ...
 }; 
 // acl clauses if required 
 // defined before use avoids forward name references
 acl "name" {
  ...
 }; 
 logging {...}
 // usually requires at least a file statement
 // unless you are using the system log
 options {...};
 // other clauses/statements (as required)
 view "first" {
  options{...};
 	// zones clauses including 'required' zones
  zone {...};
  .....
  zone {...};
 };
 view "second" {
  options {...};
  // zones clauses including 'required' zones
  zone {...};
  .....
  zone {...};
 };

BIND is very picky about opening and closing brackets/braces, semicolons and all the other separators defined in the formal grammars below, you will see in the literature various ways to layout statements. These variations are simply attempts to minimise the chance of errors, they have no other significance. Use the method you feel most comfortable with.

named.conf required zone files

Depending on your requirements BIND needs a number of zone files to allow it to function properly - these are in addition to any zones files that explicitly describe master or slave zones:

root.servers	Only applicable if the name server supports recursive queries. This file (called named.ca or named.root in most distributions but renamed root.servers in this guide) defines a list of name servers (a.root-servers.net - m.root-servers.net) where BIND can get a list of TLD servers for the particular TLD, for instance, .com - perhaps that's why its called hint. When a name server wich supports recursive queries (a full function resolver) cannot resolve a query it uses the name server list obtained to provide a referral (if it's an Iterative query) or to find an answer (if it's a Recursive query). The root server file is defined using a normal zone clause with type hint as in the fragment below: zone "." in{ type hint; file "root.servers"; }; The 'zone "."' is short for the root zone and means any zone for which there is no locally defined zone (slave or master) or cached answer. By convention this file is usually included as the first zone statement but there is no good reason for this - it may be placed anywhere suitable. If you are running an authoritative only server or an internal name service on a closed network you do not need the root.servers file or 'hint' zone. Even if the hint zone file is not defined BIND 9 has an internal list which it uses. The root servers file (whatever its name) supplied with any DNS distribution will get out of date and can be updated from a number of locations including ICANN. Numerous commentators advise that this file be updated periodically. This is not essential - root server IP addresses change rarely. The first thing that BIND does when loaded with a hint zone is to update the root-server list from one of the locations in the root.server file. It will log any discrepancies from the supplied file but carry on using its retrieved list. Other than extra log messages there seems little advantage in updating the root.server file unless BIND load time is vital. If you are curious to see a sample root.server file.
localhost	This zone allows resolution of the name localhost to the loopback address 127.0.0.1 when using the DNS server. Any query for 'localhost' from any host using the name server will return 127.0.0.1. localhost is used by many applications in both the Windows and nix worlds. On its face this may all seem a little strange and exotic and you can either continue to treat the process as magic or get some understanding of how resolvers work. Failure to include a localhost* zone has two consequences. It can slow up local applications since the query, instead of being answered locally, will go to the DNS hierarchy where it will take much longer to get a response. Second, it sends an unnecessay query to the root thus slowing up responses to everybody's genuine queries - including yours. Other than for hardened authoritative servers, not including a localhost zone file is the ultimate failure of enlightened self-interest as well as being plain stupid. The localhost zone is defined as shown below zone "localhost" in{ type master; file "master.localhost"; }; In many examples and even the files supplied with BIND 9 a zone specific option allow-update statement is shown as allow-update (none;);. Since this is BIND 9's default mode it is not required and has been omitted though its inclusion is generally good practice. An example master.localhost.
reverse-map	Reverse mapping describes the process of translating an IP address to a host name. This process uses a special domain called IN-ADDR.ARPA and, if it is to be supported, requires a corresponding zone file. Reverse Mapping and the required zone files are described in detail. Reverse-mapping, especially when using RFC1918 style private addresses of the form 192.168.x.x, 10.x.x.x or some addresses in the 172.x.x.x range, is the cause of much DNS/BIND mis-configuration and results in pointless queries being directed at the DNS hierarchy thus increasing the already extensive unnecessary query pollution. The empty-zones-enable statement (defaults to yes) was introduced in an attempt to reduce this problem. However, failing to understand how the entire process works and how to correctly configure your DNS may lead to other more heinous mis-configuration errors which will likely, sooner rather than later, cause discomfort, performance loss and in extreme cases the sun to fall out of the sky. It will, as your mother used to say, all end in tears.
0.0.127.IN-ADDR.ARPA	This special zone allows reverse mapping of the loopback address 127.0.0.1 to satisfy applications which do reverse or double lookups. Any request for the address 127.0.0.1 using this name server will return the name localhost. On its face this may seem a little strange and you can either continue to treat the process as magic or get some understanding of how resolvers work and the unpleasant issue of reverse mapping. The 0.0.127.IN-ADDR.ARPA zone is defined as shown below zone "0.0.127.in-addr.arpa" in{ type master; file "localhost.rev"; }; In many examples and even the files supplied with BIND 9 a zone specific option allow-update statement is shown as allow-update (none;);. Since this is BIND 9's default mode it is not required and has been omitted. An example localhost.rev.

Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.