Added kdb5_util man page to the Sphinx doc tree

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25072 dc483132-0cff-0310-8789-dd5450dbe970

9 files changed, 215 insertions, 18 deletions

diff --git a/doc/rst_source/conf.py b/doc/rst_source/conf.py
index 8f0af99c3c..0933a77b7b 100644
--- a/doc/rst_source/conf.py
+++ b/doc/rst_source/conf.py
@@ -230,4 +230,5 @@ man_pages = [
     ('krb_admins/admin_commands/kprop', 'kprop', u'propagate a Kerberos V5 principal database to a slave server', [u'MIT'], 8),
     ('krb_admins/admin_commands/kproplog', 'kproplog', u'display the contents of the Kerberos principal update log', [u'MIT'], 8),
     ('krb_admins/admin_commands/kpropd', 'kpropd', u'Kerberos V5 slave KDC update server', [u'MIT'], 8),
+    ('krb_admins/admin_commands/kdb5_util', 'kdb5_util', u'Kerberos database maintenance utility', [u'MIT'], 8),
 ]
diff --git a/doc/rst_source/krb_admins/admin_commands/index.rst b/doc/rst_source/krb_admins/admin_commands/index.rst
index e38217801f..3ddc86d995 100644
--- a/doc/rst_source/krb_admins/admin_commands/index.rst
+++ b/doc/rst_source/krb_admins/admin_commands/index.rst
@@ -12,7 +12,7 @@ Administration  programs
    kprop.rst
    kpropd.rst
    kproplog.rst
-
+   kdb5_util.rst
 
 ------------
 
diff --git a/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst b/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
index c06afcf016..8710be4ba4 100644
--- a/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
+++ b/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
@@ -1,4 +1,4 @@
-kadmin(1), kadmin.local(8)
+kadmin, kadmin.local
 ===========================
 
 
@@ -44,7 +44,7 @@ and uses that service ticket to authenticate to KADM5.
 
 If the database is db2, the local client *kadmin.local*, is intended to run directly on the master KDC without Kerberos authentication.
 The local version provides all of the functionality of the now obsolete kdb5_edit(8), except for database dump and load, 
-which is now provided by the kdb5_util(8) utility.
+which is now provided by the :ref:`kdb5_util(8)` utility.
 
 If the database is LDAP, *kadmin.local* need not be run on the KDC.
 
