Remove man page includes from RST documentation

Rewrite parts of database.rst and appl_servers.rst to avoid including
full option descriptions from the (already linked) man pages.

7 files changed, 147 insertions, 493 deletions

diff --git a/doc/admin/admin_commands/kadmin_local.rst b/doc/admin/admin_commands/kadmin_local.rst
index cf75e6158..01b92d6fc 100644
--- a/doc/admin/admin_commands/kadmin_local.rst
+++ b/doc/admin/admin_commands/kadmin_local.rst
@@ -28,8 +28,6 @@ SYNOPSIS
 [**-x** *db_args*]
 [command args...]
 
-.. _kadmin_synopsis_end:
-
 
 DESCRIPTION
 -----------
@@ -142,8 +140,6 @@ OPTIONS
     Specifies the database specific arguments.  See the next section
     for supported options.
 
-.. _kadmin_options_end:
-
 Starting with release 1.14, if any command-line arguments remain after
 the options, they will be treated as a single query to be executed.
 This mode of operation is intended for scripts and behaves differently
@@ -426,8 +422,6 @@ Example::
     Principal "jennifer@ATHENA.MIT.EDU" created.
     kadmin:
 
-.. _add_principal_end:
-
 .. _modify_principal:
 
 modify_principal
@@ -451,8 +445,6 @@ Options (in addition to the **addprinc** options):
     authentication attempts without enough time between them according
     to its password policy) so that it can successfully authenticate.
 
-.. _modify_principal_end:
-
 .. _rename_principal:
 
 rename_principal
@@ -468,8 +460,6 @@ This command requires the **add** and **delete** privileges.
 
 Alias: **renprinc**
 
-.. _rename_principal_end:
-
 .. _delete_principal:
 
 delete_principal
@@ -484,8 +474,6 @@ This command requires the **delete** privilege.
 
 Alias: **delprinc**
 
-.. _delete_principal_end:
-
 .. _change_password:
 
 change_password
@@ -529,8 +517,6 @@ Example::
     Password for systest@BLEEP.COM changed.
     kadmin:
 
-.. _change_password_end:
-
 .. _purgekeys:
 
 purgekeys
@@ -546,8 +532,6 @@ is new in release 1.12.
 
 This command requires the **modify** privilege.
 
-.. _purgekeys_end:
-
 .. _get_principal:
 
 get_principal
@@ -588,8 +572,6 @@ Examples::
     tlyu/admin@BLEEP.COM     786100034 0    0
     kadmin:
 
-.. _get_principal_end:
-
 .. _list_principals:
 
 list_principals
@@ -618,8 +600,6 @@ Example::
     testuser@SECURE-TEST.OV.COM
     kadmin:
 
-.. _list_principals_end:
-
 .. _get_strings:
 
 get_strings
@@ -633,8 +613,6 @@ This command requires the **inquire** privilege.
 
 Alias: **getstrs**
 
-.. _get_strings_end:
-
 .. _set_string:
 
 set_string
@@ -680,8 +658,6 @@ Example::
     set_string host/foo.mit.edu session_enctypes aes128-cts
     set_string user@FOO.COM otp "[{""type"":""hotp"",""username"":""al""}]"
 
-.. _set_string_end:
-
 .. _del_string:
 
 del_string
@@ -695,8 +671,6 @@ This command requires the **delete** privilege.
 
 Alias: **delstr**
 
-.. _del_string_end:
-
 .. _add_policy:
 
 add_policy
@@ -773,8 +747,6 @@ Example::
     kadmin: add_policy -maxlife "2 days" -minlength 5 guests
     kadmin:
 
-.. _add_policy_end:
-
 .. _modify_policy:
 
 modify_policy
@@ -789,8 +761,6 @@ This command requires the **modify** privilege.
 
 Alias: **modpol**
 
-.. _modify_policy_end:
-
 .. _delete_policy:
 
 delete_policy
@@ -813,8 +783,6 @@ Example::
     (yes/no): yes
     kadmin:
 
-.. _delete_policy_end:
-
 .. _get_policy:
 
 get_policy
@@ -849,8 +817,6 @@ The "Reference count" is the number of principals using that policy.
 With the LDAP KDC database module, the reference count field is not
 meaningful.
 
