diff options
Diffstat (limited to 'doc/admin/database.rst')
| -rw-r--r-- | doc/admin/database.rst | 562 |
1 files changed, 133 insertions, 429 deletions
diff --git a/doc/admin/database.rst b/doc/admin/database.rst index eb6417288..2fd07242a 100644 --- a/doc/admin/database.rst +++ b/doc/admin/database.rst @@ -39,29 +39,7 @@ See :ref:`kadmin(1)` for the available kadmin and kadmin.local commands and options. -kadmin options --------------- - -You can invoke :ref:`kadmin(1)` or kadmin.local with any of the -following options: - -.. include:: admin_commands/kadmin_local.rst - :start-after: kadmin_synopsis: - :end-before: kadmin_synopsis_end: - -**OPTIONS** - -.. include:: admin_commands/kadmin_local.rst - :start-after: _kadmin_options: - :end-before: _kadmin_options_end: - - -Date Format ------------ - -For the supported date-time formats see :ref:`getdate` section -in :ref:`datetime`. - +.. _principals: Principals ---------- @@ -69,122 +47,52 @@ Principals Each entry in the Kerberos database contains a Kerberos principal and the attributes and policies associated with that principal. - -.. _add_mod_del_princs: - -Adding, modifying and deleting principals -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - To add a principal to the database, use the :ref:`kadmin(1)` -**add_principal** command. - -To modify attributes of a principal, use the kadmin -**modify_principal** command. - -To delete a principal, use the kadmin **delete_principal** command. - -.. include:: admin_commands/kadmin_local.rst - :start-after: _add_principal: - :end-before: _add_principal_end: - -.. include:: admin_commands/kadmin_local.rst - :start-after: _modify_principal: - :end-before: _modify_principal_end: - -.. include:: admin_commands/kadmin_local.rst - :start-after: _delete_principal: - :end-before: _delete_principal_end: +**add_principal** command. User principals should usually be created +with the ``+requires_preauth -allow_svr`` options to help mitigate +dictionary attacks (see :ref:`dictionary`):: + kadmin: addprinc +requires_preauth -allow_svr alice + Enter password for principal "alice@KRBTEST.COM": + Re-enter password for principal "alice@KRBTEST.COM": -Examples -######## +User principals which will authenticate with :ref:`pkinit` should +instead by created with the ``-nokey`` option: -If you want to create a principal which is contained by a LDAP object, -all you need to do is:: + kadmin: addprinc -nokey alice - kadmin: addprinc -x dn=cn=jennifer,dc=example,dc=com jennifer - 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: - -If you want to create a principal under a specific LDAP container and -link to an existing LDAP object, all you need to do is:: - - kadmin: addprinc -x containerdn=dc=example,dc=com -x linkdn=cn=david,dc=example,dc=com david - No policy specified for "david@ATHENA.MIT.EDU"; - defaulting to no policy. - Enter password for principal david@ATHENA.MIT.EDU: <= Type the password. - Re-enter password for principal david@ATHENA.MIT.EDU: <=Type it again. - Principal "david@ATHENA.MIT.EDU" created. - kadmin: +Service principals can be created with the ``-nokey`` option; +long-term keys will be added when a keytab is generated:: -If you want to associate a ticket policy to a principal, all you need -to do is:: + kadmin: addprinc -nokey host/foo.mit.edu + kadmin: ktadd -k foo.keytab host/foo.mit.edu + Entry for principal host/foo.mit.edu with kvno 1, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:foo.keytab. + Entry for principal host/foo.mit.edu with kvno 1, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:foo.keytab. - kadmin: modprinc -x tktpolicy=userpolicy david - Principal "david@ATHENA.MIT.EDU" modified. - kadmin: - -If, on the other hand, you want to set up an account that expires on -January 1, 2000, that uses a policy called "stduser", with a temporary -password (which you want the user to change immediately), you would -type the following:: - - kadmin: addprinc david -expire "1/1/2000 12:01am EST" -policy stduser +needchange - Enter password for principal david@ATHENA.MIT.EDU: <= Type the password. - Re-enter password for principal - david@ATHENA.MIT.EDU: <= Type it again. - Principal "david@ATHENA.MIT.EDU" created. - kadmin: +To modify attributes of an existing principal, use the kadmin +**modify_principal** command:: -If you want to delete a principal:: + kadmin: modprinc -expire tomorrow alice + Principal "alice@KRBTEST.COM" modified. - 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: +To delete a principal, use the kadmin **delete_principal** command:: + kadmin: delprinc alice + Are you sure you want to delete the principal "alice@KRBTEST.COM"? (yes/no): yes + Principal "alice@KRBTEST.COM" deleted. + Make sure that you have removed this principal from all ACLs before reusing. -Retrieving information about a principal -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To change a principal's password, use the kadmin **change_password** +command. Password changes made through kadmin are subject to the same +password policies as would apply to password changes made through +:ref:`kpasswd(1)`. -To retrieve a listing of the attributes and/or policies associated -with a principal, use the :ref:`kadmin(1)` **get_principal** command. +To view the attributes of a principal, use the kadmin` +**get_principal** command. To generate a listing of principals, use the kadmin **list_principals** command. -.. include:: admin_commands/kadmin_local.rst - :start-after: _get_principal: - :end-before: _get_principal_end: - -.. include:: admin_commands/kadmin_local.rst - :start-after: _list_principals: - :end-before: _list_principals_end: - - -Changing passwords -~~~~~~~~~~~~~~~~~~ - -To change a principal's password use the :ref:`kadmin(1)` -**change_password** command. - -.. include:: admin_commands/kadmin_local.rst - :start-after: _change_password: - :end-before: _change_password_end: - -.. note:: - - Password changes through kadmin are subject to the same - password policies as would apply to password changes through - :ref:`kpasswd(1)`. - .. _policies: @@ -196,60 +104,25 @@ minimum and maximum password lifetimes, minimum number of characters and character classes a password must contain, and the number of old passwords kept in the database. +To add a new policy, use the :ref:`kadmin(1)` **add_policy** command:: -Adding, modifying and deleting policies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To add a new policy, use the :ref:`kadmin(1)` **add_policy** command. + kadmin: addpol -maxlife "1 year" -history 3 stduser To modify attributes of a principal, use the kadmin **modify_policy** +command. To delete a policy, use the kadmin **delete_policy** command. -To delete a policy, use the kadmin **delete_policy** command. - -.. include:: admin_commands/kadmin_local.rst - :start-after: _add_policy: - :end-before: _add_policy_end: - -.. include:: admin_commands/kadmin_local.rst - :start-after: _modify_policy: - :end-before: _modify_policy_end: - -.. 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 the policy - is in use by any principals. - - -Retrieving policies -~~~~~~~~~~~~~~~~~~~ +To associate a policy with a principal, use the kadmin +**modify_principal** command with the **-policy** option: -To retrieve a policy, use the :ref:`kadmin(1)` **get_policy** command. + kadmin: modprinc -policy stduser alice + Principal "alice@KRBTEST.COM" modified. -You can retrieve the list of policies with the kadmin -**list_policies** command. - -.. include:: admin_commands/kadmin_local.rst - :start-after: _get_policy: - :end-before: _get_policy_end: - -.. include:: admin_commands/kadmin_local.rst - :start-after: _list_policies: - :end-before: _list_policies_end: - - -Policies and principals -~~~~~~~~~~~~~~~~~~~~~~~ - -Policies can be applied to principals as they are created by using -the **-policy** flag to :ref:`add_principal`. Existing principals can -be modified by using the **-policy** or **-clearpolicy** flag to -:ref:`modify_principal`. +A principal entry may be associated with a nonexistent policy, either +because the policy did not exist at the time of associated or was +deleted afterwards. kadmin will warn when associated a principal with +a nonexistent policy, and will annotate the policy name with "[does +not exist]" in the **get_principal** output. .. _updating_history_key: @@ -302,175 +175,69 @@ Operations on the Kerberos database ----------------------------------- The :ref:`kdb5_util(8)` command is the primary tool for administrating -the Kerberos database. - -.. include:: admin_commands/kdb5_util.rst - :start-after: _kdb5_util_synopsis: - :end-before: _kdb5_util_synopsis_end: - -**OPTIONS** +the Kerberos database when using the DB2 or LMDB modules (see +:ref:`dbtypes`). Creating a database is described in +:ref:`create_db`. -.. include:: admin_commands/kdb5_util.rst - :start-after: _kdb5_util_options: - :end-before: _kdb5_util_options_end: - -.. toctree:: - :maxdepth: 1 +To create a stash file using the master password (because the database +was not created with one using the ``create -s`` flag, or after +restoring from a backup which did not contain the stash file), use the +kdb5_util **stash** command:: + $ kdb5_util stash + kdb5_util: Cannot find/read stored master key while reading master key + kdb5_util: Warning: proceeding without master key + Enter KDC database master key: <= Type the KDC database master password. -Dumping a Kerberos database to a file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To destroy a database, use the kdb5_util destroy command:: -To dump a Kerberos database into a file, use the :ref:`kdb5_util(8)` -**dump** command on one of the KDCs. + $ kdb5_util destroy + Deleting KDC database stored in '/var/krb5kdc/principal', are you sure? + (type 'yes' to confirm)? yes + OK, deleting database '/var/krb5kdc/principal'... + ** Database '/var/krb5kdc/principal' destroyed. -.. include:: admin_commands/kdb5_util.rst - :start-after: _kdb5_util_dump: - :end-before: _kdb5_util_dump_end: +.. _restore_from_dump: -Examples -######## +Dumping and loading a Kerberos database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:: +To dump a Kerberos database into a text file for backup or transfer +purposes, use the :ref:`kdb5_util(8)` **dump** command on one of the +KDCs:: - shell% kdb5_util dump dumpfile - shell% + $ kdb5_util dump dumpfile - shell% kbd5_util dump -verbose dumpfile + $ kbd5_util dump -verbose dumpfile kadmin/admin@ATHENA.MIT.EDU krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU kadmin/history@ATHENA.MIT.EDU K/M@ATHENA.MIT.EDU kadmin/changepw@ATHENA.MIT.EDU - shell% -If you specify which principals to dump, you must use the full -principal, as in the following example:: +You may specify which principals to dump, using full principal names +including realm:: - shell% kdb5_util dump -verbose dumpfile K/M@ATHENA.MIT.EDU kadmin/admin@ATHENA.MIT.EDU + $ kdb5_util dump -verbose someprincs K/M@ATHENA.MIT.EDU kadmin/admin@ATHENA.MIT.EDU kadmin/admin@ATHENA.MIT.EDU K/M@ATHENA.MIT.EDU - shell% - -Otherwise, the principals will not match those in the database and -will not be dumped:: - - shell% kdb5_util dump -verbose dumpfile K/M kadmin/admin - shell% - -If you do not specify a dump file, kdb5_util will dump the database to -the standard output. - - -.. _restore_from_dump: - -Restoring a Kerberos database from a dump file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To restore a Kerberos database dump from a file, use the -:ref:`kdb5_util(8)` **load** command on one of the KDCs. - -.. include:: admin_commands/kdb5_util.rst - :start-after: _kdb5_util_load: - :end-before: _kdb5_util_load_end: - +:ref:`kdb5_util(8)` **load** command:: -Examples -######## + $ kdb5_util load dumpfile -To dump a single principal and later load it, updating the database: - -:: - - shell% kdb5_util dump dumpfile principal@REALM - shell% - - shell% kdb5_util load -update dumpfile - shell% +To update an existing database with a partial dump file containing +only some principals, use the ``-update`` flag:: + $ kdb5_util load -update someprincs .. note:: If the database file exists, and the *-update* flag was not given, *kdb5_util* will overwrite the existing database. -.. note:: - - Using kdb5_util to dump and reload the principal database is - only necessary when upgrading from versions of krb5 prior - to 1.2.0---newer versions will use the existing database as-is. - - -.. _create_stash: - -Creating a stash file -~~~~~~~~~~~~~~~~~~~~~ - -A stash file allows a KDC to authenticate itself to the database -utilities, such as :ref:`kadmind(8)`, :ref:`krb5kdc(8)`, and -:ref:`kdb5_util(8)`. - -To create a stash file, use the :ref:`kdb5_util(8)` **stash** command. - -.. include:: admin_commands/kdb5_util.rst - :start-after: _kdb5_util_stash: - :end-before: _kdb5_util_stash_end: - - -Example -####### - - shell% kdb5_util stash - kdb5_util: Cannot find/read stored master key while reading master key - kdb5_util: Warning: proceeding without master key - Enter KDC database master key: <= Type the KDC database master password. - shell% - -If you do not specify a stash file, kdb5_util will stash the key in -the file specified in your :ref:`kdc.conf(5)` file. - - -Creating and destroying a Kerberos database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to create a new Kerberos database, use the -:ref:`kdb5_util(8)` **create** command. - -.. include:: admin_commands/kdb5_util.rst - :start-after: _kdb5_util_create: - :end-before: _kdb5_util_create_end: - -If you need to destroy the current Kerberos database, use the -:ref:`kdb5_util(8)` **destroy** command. - -.. include:: admin_commands/kdb5_util.rst - :start-after: _kdb5_util_destroy: - :end-before: _kdb5_util_destroy_end: - - -Examples -######## - -:: - - shell% kdb5_util -r ATHENA.MIT.EDU create -s - Loading random data - Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU', - master key name 'K/M@ATHENA.MIT.EDU' - You will be prompted for the database Master Password. - It is important that you NOT FORGET this password. - Enter KDC database master key: <= Type the master password. - Re-enter KDC database master key to verify: <= Type it again. - shell% - - shell% kdb5_util -r ATHENA.MIT.EDU destroy - Deleting KDC database stored in '/usr/local/var/krb5kdc/principal', are you sure? - (type 'yes' to confirm)? <= yes - OK, deleting database '/usr/local/var/krb5kdc/principal'... - ** Database '/usr/local/var/krb5kdc/principal' destroyed. - shell% - .. _updating_master_key: @@ -538,152 +305,89 @@ availability. To roll over the master key, follow these steps: Operations on the LDAP database ------------------------------- -The :ref:`kdb5_ldap_util(8)` is the primary tool for administrating -the Kerberos LDAP database. It allows an administrator to manage -realms, Kerberos services (KDC and Admin Server) and ticket policies. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_synopsis: - :end-before: _kdb5_ldap_util_synopsis_end: - -**OPTIONS** - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_options: - :end-before: _kdb5_ldap_util_options_end: - - -.. _ldap_create_realm: - -Creating a Kerberos realm -~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to create a new realm, use the :ref:`kdb5_ldap_util(8)` -**create** command as follows. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_create: - :end-before: _kdb5_ldap_util_create_end: - - -.. _ldap_mod_realm: - -Modifying a Kerberos realm -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to modify a realm, use the :ref:`kdb5_ldap_util(8)` -**modify** command as follows. +The :ref:`kdb5_ldap_util(8)` command is the primary tool for +administrating the Kerberos database when using the LDAP module. +Creating an LDAP Kerberos database is describe in :ref:`conf_ldap`. -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_modify: - :end-before: _kdb5_ldap_util_modify_end: +To view a list of realms in the LDAP database, use the kdb5_ldap_util +**list** command:: + $ kdb5_ldap_util list + KRBTEST.COM -Destroying a Kerberos realm -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To modify the attributes of a realm, use the kdb5_ldap_util **modify** +command. For example, to change the default realm's maximum ticket +life:: -If you need to destroy a Kerberos realm, use the -:ref:`kdb5_ldap_util(8)` **destroy** command as follows. + $ kdb5_ldap_util modify -maxtktlife "10 hours" -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_destroy: - :end-before: _kdb5_ldap_util_destroy_end: +To display the attributes of a realm, use the kdb5_ldap_util **view** +command:: + $ kdb5_ldap_util view + Realm Name: KRBTEST.COM + Maximum Ticket Life: 0 days 00:10:00 -Retrieving information about a Kerberos realm -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To remove a realm from the LDAP database, destroying its contents, use +the kdb5_ldap_util **destroy** command:: -If you need to display the attributes of a realm, use the -:ref:`kdb5_ldap_util(8)` **view** command as follows. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_view: - :end-before: _kdb5_ldap_util_view_end: - - -Listing available Kerberos realms -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to display the list of the realms, use the -:ref:`kdb5_ldap_util(8)` **list** command as follows. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_list: - :end-before: _kdb5_ldap_util_list_end: - - -.. _stash_ldap: - -Stashing service object's password -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :ref:`kdb5_ldap_util(8)` **stashsrvpw** command allows an -administrator to store the password of service object in a file. The -KDC and Administration server uses this password to authenticate to -the LDAP server. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_stashsrvpw: - :end-before: _kdb5_ldap_util_stashsrvpw_end: + $ kdb5_ldap_util destroy + Deleting KDC database of 'KRBTEST.COM', are you sure? + (type 'yes' to confirm)? yes + OK, deleting database of 'KRBTEST.COM'... + ** Database of 'KRBTEST.COM' destroyed. Ticket Policy operations ~~~~~~~~~~~~~~~~~~~~~~~~ -Creating a Ticket Policy -######################## - -To create a new ticket policy in directory , use the -:ref:`kdb5_ldap_util(8)` **create_policy** command. Ticket policy -objects are created under the realm container. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_create_policy: - :end-before: _kdb5_ldap_util_create_policy_end: - - -Modifying a Ticket Policy -######################### - -To modify a ticket policy in directory, use the -:ref:`kdb5_ldap_util(8)` **modify_policy** command. +Unlike the DB2 and LMDB modules, the LDAP module supports ticket +policy objects, which can be associated with principals to restrict +maximum ticket lifetimes and set mandatory principal flags. Ticket +policy objects are distinct from the password policies described +earlier on this page, and are chiefly managed through kdb5_ldap_util +rather than kadmin. To create a new ticket policy, use the +kdb5_ldap_util **create_policy** command:: -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_modify_policy: - :end-before: _kdb5_ldap_util_modify_policy_end: + $ kdb5_ldap_util create_policy -maxrenewlife "2 days" users +To associate a ticket policy with a principal, use the +:ref:`kadmin(1)` **modify_principal** (or **add_principal**) command +with the **-x tktpolicy=**\ *policy* option:: -Retrieving Information About a Ticket Policy -############################################ + $ kadmin.local modprinc -x tktpolicy=users alice -To display the attributes of a ticket policy, use the -:ref:`kdb5_ldap_util(8)` **view_policy** command. +To remove a ticket policy reference from a principal, use the same +command with an empty *policy*:: -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_view_policy: - :end-before: _kdb5_ldap_util_view_policy_end: + $ kadmin.local modprinc -x tktpolicy= alice +To list the existing ticket policy objects, use the kdb5_ldap_util +**list_policy** command:: -Destroying a Ticket Policy -########################## + $ kdb5_ldap_util list_policy + users -To destroy an existing ticket policy, use the :ref:`kdb5_ldap_util(8)` -**destroy_policy** command. +To modify the attributes of a ticket policy object, use the +kdb5_ldap_util **modify_policy** command:: -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_destroy_policy: - :end-before: _kdb5_ldap_util_destroy_policy_end: + $ kdb5_ldap_util modify_policy -allow_svr +requires_preauth users +To view the attributes of a ticket policy object, use the +kdb5_ldap_util **view_policy** command:: -Listing available Ticket Policies -################################# + $ kdb5_ldap_util view_policy users + Ticket policy: users + Maximum renewable life: 2 days 00:00:00 + Ticket flags: REQUIRES_PRE_AUTH DISALLOW_SVR -To list the name of ticket policies in a realm, use the -:ref:`kdb5_ldap_util(8)` **list_policy** command. +To destroy an ticket policy object, use the kdb5_ldap_util +**destroy_policy** command:: -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_list_policy: - :end-before: _kdb5_ldap_util_list_policy_end: + $ kdb5_ldap_util destroy_policy users + This will delete the policy object 'users', are you sure? + (type 'yes' to confirm)? yes + ** policy object 'users' deleted. .. _xrealm_authn: |