diff --git a/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst b/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst
new file mode 100644
index 0000000000..dbf487a20e
--- /dev/null
+++ b/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst
@@ -0,0 +1,195 @@
+.. _kdb5_util(8):
+
+kdb5_util
+==========
+
+SYNOPSIS
+---------------
+       
+**kdb5_util** 
+            [**-r** *realm*] 
+            [**-d** *dbname*] 
+            [**-k** *mkeytype*] 
+            [**-M** *mkeyname*] 
+            [**-kv** *mkeyVNO*] 
+            [**-sf** *stashfilename*] 
+            [**-m**] 
+            *command* [*command_options*]
+
+DESCRIPTION
+---------------
+       
+*kdb5_util*  allows an administrator to perform low-level maintenance procedures on the Kerberos and KADM5 database.  
+Databases can be created, destroyed, and dumped to and loaded from ASCII files.  
+Additionally, *kdb5_util* can create a Kerberos master key stash file.  
+*kdb5_util* subsumes the functionality of and makes obsolete the previous database maintenance programs kdb5_create, kdb5_edit, kdb5_destroy, and kdb5_stash.
+
+When *kdb5_util* is run, it attempts to acquire the master key and open the database.  However, execution continues regardless of whether or not
+*kdb5_util* successfully opens the database, because the database may not exist yet or the stash file may be corrupt.
+
+Note that some KDB plugins may not support all *kdb5_util* commands.
+
+COMMAND-LINE OPTIONS
+----------------------
+       
+       **-r** *realm*
+              specifies the Kerberos realm of the database; by default the realm returned by krb5_default_local_realm(3) is used.
+
+       **-d** *dbname*
+              specifies the name under which the principal database is stored; by default the database is that listed in :ref:`kdc.conf`.   
+              The  KADM5  policy database and lock file are also derived from this value.
+
+       **-k** *mkeytype*
+              specifies the key type of the master key in the database; the default is that given in :ref:`kdc.conf`.
+
+       **-kv** *mkeyVNO*
+              Specifies the version number of the master key in the database; the default is 1.  Note that 0 is not allowed.
+
+       **-M** *mkeyname*
+              principal name for the master key in the database; the default is that given in :ref:`kdc.conf`.
+
+       **-m**
+              specifies that the master database password should be read from the TTY rather than fetched from a file on disk.
+
+       **-sf** *stash_file*
+              specifies the stash file of the master database password.
+
+       **-P** *password*
+              specifies the master database password.  This option is not recommended.
+
+COMMANDS
+---------------
+       
+       **create** [**-s**]
+              Creates a new database.  If the *-s* option is specified, the stash file is also created.  This command fails if the database already exists.
+              If the command is successful, the database is opened just as if it had already existed when the program was first run.
+
+       **destroy** [**-f**]
+              Destroys the database, first overwriting the disk sectors and then unlinking the files, after prompting the user for confirmation.
+              With the *-f* argument, does not prompt the user.
+
+       **stash** [**-f** *keyfile*]
+              Stores the master principal's keys in a stash file.  The *-f* argument can be used to override the *keyfile* specified at startup.
+
+       **dump** [**-old|-b6|-b7|-ov|-r13**] [**-verbose**] [**-mkey_convert**] [**-new_mkey_file** *mkey_file*] [**-rev**] [**-recurse**] [*filename* [*principals*...]]
+              Dumps the current Kerberos and KADM5 database into an ASCII file.  By default, the database is dumped in current format, "*kdb5_util*
+              load_dump version 6".  If filename is not specified, or is the string "-", the dump is sent to standard output.  Options:
+
+              **-old**
+                     causes the dump to be in the Kerberos 5 Beta 5 and earlier dump format ("kdb5_edit load_dump version 2.0").
+
+              **-b6**
+                     causes the dump to be in the Kerberos 5 Beta 6 format ("kdb5_edit load_dump version 3.0").
+
+              **-b7**
+                     causes the dump to be in the Kerberos 5 Beta 7 format ("*kdb5_util* load_dump version 4").   
+                     This  was  the  dump  format  produced  on releases prior to 1.2.2.
+
+              **-ov**
+                     causes the dump to be in ovsec_adm_export format.
+
+              **-r13**
+                     causes the dump to be in the Kerberos 5 1.3 format ("*kdb5_util* load_dump version 5").  
+                     This was the dump format produced on releases prior to 1.8.
+
+              **-verbose**
+                     causes the name of each principal and policy to be printed as it is dumped.
+
+              **-mkey_convert**
+                     prompts for a new master key.  This new master key will be used to re-encrypt the key data in the dumpfile.
+                     The key data in the database will not be changed.
+
+              **-new_mkey_file** *mkey_file*
+                     the filename of a stash file.  The master key in this stash file will be used to re-encrypt the key data in the dumpfile.
+                     The key data in the database will not be changed.
+
+              **-rev**
+                     dumps in reverse order.  This may recover principals that do not dump normally, in cases where database corruption has occured.
+
+              **-recurse**
+                     causes the dump to walk the database recursively (btree only).  This may recover principals that do not dump normally,
+                     in cases where database corruption has occured.
+                     In  cases  of such corruption, this option will probably retrieve more principals than the *-rev* option will.
+
+
+       **load** [**-old|-b6|-b7|-ov|-r13**] [**-hash**] [**-verbose**] [**-update**] *filename dbname*
+              Loads a database dump from the named file into the named database.  
+              Unless the *-old* or *-b6* option is given, the format of the dump file is detected automatically and handled as appropriate.
+              Unless the *-update* option is given, load creates a new database containing only the principals in the dump file,
+              overwriting the contents of any previously existing database.
+              Note that when using the LDAP KDB plugin the *-update* must be given.  Options:
+
+              **-old**
+                     requires the database to be in the Kerberos 5 Beta 5 and earlier format ("kdb5_edit load_dump version 2.0").
+
+              **-b6**
+                     requires the database to be in the Kerberos 5 Beta 6 format ("kdb5_edit load_dump version 3.0").
+
+              **-b7**
+                     requires the database to be in the Kerberos 5 Beta 7 format ("*kdb5_util* load_dump version 4").
+
+              **-ov**
+                     requires the database to be in ovsec_adm_import format.  Must be used with the *-update* option.
+
+              **-hash**
+                     requires the database to be stored as a hash.  If this option is not specified, the database will be stored as a btree.
+                     This option is not recommended, as databases stored in hash format are known to corrupt data and lose principals.
+
+              **-verbose**
+                     causes the name of each principal and policy to be printed as it is dumped.
+
+              **-update**
+                     records from the dump file are added to or updated in the existing database; 
+                     otherwise, a new database  is  created  containing  only what is in the dump file and the old one destroyed upon successful completion.
+
+              *dbname* is required and overrides the value specified on the command line or the default.
+
+       **ark**
+              Adds a random key.
+
+       **add_mkey** [**-e** *etype*] [**-s**]
+              Adds a new master key to the K/M (master key) principal.  Existing master keys will remain.
+              The *-e etype* option allows specification of the enctype of the new master key.
+              The *-s* option stashes the new master key in a local stash file which will be created if it doesn't already exist.
+
+       **use_mkey** *mkeyVNO* [*time*]
+              Sets the activation time of the master key specified by mkeyVNO.
+              Once a master key is active (i.e. its activation time has been reached) it will then be used to encrypt principal keys either when
+              the principal keys change, are newly created or when the update_princ_encryption command is run.
+              If the time argument is provided then that will be the activation time otherwise the current time is used by default.
+              The format of the optional time argument is that specified in the Time Formats section of the kadmin man page.
+
+       **list_mkeys**
+              List all master keys from most recent to earliest in K/M principal.
+              The output will show the KVNO, enctype and salt for each mkey similar to kadmin getprinc output.
+              A \* following an mkey denotes the currently active master key.
+
+       **purge_mkeys** [**-f**] [**-n**] [**-v**]
+              Delete master keys from the K/M principal that are not used to protect any principals.
+              This command can be used to remove old master keys from a K/M principal once all principal keys are protected by a newer master key.
+
+       **-f**     
+              does not prompt user.
+
+       **-n**
+              do a dry run, shows master keys that would be purged, does not actually purge any keys.
+
+       **-v**
+              verbose output.
+
+       **update_princ_encryption** [**-f**] [**-n**] [**-v**] [*princ-pattern*]
+              Update all principal records (or only those matching the princ-pattern glob pattern)
+              to re-encrypt the key data using the active database master key, if they are encrypted using older versions,
+              and give a count at the end of the number of principals updated.
+              If the *-f* option is not given, ask for confirmation before starting to make changes.
+              The *-v* option causes each principal processed (each one matching the pattern) to be listed,
+              and an indication given as to whether it needed updating or not.
+              The *-n* option causes the actions not to be taken, only the normal or verbose status messages displayed;
+              this implies *-f* since no database changes will be performed and thus there's little reason to seek confirmation.
+
+SEE ALSO
+---------------
+       
+kadmin(8)
+
+
diff --git a/doc/rst_source/krb_admins/admin_commands/kprop.rst b/doc/rst_source/krb_admins/admin_commands/kprop.rst
index a810d8dca7..6416473e75 100644
--- a/doc/rst_source/krb_admins/admin_commands/kprop.rst
+++ b/doc/rst_source/krb_admins/admin_commands/kprop.rst
@@ -1,6 +1,6 @@
-.. _kprop:
+.. _kprop(8):
 
