From 6858ecbb9c407ff6d2b22cac283ea2461af1757b Mon Sep 17 00:00:00 2001 From: Robbie Harwood Date: Thu, 20 Aug 2020 17:49:29 -0400 Subject: [PATCH] Unify kvno option documentation Add missing kvno options to the kvno.rst synopsis and option descriptions, and to the kvno usage message. Remove mention of '-h' (help text), from kvno.rst as it is an implicit option. Note that the three new caching options were added in release 1.19. Indicate the two exclusions (-u/-S and --u2u with the S4U2Self options) and dependency (-P on S4U2Self) where they are missing. Switch xusage() to print only a single localized string, rather than running each line of output through localization separately. Leave kvno -C undocumented for now, as the semantics of KRB5_GC_CANONICALIZE are minimally useful and likely to change. [ghudson@mit.edu: edited documentation and commit message] ticket: 7476 tags: pullup target_version: 1.18-next (cherry picked from commit becd1ad6830b526d08ddaf5b2b6f213154c6446c) (cherry picked from commit 52e3695cc5ef00766e12adfe8ed276c2885e71bb) --- doc/user/user_commands/kvno.rst | 24 +++++++++++++----------- src/clients/kvno/kvno.c | 15 +++++++++------ src/man/kvno.man | 24 +++++++++++++----------- 3 files changed, 35 insertions(+), 28 deletions(-) diff --git a/doc/user/user_commands/kvno.rst b/doc/user/user_commands/kvno.rst index 718313576..65c44e1c0 100644 --- a/doc/user/user_commands/kvno.rst +++ b/doc/user/user_commands/kvno.rst @@ -10,13 +10,9 @@ SYNOPSIS [**-c** *ccache*] [**-e** *etype*] [**-q**] -[**-h**] +[**-u** | **-S** *sname*] [**-P**] -[**-S** *sname*] -[**-I** *for_user*] -[**-U** *for_user*] -[**-F** *cert_file*] -[**--u2u** *ccache*] +[[{**-F** *cert_file* | {**-I** | **-U**} *for_user*} [**-P**]] | **--u2u** *ccache*] *service1 service2* ... @@ -39,13 +35,18 @@ OPTIONS of all the services named on the command line. This is useful in certain backward compatibility situations. +**-k** *keytab* + Decrypt the acquired tickets using *keytab* to confirm their + validity. + **-q** Suppress printing output when successful. If a service ticket cannot be obtained, an error message will still be printed and kvno will exit with nonzero status. -**-h** - Prints a usage statement and exits. +**-u** + Use the unknown name type in requested service principal names. + This option Cannot be used with *-S*. **-P** Specifies that the *service1 service2* ... arguments are to be @@ -76,16 +77,17 @@ OPTIONS **--cached-only** Only retrieve credentials already present in the cache, not from - the KDC. + the KDC. (Added in release 1.19.) **--no-store** Do not store retrieved credentials in the cache. If **--out-cache** is also specified, credentials will still be - stored into the output credential cache. + stored into the output credential cache. (Added in release 1.19.) **--out-cache** *ccache* Initialize *ccache* and store all retrieved credentials into it. - Do not store acquired credentials in the input cache. + Do not store acquired credentials in the input cache. (Added in + release 1.19.) **--u2u** *ccache* Requests a user-to-user ticket. *ccache* must contain a local diff --git a/src/clients/kvno/kvno.c b/src/clients/kvno/kvno.c index 9d85864f6..c5f6bf700 100644 --- a/src/clients/kvno/kvno.c +++ b/src/clients/kvno/kvno.c @@ -38,15 +38,18 @@ static char *prog; static int quiet = 0; +#define XUSAGE_BREAK "\n\t" + static void xusage() { - fprintf(stderr, _("usage: %s [-C] [-u] [-c ccache] [-e etype]\n"), prog); - fprintf(stderr, _("\t[-k keytab] [-S sname] [{-I | -U} for_user | " - "[-F cert_file] [-P]]\n")); - fprintf(stderr, _("\t[--cached-only] [--no-store] [--out-cache ccache] " - "[--u2u ccache]\n")); - fprintf(stderr, _("\tservice1 service2 ...\n")); + fprintf(stderr, _("usage: %s [-c ccache] [-e etype] [-k keytab] [-q] " + "[-u | -S sname]" XUSAGE_BREAK + "[[{-F cert_file | {-I | -U} for_user} [-P]] | " + "--u2u ccache]" XUSAGE_BREAK + "[--cached-only] [--no-store] [--out-cache] " + "service1 service2 ...\n"), + prog); exit(1); } diff --git a/src/man/kvno.man b/src/man/kvno.man index b9f6739eb..22318324d 100644 --- a/src/man/kvno.man +++ b/src/man/kvno.man @@ -36,13 +36,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] [\fB\-c\fP \fIccache\fP] [\fB\-e\fP \fIetype\fP] [\fB\-q\fP] -[\fB\-h\fP] +[\fB\-u\fP | \fB\-S\fP \fIsname\fP] [\fB\-P\fP] -[\fB\-S\fP \fIsname\fP] -[\fB\-I\fP \fIfor_user\fP] -[\fB\-U\fP \fIfor_user\fP] -[\fB\-F\fP \fIcert_file\fP] -[\fB\-\-u2u\fP \fIccache\fP] +[[{\fB\-F\fP \fIcert_file\fP | {\fB\-I\fP | \fB\-U\fP} \fIfor_user\fP} [\fB\-P\fP]] | \fB\-\-u2u\fP \fIccache\fP] \fIservice1 service2\fP ... .SH DESCRIPTION .sp @@ -60,13 +56,18 @@ Specifies the enctype which will be requested for the session key of all the services named on the command line. This is useful in certain backward compatibility situations. .TP +\fB\-k\fP \fIkeytab\fP +Decrypt the acquired tickets using \fIkeytab\fP to confirm their +validity. +.TP \fB\-q\fP Suppress printing output when successful. If a service ticket cannot be obtained, an error message will still be printed and kvno will exit with nonzero status. .TP -\fB\-h\fP -Prints a usage statement and exits. +\fB\-u\fP +Use the unknown name type in requested service principal names. +This option Cannot be used with \fI\-S\fP\&. .TP \fB\-P\fP Specifies that the \fIservice1 service2\fP ... arguments are to be @@ -97,16 +98,17 @@ certificate file must be in PEM format. .TP \fB\-\-cached\-only\fP Only retrieve credentials already present in the cache, not from -the KDC. +the KDC. (Added in release 1.19.) .TP \fB\-\-no\-store\fP Do not store retrieved credentials in the cache. If \fB\-\-out\-cache\fP is also specified, credentials will still be -stored into the output credential cache. +stored into the output credential cache. (Added in release 1.19.) .TP \fB\-\-out\-cache\fP \fIccache\fP Initialize \fIccache\fP and store all retrieved credentials into it. -Do not store acquired credentials in the input cache. +Do not store acquired credentials in the input cache. (Added in +release 1.19.) .TP \fB\-\-u2u\fP \fIccache\fP Requests a user\-to\-user ticket. \fIccache\fP must contain a local