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 [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 kadmind 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 krb5kdc and kadmind 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 kdb5_util dump command (perhaps invoked by kprop or by kadmind for incremental propagation) may cause krb5kdc 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 KDC performance and account 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 KDC performance and account 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 kadmin 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 Configuring Kerberos with OpenLDAP back-end for details.

Because krb5kdc 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 krb5kdc -w option to enable concurrent processing of KDC requests.

The kldap module does not support explicit locking with the kadmin lock command.