* 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.

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

4 files changed, 80 insertions, 16 deletions

diff --git a/src/kadmin/dbutil/ChangeLog b/src/kadmin/dbutil/ChangeLog
index 4ecf34e..e0e61cd 100644
--- a/src/kadmin/dbutil/ChangeLog
+++ b/src/kadmin/dbutil/ChangeLog
@@ -1,3 +1,20 @@
+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.
+
 2002-08-14  Jen Selby <jenselby@mit.edu>
 
 	* dump.c: added -mkey_convert and -new_mkey_file to the usage
diff --git a/src/kadmin/dbutil/dump.c b/src/kadmin/dbutil/dump.c
index 47042aa..8dee427 100644
--- a/src/kadmin/dbutil/dump.c
+++ b/src/kadmin/dbutil/dump.c
@@ -43,6 +43,9 @@
 static int			mkey_convert;
 static krb5_keyblock		new_master_keyblock;
 
+static int	backwards;
+static int	recursive;
+
 /*
  * Use compile(3) if no regcomp present.
  */
@@ -1002,7 +1005,8 @@ static krb5_error_code dump_ov_princ(krb5_pointer ptr, krb5_db_entry *kdb)
 /*
  * usage is:
  *	dump_db [-old] [-b6] [-b7] [-ov] [-verbose] [-mkey_convert]
- *	[-new_mkey_file] [filename [principals...]]
+ *		[-new_mkey_file mkey_file] [-rev] [-recurse]
+ *		[filename [principals...]]
  */
 void
 dump_db(argc, argv)
@@ -1031,6 +1035,8 @@ dump_db(argc, argv)
     arglist.verbose = 0;
     new_mkey_file = 0;
     mkey_convert = 0;
+    backwards = 0;
+    recursive = 0;
 
     /*
      * Parse the qualifiers.
@@ -1051,7 +1057,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;
     }
 
@@ -1123,6 +1133,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.
 	 * 
@@ -1159,9 +1174,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 8a6c00a..964212b 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
@@ -90,11 +91,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
@@ -116,6 +122,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\-b7\fP] [\fB\-ov\fP] [\fB\-hash\fP]
@@ -126,7 +153,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, 
@@ -156,7 +183,7 @@ 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 binary tree.  This option
+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
@@ -184,8 +211,9 @@ Dumps the current database into the Kerberos 4 database dump format.
 The \-S option specifies the short lifetime algorithm.
 .TP
 \fBload_v4\fP [\fB\-T\fP] [\fB\-v\fP] [\fB\-h\fP] [\fB\-S\fP]
-[\fB\-t\fP] [\fB-n\fP] [\fB\-K\fP] [\fB\-s\ \fIstashfile\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
@@ -214,7 +242,7 @@ the keys to the current database.
 Uses the short lifetime algorithm for conversion.
 .TP
 .B \-h
-Stores the database as a hash instead of a binary tree.  This option is
+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
@@ -229,6 +257,7 @@ 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.
diff --git a/src/kadmin/dbutil/kdb5_util.c b/src/kadmin/dbutil/kdb5_util.c
index bace2fa..5249768 100644
--- a/src/kadmin/dbutil/kdb5_util.c
+++ b/src/kadmin/dbutil/kdb5_util.c
@@ -82,12 +82,14 @@ kadm5_config_params global_params;
 void 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	[-S] [filename]\n"
 	     "\tload_v4	[-S] [-t] [-n] [-v] [-K] [-s stashfile] inputfile\n"