slapdconfig.sdf 24.7 KB
Newer Older
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1
# $OpenLDAP$
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
2
# Copyright 1999-2020 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
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
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
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
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
94
requestors (specified by <who>).  See the {{SECT:Access Control}} section of 
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

Kurt Zeilenga's avatar
Kurt Zeilenga committed
133
This directive specifies the level at which debugging statements
Kurt Zeilenga's avatar
Kurt Zeilenga committed
134
and operation statistics should be syslogged (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
137
configured OpenLDAP {{EX:--enable-debug}} (the default) for this
to work (except for the two statistics levels, which are always
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
138
139
140
enabled). Log levels may be specified as integers or by keyword.
Multiple log levels may be used and the levels are additive. To display what
numbers correspond to what kind of debugging, invoke slapd with {{EX:-d?}}
Kurt Zeilenga's avatar
Kurt Zeilenga committed
141
or consult the table below. The possible values for <integer> are:
142

143
!block table; colaligns="RL"; align=Center; \
Kurt Zeilenga's avatar
Kurt Zeilenga committed
144
	title="Table 6.1: Debugging Levels"
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
Level	Keyword		Description
-1	any		enable all debugging
0			no debugging
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
32768	(0x8000 none)	only messages that get logged whatever log level is set
162
!endblock
163

Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
164
165
166
167
168
169
170
171
172
173
174
175
176
The desired log level can be input as a single integer that
combines the (ORed) desired levels, both in decimal or in hexadecimal 
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.

\Examples:
177

178
E: loglevel -1
179
180

This will cause lots and lots of debugging information to be
181
logged.
182

Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
183
184
185
186
187
188
189
190
191
192
E: loglevel conns filter

Just log the connection and search filter processing.

E: loglevel none

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.

193
194
\Default:

Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
195
E: loglevel stats
196

Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
197
198
Basic stats logging is configured by default. However, if no loglevel is
defined, no logging occurs (equivalent to a 0 level).
199

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

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

206

Kurt Zeilenga's avatar
ispell    
Kurt Zeilenga committed
207
H4: referral <URI>
208

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

\Example:

214
>	referral ldap://root.openldap.org
215

Kurt Zeilenga's avatar
Kurt Zeilenga committed
216
217
This will refer non-local queries to the global root LDAP server
at the OpenLDAP Project. Smart LDAP clients can re-ask their
218
219
220
221
222
223
224
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
225
This directive specifies the maximum number of entries to return
226
227
228
229
from a search operation.

\Default:

230
>	sizelimit 500
231

232
See the {{SECT:Limits}} section of this guide and {{slapd.conf}}(5)
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
233
for more details.
234
235
236

H4: timelimit <integer>

Kurt Zeilenga's avatar
Kurt Zeilenga committed
237
This directive specifies the maximum number of seconds (in real
238
239
240
241
242
243
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:

244
>	timelimit 3600
245

246
See the {{SECT:Limits}} section of this guide and {{slapd.conf}}(5)
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
247
248
for more details.

249

Kurt Zeilenga's avatar
Kurt Zeilenga committed
250
H3: General Backend Directives
251

Kurt Zeilenga's avatar
Kurt Zeilenga committed
252
253
254
255
256
257
258
259
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
260
This directive marks the beginning of a backend declaration.
Howard Chu's avatar
Howard Chu committed
261
{{EX:<type>}} should be one of the
Kurt Zeilenga's avatar
Kurt Zeilenga committed
262
supported backend types listed in Table 6.2.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
263
264

!block table; align=Center; coltags="EX,N"; \
Howard Chu's avatar
Howard Chu committed
265
	title="Table 6.2: Database Backends"
Kurt Zeilenga's avatar
Kurt Zeilenga committed
266
Types	Description
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
267
bdb	Berkeley DB transactional backend (deprecated)
Kurt Zeilenga's avatar
Kurt Zeilenga committed
268
dnssrv	DNS SRV backend
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
269
hdb	Hierarchical variant of bdb backend (deprecated)
Kurt Zeilenga's avatar
Kurt Zeilenga committed
270
ldap	Lightweight Directory Access Protocol (Proxy) backend
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
271
mdb	Memory-Mapped DB backend
Kurt Zeilenga's avatar
Kurt Zeilenga committed
272
273
274
275
276
277
278
279
280
281
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:

282
>	backend mdb
Kurt Zeilenga's avatar
Kurt Zeilenga committed
283

284
This marks the beginning of a new {{TERM:MDB}} backend
Kurt Zeilenga's avatar
Kurt Zeilenga committed
285
definition.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
286
287


Kurt Zeilenga's avatar
Kurt Zeilenga committed
288
H3: General Database Directives
289

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

Kurt Zeilenga's avatar
Kurt Zeilenga committed
293
H4: database <type>
294

Kurt Zeilenga's avatar
Kurt Zeilenga committed
295
296
This directive marks the beginning of a database instance
declaration.
Howard Chu's avatar
Howard Chu committed
297
{{EX:<type>}} should be one of the
Kurt Zeilenga's avatar
Kurt Zeilenga committed
298
supported backend types listed in Table 6.2.
299
300
301

\Example:

302
>	database mdb
303

304
This marks the beginning of a new {{TERM:MDB}} database instance
Kurt Zeilenga's avatar
Kurt Zeilenga committed
305
declaration.
306
307


308
H4: limits <selector> <limit> [<limit> [...]]
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
309

310
311
Specify time and size limits based on the operation's initiator or base
DN.
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
312

313
See the {{SECT:Limits}} section of this guide and {{slapd.conf}}(5)
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
314
315
316
for more details.


317
318
H4: readonly { on | off }

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

\Default:

326
>	readonly off
327
328


329
H4: rootdn <DN>
330

331
This directive specifies the DN that is not subject to
332
access control or administrative limit restrictions for
333
operations on this database.  The DN need not refer to
334
335
an entry in this database or even in the directory. The
DN may refer to a SASL identity.
336

337
Entry-based Example:
338

339
>	rootdn "cn=Manager,dc=example,dc=com"
340

341
342
SASL-based Example:

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

345
346
347
See the {{SECT:SASL Authentication}} section for information on
SASL authentication identities.

348

349
350
H4: rootpw <password>

351
This directive can be used to specifies a password for the DN for
352
the rootdn (when the rootdn is set to a DN within the database).
353
354
355

\Example:

356
>	rootpw secret
357

Kurt Zeilenga's avatar
Kurt Zeilenga committed
358
It is also permissible to provide hash of the password in {{REF:RFC2307}}
359
form.  {{slappasswd}}(8) may be used to generate the password hash.
360
361
362
363
364
365
366

\Example:

>	rootpw {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN

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

367

368
369
H4: suffix <dn suffix>

Kurt Zeilenga's avatar
Kurt Zeilenga committed
370
This directive specifies the DN suffix of queries that will be
371
372
373
374
375
376
passed to this backend database. Multiple suffix lines can be
given, and at least one is required for each database
definition.

\Example:

377
>	suffix "dc=example,dc=com"
378

379
Queries with a DN ending in "dc=example,dc=com"
380
381
will be passed to this backend.

382
Note: When the backend to pass a query to is selected, slapd
383
384
385
386
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.

387

388
389
H4: syncrepl

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

429

430
431
This directive specifies the current database as a consumer of the
provider content by establishing the current {{slapd}}(8) as a
432
replication consumer site running a syncrepl replication engine.
433
434
435
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
436
437
Synchronization protocol. See {{REF:RFC4533}}
for more information on the protocol.
438

439
The {{EX:rid}} parameter is used for identification of the current
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
440
{{EX:syncrepl}} directive within the replication consumer server,
441
442
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
443
is non-negative and is no more than three decimal digits in length.
444
445

The {{EX:provider}} parameter specifies the replication provider site
446
containing the provider content as an LDAP URI. The {{EX:provider}}
447
448
449
450
451
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.
452
Note that the syncrepl uses a consumer-initiated protocol, and hence its
453
specification is located on the consumer.
454

455
The content of the syncrepl consumer is defined using a search
456
specification as its result set. The consumer slapd will
Kurt Zeilenga's avatar
Kurt Zeilenga committed
457
send search requests to the provider slapd according to the search
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
458
specification. The search specification includes {{EX:searchbase}},
459
{{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:exattrs}}, {{EX:attrsonly}},
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
460
{{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal
461
462
463
464
465
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}}
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
466
and {{EX:timelimit}} default to "unlimited", and only positive integers
467
468
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
469

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

Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
482
483
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>
484
and <# of retries> pairs. For example, retry="60 10 300 3" lets the consumer
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
485
486
487
488
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.

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

498
499
500
501
502
503
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
504
505
506
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
507
provider database. 
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
508
509
510
511

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
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
512
to the provider {{slapd}} instance.
513

Kurt Zeilenga's avatar
Kurt Zeilenga committed
514
515
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
516
or IPsec). Simple authentication requires specification of {{EX:binddn}}
Kurt Zeilenga's avatar
Kurt Zeilenga committed
517
and {{EX:credentials}} parameters.
518

Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
519
520
SASL authentication is generally recommended.  SASL authentication
requires specification of a mechanism using the {{EX:saslmech}} parameter.
521
Depending on the mechanism, an authentication identity and/or
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
522
credentials can be specified using {{EX:authcid}} and {{EX:credentials}},
523
respectively.  The {{EX:authzid}} parameter may be used to specify
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
524
525
526
527
528
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.
529

530
The {{EX:keepalive}} parameter sets the values of idle, probes, and interval
531
532
533
534
535
536
537
538
539
540
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.

Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
541
542
543
544
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
545
546
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.
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
547

548
549
550
551
552
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.

Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
553
554
555
556
557
558
559
560
561
562
563
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.

564
565
The {{syncrepl}} replication mechanism is supported by the {{bdb}},
{{hdb}}, and {{mdb}} backends.
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
566
567
568

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

570

571
572
H4: updateref <URL>

573
This directive is only applicable in a {{replica}} (or {{shadow}})
574
{{slapd}}(8) instance. It
575
576
577
578
579
580
specifies the URL to return to clients which submit update
requests upon the replica.
If specified multiple times, each {{TERM:URL}} is provided.

\Example:

581
>	updateref	ldap://provider.example.net
582
583


Howard Chu's avatar
Howard Chu committed
584
H3: BDB and HDB Database Directives
Kurt Zeilenga's avatar
Kurt Zeilenga committed
585

Howard Chu's avatar
Howard Chu committed
586
587
588
589
Directives in this category only apply to both the {{TERM:BDB}}
and the {{TERM:HDB}} database.
That is, they must follow a "database bdb" or "database hdb" line
and come before any
590
subsequent "backend" or "database" line.  For a complete reference
Howard Chu's avatar
Howard Chu committed
591
of BDB/HDB configuration directives, see {{slapd-bdb}}(5).
Kurt Zeilenga's avatar
Kurt Zeilenga committed
592

593

Kurt Zeilenga's avatar
Kurt Zeilenga committed
594
595
596
H4: directory <directory>

This directive specifies the directory where the BDB files
Howard Chu's avatar
Howard Chu committed
597
containing the database and associated indices live.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
598
599
600
601

\Default:

>	directory /usr/local/var/openldap-data
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
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


H2: Configuration File Example

The following is an example configuration file, interspersed
with explanatory text. It defines two databases to handle
different parts of the {{TERM:X.500}} tree; both are {{TERM:BDB}}
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
 
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).

The next section of the configuration file defines a BDB
backend that will handle queries for things in the
"dc=example,dc=com" portion of the tree. The
632
database is to be replicated to two replica slapds, one on
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
633
634
635
636
637
638
639
640
641
642
643
644
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.

E:  5.    # BDB definition for the example.com
E:  6.    database bdb
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
645
E: 13.    index cn,sn pres,eq,approx,sub
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
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
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
BDB database. This one handles queries involving the
{{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.

E: 33.    # BDB definition for example.net
E: 34.    database bdb
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