-.. _get_policy_end:
-
 .. _list_policies:
 
 list_policies
@@ -881,8 +847,6 @@ Examples::
     test-pol-nopw
     kadmin:
 
-.. _list_policies_end:
-
 .. _ktadd:
 
 ktadd
@@ -932,8 +896,6 @@ Example::
          FILE:/tmp/foo-new-keytab
     kadmin:
 
-.. _ktadd_end:
-
 .. _ktremove:
 
 ktremove
@@ -968,8 +930,6 @@ Example::
          FILE:/etc/krb5.keytab
     kadmin:
 
-.. _ktremove_end:
-
 lock
 ~~~~
 
diff --git a/doc/admin/appl_servers.rst b/doc/admin/appl_servers.rst
index afdf30297..e9d16e877 100644
--- a/doc/admin/appl_servers.rst
+++ b/doc/admin/appl_servers.rst
@@ -4,9 +4,9 @@ Application servers
 If you need to install the Kerberos V5 programs on an application
 server, please refer to the Kerberos V5 Installation Guide.  Once you
 have installed the software, you need to add that host to the Kerberos
-database (see :ref:`add_mod_del_princs`), and generate a keytab for
-that host, that contains the host's key.  You also need to make sure
-the host's clock is within your maximum clock skew of the KDCs.
+database (see :ref:`principals`), and generate a keytab for that host,
+that contains the host's key.  You also need to make sure the host's
+clock is within your maximum clock skew of the KDCs.
 
 
 Keytabs
@@ -30,34 +30,23 @@ Adding principals to keytabs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To generate a keytab, or to add a principal to an existing keytab, use
-the **ktadd** command from kadmin.
-
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  _ktadd:
-   :end-before: _ktadd_end:
-
-
-Examples
-########
-
-Here is a sample session, using configuration files that enable only
-AES encryption::
+the **ktadd** command from kadmin.  Here is a sample session, using
+configuration files that enable only AES encryption::
 
     kadmin: ktadd host/daffodil.mit.edu@ATHENA.MIT.EDU
     Entry for principal host/daffodil.mit.edu with kvno 2, encryption type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab
     Entry for principal host/daffodil.mit.edu with kvno 2, encryption type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab
-    kadmin:
 
 
 Removing principals from keytabs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To remove a principal from an existing keytab, use the kadmin
-**ktremove** command.
+**ktremove** command::
 
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  _ktremove:
-   :end-before: _ktremove_end:
+    kadmin:  ktremove host/daffodil.mit.edu@ATHENA.MIT.EDU
+    Entry for principal host/daffodil.mit.edu with kvno 2 removed from keytab FILE:/etc/krb5.keytab.
+    Entry for principal host/daffodil.mit.edu with kvno 2 removed from keytab FILE:/etc/krb5.keytab.
 
 
 Using a keytab to acquire client credentials
diff --git a/doc/admin/conf_ldap.rst b/doc/admin/conf_ldap.rst
index 604faa842..65542c1a4 100644
--- a/doc/admin/conf_ldap.rst
+++ b/doc/admin/conf_ldap.rst
@@ -87,8 +87,7 @@ Configuring Kerberos with OpenLDAP back-end
        ldap_service_password_file
        ldap_servers
 
- 8. Create the realm using :ref:`kdb5_ldap_util(8)` (see
-    :ref:`ldap_create_realm`)::
+ 8. Create the realm using :ref:`kdb5_ldap_util(8)`:
 
        kdb5_ldap_util create -subtrees ou=users,dc=example,dc=com -s
 
diff --git a/doc/admin/database.rst b/doc/admin/database.rst
index eb6417288..2fd07242a 100644
--- a/doc/admin/database.rst
+++ b/doc/admin/database.rst
@@ -39,29 +39,7 @@ See :ref:`kadmin(1)` for the available kadmin and kadmin.local
 commands and options.
 
 
-kadmin options
---------------
-
-You can invoke :ref:`kadmin(1)` or kadmin.local with any of the
-following options:
-
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  kadmin_synopsis:
-   :end-before: kadmin_synopsis_end:
-
-**OPTIONS**
-
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  _kadmin_options:
-   :end-before: _kadmin_options_end:
-
-
-Date Format
------------
-
-For the supported date-time formats see :ref:`getdate` section
-in :ref:`datetime`.
-
+.. _principals:
 
 Principals
 ----------
