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