doc: extend shared-ksk limitations

diff --git a/doc/configuration.rst b/doc/configuration.rst
index 2065b68f0c3686d3a8ac7694d543de70dc5a40ef..8f0c2e434de74938178a362b4fd2e4744c1a5cd9 100644 (file)
--- 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 baf717dc582fbb43aeb726bd50e1baf7588f3c08..8a2bbff618bb931962d9b447e63fbdc42be7cc64 100644 (file)
--- 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 62d1ab10cf5bc7fab2eef179fb6eec62af85a787..9fa47c37b4440be3fc7dca722a5f4249de120c5b 100644 (file)
--- 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 75d2314b9e7407fdf74f929b1fd5df454df165fe..435ac901227754538ab49e223315f5af30796671 100644 (file)
--- 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