Synchronize command-line option documentation

Command-line options are described in the following places:

- .rst file "SYNOPSIS" section
- .rst file "OPTIONS" section
- parameters to getopt()
- results of getopt() that are actually handled
- a usage() or xusage() function
- occasionally, a long form in usage()/xusage()
- occasionally, libss subcommand specifications

Over time, these have drifted.  Make an effort to correct this drift,
marking deprecated options as such.  For consistency, remove mention
of long arguments that have an equivalent short form.

ticket: 8987 (new)
tags: pullup
target_version: 1.19-next

diff --git a/doc/admin/admin_commands/kadmin_local.rst b/doc/admin/admin_commands/kadmin_local.rst
index c6c7795adbcdbb3a0d6df46cfd9f837bde794a5d..cf75e615843b7907baa00b444b7a852acf0f9d42 100644 (file)
--- a/doc/admin/admin_commands/kadmin_local.rst
+++ b/doc/admin/admin_commands/kadmin_local.rst
@@ -607,7 +607,7 @@ expression.
 
 This command requires the **list** privilege.
 
-Alias: **listprincs**, **get_principals**, **get_princs**
+Alias: **listprincs**, **get_principals**, **getprincs**
 
 Example::
 
@@ -631,7 +631,7 @@ Displays string attributes on *principal*.
 
 This command requires the **inquire** privilege.
 
-Alias: **getstr**
+Alias: **getstrs**
 
 .. _get_strings_end:
 
@@ -828,7 +828,7 @@ tabs.
 
 This command requires the **inquire** privilege.
 
-Alias: getpol
+Alias: **getpol**
 
 Examples::
 
@@ -922,6 +922,8 @@ An entry for each of the principal's unique encryption types is added,
 ignoring multiple keys with the same encryption type but different
 salt types.
 
+Alias: **xst**
+
 Example::
 
     kadmin: ktadd -k /tmp/foo-new-keytab host/foo.mit.edu
@@ -957,6 +959,8 @@ The options are:
 **-q**
     Display less verbose information.
 
+Alias: **ktrem**
+
 Example::
 
     kadmin: ktremove kadmin/admin all

diff --git a/doc/admin/admin_commands/kpropd.rst b/doc/admin/admin_commands/kpropd.rst
index 797090ce7ed1661ce3258a3defe03ff4a99c8ab9..30c66c7e26a4081d827815d033c6faec08c5d38e 100644 (file)
--- a/doc/admin/admin_commands/kpropd.rst
+++ b/doc/admin/admin_commands/kpropd.rst
@@ -15,8 +15,9 @@ SYNOPSIS
 [**-p** *kdb5_util_prog*]
 [**-P** *port*]
 [**--pid-file**\ =\ *pid_file*]
+[**-D**]
 [**-d**]
-[**-t**]
+[**-s** *keytab_file*]
 
 DESCRIPTION
 -----------
@@ -81,22 +82,23 @@ OPTIONS
     to be stored; by default the dumped database file is |kdcdir|\
     ``/from_master``.
 
+**-F** *kerberos_db*
+    Path to the Kerberos database file, if not the default.
+
 **-p**
     Allows the user to specify the pathname to the :ref:`kdb5_util(8)`
     program; by default the pathname used is |sbindir|\
     ``/kdb5_util``.
 
-**-d**
-    Turn on debug mode.  In this mode, kpropd will not detach
-    itself from the current job and run in the background.  Instead,
-    it will run in the foreground and print out debugging messages
-    during the database propagation.
+**-D**
+    In this mode, kpropd will not detach itself from the current job
+    and run in the background.  Instead, it will run in the
+    foreground.
 
-**-t**
-    In standalone mode without incremental propagation, exit after one
-    dump file is received.  In incremental propagation mode, exit as
-    soon as the database is up to date, or if the primary returns an
-    error.
+**-d**
+    Turn on debug mode.  kpropd will print out debugging messages
+    during the database propogation and will run in the foreground
+    (implies **-D**).
 
 **-P**
     Allow for an alternate port number for kpropd to listen on.  This
@@ -110,14 +112,12 @@ OPTIONS
     In standalone mode, write the process ID of the daemon into
     *pid_file*.
 
