Database types
==============

A Kerberos database can be implemented with one of three built-in
database providers, called KDB modules.  Software which incorporates
the MIT krb5 KDC may also provide its own KDB module.  The following
subsections describe the three built-in KDB modules and the
configuration specific to them.

The database type can be configured with the **db_library** variable
in the :ref:`dbmodules` subsection for the realm.  For example::

    [dbmodules]
        ATHENA.MIT.EDU = {
            db_library = db2
        }

If the ``ATHENA.MIT.EDU`` realm subsection contains a
**database_module** setting, then the subsection within
``[dbmodules]`` should use that name instead of ``ATHENA.MIT.EDU``.

To transition from one database type to another, stop the
:ref:`kadmind(8)` service, use ``kdb5_util dump`` to create a dump
file, change the **db_library** value and set any appropriate
configuration for the new database type, and use ``kdb5_util load`` to
create and populate the new database.  If the new database type is
LDAP, create the new database using ``kdb5_ldap_util`` and populate it
from the dump file using ``kdb5_util load -update``.  Then restart the
:ref:`krb5kdc(8)` and :ref:`kadmind(8)` services.


Berkeley database module (db2)
------------------------------

The default KDB module is ``db2``, which uses a version of the
Berkeley DB library.  It creates four files based on the database
pathname.  If the pathname ends with ``principal`` then the four files
are:

* ``principal``, containing principal entry data
* ``principal.ok``, a lock file for the principal database
* ``principal.kadm5``, containing policy object data
* ``principal.kadm5.lock``, a lock file for the policy database

For large databases, the :ref:`kdb5_util(8)` **dump** command (perhaps
invoked by :ref:`kprop(8)` or by :ref:`kadmind(8)` for incremental
propagation) may cause :ref:`krb5kdc(8)` to stop for a noticeable
period of time while it iterates over the database.  This delay can be
avoided by disabling account lockout features so that the KDC does not
perform database writes (see :ref:`disable_lockout`).  Alternatively,
a slower form of iteration can be enabled by setting the
**unlockiter** variable to ``true``.  For example::

    [dbmodules]
        ATHENA.MIT.EDU = {
            db_library = db2
            unlockiter = true
        }

In rare cases, a power failure or other unclean system shutdown may
cause inconsistencies in the internal pointers within a database file,
such that ``kdb5_util dump`` cannot retrieve all principal entries in
the database.  In this situation, it may be possible to retrieve all
of the principal data by running ``kdb5_util dump -recurse`` to
iterate over the database using the tree pointers instead of the
iteration pointers.  Running ``kdb5_util dump -rev`` to iterate over
the database backwards may also retrieve some of the data which is not
retrieved by a normal dump operation.


Lightning Memory-Mapped Database module (klmdb)
-----------------------------------------------

The klmdb module was added in release 1.17.  It uses the LMDB library,
and may offer better performance and reliability than the db2 module.
It creates four files based on the database pathname.  If the pathname
ends with ``principal``, then the four files are:

* ``principal.mdb``, containing policy object data and most principal
  entry data
* ``principal.mdb-lock``, a lock file for the primary database
* ``principal.lockout.mdb``, containing the account lockout attributes
  (last successful authentication time, last failed authentication
  time, and number of failed attempts) for each principal entry
* ``principal.lockout.mdb-lock``, a lock file for the lockout database

Separating out the lockout attributes ensures that the KDC will never
block on an administrative operation such as a database dump or load.
It also allows the KDC to operate without write access to the primary
database.  If both account lockout features are disabled (see
:ref:`disable_lockout`), the lockout database files will be created
but will not subsequently be opened, and the account lockout
attributes will always have zero values.

Because LMDB creates a memory map to the database files, it requires a
configured memory map size which also determines the maximum size of
the database.  This size is applied equally to the two databases, so
twice the configured size will be consumed in the process address
space; this is primarily a limitation on 32-bit platforms.  The
default value of 128 megabytes should be sufficient for several
hundred thousand principal entries.  If the limit is reached, kadmin
operations will fail and the error message "Environment mapsize limit
reached" will appear in the kadmind log file.  In this case, the
**mapsize** variable can be used to increase the map size.  The
following example sets the map size to 512 megabytes::

    [dbmodules]
        ATHENA.MIT.EDU = {
            db_library = klmdb
            mapsize = 512
        }

LMDB has a configurable maximum number of readers.  The default value
of 128 should be sufficient for most deployments.  If you are going to
use a large number of KDC worker processes, it may be necessary to set
the **max_readers** variable to a larger number.

By default, LMDB synchronizes database files to disk after each write
transaction to ensure durability in the case of an unclean system
shutdown.  The klmdb module always turns synchronization off for the
lockout database to ensure reasonable KDC performance, but leaves it
on for the primary database.  If high throughput for administrative
operations (including password changes) is required, the **nosync**
variable can be set to "true" to disable synchronization for the
primary database.

The klmdb module does not support explicit locking with the
:ref:`kadmin(1)` **lock** command.


LDAP module (kldap)
-------------------

The kldap module stores principal and policy data using an LDAP
server.  To use it you must configure an LDAP server to use the
Kerberos schema.  See :ref:`conf_ldap` for details.

Because :ref:`krb5kdc(8)` is single-threaded, latency in LDAP database
accesses may limit KDC operation throughput.  If the LDAP server is
located on the same server host as the KDC and accessed through an
``ldapi://`` URL, latency should be minimal.  If this is not possible,
consider starting multiple KDC worker processes with the
:ref:`krb5kdc(8)` **-w** option to enable concurrent processing of KDC
requests.

The kldap module does not support explicit locking with the
:ref:`kadmin(1)` **lock** command.