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.

(cherry picked from commit bd912c8)

ticket: 8987
version_fixed: 1.19.1

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

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

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

doc/user/user_commands/kdestroy.rst

@@ -10,6 +10,7 @@ SYNOPSIS
 [**-A**]
 [**-q**]
 [**-c** *cache_name*]
+[**-p** *princ_name*]
 
 
 DESCRIPTION

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

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.
 

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

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);
 }
 

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);
 }
 

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 "

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;

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"

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)
 {

src/kdc/main.c

@@ -605,7 +605,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"
@@ -697,7 +697,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++;

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);
 }