+**-s** *keytab_file*
+    Path to a keytab to use for acquiring acceptor credentials.
 
-ENVIRONMENT
------------
-
-kpropd uses the following environment variables:
-
-* **KRB5_CONFIG**
-* **KRB5_KDC_PROFILE**
+**-x** *db_args*
+    Database-specific arguments.  See :ref:`Database Options
+    <dboptions>` in :ref:`kadmin(1)` for supported arguments.
 
 
 FILES

diff --git a/doc/admin/admin_commands/ktutil.rst b/doc/admin/admin_commands/ktutil.rst
index 0897c77579d1418e957edd811d219ee5fcb905d1..ba6e3da6420c711b69591c0716f6c1cc710bc6ef 100644 (file)
--- a/doc/admin/admin_commands/ktutil.rst
+++ b/doc/admin/admin_commands/ktutil.rst
@@ -23,9 +23,11 @@ COMMANDS
 list
 ~~~~
 
-    **list**
+    **list** [**-t**] [**-k**] [**-e**]
 
-Displays the current keylist.
+Displays the current keylist.  If **-t**, **-k**, and/or **-e** are
+specified, also display the timestamp, key contents, or enctype
+(respectively).
 
 Alias: **l**
 

diff --git a/doc/user/user_commands/kdestroy.rst b/doc/user/user_commands/kdestroy.rst
index becfcef8995dd2d449546fc8998fe155096a64be..b15846f9192deb146ab34cceeddc6ada9112fec0 100644 (file)
--- a/doc/user/user_commands/kdestroy.rst
+++ b/doc/user/user_commands/kdestroy.rst
@@ -10,6 +10,7 @@ SYNOPSIS
 [**-A**]
 [**-q**]
 [**-c** *cache_name*]
+[**-p** *princ_name*]
 
 
 DESCRIPTION

diff --git a/doc/user/user_commands/kinit.rst b/doc/user/user_commands/kinit.rst
index e12e88a3721814c74b60ab70b42d294114f9b03b..5b105e35a5ae53d790c776d816e71bfc83277082 100644 (file)
--- a/doc/user/user_commands/kinit.rst
+++ b/doc/user/user_commands/kinit.rst
@@ -19,13 +19,14 @@ SYNOPSIS
 [**-E**]
 [**-v**]
 [**-R**]
-[**-k** [-**t** *keytab_file*]]
+[**-k** [**-i** | -**t** *keytab_file*]]
 [**-c** *cache_name*]
 [**-n**]
 [**-S** *service_name*]
 [**-I** *input_ccache*]
 [**-T** *armor_ccache*]
 [**-X** *attribute*\ [=\ *value*]]
+[**--request-pac** | **--no-request-pac**]
 [*principal*]
 
 
@@ -199,6 +200,13 @@ OPTIONS
     **disable_freshness**\ [**=yes**]
         disable sending freshness tokens (for testing purposes only)
 
+**--request-pac** | **--no-request-pac**
+    mutually exclusive.  If **--request-pac** is set, ask the KDC to
+    include a PAC in authdata; if **--no-request-pac** is set, ask the
+    KDC not to include a PAC; if neither are set,  the KDC will follow
+    its default, which is typically is to include a PAC if doing so is
+    supported.
+
 ENVIRONMENT
 -----------
 

diff --git a/doc/user/user_commands/klist.rst b/doc/user/user_commands/klist.rst
index 88e4578469913470284ade93e88fb50c363306af..eb556450892490aa5e4e59d8730396905f7f318b 100644 (file)
--- a/doc/user/user_commands/klist.rst
+++ b/doc/user/user_commands/klist.rst
@@ -10,8 +10,9 @@ SYNOPSIS
 [**-e**]
 [[**-c**] [**-l**] [**-A**] [**-f**] [**-s**] [**-a** [**-n**]]]
 [**-C**]
-[**-k** [**-t**] [**-K**]]
+[**-k** [**-i**] [**-t**] [**-K**]]
 [**-V**]
+[**-d**]
 [*cache_name*\|\ *keytab_name*]
 
 
@@ -93,6 +94,9 @@ OPTIONS
     Display the value of the encryption key in each keytab entry in
     the keytab file.
 
+**-d**
+    Display the authdata types (if any) for each entry.
+
 **-V**
     Display the Kerberos version number and exit.
 

