Rename doc subdirectories

We like these names better, and they match the PDF document filenames.

admins -> admin
appldev -> appdev
users -> user

and catch up where the names are used elsewhere.

The relay/ directory has been removed, with its contents moved to the
top level in build_this.rst and a new about.rst.

The section headers for kadmind, krb5kdc, sserver, kpasswd, kswitch,
and sclient are misdetected as conflict markers.
bigredbutton: whitespace

ticket: 7433
tags: pullup

4 files changed, 1915 insertions, 0 deletions

diff --git a/doc/admin/conf_files/index.rst b/doc/admin/conf_files/index.rst
new file mode 100644
index 0000000000..078a173049
--- /dev/null
+++ b/doc/admin/conf_files/index.rst
@@ -0,0 +1,9 @@
+Configuration Files
+===================
+
+.. toctree::
+   :maxdepth: 1
+
+   krb5_conf
+   kdc_conf
+   kadm5_acl
diff --git a/doc/admin/conf_files/kadm5_acl.rst b/doc/admin/conf_files/kadm5_acl.rst
new file mode 100644
index 0000000000..4a8e0741e0
--- /dev/null
+++ b/doc/admin/conf_files/kadm5_acl.rst
@@ -0,0 +1,136 @@
+.. _kadm5.acl(5):
+
+kadm5.acl
+=========
+
+DESCRIPTION
+-----------
+
+The Kerberos :ref:`kadmind(8)` daemon uses an Access Control List
+(ACL) file to manage access rights to the Kerberos database.
+For operations that affect principals, the ACL file also controls
+which principals can operate on which other principals.
+
+The default location of the Kerberos ACL file is
+|kdcdir|\ ``/kadm5.acl``  unless this is overridden by the *acl_file*
+variable in :ref:`kdc.conf(5)`.
+
+SYNTAX
+------
+
+Empty lines and lines starting with the sharp sign (``#``) are
+ignored.  Lines containing ACL entries have the format:
+
+ ::
+
+    principal  permissions  [target_principal  [restrictions] ]
+
+.. note:: Line order in the ACL file is important.  The first matching entry
+          will control access for an actor principal on a target principal.
+
+*principal*
+    (Partially or fully qualified Kerberos principal name.) Specifies
+    the principal whose permissions are to be set.
+
+    Each component of the name may be wildcarded using the ``*``
+    character.
+
+*permissions*
+    Specifies what operations may or may not be performed by a
+    *principal* matching a particular entry.  This is a string of one or
+    more of the following list of characters or their upper-case
+    counterparts.  If the character is *upper-case*, then the operation
+    is disallowed.  If the character is *lower-case*, then the operation
+    is permitted.
+
+    == ======================================================
+    a  [Dis]allows the addition of principals or policies
+    c  [Dis]allows the changing of passwords for principals
+    d  [Dis]allows the deletion of principals or policies
+    i  [Dis]allows inquiries about principals or policies
+    l  [Dis]allows the listing of principals or policies
+    m  [Dis]allows the modification of principals or policies
+    p  [Dis]allows the propagation of the principal database (used in :ref:`incr_db_prop`)
+    s  [Dis]allows the explicit setting of the key for a principal
+    x  Short for admcil. All privileges
+    \* Same as x.
+    == ======================================================
+
+
+*target_principal*
+    (Optional. Partially or fully qualified Kerberos principal name.)
+    Specifies the principal on which *permissions* may be applied.
+    Each component of the name may be wildcarded using the ``*``
+    character.
+
+    *target_principal* can also include back-references to *principal*,
+    in which ``*number`` matches the component number in *principal*.
+
+*restrictions*
+    (Optional) A string of flags. Allowed restrictions are:
+
+        {+\|-}\ *flagname*
+            flag is forced to the indicated value.  The permissible flags
+            are the same as the + and - flags for the kadmin
+            :ref:`add_principal` and :ref:`modify_principal` commands.
+
+        *-clearpolicy*
+            policy is forced to be empty.
+
+        *-policy pol*
+            policy is forced to be *pol*.
+
+        -{*expire, pwexpire, maxlife, maxrenewlife*} *time*
+            (:ref:`getdate` string) 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.
+
+.. warning::
+    If the kadmind ACL file is modified, the kadmind daemon needs to be
+    restarted for changes to take effect.
+
+EXAMPLE
+-------
+
+Here is an example of a kadm5.acl file.
+
+ ::
+
+    */admin@ATHENA.MIT.EDU        *                           # line 1
+    joeadmin@ATHENA.MIT.EDU   ADMCIL                          # line 2
+    joeadmin/*@ATHENA.MIT.EDU il  */root@ATHENA.MIT.EDU       # line 3
+    */root@ATHENA.MIT.EDU     cil *1@ATHENA.MIT.EDU           # line 4
+    */*@ATHENA.MIT.EDU        i                               # line 5
+    */admin@EXAMPLE.COM       x   * -maxlife 9h -postdateable # line 6
+
+(line 1) Any principal in the ``ATHENA.MIT.EDU`` realm with
+an ``admin`` instance has all administrative privileges.
+
+(lines 1-3) The user ``joeadmin`` has all permissions with his
+``admin`` instance, ``joeadmin/admin@ATHENA.MIT.EDU`` (matches line
+1).  He has no permissions at all with his null instance,
+``joeadmin@ATHENA.MIT.EDU`` (matches line 2).  His ``root`` and other
+non-``admin``, non-null instances (e.g., ``extra`` or ``dbadmin``) have
+inquire and list permissions with any principal that has the
+instance ``root`` (matches line 3).
+
+(line 4) Any ``root`` principal in ``ATHENA.MIT.EDU`` can inquire, list,
+or change the password of their null instance, but not any other
+null instance.  (Here, "\*1" denotes a back-reference to the first
+component of the actor principal.)
+
+(line 5) Any principal in the realm ``ATHENA.MIT.EDU`` (except for
+``joeadmin@ATHENA.MIT.EDU``, as mentioned above) has inquire
+privileges.
+
+(line 6) 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.
+
+SEE ALSO
+--------
+
+:ref:`kdc.conf(5)`, :ref:`kadmind(8)`
diff --git a/doc/admin/conf_files/kdc_conf.rst b/doc/admin/conf_files/kdc_conf.rst
new file mode 100644
index 0000000000..4da8d936f2
--- /dev/null
+++ b/doc/admin/conf_files/kdc_conf.rst
@@ -0,0 +1,714 @@
+.. _kdc.conf(5):
+
+kdc.conf
+========
+
+The kdc.conf file supplements :ref:`krb5.conf(5)` for programs which
+are typically only used on a KDC, such as the :ref:`krb5kdc(8)` and
+:ref:`kadmind(8)` daemons and the :ref:`kdb5_util(8)` program.
+Relations documented here may also be specified in krb5.conf.
+
+Normally, the kdc.conf file is found in the KDC state directory,
+|kdcdir|.  You can override the default location by setting the
+environment variable **KRB5_KDC_PROFILE**.
+
+Please note that you need to restart the KDC daemon for any configuration
+changes to take effect.
+
+Structure
+---------
+
+The kdc.conf file is set up in the same format as the
+:ref:`krb5.conf(5)` file.
+
+
+Sections
+--------
+
+The kdc.conf file may contain the following sections:
+
+==================== =================================================
+:ref:`kdcdefaults`   Default values for KDC behavior
+:ref:`kdc_realms`    Realm-specific database configuration and settings
+:ref:`dbdefaults`    Default database settings
+:ref:`dbmodules`     Per-database settings
+:ref:`logging`       Controls how Kerberos daemons perform logging
+==================== =================================================
+
+
+.. _kdcdefaults:
+
+[kdcdefaults]
+~~~~~~~~~~~~~
+
+With one exception, relations in the [kdcdefaults] section specify
+default values for realm variables, to be used if the [realms]
+subsection does not contain a relation for the tag.  See the
+:ref:`kdc_realms` section for the definitions of these relations.
+
+* **host_based_services**
+* **kdc_ports**
+* **kdc_tcp_ports**
+* **no_host_referral**
+* **restrict_anonymous_to_tgt**
+
+**kdc_max_dgram_reply_size**
+    Specifies the maximum packet size that can be sent over UDP.  The
+    default value is 4096 bytes.
+
+
+.. _kdc_realms:
+
+[realms]
+~~~~~~~~
+
+Each tag in the [realms] section is the name of a Kerberos realm.
+The value of the tag is a subsection where the relations define KDC
+parameters for that particular realm.
+
+For each realm, the following tags may be specified:
+
+**acl_file**
+    (String.)  Location of the access control list file that
+    :ref:`kadmind(8)` uses to determine which principals are allowed
+    which permissions on the Kerberos database.  The default value is
+    |kdcdir|\ ``/kadm5.acl``.  For more information on Kerberos ACL
+    file see :ref:`kadm5.acl(5)`.
+
+**database_module**
+    This relation indicates the name of the configuration section
+    under :ref:`dbmodules` for database specific parameters used by
+    the loadable database library.
+
+**database_name**
+    (String.)  This string specifies the location of the Kerberos
+    database for this realm, if the DB2 back-end is being used.  If a
+    **database_module** is specified for the realm and the
+    corresponding module contains a **database_name** parameter, that
+    value will take precedence over this one.  The default value is
+    |kdcdir|\ ``/principal``.
+
+**default_principal_expiration**
+    (:ref:`abstime` string.)  Specifies the default expiration date of
+    principals created in this realm.  The default value is 0, which
+    means no expiration date.
+
+**default_principal_flags**
+    (Flag string.)  Specifies the default attributes of principals
+    created in this realm.  The format for this string is a
+    comma-separated list of flags, with '+' before each flag that
+    should be enabled and '-' before each flag that should be
+    disabled.  The **postdateable**, **forwardable**, **tgt-based**,
+    **renewable**, **proxiable**, **dup-skey**, **allow-tickets**, and
+    **service** flags default to enabled.
+
+    There are a number of possible flags:
+
+    **allow-tickets**
+        Enabling this flag means that the KDC will issue tickets for
+        this principal.  Disabling this flag essentially deactivates
+        the principal within this realm.
+
+    **dup-skey**
+        Enabling this flag allows the principal to obtain a session
+        key for another user, permitting user-to-user authentication
+        for this principal.
+
+    **forwardable**
+        Enabling this flag allows the principal to obtain forwardable
+        tickets.
+
+    **hwauth**
+        If this flag is enabled, then the principal is required to
+        preauthenticate using a hardware device before receiving any
+        tickets.
+
+    **no-auth-data-required**
+        Enabling this flag prevents PAC data from being added to
+        service tickets for the principal.
+
+    **ok-as-delegate**
+        If this flag is enabled, it hints the client that credentials
+        can and should be delegated when authenticating to the
+        service.
+
+    **ok-to-auth-as-delegate**
+        Enabling this flag allows the principal to use S4USelf tickets.
+
+    **postdateable**
+        Enabling this flag allows the principal to obtain postdateable
+        tickets.
+
+    **preauth**
+        If this flag is enabled on a client principal, then that
+        principal is required to preauthenticate to the KDC before
+        receiving any tickets.  On a service principal, enabling this
+        flag means that service tickets for this principal will only
+        be issued to clients with a TGT that has the preauthenticated
+        bit set.
+
+    **proxiable**
+        Enabling this flag allows the principal to obtain proxy
+        tickets.
+
+    **pwchange**
+        Enabling this flag forces a password change for this
+        principal.
+
+    **pwservice**
+        If this flag is enabled, it marks this principal as a password
+        change service.  This should only be used in special cases,
+        for example, if a user's password has expired, then the user
+        has to get tickets for that principal without going through
+        the normal password authentication in order to be able to
+        change the password.
+
+    **renewable**
+        Enabling this flag allows the principal to obtain renewable
+        tickets.
+
+    **service**
+        Enabling this flag allows the the KDC to issue service tickets
+        for this principal.
+
+    **tgt-based**
+        Enabling this flag allows a principal to obtain tickets based
+        on a ticket-granting-ticket, rather than repeating the
+        authentication process that was used to obtain the TGT.
+
+**dict_file**
+    (String.)  Location of the dictionary file containing strings that
+    are not allowed as passwords.  If none is specified or if there is
+    no policy assigned to the principal, no dictionary checks of
+    passwords will be performed.
+
+**host_based_services**
+    (Whitespace- or comma-separated list.)  Lists services which will
+    get host-based referral processing even if the server principal is
+    not marked as host-based by the client.
+
+**iprop_enable**
+    (Boolean value.)  Specifies whether incremental database
+    propagation is enabled.  The default value is false.
+
+**iprop_master_ulogsize**
+    (Integer.)  Specifies the maximum number of log entries to be
+    retained for incremental propagation.  The maximum value is 2500;
+    the default value is 1000.
+
+**iprop_slave_poll**
+    (Delta time string.)  Specifies how often the slave KDC polls for
+    new updates from the master.  The default value is ``2m`` (that
+    is, two minutes).
+
+**iprop_port**
+    (Port number.)  Specifies the port number to be used for
+    incremental propagation.  This is required in both master and
+    slave configuration files.
+
+**iprop_resync_timeout**
+    (Delta time string.)  Specifies the amount of time to wait for a
+    full propagation to complete.  This is optional in configuration
+    files, and is used by slave KDCs only.  The default value is 5
+    minutes (``5m``).
+
+**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 krb5 config
+    file, 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.)
+
+**kadmind_port**
+    (Port number.)  Specifies the port on which the :ref:`kadmind(8)`
+    daemon is to listen for this realm.  The assigned port for kadmind
+    is 749, which is used by default.
+
+**key_stash_file**
+    (String.)  Specifies the location where the master key has been
+    stored (via kdb5_util stash).  The default is |kdcdir|\
+    ``/.k5.REALM``, where *REALM* is the Kerberos realm.
+
+**kdc_ports**
+    (Whitespace- or comma-separated list.)  Lists the ports on which
+    the Kerberos server should listen for UDP requests, as a
+    comma-separated list of integers.  The default value is
+    ``88,750``, which are the assigned Kerberos port and the port
+    historically used by Kerberos V4.
+
+**kdc_tcp_ports**
+    (Whitespace- or comma-separated list.)  Lists the ports on which
+    the Kerberos server should listen for TCP connections, as a
+    comma-separated list of integers.  If this relation is not
+    specified, the compiled-in default is not to listen for TCP
+    connections at all.
+
+    If you wish to change this (note that the current implementation
+    has little protection against denial-of-service attacks), the
+    standard port number assigned for Kerberos TCP traffic is port 88.
+
+**master_key_name**
+    (String.)  Specifies the name of the principal associated with the
+    master key.  The default is ``K/M``.
+
+**master_key_type**
+    (Key type string.)  Specifies the master key's key type.  The
+    default value for this is |defmkey|.  For a list of all possible
+    values, see :ref:`Encryption_and_salt_types`.
+
+**max_life**
+    (:ref:`duration` string.)  Specifies the maximum time period for
+    which a ticket may be valid in this realm.  The default value is
+    24 hours.
+
+**max_renewable_life**
+    (:ref:`duration` string.)  Specifies the maximum time period
+    during which a valid ticket may be renewed in this realm.
+    The default value is 0.
+
+**no_host_referral**
+    (Whitespace- or comma-separated list.)  Lists services to block
+    from getting host-based referral processing, even if the client
+    marks the server principal as host-based or the service is also
+    listed in **host_based_services**.  ``no_host_referral = *`` will
+    disable referral processing altogether.
+
+**des_crc_session_supported**
+    (Boolean value).  If set to true, the KDC will assume that service
+    principals support des-cbc-crc for session key enctype negotiation
+    purposes.  If **allow_weak_crypto** in :ref:`libdefaults` is
+    false, or if des-cbc-crc is not a permitted enctype, then this
+    variable has no effect.  Defaults to true.
+
+**reject_bad_transit**
+    (Boolean value.)  If set to true, the KDC will check the list of
+    transited realms for cross-realm tickets against the transit path
+    computed from the realm names and the capaths section of its
+    :ref:`krb5.conf(5)` file; if the path in the ticket to be issued
+    contains any realms not in the computed path, the ticket will not
+    be issued, and an error will be returned to the client instead.
+    If this value is set to false, such tickets will be issued
+    anyways, and it will be left up to the application server to
+    validate the realm transit path.
+
+    If the disable-transited-check flag is set in the incoming
+    request, this check is not performed at all.  Having the
+    **reject_bad_transit** option will cause such ticket requests to
+    be rejected always.
+
+    This transit path checking and config file option currently apply
+    only to TGS requests.
+
+    The default value is true.
+
+**restrict_anonymous_to_tgt**
+    (Boolean value.)  If set to true, the KDC will reject ticket
+    requests from anonymous principals to service principals other
+    than the realm's ticket-granting service.  This option allows
+    anonymous PKINIT to be enabled for use as FAST armor tickets
+    without allowing anonymous authentication to services.  The
+    default value is false.
+
+**supported_enctypes**
+    (List of *key*:*salt* strings.)  Specifies the default key/salt
+    combinations of principals for this realm.  Any principals created
+    through :ref:`kadmin(1)` will have keys of these types.  The
+    default value for this tag is |defkeysalts|.  For lists of
+    possible values, see :ref:`Encryption_and_salt_types`.
+
+
+.. _dbdefaults:
+
+[dbdefaults]
+~~~~~~~~~~~~
+
+The [dbdefaults] section specifies default values for some database
+parameters, to be used if the [dbmodules] subsection does not contain
+a relation for the tag.  See the :ref:`dbmodules` section for the
+definitions of these relations.
+
+* **ldap_kerberos_container_dn**
+* **ldap_kdc_dn**
+* **ldap_kadmind_dn**
+* **ldap_service_password_file**
+* **ldap_servers**
+* **ldap_conns_per_server**
+
+
+.. _dbmodules:
+
+[dbmodules]
+~~~~~~~~~~~
+
+The [dbmodules] section contains parameters used by the KDC database
+library and database modules.
+
+The following tag may be specified in the [dbmodules] section:
+
+**db_module_dir**
+    This tag controls where the plugin system looks for modules.  The
+    value should be an absolute path.
+
+Other tags in the [dbmodules] section name a configuration subsection
+for parameters which can be referred to by a realm's
+**database_module** parameter.  The following tags may be specified in
+the subsection:
+
+**database_name**
+    This DB2-specific tag indicates the location of the database in
+    the filesystem.  The default is |kdcdir|\ ``/principal``.
+
+**db_library**
+    This tag indicates the name of the loadable database module.  The
+    value should be ``db2`` for the DB2 module and ``kldap`` for the
+    LDAP module.
+
+**disable_last_success**
+    If set to ``true``, suppresses KDC updates to the "Last successful
+    authentication" field of principal entries requiring
+    preauthentication.  Setting this flag may improve performance.
+    (Principal entries which do not require preauthentication never
+    update the "Last successful authentication" field.).  First
+    introduced in version 1.9.
+
+**disable_lockout**
+    If set to ``true``, suppresses KDC updates to the "Last failed
+    authentication" and "Failed password attempts" fields of principal
+    entries requiring preauthentication.  Setting this flag may
+    improve performance, but also disables account lockout.  First
+    introduced in version 1.9.
+
+**ldap_conns_per_server**
+    This LDAP-specific tag indicates the number of connections to be
+    maintained per LDAP server.
+
+**ldap_kadmind_dn**
+    This LDAP-specific tag indicates the default bind DN for the
+    :ref:`kadmind(8)` daemon.  kadmind does a login to the directory
+    as this object.  This object should have the rights to read and
+    write the Kerberos data in the LDAP database.
+
+**ldap_kdc_dn**
+    This LDAP-specific tag indicates the default bind DN for the
+    :ref:`krb5kdc(8)` daemon.  The KDC does a login to the directory
+    as this object.  This object should have the rights to read the
+    Kerberos data in the LDAP database, and to write data unless
+    **disable_lockout** and **disable_last_success** are true.
+
+**ldap_kerberos_container_dn**
+    This LDAP-specific tag indicates the DN of the container object
+    where the realm objects will be located.
+
+**ldap_servers**
+    This LDAP-specific tag indicates the list of LDAP servers that the
+    Kerberos servers can connect to.  The list of LDAP servers is
+    whitespace-separated.  The LDAP server is specified by a LDAP URI.
+    It is recommended to use ``ldapi:`` or ``ldaps:`` URLs to connect
+    to the LDAP server.
+
+**ldap_service_password_file**
+    This LDAP-specific tag indicates the file containing the stashed
+    passwords (created by ``kdb5_ldap_util stashsrvpw``) for the
+    **ldap_kadmind_dn** and **ldap_kdc_dn** objects.  This file must
+    be kept secure.
+
+
+.. _logging:
+
+[logging]
+~~~~~~~~~
+
+The [logging] section indicates how :ref:`krb5kdc(8)` and
+:ref:`kadmind(8)` perform logging.  The keys in this section are
+daemon names, which may be one of:
+
+**admin_server**
+    Specifies how :ref:`kadmind(8)` performs logging.
+
+**kdc**
+    Specifies how :ref:`krb5kdc(8)` performs logging.
+
+**default**
+    Specifies how either daemon performs logging in the absence of
+    relations specific to the daemon.
+
+Values are of the following forms:
+
+**FILE=**\ *filename* or **FILE:**\ *filename*
+    This value causes the daemon's logging messages to go to the
+    *filename*.  If the ``=`` form is used, the file is overwritten.
+    If the ``:`` form is used, the file is appended to.
+
+**STDERR**
+    This value causes the daemon's logging messages to go to its
+    standard error stream.
+
+**CONSOLE**
+    This value causes the daemon's logging messages to go to the
+    console, if the system supports it.
+
+**DEVICE=**\ *<devicename>*
+    This causes the daemon's logging messages to go to the specified
+    device.
+
+**SYSLOG**\ [\ **:**\ *severity*\ [\ **:**\ *facility*\ ]]
+    This causes the daemon's logging messages to go to the system log.
+
+    The severity argument specifies the default severity of system log
+    messages.  This may be any of the following severities supported
+    by the syslog(3) call, minus the ``LOG_`` prefix: **EMERG**,
+    **ALERT**, **CRIT**, **ERR**, **WARNING**, **NOTICE**, **INFO**,
+    and **DEBUG**.
+
+    The facility argument specifies the facility under which the
+    messages are logged.  This may be any of the following facilities
+    supported by the syslog(3) call minus the LOG\_ prefix: **KERN**,
+    **USER**, **MAIL**, **DAEMON**, **AUTH**, **LPR**, **NEWS**,
+    **UUCP**, **CRON**, and **LOCAL0** through **LOCAL7**.
+
+    If no severity is specified, the default is **ERR**.  If no
+    facility is specified, the default is **AUTH**.
+
+In the following example, the logging messages from the KDC will go to
+the console and to the system log under the facility LOG_DAEMON with
+default severity of LOG_INFO; and the logging messages from the
+administrative server will be appended to the file
+``/var/adm/kadmin.log`` and sent to the device ``/dev/tty04``.
+
+ ::
+
+    [logging]
+        kdc = CONSOLE
+        kdc = SYSLOG:INFO:DAEMON
+        admin_server = FILE:/var/adm/kadmin.log
+        admin_server = DEVICE=/dev/tty04
+
+
+PKINIT options
+--------------
+
+.. note:: The following are pkinit-specific options.  These values may
+          be specified in [kdcdefaults] as global defaults, or within
+          a realm-specific subsection of [realms].  Also note that a
+          realm-specific value over-rides, does not add to, a generic
+          [kdcdefaults] specification.  The search order is:
+
+1. realm-specific subsection of [realms],
+
+    ::
+
+       [realms]
+           EXAMPLE.COM = {
+               pkinit_anchors = FILE:/usr/local/example.com.crt
+           }
+
+2. generic value in the [kdcdefaults] section.
+
+    ::
+
+       [kdcdefaults]
+           pkinit_anchors = DIR:/usr/local/generic_trusted_cas/
+
+For information about the syntax of some of these options, see
+:ref:`Specifying PKINIT identity information <pkinit_identity>` in
+:ref:`krb5.conf(5)`.
+
+**pkinit_anchors**
+    Specifies the location of trusted anchor (root) certificates which
+    the KDC trusts to sign client certificates.  This option is
+    required if pkinit is to be supported by the KDC.  This option may
+    be specified multiple times.
+
+**pkinit_dh_min_bits**
+    Specifies the minimum number of bits the KDC is willing to accept
+    for a client's Diffie-Hellman key.  The default is 2048.
+
+**pkinit_allow_upn**
+    Specifies that the KDC is willing to accept client certificates
+    with the Microsoft UserPrincipalName (UPN) Subject Alternative
+    Name (SAN).  This means the KDC accepts the binding of the UPN in
+    the certificate to the Kerberos principal name.  The default value
+    is false.
+
+    Without this option, the KDC will only accept certificates with
+    the id-pkinit-san as defined in :rfc:`4556`.  There is currently
+    no option to disable SAN checking in the KDC.
+
+**pkinit_eku_checking**
+    This option specifies what Extended Key Usage (EKU) values the KDC
+    is willing to accept in client certificates.  The values
+    recognized in the kdc.conf file are:
+
+    **kpClientAuth**
+        This is the default value and specifies that client
+        certificates must have the id-pkinit-KPClientAuth EKU as
+        defined in :rfc:`4556`.
+
+    **scLogin**
+        If scLogin is specified, client certificates with the
+        Microsoft Smart Card Login EKU (id-ms-kp-sc-logon) will be
+        accepted.
+
+    **none**
+        If none is specified, then client certificates will not be
+        checked to verify they have an acceptable EKU.  The use of
+        this option is not recommended.
+
+**pkinit_identity**
+    Specifies the location of the KDC's X.509 identity information.
+    This option is required if pkinit is to be supported by the KDC.
+
+**pkinit_kdc_ocsp**
+    Specifies the location of the KDC's OCSP.
+
+**pkinit_mapping_file**
+    Specifies the name of the ACL pkinit mapping file.  This file maps
+    principals to the certificates that they can use.
+
+**pkinit_pool**
+    Specifies the location of intermediate certificates which may be
+    used by the KDC to complete the trust chain between a client's
+    certificate and a trusted anchor.  This option may be specified
+    multiple times.
+
+**pkinit_revoke**
+    Specifies the location of Certificate Revocation List (CRL)
+    information to be used by the KDC when verifying the validity of
+    client certificates.  This option may be specified multiple times.
+
+**pkinit_require_crl_checking**
+    The default certificate verification process will always check the
+    available revocation information to see if a certificate has been
+    revoked.  If a match is found for the certificate in a CRL,
+    verification fails.  If the certificate being verified is not
+    listed in a CRL, or there is no CRL present for its issuing CA,
+    and **pkinit_require_crl_checking** is false, then verification
+    succeeds.
+
+    However, if **pkinit_require_crl_checking** is true and there is
+    no CRL information available for the issuing CA, then verification
+    fails.
+
+    **pkinit_require_crl_checking** should be set to true if the
+    policy is such that up-to-date CRLs must be present for every CA.
+
+
+.. _Encryption_and_salt_types:
+
+Encryption and salt types
+-------------------------
+
+Any tag in the configuration files which requires a list of encryption
+types can be set to some combination of the following strings.
+Encryption types marked as "weak" are available for compatibility but
+not recommended for use.
+
+==================================================== =========================================================
+des-cbc-crc                                          DES cbc mode with CRC-32 (weak)
+des-cbc-md4                                          DES cbc mode with RSA-MD4 (weak)
+des-cbc-md5                                          DES cbc mode with RSA-MD5 (weak)
+des-cbc-raw                                          DES cbc mode raw (weak)
+des3-cbc-raw                                         Triple DES cbc mode raw (weak)
+des3-cbc-sha1 des3-hmac-sha1 des3-cbc-sha1-kd        Triple DES cbc mode with HMAC/sha1
+des-hmac-sha1                                        DES with HMAC/sha1 (weak)
+aes256-cts-hmac-sha1-96 aes256-cts AES-256           CTS mode with 96-bit SHA-1 HMAC
+aes128-cts-hmac-sha1-96 aes128-cts AES-128           CTS mode with 96-bit SHA-1 HMAC
+arcfour-hmac rc4-hmac arcfour-hmac-md5               RC4 with HMAC/MD5
+arcfour-hmac-exp rc4-hmac-exp arcfour-hmac-md5-exp   Exportable RC4 with HMAC/MD5 (weak)
+camellia256-cts-cmac camellia256-cts                 Camellia-256 CTS mode with CMAC
+camellia128-cts-cmac camellia128-cts                 Camellia-128 CTS mode with CMAC
+des                                                  The DES family: des-cbc-crc, des-cbc-md5, and des-cbc-md4 (weak)
+des3                                                 The triple DES family: des3-cbc-sha1
+aes                                                  The AES family: aes256-cts-hmac-sha1-96 and aes128-cts-hmac-sha1-96
+rc4                                                  The RC4 family: arcfour-hmac
+camellia                                             The Camellia family: camellia256-cts-cmac and camellia128-cts-cmac
+==================================================== =========================================================
+
+The string **DEFAULT** can be used to refer to the default set of
+types for the variable in question.  Types or families can be removed
+from the current list by prefixing them with a minus sign ("-").
+Types or families can be prefixed with a plus sign ("+") for symmetry;
+it has the same meaning as just listing the type or family.  For
+example, "``DEFAULT -des``" would be the default set of encryption
+types with DES types removed, and "``des3 DEFAULT``" would be the
+default set of encryption types with triple DES types moved to the
+front.
+
+While **aes128-cts** and **aes256-cts** are supported for all Kerberos
+operations, they are not supported by very old versions of our GSSAPI
+implementation (krb5-1.3.1 and earlier).  Services running versions of
+krb5 without AES support must not be given AES keys in the KDC
+database.
+
+Kerberos keys for users are usually derived from passwords.  To ensure
+that people who happen to pick the same password do not have the same
+key, Kerberos 5 incorporates more information into the key using
+something called a salt.  The supported salt types are as follows:
+
+================= ============================================
+normal            default for Kerberos Version 5
+v4                the only type used by Kerberos Version 4 (no salt)
+norealm           same as the default, without using realm information
+onlyrealm         uses only realm information as the salt
+afs3              AFS version 3, only used for compatibility with Kerberos 4 in AFS
+special           generate a random salt
+================= ============================================
+
+
+Sample kdc.conf File
+--------------------
+
+Here's an example of a kdc.conf file:
+
+ ::
+
+    [kdcdefaults]
+        kdc_ports = 88
+
+    [realms]
+        ATHENA.MIT.EDU = {
+            kadmind_port = 749
+            max_life = 12h 0m 0s
+            max_renewable_life = 7d 0h 0m 0s
+            master_key_type = des3-hmac-sha1
+            supported_enctypes = des3-hmac-sha1:normal des-cbc-crc:normal des-cbc-crc:v4
+            database_module = openldap_ldapconf
+        }
+
+    [logging]
+        kdc = FILE:/usr/local/var/krb5kdc/kdc.log
+        admin_server = FILE:/usr/local/var/krb5kdc/kadmin.log
+
+    [dbdefaults]
+        ldap_kerberos_container_dn = cn=krbcontainer,dc=mit,dc=edu
+
+    [dbmodules]
+        openldap_ldapconf = {
+            db_library = kldap
+            disable_last_success = true
+            ldap_kdc_dn = "cn=krbadmin,dc=mit,dc=edu"
+                # this object needs to have read rights on
+                # the realm container and principal subtrees
+            ldap_kadmind_dn = "cn=krbadmin,dc=mit,dc=edu"
+                # this object needs to have read and write rights on
+                # the realm container and principal subtrees
+            ldap_service_password_file = /etc/kerberos/service.keyfile
+            ldap_servers = ldaps://kerberos.mit.edu
+            ldap_conns_per_server = 5
+        }
+
+
+FILES
+------
+
+|kdcdir|\ ``/kdc.conf``
+
+
+SEE ALSO
+---------
+
+:ref:`krb5.conf(5)`, :ref:`krb5kdc(8)`, :ref:`kadm5.acl(5)`
diff --git a/doc/admin/conf_files/krb5_conf.rst b/doc/admin/conf_files/krb5_conf.rst
new file mode 100644
index 0000000000..451532eeb2
--- /dev/null
+++ b/doc/admin/conf_files/krb5_conf.rst
@@ -0,0 +1,1056 @@
+.. _krb5.conf(5):
+
+krb5.conf
+=========
+
+The krb5.conf file contains Kerberos configuration information,
+including the locations of KDCs and admin servers for the Kerberos
+realms of interest, defaults for the current realm and for Kerberos
+applications, and mappings of hostnames onto Kerberos realms.
+Normally, you should install your krb5.conf file in the directory
+``/etc``.  You can override the default location by setting the
+environment variable **KRB5_CONFIG**.
+
+
+Structure
+---------
+
+The krb5.conf file is set up in the style of a Windows INI file.
+Sections are headed by the section name, in square brackets.  Each
+section may contain zero or more relations, of the form:
+
+ ::
+
+    foo = bar
+
+or
+ ::
+
+    fubar = {
+        foo = bar
+        baz = quux
+    }
+
+Placing a '\*' at the end of a line indicates that this is the *final*
+value for the tag.  This means that neither the remainder of this
+configuration file nor any other configuration file will be checked
+for any other values for this tag.
+
+For example, if you have the following lines:
+ ::
+
+    foo = bar*
+    foo = baz
+
+then the second value of ``foo`` (``baz``) would never be read.
+
+The krb5.conf file can include other files using either of the
+following directives at the beginning of a line:
+
+ ::
+
+    include FILENAME
+    includedir DIRNAME
+
+*FILENAME* or *DIRNAME* should be an absolute path. The named file or
+directory must exist and be readable.  Including a directory includes
+all files within the directory whose names consist solely of
+alphanumeric characters, dashes, or underscores.  Included profile
+files are syntactically independent of their parents, so each included
+file must begin with a section header.
+
+The krb5.conf file can specify that configuration should be obtained
+from a loadable module, rather than the file itself, using the
+following directive at the beginning of a line before any section
+headers:
+
+ ::
+
+    module MODULEPATH:RESIDUAL
+
+*MODULEPATH* may be relative to the library path of the krb5
+installation, or it may be an absolute path.  *RESIDUAL* is provided
+to the module at initialization time.  If krb5.conf uses a module
+directive, :ref:`kdc.conf(5)` should also use one if it exists.
+
+
+Sections
+--------
+
+The krb5.conf file may contain the following sections:
+
+===================  =======================================================
+:ref:`libdefaults`   Settings used by the Kerberos V5 library
+:ref:`realms`        Realm-specific contact information and settings
+:ref:`domain_realm`  Maps server hostnames to Kerberos realms
+:ref:`capaths`       Authentication paths for non-hierarchical cross-realm
+:ref:`appdefaults`   Settings used by some Kerberos V5 applications
+:ref:`plugins`       Controls plugin module registration
+===================  =======================================================
+
+Additionally, krb5.conf may include any of the relations described in
+:ref:`kdc.conf(5)`, but it is not a recommended practice.
+
+.. _libdefaults:
+
+[libdefaults]
+~~~~~~~~~~~~~
+
+The libdefaults section may contain any of the following relations:
+
+**allow_weak_crypto**
+    If this flag is set to false, then weak encryption types will be
+    filtered out of the previous three lists (as noted in
+    :ref:`Encryption_and_salt_types` in :ref:`kdc.conf(5)`).  The
+    default value for this tag is false, which may cause
+    authentication failures in existing Kerberos infrastructures that
+    do not support strong crypto.  Users in affected environments
+    should set this tag to true until their infrastructure adopts
+    stronger ciphers.
+
+**ap_req_checksum_type**
+    An integer which specifies the type of AP-REQ checksum to use in
+    authenticators.  This variable should be unset so the appropriate
+    checksum for the encryption key in use will be used.  This can be
+    set if backward compatibility requires a specific checksum type.
+    See the **kdc_req_checksum_type** configuration option for the
+    possible values and their meanings.
+
+**canonicalize**
+    If this flag is set to true, initial ticket requests to the KDC
+    will request canonicalization of the client principal name, and
+    answers with different client principals than the requested
+    principal will be accepted.  The default value is false.
+
+**ccache_type**
+    This parameter determines the format of credential cache types
+    created by :ref:`kinit(1)` or other programs.  The default value
+    is 4, which represents the most current format.  Smaller values
+    can be used for compatibility with very old implementations of
+    Kerberos which interact with credential caches on the same host.
+
+**clockskew**
+    Sets the maximum allowable amount of clockskew in seconds that the
+    library will tolerate before assuming that a Kerberos message is
+    invalid.  The default value is 300 seconds, or five minutes.
+
+**default_ccache_name**
+    This relation specifies the name of the default credential cache.
+    The default is |ccache|.  This relation is subject to parameter
+    expansion (see below).
+
+**default_client_keytab_name**
+    This relation specifies the name of the default keytab for
+    obtaining client credentials.  The default is |ckeytab|.  This
+    relation is subject to parameter expansion (see below).
+
+**default_keytab_name**
+    This relation specifies the default keytab name to be used by
+    application servers such as sshd.  The default is |keytab|.  This
+    relation is subject to parameter expansion (see below).
+
+**default_realm**
+    Identifies the default Kerberos realm for the client.  Set its
+    value to your Kerberos realm.  If this value is not set, then a
+    realm must be specified with every Kerberos principal when
+    invoking programs such as :ref:`kinit(1)`.
+
+**default_tgs_enctypes**
+    Identifies the supported list of session key encryption types that
+    should be returned by the KDC, in order of preference from
+    highest to lowest.  The list may be delimited with commas or
+    whitespace.  See :ref:`Encryption_and_salt_types` in
+    :ref:`kdc.conf(5)` for a list of the accepted values for this tag.
+    The default value is |defetypes|, but single-DES encryption types
+    will be implicitly removed from this list if the value of
+    **allow_weak_crypto** is false.
+
+**default_tkt_enctypes**
+    Identifies the supported list of session key encryption types that
+    should be requested by the client, in order of preference from
+    highest to lowest.  The format is the same as for
+    default_tgs_enctypes.  The default value for this tag is
+    |defetypes|, but single-DES encryption types will be implicitly
+    removed from this list if the value of **allow_weak_crypto** is
+    false.
+
+**dns_lookup_kdc**
+    Indicate whether DNS SRV records should be used to locate the KDCs
+    and other servers for a realm, if they are not listed in the
+    krb5.conf information for the realm.  (Note that the admin_server
+    entry must be in the krb5.conf realm information in order to
+    contact kadmind, because the DNS implementation for kadmin is
+    incomplete.)
+
+    Enabling this option does open up a type of denial-of-service
+    attack, if someone spoofs the DNS records and redirects you to
+    another server.  However, it's no worse than a denial of service,
+    because that fake KDC will be unable to decode anything you send
+    it (besides the initial ticket request, which has no encrypted
+    data), and anything the fake KDC sends will not be trusted without
+    verification using some secret that it won't know.
+
+**extra_addresses**
+    This allows a computer to use multiple local addresses, in order
+    to allow Kerberos to work in a network that uses NATs while still
+    using address-restricted tickets.  The addresses should be in a
+    comma-separated list.  This option has no effect if
+    **noaddresses** is true.
+
+**forwardable**
+    If this flag is true, initial tickets will be forwardable by
+    default, if allowed by the KDC.  The default value is false.
+
+**ignore_acceptor_hostname**
+    When accepting GSSAPI or krb5 security contexts for host-based
+    service principals, ignore any hostname passed by the calling
+    application, and allow clients to authenticate to any service
+    principal in the keytab matching the service name and realm name
+    (if given).  This option can improve the administrative
+    flexibility of server applications on multihomed hosts, but could
+    compromise the security of virtual hosting environments.  The
+    default value is false.
+
+**k5login_authoritative**
+    If this flag is true, principals must be listed in a local user's
+    k5login file to be granted login access, if a :ref:`.k5login(5)`
+    file exists.  If this flag is false, a principal may still be
+    granted login access through other mechanisms even if a k5login
+    file exists but does not list the principal.  The default value is
+    true.
+
+**k5login_directory**
+    If set, the library will look for a local user's k5login file
+    within the named directory, with a filename corresponding to the
+    local username.  If not set, the library will look for k5login
+    files in the user's home directory, with the filename .k5login.
+    For security reasons, .k5login files must be owned by
+    the local user or by root.
+
+**kdc_default_options**
+    Default KDC options (Xored for multiple values) when requesting
+    initial tickets.  By default it is set to 0x00000010
+    (KDC_OPT_RENEWABLE_OK).
+
+**kdc_timesync**
+    Accepted values for this relation are 1 or 0.  If it is nonzero,
+    client machines will compute the difference between their time and
+    the time returned by the KDC in the timestamps in the tickets and
+    use this value to correct for an inaccurate system clock when
+    requesting service tickets or authenticating to services.  This
+    corrective factor is only used by the Kerberos library; it is not
+    used to change the system clock.  The default value is 1.
+
+**kdc_req_checksum_type**
+    An integer which specifies the type of checksum to use for the KDC
+    requests, for compatibility with very old KDC implementations.
+    This value is only used for DES keys; other keys use the preferred
+    checksum type for those keys.
+
+    The possible values and their meanings are as follows.
+
+    ======== ===============================
+    1        CRC32
+    2        RSA MD4
+    3        RSA MD4 DES
+    4        DES CBC
+    7        RSA MD5
+    8        RSA MD5 DES
+    9        NIST SHA
+    12       HMAC SHA1 DES3
+    -138     Microsoft MD5 HMAC checksum type
+    ======== ===============================
+
+**noaddresses**
+    If this flag is true, requests for initial tickets will not be
+    made with address restrictions set, allowing the tickets to be
+    used across NATs.  The default value is true.
+
+**permitted_enctypes**
+    Identifies all encryption types that are permitted for use in
+    session key encryption.  The default value for this tag is
+    |defetypes|, but single-DES encryption types will be implicitly
+    removed from this list if the value of **allow_weak_crypto** is
+    false.
+
+**plugin_base_dir**
+    If set, determines the base directory where krb5 plugins are
+    located.  The default value is the ``krb5/plugins`` subdirectory
+    of the krb5 library directory.
+
+**preferred_preauth_types**
+    This allows you to set the preferred preauthentication types which
+    the client will attempt before others which may be advertised by a
+    KDC.  The default value for this setting is "17, 16, 15, 14",
+    which forces libkrb5 to attempt to use PKINIT if it is supported.
+
+**proxiable**
+    If this flag is true, initial tickets will be proxiable by
+    default, if allowed by the KDC.  The default value is false.
+
+**rdns**
+    If this flag is true, reverse name lookup will be used in addition
+    to forward name lookup to canonicalizing hostnames for use in
+    service principal names.  The default value is true.
+
+**realm_try_domains**
+    Indicate whether a host's domain components should be used to
+    determine the Kerberos realm of the host.  The value of this
+    variable is an integer: -1 means not to search, 0 means to try the
+    host's domain itself, 1 means to also try the domain's immediate
+    parent, and so forth.  The library's usual mechanism for locating
+    Kerberos realms is used to determine whether a domain is a valid
+    realm, which may involve consulting DNS if **dns_lookup_kdc** is
+    set.  The default is not to search domain components.
+
+**renew_lifetime**
+    (:ref:`duration` string.)  Sets the default renewable lifetime
+    for initial ticket requests.  The default value is 0.
+
+**safe_checksum_type**
+    An integer which specifies the type of checksum to use for the
+    KRB-SAFE requests.  By default it is set to 8 (RSA MD5 DES).  For
+    compatibility with applications linked against DCE version 1.1 or
+    earlier Kerberos libraries, use a value of 3 to use the RSA MD4
+    DES instead.  This field is ignored when its value is incompatible
+    with the session key type.  See the **kdc_req_checksum_type**
+    configuration option for the possible values and their meanings.
+
+**ticket_lifetime**
+    (:ref:`duration` string.)  Sets the default lifetime for initial
+    ticket requests.  The default value is 1 day.
+
+**udp_preference_limit**
+    When sending a message to the KDC, the library will try using TCP
+    before UDP if the size of the message is above
+    **udp_preference_limit**.  If the message is smaller than
+    **udp_preference_limit**, then UDP will be tried before TCP.
+    Regardless of the size, both protocols will be tried if the first
+    attempt fails.
+
+**verify_ap_req_nofail**
+    If this flag is true, then an attempt to verify initial
+    credentials will fail if the client machine does not have a
+    keytab.  The default value is false.
+
+
+.. _realms:
+
+[realms]
+~~~~~~~~
+
+Each tag in the [realms] section of the file is the name of a Kerberos
+realm.  The value of the tag is a subsection with relations that
+define the properties of that particular realm.  For each realm, the
+following tags may be specified in the realm's subsection:
+
+**admin_server**
+    Identifies the host where the administration server is running.
+    Typically, this is the master Kerberos server.  This tag must be
+    given a value in order to communicate with the :ref:`kadmind(8)`
+    server for the realm.
+
+**auth_to_local**
+    This tag allows you to set a general rule for mapping principal
+    names to local user names.  It will be used if there is not an
+    explicit mapping for the principal name that is being
+    translated. The possible values are:
+
+    **RULE:**\ *exp*
+        The local name will be formulated from *exp*.
+
+        The format for *exp* is **[**\ *n*\ **:**\ *string*\ **](**\
+        *regexp*\ **)s/**\ *pattern*\ **/**\ *replacement*\ **/g**.
+        The integer *n* indicates how many components the target
+        principal should have.  If this matches, then a string will be
+        formed from *string*, substituting the realm of the principal
+        for ``$0`` and the *n*'th component of the principal for
+        ``$n`` (e.g., if the principal was ``johndoe/admin`` then
+        ``[2:$2$1foo]`` would result in the string
+        ``adminjohndoefoo``).  If this string matches *regexp*, then
+        the ``s//[g]`` substitution command will be run over the
+        string.  The optional **g** will cause the substitution to be
+        global over the *string*, instead of replacing only the first
+        match in the *string*.
+
+    **DEFAULT**
+        The principal name will be used as the local user name.  If
+        the principal has more than one component or is not in the
+        default realm, this rule is not applicable and the conversion
+        will fail.
+
+    For example:
+     ::
+
+        [realms]
+            ATHENA.MIT.EDU = {
+                auth_to_local = RULE:[2:$1](johndoe)s/^.*$/guest/
+                auth_to_local = RULE:[2:$1;$2](^.*;admin$)s/;admin$//
+                auth_to_local = RULE:[2:$2](^.*;root)s/^.*$/root/
+                auto_to_local = DEFAULT
+            }
+
+    would result in any principal without ``root`` or ``admin`` as the
+    second component to be translated with the default rule.  A
+    principal with a second component of ``admin`` will become its
+    first component.  ``root`` will be used as the local name for any
+    principal with a second component of ``root``.  The exception to
+    these two rules are any principals ``johndoe/*``, which will
+    always get the local name ``guest``.
+
+**auth_to_local_names**
+    This subsection allows you to set explicit mappings from principal
+    names to local user names.  The tag is the mapping name, and the
+    value is the corresponding local user name.
+
+**default_domain**
+    This tag specifies the domain used to expand hostnames when
+    translating Kerberos 4 service principals to Kerberos 5 principals
+    (for example, when converting ``rcmd.hostname`` to
+    ``host/hostname.domain``).
+
+**kdc**
+    The name or address of a host running a KDC for that realm.  An
+    optional port number, separated from the hostname by a colon, may
+    be included.  If the name or address contains colons (for example,
+    if it is an IPv6 address), enclose it in square brackets to
+    distinguish the colon from a port separator.  For your computer to
+    be able to communicate with the KDC for each realm, this tag must
+    be given a value in each realm subsection in the configuration
+    file, or there must be DNS SRV records specifying the KDCs.
+
+**kpasswd_server**
+    Points to the server where all the password changes are performed.
+    If there is no such entry, the port 464 on the **admin_server**
+    host will be tried.
+
+**master_kdc**
+    Identifies the master KDC(s).  Currently, this tag is used in only
+    one case: If an attempt to get credentials fails because of an
+    invalid password, the client software will attempt to contact the
+    master KDC, in case the user's password has just been changed, and
+    the updated database has not been propagated to the slave servers
+    yet.
+
+**v4_instance_convert**
+    This subsection allows the administrator to configure exceptions
+    to the **default_domain** mapping rule.  It contains V4 instances
+    (the tag name) which should be translated to some specific
+    hostname (the tag value) as the second component in a Kerberos V5
+    principal name.
+
+**v4_realm**
+    This relation is used by the krb524 library routines when
+    converting a V5 principal name to a V4 principal name.  It is used
+    when the V4 realm name and the V5 realm name are not the same, but
+    still share the same principal names and passwords. The tag value
+    is the Kerberos V4 realm name.
+
+
+.. _domain_realm:
+
+[domain_realm]
+~~~~~~~~~~~~~~
+
+The [domain_realm] section provides a translation from a domain name
+or hostname to a Kerberos realm name.  The tag name can be a host name
+or domain name, where domain names are indicated by a prefix of a
+period (``.``).  The value of the relation is the Kerberos realm name
+for that particular host or domain.  The Kerberos realm may be
+identified either in the realms_ section or using DNS SRV records.
+Host names and domain names should be in lower case.  For example:
+
+ ::
+
+    [domain_realm]
+        crash.mit.edu = TEST.ATHENA.MIT.EDU
+        .mit.edu = ATHENA.MIT.EDU
+        mit.edu = ATHENA.MIT.EDU
+
+maps the host with the exact name ``crash.mit.edu`` into the
+TEST.ATHENA.MIT.EDU realm.  The period prefix in ``.mit.edu`` denotes
+that all systems in the ``mit.edu`` domain belong to
+``ATHENA.MIT.EDU`` realm.  The third entry maps the host ``mit.edu``
+itself to the ``ATHENA.MIT.EDU`` realm.
+
+If no translation entry applies to a hostname used for a service
+principal for a service ticket request, the library will try to get a
+referral to the appropriate realm from the client realm's KDC.  If
+that does not succeed, the host's realm is considered to be the
+hostname's domain portion converted to uppercase, unless the
+**realm_try_domains** setting in [libdefaults] causes a different
+parent domain to be used.
+
+
+.. _capaths:
+
+[capaths]
+~~~~~~~~~
+
+In order to perform direct (non-hierarchical) cross-realm
+authentication, configuration is needed to determine the
+authentication paths between realms.
+
+A client will use this section to find the authentication path between
+its realm and the realm of the server.  The server will use this
+section to verify the authentication path used by the client, by
+checking the transited field of the received ticket.
+
+There is a tag for each participating client realm, and each tag has
+subtags for each of the server realms.  The value of the subtags is an
+intermediate realm which may participate in the cross-realm
+authentication.  The subtags may be repeated if there is more then one
+intermediate realm.  A value of "." means that the two realms share
+keys directly, and no intermediate realms should be allowed to
+participate.
+
+Only those entries which will be needed on the client or the server
+need to be present.  A client needs a tag for its local realm with
+subtags for all the realms of servers it will need to authenticate to.
+A server needs a tag for each realm of the clients it will serve, with
+a subtag of the server realm.
+
+For example, ``ANL.GOV``, ``PNL.GOV``, and ``NERSC.GOV`` all wish to
+use the ``ES.NET`` realm as an intermediate realm.  ANL has a sub
+realm of ``TEST.ANL.GOV`` which will authenticate with ``NERSC.GOV``
+but not ``PNL.GOV``.  The [capaths] section for ``ANL.GOV`` systems
+would look like this:
+
+ ::
+
+    [capaths]
+        ANL.GOV = {
+            TEST.ANL.GOV = .
+            PNL.GOV = ES.NET
+            NERSC.GOV = ES.NET
+            ES.NET = .
+        }
+        TEST.ANL.GOV = {
+            ANL.GOV = .
+        }
+        PNL.GOV = {
+            ANL.GOV = ES.NET
+        }
+        NERSC.GOV = {
+            ANL.GOV = ES.NET
+        }
+        ES.NET = {
+            ANL.GOV = .
+        }
+
+The [capaths] section of the configuration file used on ``NERSC.GOV``
+systems would look like this:
+
+ ::
+
+    [capaths]
+        NERSC.GOV = {
+            ANL.GOV = ES.NET
+            TEST.ANL.GOV = ES.NET
+            TEST.ANL.GOV = ANL.GOV
+            PNL.GOV = ES.NET
+            ES.NET = .
+        }
+        ANL.GOV = {
+            NERSC.GOV = ES.NET
+        }
+        PNL.GOV = {
+            NERSC.GOV = ES.NET
+        }
+        ES.NET = {
+            NERSC.GOV = .
+        }
+        TEST.ANL.GOV = {
+            NERSC.GOV = ANL.GOV
+            NERSC.GOV = ES.NET
+        }
+
+When a subtag is used more than once within a tag, clients will use
+the order of values to determine the path.  The order of values is not
+important to servers.
+
+
+.. _appdefaults:
+
+[appdefaults]
+~~~~~~~~~~~~~
+
+Each tag in the [appdefaults] section names a Kerberos V5 application
+or an option that is used by some Kerberos V5 application[s].  The
+value of the tag defines the default behaviors for that application.
+
+For example:
+ ::
+
+    [appdefaults]
+        telnet = {
+            ATHENA.MIT.EDU = {
+                option1 = false
+            }
+        }
+        telnet = {
+            option1 = true
+            option2 = true
+        }
+        ATHENA.MIT.EDU = {
+            option2 = false
+        }
+        option2 = true
+
+The above four ways of specifying the value of an option are shown in
+order of decreasing precedence. In this example, if telnet is running
+in the realm EXAMPLE.COM, it should, by default, have option1 and
+option2 set to true.  However, a telnet program in the realm
+``ATHENA.MIT.EDU`` should have ``option1`` set to false and
+``option2`` set to true.  Any other programs in ATHENA.MIT.EDU should
+have ``option2`` set to false by default.  Any programs running in
+other realms should have ``option2`` set to true.
+
+The list of specifiable options for each application may be found in
+that application's man pages.  The application defaults specified here
+are overridden by those specified in the realms_ section.
+
+
+.. _plugins:
+
+[plugins]
+~~~~~~~~~
+
+    * pwqual_ interface
+    * kadm5_hook_ interface
+    * clpreauth_ and kdcpreauth_ interfaces
+
+Tags in the [plugins] section can be used to register dynamic plugin
+modules and to turn modules on and off.  Not every krb5 pluggable
+interface uses the [plugins] section; the ones that do are documented
+here.
+
+Each pluggable interface corresponds to a subsection of [plugins].
+All subsections support the same tags:
+
+**disable**
+    This tag may have multiple values. If there are values for this
+    tag, then the named modules will be disabled for the pluggable
+    interface.
+
+**enable_only**
+    This tag may have multiple values. If there are values for this
+    tag, then only the named modules will be enabled for the pluggable
+    interface.
+
+**module**
+    This tag may have multiple values.  Each value is a string of the
+    form ``modulename:pathname``, which causes the shared object
+    located at *pathname* to be registered as a dynamic module named
+    *modulename* for the pluggable interface.  If *pathname* is not an
+    absolute path, it will be treated as relative to the
+    **plugin_base_dir** value from :ref:`libdefaults`.
+
+The following subsections are currently supported within the [plugins]
+section:
+
+.. _ccselect:
+
+ccselect interface
+##################
+
+The ccselect subsection controls modules for credential cache
+selection within a cache collection.  In addition to any registered
+dynamic modules, the following built-in modules exist (and may be
+disabled with the disable tag):
+
+**k5identity**
+    Uses a .k5identity file in the user's home directory to select a
+    client principal
+
+**realm**
+    Uses the service realm to guess an appropriate cache from the
+    collection
+
+.. _pwqual:
+
+pwqual interface
+################
+
+The pwqual subsection controls modules for the password quality
+interface, which is used to reject weak passwords when passwords are
+changed.  The following built-in modules exist for this interface:
+
+**dict**
+    Checks against the realm dictionary file
+
+**empty**
+    Rejects empty passwords
+
+**hesiod**
+    Checks against user information stored in Hesiod (only if Kerberos
+    was built with Hesiod support)
+
+**princ**
+    Checks against components of the principal name
+
+.. _kadm5_hook:
+
+kadm5_hook interface
+####################
+
+The kadm5_hook interface provides plugins with information on
+principal creation, modification, password changes and deletion.  This
+interface can be used to write a plugin to synchronize MIT Kerberos
+with another database such as Active Directory.  No plugins are built
+in for this interface.
+
+.. _clpreauth:
+
+.. _kdcpreauth:
+
+clpreauth and kdcpreauth interfaces
+###################################
+
+The clpreauth and kdcpreauth interfaces allow plugin modules to
+provide client and KDC preauthentication mechanisms.  The following
+built-in modules exist for these interfaces:
+
+**pkinit**
+    This module implements the PKINIT preauthentication mechanism.
+
+**encrypted_challenge**
+    This module implements the encrypted challenge FAST factor.
+
+**encrypted_timestamp**
+    This module implements the encrypted timestamp mechanism.
+
+
+PKINIT options
+--------------
+
+.. note:: The following are PKINIT-specific options.  These values may
+          be specified in [libdefaults] as global defaults, or within
+          a realm-specific subsection of [libdefaults], or may be
+          specified as realm-specific values in the [realms] section.
+          A realm-specific value overrides, not adds to, a generic
+          [libdefaults] specification.  The search order is:
+
+1. realm-specific subsection of [libdefaults]:
+
+    ::
+
+       [libdefaults]
+           EXAMPLE.COM = {
+               pkinit_anchors = FILE:/usr/local/example.com.crt
+           }
+
+2. realm-specific value in the [realms] section,
+
+    ::
+
+       [realms]
+           OTHERREALM.ORG = {
+               pkinit_anchors = FILE:/usr/local/otherrealm.org.crt
+           }
+
+3. generic value in the [libdefaults] section.
+
+    ::
+
+       [libdefaults]
+           pkinit_anchors = DIR:/usr/local/generic_trusted_cas/
+
+
+.. _pkinit_identity:
+
+Specifying PKINIT identity information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The syntax for specifying Public Key identity, trust, and revocation
+information for PKINIT is as follows:
+
+**FILE:**\ *filename*\ [**,**\ *keyfilename*]
+    This option has context-specific behavior.
+
+    In **pkinit_identity** or **pkinit_identities**, *filename*
+    specifies the name of a PEM-format file containing the user's
+    certificate.  If *keyfilename* is not specified, the user's
+    private key is expected to be in *filename* as well.  Otherwise,
+    *keyfilename* is the name of the file containing the private key.
+
+    In **pkinit_anchors** or **pkinit_pool**, *filename* is assumed to
+    be the name of an OpenSSL-style ca-bundle file.
+
+**DIR:**\ *dirname*
+    This option has context-specific behavior.
+
+    In **pkinit_identity** or **pkinit_identities**, *dirname*
+    specifies a directory with files named ``*.crt`` and ``*.key``
+    where the first part of the file name is the same for matching
+    pairs of certificate and private key files.  When a file with a
+    name ending with ``.crt`` is found, a matching file ending with
+    ``.key`` is assumed to contain the private key.  If no such file
+    is found, then the certificate in the ``.crt`` is not used.
+
+    In **pkinit_anchors** or **pkinit_pool**, *dirname* is assumed to
+    be an OpenSSL-style hashed CA directory where each CA cert is
+    stored in a file named ``hash-of-ca-cert.#``.  This infrastructure
+    is encouraged, but all files in the directory will be examined and
+    if they contain certificates (in PEM format), they will be used.
+
+    In **pkinit_revoke**, *dirname* is assumed to be an OpenSSL-style
+    hashed CA directory where each revocation list is stored in a file
+    named ``hash-of-ca-cert.r#``.  This infrastructure is encouraged,
+    but all files in the directory will be examined and if they
+    contain a revocation list (in PEM format), they will be used.
+
+**PKCS12:**\ *filename*
+    *filename* is the name of a PKCS #12 format file, containing the
+    user's certificate and private key.
+
+**PKCS11:**\ [**module_name=**]\ *modname*\ [**:slotid=**\ *slot-id*][**:token=**\ *token-label*][**:certid=**\ *cert-id*][**:certlabel=**\ *cert-label*]
+    All keyword/values are optional.  *modname* specifies the location
+    of a library implementing PKCS #11.  If a value is encountered
+    with no keyword, it is assumed to be the *modname*.  If no
+    module-name is specified, the default is ``opensc-pkcs11.so``.
+    ``slotid=`` and/or ``token=`` may be specified to force the use of
+    a particular smard card reader or token if there is more than one
+    available.  ``certid=`` and/or ``certlabel=`` may be specified to
+    force the selection of a particular certificate on the device.
+    See the **pkinit_cert_match** configuration option for more ways
+    to select a particular certificate to use for PKINIT.
+
+**ENV:**\ *envvar*
+    *envvar* specifies the name of an environment variable which has
+    been set to a value conforming to one of the previous values.  For
+    example, ``ENV:X509_PROXY``, where environment variable
+    ``X509_PROXY`` has been set to ``FILE:/tmp/my_proxy.pem``.
+
+
+PKINIT krb5.conf options
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+**pkinit_anchors**
+    Specifies the location of trusted anchor (root) certificates which
+    the client trusts to sign KDC certificates.  This option may be
+    specified multiple times.  These values from the config file are
+    not used if the user specifies X509_anchors on the command line.
+
+**pkinit_cert_match**
+    Specifies matching rules that the client certificate must match
+    before it is used to attempt PKINIT authentication.  If a user has
+    multiple certificates available (on a smart card, or via other
+    media), there must be exactly one certificate chosen before
+    attempting PKINIT authentication.  This option may be specified
+    multiple times.  All the available certificates are checked
+    against each rule in order until there is a match of exactly one
+    certificate.
+
+    The Subject and Issuer comparison strings are the :rfc:`2253`
+    string representations from the certificate Subject DN and Issuer
+    DN values.
+
+    The syntax of the matching rules is:
+
+        [*relation-operator*\ ]\ *component-rule* ...
+
+    where:
+
+    *relation-operator*
+        can be either ``&&``, meaning all component rules must match,
+        or ``||``, meaning only one component rule must match.  The
+        default is ``&&``.
+
+    *component-rule*
+        can be one of the following.  Note that there is no
+        punctuation or whitespace between component rules.
+
+            | **<SUBJECT>**\ *regular-expression*
+            | **<ISSUER>**\ *regular-expression*
+            | **<SAN>**\ *regular-expression*
+            | **<EKU>**\ *extended-key-usage-list*
+	    | **<KU>**\ *key-usage-list*
+
+        *extended-key-usage-list* is a comma-separated list of
+        required Extended Key Usage values.  All values in the list
+        must be present in the certificate.  Extended Key Usage values
+        can be:
+
+        * pkinit
+        * msScLogin
+        * clientAuth
+        * emailProtection
+
+        *key-usage-list* is a comma-separated list of required Key
+        Usage values.  All values in the list must be present in the
+        certificate.  Key Usage values can be:
+
+        * digitalSignature
+        * keyEncipherment
+
+    Examples:
+
+     ::
+
+        pkinit_cert_match = ||<SUBJECT>.*DoE.*<SAN>.*@EXAMPLE.COM
+        pkinit_cert_match = &&<EKU>msScLogin,clientAuth<ISSUER>.*DoE.*
+        pkinit_cert_match = <EKU>msScLogin,clientAuth<KU>digitalSignature
+
+**pkinit_eku_checking**
+    This option specifies what Extended Key Usage value the KDC
+    certificate presented to the client must contain.  (Note that if
+    the KDC certificate has the pkinit SubjectAlternativeName encoded
+    as the Kerberos TGS name, EKU checking is not necessary since the
+    issuing CA has certified this as a KDC certificate.)  The values
+    recognized in the krb5.conf file are:
+
+    **kpKDC**
+        This is the default value and specifies that the KDC must have
+        the id-pkinit-KPKdc EKU as defined in :rfc:`4556`.
+
+    **kpServerAuth**
+        If **kpServerAuth** is specified, a KDC certificate with the
+        id-kp-serverAuth EKU as used by Microsoft will be accepted.
+
+    **none**
+        If **none** is specified, then the KDC certificate will not be
+        checked to verify it has an acceptable EKU.  The use of this
+        option is not recommended.
+
+**pkinit_dh_min_bits**
+    Specifies the size of the Diffie-Hellman key the client will
+    attempt to use.  The acceptable values are 1024, 2048, and 4096.
+    The default is 2048.
+
+**pkinit_identities**
+    Specifies the location(s) to be used to find the user's X.509
+    identity information.  This option may be specified multiple
+    times.  Each value is attempted in order until identity
+    information is found and authentication is attempted.  Note that
+    these values are not used if the user specifies
+    **X509_user_identity** on the command line.
+
+**pkinit_kdc_hostname**
+    The presense of this option indicates that the client is willing
+    to accept a KDC certificate with a dNSName SAN (Subject
+    Alternative Name) rather than requiring the id-pkinit-san as
+    defined in :rfc:`4556`.  This option may be specified multiple
+    times.  Its value should contain the acceptable hostname for the
+    KDC (as contained in its certificate).
+
+**pkinit_longhorn**
+    If this flag is set to true, we are talking to the Longhorn KDC.
+
+**pkinit_pool**
+    Specifies the location of intermediate certificates which may be
+    used by the client to complete the trust chain between a KDC
+    certificate and a trusted anchor.  This option may be specified
+    multiple times.
+
+**pkinit_require_crl_checking**
+    The default certificate verification process will always check the
+    available revocation information to see if a certificate has been
+    revoked.  If a match is found for the certificate in a CRL,
+    verification fails.  If the certificate being verified is not
+    listed in a CRL, or there is no CRL present for its issuing CA,
+    and **pkinit_require_crl_checking** is false, then verification
+    succeeds.
+
+    However, if **pkinit_require_crl_checking** is true and there is
+    no CRL information available for the issuing CA, then verification
+    fails.
+
+    **pkinit_require_crl_checking** should be set to true if the
+    policy is such that up-to-date CRLs must be present for every CA.
+
+**pkinit_revoke**
+    Specifies the location of Certificate Revocation List (CRL)
+    information to be used by the client when verifying the validity
+    of the KDC certificate presented.  This option may be specified
+    multiple times.
+
+**pkinit_win2k**
+    This flag specifies whether the target realm is assumed to support
+    only the old, pre-RFC version of the protocol.  The default is
+    false.
+
+**pkinit_win2k_require_binding**
+    If this flag is set to true, it expects that the target KDC is
+    patched to return a reply with a checksum rather than a nonce.
+    The default is false.
+
+
+.. _parameter_expansion:
+
+Parameter expansion
+-------------------
+
+Several variables, such as **default_keytab_name**, allow parameters
+to be expanded.  Valid parameters are:
+
+    =================  ===================================================
+    %{TEMP}            Temporary directory
+    %{uid}             Unix real UID or Windows SID
+    %{euid}            Unix effective user ID or Windows SID
+    %{USERID}          Same as %{uid}
+    %{null}            Empty string
+    %{LIBDIR}          Installation library directory
+    %{BINDIR}          Installation binary directory
+    %{SBINDIR}         Installation admin binary directory
+    %{username}        (Unix) Username of effective user ID
+    %{APPDATA}         (Windows) Roaming application data for current user
+    %{COMMON_APPDATA}  (Windows) Application data for all users
+    %{LOCAL_APPDATA}   (Windows) Local application data for current user
+    %{SYSTEM}          (Windows) Windows system folder
+    %{WINDOWS}         (Windows) Windows folder
+    %{USERCONFIG}      (Windows) Per-user MIT krb5 config file directory
+    %{COMMONCONFIG}    (Windows) Common MIT krb5 config file directory
+    =================  ===================================================
+
+Sample krb5.conf file
+---------------------
+
+Here is an example of a generic krb5.conf file:
+
+ ::
+
+    [libdefaults]
+        default_realm = ATHENA.MIT.EDU
+        default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc
+        default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc
+        dns_lookup_kdc = true
+        dns_lookup_realm = false
+
+    [realms]
+        ATHENA.MIT.EDU = {
+            kdc = kerberos.mit.edu
+            kdc = kerberos-1.mit.edu
+            kdc = kerberos-2.mit.edu:750
+            admin_server = kerberos.mit.edu
+            master_kdc = kerberos.mit.edu
+            default_domain = mit.edu
+        }
+        EXAMPLE.COM = {
+            kdc = kerberos.example.com
+            kdc = kerberos-1.example.com
+            admin_server = kerberos.example.com
+        }
+
+    [domain_realm]
+        .mit.edu = ATHENA.MIT.EDU
+        mit.edu = ATHENA.MIT.EDU
+
+    [capaths]
+        ATHENA.MIT.EDU = {
+               EXAMPLE.COM = .
+        }
+        EXAMPLE.COM = {
+               ATHENA.MIT.EDU = .
+        }
+
+FILES
+-----
+
+|krb5conf|
+
+
+SEE ALSO
+--------
+
+syslog(3)