Merge branch '2127-xml2rst-add-missing-updates' into 'main'

Resolve "Update ARM with lost changes since the conversion to RST files"

Closes #2127

See merge request isc-projects/bind9!4112

doc/arm/dnssec.rst

@@ -16,13 +16,15 @@ DNSSEC, Dynamic Zones, and Automatic Signing
 Converting From Insecure to Secure
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A zone can be changed from insecure to secure in two ways: using a
+A zone can be changed from insecure to secure in three ways: using a
-dynamic DNS update, or via the ``auto-dnssec`` zone option.
+dynamic DNS update, via the ``auto-dnssec`` zone option, or by setting a
+DNSSEC policy for the zone with ``dnssec-policy``.
 
-For either method, ``named`` must be configured so that it can see
+For any method, ``named`` must be configured so that it can see
 the ``K*`` files which contain the public and private parts of the keys
 that are used to sign the zone. These files are generated
-by ``dnssec-keygen``, and they should be placed in the
+by ``dnssec-keygen``, or created when needed by ``named`` if
+``dnssec-policy`` is used. Keys should be placed in the
 key-directory, as specified in ``named.conf``:
 
 ::
@@ -39,6 +41,18 @@ configuration causes all records in the zone to be signed with the
 ZSK, and the DNSKEY RRset to be signed with the KSK. An NSEC
 chain is generated as part of the initial signing process.
 
+With ``dnssec-policy``, it is possible to specify which keys should be
+KSK and/or ZSK. To sign all records with a key, a CSK must be specified.
+For example:
+
+::
+
+        dnssec-policy csk {
+	    keys {
+                csk lifetime unlimited algorithm 13;
+            };
+	};
+
 Dynamic DNS Update Method
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -83,9 +97,9 @@ other updates are possible as well.
 Fully Automatic Zone Signing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To enable automatic signing, add the ``auto-dnssec`` option to the zone
+To enable automatic signing, set a ``dnssec-policy`` or add the
-statement in ``named.conf``. ``auto-dnssec`` has two possible arguments:
+``auto-dnssec`` option to the zone statement in ``named.conf``.
-``allow`` or ``maintain``.
+``auto-dnssec`` has two possible arguments: ``allow`` or ``maintain``.
 
 With ``auto-dnssec allow``, ``named`` can search the key directory for
 keys matching the zone, insert them into the zone, and use them to sign
@@ -97,6 +111,11 @@ automatically adjusts the zone's DNSKEY records on a schedule according to
 the keys' timing metadata. (See :ref:`man_dnssec-keygen` and
 :ref:`man_dnssec-settime` for more information.)
 
+``dnssec-policy`` is similar to ``auto-dnssec maintain``, but
+``dnssec-policy`` also automatically creates new keys when necessary. In
+addition, any configuration related to DNSSEC signing is retrieved from the
+policy, ignoring existing DNSSEC ``named.conf`` options.
+
 ``named`` periodically searches the key directory for keys matching
 the zone; if the keys' metadata indicates that any change should be
 made to the zone - such as adding, removing, or revoking a key - then that
@@ -224,6 +243,8 @@ conversion is complete, the NSEC chain is removed and the
 NSEC3PARAM record has a zero flag field. The NSEC3 chain is
 generated before the NSEC chain is destroyed.
 
+NSEC3 is not yet supported with ``dnssec-policy``.
+
 Converting From NSEC3 to NSEC
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/arm/managed-keys.rst

@@ -22,7 +22,7 @@ Validating Resolver
 ~~~~~~~~~~~~~~~~~~~
 
 To configure a validating resolver to use :rfc:`5011` to maintain a trust
-anchor, configure the trust anchor using a ``dnssec-keys`` statement and
+anchor, configure the trust anchor using a ``trust-anchors`` statement and
 the ``initial-key`` keyword. Information about this can be found in
 :ref:`trust-anchors`.
 

doc/arm/reference.rst

@@ -1533,8 +1533,10 @@ default is used.
    If ``full``, the server collects statistical data on all zones,
    unless specifically turned off on a per-zone basis by specifying
    ``zone-statistics terse`` or ``zone-statistics none`` in the ``zone``
-   statement. The default is ``terse``, providing minimal statistics on
+   statement. The statistical data includes, for example, DNSSEC signing
-   zones (including name and current serial number, but not query type
+   operations and the number of authoritative answers per query type. The
+   default is ``terse``, providing minimal statistics on zones
+   (including name and current serial number, but not query type
    counters).
 
    These statistics may be accessed via the ``statistics-channel`` or
@@ -1885,7 +1887,7 @@ Boolean Options
 ``trust-anchor-telemetry``
    This causes ``named`` to send specially formed queries once per day to
    domains for which trust anchors have been configured via, e.g.,
-   ``dnssec-keys`` or ``dnssec-validation auto``.
+   ``trust-anchors`` or ``dnssec-validation auto``.
 
    The query name used for these queries has the form
    ``_ta-xxxx(-xxxx)(...).<domain>``, where each "xxxx" is a group of four
@@ -4654,7 +4656,7 @@ not used to validate answers; it is superseded by the key or keys stored
 in the managed-keys database.
 
 The next time ``named`` runs after an ``initial-key`` or ``initial-ds`` has been *removed*
-from the ``dnssec-keys`` statement (or changed to a ``static-key`` or ``static-ds``), the
+from the ``trust-anchors`` statement (or changed to a ``static-key`` or ``static-ds``), the
 corresponding zone is removed from the managed-keys database, and
 :rfc:`5011` key maintenance is no longer used for that domain.