diff --git a/src/build-tools/krb5-config.in b/src/build-tools/krb5-config.in
index 9f96a8719dba4c9d7fdf1cebc9de25712a496095..dead0dddce7a6cedcc807a7ac41b706a4c4800d1 100755 (executable)
--- a/src/build-tools/krb5-config.in
+++ b/src/build-tools/krb5-config.in
@@ -70,8 +70,7 @@ while test $# != 0; do
        --defktname)
            do_defktname=1
            ;;
-       --deps)
-           do_deps=1
+       --deps) # historically a no-op
            ;;
        --exec-prefix)
            do_exec_prefix=1

diff --git a/src/clients/kinit/kinit.c b/src/clients/kinit/kinit.c
index e5ebeb8952b916c2227dceb65886e7e8c349f82e..d1f5d74c3adad30f29ac4c39e7e578202203e540 100644 (file)
--- a/src/clients/kinit/kinit.c
+++ b/src/clients/kinit/kinit.c
@@ -139,32 +139,20 @@ const char *shopts = "r:fpFPn54aAVl:s:c:kit:T:RS:vX:CEI:";
 static void
 usage()
 {
-    fprintf(stderr, "Usage: %s [-V] "
-            "[-l lifetime] [-s start_time] "
-            USAGE_BREAK
-            "[-r renewable_life] "
-            "[-f | -F | --forwardable | --noforwardable] "
-            USAGE_BREAK
-            "[-p | -P | --proxiable | --noproxiable] "
-            USAGE_BREAK
-            "-n "
-            "[-a | -A | --addresses | --noaddresses] "
-            USAGE_BREAK
-            "[--request-pac | --no-request-pac] "
-            USAGE_BREAK
-            "[-C | --canonicalize] "
-            USAGE_BREAK
-            "[-E | --enterprise] "
-            USAGE_BREAK
-            "[-v] [-R] "
-            "[-k [-i|-t keytab_file]] "
-            "[-c cachename] "
-            USAGE_BREAK
-            "[-S service_name] [-T ticket_armor_cache]"
-            USAGE_BREAK
-            "[-X <attribute>[=<value>]] [principal]"
-            "\n\n",
-            progname);
+    fprintf(stderr,
+            _("Usage: %s [-V] [-l lifetime] [-s start_time] "
+              "[-r renewable_life]"
+              USAGE_BREAK
+              "[-f | -F] [-p | -P] [-n] [-a | -A] [-C] [-E]"
+              USAGE_BREAK
+              "[--request-pac | --no-request-pac] "
+              USAGE_BREAK
+              "[-v] [-R] [-k [-i|-t keytab_file]] [-c cachename]"
+              USAGE_BREAK
+              "[-S service_name] [-I input_ccache] [-T ticket_armor_cache]"
+              USAGE_BREAK
+              "[-X <attribute>[=<value>]] [principal]"
+              "\n\n"), progname);
 
     fprintf(stderr, "    options:\n");
     fprintf(stderr, _("\t-V verbose\n"));
@@ -187,8 +175,11 @@ usage()
     fprintf(stderr, _("\t-t filename of keytab to use\n"));
     fprintf(stderr, _("\t-c Kerberos 5 cache name\n"));
     fprintf(stderr, _("\t-S service\n"));
+    fprintf(stderr, _("\t-I input credential cache\n"));
     fprintf(stderr, _("\t-T armor credential cache\n"));
     fprintf(stderr, _("\t-X <attribute>[=<value>]\n"));
+    fprintf(stderr,
+            _("\t--{,no}-request-pac request KDC include/exclude a PAC\n"));
     exit(2);
 }
 

diff --git a/src/clients/klist/klist.c b/src/clients/klist/klist.c
index a54e378780cd6324c6222c9ae80ca4eace3871b4..dcdc5a2d5955eee6dc54c7ab9c56f66bd4b66109 100644 (file)
--- a/src/clients/klist/klist.c
+++ b/src/clients/klist/klist.c
@@ -83,7 +83,8 @@ static void
 usage()
 {
     fprintf(stderr, _("Usage: %s [-e] [-V] [[-c] [-l] [-A] [-d] [-f] [-s] "
-                      "[-a [-n]]] [-k [-t] [-K]] [name]\n"), progname);
+                      "[-a [-n]]] [-k [-i] [-t] [-K]] [-C] [name]\n"),
+            progname);
     fprintf(stderr, _("\t-c specifies credentials cache\n"));
     fprintf(stderr, _("\t-k specifies keytab\n"));
     fprintf(stderr, _("\t   (Default is credentials cache)\n"));
