krb5 commit: Add database type documentation
Greg Hudson
ghudson at mit.edu
Tue May 29 15:00:08 EDT 2018
https://github.com/krb5/krb5/commit/1c8223ecf9d4a892eb5ff0114a31b218625f76d5
commit 1c8223ecf9d4a892eb5ff0114a31b218625f76d5
Author: Greg Hudson <ghudson at mit.edu>
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
More information about the cvs-krb5
mailing list