path: root/src/kadmin/cli/kadmin.1

KADMIN(8)		USER_COMMANDS			KADMIN(8)

NAME
	kadmin - a command line interface to the Kerberos KADM5
	administration system

SYNOPSIS
	kadmin [-r realm] [-p principal] [-q query] [clnt|local args]
	    clnt args: [-p principal] [[-c ccache]|[-k [-t keytab]]]
		       [-w] [-s admin_server[:port]]
	    local args: [-d dbname] [-e \"enc:salt ...\"] [-m]

DESCRIPTION
	kadmin is a command-line interface to the Kerberos KADM5
	administration system.  It provides for the maintainance of
	Kerberos principals, KADM5 policies, and service key tables
	(keytabs).  It exists as both a remote client, using Kerberos
	authentication and an encrypted RPC to operate securely from
	anywhere on the network, and as a local client intended to run
	directly on the 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.

COMMAND LINE ARGUMENTS
	If -r is specified, then kadmin will use the specified realm
	as the default database realm rather than the default realm
	for the local machine.

	The -q option allows the passing of a request directly to
	kadmin, which will then exit.  This can be useful for writing
	scripts.

	The remote version authenticates to the KADM5 server using the
	service kadmin/admin, and therefore needs a client Kerberos
	principal name as which to authenticate.  The -p, -c, and -k
	are designed to work together to specify which principal as
	which to authenticate and where the service ticket or
	password/key for that principal should be obtained.  If given
	the -p option, kadmin will use the specified principal to
	authenticate.  Otherwise, if given -c option then the primary
	principal name of the ccache is used.  Otherwise, if given the
	-k option, the principal name host/<hostname> is used.
	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.

	Once kadmin knows the principal name as which to authenticate,
	it needs to acquire a Kerberos service ticket for the KADM5
	server.  If the -c ccache argument is specified, the ccache
	should contain a service ticket for the kadmin/admin service;
	it can be acquired with the kinit(1) program.  Otherwise,
	kadmin requests a new service ticket from the KDC and stores
	it in its own temporary ccache.  If the -k keytab argument is
	specified, the keytab is used to decrypt the KDC response;
	otherwise, a password is required.  By default, the user is
	prompted for the password on the TTY.  However, if given the
	-w option, kadmin will use the password provided on the
	command line instead of prompting for one on the TTY.
	WARNING!  Placing the password for a Kerberos principal with
	administration access into a shell script is EXTREMELY
	DANGEROUS and should only be done if you are highly sure that
	the script will not fall into the wrong hands.

	If given the -d argument, kadmin will use the specified
	database name instead of the default defined in kdc.conf.
	Note that specifying a different KDC database name also
	specifies a different name for the KADM5 policy database and
	lock file.

	If given the -e argument, kadmin will use the specified list
	of encryption and salt type tuples instead of the values
	specified in kdc.conf.  This is useful, for example, if you
	want to create a single principal with a particular key/salt
	type without affecting any other principals.

	If given the -m argument, kadmin will prompt for the Kerberos
	master password on the command line instead of attempting to
	use the stash file.

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
		last Monday
		yesterday
		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" on a duration may
	result in unexpected behaviour.

COMMAND DESCRIPTIONS

add_principal [options] _newprinc_
	creates the principal _newprinc_, prompting twice for a
	password.  This command requires the "add" privilege.  This
	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

	-pwexpire _pwexpdate_
		password expiration date

	-maxlife _maxlife_
		maximum ticket life of the principal

	-maxrenewlife _maxrenewlife_
		maximum renewable ticket lifetime of the principal

	-kvno _kvno_
		explicity set the key version number.  This is not
		recommended.

	-policy _policy_
		policy used by this principal.  If no policy is
		supplied, the principal will default to having no
		policy, and a warning message will be printed.

	{-|+}allow_tgs_req
		"-allow_tgs_req" specifies that a TGS request for a
		ticket 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.

	-randpass
		sets the key of the principal to a random value

	-pw _password_
		sets the key of the principal to the specified string
		and does not prompt for a password.  This is not
		recommended.

	EXAMPLE
	kadmin: addprinc tlyu/deity
	WARNING: no policy specified for "tlyu/deity@ATHENA.MIT.EDU";
	defaulting to no policy.
	Enter password for principal tlyu/deity@ATHENA.MIT.EDU:
	Re-enter password for principal tlyu/deity@ATHENA.MIT.EDU:
	Principal "tlyu/deity@ATHENA.MIT.EDU" 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@ATHENA.MIT.EDU"? (yes/no): yes
	Principal "mwm_user@ATHENA.MIT.EDU" 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 is forbidden by this command.
	In addition, the option "-clearpolicy" will remove clear the
	current	policy of a principal.  This command requires the
	"modify" privilege.  Aliased to "modprinc".

	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 -randpass or -pw is specified.  Requires
	the "modify" privilege, or that the principal that is running
	the program to be the same as the one changed.  Aliased to
	"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
		sets the key of the principal to a random value

	-pw _password_
		set the password to the specified string.  Not
		recommended.

	EXAMPLE
	kadmin: cpw systest
	Enter password for principal systest@ATHENA.MIT.EDU:
	Re-enter password for principal systest@ATHENA.MIT.EDU:
	Password for systest@ATHENA.MIT.EDU changed.
	kadmin:

	ERRORS
	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 istory)
	KADM5_PASS_TOOSOON (current password minimum life not xpired)

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

	EXAMPLES
	kadmin: getprinc tlyu/deity
	Principal: tlyu/deity@ATHENA.MIT.EDU
	Key version: 3
	Maximum life: 1 day 00:00:00
	Maximum renewable life: 7 days 00:00:00
	Master key version: 1
	Expires: Mon Jan 18 22:14:07 EDT 2038
	Password expires: Mon Sep 19 14:40:00 EDT 1994
	Password last changed: Mon Jan 31 02:06:40 EDT 1994
	Last modified: by tlyu/admin@ATHENA.MIT.EDU
		on Wed Jul 13 18:27:08 EDT 1994
	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:

	ERRORS
	KADM5_AUTH_GET (requires the get privilege)
	KADM5_UNK_PRINC (principal does not exist)