@@ -103,6 +104,7 @@ usage()
     fprintf(stderr, _("\toptions for keytabs:\n"));
     fprintf(stderr, _("\t\t-t shows keytab entry timestamps\n"));
     fprintf(stderr, _("\t\t-K shows keytab entry keys\n"));
+    fprintf(stderr, _("\t\t-C includes configuration data entries\n"));
     exit(1);
 }
 

diff --git a/src/kadmin/cli/kadmin.c b/src/kadmin/cli/kadmin.c
index 225cd2b9a9adceb1d8bf2ce187d35fe0406f2612..f3ea6fae1766ccc042dabdc3237b3a1502db3e94 100644 (file)
--- a/src/kadmin/cli/kadmin.c
+++ b/src/kadmin/cli/kadmin.c
@@ -104,9 +104,9 @@ usage()
             "[clnt|local args]\n"
             "              [command args...]\n"
             "\tclnt args: [-s admin_server[:port]] "
-            "[[-c ccache]|[-k [-t keytab]]]|[-n]\n"
+            "[[-c ccache]|[-k [-t keytab]]]|[-n] [-O | -N]\n"
             "\tlocal args: [-x db_args]* [-d dbname] "
-            "[-e \"enc:salt ...\"] [-m]"
+            "[-e \"enc:salt ...\"] [-m] [-w password] "
             "where,\n\t[-x db_args]* - any number of database specific "
             "arguments.\n"
             "\t\t\tLook at each database documentation for supported "

diff --git a/src/kadmin/dbutil/dump.c b/src/kadmin/dbutil/dump.c
index ff2f25050345b076daac9d470b13bc4fc9ea4f57..634ba4a8bc0fcf95b5fa2cb8d33a5389bf042948 100644 (file)
--- a/src/kadmin/dbutil/dump.c
+++ b/src/kadmin/dbutil/dump.c
@@ -1161,12 +1161,6 @@ current_dump_sno_in_ulog(krb5_context context, const char *ifile)
     return status == UPDATE_OK || status == UPDATE_NIL;
 }
 
