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

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

1 files changed, 320 insertions, 0 deletions

diff --git a/doc/arm/configuration.rst b/doc/arm/configuration.rst
new file mode 100644
index 0000000..0b8d8ec
--- /dev/null
+++ b/doc/arm/configuration.rst
@@ -0,0 +1,320 @@
+.. 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:
+
+Name Server Configuration
+=========================
+
+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 {
+        // Working directory
+        directory "/etc/namedb";
+
+        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 {
+        // Working directory
+        directory "/etc/namedb";
+        // 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
+        masters { 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`.
+
+.. _ns_operations:
+
+Name Server Operations
+----------------------
+
+.. _tools:
+
+Tools for Use With the Name Server Daemon
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section describes several indispensable diagnostic, administrative, 
+and monitoring tools available to the system administrator for
+controlling and debugging the name server daemon.
+
+.. _diagnostic_tools:
+
+Diagnostic Tools
+^^^^^^^^^^^^^^^^
+
+The ``dig``, ``host``, and ``nslookup`` programs are all command-line
+tools for manually querying name servers. They differ in style and
+output format.
+
+``dig``
+   ``dig`` is the most versatile and complete of these lookup tools. It
+   has two modes: simple interactive mode for a single query, and batch
+   mode, which executes a query for each in a list of several query
+   lines. All query options are accessible from the command line.
+
+   For more information and a list of available commands and options,
+   see :ref:`man_dig`.
+
+``host``
+   The ``host`` utility emphasizes simplicity and ease of use. By
+   default, it converts between host names and Internet addresses, but
+   its functionality can be extended with the use of options.
+
+   For more information and a list of available commands and options,
+   see :ref:`man_host`.
+
+``nslookup``
+   ``nslookup`` has two modes: interactive and non-interactive.
+   Interactive mode allows the user to query name servers for
+   information about various hosts and domains, or to print a list of
+   hosts in a domain. Non-interactive mode is used to print just the
+   name and requested information for a host or domain.
+
+   Due to its arcane user interface and frequently inconsistent
+   behavior, we do not recommend the use of ``nslookup``. Use ``dig``
+   instead.
+
+.. _admin_tools:
+
+Administrative Tools
+^^^^^^^^^^^^^^^^^^^^
+
+Administrative tools play an integral part in the management of a
+server.
+
+``named-checkconf``
+   The ``named-checkconf`` program checks the syntax of a ``named.conf``
+   file.
+
+   For more information and a list of available commands and options,
+   see :ref:`man_named-checkconf`.
+
+``named-checkzone``
+   The ``named-checkzone`` program checks a zone file for syntax and
+   consistency.
+
+   For more information and a list of available commands and options,
+   see :ref:`man_named-checkzone`.
+
+``named-compilezone``
+   This tool is similar to ``named-checkzone`` but it always dumps the zone content
+   to a specified file (typically in a different format).
+
+   For more information and a list of available commands and options,
+   see :ref:`man_named-compilezone`.
+
+``rndc``
+   The remote name daemon control (``rndc``) program allows the system
+   administrator to control the operation of a name server.
+
+   See :ref:`man_rndc` for details of the available ``rndc``
+   commands.
+
+   ``rndc`` requires a configuration file, since all communication with
+   the server is authenticated with digital signatures that rely on a
+   shared secret, and there is no way to provide that secret other than
+   with a configuration file. The default location for the ``rndc``
+   configuration file is ``/etc/rndc.conf``, but an alternate location
+   can be specified with the ``-c`` option. If the configuration file is
+   not found, ``rndc`` also looks in ``/etc/rndc.key`` (or whatever
+   ``sysconfdir`` was defined when the BIND build was configured). The
+   ``rndc.key`` file is generated by running ``rndc-confgen -a`` as
+   described in :ref:`controls_statement_definition_and_usage`.
+
+   The format of the configuration file is similar to that of
+   ``named.conf``, but is limited to only four statements: the ``options``,
+   ``key``, ``server``, and ``include`` statements. These statements are
+   what associate the secret keys to the servers with which they are
+   meant to be shared. The order of statements is not significant.
+
+   The ``options`` statement has three clauses: ``default-server``,
+   ``default-key``, and ``default-port``. ``default-server`` takes a
+   host name or address argument and represents the server that is
+   contacted if no ``-s`` option is provided on the command line.
+   ``default-key`` takes the name of a key as its argument, as defined
+   by a ``key`` statement. ``default-port`` specifies the port to which
+   ``rndc`` should connect if no port is given on the command line or in
+   a ``server`` statement.
+
+   The ``key`` statement defines a key to be used by ``rndc`` when
+   authenticating with ``named``. Its syntax is identical to the ``key``
+   statement in ``named.conf``. The keyword ``key`` is followed by a key
+   name, which must be a valid domain name, though it need not actually
+   be hierarchical; thus, a string like ``rndc_key`` is a valid name.
+   The ``key`` statement has two clauses: ``algorithm`` and ``secret``.
+   While the configuration parser accepts any string as the argument
+   to ``algorithm``, currently only the strings ``hmac-md5``,
+   ``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``,
+   ``hmac-sha384``, and ``hmac-sha512`` have any meaning. The secret
+   is a Base64-encoded string as specified in :rfc:`3548`.
+
+   The ``server`` statement associates a key defined using the ``key``
+   statement with a server. The keyword ``server`` is followed by a host
+   name or address. The ``server`` statement has two clauses: ``key``
+   and ``port``. The ``key`` clause specifies the name of the key to be
+   used when communicating with this server, and the ``port`` clause can
+   be used to specify the port ``rndc`` should connect to on the server.
+
+   A sample minimal configuration file is as follows:
+
+   ::
+
+      key rndc_key {
+           algorithm "hmac-sha256";
+           secret
+             "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW4gYnV0IG1hZGUgZm9yIGEgd29tYW4K";
+      };
+      options {
+           default-server 127.0.0.1;
+           default-key    rndc_key;
+      };
+
+   This file, if installed as ``/etc/rndc.conf``, allows the
+   command:
+
+   ``$ rndc reload``
+
+   to connect to 127.0.0.1 port 953 and causes the name server to reload,
+   if a name server on the local machine is running with the following
+   controls statements:
+
+   ::
+
+      controls {
+          inet 127.0.0.1
+              allow { localhost; } keys { rndc_key; };
+      };
+
+   and it has an identical key statement for ``rndc_key``.
+
+   Running the ``rndc-confgen`` program conveniently creates an
+   ``rndc.conf`` file, and also displays the corresponding
+   ``controls`` statement needed to add to ``named.conf``.
+   Alternatively, it is possible to run ``rndc-confgen -a`` to set up an
+   ``rndc.key`` file and not modify ``named.conf`` at all.
+
+Signals
+~~~~~~~
+
+Certain Unix signals cause the name server to take specific actions, as
+described in the following table. These signals can be sent using the
+``kill`` command.
+
++--------------+-------------------------------------------------------+
+| ``SIGHUP``   | Causes the server to read ``named.conf`` and reload   |
+|              | the database.                                         |
++--------------+-------------------------------------------------------+
+| ``SIGTERM``  | Causes the server to clean up and exit.               |
++--------------+-------------------------------------------------------+
+| ``SIGINT``   | Causes the server to clean up and exit.               |
++--------------+-------------------------------------------------------+
+
+.. include:: plugins.rst