@@ -69,122 +47,52 @@ Principals
 Each entry in the Kerberos database contains a Kerberos principal and
 the attributes and policies associated with that principal.
 
-
-.. _add_mod_del_princs:
-
-Adding, modifying and deleting principals
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 To add a principal to the database, use the :ref:`kadmin(1)`
-**add_principal** command.
-
-To modify attributes of a principal, use the kadmin
-**modify_principal** command.
-
-To delete a principal, use the kadmin **delete_principal** command.
-
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  _add_principal:
-   :end-before: _add_principal_end:
-
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  _modify_principal:
-   :end-before: _modify_principal_end:
-
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  _delete_principal:
-   :end-before: _delete_principal_end:
+**add_principal** command.  User principals should usually be created
+with the ``+requires_preauth -allow_svr`` options to help mitigate
+dictionary attacks (see :ref:`dictionary`)::
 
+    kadmin: addprinc +requires_preauth -allow_svr alice
+    Enter password for principal "alice@KRBTEST.COM":
+    Re-enter password for principal "alice@KRBTEST.COM":
 
-Examples
-########
+User principals which will authenticate with :ref:`pkinit` should
+instead by created with the ``-nokey`` option:
 
-If you want to create a principal which is contained by a LDAP object,
-all you need to do is::
+    kadmin: addprinc -nokey alice
 
-    kadmin: addprinc -x dn=cn=jennifer,dc=example,dc=com jennifer
-    No policy specified for "jennifer@ATHENA.MIT.EDU";
-    defaulting to no policy.
-    Enter password for principal jennifer@ATHENA.MIT.EDU:  <= Type the password.
-    Re-enter password for principal jennifer@ATHENA.MIT.EDU:  <=Type it again.
-    Principal "jennifer@ATHENA.MIT.EDU" created.
-    kadmin:
-
-If you want to create a principal under a specific LDAP container and
-link to an existing LDAP object, all you need to do is::
-
-    kadmin: addprinc -x containerdn=dc=example,dc=com -x linkdn=cn=david,dc=example,dc=com david
-    No policy specified for "david@ATHENA.MIT.EDU";
-    defaulting to no policy.
-    Enter password for principal david@ATHENA.MIT.EDU:  <= Type the password.
-    Re-enter password for principal david@ATHENA.MIT.EDU:  <=Type it again.
-    Principal "david@ATHENA.MIT.EDU" created.
-    kadmin:
+Service principals can be created with the ``-nokey`` option;
+long-term keys will be added when a keytab is generated::
 
-If you want to associate a ticket policy to a principal, all you need
-to do is::
+    kadmin: addprinc -nokey host/foo.mit.edu
+    kadmin: ktadd -k foo.keytab host/foo.mit.edu
+    Entry for principal host/foo.mit.edu with kvno 1, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:foo.keytab.
+    Entry for principal host/foo.mit.edu with kvno 1, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:foo.keytab.
 
-    kadmin: modprinc -x tktpolicy=userpolicy david
-    Principal "david@ATHENA.MIT.EDU" modified.
-    kadmin:
-
-If, on the other hand, you want to set up an account that expires on
-January 1, 2000, that uses a policy called "stduser", with a temporary
-password (which you want the user to change immediately), you would
-type the following::
-
-    kadmin: addprinc david -expire "1/1/2000 12:01am EST" -policy stduser +needchange
-    Enter password for principal david@ATHENA.MIT.EDU:  <= Type the password.
-    Re-enter password for principal
-    david@ATHENA.MIT.EDU:  <= Type it again.
-    Principal "david@ATHENA.MIT.EDU" created.
-    kadmin:
+To modify attributes of an existing principal, use the kadmin
+**modify_principal** command::
 
-If you want to delete a principal::
+    kadmin: modprinc -expire tomorrow alice
+    Principal "alice@KRBTEST.COM" modified.
 