-/*
- * usage is:
- *      dump_db [-b7] [-r13] [-r18] [-verbose] [-mkey_convert]
- *              [-new_mkey_file mkey_file] [-rev] [-recurse]
- *              [filename [principals...]]
- */
 void
 dump_db(int argc, char **argv)
 {
@@ -1205,6 +1199,7 @@ dump_db(int argc, char **argv)
         } else if (!strcmp(argv[aindex], "-r18")) {
             dump = &r1_8_version;
         } else if (!strncmp(argv[aindex], "-i", 2)) {
+            /* Intentionally undocumented - only used by kadmin. */
             if (log_ctx && log_ctx->iproprole) {
                 /* ipropx_version is the maximum version acceptable. */
                 ipropx_version = atoi(argv[aindex] + 2);
@@ -1411,9 +1406,6 @@ restore_dump(krb5_context context, char *dumpfile, FILE *f,
     return 0;
 }
 
-/*
- * Usage: load_db [-b7] [-r13] [-r18] [-verbose] [-update] [-hash] filename
- */
 void
 load_db(int argc, char **argv)
 {
@@ -1443,6 +1435,7 @@ load_db(int argc, char **argv)
         } else if (!strcmp(argv[aindex], "-r18")){
             load = &r1_8_version;
         } else if (!strcmp(argv[aindex], "-i")) {
+            /* Intentionally undocumented - only used by kadmin. */
             if (log_ctx && log_ctx->iproprole) {
                 load = &iprop_version;
                 iprop_load = TRUE;

diff --git a/src/kadmin/dbutil/kdb5_util.c b/src/kadmin/dbutil/kdb5_util.c
index 024edb1cf074d033bc57c68910bc23aaac9f239e..19a59250ee26c96282b0c443a945d2de74e77933 100644 (file)
--- a/src/kadmin/dbutil/kdb5_util.c
+++ b/src/kadmin/dbutil/kdb5_util.c
@@ -85,10 +85,10 @@ void usage()
               "\tcreate  [-s]\n"
               "\tdestroy [-f]\n"
               "\tstash   [-f keyfile]\n"
-              "\tdump    [-old|-b6|-b7|-r13|-r18] [-verbose]\n"
+              "\tdump    [-b7|-r13|-r18] [-verbose]\n"
               "\t        [-mkey_convert] [-new_mkey_file mkey_file]\n"
               "\t        [-rev] [-recurse] [filename [princs...]]\n"
-              "\tload    [-old|-b6|-b7|-r13|-r18] [-verbose] [-update] "
+              "\tload    [-b7|-r13|-r18] [-hash] [-verbose] [-update] "
               "filename\n"
               "\tark     [-e etype_list] principal\n"
               "\tadd_mkey [-e etype] [-s]\n"

diff --git a/src/kadmin/dbutil/tabdump.c b/src/kadmin/dbutil/tabdump.c
index 2f313dbb0ce57407937619ef39945c0833e4ba95..da55c2d78d1b83096d711a9f9d684cb56e978745 100644 (file)
--- a/src/kadmin/dbutil/tabdump.c
+++ b/src/kadmin/dbutil/tabdump.c
@@ -602,10 +602,6 @@ cleanup_args(struct rec_args *args)
         fclose(args->f);
 }
 
-/*
- * Usaage is:
- *     tabdump [-H] [-c] [-e] [-n] [-o outfile] dumptype
- */
 void
 tabdump(int argc, char **argv)
 {

diff --git a/src/kdc/main.c b/src/kdc/main.c
index 40f7af4e90423aa3bf08e6b8cc7583550723fa60..d27d15f8ecc645056f9fd00562e428037cc25276 100644 (file)
--- a/src/kdc/main.c
+++ b/src/kdc/main.c
@@ -593,7 +593,7 @@ usage(char *name)
 {
     fprintf(stderr,
             _("usage: %s [-x db_args]* [-d dbpathname] [-r dbrealmname]\n"
-              "\t\t[-R replaycachename] [-m] [-k masterenctype]\n"
+              "\t\t[-T time_offset] [-m] [-k masterenctype]\n"
               "\t\t[-M masterkeyname] [-p port] [-P pid_file]\n"
               "\t\t[-n] [-w numworkers] [/]\n\n"
               "where,\n"
@@ -685,7 +685,7 @@ initialize_realms(krb5_context kcontext, int argc, char **argv,
      * twice if worker processes are used, so we must initialize optind.
      */
     optind = 1;
-    while ((c = getopt(argc, argv, "x:r:d:mM:k:R:e:P:p:s:nw:4:T:X3")) != -1) {
+    while ((c = getopt(argc, argv, "x:r:d:mM:k:R:P:p:nw:4:T:X3")) != -1) {
         switch(c) {
         case 'x':
             db_args_size++;

diff --git a/src/kprop/kpropd.c b/src/kprop/kpropd.c
index 874ba1305012ade7a89c024231327aa986e36c30..498ca599a147a41a2195e8f216ee7506add23401 100644 (file)
--- a/src/kprop/kpropd.c
+++ b/src/kprop/kpropd.c
@@ -167,11 +167,11 @@ static void
 usage()
 {
     fprintf(stderr,
-            _("\nUsage: %s [-r realm] [-s keytab] [-dS] [-f replica_file]\n"),
+            _("\nUsage: %s [-r realm] [-s keytab] [-d] [-D] [-S]\n"
+              "\t[-f replica_file] [-F kerberos_db_file ]\n"
+              "\t[-p kdb5_util_pathname] [-x db_args]* [-P port]\n"
+              "\t[-a acl_file] [-A admin_server] [--pid-file=pid_file]\n"),
             progname);
-    fprintf(stderr, _("\t[-F kerberos_db_file ] [-p kdb5_util_pathname]\n"));
-    fprintf(stderr, _("\t[-x db_args]* [-P port] [-a acl_file]\n"));
-    fprintf(stderr, _("\t[-A admin_server] [--pid-file=pid_file]\n"));
     exit(1);
 }