chapter6.rst \
chapter7.rst \
chapter9.rst \
- configuration.inc.rst \
+ config-auth.inc.rst \
+ config-intro.inc.rst \
+ config-resolve.inc.rst \
conf.py \
dlz.inc.rst \
dns-ops.inc.rst \
pkcs11.inc.rst \
platforms.inc.rst \
plugins.inc.rst \
+ primary-secondary.dia \
+ primary-secondary.png \
recursive-query.dia \
recursive-query.png \
reference.rst \
requirements.inc.rst \
requirements.txt \
+ resolver-forward.dia \
+ resolver-forward.png \
security.inc.rst \
sig0.inc.rst \
tkey.inc.rst \
.. See the COPYRIGHT file distributed with this work for additional
.. information regarding copyright ownership.
-.. include:: configuration.inc.rst
+.. highlight:: none
+
+.. include:: config-intro.inc.rst
+.. include:: config-auth.inc.rst
+.. include:: config-resolve.inc.rst
.. include:: zones.inc.rst
--- /dev/null
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0. If a copy of the MPL was not distributed with this
+.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
+..
+.. See the COPYRIGHT file distributed with this work for additional
+.. information regarding copyright ownership.
+
+.. _config_auth_samples:
+
+Authoritative Name Servers
+--------------------------
+
+These provide authoritative answers to user queries for the zones
+they support: for instance, the zone data describing the domain name **example.com**. An
+authoritative name server may support one or many zones.
+
+Each zone may be defined as either a **primary** or a **secondary**. A primary zone
+reads its zone data directly from a file system. A secondary zone obtains its zone
+data from the primary zone using a process called **zone transfer**. Both the primary
+and the secondary zones provide authoritative data for their zone; there is no difference
+in the answer to a query from a primary or a secondary zone. An authoritative name server
+may support any combination of primary and secondary zones.
+
+.. Note:: The terms **primary** and **secondary** do not imply any access
+ priority. Resolvers (name servers that provide the complete answers to user
+ queries) are not aware of (and cannot find out) whether an authoritative
+ answer comes from the primary or secondary name server. Instead, the
+ resolver uses the list of authoritative servers for the zone (there must be
+ at least two) and maintains a Round Trip Time (RTT) - the time taken to
+ respond to the query - for each server in the list. The resolver uses the
+ lowest-value server (the fastest) as its preferred server for the zone and
+ continues to do so until its RTT becomes higher than the next slowest in its
+ list, at which time that one becomes the preferred server.
+
+ For reasons of backward compatibility BIND 9 treats "primary" and "master" as
+ synonyms, as well as "secondary" and "slave."
+
+.. _notify:
+
+The following diagram shows the relationship between the primary and secondary
+name servers. The text below explains the process in detail.
+
+.. figure:: primary-secondary.png
+ :align: center
+
+ Authoritative Primary and Secondary Name Servers
+
+The numbers in parentheses in the following text refer to the numbered items in the diagram above.
+
+1. The authoritative primary name server always loads (or reloads) its zone
+ files from (1) a local or networked filestore.
+
+2. The authoritative secondary name server always loads its zone data from a
+ primary via a **zone transfer** operation. Zone transfer may use **AXFR**
+ (complete zone transfer) or **IXFR** (incremental zone transfer), but only
+ if both primary and secondary name servers support the service. The zone
+ transfer process (either AXFR or IXFR) works as follows:
+
+ a) The secondary name server for the zone reads (3 and 4) the
+ :ref:`SOA RR<soa_rr>` periodically. The interval is defined by the **refresh**
+ parameter of the Start of Authority (SOA) RR.
+
+ b) The secondary compares the **serial number** parameter of the SOA RR
+ received from the primary with the serial number in the SOA RR of its
+ current zone data.
+
+ c) If the received serial number is arithmetically greater (higher) than the
+ current one, the secondary initiates a zone transfer (5) using AXFR or IXFR
+ (depending on the primary and secondary configuration), using TCP over
+ port 53 (6).
+
+3. The typically recommended zone refresh times for the SOA RR (the time
+ interval when the secondary reads or polls the primary for the zone SOA RR)
+ are multiples of hours to reduce traffic loads. Worst-case zone change
+ propagation can therefore take extended periods.
+
+4. The optional NOTIFY (:rfc:`1996`) feature (2) is automatically configured;
+ use the :ref:`notify <notify_st>` statement to turn off the feature.
+ Whenever the primary loads or reloads a zone, it sends a NOTIFY message to
+ the configured secondary (or secondaries) and may optionally be configured
+ to send the NOTIFY message to other hosts using the
+ :ref:`also-notify<also-notify>` statement. The NOTIFY message simply
+ indicates to the secondary that the primary has loaded or reloaded the zone.
+ On receipt of the NOTIFY message, the secondary respons to indicate it has received the NOTIFY and immediately reads the SOA RR
+ from the primary (as described in section 2 a. above). If the zone file has
+ changed, propagation is practically immediate.
+
+The authoritative samples all use NOTIFY but identify the statements used, so
+that they can be removed if not required.
+
+.. _sample_primary:
+
+Primary Authoritative Name Server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The zone files are unmodified :ref:`from the base samples<base_zone_file>` but
+the :iscman:`named.conf` file has been modified as shown:
+
+.. code-block:: c
+ :linenos:
+
+ // authoritative primary named.conf file
+ // options clause defining the server-wide properties
+ options {
+ // all relative paths use this directory as a base
+ directory "/var";
+ // version statement for security to avoid hacking known weaknesses
+ // if the real version number is revealed
+ version "not currently available";
+ // This is the default - allows user queries from any IP
+ allow-query { any; };
+ // normal server operations may place items in the cache
+ // this prevents any user query from accessing these items
+ // only authoritative zone data will be returned
+ allow-query-cache { none; };
+ // Do not provide recursive service to user queries
+ recursion no;
+ };
+ // logging clause
+ // log to /var/log/named/example.log all events from info UP in severity (no debug)
+ // uses 3 files in rotation swaps files when size reaches 250K
+ // failure messages that occur before logging is established are
+ // in syslog (/var/log/messages)
+ //
+ logging {
+ channel example_log {
+ // uses a relative path name and the directory statement to
+ // expand to /var/log/named/example.log
+ file "log/named/example.log" versions 3 size 250k;
+ // only log info and up messages - all others discarded
+ severity info;
+ };
+ category default {
+ example_log;
+ };
+ };
+ // Provide forward mapping zone for localhost
+ // (optional)
+ zone "localhost" {
+ type primary;
+ file "master/localhost-forward.db";
+ notify no;
+ };
+ // Provide reverse mapping zone for the loopback
+ // address 127.0.0.1
+ zone "0.0.127.in-addr.arpa" {
+ type primary;
+ file "localhost.rev";
+ notify no;
+ };
+ // We are the primary server for example.com
+ zone "example.com" {
+ // this is the primary name server for the zone
+ type primary;
+ file "example.com";
+ // this is the default
+ notify yes;
+ // IP addresses of secondary servers allowed to
+ // transfer example.com from this server
+ allow-transfer {
+ 192.168.4.14;
+ 192.168.5.53;
+ };
+ };
+
+The added statements and clauses are commented in the above file.
+
+The :ref:`zone<zone_clause>` clause, and :ref:`allow-query<allow-query>`,
+:ref:`allow-query-cache<allow-query-cache>`,
+:ref:`allow-transfer<allow-transfer>`, :ref:`file<file>`,
+:ref:`notify<notify_st>`, :ref:`recursion<recursion>`, and :ref:`type<type>`
+statements are described in detail in the appropriate sections.
+
+.. _sample_secondary:
+
+Secondary Authoritative Name Server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The zone files ``local-host-forward.db`` and ``localhost.rev`` are unmodified
+:ref:`from the base samples<base_zone_file>`. The **example.com** zone file is
+not required (the zone file is obtained from the primary via zone transfer).
+The :iscman:`named.conf` file has been modified as shown:
+
+.. code-block:: c
+ :linenos:
+
+ // authoritative secondary named.conf file
+ // options clause defining the server-wide properties
+ options {
+ // all relative paths use this directory as a base
+ directory "/var";
+ // version statement for security to avoid hacking known weaknesses
+ // if the real version number is revealed
+ version "not currently available";
+ // This is the default - allows user queries from any IP
+ allow-query { any; };
+ // normal server operations may place items in the cache
+ // this prevents any user query from accessing these items
+ // only authoritative zone data will be returned
+ allow-query-cache { none; };
+ // Do not provide recursive service to user queries
+ recursion no;
+ };
+ // logging clause
+ // log to /var/log/named/example.log all events from info UP in severity (no debug)
+ // uses 3 files in rotation swaps files when size reaches 250K
+ // failure messages that occur before logging is established are
+ // in syslog (/var/log/messages)
+ //
+ logging {
+ channel example_log {
+ // uses a relative path name and the directory statement to
+ // expand to /var/log/named/example.log
+ file "log/named/example.log" versions 3 size 250k;
+ // only log info and up messages - all others discarded
+ severity info;
+ };
+ category default {
+ example_log;
+ };
+ };
+ // Provide forward mapping zone for localhost
+ // (optional)
+ zone "localhost" {
+ type primary;
+ file "master/localhost-forward.db";
+ notify no;
+ };
+ // Provide reverse mapping zone for the loopback
+ // address 127.0.0.1
+ zone "0.0.127.in-addr.arpa" {
+ type primary;
+ file "localhost.rev";
+ notify no;
+ };
+ // We are the secondary server for example.com
+ zone "example.com" {
+ // this is a secondary server for the zone
+ type secondary;
+ // the file statement here allows the secondary to save
+ // each zone transfer so that in the event of a program restart
+ // the zone can be loaded immediately and the server can start
+ // to respond to queries without waiting for a zone transfer
+ file "example.com.saved";
+ // IP address of example.com primary server
+ primaries { 192.168.254.2; };
+ };
+
+The statements and clauses added are all commented in the above file.
+
+The :ref:`zone<zone_clause>` clause, and :ref:`allow-query<allow-query>`,
+:ref:`allow-query-cache<allow-query-cache>`,
+:ref:`allow-transfer<allow-transfer>`, :ref:`file<file>`,
+:ref:`notify<notify_st>`, :ref:`primaries<primaries>`,
+:ref:`recursion<recursion>`, and :ref:`type<type>` statements are described in
+detail in the appropriate sections.
+
+If NOTIFY is not being used, no changes are required in this
+:iscman:`named.conf` file, since it is the primary that initiates the NOTIFY
+message.
+
+.. note::
+ Just when the reader thought they understood primary and secondary, things
+ can get more complicated. A secondary zone can also be a primary to other
+ secondaries: :iscman:`named`, by default, sends NOTIFY messages for every
+ zone it loads. Specifying :ref:`notify primary-only;<notify>` in the
+ :ref:`zone<zone_clause>` clause for the secondary causes :iscman:`named` to
+ only send NOTIFY messages for primary zones that it loads.
--- /dev/null
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0. If a copy of the MPL was not distributed with this
+.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
+..
+.. See the COPYRIGHT file distributed with this work for additional
+.. information regarding copyright ownership.
+
+.. _configuration:
+
+.. _sample_configuration:
+
+Configurations and Zone Files
+=============================
+
+Introduction
+------------
+
+BIND 9 uses a single configuration file called :iscman:`named.conf`.
+:iscman:`named.conf` is typically located in either /etc/namedb or
+/usr/local/etc/namedb.
+
+ .. Note:: If :ref:`rndc<ops_rndc>` is being used locally (on the same host
+ as BIND 9) then an additional file :iscman:`rndc.conf` may be present, though
+ :iscman:`rndc` operates without this file. If :iscman:`rndc` is being run
+ from a remote host then an :iscman:`rndc.conf` file must be present as it
+ defines the link characteristics and properties.
+
+Depending on the functionality of the system, one or more zone files is
+required.
+
+The samples given throughout this and subsequent chapters use a standard base
+format for both the :iscman:`named.conf` and the zone files for **example.com**. The
+intent is for the reader to see the evolution from a common base as features
+are added or removed.
+
+.. _base_named_conf:
+
+``named.conf`` Base File
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This file illustrates the typical format and layout style used for
+:iscman:`named.conf` and provides a basic logging service, which may be extended
+as required by the user.
+
+.. code-block:: c
+ :linenos:
+
+ // base named.conf file
+ // Recommended that you always maintain a change log in this file as shown here
+ // options clause defining the server-wide properties
+ options {
+ // all relative paths use this directory as a base
+ directory "/var";
+ // version statement for security to avoid hacking known weaknesses
+ // if the real version number is revealed
+ version "not currently available";
+ };
+
+ // logging clause
+ // log to /var/log/named/example.log all events from info UP in severity (no debug)
+ // uses 3 files in rotation swaps files when size reaches 250K
+ // failure messages that occur before logging is established are
+ // in syslog (/var/log/messages)
+ //
+ logging {
+ channel example_log {
+ // uses a relative path name and the directory statement to
+ // expand to /var/log/named/example.log
+ file "log/named/example.log" versions 3 size 250k;
+ // only log info and up messages - all others discarded
+ severity info;
+ };
+ category default {
+ example_log;
+ };
+ };
+
+The :ref:`logging<logging_grammar>` and :ref:`options<options_grammar>` clauses
+and :ref:`category<the_category_phrase>`, :ref:`channel<channel>`,
+:ref:`directory<directory>`, :ref:`file<file>`, and :ref:`severity<severity>`
+statements are all described further in the appropriate sections of this ARM.
+
+.. _base_zone_file:
+
+**example.com** base zone file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following is a complete zone file for the domain **example.com**, which
+illustrates a number of common features. Comments in the file explain these
+features where appropriate. Zone files consist of :ref:`Resource Records (RR)
+<zone_file>`, which describe the zone's characteristics or properties.
+
+.. code-block::
+ :linenos:
+
+ ; base zone file for example.com
+ $TTL 2d ; default TTL for zone
+ $ORIGIN example.com. ; base domain-name
+ ; Start of Authority RR defining the key characteristics of the zone (domain)
+ @ IN SOA ns1.example.com. hostmaster.example.com. (
+ 2003080800 ; serial number
+ 12h ; refresh
+ 15m ; update retry
+ 3w ; expiry
+ 2h ; minimum
+ )
+ ; name server RR for the domain
+ IN NS ns1.example.com.
+ ; the second name server is external to this zone (domain)
+ IN NS ns2.example.net.
+ ; mail server RRs for the zone (domain)
+ 3w IN MX 10 mail.example.com.
+ ; the second mail servers is external to the zone (domain)
+ IN MX 20 mail.example.net.
+ ; domain hosts includes NS and MX records defined above
+ ; plus any others required
+ ; for instance a user query for the A RR of joe.example.com will
+ ; return the IPv4 address 192.168.254.6 from this zone file
+ ns1 IN A 192.168.254.2
+ mail IN A 192.168.254.4
+ joe IN A 192.168.254.6
+ www IN A 192.168.254.7
+ ; aliases ftp (ftp server) to an external domain
+ ftp IN CNAME ftp.example.net.
+
+This type of zone file is frequently referred to as a **forward-mapped zone
+file**, since it maps domain names to some other value, while a
+:ref:`reverse-mapped zone file<ipv4_reverse>` maps an IP address to a domain
+name. The zone file is called **example.com** for no good reason except that
+it is the domain name of the zone it describes; as always, users are free to
+use whatever file-naming convention is appropriate to their needs.
+
+Other Zone Files
+~~~~~~~~~~~~~~~~
+
+Depending on the configuration additional zone files may or should be present.
+Their format and functionality are briefly described here.
+
+localhost Zone File
+~~~~~~~~~~~~~~~~~~~
+
+All end-user systems are shipped with a ``hosts`` file (usually located in
+/etc). This file is normally configured to map the name **localhost** (the name
+used by applications when they run locally) to the loopback address. It is
+argued, reasonably, that a forward-mapped zone file for **localhost** is
+therefore not strictly required. This manual does use the BIND 9 distribution
+file ``localhost-forward.db`` (normally in /etc/namedb/master or
+/usr/local/etc/namedb/master) in all configuration samples for the following
+reasons:
+
+1. Many users elect to delete the ``hosts`` file for security reasons (it is a
+ potential target of serious domain name redirection/poisoning attacks).
+
+2. Systems normally lookup any name (including domain names) using the
+ ``hosts`` file first (if present), followed by DNS. However, the
+ ``nsswitch.conf`` file (typically in /etc) controls this order (normally
+ **hosts: file dns**), allowing the order to be changed or the **file** value
+ to be deleted entirely depending on local needs. Unless the BIND
+ administrator controls this file and knows its values, it is unsafe to
+ assume that **localhost** is forward-mapped correctly.
+
+3. As a reminder to users that unnecessary queries for **localhost** form a
+ non-trivial volume of DNS queries on the public network, which affects DNS
+ performance for all users.
+
+Users may, however, elect at their discretion not to implement this file since,
+depending on the operational environment, it may not be essential.
+
+The BIND 9 distribution file ``localhost-forward.db`` format is shown for
+completeness and provides for both IPv4 and IPv6 localhost resolution. The zone
+(domain) name is **localhost.**
+
+.. code-block::
+ :linenos:
+
+ $TTL 3h
+ localhost. SOA localhost. nobody.localhost. 42 1d 12h 1w 3h
+ NS localhost.
+ A 127.0.0.1
+ AAAA ::1
+
+.. NOTE:: Readers of a certain age or disposition may note the reference in this file to the late,
+ lamented Douglas Noel Adams.
+
+localhost Reverse-Mapped Zone File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This zone file allows any query requesting the name associated with the
+loopback IP (127.0.0.1). This file is required to prevent unnecessary queries
+from reaching the public DNS hierarchy. The BIND 9 distribution file
+``localhost.rev`` is shown for completeness:
+
+.. code-block::
+ :linenos:
+
+ $TTL 1D
+ @ IN SOA localhost. root.localhost. (
+ 2007091701 ; serial
+ 30800 ; refresh
+ 7200 ; retry
+ 604800 ; expire
+ 300 ) ; minimum
+ IN NS localhost.
+ 1 IN PTR localhost.
--- /dev/null
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0. If a copy of the MPL was not distributed with this
+.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
+..
+.. See the COPYRIGHT file distributed with this work for additional
+.. information regarding copyright ownership.
+
+.. _config_resolver_samples:
+
+Resolver (Caching Name Servers)
+-------------------------------
+
+Resolvers handle :ref:`recursive user queries <recursive_query>` and provide
+complete answers; that is, they issue one or more :ref:`iterative queries
+<iterative_query>` to the DNS hierarchy. Having obtained a complete answer (or
+an error), a resolver passes the answer to the user and places it in its cache.
+Subsequent user requests for the same query will be answered from the
+resolver's cache until the :term:`TTL` of the cached answer has expired, when
+it will be flushed from the cache; the next user query that requests the same
+information results in a new series of queries to the DNS hierarchy.
+
+Resolvers are frequently referred to by a bewildering variety of names,
+including caching name servers, recursive name servers, forwarding resolvers,
+area resolvers, and full-service resolvers.
+
+The following diagram shows how resolvers can function in a typical networked
+environment:
+
+.. figure:: resolver-forward.png
+ :align: center
+
+Resolver and Forwarding Resolver
+
+1. End-user systems are all distributed with a local **stub resolver** as a
+ standard feature. Today, the majority of stub resolvers also provide a local
+ cache service to speed up user response times.
+
+2. A stub resolver has limited functionality; specifically, it cannot follow
+ :ref:`referrals<referral>`. When a stub resolver receives a request for a
+ name from a local program, such as a browser, and the answer is not in its
+ local cache, it sends a :ref:`recursive user query<recursive_query>` (1) to
+ a locally configured resolver (5), which may have the answer available in
+ its cache. If it does not, it issues :ref:`iterative
+ queries<iterative_query>` (2) to the DNS hierarchy to obtain the answer. The
+ resolver to which the local system sends the user query is configured, for
+ Linux and Unix hosts, in ``/etc/resolv.conf``; for Windows users it is
+ configured or changed via the Control Panel or Settings interface.
+
+3. Alternatively, the user query can be sent to a **forwarding resolver** (4).
+ Forwarding resolvers on first glance look fairly pointless, since they
+ appear to be acting as a simple pass-though and, like the stub resolver,
+ require a full-service resolver (5). However, forwarding resolvers can be
+ very powerful additions to a network for the following reasons:
+
+ a) Cost and Performance. Each **recursive user query** (1) at the forwarding
+ resolver (4) results in two messages - the query and its answer. The resolver
+ (5) may have to issue three, four, or more query pairs (2) to get the required
+ answer. Traffic is reduced dramatically, increasing performance or reducing
+ cost (if the link is tariffed). Additionally, since the forwarding resolver is
+ typically shared across multiple hosts, its cache is more likely to contain
+ answers, again improving user performance.
+
+ b) Network Maintenance. Forwarding resolvers (4) can be used to ease the burden
+ of local administration by providing a single point at which changes to remote
+ name servers can be managed, rather than having to update all hosts. Thus, all
+ hosts in a particular network section or area can be configured to point to a
+ forwarding resolver, which can be configured to stream DNS traffic as desired
+ and changed over time with minimal effort.
+
+ c) Sanitizing Traffic. Especially in larger private networks it may be sensible
+ to stream DNS traffic using a forwarding resolver structure. The forwarding
+ resolver (4) may be configured, for example, to handle all in-domain traffic
+ (relatively safe) and forward all external traffic to a **hardened** resolver
+ (5).
+
+ d) Stealth Networks. Forwarding resolvers are extensively used in :ref:`stealth
+ or split networks<split_dns_sample>`.
+
+4. Forwarding resolvers (4) can be configured to forward all traffic to a
+ resolver (5), or to only forward selective traffic (5) while directly
+ resolving other traffic (3).
+
+.. Attention:: While the diagram above shows **recursive user queries**
+ arriving via interface (1), there is nothing to stop them from arriving via
+ interface (2) via the public network. If no limits are placed on the source
+ IPs that can send such queries, the resolver is termed an **open resolver**.
+ Indeed, when the world was young this was the way things worked on the
+ Internet. Much has changed and what seems to be a friendly, generous action
+ can be used by rogue actors to cause all kinds of problems including
+ **Denial of Service (DoS)** attacks. Resolvers should always be configured
+ to limit the IP addresses that can use their services. BIND 9 provides a
+ number of statements and clauses to simplify defining these IP limits and
+ configuring a **closed resolver**. The resolver samples given here all
+ configure closed resolvers using a variety of techniques.
+
+Additional Zone Files
+~~~~~~~~~~~~~~~~~~~~~
+
+Root Servers (Hint) Zone File
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Resolvers (although not necessarily forwarding resolvers) need to access the
+DNS hierarchy. To do this, they need to know the addresses (IPv4 and/or IPv6)
+of the 13 :ref:`root servers<root_servers>`. This is done by the provision of a
+root server zone file, which is contained in the standard BIND 9 distribution
+as the file ``named.root`` (normally found in /etc/namedb or
+/usr/local/namedb). This file may also be obtained from the IANA website
+(https://www.iana.org/domains/root/files).
+
+
+ .. Note:: Many distributions rename this file for historical reasons.
+ Consult the appropriate distribution documentation for the actual file name.
+
+
+The hint zone file is referenced using the :ref:`type hint;<type>` statement and
+a zone (domain) name of "." (the generally silent dot).
+
+ .. Note:: The root server IP addresses have been stable for a number of
+ years and are likely to remain stable for the near future. BIND 9 has a
+ root-server list in its executable such that even if this file is omitted,
+ out-of-date, or corrupt BIND 9 can still function. For this reason, many
+ sample configurations omit the hints file. All the samples given here
+ include the hints file primarily as a reminder of the functionality of the
+ configuration, rather than as an absolute necessity.
+
+Private IP Reverse Map Zone Files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Resolvers are configured to send :ref:`iterative queries<iterative_query>` to
+the public DNS hierarchy when the information requested is not in their cache
+or not defined in any local zone file. Many networks make extensive use of
+private IP addresses (defined by :rfc:`1918`, :rfc:`2193`, :rfc:`5737`, and
+:rfc:`6598`). By their nature these IP addresses are forward-mapped in various
+user zone files. However, certain applications may issue **reverse map**
+queries (mapping an IP address to a name). If the private IP addresses are not
+defined in one or more reverse-mapped zone file(s), the resolver sends them to
+the DNS hierarchy where they are simply useless traffic, slowing down DNS
+responses for all users.
+
+Private IP addresses may be defined using standard :ref:`reverse-mapping
+techniques<ipv4_reverse>` or using the
+:ref:`empty-zones-enable<empty-zones-enable>` statement. By
+default this statement is set to ``empty-zones-enable yes;`` and thus automatically prevents
+unnecessary DNS traffic by sending an NXDOMAIN error response (indicating the
+name does not exist) to any request. However, some applications may require a
+genuine answer to such reverse-mapped requests or they will fail to function.
+Mail systems in particular perform reverse DNS queries as a first-line spam
+check; in this case a reverse-mapped zone file is essential. The sample
+configuration files given here for both the resolver and the forwarding
+resolver provide a reverse-mapping zone file for the private IP address
+192.168.254.4, which is the mail server address in the :ref:`base zone
+file<base_zone_file>`, as an illustration of the reverse-map technique. The
+file is named ``192.168.254.rev`` and has a zone name of
+**254.168.192.in-addr.arpa**.
+
+.. code-block::
+ :linenos:
+
+ ; reverse map zone file for 192.168.254.4 only
+ $TTL 2d ; 172800 seconds
+ $ORIGIN 254.168.192.IN-ADDR.ARPA.
+ @ IN SOA ns1.example.com. hostmaster.example.com. (
+ 2003080800 ; serial number
+ 3h ; refresh
+ 15m ; update retry
+ 3w ; expiry
+ 3h ; nx = nxdomain ttl
+ )
+ ; only one NS is required for this local file
+ ; and is an out of zone name
+ IN NS ns1.example.com.
+ ; other IP addresses can be added as required
+ ; this maps 192.168.254.4 as shown
+ 4 IN PTR mail.example.com. ; fully qualified domain name (FQDN)
+
+.. _sample_resolver:
+
+Resolver Configuration
+~~~~~~~~~~~~~~~~~~~~~~
+
+The resolver provides :ref:`recursive query support<recursive_query>` to a defined set of IP addresses.
+It is therefore a **closed** resolver and cannot be used in wider network attacks.
+
+.. code-block:: c
+ :linenos:
+
+ // resolver named.conf file
+ // Two corporate subnets we wish to allow queries from
+ // defined in an acl clause
+ acl corpnets {
+ 192.168.4.0/24;
+ 192.168.7.0/24;
+ };
+
+ // options clause defining the server-wide properties
+ options {
+ // all relative paths use this directory as a base
+ directory "/var";
+ // version statement for security to avoid hacking known weaknesses
+ // if the real version number is revealed
+ version "not currently available";
+ // this is the default
+ recursion yes;
+ // recursive queries only allowed from these ips
+ // and references the acl clause
+ allow-query { corpnets; };
+ // this ensures that any reverse map for private IPs
+ // not defined in a zone file will *not* be passed to the public network
+ // it is the default value
+ empty-zones-enable yes;
+ };
+
+ // logging clause
+ // log to /var/log/named/example.log all events from info UP in severity (no debug)
+ // uses 3 files in rotation swaps files when size reaches 250K
+ // failure messages that occur before logging is established are
+ // in syslog (/var/log/messages)
+ //
+ logging {
+ channel example_log {
+ // uses a relative path name and the directory statement to
+ // expand to /var/log/named/example.log
+ file "log/named/example.log" versions 3 size 250k;
+ // only log info and up messages - all others discarded
+ severity info;
+ };
+ category default {
+ example_log;
+ };
+ };
+
+ // zone file for the root servers
+ // discretionary zone (see root server discussion above)
+ zone "." {
+ type hint;
+ file "named.root";
+ };
+
+ // zone file for the localhost forward map
+ // discretionary zone depending on hosts file (see discussion)
+ zone "localhost" {
+ type primary;
+ file "masters/localhost-forward.db";
+ notify no;
+ };
+
+ // zone file for the loopback address
+ // necessary zone
+ zone "0.0.127.in-addr.arpa" {
+ type primary;
+ file "localhost.rev";
+ notify no;
+ };
+
+ // zone file for local IP reverse map
+ // discretionary file depending on requirements
+ zone "254.168.192.in-addr.arpa" {
+ type primary;
+ file "192.168.254.rev";
+ notify no;
+ };
+
+The :ref:`zone<zone_clause>` and :ref:`acl<acl_grammar>` clauses, and the
+:ref:`allow-query<allow-query>`, :ref:`empty-zones-enable<empty-zones-enable>`,
+:ref:`file<file>`, :ref:`notify<notify_st>`, :ref:`recursion<recursion>`, and
+:ref:`type<type>` statements are described in detail in the appropriate
+sections.
+
+As a reminder, the configuration of this resolver does **not** access the DNS
+hierarchy (does not use the public network) for any recursive query for which:
+
+1. The answer is already in the cache.
+
+2. The domain name is **localhost** (zone localhost).
+
+3. Is a reverse-map query for 127.0.0.1 (zone 0.0.127.in-addr.arpa).
+
+4. Is a reverse-map query for 192.168.254/24 (zone 254.168.192.in-addr.arpa).
+
+5. Is a reverse-map query for any local IP (``empty-zones-enable``
+ statement).
+
+All other recursive queries will result in access to the DNS hierarchy to
+resolve the query.
+
+.. _sample_forwarding:
+
+Forwarding Resolver Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This forwarding resolver configuration forwards all recursive queries, other
+than those for the defined zones and those for which the answer is already in
+its cache, to a full-service resolver at the IP address 192.168.250.3, with an
+alternative at 192.168.230.27. The forwarding resolver will cache all responses
+from these servers. The configuration is closed, in that it defines those IPs
+from which it will accept recursive queries.
+
+A second configuration in which selective forwarding occurs :ref:`is also
+provided<selective_forward_sample>`.
+
+.. code-block:: c
+ :linenos:
+
+ // forwarding named.conf file
+ // Two corporate subnets we wish to allow queries from
+ // defined in an acl clause
+ acl corpnets {
+ 192.168.4.0/24;
+ 192.168.7.0/24;
+ };
+
+ // options clause defining the server-wide properties
+ options {
+ // all relative paths use this directory as a base
+ directory "/var";
+ // version statement for security to avoid hacking known weaknesses
+ // if the real version number is revealed
+ version "not currently available";
+ // this is the default
+ recursion yes;
+ // recursive queries only allowed from these ips
+ // and references the acl clause
+ allow-query { corpnets; };
+ // this ensures that any reverse map for private IPs
+ // not defined in a zone file will *not* be passed to the public network
+ // it is the default value
+ empty-zones-enable yes;
+ // this defines the addresses of the resolvers to which queries will be forwarded
+ forwarders {
+ 192.168.250.3;
+ 192.168.230.27;
+ };
+ // indicates all queries will be forwarded other than for defined zones
+ forward only;
+ };
+
+ // logging clause
+ // log to /var/log/named/example.log all events from info UP in severity (no debug)
+ // uses 3 files in rotation swaps files when size reaches 250K
+ // failure messages that occur before logging is established are
+ // in syslog (/var/log/messages)
+ //
+ logging {
+ channel example_log {
+ // uses a relative path name and the directory statement to
+ // expand to /var/log/named/example.log
+ file "log/named/example.log" versions 3 size 250k;
+ // only log info and up messages - all others discarded
+ severity info;
+ };
+ category default {
+ example_log;
+ };
+ };
+
+ // hints zone file is not required
+
+ // zone file for the localhost forward map
+ // discretionary zone depending on hosts file (see discussion)
+ zone "localhost" {
+ type primary;
+ file "masters/localhost-forward.db";
+ notify no;
+ };
+
+ // zone file for the loopback address
+ // necessary zone
+ zone "0.0.127.in-addr.arpa" {
+ type primary;
+ file "localhost.rev";
+ notify no;
+ };
+
+ // zone file for local IP reverse map
+ // discretionary file depending on requirements
+ zone "254.168.192.in-addr.arpa" {
+ type primary;
+ file "192.168.254.rev";
+ notify no;
+ };
+
+The :ref:`zone<zone_clause>` and :ref:`acl<acl_grammar>` clauses, and the
+:ref:`allow-query<allow-query>`, :ref:`empty-zones-enable<empty-zones-enable>`,
+:ref:`file<file>`, :ref:`forward<forward>`, :ref:`forwarders<forwarders>`,
+:ref:`notify<notify_st>`, :ref:`recursion<recursion>`, and :ref:`type<type>`
+statements are described in detail in the appropriate sections.
+
+As a reminder, the configuration of this forwarding resolver does **not**
+forward any recursive query for which:
+
+1. The answer is already in the cache.
+
+2. The domain name is **localhost** (zone localhost).
+
+3. Is a reverse-map query for 127.0.0.1 (zone 0.0.127.in-addr.arpa).
+
+4. Is a reverse-map query for 192.168.254/24 (zone 254.168.192.in-addr.arpa).
+
+5. Is a reverse-map query for any local IP (``empty-zones-enable`` statement).
+
+All other recursive queries will be forwarded to resolve the query.
+
+.. _selective_forward_sample:
+
+Selective Forwarding Resolver Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This forwarding resolver configuration only forwards recursive queries for the
+zone **example.com** to the resolvers at 192.168.250.3 and 192.168.230.27. All
+other recursive queries, other than those for the defined zones and those for
+which the answer is already in its cache, are handled by this resolver. The
+forwarding resolver will cache all responses from both the public network and
+from the forwarded resolvers. The configuration is closed, in that it defines
+those IPs from which it will accept recursive queries.
+
+.. code-block:: c
+ :linenos:
+
+ // selective forwarding named.conf file
+ // Two corporate subnets we wish to allow queries from
+ // defined in an acl clause
+ acl corpnets {
+ 192.168.4.0/24;
+ 192.168.7.0/24;
+ };
+
+ // options clause defining the server-wide properties
+ options {
+ // all relative paths use this directory as a base
+ directory "/var";
+ // version statement for security to avoid hacking known weaknesses
+ // if the real version number is revealed
+ version "not currently available";
+ // this is the default
+ recursion yes;
+ // recursive queries only allowed from these ips
+ // and references the acl clause
+ allow-query { corpnets; };
+ // this ensures that any reverse map for private IPs
+ // not defined in a zone file will *not* be passed to the public network
+ // it is the default value
+ empty-zones-enable yes;
+
+ // forwarding is not global but selective by zone in this configuration
+ };
+
+ // logging clause
+ // log to /var/log/named/example.log all events from info UP in severity (no debug)
+ // uses 3 files in rotation swaps files when size reaches 250K
+ // failure messages that occur before logging is established are
+ // in syslog (/var/log/messages)
+ //
+ logging {
+ channel example_log {
+ // uses a relative path name and the directory statement to
+ // expand to /var/log/named/example.log
+ file "log/named/example.log" versions 3 size 250k;
+ // only log info and up messages - all others discarded
+ severity info;
+ };
+ category default {
+ example_log;
+ };
+ };
+
+ // zone file for the root servers
+ // discretionary zone (see root server discussion above)
+ zone "." {
+ type hint;
+ file "named.root";
+ };
+
+ // zone file for the localhost forward map
+ // discretionary zone depending on hosts file (see discussion)
+ zone "localhost" {
+ type primary;
+ file "masters/localhost-forward.db";
+ notify no;
+ };
+
+ // zone file for the loopback address
+ // necessary zone
+ zone "0.0.127.in-addr.arpa" {
+ type primary;
+ file "localhost.rev";
+ notify no;
+ };
+
+ // zone file for local IP reverse map
+ // discretionary file depending on requirements
+ zone "254.168.192.in-addr.arpa" {
+ type primary;
+ file "192.168.254.rev";
+ notify no;
+ };
+ // zone file forwarded example.com
+ zone "example.com" {
+ type forward;
+ // this defines the addresses of the resolvers to
+ // which queries for this zone will be forwarded
+ forwarders {
+ 192.168.250.3;
+ 192.168.230.27;
+ };
+ // indicates all queries for this zone will be forwarded
+ forward only;
+ };
+
+
+The :ref:`zone<zone_clause>` and :ref:`acl<acl_grammar>` clauses, and the
+:ref:`allow-query<allow-query>`, :ref:`empty-zones-enable<empty-zones-enable>`,
+:ref:`file<file>`, :ref:`forward<forward>`, :ref:`forwarders<forwarders>`,
+:ref:`notify<notify_st>`, :ref:`recursion<recursion>`, and :ref:`type<type>`
+statements are described in detail in the appropriate sections.
+
+As a reminder, the configuration of this resolver does **not** access the DNS
+hierarchy (does not use the public network) for any recursive query for which:
+
+1. The answer is already in the cache.
+
+2. The domain name is **localhost** (zone localhost).
+
+3. Is a reverse-map query for 127.0.0.1 (zone 0.0.127.in-addr.arpa).
+
+4. Is a reverse-map query for 192.168.254/24 (zone 254.168.192.in-addr.arpa).
+
+5. Is a reverse-map query for any local IP (empty-zones-enable statement).
+
+6. Is a query for the domain name **example.com**, in which case it will be
+ forwarded to either 192.168.250.3 or 192.168.230.27 (zone example.com).
+
+All other recursive queries will result in access to the DNS hierarchy to
+resolve the query.
+
+.. _load_balancing:
+
+Load Balancing
+--------------
+
+A primitive form of load balancing can be achieved in the DNS by using multiple
+resource records (RRs) in a :ref:`zone file<zone_file>` (such as multiple A
+records) for one name.
+
+For example, assuming three HTTP servers with network addresses of
+10.0.0.1, 10.0.0.2, and 10.0.0.3, a set of records such as the following
+means that clients will connect to each machine one-third of the time:
+
++-----------+------+----------+----------+----------------------------+
+| Name | TTL | CLASS | TYPE | Resource Record (RR) Data |
++-----------+------+----------+----------+----------------------------+
+| www | 600 | IN | A | 10.0.0.1 |
++-----------+------+----------+----------+----------------------------+
+| | 600 | IN | A | 10.0.0.2 |
++-----------+------+----------+----------+----------------------------+
+| | 600 | IN | A | 10.0.0.3 |
++-----------+------+----------+----------+----------------------------+
+
+When a resolver queries for these records, BIND rotates them and
+responds to the query with the records in a random order. In the
+example above, clients randomly receive records in the order 1, 2,
+3; 2, 3, 1; and 3, 1, 2. Most clients use the first record returned
+and discard the rest.
+
+For more detail on ordering responses, refer to the
+:ref:`rrset-order<rrset_ordering>` statement in the
+:ref:`options<options_grammar>` clause.
+++ /dev/null
-.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
-..
-.. SPDX-License-Identifier: MPL-2.0
-..
-.. This Source Code Form is subject to the terms of the Mozilla Public
-.. License, v. 2.0. If a copy of the MPL was not distributed with this
-.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
-..
-.. See the COPYRIGHT file distributed with this work for additional
-.. information regarding copyright ownership.
-
-.. _configuration:
-
-Configurations and Zone Files
-=============================
-
-In this chapter we provide some suggested configurations, along with
-guidelines for their use. We suggest reasonable values for certain
-option settings.
-
-.. _sample_configuration:
-
-Sample Configurations
----------------------
-
-.. _cache_only_sample:
-
-A Caching-only Name Server
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following sample configuration is appropriate for a caching-only
-name server for use by clients internal to a corporation. All queries
-from outside clients are refused using the ``allow-query`` option.
-The same effect can be achieved using suitable firewall
-rules.
-
-::
-
- // Two corporate subnets we wish to allow queries from.
- acl corpnets { 192.168.4.0/24; 192.168.7.0/24; };
- options {
- allow-query { corpnets; };
- };
- // Provide a reverse mapping for the loopback
- // address 127.0.0.1
- zone "0.0.127.in-addr.arpa" {
- type primary;
- file "localhost.rev";
- notify no;
- };
-
-.. _auth_only_sample:
-
-An Authoritative-only Name Server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This sample configuration is for an authoritative-only server that is
-the primary server for ``example.com`` and a secondary server for the subdomain
-``eng.example.com``.
-
-::
-
- options {
- // Do not allow access to cache
- allow-query-cache { none; };
- // This is the default
- allow-query { any; };
- // Do not provide recursive service
- recursion no;
- };
-
- // Provide a reverse mapping for the loopback
- // address 127.0.0.1
- zone "0.0.127.in-addr.arpa" {
- type primary;
- file "localhost.rev";
- notify no;
- };
- // We are the primary server for example.com
- zone "example.com" {
- type primary;
- file "example.com.db";
- // IP addresses of secondary servers allowed to
- // transfer example.com
- allow-transfer {
- 192.168.4.14;
- 192.168.5.53;
- };
- };
- // We are a secondary server for eng.example.com
- zone "eng.example.com" {
- type secondary;
- file "eng.example.com.bk";
- // IP address of eng.example.com primary server
- primaries { 192.168.4.12; };
- };
-
-.. _load_balancing:
-
-Load Balancing
---------------
-
-A primitive form of load balancing can be achieved in the DNS by using
-multiple records (such as multiple A records) for one name.
-
-For example, assuming three HTTP servers with network addresses of
-10.0.0.1, 10.0.0.2, and 10.0.0.3, a set of records such as the following
-means that clients will connect to each machine one-third of the time:
-
-+-----------+------+----------+----------+----------------------------+
-| Name | TTL | CLASS | TYPE | Resource Record (RR) Data |
-+-----------+------+----------+----------+----------------------------+
-| www | 600 | IN | A | 10.0.0.1 |
-+-----------+------+----------+----------+----------------------------+
-| | 600 | IN | A | 10.0.0.2 |
-+-----------+------+----------+----------+----------------------------+
-| | 600 | IN | A | 10.0.0.3 |
-+-----------+------+----------+----------+----------------------------+
-
-When a resolver queries for these records, BIND rotates them and
-responds to the query with the records in a different order. In the
-example above, clients randomly receive records in the order 1, 2,
-3; 2, 3, 1; and 3, 1, 2. Most clients use the first record returned
-and discard the rest.
-
-For more detail on ordering responses, check the ``rrset-order``
-sub-statement in the ``options`` statement; see :ref:`rrset_ordering`.
-
projects / thirdparty / bind9.git / commitdiff
