named.conf

From: https://www.zytrax.com/books/dns/ch7/

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.


==================== EXAMPLES =========================



localhost-reverse-map-zone
Sample localhost Reverse Map zone file

The localhost reverse-mapping file which this guide calls locahost.rev is 
supplied with the standard BIND distributions (typically called named.local in 
BIND distributions). This file should not need modification. This file lacks an
$ORIGIN directive which might help clarify understanding.

The localhost.rev file maps the IP address 127.0.0.1 to the name 'localhost'.

	 $TTL86400 ;
; could use $ORIGIN 0.0.127.IN-ADDR.ARPA.
@       IN      SOA     localhost. root.localhost.  (
                        1997022700 ; Serial
                        3h      ; Refresh
                        15      ; Retry
                        1w      ; Expire
                        3h )    ; Minimum
        IN      NS      localhost.
1       IN      PTR     localhost.  



Sample master.localhost zone file

This file, supplied with the standard distributions (typically called localhost.
zone in BIND distributions), is a model of brevity and very cryptic! Comments 
have been added to clarify the definitions. This file should not need 
modification.

The master.localhost file maps the name localhost to the local or loopback 
address (127.0.0.1). Localhost is used by many system programs.

$TTL86400 ; 24 hours could have been written as 24h or 1D
$ORIGIN localhost.
; line below expands to: localhost 1D IN SOA localhost root.localhost
@  1D  IN SOA @root (
      2002022401 ; serial
      3H ; refresh
      15 ; retry
      1w ; expire
      3h ; minimum
     )
@  1D  IN  NS @ 
   1D  IN  A  127.0.0.1



Sample localhost Reverse Map zone file

The localhost reverse-mapping file which this guide calls locahost.rev is supplied with the standard BIND distributions (typically called named.local in BIND distributions). This file should not need modification. This file lacks an $ORIGIN directive which might help clarify understanding.

The localhost.rev file maps the IP address 127.0.0.1 to the name 'localhost'.

$TTL86400 ;
; could use $ORIGIN 0.0.127.IN-ADDR.ARPA.
@       IN      SOA     localhost. root.localhost.  (
                        1997022700 ; Serial
                        3h      ; Refresh
                        15      ; Retry
                        1w      ; Expire
                        3h )    ; Minimum
        IN      NS      localhost.
1       IN      PTR     localhost.


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.


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.