-    kadmin: delprinc jennifer
-    Are you sure you want to delete the principal
-    "jennifer@ATHENA.MIT.EDU"? (yes/no): yes
-    Principal "jennifer@ATHENA.MIT.EDU" deleted.
-    Make sure that you have removed this principal from
-    all ACLs before reusing.
-    kadmin:
+To delete a principal, use the kadmin **delete_principal** command::
 
+    kadmin: delprinc alice
+    Are you sure you want to delete the principal "alice@KRBTEST.COM"? (yes/no): yes
+    Principal "alice@KRBTEST.COM" deleted.
+    Make sure that you have removed this principal from all ACLs before reusing.
 
-Retrieving information about a principal
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To change a principal's password, use the kadmin **change_password**
+command.  Password changes made through kadmin are subject to the same
+password policies as would apply to password changes made through
+:ref:`kpasswd(1)`.
 
-To retrieve a listing of the attributes and/or policies associated
-with a principal, use the :ref:`kadmin(1)` **get_principal** command.
+To view the attributes of a principal, use the kadmin`
+**get_principal** command.
 
 To generate a listing of principals, use the kadmin
 **list_principals** command.
 
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  _get_principal:
-   :end-before: _get_principal_end:
-
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  _list_principals:
-   :end-before: _list_principals_end:
-
-
-Changing passwords
-~~~~~~~~~~~~~~~~~~
-
-To change a principal's password use the :ref:`kadmin(1)`
-**change_password** command.
-
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  _change_password:
-   :end-before: _change_password_end:
-
-.. note::
-
-          Password changes through kadmin are subject to the same
-          password policies as would apply to password changes through
-          :ref:`kpasswd(1)`.
-
 
 .. _policies:
 
@@ -196,60 +104,25 @@ minimum and maximum password lifetimes, minimum number of characters
 and character classes a password must contain, and the number of old
 passwords kept in the database.
 
+To add a new policy, use the :ref:`kadmin(1)` **add_policy** command::
 
-Adding, modifying and deleting policies
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To add a new policy, use the :ref:`kadmin(1)` **add_policy** command.
+    kadmin: addpol -maxlife "1 year" -history 3 stduser
 
 To modify attributes of a principal, use the kadmin **modify_policy**
+command.  To delete a policy, use the kadmin **delete_policy**
 command.
 
-To delete a policy, use the kadmin **delete_policy** command.
-
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  _add_policy:
-   :end-before: _add_policy_end:
-
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  _modify_policy:
-   :end-before: _modify_policy_end:
-
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  _delete_policy:
-   :end-before: _delete_policy_end:
-
-.. note::
-
-          You must cancel the policy from *all* principals before
-          deleting it.  The *delete_policy* command will fail if the policy
-          is in use by any principals.
-
-
-Retrieving policies
-~~~~~~~~~~~~~~~~~~~
+To associate a policy with a principal, use the kadmin
+**modify_principal** command with the **-policy** option:
 
-To retrieve a policy, use the :ref:`kadmin(1)` **get_policy** command.
+    kadmin: modprinc -policy stduser alice
+    Principal "alice@KRBTEST.COM" modified.
 
-You can retrieve the list of policies with the kadmin
-**list_policies** command.
-
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  _get_policy:
-   :end-before: _get_policy_end:
-
-.. include:: admin_commands/kadmin_local.rst
-   :start-after:  _list_policies:
-   :end-before: _list_policies_end:
-
-
-Policies and principals
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Policies can be applied to principals as they are created by using
-the **-policy** flag to :ref:`add_principal`. Existing principals can
-be modified by using the **-policy** or **-clearpolicy** flag to
-:ref:`modify_principal`.
+A principal entry may be associated with a nonexistent policy, either
+because the policy did not exist at the time of associated or was
+deleted afterwards.  kadmin will warn when associated a principal with
+a nonexistent policy, and will annotate the policy name with "[does
+not exist]" in the **get_principal** output.
 
 
 .. _updating_history_key:
@@ -302,175 +175,69 @@ Operations on the Kerberos database
 -----------------------------------
 
 The :ref:`kdb5_util(8)` command is the primary tool for administrating
-the Kerberos database.
-
-.. include:: admin_commands/kdb5_util.rst
-   :start-after:  _kdb5_util_synopsis:
-   :end-before: _kdb5_util_synopsis_end:
-
-**OPTIONS**
+the Kerberos database when using the DB2 or LMDB modules (see
+:ref:`dbtypes`).  Creating a database is described in
+:ref:`create_db`.
 
-.. include:: admin_commands/kdb5_util.rst
-   :start-after:  _kdb5_util_options:
-   :end-before: _kdb5_util_options_end:
-
-.. toctree::
-   :maxdepth: 1
+To create a stash file using the master password (because the database
+was not created with one using the ``create -s`` flag, or after
+restoring from a backup which did not contain the stash file), use the
+kdb5_util **stash** command::
 
+    $ kdb5_util stash
+    kdb5_util: Cannot find/read stored master key while reading master key
+    kdb5_util: Warning: proceeding without master key
+    Enter KDC database master key:  <= Type the KDC database master password.
 
-Dumping a Kerberos database to a file
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To destroy a database, use the kdb5_util destroy command::
 
-To dump a Kerberos database into a file, use the :ref:`kdb5_util(8)`
-**dump** command on one of the KDCs.
+    $ kdb5_util destroy
+    Deleting KDC database stored in '/var/krb5kdc/principal', are you sure?
+    (type 'yes' to confirm)? yes
+    OK, deleting database '/var/krb5kdc/principal'...
+    ** Database '/var/krb5kdc/principal' destroyed.
 
-.. include:: admin_commands/kdb5_util.rst
-   :start-after:  _kdb5_util_dump:
-   :end-before: _kdb5_util_dump_end:
 
+.. _restore_from_dump:
 
-Examples
-########
+Dumping and loading a Kerberos database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-::
+To dump a Kerberos database into a text file for backup or transfer
+purposes, use the :ref:`kdb5_util(8)` **dump** command on one of the
+KDCs::
 
-    shell% kdb5_util dump dumpfile
-    shell%
+    $ kdb5_util dump dumpfile
 
-    shell% kbd5_util dump -verbose dumpfile
+    $ kbd5_util dump -verbose dumpfile
     kadmin/admin@ATHENA.MIT.EDU
     krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
     kadmin/history@ATHENA.MIT.EDU
     K/M@ATHENA.MIT.EDU
     kadmin/changepw@ATHENA.MIT.EDU
-    shell%
 
-If you specify which principals to dump, you must use the full
-principal, as in the following example::
+You may specify which principals to dump, using full principal names
+including realm::
 
-    shell% kdb5_util dump -verbose dumpfile K/M@ATHENA.MIT.EDU kadmin/admin@ATHENA.MIT.EDU
+    $ kdb5_util dump -verbose someprincs K/M@ATHENA.MIT.EDU kadmin/admin@ATHENA.MIT.EDU
     kadmin/admin@ATHENA.MIT.EDU
     K/M@ATHENA.MIT.EDU
-    shell%
-
-Otherwise, the principals will not match those in the database and
-will not be dumped::
-
-     shell% kdb5_util dump -verbose dumpfile K/M kadmin/admin
-     shell%
-
-If you do not specify a dump file, kdb5_util will dump the database to
-the standard output.
-
-
-.. _restore_from_dump:
-
-Restoring a Kerberos database from a dump file
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To restore a Kerberos database dump from a file, use the
-:ref:`kdb5_util(8)` **load** command on one of the KDCs.
-
-.. include:: admin_commands/kdb5_util.rst
-   :start-after:  _kdb5_util_load:
-   :end-before: _kdb5_util_load_end:
-
+:ref:`kdb5_util(8)` **load** command::
 
-Examples
-########
+    $ kdb5_util load dumpfile
 
-To dump a single principal and later load it, updating the database:
-
-::
-
-     shell% kdb5_util dump dumpfile principal@REALM
-     shell%
-
-     shell% kdb5_util load -update dumpfile
-     shell%
+To update an existing database with a partial dump file containing
+only some principals, use the ``-update`` flag::
 
+    $ kdb5_util load -update someprincs
 
 .. note::
 
           If the database file exists, and the *-update* flag was not
           given, *kdb5_util* will overwrite the existing database.
 
-.. note::
-
-          Using kdb5_util to dump and reload the principal database is
-          only necessary when upgrading from versions of krb5 prior
-          to 1.2.0---newer versions will use the existing database as-is.
-
-
-.. _create_stash:
-
-Creating a stash file
-~~~~~~~~~~~~~~~~~~~~~
-
-A stash file allows a KDC to authenticate itself to the database
-utilities, such as :ref:`kadmind(8)`, :ref:`krb5kdc(8)`, and
-:ref:`kdb5_util(8)`.
-
-To create a stash file, use the :ref:`kdb5_util(8)` **stash** command.
-
-.. include:: admin_commands/kdb5_util.rst
-   :start-after: _kdb5_util_stash:
-   :end-before: _kdb5_util_stash_end:
-
-
-Example
-#######
-
-    shell% kdb5_util stash
-    kdb5_util: Cannot find/read stored master key while reading master key
-    kdb5_util: Warning: proceeding without master key
-    Enter KDC database master key:  <= Type the KDC database master password.
-    shell%
-
-If you do not specify a stash file, kdb5_util will stash the key in
-the file specified in your :ref:`kdc.conf(5)` file.
-
-
-Creating and destroying a Kerberos database
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you need to create a new Kerberos database, use the
-:ref:`kdb5_util(8)` **create** command.
-
-.. include:: admin_commands/kdb5_util.rst
-   :start-after: _kdb5_util_create:
-   :end-before: _kdb5_util_create_end:
-
-If you need to destroy the current Kerberos database, use the
-:ref:`kdb5_util(8)` **destroy** command.
-
-.. include:: admin_commands/kdb5_util.rst
-   :start-after: _kdb5_util_destroy:
-   :end-before: _kdb5_util_destroy_end:
-
-
-Examples
-########
-
-::
-
-    shell% kdb5_util -r ATHENA.MIT.EDU create -s
-    Loading random data
-    Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU',
-    master key name 'K/M@ATHENA.MIT.EDU'
-    You will be prompted for the database Master Password.
-    It is important that you NOT FORGET this password.
-    Enter KDC database master key:  <= Type the master password.
-    Re-enter KDC database master key to verify:  <= Type it again.
-    shell%
-
-    shell% kdb5_util -r ATHENA.MIT.EDU destroy
-    Deleting KDC database stored in '/usr/local/var/krb5kdc/principal', are you sure?
-    (type 'yes' to confirm)?  <= yes
-    OK, deleting database '/usr/local/var/krb5kdc/principal'...
-    ** Database '/usr/local/var/krb5kdc/principal' destroyed.
-    shell%
-
 
 .. _updating_master_key:
 
@@ -538,152 +305,89 @@ availability.  To roll over the master key, follow these steps:
 Operations on the LDAP database
 -------------------------------
 
-The :ref:`kdb5_ldap_util(8)` is the primary tool for administrating
-the Kerberos LDAP database.  It allows an administrator to manage
-realms, Kerberos services (KDC and Admin Server) and ticket policies.
-
-.. include:: admin_commands/kdb5_ldap_util.rst
-   :start-after:  _kdb5_ldap_util_synopsis:
-   :end-before: _kdb5_ldap_util_synopsis_end:
-
-**OPTIONS**
-
-.. include:: admin_commands/kdb5_ldap_util.rst
-   :start-after:  _kdb5_ldap_util_options:
-   :end-before: _kdb5_ldap_util_options_end:
-
-
-.. _ldap_create_realm:
-
-Creating a Kerberos realm
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you need to create a new realm, use the :ref:`kdb5_ldap_util(8)`
-**create** command as follows.
-
-.. include:: admin_commands/kdb5_ldap_util.rst
-   :start-after:  _kdb5_ldap_util_create:
-   :end-before: _kdb5_ldap_util_create_end:
-
-
-.. _ldap_mod_realm:
-
-Modifying a Kerberos realm
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you need to modify a realm, use the :ref:`kdb5_ldap_util(8)`
-**modify** command as follows.
+The :ref:`kdb5_ldap_util(8)` command is the primary tool for
+administrating the Kerberos database when using the LDAP module.
+Creating an LDAP Kerberos database is describe in :ref:`conf_ldap`.
 
-.. include:: admin_commands/kdb5_ldap_util.rst
-   :start-after:  _kdb5_ldap_util_modify:
-   :end-before: _kdb5_ldap_util_modify_end:
+To view a list of realms in the LDAP database, use the kdb5_ldap_util
+**list** command::
 
+    $ kdb5_ldap_util list
+    KRBTEST.COM
 
-Destroying a Kerberos realm
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To modify the attributes of a realm, use the kdb5_ldap_util **modify**
+command.  For example, to change the default realm's maximum ticket
+life::
 
-If you need to destroy a Kerberos realm, use the
-:ref:`kdb5_ldap_util(8)` **destroy** command as follows.
+    $ kdb5_ldap_util modify -maxtktlife "10 hours"
 
-.. include:: admin_commands/kdb5_ldap_util.rst
-   :start-after:  _kdb5_ldap_util_destroy:
-   :end-before: _kdb5_ldap_util_destroy_end:
+To display the attributes of a realm, use the kdb5_ldap_util **view**
+command::
 
+    $ kdb5_ldap_util view
+                   Realm Name: KRBTEST.COM
+          Maximum Ticket Life: 0 days 00:10:00
 
-Retrieving information about a Kerberos realm
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To remove a realm from the LDAP database, destroying its contents, use
+the kdb5_ldap_util **destroy** command::
 
-If you need to display the attributes of a realm, use the
-:ref:`kdb5_ldap_util(8)` **view** command as follows.
-
-.. include:: admin_commands/kdb5_ldap_util.rst
-   :start-after:  _kdb5_ldap_util_view:
-   :end-before: _kdb5_ldap_util_view_end:
-
-
-Listing available Kerberos realms
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you need to display the list of the realms, use the
-:ref:`kdb5_ldap_util(8)` **list** command as follows.
-
-.. include:: admin_commands/kdb5_ldap_util.rst
-   :start-after:  _kdb5_ldap_util_list:
-   :end-before: _kdb5_ldap_util_list_end:
-
-
-.. _stash_ldap:
-
-Stashing service object's password
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The :ref:`kdb5_ldap_util(8)` **stashsrvpw** command allows an
-administrator to store the password of service object in a file.  The
-KDC and Administration server uses this password to authenticate to
-the LDAP server.
-
-.. include:: admin_commands/kdb5_ldap_util.rst
-   :start-after:  _kdb5_ldap_util_stashsrvpw:
-   :end-before: _kdb5_ldap_util_stashsrvpw_end:
+    $ kdb5_ldap_util destroy
+    Deleting KDC database of 'KRBTEST.COM', are you sure?
+    (type 'yes' to confirm)? yes
+    OK, deleting database of 'KRBTEST.COM'...
+    ** Database of 'KRBTEST.COM' destroyed.
 
 
 Ticket Policy operations
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Creating a Ticket Policy
-########################
-
-To create a new ticket policy in directory , use the
-:ref:`kdb5_ldap_util(8)` **create_policy** command.  Ticket policy
-objects are created under the realm container.
-
-.. include:: admin_commands/kdb5_ldap_util.rst
-   :start-after:  _kdb5_ldap_util_create_policy:
-   :end-before: _kdb5_ldap_util_create_policy_end:
-
-
-Modifying a Ticket Policy
-#########################
-
-To modify a ticket policy in directory, use the
-:ref:`kdb5_ldap_util(8)` **modify_policy** command.
+Unlike the DB2 and LMDB modules, the LDAP module supports ticket
+policy objects, which can be associated with principals to restrict
+maximum ticket lifetimes and set mandatory principal flags.  Ticket
+policy objects are distinct from the password policies described
+earlier on this page, and are chiefly managed through kdb5_ldap_util
+rather than kadmin.  To create a new ticket policy, use the
+kdb5_ldap_util **create_policy** command::
 
-.. include:: admin_commands/kdb5_ldap_util.rst
-   :start-after:  _kdb5_ldap_util_modify_policy:
-   :end-before: _kdb5_ldap_util_modify_policy_end:
+    $ kdb5_ldap_util create_policy -maxrenewlife "2 days" users
 
+To associate a ticket policy with a principal, use the
+:ref:`kadmin(1)` **modify_principal** (or **add_principal**) command
+with the **-x tktpolicy=**\ *policy* option::
 
-Retrieving Information About a Ticket Policy
-############################################
+    $ kadmin.local modprinc -x tktpolicy=users alice
 
-To display the attributes of a ticket policy, use the
-:ref:`kdb5_ldap_util(8)` **view_policy** command.
+To remove a ticket policy reference from a principal, use the same
+command with an empty *policy*::
 
-.. include:: admin_commands/kdb5_ldap_util.rst
-   :start-after:  _kdb5_ldap_util_view_policy:
-   :end-before: _kdb5_ldap_util_view_policy_end:
+    $ kadmin.local modprinc -x tktpolicy= alice
 
+To list the existing ticket policy objects, use the kdb5_ldap_util
+**list_policy** command::
 
-Destroying a Ticket Policy
-##########################
+    $ kdb5_ldap_util list_policy
+    users
 
-To destroy an existing ticket policy, use the :ref:`kdb5_ldap_util(8)`
-**destroy_policy** command.
+To modify the attributes of a ticket policy object, use the
+kdb5_ldap_util **modify_policy** command::
 
-.. include:: admin_commands/kdb5_ldap_util.rst
-   :start-after:  _kdb5_ldap_util_destroy_policy:
-   :end-before: _kdb5_ldap_util_destroy_policy_end:
+    $ kdb5_ldap_util modify_policy -allow_svr +requires_preauth users
 
+To view the attributes of a ticket policy object, use the
+kdb5_ldap_util **view_policy** command::
 
-Listing available Ticket Policies
-#################################
+    $ kdb5_ldap_util view_policy users
+                Ticket policy: users
+       Maximum renewable life: 2 days 00:00:00
+                 Ticket flags: REQUIRES_PRE_AUTH DISALLOW_SVR
 
-To list the name of ticket policies in a realm, use the
-:ref:`kdb5_ldap_util(8)` **list_policy** command.
+To destroy an ticket policy object, use the kdb5_ldap_util
+**destroy_policy** command::
 
-.. include:: admin_commands/kdb5_ldap_util.rst
-   :start-after:  _kdb5_ldap_util_list_policy:
-   :end-before: _kdb5_ldap_util_list_policy_end:
+    $ kdb5_ldap_util destroy_policy users
+    This will delete the policy object 'users', are you sure?
+    (type 'yes' to confirm)? yes
+    ** policy object 'users' deleted.
 
 
 .. _xrealm_authn:
diff --git a/doc/admin/dbtypes.rst b/doc/admin/dbtypes.rst
index 02f79ac9d..047481765 100644
--- a/doc/admin/dbtypes.rst
+++ b/doc/admin/dbtypes.rst
@@ -1,3 +1,5 @@
+.. _dbtypes:
+
 Database types
 ==============
 
diff --git a/doc/admin/install_appl_srv.rst b/doc/admin/install_appl_srv.rst
index 6b2d8e471..2e1981385 100644
--- a/doc/admin/install_appl_srv.rst
+++ b/doc/admin/install_appl_srv.rst
@@ -33,7 +33,7 @@ the machine's root password.
 
 In order to generate a keytab for a host, the host must have a
 principal in the Kerberos database.  The procedure for adding hosts to
-the database is described fully in :ref:`add_mod_del_princs`.  (See
+the database is described fully in :ref:`principals`.  (See
 :ref:`replica_host_key` for a brief description.)  The keytab is
 generated by running :ref:`kadmin(1)` and issuing the :ref:`ktadd`
 command.
diff --git a/doc/admin/install_kdc.rst b/doc/admin/install_kdc.rst
index 4d9017264..8cab6514b 100644
--- a/doc/admin/install_kdc.rst
+++ b/doc/admin/install_kdc.rst
@@ -488,7 +488,7 @@ Add Kerberos principals to the database
 Once your KDCs are set up and running, you are ready to use
 :ref:`kadmin(1)` to load principals for your users, hosts, and other
 services into the Kerberos database.  This procedure is described
-fully in :ref:`add_mod_del_princs`.
+fully in :ref:`principals`.
 
 You may occasionally want to use one of your replica KDCs as the
 primary.  This might happen if you are upgrading the primary KDC, or