mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-27 03:20:22 +08:00
256 lines
8.6 KiB
Groff
256 lines
8.6 KiB
Groff
.TH SLAPD-BDB 5 "RELEASEDATE" "OpenLDAP LDVERSION"
|
|
.\" Copyright 1998-2008 The OpenLDAP Foundation All Rights Reserved.
|
|
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
|
|
.\" $OpenLDAP$
|
|
.SH NAME
|
|
slapd-bdb, slapd-hdb \- Berkeley DB backends to slapd
|
|
.SH SYNOPSIS
|
|
.B ETCDIR/slapd.conf
|
|
.SH DESCRIPTION
|
|
The \fBbdb\fP backend to
|
|
.BR slapd (8)
|
|
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 \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
|
|
.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
|
|
.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 \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 cryptfile \ <file>
|
|
Specify the pathname of a file containing an encryption key to use for
|
|
encrypting the database. Encryption is performed using Berkeley DB's
|
|
implementation of AES. Note that encryption can only be configured before
|
|
any database files are created, and changing the key can only be done
|
|
after destroying the current database and recreating it. Encryption is
|
|
not enabled by default, and some distributions of Berkeley DB do not
|
|
support encryption.
|
|
.TP
|
|
.BI cryptkey \ <key>
|
|
Specify an encryption key to use for encrypting the database. This option
|
|
may be used when a separate
|
|
.I cryptfile
|
|
is not desired. Only one of
|
|
.B cryptkey
|
|
or
|
|
.B cryptfile
|
|
may be configured.
|
|
.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
|
|
.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.
|
|
The default is
|
|
.BR LOCALSTATEDIR/openldap-data .
|
|
.TP
|
|
.B dirtyread
|
|
Allow reads of modified but not yet committed data.
|
|
Usually transactions are isolated to prevent other operations from
|
|
accessing uncommitted data.
|
|
This option may improve performance, but may also return inconsistent
|
|
results if the data comes from a transaction that is later aborted.
|
|
In this case, the modified data is discarded and a subsequent search
|
|
will return a different result.
|
|
.TP
|
|
.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 \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
|
|
.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
|
|
.BR lockdetect \ { oldest | youngest | fewest | random | default }
|
|
Specify which transaction to abort when a deadlock is detected.
|
|
The default is
|
|
.BR random .
|
|
.TP
|
|
.BI mode \ <integer>
|
|
Specify the file protection mode that newly created database
|
|
index files should have.
|
|
The default is 0600.
|
|
.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.
|
|
.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
|
|
.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),
|
|
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.
|