slapdconfig.sdf 31.4 KB
Newer Older
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1
# $OpenLDAP$
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
2
# Copyright 1999-2021 The OpenLDAP Foundation, All Rights Reserved.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
3
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
4

5
H1: The slapd Configuration File
6

7
8
9
10
11
This chapter describes configuring {{slapd}}(8) via the {{slapd.conf}}(5)
configuration file.  {{slapd.conf}}(5) has been deprecated and should
only be used if your site requires one of the backends that hasn't yet
been updated to work with the newer {{slapd-config}}(5) system.  Configuring
{{slapd}}(8) via {{slapd-config}}(5) is described in the previous chapter.
12

13
14
15
The {{slapd.conf}}(5) file is normally installed in the
{{EX:/usr/local/etc/openldap}} directory.  An alternate configuration
file location can be specified via a command-line option to {{slapd}}(8).
16
17
18
19


H2: Configuration File Format

20
21
The {{slapd.conf}}(5) file consists of three types of configuration
information: global, backend specific, and database specific.  Global
Kurt Zeilenga's avatar
Kurt Zeilenga committed
22
23
24
information is specified first, followed by information associated
with a particular backend type, which is then followed by information
associated with a particular database instance.  Global directives can
Howard Chu's avatar
Howard Chu committed
25
be overridden in backend and/or database directives, and backend directives
Kurt Zeilenga's avatar
Kurt Zeilenga committed
26
can be overridden by database directives.
27

Kurt Zeilenga's avatar
Kurt Zeilenga committed
28
Blank lines and comment lines beginning with a '{{EX:#}}' character
29
are ignored.  If a line begins with whitespace, it is considered a
Kurt Zeilenga's avatar
Kurt Zeilenga committed
30
31
32
33
continuation of the previous line (even if the previous line is a
comment).

The general format of slapd.conf is as follows:
34

35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
>	# global configuration directives
>	<global config directives>
>
>	# backend definition
>	backend <typeA>
>	<backend-specific directives>
>
>	# first database definition & config directives
>	database <typeA>
>	<database-specific directives>
>
>	# second database definition & config directives
>	database <typeB>
>	<database-specific directives>
>
>	# second database definition & config directives
>	database <typeA>
>	<database-specific directives>
>
>	# subsequent backend & database definitions & config directives
>	...
56

Kurt Zeilenga's avatar
Kurt Zeilenga committed
57
A configuration directive may take arguments.  If so, they are
58
separated by whitespace.  If an argument contains whitespace,
59
60
61
the argument should be enclosed in double quotes {{EX:"like this"}}. If
an argument contains a double quote or a backslash character `{{EX:\}}',
the character should be preceded by a backslash character `{{EX:\}}'.
62
63

The distribution contains an example configuration file that will
Kurt Zeilenga's avatar
Kurt Zeilenga committed
64
be installed in the {{F: /usr/local/etc/openldap}} directory.
65
A number of files containing schema definitions (attribute types
Kurt Zeilenga's avatar
Kurt Zeilenga committed
66
67
and object classes) are also provided in the
{{F: /usr/local/etc/openldap/schema}} directory.
68
69


Kurt Zeilenga's avatar
Kurt Zeilenga committed
70
H2: Configuration File Directives
71

Kurt Zeilenga's avatar
Kurt Zeilenga committed
72
This section details commonly used configuration directives.  For
Howard Chu's avatar
Howard Chu committed
73
a complete list, see the {{slapd.conf}}(5) manual page.  This section
Kurt Zeilenga's avatar
Kurt Zeilenga committed
74
75
76
separates the configuration file directives into global,
backend-specific and data-specific categories, describing each
directive and its default value (if any), and giving an example of
77
78
79
80
its use.



Kurt Zeilenga's avatar
Kurt Zeilenga committed
81
H3: Global Directives
82

83
Directives described in this section apply to all backends
84
and databases unless specifically overridden in a backend or
Kurt Zeilenga's avatar
Kurt Zeilenga committed
85
database definition.  Arguments that should be replaced
86
by actual text are shown in brackets {{EX:<>}}.
87
88


89
H4: access to <what> [ by <who> [<accesslevel>] [<control>] ]+
90