get_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, the
	expression "*" is assumed.  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 "getprincs".

	EXAMPLES
	kadmin:  getprincs test*
	test3@SECURE-TEST.OV.COM
	test2@SECURE-TEST.OV.COM
	test1@SECURE-TEST.OV.COM
	testuser@SECURE-TEST.OV.COM
	kadmin:

add_policy [options] _policy_
	adds the named policy to the policy database.  Requires the
	"add" privilege.  Aliased to "addpol".

	OPTIONS
	-maxlife _time_
		sets the maximum lifetime of a password

	-minlife _time_
		sets the minimum lifetime of a password

	-minlength _length_
		sets the minimum length of a password

	-minclasses _number_
		sets the minimum number of character classes allowed
		in a password

	-history _number_
		sets the number of past keys kept for a principal

	ERRORS
	KADM5_AUTH_ADD (requires the add privilege)
	KADM5_DUP (policy already exists)

delete_policy _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
	Policy "guests" deleted.
	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 "get"
	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)

get_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, the
	expression "*" is assumed.  Requires the "list" priviledge.
	Alias "getpols".

	EXAMPLES
	kadmin:  getpols
	test-pol
	dict-only
	once-a-min
	test-pol-nopw
	kadmin:  getpols t*
	test-pol
	test-pol-nopw
	kadmin:

ktadd [-k keytab] [-q] [principal | -glob princ-exp] [...]
	Adds principal or all principals matching princ-exp to a
	keytab.  princ-exp follows the same rules described for the
	get_principals command.  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/v5srvtab is
	used.  If the -q option is specified, less verbose status
	information is displayed.

	The -glob option requires the "list" privilege.

	EXAMPLES
	kadmin% ktadd -k /krb5/kadmind.keytab kadmin/admin kadmin/changepw
	kadmin: Entry for principal kadmin/admin@ATHENA.MIT.EDU with
		kvno 3, encryption type DES-CBC-CRC added to keytab
		WRFILE:/krb5/kadmind.keytab.
	kadmin: Entry for principal kadmin/changepw@ATHENA.MIT.EDU
		with kvno 3, encryption type DES-CBC-CRC added to keytab
		WRFILE:/krb5/kadmind.keytab.
	kadmin:

ktremove [-k keytab] [-q] principal [kvno|"all"|"old"]
	Removes entries for the specified principal from a keytab.  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/v5srvtab
	is used.  If the -q is specified, less verbose status
	information is displayed.

	EXAMPLES
	kadmin: ktremove -k /krb5/kadmind.keytab kadmin/admin
	kadmin: Entry for principal kadmin/admin with kvno 3 removed
		from keytab WRFILE:/krb5/kadmind.keytab.
	kadmin:

SEE ALSO
	kerberos(1), kdb5_util(8)