-kprop(8)
+kprop
 =========
 
 
@@ -34,7 +34,7 @@ OPTIONS
               *KPROP_DEFAULT_FILE* (normally /usr/local/var/krb5kdc/slave_datatrans).
 
        **-P** *port*
-              Specifies the port to use to contact the :ref:`kpropd` server on the remote host.
+              Specifies the port to use to contact the :ref:`kpropd(8)` server on the remote host.
 
        **-d**     
               Prints debugging information.
diff --git a/doc/rst_source/krb_admins/admin_commands/kpropd.rst b/doc/rst_source/krb_admins/admin_commands/kpropd.rst
index 78746ef034..1fc0368ede 100644
--- a/doc/rst_source/krb_admins/admin_commands/kpropd.rst
+++ b/doc/rst_source/krb_admins/admin_commands/kpropd.rst
@@ -1,6 +1,6 @@
-.. _kpropd:
+.. _kpropd(8):
 
-kpropd(8)
+kpropd
 ===========
 
 
@@ -20,11 +20,11 @@ DESCRIPTION
 -------------
 
 The *kpropd* command runs on the slave KDC server.  
-It listens for update requests made by the :ref:`kprop` program, and periodically requests incremental updates from the master KDC.
+It listens for update requests made by the :ref:`kprop(8)` program, and periodically requests incremental updates from the master KDC.
 
 When the slave receives a kprop request from the master, *kpropd* accepts the dumped KDC database and places it in a file, 
