1SLAPD-BDB(5)                  File Formats Manual                 SLAPD-BDB(5)
2
3
4

NAME

6       slapd-bdb, slapd-hdb - Berkeley DB backends to slapd
7

SYNOPSIS

9       /etc/openldap/slapd.conf
10

DESCRIPTION

12       The  bdb  backend to slapd(8) uses the Oracle Berkeley DB (BDB) package
13       to store data.  It makes extensive use of indexing and caching to speed
14       data access.
15
16       Note  that  BDB  is  deprecated  and  support will be dropped in future
17       OpenLDAP releases. Installations should use the mdb backend instead.
18
19       hdb is a variant of the bdb backend that uses a  hierarchical  database
20       layout  which supports subtree renames. It is both more space-efficient
21       and more execution-efficient than the bdb  backend.   It  is  otherwise
22       identical  to  the bdb behavior, and all the same configuration options
23       apply.
24
25       It is noted that these options are intended to complement  Berkeley  DB
26       configuration  options  set  in  the environment's DB_CONFIG file.  See
27       Berkeley  DB  documentation  for  details  on  DB_CONFIG  configuration
28       options.   Where  there  is  overlap, settings in DB_CONFIG take prece‐
29       dence.
30

CONFIGURATION

32       These slapd.conf options apply to the bdb  and  hdb  backend  database.
33       That  is,  they must follow a "database bdb" or "database hdb" line and
34       come before any subsequent "backend" or "database" lines.  Other  data‐
35       base options are described in the slapd.conf(5) manual page.
36
37       cachesize <integer>
38              Specify  the  size in entries of the in-memory entry cache main‐
39              tained by the bdb or hdb backend database instance.  The default
40              is 1000 entries.
41
42       cachefree <integer>
43              Specify  the number of entries to free from the entry cache when
44              the cache reaches the cachesize limit.  The default is 1 entry.
45
46       checkpoint <kbyte> <min>
47              Specify the frequency for checkpointing the database transaction
48              log.   A  checkpoint  operation  flushes the database buffers to
49              disk and writes a checkpoint record in the log.  The  checkpoint
50              will occur if either <kbyte> data has been written or <min> min‐
51              utes have passed since  the  last  checkpoint.   Both  arguments
52              default  to zero, in which case they are ignored. When the <min>
53              argument is non-zero, an internal task will run every <min> min‐
54              utes  to  perform the checkpoint.  See the Berkeley DB reference
55              guide for more details.
56
57       checksum
58              Enable checksum validation of DB pages whenever  they  are  read
59              from disk.  This setting can only be configured before any data‐
60              base files are created.
61
62       cryptfile <file>
63              Specify the pathname of a file containing an encryption  key  to
64              use  for  encrypting the database. Encryption is performed using
65              Berkeley DB's implementation of AES. Note  that  encryption  can
66              only  be  configured  before any database files are created, and
67              changing the key can only be done after destroying  the  current
68              database  and  recreating  it.  Encryption  is  not  enabled  by
69              default, and some distributions of Berkeley DB  do  not  support
70              encryption.
71
72       cryptkey <key>
73              Specify  an  encryption  key to use for encrypting the database.
74              This option may  be  used  when  a  separate  cryptfile  is  not
75              desired. Only one of cryptkey or cryptfile may be configured.
76
77       dbconfig <Berkeley-DB-setting>
78              Specify  a configuration directive to be placed in the DB_CONFIG
79              file of the database directory. The dbconfig directive is just a
80              convenience  to  allow  all necessary configuration to be set in
81              the slapd.conf file.  The options set using this directive  will
82              only be written to the DB_CONFIG file if no such file existed at
83              server startup time, otherwise they are completely ignored. This
84              allows  one to set initial values without overwriting/destroying
85              a DB_CONFIG file  that  was  already  customized  through  other
86              means.   This  directive  may  be  specified  multiple times, as
87              needed.  For example:
88                   dbconfig set_cachesize 0 1048576 0
89                   dbconfig set_lg_bsize 2097152
90
91       dbnosync
92              Specify that on-disk database contents should not be immediately
93              synchronized  with  in memory changes.  Enabling this option may
94              improve performance at the expense of data  security.   See  the
95              Berkeley DB reference guide for more details.
96
97       dbpagesize  <dbfile> <size>
98              Specify  the page size to use for a particular database file, in
99              units of 1024 bytes. The default for the id2entry  file  is  16,
100              the  default  for  all  other  files  depends on the size of the
101              underlying filesystem's block size (typically 4 or 8).  The max‐
102              imum that BerkeleyDB supports is 64. This setting usually should
103              not need to be changed, but if BerkeleyDB's "db_stat -d" shows a
104              large  amount  of  overflow  pages  in  use in a file, setting a
105              larger size may increase performance  at  the  expense  of  data
106              integrity.  This  setting  only  takes effect when a database is
107              being newly created. See the Berkeley  DB  reference  guide  for
108              more details.
109
110       directory <directory>
111              Specify  the directory where the BDB files containing this data‐
112              base and associated indexes live.  A separate directory must  be
113              specified for each database.  The default is /var/openldap-data.
114
115       dirtyread
116              Allow  reads  of  modified  but not yet committed data.  Usually
117              transactions are  isolated  to  prevent  other  operations  from
118              accessing  uncommitted  data.   This  option may improve perfor‐
119              mance, but may also return  inconsistent  results  if  the  data
120              comes  from  a transaction that is later aborted.  In this case,
121              the modified data is discarded  and  a  subsequent  search  will
122              return a different result.
123
124       dncachesize <integer>
125              Specify  the  maximum  number  of DNs in the in-memory DN cache.
126              Ideally this cache should be large enough to contain the DNs  of
127              every  entry in the database. If set to a smaller value than the
128              cachesize it will be silently increased to equal the  cachesize.
129              The  default value is 0 which means unlimited, i.e. the DN cache
130              will grow without bound.
131
132              It should be noted that the DN cache is allowed  to  temporarily
133              grow  beyond  the  configured size. It does this if many entries
134              are locked when it tries to  do  a  purge,  because  that  means
135              they're  legitimately  in  use.  Also, the DN cache never purges
136              entries that have cached children, so depending on the shape  of
137              the  DIT,  it  could  have  lots  of cached DNs over the defined
138              limit.
139
140       idlcachesize <integer>
141              Specify the size of the in-memory index cache, in  index  slots.
142              The  default  is  zero.  A  larger  value will speed up frequent
143              searches of indexed entries. An hdb database needs a large  idl‐
144              cachesize for good search performance, typically three times the
145              cachesize (entry cache size) or larger.
146
147       index {<attrlist>|default} [pres,eq,approx,sub,<special>]
148              Specify the indexes to maintain for the given attribute (or list
149              of  attributes).   Some  attributes  only  support  a  subset of
150              indexes.  If only an <attr> is given, the indices specified  for
151              default  are  maintained.   Note that setting a default does not
152              imply that all attributes will be indexed. Also, for  best  per‐
153              formance,  an  eq  index  should  always  be  configured for the
154              objectClass attribute.
155
156              A number of special index  parameters  may  be  specified.   The
157              index  type  sub  can be decomposed into subinitial, subany, and
158              subfinal indices.  The special type nolang may be  specified  to
159              disallow  use  of  this index by language subtypes.  The special
160              type nosubtypes may be specified to disallow use of  this  index
161              by   named   subtypes.    Note:   changing   index  settings  in
162              slapd.conf(5) requires  rebuilding  indices,  see  slapindex(8);
163              changing index settings dynamically by LDAPModifying "cn=config"
164              automatically causes rebuilding of the indices online in a back‐
165              ground task.
166
167       linearindex
168              Tell slapindex to index one attribute at a time. By default, all
169              indexed attributes in an entry are processed at the  same  time.
170              With  this option, each indexed attribute is processed individu‐
171              ally, using multiple passes through the  entire  database.  This
172              option  improves  slapindex  performance  when the database size
173              exceeds the dbcache size. When the dbcache is large enough, this
174              option  is  not  needed  and will decrease performance.  Also by
175              default, slapadd  performs  full  indexing  and  so  a  separate
176              slapindex  run  is not needed. With this option, slapadd does no
177              indexing and slapindex must be used.
178
179       lockdetect {oldest|youngest|fewest|random|default}
180              Specify which transaction to abort when a deadlock is  detected.
181              The default is random.
182
183       mode <integer>
184              Specify  the  file  protection  mode that newly created database
185              index files should have.  The default is 0600.
186
187       searchstack <depth>
188              Specify the depth of the stack used for  search  filter  evalua‐
189              tion.   Search  filters  are evaluated on a stack to accommodate
190              nested AND / OR clauses. An individual stack is assigned to each
191              server  thread.  The depth of the stack determines how complex a
192              filter can be evaluated without requiring any additional  memory
193              allocation. Filters that are nested deeper than the search stack
194              depth will cause a separate stack to be allocated for that  par‐
195              ticular  search  operation.  These  allocations can have a major
196              negative impact on server performance, but specifying  too  much
197              stack  will  also  consume  a great deal of memory.  Each search
198              stack uses 512K bytes per level. The default stack depth is  16,
199              thus 8MB per thread is used.
200
201       shm_key <integer>
202              Specify  a  key  for a shared memory BDB environment. By default
203              the BDB environment uses memory  mapped  files.  If  a  non-zero
204              value  is  specified,  it  will be used as the key to identify a
205              shared memory region that will house the environment.
206

ACCESS CONTROL

208       The bdb and hdb backends honor access control semantics as indicated in
209       slapd.access(5).
210

FILES

212       /etc/openldap/slapd.conf
213              default slapd configuration file
214
215       DB_CONFIG
216              Berkeley DB configuration file
217

SEE ALSO

219       slapd.conf(5),  slapd-config(5),  slapd-mdb(5),  slapd(8),  slapadd(8),
220       slapcat(8), slapindex(8), Berkeley DB documentation.
221

ACKNOWLEDGEMENTS

223       OpenLDAP Software is developed and maintained by The  OpenLDAP  Project
224       <http://www.openldap.org/>.  OpenLDAP Software is derived from the Uni‐
225       versity of  Michigan  LDAP  3.3  Release.   Originally  begun  by  Kurt
226       Zeilenga.  Caching  mechanisms  originally  designed by Jong-Hyuk Choi.
227       Completion and subsequent work, as well as back-hdb, by Howard Chu.
228
229
230
231OpenLDAP 2.4.47                   2018/12/19                      SLAPD-BDB(5)
Impressum