kadmin
and
kadmin.local
are command-line interfaces to the Kerberos V5 KADM5 administration
system. Both
kadmin
and
kadmin.local
provide identical functionalities; the difference is that
kadmin.local
runs on the master KDC if the database is db2 and
does not use Kerberos to authenticate to the
database. Except as explicitly noted otherwise,
this man page will use
kadmin
to refer to both versions.
kadmin
provides for the maintenance of Kerberos principals, KADM5 policies, and
service key tables (keytabs).
The remote version uses Kerberos authentication and an encrypted RPC, to
operate securely from anywhere on the network. It authenticates to the
KADM5 server using the service principal
kadmin/admin.
If the credentials cache contains a ticket for the
kadmin/admin
principal, and the
-ccredentials_cache
option is specified, that ticket is used to authenticate to KADM5.
Otherwise, the
-p
and
-k
options are used to specify the client Kerberos principal name used to
authenticate. Once
kadmin
has determined the principal name, it requests a
kadmin/admin
Kerberos service ticket from the KDC, and uses that service ticket to
authenticate to KADM5.
If the database is db2, the local client
kadmin.local,
is intended to run directly on the master KDC without Kerberos
authentication. The local version provides all of the functionality of
the now obsolete
kdb5_edit(8),
except for database dump and load, which is now provided by the
kdb5_util(8)
utility.
If the database is LDAP, kadmin.local need not be run on the KDC.
kadmin.local can be configured to log updates for incremental database
propagation. Incremental propagation allows slave KDC servers to
receive principal and policy updates incrementally instead of
receiving full dumps of the database. This facility can be enabled in
the
kdc.conf
file with the
iprop_enable
option. See the
kdc.conf
documentation for other options for tuning incremental propagation
parameters.
OPTIONS
-rrealm
Use
realm
as the default database realm.
-pprincipal
Use
principal
to authenticate. Otherwise, kadmin will append "/admin" to the primary
principal name of the default ccache, the value of the
USER
environment variable, or the username as obtained with getpwuid, in
order of preference.
-k
Use a keytab to decrypt the KDC response instead of prompting for a
password on the TTY. In this case, the default principal will be
host/hostname. If there is not a keytab specified with the
-t
option, then the default keytab will be used.
-tkeytab
Use
keytab
to decrypt the KDC response. This can only be used with the
-k
option.
-n
Requests anonymous processing. Two types of anonymous principals are
supported. For fully anonymous Kerberos, configure pkinit on the KDC
and configure
pkinit_anchors
in the client's krb5.conf. Then use the
-n
option with a principal of the form
@REALM
(an empty principal name followed by the at-sign and a realm name).
If permitted by the KDC, an anonymous ticket will be returned.
A second form of anonymous tickets is supported; these realm-exposed
tickets hide the identity of the client but not the client's realm.
For this mode, use
kinit -n
with a normal principal name. If supported by the KDC, the principal
(but not realm) will be replaced by the anonymous principal.
As of release 1.8, the MIT Kerberos KDC only supports fully anonymous
operation.
-ccredentials_cache
Use
credentials_cache
as the credentials cache. The
credentials_cache
should contain a service ticket for the
kadmin/admin
service; it can be acquired with the
kinit(1)
program. If this option is not specified,
kadmin
requests a new service ticket from the KDC, and stores it in its own
temporary ccache.
-wpassword
Use
password
instead of prompting for one on the TTY. Note: placing the password
for a Kerberos principal with administration access into a shell script
can be dangerous if unauthorized users gain read access to the script.
-qquery
pass
query
directly to
kadmin,
which will perform
query
and then exit. This can be useful for writing scripts.
-ddbname
Specifies the name of the Kerberos database.
This option does not apply to the LDAP database.
-sadmin_server[:port]
Specifies the admin server which kadmin should contact.
-m
Do not authenticate using a keytab. This option will cause kadmin
to prompt for the master database password.
-eenc:salt_list
Sets the list of encryption types and salt types to be used for any new
keys created.
-O
Force use of old AUTH_GSSAPI authentication flavor.
-N
Prevent fallback to AUTH_GSSAPI authentication flavor.
-xdb_args
Specifies the database specific arguments.
Options supported for LDAP database are:
-x host=<hostname>
specifies the LDAP server to connect to by a LDAP URI.
-x binddn=<bind_dn>
specifies the DN of the object used by the administration server to bind to the LDAP server.
This object should have the read and write rights on the realm container, principal container
and the subtree that is referenced by the realm.
-x bindpwd=<bind_password>
specifies the password for the above mentioned binddn. It is recommended not to use this option.
Instead, the password can be stashed using the stashsrvpw command of kdb5_ldap_util.
DATE FORMAT
Various commands in kadmin can take a variety of date formats,
specifying durations or absolute times. Examples of valid formats are:
1 month ago
2 hours ago
400000 seconds ago
last year
this Monday
next Monday
yesterday
tomorrow
now
second Monday
a fortnight ago
3/31/92 10:00:07 PST
January 23, 1987 10:05pm
22:00 GMT
Dates which do not have the "ago" specifier default to being 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" in a duration may result in unexpected behavior.
COMMANDS
add_principal [options] newprinc
creates the principal
newprinc,
prompting twice for a password. If no policy is specified with the
-policy option, and the policy named "default" exists, then that
policy is assigned to the principal; note that the assignment of the
policy "default" only occurs automatically when a principal is first
created, so the policy "default" must already exist for the assignment
to occur. This assignment of "default" can be suppressed with the
-clearpolicy option. This command requires the
add
privilege. This command has the aliases
addprinc
and
ank.
The options are:
-xdb_princ_args
Denotes the database specific options. The options for LDAP database are:
-x dn=<dn>
Specifies the LDAP object that will contain the Kerberos principal being
created.
-x linkdn=<dn>
Specifies the LDAP object to which the newly created Kerberos principal object
will point to.
-x containerdn=<container_dn>
Specifies the container object under which the Kerberos principal is to be created.
-x tktpolicy=<policy>
Associates a ticket policy to the Kerberos principal.
-expireexpdate
expiration date of the principal
-pwexpirepwexpdate
password expiration date
-maxlifemaxlife
maximum ticket life for the principal
-maxrenewlifemaxrenewlife
maximum renewable life of tickets for the principal
-kvnokvno
explicity set the key version number.
-policypolicy
policy used by this principal. If no policy is supplied, then if the
policy "default" exists and the -clearpolicy is not also specified,
then the policy "default" is used; otherwise, the principal
will have no policy, and a warning message will be printed.
-clearpolicy
-clearpolicy
prevents the policy "default" from being assigned when
-policy
is not specified. This option has no effect if the policy "default"
does not exist.
{-|+}allow_postdated
-allow_postdated
prohibits this principal from obtaining postdated tickets. (Sets the
KRB5_KDB_DISALLOW_POSTDATED
flag.)
+allow_postdated
clears this flag.
{-|+}allow_forwardable
-allow_forwardable
prohibits this principal from obtaining forwardable tickets. (Sets the
KRB5_KDB_DISALLOW_FORWARDABLE
flag.)
+allow_forwardable
clears this flag.
{-|+}allow_renewable
-allow_renewable
prohibits this principal from obtaining renewable tickets. (Sets the
KRB5_KDB_DISALLOW_RENEWABLE
flag.)
+allow_renewable
clears this flag.
{-|+}allow_proxiable
-allow_proxiable
prohibits this principal from obtaining proxiable tickets. (Sets the
KRB5_KDB_DISALLOW_PROXIABLE
flag.)
+allow_proxiable
clears this flag.
{-|+}allow_dup_skey
-allow_dup_skey
Disables user-to-user authentication for this principal by prohibiting
this principal from obtaining a session key for another user. (Sets the
KRB5_KDB_DISALLOW_DUP_SKEY
flag.)
+allow_dup_skey
clears this flag.
{-|+}requires_preauth
+requires_preauth
requires this principal to preauthenticate before being allowed to
kinit. (Sets the
KRB5_KDB_REQUIRES_PRE_AUTH
flag.)
-requires_preauth
clears this flag.
{-|+}requires_hwauth
+requires_hwauth
requires this principal to preauthenticate using a hardware device
before being allowed to kinit. (Sets the
KRB5_KDB_REQUIRES_HW_AUTH
flag.)
-requires_hwauth
clears this flag.
{-|+}ok_as_delegate
+ok_as_delegate
sets the OK-AS-DELEGATE flag on tickets issued for use with this principal
as the service, which clients may use as a hint that credentials can and
should be delegated when authenticating to the service. (Sets the
KRB5_KDB_OK_AS_DELEGATE
flag.)
-ok_as_delegate
clears this flag.
{-|+}allow_svr
-allow_svr
prohibits the issuance of service tickets for this principal. (Sets the
KRB5_KDB_DISALLOW_SVR
flag.)
+allow_svr
clears this flag.
{-|+}allow_tgs_req
-allow_tgs_req
specifies that a Ticket-Granting Service (TGS) request for a service
ticket for this principal is not permitted. This option is useless for
most things.
+allow_tgs_req
clears this flag. The default is
+allow_tgs_req.
In effect,
-allow_tgs_req
sets the
KRB5_KDB_DISALLOW_TGT_BASED
flag on the principal in the database.
{-|+}allow_tix
-allow_tix
forbids the issuance of any tickets for this principal.
+allow_tix
clears this flag. The default is
+allow_tix.
In effect,
-allow_tix
sets the
KRB5_KDB_DISALLOW_ALL_TIX
flag on the principal in the database.
{-|+}needchange
+needchange
sets a flag in attributes field to force a password change;
-needchange
clears it. The default is
-needchange.
In effect,
+needchange
sets the
KRB5_KDB_REQUIRES_PWCHANGE
flag on the principal in the database.
{-|+}password_changing_service
+password_changing_service
sets a flag in the attributes field marking this as a password change
service principal (useless for most things).
-password_changing_service
clears the flag. This flag intentionally has a long name. The default
is
-password_changing_service.
In effect,
+password_changing_service
sets the
KRB5_KDB_PWCHANGE_SERVICE
flag on the principal in the database.
-randkey
sets the key of the principal to a random value
-pwpassword
sets the key of the principal to the specified string and does not
prompt for a password. Note: using this option in a shell script can
be dangerous if unauthorized users gain read access to the script.
-e"enc:salt ..."
uses the specified list of enctype-salttype pairs for setting the key
of the principal. The quotes are necessary if there are multiple
enctype-salttype pairs. This will not function against kadmin
daemons earlier than krb5-1.2.
EXAMPLE:
kadmin: addprinc tlyu/admin
WARNING: no policy specified for "tlyu/admin@BLEEP.COM";
defaulting to no policy.
Enter password for principal tlyu/admin@BLEEP.COM:
Re-enter password for principal tlyu/admin@BLEEP.COM:
Principal "tlyu/admin@BLEEP.COM" created.
kadmin:
kadmin: addprinc -x dn=cn=mwm_user,o=org mwm_user
WARNING: no policy specified for "mwm_user@BLEEP.COM";
defaulting to no policy.
Enter password for principal mwm_user@BLEEP.COM:
Re-enter password for principal mwm_user@BLEEP.COM:
Principal "mwm_user@BLEEP.COM" created.
kadmin:
ERRORS:
KADM5_AUTH_ADD (requires "add" privilege)
KADM5_BAD_MASK (shouldn't happen)
KADM5_DUP (principal exists already)
KADM5_UNK_POLICY (policy does not exist)
KADM5_PASS_Q_* (password quality violations)
delete_principal [-force] principal
deletes the specified principal from the database. This command prompts
for deletion, unless the
-force
option is given. This command requires the
delete
privilege. Aliased
to
delprinc.
EXAMPLE:
kadmin: delprinc mwm_user
Are you sure you want to delete the principal
"mwm_user@BLEEP.COM"? (yes/no): yes
Principal "mwm_user@BLEEP.COM" deleted.
Make sure that you have removed this principal from
all ACLs before reusing.
kadmin:
ERRORS:
KADM5_AUTH_DELETE (reequires "delete" privilege)
KADM5_UNK_PRINC (principal does not exist)
modify_principal [options] principal
modifies the specified principal, changing the fields as specified. The
options are as above for
add_principal,
except that password changing and flags related to password changing
are forbidden by this command. In addition, the option
-clearpolicy
will clear the current policy of a principal. This command requires the
modify
privilege. Aliased to
modprinc.
-xdb_princ_args
Denotes the database specific options. The options for LDAP database are:
-x tktpolicy=<policy>
Associates a ticket policy to the Kerberos principal.
-x linkdn=<dn>
Associates a Kerberos principal with a LDAP object. This option is honored only
if the Kerberos principal is not already associated with a LDAP object.
ERRORS:
KADM5_AUTH_MODIFY (requires "modify" privilege)
KADM5_UNK_PRINC (principal does not exist)
KADM5_UNK_POLICY (policy does not exist)
KADM5_BAD_MASK (shouldn't happen)
change_password [options] principal
changes the password of
principal.
Prompts for a new password if neither
-randkey
or
-pw
is specified. Requires the
changepw
privilege, or that the principal that is running the program to be the
same as the one changed. Aliased to
cpw.
The following options are available:
-randkey
sets the key of the principal to a random value
-pwpassword
set the password to the specified string. Not recommended.
-e"enc:salt ..."
uses the specified list of enctype-salttype pairs for setting the key
of the principal. The quotes are necessary if there are multiple
enctype-salttype pairs. This will not function against kadmin
daemons earlier than krb5-1.2.
-keepold
Keeps the previous kvno's keys around. There is no
easy way to delete the old keys, and this flag is usually not
necessary except perhaps for TGS keys. Don't use this flag unless you
know what you're doing. This option is not supported for the LDAP database.
KADM5_AUTH_MODIFY (requires the modify privilege)
KADM5_UNK_PRINC (principal does not exist)
KADM5_PASS_Q_* (password policy violation errors)
KADM5_PADD_REUSE (password is in principal's password
history)
KADM5_PASS_TOOSOON (current password minimum life not
expired)
get_principal [-terse] principal
gets the attributes of
principal.
Requires the
inquire
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 quoted tab-separated strings. Alias
getprinc.
EXAMPLES:
kadmin: getprinc tlyu/admin
Principal: tlyu/admin@BLEEP.COM
Expiration date: [never]
Last password change: Mon Aug 12 14:16:47 EDT 1996
Password expiration date: [none]
Maximum ticket life: 0 days 10:00:00
Maximum renewable life: 7 days 00:00:00
Last modified: Mon Aug 12 14:16:47 EDT 1996 (bjaspan/admin@BLEEP.COM)
Last successful authentication: [never]
Last failed authentication: [never]
Failed password attempts: 0
Number of keys: 2
Key: vno 1, DES cbc mode with CRC-32, no salt
Key: vno 1, DES cbc mode with CRC-32, Version 4
Attributes:
Policy: [none]
kadmin: getprinc -terse systest
systest@BLEEP.COM 3 86400 604800 1
785926535 753241234 785900000
tlyu/admin@BLEEP.COM 786100034 0 0
kadmin:
ERRORS:
KADM5_AUTH_GET (requires the get (inquire) privilege)
KADM5_UNK_PRINC (principal does not exist)
list_principals [expression]
Retrieves all or some principal names.
Expression
is a shell-style glob expression that can contain the wild-card
characters ?, *, and []'s. All principal names matching the
expression are printed. If no expression is provided, all principal
names are printed. If the expression does not contain an "@" character,
an "@" character followed by the local realm is appended to the
expression. Requires the
list
priviledge. Alias
listprincs,
get_principals,
get_princs.
KADM5_AUTH_ADD (requires the add privilege)
KADM5_DUP (policy already exists)
delete_policy [-force]policy
deletes the named policy. Prompts for confirmation before deletion.
The command will fail if the policy is in use by any principals.
Requires the
delete
privilege. Alias
delpol.
EXAMPLE:
kadmin: del_policy guests
Are you sure you want to delete the policy "guests"?
(yes/no): yes
kadmin:
ERRORS:
KADM5_AUTH_DELETE (requires the delete privilege)
KADM5_UNK_POLICY (policy does not exist)
KADM5_POLICY_REF (reference count on policy is not zero)
modify_policy [options] policy
modifies the named policy. Options are as above for
add_policy.
Requires the
modify
privilege. Alias
modpol.
ERRORS:
KADM5_AUTH_MODIFY (requires the modify privilege)
KADM5_UNK_POLICY (policy does not exist)
get_policy [-terse] policy
displays the values of the named policy. Requires the
inquire
privilege. With the
-terse
flag, outputs the fields as quoted strings separated by tabs. Alias
getpol.
EXAMPLES:
kadmin: get_policy admin
Policy: admin
Maximum password life: 180 days 00:00:00
Minimum password life: 00:00:00
Minimum password length: 6
Minimum number of password character classes: 2
Number of old keys kept: 5
Reference count: 17
kadmin: get_policy -terse admin
admin 15552000 0 6 2 5 17
kadmin:
ERRORS:
KADM5_AUTH_GET (requires the get privilege)
KADM5_UNK_POLICY (policy does not exist)
list_policies [expression]
Retrieves all or some policy names.
Expression
is a shell-style glob expression that can contain the wild-card
characters ?, *, and []'s. All policy names matching the expression
are printed. If no expression is provided, all existing policy names
are printed. Requires the
list
priviledge. Alias
listpols,
get_policies,
getpols.
[-norandkey] [[principal | -globprinc-exp] [...]
Adds a principal or all principals matching
princ-exp
to a keytab.
It randomizes each principal's key in the process, to prevent a
compromised admin account from reading out all of the keys from the
database. However,
kadmin.local
has the
-norandkey
option, which leaves the keys and their version numbers unchanged,
similar to the Kerberos V4
ext_srvtab
command.
That allows users to continue to use the passwords they know
to login normally, while simultaneously allowing scripts
to login to the same account using a keytab.
There is no significant security risk added since
kadmin.local
must be run by root on the KDC anyway.
Requires the
inquire
and
changepw
privileges. 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. If the
-k
argument is not specified, the default keytab
/etc/krb5.keytab
is used. If the
-q
option is specified, less verbose status information is displayed.
The
-glob
option requires the
list
privilege.
princ-exp
follows the same rules described for the
list_principals
command.
EXAMPLE:
kadmin: ktadd -k /tmp/foo-new-keytab host/foo.mit.edu
Entry for principal host/foo.mit.edu@ATHENA.MIT.EDU with
kvno 3, encryption type DES-CBC-CRC added to keytab
WRFILE:/tmp/foo-new-keytab
kadmin:
ktremove [-kkeytab] [-q] principal [kvno | all | old]
Removes entries for the specified principal from a keytab. Requires no
permissions, since this does not require database access. If the string
"all" is specified, all entries for that principal are removed; if the
string "old" is specified, all entries for that principal except those
with the highest kvno are removed. Otherwise, the value specified is
parsed as an integer, and all entries whose kvno match that integer are
removed. If the
-k
argument is not specifeid, the default keytab
/etc/krb5.keytab
is used. If the
-q
option is specified, less verbose status information is displayed.
EXAMPLE:
kadmin: ktremove -k /usr/local/var/krb5kdc/kadmind.keytab kadmin/admin
Entry for principal kadmin/admin with kvno 3 removed
from keytab WRFILE:/usr/local/var/krb5kdc/kadmind.keytab.
kadmin:
FILES
principal.db
default name for Kerberos principal database
<dbname>.kadm5
KADM5 administrative database. (This would be "principal.kadm5", if you
use the default database name.) Contains policy information.
<dbname>.kadm5.lock
lock file for the KADM5 administrative database. This file works
backwards from most other lock files. I.e.,
kadmin
will exit with an error if this file does
not
exist.
Note:
The above three files are specific to db2 database.
kadm5.acl
file containing list of principals and their
kadmin
administrative privileges. See
kadmind(8)
for a description.
kadm5.keytab
keytab file for
kadmin/admin
principal.
kadm5.dict
file containing dictionary of strings explicitly disallowed as
passwords.
HISTORY
The
kadmin
prorgam was originally written by Tom Yu at MIT, as an interface to the
OpenVision Kerberos administration program.
There is no way to delete a key kept around from a "-keepold" option
to a password-changing command, other than to do a password change
without the "-keepold" option, which will of course cause problems if
the key is a TGS key. There will be more powerful key-manipulation
commands in the future.