krb5 commit: Synchronize command-line option documentation
Greg Hudson
ghudson at mit.edu
Wed Feb 17 17:54:04 EST 2021
https://github.com/krb5/krb5/commit/bd912c8583261f1f2521a06e5c05757cec032580
commit bd912c8583261f1f2521a06e5c05757cec032580
Author: Robbie Harwood <rharwood at redhat.com>
Date: Fri Jan 15 15:55:01 2021 -0500
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
doc/admin/admin_commands/kadmin_local.rst | 10 +++++--
doc/admin/admin_commands/kpropd.rst | 36 ++++++++++++------------
doc/admin/admin_commands/ktutil.rst | 6 +++-
doc/user/user_commands/kdestroy.rst | 1 +
doc/user/user_commands/kinit.rst | 10 ++++++-
doc/user/user_commands/klist.rst | 6 +++-
src/build-tools/krb5-config.in | 3 +-
src/clients/kinit/kinit.c | 43 +++++++++++-----------------
src/clients/klist/klist.c | 4 ++-
src/kadmin/cli/kadmin.c | 4 +-
src/kadmin/dbutil/dump.c | 11 +------
src/kadmin/dbutil/kdb5_util.c | 4 +-
src/kadmin/dbutil/tabdump.c | 4 ---
src/kdc/main.c | 4 +-
src/kprop/kpropd.c | 8 +++---
15 files changed, 77 insertions(+), 77 deletions(-)
diff --git a/doc/admin/admin_commands/kadmin_local.rst b/doc/admin/admin_commands/kadmin_local.rst
index c6c7795..cf75e61 100644
--- 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 797090c..30c66c7 100644
--- 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 0897c77..ba6e3da 100644
--- 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 becfcef..b15846f 100644
--- 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 e12e88a..5b105e3 100644
--- 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 88e4578..eb55645 100644
--- 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 9f96a87..dead0dd 100755
--- 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 e5ebeb8..d1f5d74 100644
--- 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 a54e378..dcdc5a2 100644
--- 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 225cd2b..f3ea6fa 100644
--- 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 ff2f250..634ba4a 100644
--- 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 024edb1..19a5925 100644
--- 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 2f313db..da55c2d 100644
--- 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 40f7af4..d27d15f 100644
--- 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 874ba13..498ca59 100644
--- 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);
}
More information about the cvs-krb5
mailing list