Suggest unlocked iteration for mkey rollover

In database.rst when discussing the procedure for master key rollover,
suggest using unlocked iteration for large databases.  Also make it
clear that unavailability due to locking during iteration is specific
to DB2.

ticket: 8507 (new)
target_version: 1.14-next
tags: pullup

diff --git a/doc/admin/database.rst b/doc/admin/database.rst
index c7abc1b603a613c3547d8617719f7fd4c3da2986..078abc78c1d59d508e80c9c1f9640c7a354aa928 100644 (file)
--- a/doc/admin/database.rst
+++ b/doc/admin/database.rst
@@ -527,9 +527,13 @@ availability.  To roll over the master key, follow these steps:
 
 #. On the master KDC, run ``kdb5_util update_princ_encryption``.  This
    command will iterate over the database and re-encrypt all keys in
-   the new master key.  If the database is large, the master KDC will
-   become unavailable while this command runs, but clients should fail
-   over to slave KDCs (if any are present) during this time period.
+   the new master key.  If the database is large and uses DB2, the
+   master KDC will become unavailable while this command runs, but
+   clients should fail over to slave KDCs (if any are present) during
+   this time period.  In release 1.13 and later, you can instead run
+   ``kdb5_util -x unlockiter update_princ_encryption`` to use unlocked
+   iteration; this variant will take longer, but will keep the
+   database available to the KDC and kadmind while it runs.
 
 #. On the master KDC, run ``kdb5_util purge_mkeys`` to clean up the
    old master key.