-and then runs kdb5_util(8) to load the dumped database into the active database which is used by :ref:`krb5kdc`.  
-Thus, the master Kerberos server can use :ref:`kprop` to propagate its database to the slave slavers.  
+and then runs :ref:`kdb5_util(8)` to load the dumped database into the active database which is used by :ref:`krb5kdc(8)`.  
+Thus, the master Kerberos server can use :ref:`kprop(8)` to propagate its database to the slave slavers.  
 Upon a successful download of the KDC database file, the slave Kerberos server will have an up-to-date KDC database.
 
 Normally, *kpropd* is invoked out of inetd(8).  This is done by adding a line to the *inetd.conf* file which looks like this::
@@ -35,7 +35,7 @@ However, *kpropd* can also run as a standalone daemon, if the *-S* option is tur
 This is done for debugging purposes, or if for some reason the system administrator just doesn't want to run it out of inetd(8).
 
 When the slave periodically requests incremental updates, *kpropd* updates its *principal.ulog* file with any updates from the master.  
-:ref:`kproplog` can be used to view a summary of the update entry log on the slave KDC.  
+:ref:`kproplog(8)` can be used to view a summary of the update entry log on the slave KDC.  
 Incremental propagation is not enabled by default; it can be enabled using the *iprop_enable* and *iprop_slave_poll* settings in :ref:`kdc.conf`).  
 The principal "kiprop/slavehostname@REALM" (where "slavehostname" is the name of the slave KDC host, 
 and "REALM" is the name of the Kerberos realm) must be present in the slave's keytab file.
@@ -51,7 +51,7 @@ OPTIONS
               (normally /usr/local/var/krb5kdc/from_master).
 
        **-p**
-              Allows the user to specify the pathname to the kdb5_util(8) program; by default the pathname used is *KPROPD_DEFAULT_KDB5_UTIL*
+              Allows the user to specify the pathname to the :ref:`kdb5_util(8)` program; by default the pathname used is *KPROPD_DEFAULT_KDB5_UTIL*
               (normally /usr/local/sbin/kdb5_util).
 
        **-S**     
@@ -75,7 +75,7 @@ FILES
 
 *kpropd.acl*  
             Access file for *kpropd*; the default location is KPROPD_ACL_FILE (normally /usr/local/var/krb5kdc/kpropd.acl).  
-            Each entry is a line containing the principal of a host from which the local machine will allow Kerberos database propagation via :ref:`kprop`.
+            Each entry is a line containing the principal of a host from which the local machine will allow Kerberos database propagation via :ref:`kprop(8)`.
 
 SEE ALSO
 ----------
diff --git a/doc/rst_source/krb_admins/admin_commands/kproplog.rst b/doc/rst_source/krb_admins/admin_commands/kproplog.rst
index dc5c4e0399..fda3228d5b 100644
--- a/doc/rst_source/krb_admins/admin_commands/kproplog.rst
+++ b/doc/rst_source/krb_admins/admin_commands/kproplog.rst
@@ -1,6 +1,6 @@
-.. _kproplog:
+.. _kproplog(8):
 
-kproplog(8)
+kproplog
 ===========
 
 
diff --git a/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst b/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst
index 91f10204d6..f588d7bd27 100644
--- a/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst
+++ b/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst
@@ -1,6 +1,6 @@
-.. _krb5kdc:
+.. _krb5kdc(8):
 
-krb5kdc(8)
+krb5kdc
 ===========================
 
 SYNOPSIS
diff --git a/doc/rst_source/krb_users/user_commands/index.rst b/doc/rst_source/krb_users/user_commands/index.rst
index e88f4ab095..6ae62d2a6a 100644
--- a/doc/rst_source/krb_users/user_commands/index.rst
+++ b/doc/rst_source/krb_users/user_commands/index.rst
@@ -13,6 +13,7 @@ User commands
    kpasswd.rst
    kvno.rst
    ksu.rst
+   ../../krb_admins/admin_commands/kadmin_local.rst
 
 
 ------------------