* dump.c (dump_db): Update usage comment. Add "-rev" and

	"-recurse" flags to permit reverse and recursive dumping of the
	database, respectively.  Check for dump filename beginning with
	"-" to avoid accidental dumps to such filenames.

	* kdb5_util.c (usage): Update to match reality, primarily by
	updating the "dump" usage, but also showing global options before
	the command, which is how they were being interpreted anyway.

	* kdb5_util.M: Update to match reality.  Document "-mkey_convert",
	"-new_mkey_file", "-rev", and "-recurse" options to "dump".
	Document "dump to stdout" behavior.  Show global options before
	the command.  Make some formatting fixes.  s/binary tree/btree/
	since the btree back end is actually an n-ary tree.

	[pullups from trunk]

git-svn-id: svn://anonsvn.mit.edu/krb5/branches/krb5-1-2-2-branch@14775 dc483132-0cff-0310-8789-dd5450dbe970

4 files changed, 97 insertions, 14 deletions

diff --git a/src/kadmin/dbutil/ChangeLog b/src/kadmin/dbutil/ChangeLog
index 6fde232..2008272 100644
--- a/src/kadmin/dbutil/ChangeLog
+++ b/src/kadmin/dbutil/ChangeLog
@@ -1,3 +1,22 @@
+2002-08-23  Tom Yu  <tlyu@mit.edu>
+
+	* dump.c (dump_db): Update usage comment.  Add "-rev" and
+	"-recurse" flags to permit reverse and recursive dumping of the
+	database, respectively.  Check for dump filename beginning with
+	"-" to avoid accidental dumps to such filenames.
+
+	* kdb5_util.c (usage): Update to match reality, primarily by
+	updating the "dump" usage, but also showing global options before
+	the command, which is how they were being interpreted anyway.
+
+	* kdb5_util.M: Update to match reality.  Document "-mkey_convert",
+	"-new_mkey_file", "-rev", and "-recurse" options to "dump".
+	Document "dump to stdout" behavior.  Show global options before
+	the command.  Make some formatting fixes.  s/binary tree/btree/
+	since the btree back end is actually an n-ary tree.
+
+	[pullups from trunk]
+
 2002-08-12  Tom Yu  <tlyu@mit.edu>
 
 	* dump.c (master_key_convert): Iterate over freeing
diff --git a/src/kadmin/dbutil/dump.c b/src/kadmin/dbutil/dump.c
index 2b66bd4..2023f7d 100644
--- a/src/kadmin/dbutil/dump.c
+++ b/src/kadmin/dbutil/dump.c
@@ -47,6 +47,9 @@ extern void usage();
 static int			mkey_convert;
 static krb5_keyblock		new_master_keyblock;
 
+static int	backwards;
+static int	recursive;
+
 /*
  * Use compile(3) if no regcomp present.
  */
@@ -1005,7 +1008,9 @@ static krb5_error_code dump_ov_princ(krb5_pointer ptr, krb5_db_entry *kdb)
 
 /*
  * usage is:
- *	dump_db [-old] [-b6] [-b7] [-ov] [-verbose] [filename [principals...]]
+ *	dump_db [-old] [-b6] [-b7] [-ov] [-verbose] [-mkey_convert]
+ *		[-new_mkey_file mkey_file] [-rev] [-recurse]
+ *		[filename [principals...]]
  */
 void
 dump_db(argc, argv)
@@ -1036,6 +1041,8 @@ dump_db(argc, argv)
     arglist.verbose = 0;
     new_mkey_file = 0;
     mkey_convert = 0;
