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, 241 insertions, 0 deletions

diff --git a/doc/arm/catz.rst b/doc/arm/catz.rst
new file mode 100644
index 0000000..177a562
--- /dev/null
+++ b/doc/arm/catz.rst
@@ -0,0 +1,241 @@
+.. 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.
+
+.. _catz-info:
+
+Catalog Zones
+-------------
+
+A "catalog zone" is a special DNS zone that contains a list of other
+zones to be served, along with their configuration parameters. Zones
+listed in a catalog zone are called "member zones." When a catalog zone
+is loaded or transferred to a secondary server which supports this
+functionality, the secondary server creates the member zones
+automatically. When the catalog zone is updated (for example, to add or
+delete member zones, or change their configuration parameters), those
+changes are immediately put into effect. Because the catalog zone is a
+normal DNS zone, these configuration changes can be propagated using the
+standard AXFR/IXFR zone transfer mechanism.
+
+Catalog zones' format and behavior are specified as an Internet draft
+for interoperability among DNS implementations. The
+latest revision of the DNS catalog zones draft can be found here:
+https://datatracker.ietf.org/doc/draft-toorop-dnsop-dns-catalog-zones/ .
+
+Principle of Operation
+~~~~~~~~~~~~~~~~~~~~~~
+
+Normally, if a zone is to be served by a secondary server, the
+``named.conf`` file on the server must list the zone, or the zone must
+be added using ``rndc addzone``. In environments with a large number of
+secondary servers, and/or where the zones being served are changing
+frequently, the overhead involved in maintaining consistent zone
+configuration on all the secondary servers can be significant.
+
+A catalog zone is a way to ease this administrative burden: it is a DNS
+zone that lists member zones that should be served by secondary servers.
+When a secondary server receives an update to the catalog zone, it adds,
+removes, or reconfigures member zones based on the data received.
+
+To use a catalog zone, it must first be set up as a normal zone on both the
+primary and secondary servers that are configured to use it. It
+must also be added to a ``catalog-zones`` list in the ``options`` or
+``view`` statement in ``named.conf``. This is comparable to the way a
+policy zone is configured as a normal zone and also listed in a
+``response-policy`` statement.
+
+To use the catalog zone feature to serve a new member zone:
+
+-  Set up the member zone to be served on the primary as normal. This
+   can be done by editing ``named.conf`` or by running
+   ``rndc addzone``.
+
+-  Add an entry to the catalog zone for the new member zone. This can
+   be done by editing the catalog zone's zone file and running
+   ``rndc reload``, or by updating the zone using ``nsupdate``.
+
+The change to the catalog zone is propagated from the primary to all
+secondaries using the normal AXFR/IXFR mechanism. When the secondary receives the
+update to the catalog zone, it detects the entry for the new member
+zone, creates an instance of that zone on the secondary server, and points
+that instance to the ``masters`` specified in the catalog zone data. The
+newly created member zone is a normal secondary zone, so BIND
+immediately initiates a transfer of zone contents from the primary. Once
+complete, the secondary starts serving the member zone.
+
+Removing a member zone from a secondary server requires only
+deleting the member zone's entry in the catalog zone; the change to the
+catalog zone is propagated to the secondary server using the normal
+AXFR/IXFR transfer mechanism. The secondary server, on processing the
+update, notices that the member zone has been removed, stops
+serving the zone, and removes it from its list of configured zones.
+However, removing the member zone from the primary server must be done
+by editing the configuration file or running
+``rndc delzone``.
+
+Configuring Catalog Zones
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Catalog zones are configured with a ``catalog-zones`` statement in the
+``options`` or ``view`` section of ``named.conf``. For example:
+
+::
+
+   catalog-zones {
+       zone "catalog.example"
+            default-masters { 10.53.0.1; }
+            in-memory no
+            zone-directory "catzones"
+            min-update-interval 10;
+   };
+
+This statement specifies that the zone ``catalog.example`` is a catalog
+zone. This zone must be properly configured in the same view. In most
+configurations, it would be a secondary zone.
+
+The options following the zone name are not required, and may be
+specified in any order.
+
+``default-masters``
+   This option defines the default primaries for member
+   zones listed in a catalog zone, and can be overridden by options within
+   a catalog zone. If no such options are included, then member zones
+   transfer their contents from the servers listed in this option.
+
+``in-memory``
+   This option, if set to ``yes``, causes member zones to be
+   stored only in memory. This is functionally equivalent to configuring a
+   secondary zone without a ``file`` option. The default is ``no``; member
+   zones' content is stored locally in a file whose name is
+   automatically generated from the view name, catalog zone name, and
+   member zone name.
+
+``zone-directory``
+   This option causes local copies of member zones' zone files to be
+   stored in the specified directory, if ``in-memory`` is not set to
+   ``yes``. The default is to store zone files in the server's working
+   directory. A non-absolute pathname in ``zone-directory`` is assumed
+   to be relative to the working directory.
+
+``min-update-interval``
+   This option sets the minimum interval between updates to catalog
+   zones, in seconds. If an update to a catalog zone (for example, via
+   IXFR) happens less than ``min-update-interval`` seconds after the
+   most recent update, the changes are not carried out until this
+   interval has elapsed. The default is 5 seconds.
+
+Catalog zones are defined on a per-view basis. Configuring a non-empty
+``catalog-zones`` statement in a view automatically turns on
+``allow-new-zones`` for that view. This means that ``rndc addzone``
+and ``rndc delzone`` also work in any view that supports catalog
+zones.
+
+Catalog Zone Format
+~~~~~~~~~~~~~~~~~~~
+
+A catalog zone is a regular DNS zone; therefore, it must have a single
+``SOA`` and at least one ``NS`` record.
+
+A record stating the version of the catalog zone format is also
+required. If the version number listed is not supported by the server,
+then a catalog zone may not be used by that server.
+
+::
+
+   catalog.example.    IN SOA . . 2016022901 900 600 86400 1
+   catalog.example.    IN NS nsexample.
+   version.catalog.example.    IN TXT "1"
+
+Note that this record must have the domain name
+``version.catalog-zone-name``. The data
+stored in a catalog zone is indicated by the domain name label
+immediately before the catalog zone domain.
+
+Catalog zone options can be set either globally for the whole catalog
+zone or for a single member zone. Global options override the settings
+in the configuration file, and member zone options override global
+options.
+
+Global options are set at the apex of the catalog zone, e.g.:
+
+::
+
+    masters.catalog.example.    IN AAAA 2001:db8::1
+
+BIND currently supports the following options:
+
+-  A simple ``masters`` definition:
+
+   ::
+
+           masters.catalog.example.    IN A 192.0.2.1
+
+
+   This option defines a primary server for the member zones, which can be
+   either an A or AAAA record. If multiple primaries are set, the order in
+   which they are used is random.
+
+-  A ``masters`` with a TSIG key defined:
+
+   ::
+
+               label.masters.catalog.example.     IN A 192.0.2.2
+               label.masters.catalog.example.     IN TXT "tsig_key_name"
+
+
+   This option defines a primary server for the member zone with a TSIG
+   key set. The TSIG key must be configured in the configuration file.
+   ``label`` can be any valid DNS label.
+
+-  ``allow-query`` and ``allow-transfer`` ACLs:
+
+   ::
+
+               allow-query.catalog.example.   IN APL 1:10.0.0.1/24
+               allow-transfer.catalog.example.    IN APL !1:10.0.0.1/32 1:10.0.0.0/24
+
+
+   These options are the equivalents of ``allow-query`` and
+   ``allow-transfer`` in a zone declaration in the ``named.conf``
+   configuration file. The ACL is processed in order; if there is no
+   match to any rule, the default policy is to deny access. For the
+   syntax of the APL RR, see :rfc:`3123`.
+
+A member zone is added by including a ``PTR`` resource record in the
+``zones`` sub-domain of the catalog zone. The record label is a
+``SHA-1`` hash of the member zone name in wire format. The target of the
+PTR record is the member zone name. For example, to add the member zone
+``domain.example``:
+
+::
+
+   5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN PTR domain.example.
+
+The hash is necessary to identify options for a specific member zone.
+The member zone-specific options are defined the same way as global
+options, but in the member zone subdomain:
+
+::
+
+   masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN A 192.0.2.2
+   label.masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN AAAA 2001:db8::2
+   label.masters.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN TXT "tsig_key"
+   allow-query.5960775ba382e7a4e09263fc06e7c00569b6a05c.zones.catalog.example. IN APL 1:10.0.0.0/24
+
+Options defined for a specific zone override the
+global options defined in the catalog zone. These in turn override the
+global options defined in the ``catalog-zones`` statement in the
+configuration file.
+
+Note that none of the global records for an option are inherited if any
+records are defined for that option for the specific zone. For example,
+if the zone had a ``masters`` record of type A but not AAAA, it
+would *not* inherit the type AAAA record from the global option.