From: Daniel Salzman <daniel.salzman@nic.cz>
Date: Thu, 29 Jul 2021 20:14:41 +0000 (+0200)
Subject: doc: extend shared-ksk limitations
X-Git-Tag: v3.1.0~4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a987b98d782c49811cb48684f5cb0c663c86a23f;p=thirdparty%2Fknot-dns.git

doc: extend shared-ksk limitations
---

diff --git a/doc/configuration.rst b/doc/configuration.rst
index 2065b68f0c..8f0c2e434d 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -433,9 +433,10 @@ convenience delay the submission is started. The server publishes CDS and CDNSKE
 and the user shall propagate them to the parent. The server periodically checks for
 DS at the parent zone and when positive, finishes the rollover.
 
-To share KSKs among zones, set the ksk-shared policy parameter. It is strongly discouraged to
-change the policy ``id`` afterwards! The shared key's creation timestamp will be equal for all
-zones, but other timers (e.g. activate, retire) may get out of sync. ::
+To share KSKs among zones, set the :ref:`policy_ksk-shared` policy parameter. Please note
+that changing the policy ``id`` afterwards can have unexpected conseqences!
+The shared key's creation timestamp will be equal for all zones, but other timers
+(e.g. activate, retire) may get out of sync. ::
 
   policy:
     - id: shared
diff --git a/doc/man/knot.conf.5in b/doc/man/knot.conf.5in
index baf717dc58..8a2bbff618 100644
--- a/doc/man/knot.conf.5in
+++ b/doc/man/knot.conf.5in
@@ -1316,12 +1316,15 @@ A length of newly generated ZSK keys.
 \fIDefault:\fP see default for \fI\%ksk\-size\fP
 .SS ksk\-shared
 .sp
-If enabled, all zones with this policy assigned will share one KSK.
+If enabled, all zones with this policy assigned will share one or more KSKs.
+More KSKs can be shared during a KSK rollover.
 .sp
 \fBWARNING:\fP
 .INDENT 0.0
 .INDENT 3.5
-It is discouraged to modify policy \fI\%id\fP when shared KSK is enabled.
+As the shared KSK set is bound to the policy \fI\%id\fP, renaming the
+policy breaks this connection and new shared KSK set is initiated when
+a new KSK is needed.
 .UNINDENT
 .UNINDENT
 .sp
diff --git a/doc/operation.rst b/doc/operation.rst
index 62d1ab10cf..9fa47c37b4 100644
--- a/doc/operation.rst
+++ b/doc/operation.rst
@@ -707,8 +707,8 @@ If we have zones which already have their keys, turning on the shared KSK featur
 But when a KSK rollover takes place, they will use the same new key afterwards.
 
 .. WARNING::
-   It is discouraged to modify policy :ref:`id<policy_id>` when :ref:`shared KSK<policy_ksk-shared>`
-   is enabled.
+   Changing the policy :ref:`id<policy_id>` must be done carefully if shared
+   KSK is in use.
 
 .. _DNSSEC Delete algorithm:
 
diff --git a/doc/reference.rst b/doc/reference.rst
index 75d2314b9e..435ac90122 100644
--- a/doc/reference.rst
+++ b/doc/reference.rst
@@ -1421,10 +1421,13 @@ A length of newly generated :abbr:`ZSK (Zone Signing Key)` keys.
 ksk-shared
 ----------
 
-If enabled, all zones with this policy assigned will share one KSK.
+If enabled, all zones with this policy assigned will share one or more KSKs.
+More KSKs can be shared during a KSK rollover.
 
 .. WARNING::
-   It is discouraged to modify policy :ref:`id<policy_id>` when shared KSK is enabled.
+   As the shared KSK set is bound to the policy :ref:`id<policy_id>`, renaming the
+   policy breaks this connection and new shared KSK set is initiated when
+   a new KSK is needed.
 
 *Default:* off