+    backwards = 0;
+    recursive = 0;
 
     /*
      * Parse the qualifiers.
@@ -1056,7 +1063,11 @@ dump_db(argc, argv)
 	else if (!strcmp(argv[aindex], "-new_mkey_file")) {
 	    new_mkey_file = argv[++aindex];
 	    mkey_convert = 1;
-        } else
+        } else if (!strcmp(argv[aindex], "-rev"))
+	    backwards = 1;
+	else if (!strcmp(argv[aindex], "-recurse"))
+	    recursive = 1;
+	else
 	    break;
     }
 
@@ -1126,6 +1137,11 @@ dump_db(argc, argv)
     locked = 0;
     if (ofile && strcmp(ofile, "-")) {
 	/*
+	 * Discourage accidental dumping to filenames beginning with '-'.
+	 */
+	if (ofile[0] == '-')
+	    usage();
+	/*
 	 * Make sure that we don't open and truncate on the fopen,
 	 * since that may hose an on-going kprop process.
 	 * 
@@ -1162,9 +1178,10 @@ dump_db(argc, argv)
 	if (dump->header[strlen(dump->header)-1] != '\n')
 	     fputc('\n', arglist.ofile);
 	
-	if ((kret = krb5_db_iterate(util_context,
-				    dump->dump_princ,
-				    (krb5_pointer) &arglist))) {
+	if ((kret = krb5_db_iterate_ext(util_context,
+					dump->dump_princ,
+					(krb5_pointer) &arglist,
+					backwards, recursive))) {
 	     fprintf(stderr, dumprec_err,
 		     programname, dump->name, error_message(kret));
 	     exit_status++;
diff --git a/src/kadmin/dbutil/kdb5_util.M b/src/kadmin/dbutil/kdb5_util.M
index 8f529d6..8080756 100644
--- a/src/kadmin/dbutil/kdb5_util.M
+++ b/src/kadmin/dbutil/kdb5_util.M
@@ -3,11 +3,12 @@
 kdb5_util \- Kerberos database maintainance utility
 .SH SYNOPSIS
 .B kdb5_util
-.I command
 [\fB\-r\fP\ \fIrealm\fP] [\fB\-d\fP\ \fIdbname\fP]
 [\fB\-k\fP\ \fImkeytype\fP] [\fB\-M\fP\ \fImkeyname\fP]
+[\fB\-sf\fP\ \fIstashfilename\fP]
 [\fB\-m\fP]
-.I command_options
+.I command
+.I [command_options]
 .SH DESCRIPTION
 .B kdb5_util
 allows an administrator to perform low-level maintainance procedures on
@@ -84,11 +85,16 @@ Stores the master principal's keys in a stash file.  The
 argument can be used to override the keyfile specified at startup.
 .TP
 \fBdump\fP [\fB\-old\fP] [\fB\-b6\fP] [\fB\-b7\fP] [\fB\-ov\fP]
-[\fB\-verbose\fP] [\fIfilename\fP [\fIprincipals...\fP]]
+[\fB\-verbose\fP] [\fB\-mkey_convert\fP]
+[\fB\-new_mkey_file\fP \fImkey_file\fP] [\fB\-rev\fP] [\fB\-recurse\fP]
+[\fIfilename\fP [\fIprincipals...\fP]]
 .br
 Dumps the current Kerberos and KADM5 database into an ASCII file.  By
 default, the database is dumped in current format, "kdb5_util
-load_dumpversion 5".  Options:
+load_dumpversion 5".  If
+.I filename
+is not specified, or is the string "\-", the dump is sent to standard
+output.  Options:
 .RS
 .TP
 .B \-old
@@ -110,6 +116,27 @@ format.
 .B \-verbose
 causes the name of each principal and policy to be printed as it is
 dumped.
+.TP
+.B \-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.
+.TP
+.B \-new_mkey_file \fImkey_file\fP
+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.
+.TP
+.B \-rev
+dumps in reverse order.  This may recover principals that do not dump
+normally, in cases where database corruption has occured.
+.TP
+.B \-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 \fB\-rev\fP
+option will.
 .RE
 .TP
 \fBload\fP [\fB\-old\fP] [\fB\-b6\fP] [\fB\-ov\fP]
@@ -120,7 +147,7 @@ Unless the
 .B \-old
 or 
 .B \-b6
-option is givnen, the format of the dump file is detected
+option is given, the format of the dump file is detected
 automatically and handled as appropriate.  Unless the
 .B \-update
 option is given, 
@@ -148,6 +175,12 @@ format.  Must be used with the
 .B \-update
 option.
 .TP
+.B \-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.
+.TP
 .B \-verbose
 causes the name of each principal and policy to be printed as it is
 dumped.
@@ -170,7 +203,10 @@ if not specified.
 \fBdump_v4\fP [\fIfilename\fP]
 Dumps the current database into the Kerberos 4 database dump format.
 .TP
-\fBload_v4\fP [\fB\-t\fP] [\fB-n\fP] [\fB\-K\fP] [\fB\-s\ \fIstashfile\fP] \fIinputfile\fP
+\fBload_v4\fP [\fB\-T\fP] [\fB\-v\fP] [\fB\-h\fP]
+[\fB\-t\fP] [\fB-n\fP] [\fB\-K\fP] [\fB\-s\fP\ \fIstashfile\fP]
+\fIinputfile\fP
+.br
 Loads a Kerberos 4 database dump file.  Options:
 .RS
 .TP
@@ -194,6 +230,11 @@ lists each principal as it is converted or ignored.
 .B \-t
 uses a temporary database, then moves that into place, instead of adding 
 the keys to the current database.
+.TP
+.B \-h
+Stores the database as a hash instead of a btree.  This option is
+not recommended, as databases stored in hash format are known to
+corrupt data and lose principals.
 .PP
 Note: if the Kerberos 4 database had a default expiration date of 12/31/1999
 or 12/31/2009 (the compiled in defaults for older or newer Kerberos
@@ -206,5 +247,9 @@ record; Version 5 stores a seperate modification time and last
 password change time.  In practice, Version 4 "modifications" were
 always password changes.  \fIload_v4\fP copies the value into both
 fields.
+.RE
+.TP
+\fBark\fP
+Adds a random key.
 .SH SEE ALSO
 kadmin(8)
diff --git a/src/kadmin/dbutil/kdb5_util.c b/src/kadmin/dbutil/kdb5_util.c
index 92b1c21..7eaa7f8 100644
--- a/src/kadmin/dbutil/kdb5_util.c
+++ b/src/kadmin/dbutil/kdb5_util.c
@@ -81,12 +81,14 @@ kadm5_config_params global_params;
 usage()
 {
      fprintf(stderr, "Usage: "
-	   "kdb5_util cmd [-r realm] [-d dbname] [-k mkeytype] [-M mkeyname]\n"
-	     "\t         [-m] [cmd options]\n"
+	   "kdb5_util [-r realm] [-d dbname] [-k mkeytype] [-M mkeyname]\n"
+	     "\t        [-sf stashfilename] [-m] cmd [cmd_options]\n"
 	     "\tcreate	[-s]\n"
 	     "\tdestroy	[-f]\n"
 	     "\tstash	[-f keyfile]\n"
-	     "\tdump	[-old] [-ov] [-b6] [-verbose] [filename	[princs...]]\n"
+	     "\tdump	[-old] [-ov] [-b6] [-verbose]\n"
+	     "\t	[-mkey_convert] [-new_mkey_file mkey_file]\n"
+	     "\t	[-rev] [-recurse] [filename [princs...]]\n"
 	     "\tload	[-old] [-ov] [-b6] [-verbose] [-update] filename\n"
 	     "\tdump_v4	[filename]\n"
 	     "\tload_v4	[-t] [-n] [-v] [-K] [-s stashfile] inputfile\n"