diff --git a/doc/arm/Makefile.am b/doc/arm/Makefile.am index f22b365717..972af604e9 100644 --- a/doc/arm/Makefile.am +++ b/doc/arm/Makefile.am @@ -14,7 +14,9 @@ EXTRA_DIST = \ 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 \ @@ -43,11 +45,15 @@ EXTRA_DIST = \ 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 \ diff --git a/doc/arm/chapter3.rst b/doc/arm/chapter3.rst index a9d263f609..509dc489e6 100644 --- a/doc/arm/chapter3.rst +++ b/doc/arm/chapter3.rst @@ -9,5 +9,9 @@ .. 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 diff --git a/doc/arm/config-auth.inc.rst b/doc/arm/config-auth.inc.rst new file mode 100644 index 0000000000..6c4272efd0 --- /dev/null +++ b/doc/arm/config-auth.inc.rst @@ -0,0 +1,272 @@ +.. 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` 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 ` 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` 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` 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` clause, and :ref:`allow-query`, +:ref:`allow-query-cache`, +:ref:`allow-transfer`, :ref:`file`, +:ref:`notify`, :ref:`recursion`, and :ref:`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`. 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` clause, and :ref:`allow-query`, +:ref:`allow-query-cache`, +:ref:`allow-transfer`, :ref:`file`, +:ref:`notify`, :ref:`primaries`, +:ref:`recursion`, and :ref:`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;` in the + :ref:`zone` clause for the secondary causes :iscman:`named` to + only send NOTIFY messages for primary zones that it loads. diff --git a/doc/arm/config-intro.inc.rst b/doc/arm/config-intro.inc.rst new file mode 100644 index 0000000000..7598c6571e --- /dev/null +++ b/doc/arm/config-intro.inc.rst @@ -0,0 +1,208 @@ +.. 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` 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` and :ref:`options` clauses +and :ref:`category`, :ref:`channel`, +:ref:`directory`, :ref:`file`, and :ref:`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) +`, 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` 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. diff --git a/doc/arm/config-resolve.inc.rst b/doc/arm/config-resolve.inc.rst new file mode 100644 index 0000000000..ab05742bac --- /dev/null +++ b/doc/arm/config-resolve.inc.rst @@ -0,0 +1,570 @@ +.. 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 ` and provide +complete answers; that is, they issue one or more :ref:`iterative queries +` 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`. 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` (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` (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`. + +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`. 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;` 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` 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` or using the +:ref:`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`, 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` 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` and :ref:`acl` clauses, and the +:ref:`allow-query`, :ref:`empty-zones-enable`, +:ref:`file`, :ref:`notify`, :ref:`recursion`, and +:ref:`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`. + +.. 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` and :ref:`acl` clauses, and the +:ref:`allow-query`, :ref:`empty-zones-enable`, +:ref:`file`, :ref:`forward`, :ref:`forwarders`, +:ref:`notify`, :ref:`recursion`, and :ref:`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` and :ref:`acl` clauses, and the +:ref:`allow-query`, :ref:`empty-zones-enable`, +:ref:`file`, :ref:`forward`, :ref:`forwarders`, +:ref:`notify`, :ref:`recursion`, and :ref:`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` (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` statement in the +:ref:`options` clause. diff --git a/doc/arm/configuration.inc.rst b/doc/arm/configuration.inc.rst deleted file mode 100644 index 2c6684737a..0000000000 --- a/doc/arm/configuration.inc.rst +++ /dev/null @@ -1,128 +0,0 @@ -.. 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`. - diff --git a/doc/arm/primary-secondary.dia b/doc/arm/primary-secondary.dia new file mode 100644 index 0000000000..795625a2d8 Binary files /dev/null and b/doc/arm/primary-secondary.dia differ diff --git a/doc/arm/primary-secondary.png b/doc/arm/primary-secondary.png new file mode 100644 index 0000000000..573cb0f182 Binary files /dev/null and b/doc/arm/primary-secondary.png differ diff --git a/doc/arm/resolver-forward.dia b/doc/arm/resolver-forward.dia new file mode 100644 index 0000000000..9faf84e243 Binary files /dev/null and b/doc/arm/resolver-forward.dia differ diff --git a/doc/arm/resolver-forward.png b/doc/arm/resolver-forward.png new file mode 100644 index 0000000000..188e834a3e Binary files /dev/null and b/doc/arm/resolver-forward.png differ