--- /dev/null
+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@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@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
+ WARNING: 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:
+
+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@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:
+
+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` 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:
+
+
+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@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@ATHENA.MIT.EDU *
+ joeadmin@ATHENA.MIT.EDU ADMCIL
+ joeadmin/*@ATHENA.MIT.EDU il */root@ATHENA.MIT.EDU
+ *@ATHENA.MIT.EDU cil *1/admin@ATHENA.MIT.EDU
+ */*@ATHENA.MIT.EDU i
+ */admin@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@ATHENA.MIT.EDU`` (matches the first line). He has no
+permissions at all with his null instance, ``joeadmin@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@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@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::
+
+ shell% kdb5_util dump -verbose dumpfile 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.
+
+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@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@EXAMPLE.COM
+ Enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
+ Re-enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
+ kadmin: addprinc -requires_preauth krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU
+ Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
+ Enter password for principal krbtgt/EXAMPLE.COM@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@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@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@mit.edu?subject=Documentation___db
+++ /dev/null
-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@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.
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db
+++ /dev/null
-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.
+++ /dev/null
-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@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%
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_operations
+++ /dev/null
-.. _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.
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_operations
+++ /dev/null
-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@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::
-
- shell% kdb5_util dump -verbose dumpfile 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.
-
-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.
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_operations
+++ /dev/null
-.. _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.
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_operations
+++ /dev/null
-.. _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
-
- db2file.rst
- file2db.rst
- create_stash.rst
- create_destroy_db.rst
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_operations
+++ /dev/null
-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:
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db
+++ /dev/null
-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.
-
-.. toctree::
- :maxdepth: 1
-
- mod_pol.rst
- retr_pol.rst
- update_histkey.rst
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_policies
+++ /dev/null
-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.
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_policies
+++ /dev/null
-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:
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_policies
+++ /dev/null
-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+
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_policies
+++ /dev/null
-Principals
-==========
-
-Each entry in the Kerberos database contains a Kerberos principal and
-the attributes and policies associated with that principal.
-
-.. toctree::
- :maxdepth: 2
-
- modify_princ.rst
- info_princ.rst
- priv_princ.rst
- pass_princ.rst
+++ /dev/null
-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:
+++ /dev/null
-.. _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@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
- WARNING: 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:
-
-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@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:
-
-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` 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:
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_princs
+++ /dev/null
-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.
+++ /dev/null
-.. _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@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@ATHENA.MIT.EDU *
- joeadmin@ATHENA.MIT.EDU ADMCIL
- joeadmin/*@ATHENA.MIT.EDU il */root@ATHENA.MIT.EDU
- *@ATHENA.MIT.EDU cil *1/admin@ATHENA.MIT.EDU
- */*@ATHENA.MIT.EDU i
- */admin@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@ATHENA.MIT.EDU`` (matches the first line). He has no
-permissions at all with his null instance, ``joeadmin@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@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.
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_princs
+++ /dev/null
-.. _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@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``.
+++ /dev/null
-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@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.
-
-.. toctree::
- :maxdepth: 2
-
- db_options.rst
- date_format.rst
- db_princs/index.rst
- db_policies/index.rst
- db_operations/index.rst
- ldap_operations/index.rst
- xrealm_authn.rst
- change_tgtkey.rst
- incr_db_prop.rst
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db
+++ /dev/null
-.. _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
-----
-
-.. toctree::
- :maxdepth: 2
-
- ldap_create_realm.rst
- ldap_mod_realm.rst
- ldap_del_realm.rst
- ldap_realm_info.rst
- ldap_realm_list.rst
- ldap_stash_pass.rst
- ldap_tkt_pol.rst
+++ /dev/null
-.. _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:
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_ldap
+++ /dev/null
-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:
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_ldap
+++ /dev/null
-.. _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:
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_ldap
+++ /dev/null
-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:
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_ldap
+++ /dev/null
-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:
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_ldap
+++ /dev/null
-.. _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:
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_ldap
+++ /dev/null
-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:
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db_ldap
+++ /dev/null
-.. _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@EXAMPLE.COM
- Enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
- Re-enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
- kadmin: addprinc -requires_preauth krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU
- Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
- Enter password for principal krbtgt/EXAMPLE.COM@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.
-
-
-Feedback
---------
-
-Please, provide your feedback at
-krb5-bugs@mit.edu?subject=Documentation___db
conf_files/index.rst
realm_config.rst
dns.rst
- database/index.rst
+ database.rst
conf_ldap.rst
appl_servers/index.rst
backup_host.rst
projects / krb5.git / commitdiff