krb5 commit: Add a kdb5_util examples for old KDC upgrades

[Benjamin Kaduk]

https://github.com/krb5/krb5/commit/92eafef8b949dd59db8cfdf319852d53e24fe2e5
commit 92eafef8b949dd59db8cfdf319852d53e24fe2e5
Author: Ben Kaduk <kaduk at mit.edu>
Date:   Wed Oct 3 12:29:20 2012 -0400

    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

 doc/rst_source/krb_admins/database.rst |   20 ++++++++++++++++++++
 1 files changed, 20 insertions(+), 0 deletions(-)

diff --git a/doc/rst_source/krb_admins/database.rst b/doc/rst_source/krb_admins/database.rst
index afea975..2671e0e 100644
--- 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: