1.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") 2.. 3.. SPDX-License-Identifier: MPL-2.0 4.. 5.. This Source Code Form is subject to the terms of the Mozilla Public 6.. License, v. 2.0. If a copy of the MPL was not distributed with this 7.. file, you can obtain one at https://mozilla.org/MPL/2.0/. 8.. 9.. See the COPYRIGHT file distributed with this work for additional 10.. information regarding copyright ownership. 11 12.. _configuration: 13 14.. _sample_configuration: 15 16Configurations and Zone Files 17============================= 18 19Introduction 20------------ 21 22BIND 9 uses a single configuration file called :ref:`named.conf <named_conf>`. 23which is typically located in either /etc/namedb or 24/usr/local/etc/namedb. 25 26 .. Note:: If :ref:`rndc<ops_rndc>` is being used locally (on the same host 27 as BIND 9) then an additional file :iscman:`rndc.conf` may be present, though 28 :iscman:`rndc` operates without this file. If :iscman:`rndc` is being run 29 from a remote host then an :iscman:`rndc.conf` file must be present as it 30 defines the link characteristics and properties. 31 32Depending on the functionality of the system, one or more zone files is 33required. 34 35The samples given throughout this and subsequent chapters use a standard base 36format for both the :iscman:`named.conf` and the zone files for **example.com**. The 37intent is for the reader to see the evolution from a common base as features 38are added or removed. 39 40.. _base_named_conf: 41 42``named.conf`` Base File 43~~~~~~~~~~~~~~~~~~~~~~~~ 44 45This file illustrates the typical format and layout style used for 46:iscman:`named.conf` and provides a basic logging service, which may be extended 47as required by the user. 48 49.. code-block:: c 50 51 // base named.conf file 52 // Recommended that you always maintain a change log in this file as shown here 53 // options clause defining the server-wide properties 54 options { 55 // all relative paths use this directory as a base 56 directory "/var"; 57 // version statement for security to avoid hacking known weaknesses 58 // if the real version number is revealed 59 version "not currently available"; 60 }; 61 62 // logging clause 63 // log to /var/log/named/example.log all events from info UP in severity (no debug) 64 // uses 3 files in rotation swaps files when size reaches 250K 65 // failure messages that occur before logging is established are 66 // in syslog (/var/log/messages) 67 // 68 logging { 69 channel example_log { 70 // uses a relative path name and the directory statement to 71 // expand to /var/log/named/example.log 72 file "log/named/example.log" versions 3 size 250k; 73 // only log info and up messages - all others discarded 74 severity info; 75 }; 76 category default { 77 example_log; 78 }; 79 }; 80 81The :any:`logging` and :namedconf:ref:`options` blocks 82and :any:`category`, :any:`channel`, 83:any:`directory`, :any:`file`, and :any:`severity` 84statements are all described further in the appropriate sections of this ARM. 85 86.. _base_zone_file: 87 88**example.com** base zone file 89~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 90 91The following is a complete zone file for the domain **example.com**, which 92illustrates a number of common features. Comments in the file explain these 93features where appropriate. Zone files consist of :ref:`Resource Records (RR) 94<zone_file>`, which describe the zone's characteristics or properties. 95 96.. code-block:: 97 :linenos: 98 99 ; base zone file for example.com 100 $TTL 2d ; default TTL for zone 101 $ORIGIN example.com. ; base domain-name 102 ; Start of Authority RR defining the key characteristics of the zone (domain) 103 @ IN SOA ns1.example.com. hostmaster.example.com. ( 104 2003080800 ; serial number 105 12h ; refresh 106 15m ; update retry 107 4d ; expiry 108 2h ; minimum 109 ) 110 ; name server RR for the domain 111 IN NS ns1.example.com. 112 ; the second name server is external to this zone (domain) 113 IN NS ns2.example.net. 114 ; mail server RRs for the zone (domain) 115 3w IN MX 10 mail.example.com. 116 ; the second mail servers is external to the zone (domain) 117 IN MX 20 mail.example.net. 118 ; domain hosts includes NS and MX records defined above 119 ; plus any others required 120 ; for instance a user query for the A RR of joe.example.com will 121 ; return the IPv4 address 192.168.254.6 from this zone file 122 ns1 IN A 192.168.254.2 123 mail IN A 192.168.254.4 124 joe IN A 192.168.254.6 125 www IN A 192.168.254.7 126 ; aliases ftp (ftp server) to an external domain 127 ftp IN CNAME ftp.example.net. 128 129This type of zone file is frequently referred to as a **forward-mapped zone 130file**, since it maps domain names to some other value, while a 131:ref:`reverse-mapped zone file<ipv4_reverse>` maps an IP address to a domain 132name. The zone file is called **example.com** for no good reason except that 133it is the domain name of the zone it describes; as always, users are free to 134use whatever file-naming convention is appropriate to their needs. 135 136Other Zone Files 137~~~~~~~~~~~~~~~~ 138 139Depending on the configuration additional zone files may or should be present. 140Their format and functionality are briefly described here. 141 142localhost Zone File 143~~~~~~~~~~~~~~~~~~~ 144 145All end-user systems are shipped with a ``hosts`` file (usually located in 146/etc). This file is normally configured to map the name **localhost** (the name 147used by applications when they run locally) to the loopback address. It is 148argued, reasonably, that a forward-mapped zone file for **localhost** is 149therefore not strictly required. This manual does use the BIND 9 distribution 150file ``localhost-forward.db`` (normally in /etc/namedb/master or 151/usr/local/etc/namedb/master) in all configuration samples for the following 152reasons: 153 1541. Many users elect to delete the ``hosts`` file for security reasons (it is a 155 potential target of serious domain name redirection/poisoning attacks). 156 1572. Systems normally lookup any name (including domain names) using the 158 ``hosts`` file first (if present), followed by DNS. However, the 159 ``nsswitch.conf`` file (typically in /etc) controls this order (normally 160 **hosts: file dns**), allowing the order to be changed or the **file** value 161 to be deleted entirely depending on local needs. Unless the BIND 162 administrator controls this file and knows its values, it is unsafe to 163 assume that **localhost** is forward-mapped correctly. 164 1653. As a reminder to users that unnecessary queries for **localhost** form a 166 non-trivial volume of DNS queries on the public network, which affects DNS 167 performance for all users. 168 169Users may, however, elect at their discretion not to implement this file since, 170depending on the operational environment, it may not be essential. 171 172The BIND 9 distribution file ``localhost-forward.db`` format is shown for 173completeness and provides for both IPv4 and IPv6 localhost resolution. The zone 174(domain) name is **localhost.** 175 176.. code-block:: 177 178 $TTL 3h 179 localhost. SOA localhost. nobody.localhost. 42 1d 12h 1w 3h 180 NS localhost. 181 A 127.0.0.1 182 AAAA ::1 183 184.. NOTE:: Readers of a certain age or disposition may note the reference in this file to the late, 185 lamented Douglas Noel Adams. 186 187localhost Reverse-Mapped Zone File 188~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 189 190This zone file allows any query requesting the name associated with the 191loopback IP (127.0.0.1). This file is required to prevent unnecessary queries 192from reaching the public DNS hierarchy. The BIND 9 distribution file 193``localhost.rev`` is shown for completeness: 194 195.. code-block:: 196 197 $TTL 1D 198 @ IN SOA localhost. root.localhost. ( 199 2007091701 ; serial 200 30800 ; refresh 201 7200 ; retry 202 604800 ; expire 203 300 ) ; minimum 204 IN NS localhost. 205 1 IN PTR localhost. 206