.TH SLAPD-BDB 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2003 The OpenLDAP Foundation All Rights Reserved.
+.\" Copyright 1998-2007 The OpenLDAP Foundation All Rights Reserved.
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
.\" $OpenLDAP$
.SH NAME
-slapd-bdb \- BDB backend to slapd
+slapd-bdb, slapd-hdb \- Berkeley DB backends to slapd
.SH SYNOPSIS
-ETCDIR/slapd.conf
+.B ETCDIR/slapd.conf
.SH DESCRIPTION
-The BDB backend to
+The \fBbdb\fP backend to
.BR slapd (8)
-is the recommended backend for a normal slapd database.
-It uses the Sleepycat BerkelyDB package to store data.
+is the recommended primary backend for a normal
+.B slapd
+database.
+It uses the Oracle Berkeley DB (BDB) package to store data.
It makes extensive use of indexing and caching to speed data access.
+.LP
+\fBhdb\fP is a variant of the \fBbdb\fP backend that uses a
+hierarchical database
+layout which supports subtree renames. It is otherwise identical to
+the \fBbdb\fP behavior, and all the same configuration options apply.
+.LP
+It is noted that these options are intended to complement
+Berkeley DB configuration options set in the environment's
+.B DB_CONFIG
+file. See Berkeley DB documentation for details on
+.B DB_CONFIG
+configuration options.
+Where there is overlap, settings in
+.B DB_CONFIG
+take precedence.
.SH CONFIGURATION
These
.B slapd.conf
-options apply to the BDB backend database.
-That is, they must follow a "database bdb" line and come before any
-subsequent "backend" or "database" lines.
+options apply to the \fBbdb\fP and \fBhdb\fP backend database.
+That is, they must follow a "database bdb" or "database hdb" line and
+come before any subsequent "backend" or "database" lines.
Other database options are described in the
.BR slapd.conf (5)
manual page.
.TP
-.B cachesize <integer>
-Specify the size in entries of the in-memory cache maintained
-by the BDB backend database instance.
+.BI cachesize \ <integer>
+Specify the size in entries of the in-memory entry cache maintained
+by the \fBbdb\fP or \fBhdb\fP backend database instance.
The default is 1000 entries.
.TP
-.B checkpoint <kbyte> <min>
+.BI cachefree \ <integer>
+Specify the number of entries to free from the entry cache when the
+cache reaches the \fBcachesize\fP limit.
+The default is 1 entry.
+.TP
+.BI checkpoint \ <kbyte>\ <min>
Specify the frequency for checkpointing the database transaction log.
A checkpoint operation flushes the database buffers to disk and writes
a checkpoint record in the log.
-The checkpoint will occur if either <kbyte> data has been written or
-<min> minutes have passed since the last checkpoint.
-Both arguments default to zero, in which case they are ignored.
+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.
See the Berkeley DB reference guide for more details.
.TP
+.BI dbconfig \ <Berkeley\-DB\-setting>
+Specify a configuration directive to be placed in the
+.B DB_CONFIG
+file of the database directory. The
+.B dbconfig
+directive is just a convenience
+to allow all necessary configuration to be set in the
+.B slapd.conf
+file.
+The options set using this directive will only be written to the
+.B DB_CONFIG
+file if no such file existed at server startup time, otherwise
+they are completely ignored. This allows one
+to set initial values without overwriting/destroying a
+.B DB_CONFIG
+file that was already customized through other means.
+This directive may be specified multiple times, as needed.
+For example:
+.RS
+.nf
+ dbconfig set_cachesize 0 1048576 0
+ dbconfig set_lg_bsize 2097152
+.fi
+.RE
+.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.
+See the Berkeley DB reference guide for more details.
.TP
-.B directory <directory>
+.BI directory \ <directory>
Specify the directory where the BDB files containing this database and
associated indexes live.
A separate directory must be specified for each database.
In this case, the modified data is discarded and a subsequent search
will return a different result.
.TP
-.B
-index {<attrlist>|default} [pres,eq,approx,sub,<special>]
+.BI dncachesize \ <integer>
+Specify the maximum number of DNs in the in-memory DN cache. The
+default is twice the \fBcachesize\fP. Ideally this cache should be
+large enough to contain the DNs of every entry in the database.
+.TP
+.BI idlcachesize \ <integer>
+Specify the size of the in-memory index cache, in index slots. The
+default is zero. A larger value will speed up frequent searches of
+indexed entries. An \fBhdb\fP database needs a large \fBidlcachesize\fP
+for good search performance, typically three times the
+.B cachesize
+(entry cache size)
+or larger.
+.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 <attr> is given, the indices specified for \fBdefault\fR
+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.
+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
The special type
.B nosubtypes
may be specified to disallow use of this index by named subtypes.
-Note: changing index settings requires rebuilding indices, see
-.BR slapindex (8).
+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
+.B linearindex
+Tell
+.B slapindex
+to index one attribute at a time. By default, all indexed
+attributes in an entry are processed at the same time. With this option,
+each indexed attribute is processed individually, using multiple passes
+through the entire database. This option improves
+.B slapindex
+performance
+when the database size exceeds the \fBdbcache\fP size. When the \fBdbcache\fP is
+large enough, this option is not needed and will decrease performance.
+Also by default,
+.B slapadd
+performs full indexing and so a separate
+.B slapindex
+run is not needed. With this option,
+.B slapadd
+does no indexing and
+.B slapindex
+must be used.
.TP
-.B lockdetect {oldest|youngest|fewest|random|default}
+.BR lockdetect \ { oldest | youngest | fewest | random | default }
Specify which transaction to abort when a deadlock is detected.
-The default is the same as
+The default is
.BR random .
.TP
-.B mode <integer>
+.BI mode \ <integer>
Specify the file protection mode that newly created database
index files should have.
The default is 0600.
.TP
-.B searchstack <depth>
+.BI searchstack \ <depth>
Specify the depth of the stack used for search filter evaluation.
-Search filters are evaluated on a stack to accomodate nested AND / OR
+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
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.
+.TP
+.BI shm_key \ <integer>
+Specify a key for a shared memory BDB environment. By default the
+BDB environment uses memory mapped files. If a non-zero value is
+specified, it will be used as the key to identify a shared memory
+region that will house the environment.
+.SH ACCESS CONTROL
+The
+.B bdb
+and
+.B hdb
+backends honor access control semantics as indicated in
+.BR slapd.access (5).
.SH FILES
.TP
-ETCDIR/slapd.conf
-default slapd configuration file
+.B ETCDIR/slapd.conf
+default
+.B slapd
+configuration file
+.TP
+.B DB_CONFIG
+Berkeley DB configuration file
.SH SEE ALSO
.BR slapd.conf (5),
.BR slapd (8),
.BR slapadd (8),
.BR slapcat (8),
-.BR slapindex (8).
+.BR slapindex (8),
+Berkeley DB documentation.
+.SH ACKNOWLEDGEMENTS
+.so ../Project
+Originally begun by Kurt Zeilenga. Caching mechanisms originally designed
+by Jong-Hyuk Choi. Completion and subsequent work, as well as
+back-hdb, by Howard Chu.
projects / openldap / blobdiff