Add a kdb5_util examples for old KDC upgrades

It's a slightly less-contrived use case of the utility than the
other example, which reads more like a usage statement.
Give a motivating sentence before each example, and note that this
new example is not needed in the general upgrade case.

The need to dump/load for upgrades prior to 1.2 was documented in
the texinfo install guide, but not in any RST sources until now.

ticket: 7407

diff --git a/doc/rst_source/krb_admins/database.rst b/doc/rst_source/krb_admins/database.rst
index afea97588666ee5f75c9c5e2c7a7829962d8c540..2671e0e3f83177802b15216adf79328ff212c233 100644 (file)
--- a/doc/rst_source/krb_admins/database.rst
+++ b/doc/rst_source/krb_admins/database.rst
@@ -370,6 +370,8 @@ To restore a Kerberos database dump from a file, use the
 Examples
 ########
 
+To load a single principal, either replacing or updating the database:
+
 ::
 
      shell% kdb5_util load dumpfile principal
@@ -382,6 +384,24 @@ Examples
 .. note:: If the database file exists, and the *-update* flag was not
           given, *kdb5_util* will overwrite the existing database.
 
+Using kdb5_util to upgrade a master KDC from krb5 1.1.x:
+
+::
+
+    shell% kdb5_util dump old-kdb-dump
+    shell% kdb5_util dump -ov old-kdb-dump.ov
+      [Create a new KDC installation, using the old stash file/master password]
+    shell% kdb5_util load old-kdb-dump
+    shell% kdb5_util load -update old-kdb-dump.ov
+
+The use of old-kdb-dump.ov for an extra dump and load is necessary
+to preserve per-principal policy information, which is not included in
+the default dump format of krb5 1.1.x.
+
+.. note:: Using kdb5_util to dump and reload the principal database is
+          only necessary when upgrading from versions of krb5 prior
+          to 1.2.0---newer versions will use the existing database as-is.
+
 
 .. _create_stash: