krb5 commit [krb5-1.16]: Fix up kdb5_util documentation

Greg Hudson ghudson at mit.edu
Tue Oct 30 12:25:59 EDT 2018


https://github.com/krb5/krb5/commit/479f5100007ec5472af418e15f17e4505044a8e9
commit 479f5100007ec5472af418e15f17e4505044a8e9
Author: Greg Hudson <ghudson at mit.edu>
Date:   Mon Oct 15 18:00:35 2018 -0400

    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.
    
    (cherry picked from commit fa000575085be71bfc326221a4d4d23fc00a1462)
    
    ticket: 8751
    version_fixed: 1.16.2

 doc/admin/admin_commands/kdb5_util.rst |   33 ++++++++++++++++++-------------
 doc/admin/database.rst                 |    6 ++--
 src/kadmin/dbutil/dump.c               |    2 +-
 src/kadmin/dbutil/kdb5_create.c        |    7 ------
 src/kadmin/dbutil/kdb5_util.c          |    9 ++++---
 5 files changed, 28 insertions(+), 29 deletions(-)

diff --git a/doc/admin/admin_commands/kdb5_util.rst b/doc/admin/admin_commands/kdb5_util.rst
index 258498f..774e60f 100644
--- 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 b693042..d6811da 100644
--- 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 at 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 aca136f..b4fe921 100644
--- 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 92bb6f6..18c94e2 100644
--- 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 000b559..f7853af 100644
--- 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"


More information about the cvs-krb5 mailing list