-k5srvutil - host key table (keytab) manipulation utility
+.. _k5srvutil(1):
+
+k5srvutil
=============================================================
SYNOPSIS
+.. _kadmin(1):
+
+.. _kadmin.local(1):
+
kadmin, kadmin.local
===========================
SYNOPSYS
--------------
+
+.. _kadmin_synopsys:
**kadmin**
[ **-O** | **-N** ]
[**-x** *db_args*]
+.. _kadmin_synopsys_end:
+
DESCRIPTION
------------
OPTIONS
------------
+.. _kadmin_options:
+
**-r** *realm*
- Use realm as the default database realm.
+ Use *realm* as the default database realm.
**-p** *principal*
- Use principal to authenticate. Otherwise, *kadmin* will append "/admin" to the primary principal name of the default ccache, the
+ 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**
**-c** *credentials_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
+ it can be acquired with the :ref:`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.
**-w** *password*
**-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*.
+ Instead, the password can be stashed using the stashsrvpw command of :ref:`kdb5_ldap_util(8)`
+
+
+.. _kadmin_options_end:
DATE FORMAT
--------------
-Various commands in *kadmin* can take a variety of date formats, specifying durations or absolute times.
-Examples of valid formats are::
+.. _date_format:
+
+Many of the *kadmin* commands take a duration or time as an argument. The date can appear in a wide variety of formats, such as::
1 month ago
2 hours ago
tomorrow
now
second Monday
- a fortnight ago
+ fortnight ago
3/31/92 10:00:07 PST
January 23, 1987 10:05pm
22:00 GMT
Specifying "ago" in a duration may result in unexpected behavior.
+The following is a list of all of the allowable keywords.
+
+========================== ============================================
+Months january, jan, february, feb, march, mar, april, apr, may, june, jun, july, jul, august, aug, september, sep, sept, october, oct, november, nov, december, dec
+Days sunday, sun, monday, mon, tuesday, tues, tue, wednesday, wednes, wed, thursday, thurs, thur, thu, friday, fri, saturday, sat
+Units year, month, fortnight, week, day, hour, minute, min, second, sec
+Relative tomorrow, yesterday, today, now, last, this, next, first, second, third, fourth, fifth, sixth, seventh, eighth, ninth, tenth, eleventh, twelfth, ago
+Time Zones kadmin recognizes abbreviations for most of the world's time zones. A complete listing appears in kadmin Time Zones.
+12-hour Time Delimiters am, pm
+========================== ============================================
+
+.. _date_format_end:
+
+
+
COMMANDS
-----------
+.. _add_principal:
+
+add_principal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
**add_principal** [options] *newprinc*
- creates the principal newprinc, prompting twice for a password. If no policy is specified with the *-policy* option,
+ 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.
The options are:
**-x** *db_princ_args*
- Denotes the database specific options. The options for LDAP database are:
+ 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** tktpolicy=<policy>
Associates a ticket policy to the Kerberos principal.
+
+ .. note::
+ - *containerdn* and *linkdn* options cannot be specified with dn option.
+ - If *dn* or *containerdn* options are not specified while adding the principal, the principals are created under the prinicipal container configured in the realm or the realm container.
+ - *dn* and *containerdn* should be within the subtrees or principal container configured in the realm.
+
+
**-expire** *expdate*
expiration date of the principal
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:
+
+ kadmin: addprinc jennifer
+ WARNING: no policy specified for "jennifer@ATHENA.MIT.EDU";
+ defaulting to no policy.
+ Enter password for principal jennifer@ATHENA.MIT.EDU: <= Type the password.
+ Re-enter password for principal jennifer@ATHENA.MIT.EDU: <=Type it again.
+ Principal "jennifer@ATHENA.MIT.EDU" created.
+ kadmin:
ERRORS::
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.
-
- .. note:: This command requires the *delete* privilege.
-
- Alias::
-
- delprinc
-
-
- EXAMPLE::
+.. _add_principal_end:
- 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:
+.. _modify_principal:
- ERRORS::
-
- KADM5_AUTH_DELETE (reequires "delete" privilege)
- KADM5_UNK_PRINC (principal does not exist)
+modify_principal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**modify_principal** [options] *principal*
Modifies the specified principal, changing the fields as specified. The options are as above for *add_principal*, except that
The options are:
**-x** *db_princ_args*
- Denotes the database specific options. The options for LDAP database are:
+ Denotes the database specific options.
+
+ The options for LDAP database are:
**-x** tktpolicy=<policy>
Associates a ticket policy to the Kerberos principal.
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.
- *-unlock*
+ **-unlock**
Unlocks a locked principal (one which has received too many failed authentication attempts without enough time between
them according to its password policy) so that it can successfully authenticate.
KADM5_UNK_POLICY (policy does not exist)
KADM5_BAD_MASK (shouldn't happen)
+.. _modify_principal_end:
+
+.. _delete_principal:
+
+delete_principal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ **delete_principal** [ *-force* ] *principal*
+ Deletes the specified *principal* from the database. This command prompts for deletion, unless the *-force* option is given.
+
+ .. note:: This command requires the *delete* privilege.
+
+ Alias::
+
+ delprinc
+
+
+ ERRORS::
+
+ KADM5_AUTH_DELETE (reequires "delete" privilege)
+ KADM5_UNK_PRINC (principal does not exist)
+
+.. _delete_principal_end:
+
+.. _change_password:
+
+change_password
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
**change_password** [options] *principal*
- Changes the password of principal. Prompts for a new password if neither *-randkey* or *-pw* is specified.
+ Changes the password of *principal*. Prompts for a new password if neither *-randkey* or *-pw* is specified.
.. note:: Requires the *changepw* privilege, or that the principal that is running the program to be the same as the one changed.
**-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.
+ See :ref:`Supported_Encryption_Types_and_Salts` for possible values.
**-keepold**
Keeps the previous kvno's keys around. This flag is usually not necessary except perhaps for TGS keys. Don't use this
KADM5_PASS_TOOSOON (current password minimum life not
expired)
+
+.. _change_password_end:
+
+.. _purgekeys:
+
+purgekeys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
**purgekeys** [*-keepkvno oldest_kvno_to_keep* ] *principal*
Purges previously retained old keys (e.g., from *change_password -keepold*) from *principal*.
- If *-keepkvno* is specified, then only purges keys with kvnos lower than oldest_kvno_to_keep.
+ If **-keepkvno** is specified, then only purges keys with kvnos lower than *oldest_kvno_to_keep*.
+
+.. _get_principal:
+
+get_principal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**get_principal** [*-terse*] *principal*
Gets the attributes of principal.
- With the *-terse* option, outputs fields as quoted tab-separated strings.
+ With the **-terse** option, outputs fields as quoted tab-separated strings.
.. note:: Requires the *inquire* privilege, or that the principal that is running the the program to be the same as the one being listed.
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)
+.. _get_principal_end:
+
+.. _list_principals:
+
+list_principals
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
**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.
testuser@SECURE-TEST.OV.COM
kadmin:
+.. _list_principals_end:
+
+.. _add_policy:
+
+add_policy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
**add_policy** [options] *policy*
Adds the named *policy* to the policy database.
The following options are available:
- *-maxlife time*
+ **-maxlife time**
sets the maximum lifetime of a password
- *-minlife time*
+ **-minlife time**
sets the minimum lifetime of a password
- *-minlength length*
+ **-minlength length**
sets the minimum length of a password
- *-minclasses number*
+ **-minclasses number**
sets the minimum number of character classes allowed in a password
- *-history number*
+ **-history number**
sets the number of past keys kept for a principal. This option is not supported for LDAP database
- *-maxfailure maxnumber*
+ **-maxfailure maxnumber**
sets the maximum number of authentication failures before the principal is locked.
Authentication failures are only tracked for principals which require preauthentication.
- *-failurecountinterval failuretime*
+ **-failurecountinterval failuretime**
sets the allowable time between authentication failures.
If an authentication failure happens after *failuretime* has elapsed since the previous failure,
the number of authentication failures is reset to 1.
- *-lockoutduration lockouttime*
+ **-lockoutduration lockouttime**
sets the duration for which the principal is locked from authenticating if too many authentication failures occur without
the specified failure count interval elapsing.
KADM5_AUTH_ADD (requires the add privilege)
KADM5_DUP (policy already exists)
+.. _add_policy_end:
+
+.. _modify_policy:
+
+modify_policy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ **modify_policy** [options] *policy*
+ modifies the named *policy*. Options are as above for *add_policy*.
+
+ .. note:: Requires the *modify* privilege.
+
+ Alias::
+
+ modpol
+
+
+ ERRORS::
+
+ KADM5_AUTH_MODIFY (requires the modify privilege)
+ KADM5_UNK_POLICY (policy does not exist)
+
+.. _modify_policy_end:
+
+.. _delete_policy:
+
+delete_policy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
**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.
- ..note:: Requires the *delete* privilege.
+ .. note:: Requires the *delete* privilege.
Alias::
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*.
-
- .. note:: Requires the *modify* privilege.
-
- Alias::
-
- modpol
-
+.. _delete_policy_end:
- ERRORS::
+.. _get_policy:
- KADM5_AUTH_MODIFY (requires the modify privilege)
- KADM5_UNK_POLICY (policy does not exist)
+get_policy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- **get_policy** [ *-terse* ] *policy*
+ **get_policy** [ **-terse** ] *policy*
displays the values of the named *policy*.
- With the *-terse* flag, outputs the fields as quoted strings separated by tabs.
+ With the **-terse** flag, outputs the fields as quoted strings separated by tabs.
.. note:: Requires the *inquire* privilege.
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:
+The *Reference count* is the number of principals using that policy.
+
ERRORS::
KADM5_AUTH_GET (requires the get privilege)
KADM5_UNK_POLICY (policy does not exist)
+.. _get_policy_end:
+
+.. _list_policies:
+
+list_policies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
**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.
dict-only
once-a-min
test-pol-nopw
+
kadmin: listpols t*
test-pol
test-pol-nopw
kadmin:
+.. _list_policies_end:
+
+.. _ktadd:
+
+ktadd
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
**ktadd** [**-k** *keytab*] [**-q**] [**-e** *keysaltlist*] [**-norandkey**] [[*principal* | **-glob** *princ-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.
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.
+ The **-glob** option requires the *list* privilege. *princ-exp* follows the same rules described for the *list_principals* command.
EXAMPLE::
WRFILE:/tmp/foo-new-keytab
kadmin:
+.. _ktremove:
+
+ktremove
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
**ktremove** [**-k** *keytab*] [**-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
<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.
+.. note:: The above three files are specific to db2 database.
====================== =================================================
-kadm5.acl File containing list of principals and their *kadmin* administrative privileges. See :ref:`kadmind(8)` for a description.
+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.
====================== =================================================
-kdb5_ldap_util - Kerberos configuration utility
+.. _kdb5_ldap_util(8):
+
+kdb5_ldap_util
==================================================
SYNOPSIS
Application servers
==========================
-If you need to install the Kerberos V5 programs on an application server, please refer to the Kerberos V5 Installation Guide. Once you have installed the software, you need to add that host to the Kerberos database (see :ref:`add_mod_princs_label`), and generate a keytab for that host, that contains the host's key. You also need to make sure the host's clock is within your maximum clock skew of the KDCs.
+If you need to install the Kerberos V5 programs on an application server, please refer to the Kerberos V5 Installation Guide. Once you have installed the software, you need to add that host to the Kerberos database (see :ref:`add_mod_del_princs_label`), and generate a keytab for that host, that contains the host's key. You also need to make sure the host's clock is within your maximum clock skew of the KDCs.
.. toctree::
-k[eytab] *keytab* Use keytab as the keytab file. Otherwise, *ktadd* will use the default keytab file (*/etc/krb5.keytab*).
-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. See :ref:`Supported_Encryption_Types_and_Salts` for all possible values.
-q Run in quiet mode. This causes *ktadd* to display less verbose information.
-principal | -glob *principal expression* Add principal, or all principals matching principal expression to the keytab. The rules for principal expression are the same as for the kadmin list_principals (see :ref:`get_list_princs`) command.
+principal | -glob *principal expression* Add principal, or all principals matching principal expression to the keytab. The rules for principal expression are the same as for the kadmin :ref:`list_principals` command.
============================================= =================================================================
Here is a sample session, using configuration files that enable only *des-cbc-crc* encryption. (The line beginning with => is a continuation of the previous line.)::
Date Format
===============
-Many of the kadmin commands take a duration or time as an argument. The date can appear in a wide variety of formats, such as::
+.. include:: ../admin_commands/kadmin_local.rst
+ :start-after: _date_format:
+ :end-before: _date_format_end:
- "15 minutes"
- "7 days"
- "1 month"
- "2 hours"
- "400000 seconds"
- "next year"
- "this Monday"
- "next Monday"
- yesterday
- tomorrow
- now
- "second Monday"
- fortnight
- "3/31/1992 10:00:07 PST"
- "January 23, 2007 10:05pm"
- "22:00 GMT"
-
+.. note:: If the date specification contains spaces, you must enclose it in double quotes.
+ Note also that you cannot use a number without a unit.
+ (I.e., ""60 seconds"" is correct, but "60" is incorrect.) All keywords are case-insensitive.
-The following is a list of all of the allowable keywords.
-========================== ============================================
-Months january, jan, february, feb, march, mar, april, apr, may, june, jun, july, jul, august, aug, september, sep, sept, october, oct, november, nov, december, dec
-Days sunday, sun, monday, mon, tuesday, tues, tue, wednesday, wednes, wed, thursday, thurs, thur, thu, friday, fri, saturday, sat
-Units year, month, fortnight, week, day, hour, minute, min, second, sec
-Relative tomorrow, yesterday, today, now, last, this, next, first, second, third, fourth, fifth, sixth, seventh, eighth, ninth, tenth, eleventh, twelfth, ago
-Time Zones kadmin recognizes abbreviations for most of the world's time zones. A complete listing appears in kadmin Time Zones.
-12-hour Time Delimiters am, pm
-========================== ============================================
-
-
-.. note:: If the date specification contains spaces, you must enclose it in double quotes. Note also that you cannot use a number without a unit. (I.e., ""60 seconds"" is correct, but "60" is incorrect.) All keywords are case-insensitive.
-
-
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db
You can invoke **kadmin** or **kadmin.local** with any of the following options:
-======================= ============================================
--r *REALM* Use REALM as the default Kerberos realm for the database.
--p *principal* Use the Kerberos principal principal to authenticate to Kerberos. If this option is not given, *kadmin* will append admin to either the primary principal name, the environment variable USER, or to the username obtained from getpwuid, in order of preference.
--q *query* Pass query directly to *kadmin*. This is useful for writing scripts that pass specific queries to *kadmin*.
-======================= ============================================
-
-You can invoke **kadmin** with any of the following options:
-
-================================== ================================================
--k [-t keytab] Use the *keytab* to decrypt the KDC response instead of prompting for a password on the TTY. In this case, the principal will be *host/hostname*. If *-t* is not used to specify a keytab, then the default keytab will be used.
--c *credentials_cache* Use *credentials_cache* as the credentials cache. The credentials cache should contain a service ticket for the *kadmin/admin* service, which can be acquired with the *kinit* program. If this option is not specified, *kadmin* requests a new service ticket from the KDC, and stores it in its own temporary ccache.
--w *password* Use password as the 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.
--x *db_args* Specifies the database specific arguments.
--x host=*<hostname>* Specifies the LDAP server to connect to by a LDAP URI. It is recommend to use ldapi:// or ldaps:// interface to connect to the LDAP server.
--x binddn=*<bind_dn>* Specifies the Distinguished Name (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 realm subtree.
--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*. Note: This database specific argument is applicable only to *kadmin.local* and the KADM5 server.
--s admin_server[:port] Specifies the admin server that *kadmin* should contact.
-================================== ================================================
-
-
-You can invoke **kadmin.local** with an of the follwing options:
-
-======================= ===============================================
--d\_ *dbname* Specifies the name of the Kerberos database.
--e *"enctypes ..."* Sets the list of cryptosystem and salt types to be used for any new keys created. See Supported Encryption Types and Salts for available types.
--m Do not authenticate using a keytab. This option will cause *kadmin* to prompt for the master database password.
-======================= ===============================================
+.. include:: ../admin_commands/kadmin_local.rst
+ :start-after: kadmin_synopsys:
+ :end-before: kadmin_synopsys_end:
+
+**OPTIONS**
+
+.. include:: ../admin_commands/kadmin_local.rst
+ :start-after: _kadmin_options:
+ :end-before: _kadmin_options_end:
+
------------
.. toctree::
:maxdepth: 1
- retr_pol.rst
- retr_list_pol.rst
mod_pol.rst
- del_pol.rst
+ retr_pol.rst
update_histkey.rst
-Adding or modifying policies
-====================================
+Adding, modifying and deleting policies
+===================================================
-To add a new policy, use the kadmin *add_policy* command, which requires the "add" administrative privilege. The syntax is::
+To add a new policy, use the *kadmin* **add_policy** command.
- add_policy [options] policy_name
-
-*add_policy* has the alias **addpol**.
-
-To modify attributes of a principal, use the kadmin *modify_policy* command, which requires the "modify" administrative privilege. The syntax is::
+To modify attributes of a principal, use the *kadmin* **modify_policy** command.
- modify_policy [options] policy_name
+To delete a policy, use the *kadmin* **delete_policy** command.
-*modify_poilcy* has the alias **modpol**.
+.. include:: ../../admin_commands/kadmin_local.rst
+ :start-after: _add_policy:
+ :end-before: _add_policy_end:
-|
+.. note:: The policies are created under *realm* container in the LDAP database.
-The *add_policy* and *modify_policy* commands take the following switches:
+.. include:: ../../admin_commands/kadmin_local.rst
+ :start-after: _modify_policy:
+ :end-before: _modify_policy_end:
-========================= ==================================
--maxlife *time* Sets the maximum lifetime of a password to time.
--minlife *time* Sets the minimum lifetime of a password to time.
--minlength *length* Sets the minimum length of a password to length characters.
--minclasses *number* Requires at least number of character classes in a password.
--history *number* Sets the number of past keys kept for a principal to number. This option is not supported for LDAP database.
-========================= ==================================
+.. include:: ../../admin_commands/kadmin_local.rst
+ :start-after: _delete_policy:
+ :end-before: _delete_policy_end:
-|
+.. note:: You must cancel the policy from *all* principals before deleting it. The *delete_policy* command will fail if it is in use by any principals.
-.. note:: The policies are created under *realm* container in the LDAP database.
+
------------
-Retrieving Policies
+Retrieving policies
========================
-To retrieve a policy, use the kadmin *get_policy* command, which requires the "inquire" administrative privilege. The syntax is::
+To retrieve a policy, use the *kadmin* **get_policy** command.
- get_policy [-terse] policy
-
+You can retrieve the list of policies with the *kadmin* **list_policies** command.
-The *get_policy* command has the alias **getpol**.
+.. include:: ../../admin_commands/kadmin_local.rst
+ :start-after: _get_policy:
+ :end-before: _get_policy_end:
-For example::
- 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:
-
+.. include:: ../../admin_commands/kadmin_local.rst
+ :start-after: _list_policies:
+ :end-before: _list_policies_end:
-The reference count is the number of principals using that policy.
-The *get_policy* command has a *-terse* option, which lists each field as a quoted, tab-separated string. For example::
-
- kadmin: get_policy -terse admin
- admin 15552000 0 6 2 5 17
- kadmin:
-
------------
Feedback:
Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_policies
+
To delete a principal, use the kadmin *delete_principal* command, which requires the "delete" administrative privilege. The syntax is::
delete_principal [-force] principal
-
-*delete_principal* has the alias **delprinc**. The *-force* option causes *delete_principal* not to ask if you're sure.
-
-For example::
-
- kadmin: delprinc jennifer
- Are you sure you want to delete the principal
- "jennifer@ATHENA.MIT.EDU"? (yes/no): yes
- Principal "jennifer@ATHENA.MIT.EDU" deleted.
- Make sure that you have removed this principal from
- all ACLs before reusing.
- kadmin:
-
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_princs
+See :ref:`delete_principal` for details.
+
:maxdepth: 2
+ modify_princ.rst
info_princ.rst
priv_princ.rst
- modify_princ.rst
- delete_princ.rst
pass_princ.rst
-
Retrieving information about a principal
=============================================
+To retrieve a listing of the attributes and/or policies associated with a principal, use the *kadmin* **get_principal** command.
-Retrieving a list of attributes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To retrieve a listing of the attributes and/or policies associated with a principal, use the kadmin *get_principal* command, which requires the "inquire" administrative privilege. The syntax is::
-
- get_principal principal
-
-The *get_principal* command has the alias **getprinc**.
-
-For example, suppose you wanted to view the attributes of the principal *jennifer/root@ATHENA.MIT.EDU*. You would type::
-
- shell% kadmin
- kadmin: getprinc jennifer/root
- Principal: jennifer/root@ATHENA.MIT.EDU
- Expiration date: [never]
- Last password change: Mon Jan 31 02:06:40 EDT 2002
- Password Expiration date: [none]
- Maximum ticket life: 0 days 10:00:00
- Maximum renewable life: 7 days 00:00:00
- Last modified: Wed Jul 24 14:46:25 EDT 2002 (joeadmin/admin@ATHENA.MIT.EDU)
- Last successful authentication: Mon Jul 29 18:20:17 EDT 2002
- Last failed authentication: Mon Jul 29 18:18:54 EDT 2002
- Failed password attempts: 3
- Number of keys: 2
- Key: vno 2, Triple DES cbc mode with HMAC/sha1, no salt
- Key: vno 2, DES cbc mode with CRC-32, no salt
- Attributes: DISALLOW_FORWARDABLE, DISALLOW_PROXIABLE
- Policy: [none]
- kadmin:
-
-The *get_principal* command has a *-terse* option, which lists the fields as a quoted, tab-separated string. For example::
-
- kadmin: getprinc -terse jennifer/root
- jennifer/root@ATHENA.MIT.EDU 0 1027458564
- 0 36000 (joeadmin/admin@ATHENA.MIT.EDU
- 1027536385 18 2 0 [none] 604800 1027980137
- 1027980054 3 2 1 2 16 0 1
- 2 1 0
- kadmin:
-
-.. _get_list_princs:
-
-Retrieving a list of principals
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To generate a listing of principals, use the kadmin *list_principals* command, which requires the "list" privilege. The syntax is::
+To generate a listing of principals, use the *kadmin* **list_principals** command.
- list_principals [expression]
-
-where expression is a shell-style glob expression that can contain the characters \*, ?, [, and ]. All policy names matching the expression are displayed.
+.. include:: ../../admin_commands/kadmin_local.rst
+ :start-after: _get_principal:
+ :end-before: _get_principal_end:
-The *list_principals* command has the aliases **listprincs, get_principals**, and **getprincs**. For example::
+.. include:: ../../admin_commands/kadmin_local.rst
+ :start-after: _list_principals:
+ :end-before: _list_principals_end:
- kadmin: listprincs test*
- test3@ATHENA.MIT.EDU
- test2@ATHENA.MIT.EDU
- test1@ATHENA.MIT.EDU
- testuser@ATHENA.MIT.EDU
- kadmin:
-If no expression is provided, all principals are printed.
-
-------------
-
-Feedback:
-
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_princs
-
-.. _add_mod_princs_label:
+.. _add_mod_del_princs_label:
-Adding or modifying principals
-===================================
+Adding, modifying and deleting principals
+============================================
-To add a principal to the database, use the kadmin *add_principal* command, which requires the "add" administrative privilege. This function creates the new principal, prompting twice for a password, and, if neither the *-policy* nor *-clearpolicy* options are specified and the policy "default" exists, assigns it that policy. The syntax is::
+To add a principal to the database, use the *kadmin* **add_principal** command.
- kadmin: add_principal [options] principal
-
-*add_principali* has the aliases **addprinc** and **ank2**.
-
-
-To modify attributes of a principal, use the kadmin *modify_principal* command, which requires the "modify" administrative privilege. The syntax is::
-
- kadmin: modify_principal [options] principal
-
-*modify_principal* has the alias **modprinc**.
-
-|
-
-The *add_principal* and *modify_principal* commands take the following switches:
-
-*-x db_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. Specifying an empty string value clears the ticket policy associated with the principal.
-
-.. note::
- - *dn* and *containerdn* options are not valid while modifying the principal.
- - *containerdn* and *linkdn* options cannot be specified with dn option.
- - If *dn* or *containerdn* options are not specified while adding the principal, the principals are created under the prinicipal container configured in the realm or the realm container.
- - *dn* and *containerdn* should be within the subtrees or principal container configured in the realm.
-
-*-expire date*
-Sets the expiration date of the principal to date.
-
-*-pwexpire date*
-Sets the expiration date of the password to date.
-
-*-maxlife maxlife*
-Sets the maximum ticket life of the principal to maxlife.
-
-*-maxrenewlife maxrenewlife*
-Sets the maximum renewable life of tickets for the principal to maxrenewlife.
-
-*-kvno number*
-Explicity sets the key version number to number. MIT does not recommend doing this unless there is a specific reason.
-
-*-policy policy*
-Sets the policy used by this principal. (See :ref:`db_policies_label`) With *modify_principal*, the current policy assigned to the principal is set or changed. With *add_principal*, if this option is not supplied, the *-clearpolicy* is not specified, and the policy "default" exists, that policy is assigned. If a principal is created with no policy, kadmin will print a warning message.
-
-*-clearpolicy*
-For *modify_principal*, removes the current policy from a principal. For *add_principal*, suppresses the automatic assignment of the policy "default".
+To modify attributes of a principal, use the *kadmin* **modify_principal** command.
-*{-|+}allow_postdated*
-The "-allow_postdated" option prohibits this principal from obtaining postdated tickets. "+allow_postdated" clears this flag. In effect, "-allow_postdated" sets the KRB5_KDB_DISALLOW_POSTDATED flag on the principal in the database.
+To delete a principal, use the *kadmin* **delete_principal** command.
-*{-|+}allow_forwardable*
-The "-allow_forwardable" option prohibits this principal from obtaining forwardable tickets. "+allow_forwardable" clears this flag. In effect, "-allow_forwardable" sets the KRB5_KDB_DISALLOW_FORWARDABLE flag on the principal in the database.
-*{-|+}allow_renewable*
-The "-allow_renewable" option prohibits this principal from obtaining renewable tickets. "+allow_renewable" clears this flag. In effect, "-allow_renewable" sets the KRB5_KDB_DISALLOW_RENEWABLE flag on the principal in the database.
+.. include:: ../../admin_commands/kadmin_local.rst
+ :start-after: _add_principal:
+ :end-before: _add_principal_end:
-*{-|+}allow_proxiable*
-The "-allow_proxiable" option prohibits this principal from obtaining proxiable tickets. "+allow_proxiable" clears this flag. In effect, "-allow_proxiable" sets the
-KRB5_KDB_DISALLOW_PROXIABLE flag. on the principal in the database.
+.. include:: ../../admin_commands/kadmin_local.rst
+ :start-after: _modify_principal:
+ :end-before: _modify_principal_end:
-*{-|+}allow_dup_skey*
-The "-allow_dup_skey" option disables user-to-user authentication for this principal by prohibiting this principal from obtaining a session key for another user. "+allow_dup_skey" clears this flag. In effect, "-allow_dup_skey" sets the
-KRB5_KDB_DISALLOW_DUP_SKEY flag on the principal in the database.
+.. include:: ../../admin_commands/kadmin_local.rst
+ :start-after: _delete_principal:
+ :end-before: _delete_principal_end:
-*{-|+}requires_preauth*
-The "+requires_preauth" option requires this principal to preauthenticate before being allowed to kinit. -requires_preauth clears this flag. In effect, +requires_preauth sets the KRB5_KDB_REQUIRES_PRE_AUTH flag on the principal in the database.
-*{-|+}requires_hwauth*
-The "+requires_hwauth" flag requires the principal to preauthenticate using a hardware device before being allowed to kinit. "-requires_hwauth" clears this flag. In effect, "+requires_hwauth" sets the KRB5_KDB_REQUIRES_HW_AUTH flag on the principal in the database.
-
-*{-|+}allow_svr*
-The "-allow_svr" flag prohibits the issuance of service tickets for this principal. "+allow_svr" clears this flag. In effect, "-allow_svr" sets the
-KRB5_KDB_DISALLOW_SVR flag on the principal in the database.
-
-*{-|+}allow_tgs_req*
-The "-allow_tgs_req" option specifies that a Ticket-Granting Service (TGS) request for a service ticket for this principal is not permitted. You will probably never need to use this option. "+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*
-The "-allow_tix" option 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*
-The "+needchange" option 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*
-The "+password_changing_service" option sets a flag in the attributes field marking this principal as a password change service. (Again, you will probably never need to use this option.) "-password_changing_service" clears the flag. The default is "-password_changing_service". In effect, the "+password_changing_service" option sets the KRB5_KDB_PWCHANGE_SERVICE flag on the principal in the database.
-
-*{-|+}ok_as_delegate*
-The "+ok_as_delegate" option sets a flag in tickets issued for the service principal. Some client programs may recognize this flag as indicating that it is okay to delegate credentials to the service. If ok_as_delegate is set on a cross-realm TGT, it indicates that the foreign realm's ok_as_delegate flags should be honored by clients in the local realm. The default is "-ok_as_delegate".
-
-*-randkey*
-Sets the key for the principal to a random value (*add_principal* only). MIT recommends using this option for host keys.
-
-*-pw password*
-Sets the key of the principal to the specified string and does not prompt for a password (*add_principal* only). MIT does not recommend using this option.
-
-*-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. See :ref:`Supported_Encryption_Types_and_Salts` for available types.
-
-
-If you want to just use the default values, all you need to do is::
-
- kadmin: addprinc jennifer
- WARNING: no policy specified for "jennifer@ATHENA.MIT.EDU";
- defaulting to no policy.
- Enter password for principal jennifer@ATHENA.MIT.EDU: <= Type the password.
- Re-enter password for principal jennifer@ATHENA.MIT.EDU: <=Type it again.
- Principal "jennifer@ATHENA.MIT.EDU" created.
- kadmin:
+EXAMPLES
If you want to create a principal which is contained by a LDAP object, all you need to do is::
If you need cross-realm authentication, you will need to add principals for the other realm's TGT to each realm. For example, if you need to do cross-realm authentication between the realms *ATHENA.MIT.EDU* and *EXAMPLE.COM*, you would need to add the principals *krbtgt\/EXAMPLE.COM\@ATHENA.MIT.EDU* and *krbtgt\/ATHENA.MIT.EDU\@EXAMPLE.COM* to both databases. You need to be sure the passwords and the key version numbers (*kvno*) are the same in both databases. This may require explicitly setting the *kvno* with the *-kvno* option. See :ref:`xrealm_authn_label` for more details.
+If you want to delete a principal ::
+
+ kadmin: delprinc jennifer
+ Are you sure you want to delete the principal
+ "jennifer@ATHENA.MIT.EDU"? (yes/no): yes
+ Principal "jennifer@ATHENA.MIT.EDU" deleted.
+ Make sure that you have removed this principal from
+ all ACLs before reusing.
+ kadmin:
+
------------
Changing passwords
============================
-To change a principal's password use the kadmin change_password command, which requires the "modify" administrative privilege (unless the principal is changing his/her own password). The syntax is::
-
- change_password [options] principal
+To change a principal's password use the *kadmin* **change_password** command.
-The *change_password* option has the alias cpw. *change_password* takes the following options
-
-========================= ============================================================
- -randkey Sets the key of the principal to a random value.
- -pw *password* Sets the password to the string password. MIT does not recommend using this option.
- -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. See :ref:`Supported_Encryption_Types_and_Salts` for possible values.
- -keepold Keeps the previous kvno's keys around. 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
-========================= ============================================================
-
+.. include:: ../../admin_commands/kadmin_local.rst
+ :start-after: _change_password:
+ :end-before: _change_password_end:
-For example::
-
- kadmin: cpw david
- Enter password for principal david@ATHENA.MIT.EDU: <= Type the new password.
- Re-enter password for principal david@ATHENA.MIT.EDU: <= Type it again.
- Password for david@ATHENA.MIT.EDU changed.
- kadmin:
-
.. note:: *change_password* will not let you change the password to one that is in the principal's password history.
-------------
-Feedback:
-Please, provide your feedback at krb5-bugs@mit.edu?subject=Documentation___db_princs
.. note:: This document was copied from **Kerberos V5 System Administrator's Guide** with minor changes. Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs@mit.edu. Your contribution is greatly appreciated.
-Your Kerberos database contains all of your realm's Kerberos principals, their passwords, and other administrative information about each principal. For the most part, you will use the *kdb5_util* program to manipulate the Kerberos database as a whole, and the kadmin program to make changes to the entries in the database. (One notable exception is that users will use the kpasswd program to change their own passwords.) The kadmin program has its own command-line interface, to which you type the database administrating commands.
+Your Kerberos database contains all of your realm's Kerberos principals, their passwords, and other administrative information about each principal. For the most part, you will use the :ref:`kdb5_util(8)` program to manipulate the Kerberos database as a whole, and the kadmin program to make changes to the entries in the database. (One notable exception is that users will use the :ref:`kpasswd(1)` program to change their own passwords.) The kadmin program has its own command-line interface, to which you type the database administrating commands.
-*kdb5_util* provides a means to create, delete, load, or dump a Kerberos database. It also includes a command to stash a copy of the master database key in a file on a KDC, so that the KDC can authenticate itself to the kadmind and krb5kdc daemons at boot time.
+:ref:`kdb5_util(8)` provides a means to create, delete, load, or dump a Kerberos database. It also includes a command to stash a copy of the master database key in a file on a KDC, so that the KDC can authenticate itself to the *kadmind* and *krb5kdc* daemons at boot time.
-*kadmin* provides for the maintenance of Kerberos principals, KADM5 policies, and service key tables (keytabs). It exists as both a Kerberos client, kadmin, using Kerberos authentication and an RPC, to operate securely from anywhere on the network, and as a local client, *kadmin.local*, intended to run directly on the KDC without Kerberos authentication. *kadmin.local* need not run on the kdc if the database is LDAP. Other than the fact that the remote client uses Kerberos to authenticate the person using it, the functionalities of the two versions are identical. The local version is necessary to enable you to set up enough of the database to be able to use the remote version. It replaces the now obsolete kdb5_edit (except for database dump and load, which are provided by *kdb5_util*).
+*kadmin* provides for the maintenance of Kerberos principals, KADM5 policies, and service key tables (*keytabs*). It exists as both a Kerberos client, *kadmin*, using Kerberos authentication and an RPC, to operate securely from anywhere on the network, and as a local client, *kadmin.local*, intended to run directly on the KDC without Kerberos authentication. *kadmin.local* need not run on the kdc if the database is LDAP. Other than the fact that the remote client uses Kerberos to authenticate the person using it, the functionalities of the two versions are identical. The local version is necessary to enable you to set up enough of the database to be able to use the remote version. It replaces the now obsolete kdb5_edit (except for database dump and load, which are provided by *kdb5_util*).
The remote version 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 *-c* ccache 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.
+See :ref:`kadmin(1)` for the available *kadmin* and *kadmin.local* commands and options.
.. toctree::
:maxdepth: 2
All Kerberos server machines need a *keytab* file, called */etc/krb5.keytab*, to authenticate to the KDC. The keytab file is an encrypted, local, on-disk copy of the host's key. The keytab file, like the stash file (See :ref:`create_db_label`) is a potential point-of-entry for a break-in, and if compromised, would allow unrestricted access to its host. The *keytab* file should be readable only by root, and should exist only on the machine's local disk. The file should not be part of any backup of the machine, unless access to the backup data is secured as tightly as access to the machine's root password itself.
-In order to generate a *keytab* for a host, the host must have a principal in the Kerberos database. The procedure for adding hosts to the database is described fully in :ref:`add_mod_princs_label`. (See :ref:`slave_host_key_label` for a brief description.) The *keytab* is generated by running kadmin and issuing the *ktadd* command.
+In order to generate a *keytab* for a host, the host must have a principal in the Kerberos database. The procedure for adding hosts to the database is described fully in :ref:`add_mod_del_princs_label`. (See :ref:`slave_host_key_label` for a brief description.) The *keytab* is generated by running kadmin and issuing the *ktadd* command.
For example, to generate a *keytab* file to allow the host *trillium.mit.edu* to authenticate for the services host, ftp, and pop, the administrator *joeadmin* would issue the command (on *trillium.mit.edu*)::
slave_intall_fin.rst
-Once your KDCs are set up and running, you are ready to use kadmin to load principals for your users, hosts, and other services into the Kerberos database. This procedure is described fully in the :ref:`add_mod_princs_label`. The keytab is generated by running kadmin and issuing the ktadd command.
+Once your KDCs are set up and running, you are ready to use kadmin to load principals for your users, hosts, and other services into the Kerberos database. This procedure is described fully in the :ref:`add_mod_del_princs_label`. The keytab is generated by running kadmin and issuing the ktadd command.
.. note:: To limit the possibility that your Kerberos database could be compromised, MIT recommends that each KDC be a dedicated host, with limited access. If your KDC is also a file server, FTP server, Web server, or even just a client machine, someone who obtained root access through a security hole in any of those areas could gain access to the Kerberos database.
+.. _kinit(1):
+
kinit - obtain and cache Kerberos ticket-granting ticket
=========================================================
-kpasswd - change a user's Kerberos password
+.. _kpasswd(1):
+
+kpasswd
===============================================
.. highlight:: rst
-.. note:: This is a Draft. The list is incomplete.
+.. note:: The list is incomplete.
MIT Kerberos features
=======================================
+-----------------------------------------------+-----------+-------------------+
| Parallel KDC | | |
+-----------------------------------------------+-----------+-------------------+
- | Credentials delegation | 1.2 | |
+ | Credentials delegation | 1.7 | |
+-----------------------------------------------+-----------+-------------------+
| Constrained delegation | 1.8 | |
+-----------------------------------------------+-----------+-------------------+
projects / krb5.git / commitdiff