krb5 commit: Add database type documentation
Greg Hudson <[email protected]>
| Newsgroups | gmane.comp.encryption.kerberos.cvs |
|---|---|
| Message-ID | <[email protected]> |
https://github.com/krb5/krb5/commit/1c8223ecf9d4a892eb5ff0114a31b218625f76d5 commit 1c8223ecf9d4a892eb5ff0114a31b218625f76d5 Author: Greg Hudson <[email protected]> Date: Thu Apr 26 12:17:21 2018 -0400 Add database type documentation Document the new profile variables added for the LMDB KDB module and the new configure option. Add a new admin section on database types, and document the behavior of all current modules. ticket: 8674 doc/admin/conf_files/kdc_conf.rst | 22 +++++- doc/admin/conf_ldap.rst | 2 + doc/admin/dbtypes.rst | 147 +++++++++++++++++++++++++++++++++++++ doc/admin/index.rst | 1 + doc/admin/lockout.rst | 2 + doc/build/options2configure.rst | 3 + doc/mitK5features.rst | 2 +- 7 files changed, 176 insertions(+), 3 deletions(-) diff --git a/doc/admin/conf_files/kdc_conf.rst b/doc/admin/conf_files/kdc_conf.rst index 997df08..ea185ae 100644 --- a/doc/admin/conf_files/kdc_conf.rst +++ b/doc/admin/conf_files/kdc_conf.rst @@ -475,8 +475,8 @@ The following tags may be specified in a [dbmodules] subsection: **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. + value should be ``db2`` for the DB2 module, ``klmdb`` for the LMDB + module, or ``kldap`` for the LDAP module. **disable_last_success** If set to ``true``, suppresses KDC updates to the "Last successful @@ -551,6 +551,24 @@ The following tags may be specified in a [dbmodules] subsection: **ldap_kdc_sasl_authcid** or **ldap_kadmind_sasl_authcid** names for SASL authentication. This file must be kept secure. +**mapsize** + This LMDB-specific tag indicates the maximum size of the two + database environments in megabytes. The default value is 128. + Increase this value to address "Environment mapsize limit reached" + errors. New in release 1.17. + +**max_readers** + This LMDB-specific tag indicates the maximum number of concurrent + reading processes for the databases. The default value is 128. + New in release 1.17. + +**nosync** + This LMDB-specific tag can be set to improve the throughput of + kadmind and other administrative agents, at the expense of + durability (recent database changes may not survive a power outage + or other sudden reboot). It does not affect the throughput of the + KDC. The default value is false. New in release 1.17. + **unlockiter** If set to ``true``, this DB2-specific tag causes iteration operations to release the database lock while processing each diff --git a/doc/admin/conf_ldap.rst b/doc/admin/conf_ldap.rst index 6443f46..9b3e102 100644 --- a/doc/admin/conf_ldap.rst +++ b/doc/admin/conf_ldap.rst @@ -1,3 +1,5 @@ +.. _conf_ldap: + Configuring Kerberos with OpenLDAP back-end =========================================== diff --git a/doc/admin/dbtypes.rst b/doc/admin/dbtypes.rst new file mode 100644 index 0000000..02f79ac --- /dev/null +++ b/doc/admin/dbtypes.rst @@ -0,0 +1,147 @@ +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. diff --git a/doc/admin/index.rst b/doc/admin/index.rst index 292a641..fbe5e42 100644 --- a/doc/admin/index.rst +++ b/doc/admin/index.rst @@ -8,6 +8,7 @@ For administrators conf_files/index.rst realm_config.rst database.rst + dbtypes.rst lockout.rst conf_ldap.rst appl_servers.rst diff --git a/doc/admin/lockout.rst b/doc/admin/lockout.rst index d262663..c7e4e33 100644 --- a/doc/admin/lockout.rst +++ b/doc/admin/lockout.rst @@ -115,6 +115,8 @@ LDAP replication, then account lockout state may be replicated between KDCs and the concerns of this section may not apply. +.. _disable_lockout: + KDC performance and account lockout ----------------------------------- diff --git a/doc/build/options2configure.rst b/doc/build/options2configure.rst index ac1a8b9..ddbee20 100644 --- a/doc/build/options2configure.rst +++ b/doc/build/options2configure.rst @@ -329,6 +329,9 @@ Optional packages **-**\ **-with-ldap** Compile OpenLDAP database backend module. +**-**\ **-with-lmdb** + Compile LMDB database backend module. + **-**\ **-with-tcl=**\ *path* Specifies that *path* is the location of a Tcl installation. Tcl is needed for some of the tests run by 'make check'; such tests diff --git a/doc/mitK5features.rst b/doc/mitK5features.rst index 9df7e34..3b22d98 100644 --- a/doc/mitK5features.rst +++ b/doc/mitK5features.rst @@ -33,7 +33,7 @@ Crypto backends: - builtin - MIT Kerberos native crypto library - OpenSSL (1.0\+) - http://www.openssl.org -Database backends: LDAP, DB2 +Database backends: LDAP, DB2, LMDB krb4 support: Kerberos 5 release < 1.8