91
92
This directive grants access (specified by <accesslevel>) to a set
of entries and/or attributes (specified by <what>) by one or more
93
requestors (specified by <who>).  See the {{SECT:Access Control}} section of
94
this guide for basic usage.
95

96
97
98
99
!if 0
More details discussion of this directive can be found in the
{{SECT:Advanced Access Control}} chapter.
!endif
100

101
102
103
104
Note: If no {{EX:access}} directives are specified, the default
access control policy, {{EX:access to * by * read}}, allows all
both authenticated and anonymous users read access.

105

Kurt Zeilenga's avatar
Kurt Zeilenga committed
106
H4: attributetype <{{REF:RFC4512}} Attribute Type Description>
107

Kurt Zeilenga's avatar
Kurt Zeilenga committed
108
This directive defines an attribute type.
109
110
Please see the {{SECT:Schema Specification}} chapter
for information regarding how to use this directive.
111

112
113
114
H4: idletimeout <integer>

Specify the number of seconds to wait before forcibly closing
115
an idle client connection.  An idletimeout of 0, the default,
116
117
118
disables this feature.


119
120
H4: include <filename>

Kurt Zeilenga's avatar
Kurt Zeilenga committed
121
This directive specifies that slapd should read additional
122
123
configuration information from the given file before continuing
with the next line of the current file. The included file should
124
125
follow the normal slapd config file format.  The file is commonly
used to include files containing schema specifications.
126

Kurt Zeilenga's avatar
Kurt Zeilenga committed
127
128
Note: You should be careful when using this directive - there is
no small limit on the number of nested include directives, and no
129
130
loop detection is done.

131
H4: loglevel <level>
132

