From d842adb23f018f862dfd296d141a330df2367dc9 Mon Sep 17 00:00:00 2001 From: Matthijs Mekking Date: Wed, 8 Mar 2023 15:14:11 +0100 Subject: [PATCH] Update documenation for 'checkds' option Add text about the 'checkds' option in the ARM reference and DNSSEC guide. --- doc/arm/dnssec.inc.rst | 5 ++++- doc/arm/reference.rst | 14 ++++++++++++++ doc/dnssec-guide/signing.rst | 8 ++++++++ 3 files changed, 26 insertions(+), 1 deletion(-) diff --git a/doc/arm/dnssec.inc.rst b/doc/arm/dnssec.inc.rst index 6f96cb5aff..5477ebb45b 100644 --- a/doc/arm/dnssec.inc.rst +++ b/doc/arm/dnssec.inc.rst @@ -176,11 +176,14 @@ by configuring parental agents: dnssec-policy default; inline-signing yes; parental-agents { 192.0.2.1; }; + checkds explicit; }; Here one server, ``192.0.2.1``, is configured for BIND to send DS queries to, to check the DS RRset for ``dnssec-example`` during key rollovers. This needs -to be a trusted server, because BIND does not validate the response. +to be a trusted server, because BIND does not validate the response. The +``checkds`` option makes BIND use the explicitly configured parental agents, +rather than looking them up by querying for the parent NS records. If setting up a parental agent is undesirable, it is also possible to tell BIND that the DS is published in the parent with: diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 84cacb4c94..22df16551b 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -6433,6 +6433,20 @@ old DNSSEC key. The following options apply to DS queries sent to :any:`parental-agents`: +.. namedconf:statement:: checkds + :tags: dnssec + :short: Controls whether ``DS`` queries are sent to parental agents. + + If set to ``yes``, DS queries are sent when a KSK rollover is in progress. + The queries are sent to the servers listed in the parent zone's NS records. + + If set to ``explicit``, DS queries are sent only to servers explicitly listed + using :any:`parental-agents`. This is the default. + + If set to ``no``, no DS queries are sent. Users should manually run + :option:`rndc dnssec -checkds ` with the appropriate parameters + to signal that specific DS records are published and/or withdrawn. + .. namedconf:statement:: parental-source :tags: dnssec :short: Specifies which local IPv4 source address is used to send parental DS queries. diff --git a/doc/dnssec-guide/signing.rst b/doc/dnssec-guide/signing.rst index 7ed5b824af..2d5045b27d 100644 --- a/doc/dnssec-guide/signing.rst +++ b/doc/dnssec-guide/signing.rst @@ -919,6 +919,7 @@ presence. Let's look at the following configuration excerpt: dnssec-policy standard; inline-signing yes; parental-agents { "net"; }; + checkds explicit; ... }; @@ -932,6 +933,11 @@ 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. +The example also has :any:`checkds` set to `explicit`. This means that only +the addresses defined in :any:`parental-agents` are being queried. If set to +`yes`, the parental agents are being looked up by querying for the parent NS +records. + Alternatively, you can use the :iscman:`rndc` tool to tell :iscman:`named` that the DS record has been published or withdrawn. For example: @@ -939,6 +945,8 @@ record has been published or withdrawn. For example: # rndc dnssec -checkds published example.net +This command should also be used when :any:`checkds` is set to `no`. + If your parent zone doesn't support CDS/CDNSKEY, you will have to supply the DNSKEY or DS record to the parent zone manually when a new KSK appears in your zone, presumably using the same mechanism you used to upload the