Update documentation

Update ARM and DNSSEC guide with the new checkds feature.

diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst
index da6d3d602078362a29d07b7887fd2497ec649029..0f14eeb17eeac054a51acb4f91cdf59fc25ce1e3 100644 (file)
--- a/doc/arm/reference.rst
+++ b/doc/arm/reference.rst
@@ -861,6 +861,8 @@ responses such as NXDOMAIN.
 
 ``parental-agents`` lists allow for a common set of parental agents to be easily
 used by multiple primary and secondary zones in their ``parental-agents`` lists.
+A parental agent is the entity that the zone has a relationship with to
+change its delegation information (defined in :rfc:`7344`).
 
 .. _primaries_grammar:
 
@@ -5143,8 +5145,14 @@ BIND has mechanisms in place to facilitate automated KSK rollovers. It
 publishes CDS and CDNSKEY records that can be used by the parent zone to
 publish or withdraw the zone's DS records. BIND will query the parental
 agents to see if the new DS is actually published before withdrawing the
-old DNSSEC key. The following options apply to DS queries sent to
-``parental-agents``:
+old DNSSEC key.
+
+   .. note::
+      The DS response is not validated so it is recommended to set up a
+      trust relationship with the parental agent. For example, use TSIG to
+      authenticate the parental agent, or point to a validating resolver.
+
+The following options apply to DS queries sent to ``parental-agents``:
 
 ``parental-source``
    ``parental-source`` determines which local source address, and

diff --git a/doc/dnssec-guide/recipes.rst b/doc/dnssec-guide/recipes.rst
index 6fc52e06c06d715b52bd89c90b179163d34f002c..91d14be07fdede476b555b866356587303b1225b 100644 (file)
--- a/doc/dnssec-guide/recipes.rst
+++ b/doc/dnssec-guide/recipes.rst
@@ -1103,7 +1103,9 @@ unsigned.
 When the DS records have been removed from the parent zone, use
 ``rndc dnssec -checkds -key <id> withdrawn example.com`` to tell ``named`` that
 the DS is removed, and the remaining DNSSEC records will be removed in a timely
-manner.
+manner. Or if you have parental agents configured, the DNSSEC records will be
+automatically removed after BIND has seen that the parental agents no longer
+serves the DS RRset for this zone.
 
 After a while, your zone is reverted back to the traditional, insecure DNS
 format. You can verify by checking that all DNSKEY and RRSIG records have been

diff --git a/doc/dnssec-guide/signing.rst b/doc/dnssec-guide/signing.rst
index 616983474d98283b406e38dff1e8199678cc3a81..f9f65deaade23b5731350bb0417dff9ec506915b 100644 (file)
--- a/doc/dnssec-guide/signing.rst
+++ b/doc/dnssec-guide/signing.rst
@@ -888,11 +888,36 @@ you may not even have to do that [#]_.
 When the time approaches for the roll of a KSK or CSK, BIND adds a
 CDS and a CDNSKEY record for the key in question to the apex of the
 zone. If your parent zone supports polling for CDS/CDNSKEY records, they
-are uploaded and the DS record published in the parent - at least ideally. At
-the time of this writing (mid-2020) BIND does not check for the presence of a
-DS record in the parent zone before completing the KSK or CSK rollover
-and withdrawing the old key. Instead, you need to use the ``rndc`` tool
-to tell ``named`` that the DS record has been published. For example:
+are uploaded and the DS record published in the parent - at least ideally.
+
+If BIND is configured with ``parental-agents``, it will check for the DS
+presence. Let's look at the following configuration excerpt:
+
+::
+
+   parental-agents {
+       10.53.0.11, 10.53.0.12;
+   };
+
+   zone "example.net" in {
+       ...
+       dnssec-policy standard;
+       parental-agents { "net"; };
+       ...
+   };
+
+BIND will check for the presence of the DS record in the parent zone by querying
+its parental agents (defined in :rfc:`7344` to be the entities that the child
+zone has a relationship with to change its delegation information). In the
+example above, The zone `example.net` is configured with two parental agents,
+at the addresses 10.53.0.11 and 10.53.0.12. These addresses are used as an
+example only. Both addresses will have to respond with a DS RRset that
+includes the DS record identifying the key that is being rolled. If one or
+both don't have the DS included yet the rollover is paused, and the check for
+DS presence is retried after an hour. The same applies for DS withdrawal.
+
+Alternatively, you can use the ``rndc`` tool to tell ``named`` that the DS
+record has been published or withdrawn. For example:
 
 ::