133
134
This directive specifies the level at which log statements
and operation statistics should be sent to syslog (currently logged to
Howard Chu's avatar
Howard Chu committed
135
the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have
Kurt Zeilenga's avatar
Kurt Zeilenga committed
136
configured OpenLDAP {{EX:--enable-debug}} (the default) for this
137
138
139
140
to work, except for the two statistics levels, which are always
enabled. Log levels may be specified as integers or by keyword.
Multiple log levels may be used and the levels are additive.
The possible values for <integer> are:
141

142
!block table; colaligns="RL"; align=Center; \
143
	title="Table 6.1: Logging Levels"
144
145
Level	Keyword		Description
-1	any		enable all debugging
Gavin Henry's avatar
Gavin Henry committed
146
0			no debugging
147
148
149
150
151
152
153
154
155
156
157
158
159
1	(0x1 trace)	trace function calls
2	(0x2 packets)	debug packet handling
4	(0x4 args)	heavy trace debugging
8	(0x8 conns)	connection management
16	(0x10 BER)	print out packets sent and received
32	(0x20 filter)	search filter processing
64	(0x40 config)	configuration processing
128	(0x80 ACL)	access control list processing
256	(0x100 stats)	stats log connections/operations/results
512	(0x200 stats2)	stats log entries sent
1024	(0x400 shell)	print communication with shell backends
2048	(0x800 parse)	print entry parsing debugging
16384	(0x4000 sync)	syncrepl consumer processing
160
32768	(0x8000 none)	only messages that get logged regardless of configured log level
161
!endblock
162

163
The desired log level can be input as a single integer that
164
combines the (ORed) desired levels, both in decimal or in hexadecimal
165
166
167
168
169
170
171
172
173
174
notation, as a list of integers (that are ORed internally), or as a list of the names that are shown between brackets, such that

>		loglevel 129
>		loglevel 0x81
>		loglevel 128 1
>		loglevel 0x80 0x1
>		loglevel acl trace

are equivalent.

175
\Examples:
176

177
E: loglevel -1
178

179
This will enable all log levels.
180

181
E: loglevel conns filter
182
183
184

Just log the connection and search filter processing.

185
E: loglevel none
186
187
188
189
190

Log those messages that are logged regardless of the configured loglevel. This
differs from setting the log level to 0, when no logging occurs. At least the
{{EX:None}} level is required to have high priority messages logged.

191
192
\Default:

193
E: loglevel stats
194

195
Basic stats logging is configured by default.
196

Kurt Zeilenga's avatar
Kurt Zeilenga committed
197
H4: objectclass <{{REF:RFC4512}} Object Class Description>
198

Kurt Zeilenga's avatar
Kurt Zeilenga committed
199
This directive defines an object class.
200
201
Please see the {{SECT:Schema Specification}} chapter for
information regarding how to use this directive.
202

203

Kurt Zeilenga's avatar
ispell    
Kurt Zeilenga committed
204
H4: referral <URI>
205

Kurt Zeilenga's avatar
Kurt Zeilenga committed
206
This directive specifies the referral to pass back when slapd
207
208
209
210
cannot find a local database to handle a request.

\Example:

211
>	referral ldap://root.openldap.org
212

Kurt Zeilenga's avatar
Kurt Zeilenga committed
213
214
This will refer non-local queries to the global root LDAP server
at the OpenLDAP Project. Smart LDAP clients can re-ask their
215
216
217
218
219
220
221
query at that server, but note that most of these clients are
only going to know how to handle simple LDAP URLs that
contain a host part and optionally a distinguished name part.


H4: sizelimit <integer>

Kurt Zeilenga's avatar
Kurt Zeilenga committed
222
This directive specifies the maximum number of entries to return
223
224
225
226
from a search operation.

\Default:

227
>	sizelimit 500
228

229
See the {{SECT:Limits}} section of this guide and {{slapd.conf}}(5)
230
for more details.
231
232
233

H4: timelimit <integer>

Kurt Zeilenga's avatar
Kurt Zeilenga committed
234
This directive specifies the maximum number of seconds (in real
235
236
237
238
239
240
time) slapd will spend answering a search request. If a
request is not finished in this time, a result indicating an
exceeded timelimit will be returned.

\Default:

241
>	timelimit 3600
242

243
See the {{SECT:Limits}} section of this guide and {{slapd.conf}}(5)
244
245
for more details.

246

Kurt Zeilenga's avatar
Kurt Zeilenga committed
247
H3: General Backend Directives
248

Kurt Zeilenga's avatar
Kurt Zeilenga committed
249
250
251
252
253
254
255
256
Directives in this section apply only to the backend in which
they are defined. They are supported by every type of backend.
Backend directives apply to all databases instances of the
same type and, depending on the directive, may be overridden
by database directives.

H4: backend <type>

Kurt Zeilenga's avatar
Kurt Zeilenga committed
257
This directive marks the beginning of a backend declaration.
Howard Chu's avatar
Howard Chu committed
258
{{EX:<type>}} should be one of the
Kurt Zeilenga's avatar
Kurt Zeilenga committed
259
supported backend types listed in Table 6.2.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
260
261

!block table; align=Center; coltags="EX,N"; \
Howard Chu's avatar
Howard Chu committed
262
	title="Table 6.2: Database Backends"
Kurt Zeilenga's avatar
Kurt Zeilenga committed
263
264
265
Types	Description
dnssrv	DNS SRV backend
ldap	Lightweight Directory Access Protocol (Proxy) backend
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
266
mdb	Memory-Mapped DB backend
Kurt Zeilenga's avatar
Kurt Zeilenga committed
267
268
269
270
271
272
273
274
275
276
meta	Meta Directory backend
monitor	Monitor backend
passwd	Provides read-only access to {{passwd}}(5)
perl	Perl Programmable backend
shell	Shell (extern program) backend
sql	SQL Programmable backend
!endblock

\Example:

277
>	backend mdb
Kurt Zeilenga's avatar
Kurt Zeilenga committed
278

279
This marks the beginning of a new {{TERM:MDB}} backend
Kurt Zeilenga's avatar
Kurt Zeilenga committed
280
definition.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
281
282


Kurt Zeilenga's avatar
Kurt Zeilenga committed
283
H3: General Database Directives
284

Kurt Zeilenga's avatar
Kurt Zeilenga committed
285
Directives in this section apply only to the database in which
Kurt Zeilenga's avatar
Kurt Zeilenga committed
286
they are defined. They are supported by every type of database.
287

Kurt Zeilenga's avatar
Kurt Zeilenga committed
288
H4: database <type>
289

Kurt Zeilenga's avatar
Kurt Zeilenga committed
290
291
This directive marks the beginning of a database instance
declaration.
Howard Chu's avatar
Howard Chu committed
292
{{EX:<type>}} should be one of the
Kurt Zeilenga's avatar
Kurt Zeilenga committed
293
supported backend types listed in Table 6.2.
294
295
296

\Example:

297
>	database mdb
298

299
This marks the beginning of a new {{TERM:MDB}} database instance
Kurt Zeilenga's avatar
Kurt Zeilenga committed
300
declaration.
301
302


303
H4: limits <selector> <limit> [<limit> [...]]
304

305
306
Specify time and size limits based on the operation's initiator or base
DN.
307

308
See the {{SECT:Limits}} section of this guide and {{slapd.conf}}(5)
309
310
311
for more details.


312
313
H4: readonly { on | off }

Kurt Zeilenga's avatar
Kurt Zeilenga committed
314
This directive puts the database into "read-only" mode. Any
315
attempts to modify the database will return an "unwilling to
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
316
317
perform" error.  If set on a consumer, modifications sent by
syncrepl will still occur.
318
319
320

\Default:

321
>	readonly off
322
323


324
H4: rootdn <DN>
325

326
This directive specifies the DN that is not subject to
327
access control or administrative limit restrictions for
328
operations on this database.  The DN need not refer to
329
330
an entry in this database or even in the directory. The
DN may refer to a SASL identity.
331

332
Entry-based Example:
333

334
>	rootdn "cn=Manager,dc=example,dc=com"
335

336
337
SASL-based Example:

Howard Chu's avatar
Howard Chu committed
338
>	rootdn "uid=root,cn=example.com,cn=digest-md5,cn=auth"
339

340
341
342
See the {{SECT:SASL Authentication}} section for information on
SASL authentication identities.

343

344
345
H4: rootpw <password>

346
This directive can be used to specifies a password for the DN for
347
the rootdn (when the rootdn is set to a DN within the database).
348
349
350

\Example:

351
>	rootpw secret
352

Kurt Zeilenga's avatar
Kurt Zeilenga committed
353
It is also permissible to provide hash of the password in {{REF:RFC2307}}
354
form.  {{slappasswd}}(8) may be used to generate the password hash.
355
356
357
358
359
360
361

\Example:

>	rootpw {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN

The hash was generated using the command {{EX:slappasswd -s secret}}.

362

363
364
H4: suffix <dn suffix>

Kurt Zeilenga's avatar
Kurt Zeilenga committed
365
This directive specifies the DN suffix of queries that will be
366
367
368
369
370
371
passed to this backend database. Multiple suffix lines can be
given, and at least one is required for each database
definition.

\Example:

372
>	suffix "dc=example,dc=com"
373

374
Queries with a DN ending in "dc=example,dc=com"
375
376
will be passed to this backend.

377
Note: When the backend to pass a query to is selected, slapd
378
379
380
381
looks at the suffix line(s) in each database definition in the
order they appear in the file. Thus, if one database suffix is a
prefix of another, it must appear after it in the config file.

382

383
384
H4: syncrepl

385
>	syncrepl rid=<replica ID>
386
>		provider=ldap[s]://<hostname>[:port]
387
>		searchbase=<base DN>
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
388
389
>		[type=refreshOnly|refreshAndPersist]
>		[interval=dd:hh:mm:ss]
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
390
>		[retry=[<retry interval> <# of retries>]+]
391
392
>		[filter=<filter str>]
>		[scope=sub|one|base]
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
393
>		[attrs=<attr list>]
394
>		[exattrs=<attr list>]
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
395
>		[attrsonly]
396
397
>		[sizelimit=<limit>]
>		[timelimit=<limit>]
398
>		[schemachecking=on|off]
399
400
>		[network-timeout=<seconds>]
>		[timeout=<seconds>]
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
401
>		[bindmethod=simple|sasl]
402
>		[binddn=<DN>]
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
403
404
405
406
407
408
>		[saslmech=<mech>]
>		[authcid=<identity>]
>		[authzid=<identity>]
>		[credentials=<passwd>]
>		[realm=<realm>]
>		[secprops=<properties>]
409
>		[keepalive=<idle>:<probes>:<interval>]
410
411
412
413
414
415
>		[starttls=yes|critical]
>		[tls_cert=<file>]
>		[tls_key=<file>]
>		[tls_cacert=<file>]
>		[tls_cacertdir=<path>]
>		[tls_reqcert=never|allow|try|demand]
416
>		[tls_cipher_suite=<ciphers>]
417
>		[tls_crlcheck=none|peer|all]
418
419
>		[tls_protocol_min=<major>[.<minor>]]
>		[suffixmassage=<real DN>]
420
421
422
>		[logbase=<base DN>]
>		[logfilter=<filter str>]
>		[syncdata=default|accesslog|changelog]
423

424

425
426
This directive specifies the current database as a consumer of the
provider content by establishing the current {{slapd}}(8) as a
427
replication consumer site running a syncrepl replication engine.
428
429
430
The provider database is located at the replication provider site
specified by the {{EX:provider}} parameter. The consumer database is
kept up-to-date with the provider content using the LDAP Content
Howard Chu's avatar
Howard Chu committed
431
432
Synchronization protocol. See {{REF:RFC4533}}
for more information on the protocol.
433

434
The {{EX:rid}} parameter is used for identification of the current
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
435
{{EX:syncrepl}} directive within the replication consumer server,
436
437
where {{EX:<replica ID>}} uniquely identifies the syncrepl specification
described by the current {{EX:syncrepl}} directive. {{EX:<replica ID>}}
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
438
is non-negative and is no more than three decimal digits in length.
439
440

The {{EX:provider}} parameter specifies the replication provider site
441
containing the provider content as an LDAP URI. The {{EX:provider}}
442
443
444
445
446
parameter specifies a scheme, a host and optionally a port where the
provider slapd instance can be found. Either a domain name or IP
address may be used for <hostname>. Examples are
{{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}.
If <port> is not given, the standard LDAP port number (389 or 636) is used.
447
Note that the syncrepl uses a consumer-initiated protocol, and hence its
448
specification is located on the consumer.
449

450
The content of the syncrepl consumer is defined using a search
451
specification as its result set. The consumer slapd will
Kurt Zeilenga's avatar
Kurt Zeilenga committed
452
send search requests to the provider slapd according to the search
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
453
specification. The search specification includes {{EX:searchbase}},
454
{{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:exattrs}}, {{EX:attrsonly}},
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
455
{{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal
456
457
458
459
460
search specification. The {{EX:searchbase}} parameter has no
default value and must always be specified. The {{EX:scope}} defaults
to {{EX:sub}}, the {{EX:filter}} defaults to {{EX:(objectclass=*)}},
{{EX:attrs}} defaults to {{EX:"*,+"}} to replicate all user and operational
attributes, and {{EX:attrsonly}} is unset by default. Both {{EX:sizelimit}}
461
and {{EX:timelimit}} default to "unlimited", and only positive integers
462
463
or "unlimited" may be specified. The {{EX:exattrs}} option may also be used
to specify attributes that should be omitted from incoming entries.
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
464

465
The {{TERM[expand]LDAP Sync}} protocol has two operation
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
466
types: {{EX:refreshOnly}} and {{EX:refreshAndPersist}}.
467
The operation type is specified by the {{EX:type}} parameter.
468
In the {{EX:refreshOnly}} operation, the next synchronization search operation
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
469
is periodically rescheduled at an interval time after each
470
471
synchronization operation finishes. The interval is specified
by the {{EX:interval}} parameter. It is set to one day by default.
472
In the {{EX:refreshAndPersist}} operation, a synchronization search
473
remains persistent in the provider {{slapd}} instance. Further updates to the
474
provider will generate {{EX:searchResultEntry}} to the consumer slapd
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
475
as the search responses to the persistent synchronization search.
476

Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
477
478
If an error occurs during replication, the consumer will attempt to reconnect
according to the retry parameter which is a list of the <retry interval>
479
and <# of retries> pairs. For example, retry="60 10 300 3" lets the consumer
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
480
481
482
483
retry every 60 seconds for the first 10 times and then retry every 300 seconds
for the next three times before stop retrying. + in <#  of retries> means
indefinite number of retries until success.

484
The schema checking can be enforced at the LDAP Sync consumer site
485
486
by turning on the {{EX:schemachecking}} parameter.
If it is turned on, every replicated entry will be checked for its
487
488
schema as the entry is stored on the consumer.
Every entry in the consumer should contain those attributes
489
490
491
492
required by the schema definition.
If it is turned off, entries will be stored without checking
schema conformance. The default is off.

493
494
495
496
497
498
The {{EX:network-timeout}} parameter sets how long the consumer will
wait to establish a network connection to the provider.  Once a
connection is established, the {{EX:timeout}} parameter determines how
long the consumer will wait for the initial Bind request to complete.  The
defaults for these parameters come from {{ldap.conf}}(5).

Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
499
500
501
The {{EX:binddn}} parameter gives the DN to bind as for the
syncrepl searches to the provider slapd. It should be a DN
which has read access to the replication content in the
502
provider database. 
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
503
504
505
506

The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
depending on whether simple password-based authentication or
{{TERM:SASL}} authentication is to be used when connecting
507
to the provider {{slapd}} instance.
508

Kurt Zeilenga's avatar
Kurt Zeilenga committed
509
510
Simple authentication should not be used unless adequate data
integrity and confidentiality protections are in place (e.g. TLS
Kurt Zeilenga's avatar
Kurt Zeilenga committed
511
or IPsec). Simple authentication requires specification of {{EX:binddn}}
Kurt Zeilenga's avatar
Kurt Zeilenga committed
512
and {{EX:credentials}} parameters.
513

Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
514
515
SASL authentication is generally recommended.  SASL authentication
requires specification of a mechanism using the {{EX:saslmech}} parameter.
516
Depending on the mechanism, an authentication identity and/or
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
517
credentials can be specified using {{EX:authcid}} and {{EX:credentials}},
518
respectively.  The {{EX:authzid}} parameter may be used to specify
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
519
520
521
522
523
an authorization identity.

The {{EX:realm}} parameter specifies a realm which a certain
mechanisms authenticate the identity within. The {{EX:secprops}}
parameter specifies Cyrus SASL security properties.
524

525
The {{EX:keepalive}} parameter sets the values of idle, probes, and interval
526
527
528
529
530
531
532
533
534
535
used to check whether a socket is alive;  idle is the number of seconds a
connection needs to remain idle before TCP starts sending keepalive probes;
probes is the maximum number of keepalive probes TCP should send before
dropping the connection; interval is interval in seconds between individual
keepalive probes.  Only some systems support the customization of these
values; the keepalive parameter is ignored otherwise, and system-wide
settings are used. For example, keepalive="240:10:30" will send a keepalive
probe 10 times, every 30 seconds, after 240 seconds of idle activity.  If
no response to the probes is received, the connection will be dropped.

536
537
538
539
The {{EX:starttls}} parameter specifies use of the StartTLS extended
operation to establish a TLS session before authenticating to the provider.
If the {{EX:critical}} argument is supplied, the session will be aborted
if the StartTLS request fails.  Otherwise the syncrepl session continues
540
541
without TLS.  The tls_reqcert setting defaults to {{EX:"demand"}} and the
other TLS settings default to the same as the main slapd TLS settings.
542

543
544
545
546
547
The {{EX:suffixmassage}} parameter allows the consumer to pull entries
from a remote directory whose DN suffix differs from the local directory.
The portion of the remote entries' DNs that matches the searchbase will
be replaced with the suffixmassage DN.

548
549
550
551
552
553
554
555
556
557
558
Rather than replicating whole entries, the consumer can query logs
of data modifications.  This mode of operation is referred to as
{{delta syncrepl}}.  In addition to the above parameters, the
{{EX:logbase}} and {{EX:logfilter}} parameters must be set appropriately
for the log that will be used. The {{EX:syncdata}} parameter must
be set to either {{EX:"accesslog"}} if the log conforms to the
{{slapo-accesslog}}(5) log format, or {{EX:"changelog"}} if the log
conforms to the obsolete {{changelog}} format. If the {{EX:syncdata}}
parameter is omitted or set to {{EX:"default"}} then the log
parameters are ignored.

559
The {{syncrepl}} replication mechanism is supported by the {{mdb}} backend.
560
561
562

See the {{SECT:LDAP Sync Replication}} chapter of this guide for
more information on how to use this directive.
563

564

565
566
H4: updateref <URL>

567
This directive is only applicable in a {{replica}} (or {{shadow}})
568
{{slapd}}(8) instance. It
569
570
571
572
573
574
specifies the URL to return to clients which submit update
requests upon the replica.
If specified multiple times, each {{TERM:URL}} is provided.

\Example:

575
>	updateref	ldap://provider.example.net
576
577


578
H3: MDB Database Directives
Kurt Zeilenga's avatar
Kurt Zeilenga committed
579

580
581
582
583
584
Directives in this category only apply to the {{TERM:MDB}}
database backend.
That is, they must follow a "database mdb" line
and come before any subsequent "backend" or "database" lines.
For a complete reference of MDB configuration directives, see {{slapd-mdb}}(5).
Kurt Zeilenga's avatar
Kurt Zeilenga committed
585

586

Kurt Zeilenga's avatar
Kurt Zeilenga committed
587
588
H4: directory <directory>

589
This directive specifies the directory where the MDB files
Howard Chu's avatar
Howard Chu committed
590
containing the database and associated indices live.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
591
592
593
594

\Default:

>	directory /usr/local/var/openldap-data
595

596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
H4: checkpoint <kbyte> <min>

This directive specifies the frequency for flushing the database disk
buffers. This directive is only needed if the {{dbnosync}} option is
{{EX:TRUE}}.
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. When the <min> argument is
non-zero, an internal task will run every <min> minutes to perform the
checkpoint. Note: currently the _kbyte_ setting is unimplemented.

\Example:

>   checkpoint: 1024 10

H4: dbnosync: { TRUE | FALSE }

This directive causes on-disk database contents to not be immediately
synchronized with in memory changes upon change.  Setting this option
to {{EX:TRUE}} may improve performance at the expense of data integrity.


H4: envflags: {nosync,nometasync,writemap,mapasync,nordahead}

This option specifies flags for finer-grained control of  the  LMDB  library's
operation.

* {{F:nosync}}: This is exactly the same as the dbnosync directive.

* {{F: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 nometasync and nosync are set, the nosync flag takes
precedence.

* {{F: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.

* {{F: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 writemap has not been set. It also has
no effect if nosync is set.

* {{F: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.


H4: index: {<attrlist> | default} [pres,eq,approx,sub,none]

This directive specifies the indices to maintain for the given
attribute. If only an {{EX:<attrlist>}} is given, the default
indices are maintained. The index keywords correspond to the
common types of matches that may be used in an LDAP search filter.

\Example:

>   index: default pres,eq
>   index: uid
>   index: cn,sn pres,eq,sub
>   index: objectClass eq

The first line sets the default set of indices to maintain to
present and equality.  The second line causes the default (pres,eq)
set of indices to be maintained for the {{EX:uid}} attribute type.
The third line causes present, equality, and substring indices to
be maintained for {{EX:cn}} and {{EX:sn}} attribute types.  The
fourth line causes an equality index for the {{EX:objectClass}}
attribute type.

There is no index keyword for inequality matches. Generally these
matches do not use an index. However, some attributes do support
indexing for inequality matches, based on the equality index.

A substring index can be more explicitly specified as {{EX:subinitial}},
{{EX:subany}}, or {{EX:subfinal}}, corresponding to the three
possible components
of a substring match filter. A subinitial index only indexes
substrings that appear at the beginning of an attribute value.
A subfinal index only indexes substrings that appear at the end
of an attribute value, while subany indexes substrings that occur
anywhere in a value.

Note that by default, setting an index for an attribute also
affects every subtype of that attribute. E.g., setting an equality
index on the {{EX:name}} attribute causes {{EX:cn}}, {{EX:sn}}, and every other
attribute that inherits from {{EX:name}} to be indexed.

By default, no indices are maintained.  It is generally advised
that minimally an equality index upon objectClass be maintained.

>   index: objectClass eq

Additional indices should be configured corresponding to the
most common searches that are used on the database.
Presence indexing should not be configured for an attribute
unless the attribute occurs very rarely in the database, and
presence searches on the attribute occur very frequently during
normal use of the directory. Most applications don't use presence
searches, so usually presence indexing is not very useful.


H4: maxreaders: <integer>

This directive specifies 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.


H4: maxsize: <bytes>

This directive specifies 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 (10MB). 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.


H4: mode: { <octal> | <symbolic> }

This directive specifies the file protection mode that newly
created database index files should have. This can be in the form
{{EX:0600}} or {{EX:-rw-------}}

\Default:

>   mode: 0600


H4: rtxnsize: <entries>

This directive specifies 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.


H4: searchstack: <integer>

Specify the depth of the stack used for search filter evaluation.
Search filters are evaluated on a stack to accommodate nested {{EX:AND}} /
{{EX:OR}} clauses. An individual stack is allocated for 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 separate 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
uses 512K bytes per level on a 32-bit machine, or 1024K bytes per level
on a 64-bit machine. The default stack depth is 16, thus 8MB or 16MB
per thread is used on 32 and 64 bit machines, respectively. Also the
512KB size of a single stack slot is set by a compile-time constant which
may be changed if needed; the code must be recompiled for the change
to take effect.

\Default:

>   searchstack: 16


H4: Sample Entry

>database mdb
>suffix: "dc=example,dc=com"
>directory: /usr/local/var/openldap-data
>index: objectClass eq

773
774
775
776
777

H2: Configuration File Example

The following is an example configuration file, interspersed
with explanatory text. It defines two databases to handle
778
different parts of the {{TERM:X.500}} tree; both are {{TERM:MDB}}
779
780
781
782
783
784
785
786
database instances. The line numbers shown are provided for
reference only and are not included in the actual file. First, the
global configuration section:

E:  1.    # example config file - global configuration section
E:  2.    include /usr/local/etc/schema/core.schema
E:  3.    referral ldap://root.openldap.org
E:  4.    access to * by * read
787

788
789
790
791
792
793
794
795
796
797
798
Line 1 is a comment. Line 2 includes another config file
which contains {{core}} schema definitions.
The {{EX:referral}} directive on line 3
means that queries not local to one of the databases defined
below will be referred to the LDAP server running on the
standard port (389) at the host {{EX:root.openldap.org}}.

Line 4 is a global access control.  It applies to all
entries (after any applicable database-specific access
controls).

799
The next section of the configuration file defines a MDB
800
801
backend that will handle queries for things in the
"dc=example,dc=com" portion of the tree. The
802
database is to be replicated to two replica slapds, one on
803
804
805
806
truelies, the other on judgmentday. Indices are to be
maintained for several attributes, and the {{EX:userPassword}}
attribute is to be protected from unauthorized access.

807
808
E:  5.    # MDB definition for the example.com
E:  6.    database mdb
809
810
811
812
813
814
E:  7.    suffix "dc=example,dc=com"
E:  8.    directory /usr/local/var/openldap-data
E:  9.    rootdn "cn=Manager,dc=example,dc=com"
E: 10.    rootpw secret
E: 11.    # indexed attribute definitions
E: 12.    index uid pres,eq
Howard Chu's avatar
Howard Chu committed
815
E: 13.    index cn,sn pres,eq,approx,sub
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
E: 14.    index objectClass eq
E: 15.    # database access control definitions
E: 16.    access to attrs=userPassword
E: 17.        by self write
E: 18.        by anonymous auth
E: 19.        by dn.base="cn=Admin,dc=example,dc=com" write
E: 20.        by * none
E: 21.    access to *
E: 22.        by self write
E: 23.        by dn.base="cn=Admin,dc=example,dc=com" write
E: 24.        by * read

Line 5 is a comment. The start of the database definition is marked
by the database keyword on line 6. Line 7 specifies the DN suffix
for queries to pass to this database. Line 8 specifies the directory
in which the database files will live.

Lines 9 and 10 identify the database {{super-user}} entry and associated
password. This entry is not subject to access control or size or
time limit restrictions.

Lines 12 through 14 indicate the indices to maintain for various
attributes.

Lines 16 through 24 specify access control for entries in this
database. For all applicable entries, the {{EX:userPassword}} attribute is writable
by the entry itself and by the "admin" entry.  It may be used for
authentication/authorization purposes, but is otherwise not readable.
All other attributes are writable by the entry and the "admin"
entry, but may be read by all users (authenticated or not).

The next section of the example configuration file defines another
848
MDB database. This one handles queries involving the
849
850
851
852
{{EX:dc=example,dc=net}} subtree but is managed by the same entity
as the first database.  Note that without line 39, the read access
would be allowed due to the global access rule at line 4.

853
854
E: 33.    # MDB definition for example.net
E: 34.    database mdb
855
856
857
858
859
E: 35.    suffix "dc=example,dc=net"
E: 36.    directory /usr/local/var/openldap-data-net
E: 37.    rootdn "cn=Manager,dc=example,dc=com"
E: 38.    index objectClass eq
E: 39.    access to * by users read