1 files changed, 241 insertions, 0 deletions
diff --git a/doc/man/man5/slapd-mdb.5 b/doc/man/man5/slapd-mdb.5
new file mode 100644
index 0000000..a6bb77c
--- /dev/null
+++ b/doc/man/man5/slapd-mdb.5
@@ -0,0 +1,241 @@
+.TH SLAPD-MDB 5 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" Copyright 2011-2022 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
+.\" $OpenLDAP$
+.SH NAME
+slapd\-mdb \- Memory-Mapped DB backend to slapd
+.SH SYNOPSIS
+.B ETCDIR/slapd.conf
+.SH DESCRIPTION
+The \fBmdb\fP backend to
+.BR slapd (8)
+uses OpenLDAP's Lightning Memory-Mapped DB (LMDB) library to store data.
+It relies completely on the underlying operating system for memory
+management and does no caching of its own. It is the recommended
+primary database backend.
+.LP
+The \fBmdb\fP backend uses a hierarchical database layout which
+supports subtree renames.
+.SH CONFIGURATION
+These
+.B slapd.conf
+options apply to the \fBmdb\fP backend.
+That is, they must follow a "backend mdb" line and
+come before any subsequent "backend" or "database" lines.
+.TP
+.BI idlexp \ <exp>
+Specify a power of 2 for the maximum size of an index slot.
+The default is 16, yielding a maximum slot size of 2^16 or 65536.
+Once set, this option applies to every \fBmdb\fP database instance.
+The specified value must be in the range of 16-30.
+.LP
+
+These
+.B slapd.conf
+options apply to the \fBmdb\fP backend database.
+That is, they must follow a "database mdb" line and
+come before any subsequent "backend" or "database" lines.
+Other database options are described in the
+.BR slapd.conf (5)
+manual page.
+.TP
+.BI checkpoint \ <kbyte>\ <min>
+Specify the frequency for flushing the database disk buffers.
+This setting is only needed if the \fBdbnosync\fP option is used.
+The checkpoint will occur if either \fI<kbyte>\fP data has been written or
+\fI<min>\fP minutes have passed since the last checkpoint.
+Both arguments default to zero, in which case they are ignored. When
+the \fI<min>\fP argument is non-zero, an internal task will run every 
+\fI<min>\fP minutes to perform the checkpoint.
+Note: currently the \fI<kbyte>\fP setting is unimplemented.
+.TP
+.B dbnosync
+Specify that on-disk database contents should not be immediately
+synchronized with in memory changes.
+Enabling this option may improve performance at the expense of data
+security. In particular, if the operating system crashes before changes are
+flushed, some number of transactions may be lost.
+By default, a full data flush/sync is performed when each
+transaction is committed.
+.TP
+.BI directory \ <directory>
+Specify the directory where the LMDB files containing this database and
+associated indexes live.
+A separate directory must be specified for each database.
+The default is
+.BR LOCALSTATEDIR/openldap\-data .
+.TP
+\fBenvflags \fR{\fBnosync\fR,\fBnometasync\fR,\fBwritemap\fR,\fBmapasync\fR,\fBnordahead\fR}
+Specify flags for finer-grained control of the LMDB library's operation.
+.RS
+.TP
+.B nosync
+This is exactly the same as the
+.I dbnosync
+directive.
+.RE
+.RS
+.TP
+.B nometasync
+Flush the data on a commit, but skip the sync of the meta page. This mode is
+slightly faster than doing a full sync, but can potentially lose the last
+committed transaction if the operating system crashes. If both
+.I nometasync
+and
+.I nosync
+are set, the
+.I nosync
+flag takes precedence.
+.RE
+.RS
+.TP
+.B writemap
+Use a writable memory map instead of just read-only. This speeds up write operations
+but makes the database vulnerable to corruption in case any bugs in slapd
+cause stray writes into the mmap region.
+.RE
+.RS
+.TP
+.B mapasync
+When using a writable memory map and performing flushes on each commit, use an
+asynchronous flush instead of a synchronous flush (the default). This option
+has no effect if
+.I writemap
+has not been set. It also has no effect if
+.I nosync
+is set.
+.RE
+.RS
+.TP
+.B nordahead
+Turn off file readahead. Usually the OS performs readahead on every read
+request. This usually boosts read performance but can be harmful to
+random access read performance if the system's memory is full and the DB
+is larger than RAM. This option is not implemented on Windows.
+.RE
+
+.TP
+\fBindex \fR{\fI<attrlist>\fR|\fBdefault\fR} [\fBpres\fR,\fBeq\fR,\fBapprox\fR,\fBsub\fR,\fI<special>\fR]
+Specify the indexes to maintain for the given attribute (or
+list of attributes).
+Some attributes only support a subset of indexes.
+If only an \fI<attr>\fP is given, the indices specified for \fBdefault\fR
+are maintained.
+Note that setting a default does not imply that all attributes will be
+indexed. Also, for best performance, an
+.B eq
+index should always be configured for the
+.B objectClass
+attribute.
+
+A number of special index parameters may be specified.
+The index type
+.B sub
+can be decomposed into
+.BR subinitial ,
+.BR subany ,\ and
+.B subfinal
+indices.
+The special type
+.B nolang
+may be specified to disallow use of this index by language subtypes.
+The special type
+.B nosubtypes
+may be specified to disallow use of this index by named subtypes.
+Note: changing \fBindex\fP settings in 
+.BR slapd.conf (5)
+requires rebuilding indices, see
+.BR slapindex (8);
+changing \fBindex\fP settings
+dynamically by LDAPModifying "cn=config" automatically causes rebuilding
+of the indices online in a background task.
+.TP
+.BI maxentrysize \ <bytes>
+Specify the maximum size of an entry in bytes. Attempts to store
+an entry larger than this size will be rejected with the error
+LDAP_ADMINLIMIT_EXCEEDED. The default is 0, which is unlimited.
+.TP
+.BI maxreaders \ <integer>
+Specify the maximum number of threads that may have concurrent read access
+to the database. Tools such as slapcat count as a single thread,
+in addition to threads in any active slapd processes. The
+default is 126.
+.TP
+.BI maxsize \ <bytes>
+Specify the maximum size of the database in bytes. A memory map of this
+size is allocated at startup time and the database will not be allowed
+to grow beyond this size. The default is 10485760 bytes. This setting
+may be changed upward if the configured limit needs to be increased.
+
+Note: It is important to set this to as large a value as possible,
+(relative to anticipated growth of the actual data over time) since
+growing the size later may not be practical when the system is under
+heavy load.
+.TP
+.BI mode \ <integer>
+Specify the file protection mode that newly created database 
+files should have.
+The default is 0600.
+.TP
+\fBmultival \fR{\fI<attrlist>\fR|\fBdefault\fR} \fI<integer hi>\fR,\fI<integer lo>
+Specify the number of values for which a multivalued attribute is
+stored in a separate table. Normally entries are stored as a single
+blob inside the database. When an entry gets very large or contains
+attributes with a very large number of values, modifications on that
+entry may get very slow. Splitting the large attributes out to a separate
+table can improve the performance of modification operations.
+The threshold is specified as a pair of integers. If the number of
+values exceeds the hi threshold the values will be split out. If
+a modification deletes enough values to bring an attribute below
+the lo threshold the values will be removed from the separate
+table and merged back into the main entry blob.
+The threshold can be set for a specific list of attributes, or
+the default can be configured for all other attributes.
+The default value for both hi and lo thresholds is UINT_MAX, which keeps
+all attributes in the main blob.
+.TP
+.BI rtxnsize \ <entries>
+Specify the maximum number of entries to process in a single read
+transaction when executing a large search. Long-lived read transactions
+prevent old database pages from being reused in write transactions, and
+so can cause significant growth of the database file when there is
+heavy write traffic. This setting causes the read transaction in
+large searches to be released and reacquired after the given number
+of entries has been read, to give writers the opportunity to
+reclaim old database pages. The default is 10000.
+.TP
+.BI searchstack \ <depth>
+Specify the depth of the stack used for search filter evaluation.
+Search filters are evaluated on a stack to accommodate nested AND / OR
+clauses. An individual stack is assigned to each server thread.
+The depth of the stack determines how complex a filter can be
+evaluated without requiring any additional memory allocation. Filters that
+are nested deeper than the search stack depth will cause a separate
+stack to be allocated for that particular search operation. These
+allocations can have a major negative impact on server performance,
+but specifying too much stack will also consume a great deal of memory.
+Each search stack uses 512K bytes per level. The default stack depth
+is 16, thus 8MB per thread is used.
+.SH ACCESS CONTROL
+The 
+.B mdb
+backend honors access control semantics as indicated in
+.BR slapd.access (5).
+.SH FILES
+.TP
+.B ETCDIR/slapd.conf
+default 
+.B slapd 
+configuration file
+.SH SEE ALSO
+.BR slapd.conf (5),
+.BR slapd\-config (5),
+.BR slapd (8),
+.BR slapadd (8),
+.BR slapcat (8),
+.BR slapindex (8),
+.BR slapmodify (8),
+OpenLDAP LMDB documentation.
+.SH ACKNOWLEDGEMENTS
+.so ../Project
+Written by Howard Chu.