updated as pre Barr3y's comments (forgot to check in earlier)

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

diff --git a/doc/kadmin/cli.func-spec b/doc/kadmin/cli.func-spec
index 702d64314731d336875b2435ff6bb2a17f98bcca..1f336cbfd150e704a0d869683223c2c0094a9a69 100644 (file)
--- a/doc/kadmin/cli.func-spec
+++ b/doc/kadmin/cli.func-spec
@@ -2,26 +2,29 @@ kadmin [-r _realm_] [[-p _principal_] [-k _keytab_]] [-q _query_]
 
                If given the -p option, kadmin will use the specified
        principal to authenticate.  If the -p option is not given,
-       kadmin will default to $USER/admin (if the environment
-       variable USER is set).  If $USER is not set, then the first
-       component of the principal will be the username as obtained
-       from getuid(). If given -k, kadmin will not prompt for a
+       kadmin will default appending "/admin" to the first component
+       of the default principal of the default credentials cache.  If
+       the default credentials cache does not exist, then kadmin will
+       default to $USER/admin (if the environment variable USER is
+       set).  If $USER is not set, then the first component of the
+       principal will be the username as obtained from
+       getpwnam(getuid()). If given -k, kadmin will not prompt for a
        password, but rather use the specified keytab.  Also, if the
        -k option is given, the default principal will be the
        host/hostname.  If -r is present, then kadmin will use the
        specified realm as the default database realm rather than the
-       default realm for the local machine.
-
-       Upon starting up, kadmin will prompt for a password (unless
-       the -k option has been given).  The program will then obtain
-       tickets for ovsec_admin/admin in the default realm (unless -r
-       has been specified, in which case it will use the specified
-       realm).  The ticket is stored in a separate ccache, unless -c
-       is specified.  The lifetime for these tickets is 5 minutes.
+       default realm for the local machine. Upon starting up, kadmin
+       will prompt for a password (unless the -k option has been
+       given).  The program will then obtain tickets for
+       ovsec_admin/admin in the default realm (unless -r has been
+       specified, in which case it will use the specified realm).
+       The ticket is stored in a separate ccache.  The lifetime for
+       these tickets is 5 minutes.
 
        The -q option allows the passing of a request directly to
        kadmin, which will then exit.  This can be useful for writing
-       scripts.
+       scripts.  The query provided must be quoted as a single
+       argument to the program if there is more than one word in it.
 
 DATE FORMAT
        Various commands in kadmin can take a variety of date formats,
@@ -43,7 +46,10 @@ DATE FORMAT
        absolute dates, unless they appear in a field where a duration
        is expected.  In that case the time specifier will be
        interpreted as relative.  Specifying "ago" on a duration may
-       result in unexpected behaviour.
+       result in unexpected behaviour.  The format follows that of
+       the public-domain "getdate" package.  All date parameters must
+       be provided as a single word, which means that they must be
+       double-quoted if there are any spaces.
 
 COMMAND DESCRIPTIONS
 
@@ -53,15 +59,6 @@ add_principal [options] _newprinc_
        command has the aliases "addprinc", "ank".
 
        OPTIONS
-       -salt _salttype_
-               uses the specified salt instead of the default V5 salt
-               for generating the key.  Valid values for _salttype_
-               are:
-                       full_name (aliases "v5_salt", "normal")
-                       name_only
-                       realm_only
-                       no_salt (alias "v4_salt")
-
        -expire _expdate_
                expiration date of the principal
 
@@ -114,7 +111,7 @@ add_principal [options] _newprinc_
                KRB5_KDB_PWCHANGE_SERVICE flag on the principal in the
                database.
 
-       -randpass
+       -randkey
                sets the key of the principal to a random value
 
        -pw _password_
@@ -133,7 +130,6 @@ add_principal [options] _newprinc_
 
        ERRORS
        OVSEC_KADM_AUTH_ADD (requires "add" privilege)
-       OVSEC_KADM_BAD_MASK (shouldn't happen)
        OVSEC_KADM_DUP (principal exists already)
        OVSEC_KADM_UNK_POLICY (policy does not exist)
        OVSEC_KADM_PASS_Q_* (password quality violations)
@@ -145,10 +141,10 @@ delete_principal [-force] _principal_
        to "delprinc".
 
        EXAMPLE
-       kadmin: delprinc mwm_user
+       kadmin: delprinc testuser
        Are you sure you want to delete the principal
-       "mwm_user@ATHENA.MIT.EDU"? (yes/no): yes
-       Principal "mwm_user@ATHENA.MIT.EDU" deleted.
+       "testuser@ATHENA.MIT.EDU"? (yes/no): yes
+       Principal "testuser@ATHENA.MIT.EDU" deleted.
        Make sure that you have removed this principal from
        all ACLs before reusing.
        kadmin:
@@ -202,12 +198,7 @@ change_password [options] _principal_
        "cpw".
 
        OPTIONS
-       -salt _salttype_
-               uses the specified salt instead of the default V5 salt
-               for generating the key.  Options are the same as for
-               add_principal.
-
-       -randpass
+       -randkey
                sets the key of the principal to a random value
 
        -pw _password_
@@ -234,8 +225,8 @@ get_principal [-terse] _principal_
        gets the attributes of _principal_.  Requires the "get"
        privilege, or that the principal that is running the the
        program to be the same as the one being listed.  With the
-       "-terse" option, outputs fields as a quoted tab-separated
-       strings.  Alias "getprinc".
+       "-terse" option, outputs fields as tab-separated strings.  Any
+       string fields get double-quoted.  Alias "getprinc".
 
        EXAMPLES
        kadmin: getprinc tlyu/deity
@@ -252,11 +243,10 @@ get_principal [-terse] _principal_
        Attributes: DISALLOW_FORWARDABLE, DISALLOW_PROXIABLE,
                REQUIRES_HW_AUTH
        Salt type: DEFAULT
-       kadmin: getprinc systest
-       systest@ATHENA.MIT.EDU  3       86400   604800  1
-       785926535       753241234       785900000
-       tlyu/admin@ATHENA.MIT.EDU       786100034       0
-       0
+       kadmin: getprinc -terse systest
+       "systest@ATHENA.MIT.EDU"        3       86400   604800
+       1       785926535       753241234       785900000
+       "tlyu/admin@ATHENA.MIT.EDU"     786100034       0       0
        kadmin:
 
        ERRORS
@@ -318,7 +308,8 @@ modify_policy [options] _policy_
 get_policy [-terse] _policy_
        displays the values of the named policy.  Requires the "get"
        privilege.  With the "-terse" flag, outputs the fields as
-       quoted strings separated by tabs.  Alias "getpol".
+       strings separated by tabs.  All string fields get
+       double-quoted.  Alias "getpol".
 
        EXAMPLES
        kadmin: get_policy admin
@@ -330,7 +321,7 @@ get_policy [-terse] _policy_
        Number of old keys kept: 5
        Reference count: 17
        kadmin: get_policy -terse admin
-       admin   15552000        0       6       2       5       17
+       "admin" 15552000        0       6       2       5       17
        kadmin:
 
        ERRORS