svn rev #25732: trunk/doc/rst_source/krb_admins/ database/ database/db_operations/ ...
ghudson@MIT.EDU
ghudson at MIT.EDU
Mon Mar 5 14:19:33 EST 2012
http://src.mit.edu/fisheye/changelog/krb5/?cs=25732
Commit By: ghudson
Log Message:
Consolidate DB admin docs into one file
Combine the contents of the krb_admins/database directory into one
file database.rst.
Changed Files:
D trunk/doc/rst_source/krb_admins/database/change_tgtkey.rst
D trunk/doc/rst_source/krb_admins/database/date_format.rst
D trunk/doc/rst_source/krb_admins/database/db_operations/create_destroy_db.rst
D trunk/doc/rst_source/krb_admins/database/db_operations/create_stash.rst
D trunk/doc/rst_source/krb_admins/database/db_operations/db2file.rst
D trunk/doc/rst_source/krb_admins/database/db_operations/file2db.rst
D trunk/doc/rst_source/krb_admins/database/db_operations/index.rst
D trunk/doc/rst_source/krb_admins/database/db_options.rst
D trunk/doc/rst_source/krb_admins/database/db_policies/index.rst
D trunk/doc/rst_source/krb_admins/database/db_policies/mod_pol.rst
D trunk/doc/rst_source/krb_admins/database/db_policies/retr_pol.rst
D trunk/doc/rst_source/krb_admins/database/db_policies/update_histkey.rst
D trunk/doc/rst_source/krb_admins/database/db_princs/index.rst
D trunk/doc/rst_source/krb_admins/database/db_princs/info_princ.rst
D trunk/doc/rst_source/krb_admins/database/db_princs/modify_princ.rst
D trunk/doc/rst_source/krb_admins/database/db_princs/pass_princ.rst
D trunk/doc/rst_source/krb_admins/database/db_princs/priv_princ.rst
D trunk/doc/rst_source/krb_admins/database/incr_db_prop.rst
D trunk/doc/rst_source/krb_admins/database/index.rst
D trunk/doc/rst_source/krb_admins/database/ldap_operations/index.rst
D trunk/doc/rst_source/krb_admins/database/ldap_operations/ldap_create_realm.rst
D trunk/doc/rst_source/krb_admins/database/ldap_operations/ldap_del_realm.rst
D trunk/doc/rst_source/krb_admins/database/ldap_operations/ldap_mod_realm.rst
D trunk/doc/rst_source/krb_admins/database/ldap_operations/ldap_realm_info.rst
D trunk/doc/rst_source/krb_admins/database/ldap_operations/ldap_realm_list.rst
D trunk/doc/rst_source/krb_admins/database/ldap_operations/ldap_stash_pass.rst
D trunk/doc/rst_source/krb_admins/database/ldap_operations/ldap_tkt_pol.rst
D trunk/doc/rst_source/krb_admins/database/xrealm_authn.rst
A trunk/doc/rst_source/krb_admins/database.rst
U trunk/doc/rst_source/krb_admins/index.rst
Added: trunk/doc/rst_source/krb_admins/database.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/database.rst (rev 0)
+++ trunk/doc/rst_source/krb_admins/database.rst 2012-03-05 19:19:33 UTC (rev 25732)
@@ -0,0 +1,893 @@
+Database administration
+=======================
+
+.. 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 at 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
+:ref:`kdb5_util(8)` program to manipulate the Kerberos database as a
+whole, and the :ref:`kadmin(1)` 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.
+
+: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 :ref:`kadmind(8)` and :ref:`krb5kdc(8)`
+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).
+
+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.
+
+
+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
+-----------
+
+.. include:: admin_commands/kadmin_local.rst
+ :start-after: _date_format:
+ :end-before: _date_format_end:
+
+.. 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.
+
+
+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:
+
+
+Examples
+########
+
+If you want to create a principal which is contained by a LDAP object,
+all you need to do is::
+
+ kadmin: addprinc -x dn=cn=jennifer,dc=example,dc=com jennifer
+ WARNING: no policy specified for "jennifer at ATHENA.MIT.EDU";
+ defaulting to no policy.
+ Enter password for principal jennifer at ATHENA.MIT.EDU: <= Type the password.
+ Re-enter password for principal jennifer at ATHENA.MIT.EDU: <=Type it again.
+ Principal "jennifer at 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
+ WARNING: no policy specified for "david at ATHENA.MIT.EDU";
+ defaulting to no policy.
+ Enter password for principal david at ATHENA.MIT.EDU: <= Type the password.
+ Re-enter password for principal david at ATHENA.MIT.EDU: <=Type it again.
+ Principal "david at ATHENA.MIT.EDU" created.
+ kadmin:
+
+If you want to associate a ticket policy to a principal, all you need
+to do is::
+
+ kadmin: modprinc -x tktpolicy=userpolicy david
+ Principal "david at 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 at ATHENA.MIT.EDU: <= Type the password.
+ Re-enter password for principal
+ david at ATHENA.MIT.EDU: <= Type it again.
+ Principal "david at ATHENA.MIT.EDU" created.
+ kadmin:
+
+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 at ATHENA.MIT.EDU`` and
+``krbtgt/ATHENA.MIT.EDU at 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` for more details.
+
+If you want to delete a principal ::
+
+ kadmin: delprinc jennifer
+ Are you sure you want to delete the principal
+ "jennifer at ATHENA.MIT.EDU"? (yes/no): yes
+ Principal "jennifer at ATHENA.MIT.EDU" deleted.
+ Make sure that you have removed this principal from
+ all ACLs before reusing.
+ kadmin:
+
+
+Retrieving information about a principal
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To retrieve a listing of the attributes and/or policies associated
+with a principal, use the :ref:`kadmin(1)` **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:
+
+
+.. _privileges:
+
+Privileges
+~~~~~~~~~~
+
+Administrative privileges for the Kerberos database are stored in the
+file kadm5.acl.
+
+The format of the file is::
+
+ Kerberos_principal permissions [target_principal] [restrictions]
+
+The Kerberos principal (and optional target principal) can include the
+``*`` wildcard, so if you want any principal with the instance
+``admin`` to have full permissions on the database, you could use the
+principal ``*/admin at REALM`` where *REALM* is your Kerberos realm.
+*target_principal* can also include backreferences to
+*Kerberos_principal*, in which "number" matches the component number
+in the *Kerberos_principal*.
+
+.. note:: A common use of an admin instance is so you can grant
+ separate permissions (such as administrator access to the
+ Kerberos database) to a separate Kerberos principal. For
+ example, the user ``joeadmin`` might have a principal for
+ his administrative use, called ``joeadmin/admin``. This
+ way, ``joeadmin`` would obtain ``joeadmin/admin`` tickets
+ only when he actually needs to use those permissions.
+
+
+Permissions
+###########
+
+The permissions are represented by single letters; UPPER-CASE letters
+represent negative permissions. The permissions are:
+
+=== =====================================
+a allows the addition of principals or policies in the database.
+A disallows the addition of principals or policies in the database.
+c allows the changing of passwords for principals in the database.
+C disallows the changing of passwords for principals in the database.
+d allows the deletion of principals or policies in the database.
+D disallows the deletion of principals or policies in the database.
+i allows inquiries to the database.
+I disallows inquiries to the database.
+l allows the listing of principals or policies in the database.
+L disallows the listing of principals or policies in the database.
+m allows the modification of principals or policies in the database.
+M disallows the modification of principals or policies in the database.
+p allow the propagation of the principal database (used in :ref:`incr_db_prop`).
+P disallow the propagation of the principal database (used in :ref:`incr_db_prop`).
+s allows the explicit setting of the key for a principal
+S disallows the explicit setting of the key for a principal
+\* All privileges (admcil).
+x All privileges (admcil); identical to "\*".
+=== =====================================
+
+
+Restrictions
+############
+
+The restrictions are a string of flags. Allowed restrictions are:
+
+======================== ============================
+[+\|-]flagname flag is forced to indicated value. The permissible flags are the same as the + and - flags for the kadmin addprinc and modprinc commands.
+-clearpolicy policy is forced to clear
+-policy *pol* policy is forced to be *pol*
+-expire time
+-pwexpire time
+-maxlife time
+-maxrenewlife time associated value will be forced to MIN(time, requested value)
+======================== ============================
+
+The above flags act as restrictions on any add or modify operation
+which is allowed due to that ACL line.
+
+Here is an example of a *kadm5.acl* file::
+
+ */admin at ATHENA.MIT.EDU *
+ joeadmin at ATHENA.MIT.EDU ADMCIL
+ joeadmin/*@ATHENA.MIT.EDU il */root at ATHENA.MIT.EDU
+ *@ATHENA.MIT.EDU cil *1/admin at ATHENA.MIT.EDU
+ */*@ATHENA.MIT.EDU i
+ */admin at EXAMPLE.COM * -maxlife 9h -postdateable
+
+.. note:: The order is important; permissions are determined by the
+ first matching entry.
+
+In the above file, any principal in the ``ATHENA.MIT.EDU`` realm with
+an admin instance has all administrative privileges. The user
+``joeadmin`` has all permissions with his admin instance,
+``joeadmin/admin at ATHENA.MIT.EDU`` (matches the first line). He has no
+permissions at all with his null instance, ``joeadmin at ATHENA.MIT.EDU``
+(matches the second line). His root instance has inquire and list
+permissions with any other principal that has the instance root. Any
+principal in ``ATHENA.MIT.EDU`` can inquire, list, or change the
+password of their admin instance, but not any other admin instance.
+Any principal in the realm ``ATHENA.MIT.EDU`` (except for
+``joeadmin at ATHENA.MIT.EDU``, as mentioned above) has inquire
+privileges. Finally, any principal with an admin instance in
+EXAMPLE.COM has all permissions, but any principal that they create or
+modify will not be able to get postdateable tickets or tickets with a
+life of longer than 9 hours.
+
+
+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:: *change_password* will not let you change the password to
+ one that is in the principal's password history.
+
+
+Policies
+--------
+
+A policy is a set of rules governing passwords. Policies can dictate
+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.
+
+
+Adding, modifying and deleting policies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To add a new policy, use the :ref:`kadmin(1)` **add_policy** command.
+
+To modify attributes of a principal, use the kadmin **modify_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:
+
+.. note:: The policies are created under **realm** container in the
+ LDAP database.
+
+.. 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 it is
+ in use by any principals.
+
+
+Retrieving policies
+~~~~~~~~~~~~~~~~~~~
+
+To retrieve a policy, use the :ref:`kadmin(1)` **get_policy** command.
+
+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:
+
+
+Updating the history key
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following text is for release < 1.8.
+
+If a policy specifies a number of old keys kept of two or more, the
+stored old keys are encrypted in a history key, which is found in the
+key data of the ``kadmin/history`` principal.
+
+Currently there is no support for proper rollover of the history key,
+but you can change the history key (for example, to use a better
+encryption type) at the cost of invalidating currently stored old
+keys. To change the history key, run::
+
+ kadmin: change_password -randkey kadmin/history
+
+This command will fail if you specify the **-keepold** flag. Only one
+new history key will be created, even if you specify multiple key/salt
+combinations.
+
+In the future, we plan to migrate towards encrypting old keys in the
+master key instead of the history key, and implementing proper
+rollover support for stored old keys. - implemented in 1.8+
+
+
+.. _db_operations:
+
+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**
+
+.. include:: admin_commands/kdb5_util.rst
+ :start-after: _kdb5_util_options:
+ :end-before: _kdb5_util_options_end:
+
+.. toctree::
+ :maxdepth: 1
+
+
+Dumping a Kerberos database to a file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To dump a Kerberos database into a file, use the :ref:`kdb5_util(8)`
+**dump** command on one of the KDCs.
+
+.. include:: admin_commands/kdb5_util.rst
+ :start-after: _kdb5_util_dump:
+ :end-before: _kdb5_util_dump_end:
+
+
+Examples
+########
+
+::
+
+ shell% kdb5_util dump dumpfile
+ shell%
+
+ shell% kbd5_util dump -verbose dumpfile
+ kadmin/admin at ATHENA.MIT.EDU
+ krbtgt/ATHENA.MIT.EDU at ATHENA.MIT.EDU
+ kadmin/history at ATHENA.MIT.EDU
+ K/M at ATHENA.MIT.EDU
+ kadmin/changepw at ATHENA.MIT.EDU
+ shell%
+
+If you specify which principals to dump, you must use the full
+principal, as in the following example::
+
+ shell% kdb5_util dump -verbose dumpfile K/M at ATHENA.MIT.EDU kadmin/admin at ATHENA.MIT.EDU
+ kadmin/admin at ATHENA.MIT.EDU
+ K/M at 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.
+
+There is currently a bug where the default dump format omits the
+per-principal policy information. In order to dump all the data
+contained in the Kerberos database, you must perform a normal dump
+(with no option flags) and an additional dump using the "-ov" flag to
+a different file.
+
+
+.. _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:
+
+
+Examples
+########
+
+::
+
+ shell% kdb5_util load dumpfile principal
+ shell%
+
+ shell% kdb5_util load -update dumpfile principal
+ shell%
+
+
+.. note:: If the database file exists, and the *-update* flag was not
+ given, *kdb5_util* will overwrite the existing database.
+
+
+.. _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% /usr/local/sbin/kdb5_util -r ATHENA.MIT.EDU create -s
+ kdb5_util: No such file or directory while setting active database to'/usr/local/var/krb5kdc/principal'
+ Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU',
+ master key name 'K/M at 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% /usr/local/sbin/kdb5_util -r ATHENA.MIT.EDU destroy
+ kdb5_util: 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'...
+ shell%
+
+
+.. _ops_on_ldap:
+
+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.
+
+.. include:: admin_commands/kdb5_ldap_util.rst
+ :start-after: _kdb5_ldap_util_modify:
+ :end-before: _kdb5_ldap_util_modify_end:
+
+
+Destroying a Kerberos realm
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you need to destroy a Kerberos realm, use the
+:ref:`kdb5_ldap_util(8)` **destroy** command as follows.
+
+.. include:: admin_commands/kdb5_ldap_util.rst
+ :start-after: _kdb5_ldap_util_destroy:
+ :end-before: _kdb5_ldap_util_destroy_end:
+
+
+Retrieving information about a Kerberos realm
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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_list:
+ :end-before: _kdb5_ldap_util_list_end:
+
+
+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.
+
+.. include:: admin_commands/kdb5_ldap_util.rst
+ :start-after: _kdb5_ldap_util_modify_policy:
+ :end-before: _kdb5_ldap_util_modify_policy_end:
+
+
+Retrieving Information About a Ticket Policy
+############################################
+
+To display the attributes of a ticket policy, use the
+:ref:`kdb5_ldap_util(8)` **view_policy** command.
+
+.. include:: admin_commands/kdb5_ldap_util.rst
+ :start-after: _kdb5_ldap_util_view_policy:
+ :end-before: _kdb5_ldap_util_view_policy_end:
+
+
+Destroying a Ticket Policy
+##########################
+
+To destroy an existing ticket policy, use the :ref:`kdb5_ldap_util(8)`
+**destroy_policy** command.
+
+.. include:: admin_commands/kdb5_ldap_util.rst
+ :start-after: _kdb5_ldap_util_destroy_policy:
+ :end-before: _kdb5_ldap_util_destroy_policy_end:
+
+
+Listing available Ticket Policies
+#################################
+
+To list the name of ticket policies in a realm, use the
+:ref:`kdb5_ldap_util(8)` **list_policy** command.
+
+.. include:: admin_commands/kdb5_ldap_util.rst
+ :start-after: _kdb5_ldap_util_destroy_policy:
+ :end-before: _kdb5_ldap_util_destroy_policy_end:
+
+
+.. _xrealm_authn:
+
+Cross-realm authentication
+--------------------------
+
+In order for a KDC in one realm to authenticate Kerberos users in a
+different realm, it must share a key with the KDC in the other realm.
+In both databases, there must be krbtgt service principals for realms.
+These principals should all have the same passwords, key version
+numbers, and encryption types.
+
+For example, if the administrators of ATHENA.MIT.EDU and EXAMPLE.COM
+wanted to authenticate across the realms, they would run the following
+commands on the KDCs in both realms::
+
+ shell%: kadmin.local -e "des3-hmac-sha1:normal des-cbc-crc:v4"
+ kadmin: addprinc -requires_preauth krbtgt/ATHENA.MIT.EDU at EXAMPLE.COM
+ Enter password for principal krbtgt/ATHENA.MIT.EDU at EXAMPLE.COM:
+ Re-enter password for principal krbtgt/ATHENA.MIT.EDU at EXAMPLE.COM:
+ kadmin: addprinc -requires_preauth krbtgt/EXAMPLE.COM at ATHENA.MIT.EDU
+ Enter password for principal krbtgt/EXAMPLE.COM at ATHENA.MIT.EDU:
+ Enter password for principal krbtgt/EXAMPLE.COM at ATHENA.MIT.EDU:
+ kadmin:
+
+.. note:: Even if most principals in a realm are generally created
+ with the **requires_preauth** flag enabled, this flag is not
+ desirable on cross-realm authentication keys because doing
+ so makes it impossible to disable preauthentication on a
+ service-by-service basis. Disabling it as in the example
+ above is recommended.
+
+.. note:: It is very important that these principals have good
+ passwords. MIT recommends that TGT principal passwords be
+ at least 26 characters of random ASCII text.
+
+
+Changing the krbtgt key
+-----------------------
+
+A Kerberos Ticket Granting Ticket (TGT) is a service ticket for the
+principal ``krbtgt/REALM``. The key for this principal is created
+when the Kerberos database is initialized and need not be changed.
+However, it will only have the encryption types supported by the KDC
+at the time of the initial database creation. To allow use of newer
+encryption types for the TGT, this key has to be changed.
+
+Changing this key using the normal :ref:`kadmin(1)`
+**change_password** command would invalidate any previously issued
+TGTs. Therefore, when changing this key, normally one should use the
+**-keepold** flag to change_password to retain the previous key in the
+database as well as the new key. For example::
+
+ kadmin: change_password -randkey -keepold krbtgt/ATHENA.MIT.EDU at ATHENA.MIT.EDU
+
+.. warning:: After issuing this command, the old key is still valid
+ and is still vulnerable to (for instance) brute force
+ attacks. To completely retire an old key or encryption
+ type, run the kadmin **purgekeys** command to delete keys
+ with older kvnos, ideally first making sure that all
+ tickets issued with the old keys have expired.
+
+
+.. _incr_db_prop:
+
+Incremental database propagation
+--------------------------------
+
+.. note:: This document was copied from **Kerberos V5 Installation
+ Guide** with minor changes. Currently it is under review.
+ Please, send your feedback, corrections and additions to
+ krb5-bugs at mit.edu. Your contribution is greatly
+ appreciated.
+
+Overview
+~~~~~~~~
+
+At some very large sites, dumping and transmitting the database can
+take more time than is desirable for changes to propagate from the
+master KDC to the slave KDCs. The incremental propagation support
+added in the 1.7 release is intended to address this.
+
+With incremental propagation enabled, all programs on the master KDC
+that change the database also write information about the changes to
+an "update log" file, maintained as a circular buffer of a certain
+size. A process on each slave KDC connects to a service on the master
+KDC (currently implemented in the :ref:`kadmind(8)` server) and
+periodically requests the changes that have been made since the last
+check. By default, this check is done every two minutes. If the
+database has just been modified in the previous several seconds
+(currently the threshold is hard-coded at 10 seconds), the slave will
+not retrieve updates, but instead will pause and try again soon after.
+This reduces the likelihood that incremental update queries will cause
+delays for an administrator trying to make a bunch of changes to the
+database at the same time.
+
+Incremental propagation uses the following entries in the per-realm
+data in the KDC config file (See :ref:`kdc.conf(5)`):
+
+====================== =============== ===========================================
+iprop_enable *boolean* If *true*, then incremental propagation is enabled, and (as noted below) normal kprop propagation is disabled. The default is *false*.
+iprop_master_ulogsize *integer* Indicates the number of entries that should be retained in the update log. The default is 1000; the maximum number is 2500.
+iprop_slave_poll *time interval* Indicates how often the slave should poll the master KDC for changes to the database. The default is two minutes.
+iprop_port *integer* Specifies the port number to be used for incremental propagation. This is required in both master and slave configuration files.
+iprop_logfile *file name* Specifies where the update log file for the realm database is to be stored. The default is to use the *database_name* entry from the realms section of the config file :ref:`kdc.conf(5)`, with *.ulog* appended. (NOTE: If database_name isn't specified in the realms section, perhaps because the LDAP database back end is being used, or the file name is specified in the *dbmodules* section, then the hard-coded default for *database_name* is used. Determination of the *iprop_logfile* default value will not use values from the *dbmodules* section.)
+====================== =============== ===========================================
+
+Both master and slave sides must have principals named
+``kiprop/hostname`` (where *hostname* is, as usual, the lower-case,
+fully-qualified, canonical name for the host) registered and keys
+stored in the default keytab file (``/etc/krb5.keytab``).
+
+On the master KDC side, the ``kiprop/hostname`` principal must be
+listed in the kadmind ACL file kadm5.acl, and given the **p**
+privilege (see :ref:`privileges`).
+
+On the slave KDC side, :ref:`kpropd(8)` should be run. When
+incremental propagation is enabled, it will connect to the kadmind on
+the master KDC and start requesting updates.
+
+The normal kprop mechanism is disabled by the incremental propagation
+support. However, if the slave has been unable to fetch changes from
+the master KDC for too long (network problems, perhaps), the log on
+the master may wrap around and overwrite some of the updates that the
+slave has not yet retrieved. In this case, the slave will instruct
+the master KDC to dump the current database out to a file and invoke a
+one-time kprop propagation, with special options to also convey the
+point in the update log at which the slave should resume fetching
+incremental updates. Thus, all the keytab and ACL setup previously
+described for kprop propagation is still needed.
+
+There are several known bugs and restrictions in the current
+implementation:
+
+- The "call out to kprop" mechanism is a bit fragile; if the kprop
+ propagation fails to connect for some reason, the process on the
+ slave may hang waiting for it, and will need to be restarted.
+- The master and slave must be able to initiate TCP connections in
+ both directions, without an intervening NAT. They must also be able
+ to communicate over IPv4, since MIT's kprop and RPC code does not
+ currently support IPv6.
+
+
+Sun/MIT incremental propagation differences
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sun donated the original code for supporting incremental database
+propagation to MIT. Some changes have been made in the MIT source
+tree that will be visible to administrators. (These notes are based
+on Sun's patches. Changes to Sun's implementation since then may not
+be reflected here.)
+
+The Sun config file support looks for ``sunw_dbprop_enable``,
+``sunw_dbprop_master_ulogsize``, and ``sunw_dbprop_slave_poll``.
+
+The incremental propagation service is implemented as an ONC RPC
+service. In the Sun implementation, the service is registered with
+rpcbind (also known as portmapper) and the client looks up the port
+number to contact. In the MIT implementation, where interaction with
+some modern versions of rpcbind doesn't always work well, the port
+number must be specified in the config file on both the master and
+slave sides.
+
+The Sun implementation hard-codes pathnames in ``/var/krb5`` for the
+update log and the per-slave kprop dump files. In the MIT
+implementation, the pathname for the update log is specified in the
+config file, and the per-slave dump files are stored in
+``/usr/local/var/krb5kdc/slave_datatrans_hostname``.
+
+
+Feedback
+--------
+
+Please, provide your feedback at
+krb5-bugs at mit.edu?subject=Documentation___db
Modified: trunk/doc/rst_source/krb_admins/index.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/index.rst 2012-03-05 18:32:12 UTC (rev 25731)
+++ trunk/doc/rst_source/krb_admins/index.rst 2012-03-05 19:19:33 UTC (rev 25732)
@@ -11,7 +11,7 @@
conf_files/index.rst
realm_config.rst
dns.rst
- database/index.rst
+ database.rst
conf_ldap.rst
appl_servers/index.rst
backup_host.rst
More information about the cvs-krb5
mailing list