doc/admin/dbtypes.rst

   1 Database types
   2 ==============
   3
   4 A Kerberos database can be implemented with one of three built-in
   5 database providers, called KDB modules.  Software which incorporates
   6 the MIT krb5 KDC may also provide its own KDB module.  The following
   7 subsections describe the three built-in KDB modules and the
   8 configuration specific to them.
   9
  10 The database type can be configured with the **db_library** variable
  11 in the :ref:`dbmodules` subsection for the realm.  For example::
  12
  13     [dbmodules]
  14         ATHENA.MIT.EDU = {
  15             db_library = db2
  16         }
  17
  18 If the ``ATHENA.MIT.EDU`` realm subsection contains a
  19 **database_module** setting, then the subsection within
  20 ``[dbmodules]`` should use that name instead of ``ATHENA.MIT.EDU``.
  21
  22 To transition from one database type to another, stop the
  23 :ref:`kadmind(8)` service, use ``kdb5_util dump`` to create a dump
  24 file, change the **db_library** value and set any appropriate
  25 configuration for the new database type, and use ``kdb5_util load`` to
  26 create and populate the new database.  If the new database type is
  27 LDAP, create the new database using ``kdb5_ldap_util`` and populate it
  28 from the dump file using ``kdb5_util load -update``.  Then restart the
  29 :ref:`krb5kdc(8)` and :ref:`kadmind(8)` services.
  30
  31
  32 Berkeley database module (db2)
  33 ------------------------------
  34
  35 The default KDB module is ``db2``, which uses a version of the
  36 Berkeley DB library.  It creates four files based on the database
  37 pathname.  If the pathname ends with ``principal`` then the four files
  38 are:
  39
  40 * ``principal``, containing principal entry data
  41 * ``principal.ok``, a lock file for the principal database
  42 * ``principal.kadm5``, containing policy object data
  43 * ``principal.kadm5.lock``, a lock file for the policy database
  44
  45 For large databases, the :ref:`kdb5_util(8)` **dump** command (perhaps
  46 invoked by :ref:`kprop(8)` or by :ref:`kadmind(8)` for incremental
  47 propagation) may cause :ref:`krb5kdc(8)` to stop for a noticeable
  48 period of time while it iterates over the database.  This delay can be
  49 avoided by disabling account lockout features so that the KDC does not
  50 perform database writes (see :ref:`disable_lockout`).  Alternatively,
  51 a slower form of iteration can be enabled by setting the
  52 **unlockiter** variable to ``true``.  For example::
  53
  54     [dbmodules]
  55         ATHENA.MIT.EDU = {
  56             db_library = db2
  57             unlockiter = true
  58         }
  59
  60 In rare cases, a power failure or other unclean system shutdown may
  61 cause inconsistencies in the internal pointers within a database file,
  62 such that ``kdb5_util dump`` cannot retrieve all principal entries in
  63 the database.  In this situation, it may be possible to retrieve all
  64 of the principal data by running ``kdb5_util dump -recurse`` to
  65 iterate over the database using the tree pointers instead of the
  66 iteration pointers.  Running ``kdb5_util dump -rev`` to iterate over
  67 the database backwards may also retrieve some of the data which is not
  68 retrieved by a normal dump operation.
  69
  70
  71 Lightning Memory-Mapped Database module (klmdb)
  72 -----------------------------------------------
  73
  74 The klmdb module was added in release 1.17.  It uses the LMDB library,
  75 and may offer better performance and reliability than the db2 module.
  76 It creates four files based on the database pathname.  If the pathname
  77 ends with ``principal``, then the four files are:
  78
  79 * ``principal.mdb``, containing policy object data and most principal
  80   entry data
  81 * ``principal.mdb-lock``, a lock file for the primary database
  82 * ``principal.lockout.mdb``, containing the account lockout attributes
  83   (last successful authentication time, last failed authentication
  84   time, and number of failed attempts) for each principal entry
  85 * ``principal.lockout.mdb-lock``, a lock file for the lockout database
  86
  87 Separating out the lockout attributes ensures that the KDC will never
  88 block on an administrative operation such as a database dump or load.
  89 It also allows the KDC to operate without write access to the primary
  90 database.  If both account lockout features are disabled (see
  91 :ref:`disable_lockout`), the lockout database files will be created
  92 but will not subsequently be opened, and the account lockout
  93 attributes will always have zero values.
  94
  95 Because LMDB creates a memory map to the database files, it requires a
  96 configured memory map size which also determines the maximum size of
  97 the database.  This size is applied equally to the two databases, so
  98 twice the configured size will be consumed in the process address
  99 space; this is primarily a limitation on 32-bit platforms.  The
 100 default value of 128 megabytes should be sufficient for several
 101 hundred thousand principal entries.  If the limit is reached, kadmin
 102 operations will fail and the error message "Environment mapsize limit
 103 reached" will appear in the kadmind log file.  In this case, the
 104 **mapsize** variable can be used to increase the map size.  The
 105 following example sets the map size to 512 megabytes::
 106
 107     [dbmodules]
 108         ATHENA.MIT.EDU = {
 109             db_library = klmdb
 110             mapsize = 512
 111         }
 112
 113 LMDB has a configurable maximum number of readers.  The default value
 114 of 128 should be sufficient for most deployments.  If you are going to
 115 use a large number of KDC worker processes, it may be necessary to set
 116 the **max_readers** variable to a larger number.
 117
 118 By default, LMDB synchronizes database files to disk after each write
 119 transaction to ensure durability in the case of an unclean system
 120 shutdown.  The klmdb module always turns synchronization off for the
 121 lockout database to ensure reasonable KDC performance, but leaves it
 122 on for the primary database.  If high throughput for administrative
 123 operations (including password changes) is required, the **nosync**
 124 variable can be set to "true" to disable synchronization for the
 125 primary database.
 126
 127 The klmdb module does not support explicit locking with the
 128 :ref:`kadmin(1)` **lock** command.
 129
 130
 131 LDAP module (kldap)
 132 -------------------
 133
 134 The kldap module stores principal and policy data using an LDAP
 135 server.  To use it you must configure an LDAP server to use the
 136 Kerberos schema.  See :ref:`conf_ldap` for details.
 137
 138 Because :ref:`krb5kdc(8)` is single-threaded, latency in LDAP database
 139 accesses may limit KDC operation throughput.  If the LDAP server is
 140 located on the same server host as the KDC and accessed through an
 141 ``ldapi://`` URL, latency should be minimal.  If this is not possible,
 142 consider starting multiple KDC worker processes with the
 143 :ref:`krb5kdc(8)` **-w** option to enable concurrent processing of KDC
 144 requests.
 145
 146 The kldap module does not support explicit locking with the
 147 :ref:`kadmin(1)` **lock** command.