Adding upstream version 1:9.18.19.upstream/1%9.18.19upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 566 insertions, 0 deletions

diff --git a/doc/arm/config-resolve.inc.rst b/doc/arm/config-resolve.inc.rst
new file mode 100644
index 0000000..fcfa97e
--- /dev/null
+++ b/doc/arm/config-resolve.inc.rst
@@ -0,0 +1,566 @@
+.. 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 blocks 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 :any:`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<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
+:any:`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::
+
+	; 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
+
+        // 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 :any:`zone` and :any:`acl` blocks, and the
+:any:`allow-query`, :any:`empty-zones-enable`,
+:any:`file`, :namedconf:ref:`notify`, :any:`recursion`, and
+:any:`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 (:any:`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
+
+        // 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 :any:`zone` and :any:`acl` blocks, and the
+:any:`allow-query`, :any:`empty-zones-enable`,
+:any:`file`, :any:`forward`, :any:`forwarders`,
+:namedconf:ref:`notify`, :any:`recursion`, and :any:`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 (:any:`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
+
+        // 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 :any:`zone` and :any:`acl` blocks, and the
+:any:`allow-query`, :any:`empty-zones-enable`,
+:any:`file`, :any:`forward`, :any:`forwarders`,
+:namedconf:ref:`notify`, :any:`recursion`, and :any:`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
+:namedconf:ref:`options` block.