Fix up kdb5_util documentation

In kdb5_util.rst, reorder the main option summary to match the order
they are documented in below, and document the -x option.  Remove the
kdb5_util create -h switch case as 'h' has never been in the getopt
string.  Add the -r18 option to the kdb5_util dump and load option
summaries.  Reword the kdb5_util load -hash option.  Remove the
nonexistent kdb5_util load dbname parameter.

In database.rst, alter the example for loading a single principal to
use the dump principal filtering functionality, as that functionality
does not currently exist for load.

In the kdb5_util usage error message, reorder the main options to
match the order in the documentation and to fit within 79 columns.
Also add the -P option.

ticket: 8751 (new)
tags: pullup
target_version: 1.16-next

diff --git a/doc/admin/admin_commands/kdb5_util.rst b/doc/admin/admin_commands/kdb5_util.rst
index 69086fc413fb875f6a75080af196789ee67f9002..7783cb649ca5a86bc5a1691b4e98b691de3ef9e8 100644 (file)
--- a/doc/admin/admin_commands/kdb5_util.rst
+++ b/doc/admin/admin_commands/kdb5_util.rst
@@ -12,10 +12,12 @@ SYNOPSIS
 [**-r** *realm*]
 [**-d** *dbname*]
 [**-k** *mkeytype*]
-[**-M** *mkeyname*]
 [**-kv** *mkeyVNO*]
-[**-sf** *stashfilename*]
+[**-M** *mkeyname*]
 [**-m**]
+[**-sf** *stashfilename*]
+[**-P** *password*]
+[**-x** *db_args*]
 *command* [*command_options*]
 
 .. _kdb5_util_synopsis_end:
@@ -79,6 +81,10 @@ COMMAND-LINE OPTIONS
     expose the password to other users on the system via the process
     list.
 
+**-x** *db_args*
+    specifies database-specific options.  See :ref:`kadmin(1)` for
+    supported options.
+
 .. _kdb5_util_options_end:
 
 
@@ -130,9 +136,10 @@ dump
 
 .. _kdb5_util_dump:
 
-    **dump** [**-b7**\|\ **-ov**\|\ **-r13**] [**-verbose**]
-    [**-mkey_convert**] [**-new_mkey_file** *mkey_file*] [**-rev**]
-    [**-recurse**] [*filename* [*principals*...]]
+    **dump** [**-b7**\|\ **-ov**\|\ **-r13**\|\ **-r18**]
+    [**-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
@@ -197,8 +204,8 @@ load
 
 .. _kdb5_util_load:
 
-    **load** [**-b7**\|\ **-ov**\|\ **-r13**] [**-hash**]
-    [**-verbose**] [**-update**] *filename* [*dbname*]
+    **load** [**-b7**\|\ **-ov**\|\ **-r13**\|\ **-r18**] [**-hash**]
+    [**-verbose**] [**-update**] *filename*
 
 Loads a database dump from the named file into the named database.  If
 no option is given to determine the format of the dump file, the
@@ -230,10 +237,11 @@ Options:
     releases prior to 1.11.
 
 **-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.
+    stores the database in hash format, if using the DB2 database
+    type.  If this option is not specified, the database will be
+    stored in btree format.  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
@@ -245,9 +253,6 @@ Options:
     what is in the dump file and the old one destroyed upon successful
     completion.
 
-If specified, *dbname* overrides the value specified on the command
-line or the default.
-
 .. _kdb5_util_load_end:
 
 ark

diff --git a/doc/admin/database.rst b/doc/admin/database.rst
index 3007cfe35a20d72632f3bfc1b5def59c0e76fae1..14c145b24dd81abe70bccdd48af4458fcaf5dc17 100644 (file)
--- a/doc/admin/database.rst
+++ b/doc/admin/database.rst
@@ -377,14 +377,14 @@ To restore a Kerberos database dump from a file, use the
 Examples
 ########
 
-To load a single principal, either replacing or updating the database:
+To dump a single principal and later load it, updating the database:
 
 ::
 
-     shell% kdb5_util load dumpfile principal
+     shell% kdb5_util dump dumpfile principal@REALM
      shell%
 
-     shell% kdb5_util load -update dumpfile principal
+     shell% kdb5_util load -update dumpfile
      shell%
 
 

diff --git a/src/kadmin/dbutil/dump.c b/src/kadmin/dbutil/dump.c
index 2645088bfbebfbda6da4994aba43608dd4880069..c792afd1a6a7c1a0fca147a032b06652769cb779 100644 (file)
--- a/src/kadmin/dbutil/dump.c
+++ b/src/kadmin/dbutil/dump.c
@@ -1494,7 +1494,7 @@ restore_dump(krb5_context context, char *dumpfile, FILE *f,
 }
 
 /*
- * Usage: load_db [-ov] [-b7] [-r13] [-verbose] [-update] [-hash]
+ * Usage: load_db [-ov] [-b7] [-r13] [-r18] [-verbose] [-update] [-hash]
  *                filename
  */
 void

diff --git a/src/kadmin/dbutil/kdb5_create.c b/src/kadmin/dbutil/kdb5_create.c
index 5cdee473b7013f822bcf7e174b851bd0b47c9f02..bc1b9195dd566b2e4a2c58693741243ce0ffd604 100644 (file)
--- a/src/kadmin/dbutil/kdb5_create.c
+++ b/src/kadmin/dbutil/kdb5_create.c
@@ -169,13 +169,6 @@ void kdb5_create(argc, argv)
         case 's':
             do_stash++;
             break;
-        case 'h':
-            if (!add_db_arg("hash=true")) {
-                com_err(progname, ENOMEM,
-                        _("while parsing command arguments\n"));
-                exit(1);
-            }
-            break;
         case 'W':
             strong_random = 0;
             break;

diff --git a/src/kadmin/dbutil/kdb5_util.c b/src/kadmin/dbutil/kdb5_util.c
index 4ff1cdf3837eecf1ecad433de0a53703876a1b43..accc959e0299f40b86b7fc3d83a6216bd1a8e62f 100644 (file)
--- a/src/kadmin/dbutil/kdb5_util.c
+++ b/src/kadmin/dbutil/kdb5_util.c
@@ -77,10 +77,11 @@ kadm5_config_params global_params;
 void usage()
 {
     fprintf(stderr,
-            _("Usage: kdb5_util [-x db_args]* [-r realm] [-d dbname] "
-              "[-k mkeytype] [-M mkeyname]\n"
-              "\t        [-kv mkeyVNO] [-sf stashfilename] [-m] cmd "
-              "[cmd_options]\n"
+            _("Usage: kdb5_util [-r realm] [-d dbname] "
+              "[-k mkeytype] [-kv mkeyVNO]\n"
+              "\t        [-M mkeyname] [-m] [-sf stashfilename] "
+              "[-P password]\n"
+              "\t        [-x db_args]* cmd [cmd_options]\n"
               "\tcreate  [-s]\n"
               "\tdestroy [-f]\n"
               "\tstash   [-f keyfile]\n"