slapd.conf.5 53 KB
Newer Older
1
.TH SLAPD.CONF 5 "RELEASEDATE" "OpenLDAP LDVERSION"
Kurt Zeilenga's avatar
Kurt Zeilenga committed
2
.\" Copyright 1998-2005 The OpenLDAP Foundation All Rights Reserved.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
3
.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
4
.\" $OpenLDAP$
Kurt Zeilenga's avatar
Kurt Zeilenga committed
5
6
7
8
9
10
11
12
13
14
slapd.conf \- configuration file for slapd, the stand-alone LDAP daemon
.SH SYNOPSIS
ETCDIR/slapd.conf
.SH DESCRIPTION
The file
.B ETCDIR/slapd.conf
contains configuration information for the
.BR slapd (8)
daemon.  This configuration file is also used by the
.BR slurpd (8)
15
replication daemon and by the SLAPD tools
Pierangelo Masarati's avatar
Pierangelo Masarati committed
16
.BR slapacl (8),
17
.BR slapadd (8),
Pierangelo Masarati's avatar
Pierangelo Masarati committed
18
.BR slapauth (8),
19
.BR slapcat (8),
Pierangelo Masarati's avatar
Pierangelo Masarati committed
20
21
.BR slapdn (8),
.BR slapindex (8),
Kurt Zeilenga's avatar
Kurt Zeilenga committed
22
and
Pierangelo Masarati's avatar
Pierangelo Masarati committed
23
.BR slaptest (8).
Kurt Zeilenga's avatar
Kurt Zeilenga committed
24
25
26
27
28
29
30
31
.LP
The
.B slapd.conf
file consists of a series of global configuration options that apply to
.B slapd
as a whole (including all backends), followed by zero or more database
backend definitions that contain information specific to a backend
instance.
32
33
The configuration options are case-insensitive;
their value, on a case by case basis, may be case-sensitive.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
34
35
36
37
38
39
40
41
42
.LP
The general format of
.B slapd.conf
is as follows:
.LP
.nf
    # comment - these options apply to every database
    <global configuration options>
    # first database definition & configuration options
43
    database <backend 1 type>
Kurt Zeilenga's avatar
Kurt Zeilenga committed
44
45
46
47
48
49
50
51
52
    <configuration options specific to backend 1>
    # subsequent database definitions & configuration options
    ...
.fi
.LP
As many backend-specific sections as desired may be included.  Global
options can be overridden in a backend (for options that appear more
than once, the last appearance in the
.B slapd.conf
53
54
55
56
file is used).
.LP
If a line begins with white space, it is considered a continuation
of the previous line.  Blank lines and comment lines beginning with
57
58
a `#' character are ignored.  Note: continuation lines are unwrapped
before comment processing is applied.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
59
60
61
62
63
64
65
66
.LP
Arguments on configuration lines are separated by white space. If an
argument contains white space, the argument should be enclosed in
double quotes.  If an argument contains a double quote (`"') or a
backslash character (`\\'), the character should be preceded by a
backslash character.
.LP
The specific configuration options available are discussed below in the
67
68
69
70
71
Global Configuration Options, General Backend Options, and General Database
Options.  Backend-specific options are discussed in the
.B slapd-<backend>(5)
manual pages.  Refer to the "OpenLDAP Administrator's Guide" for more
details on the slapd configuration file.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
72
73
74
75
76
.SH GLOBAL CONFIGURATION OPTIONS
Options described in this section apply to all backends, unless specifically 
overridden in a backend definition. Arguments that should be replaced by 
actual text are shown in brackets <>.
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
77
.B access to <what> "[ by <who> <access> <control> ]+"
78
Grant access (specified by <access>) to a set of entries and/or
Kurt Zeilenga's avatar
Kurt Zeilenga committed
79
attributes (specified by <what>) by one or more requestors (specified
80
by <who>).
81
82
83
84
If no access controls are present, the default policy
allows anyone and everyone to read anything but restricts
updates to rootdn.  (e.g., "access to * by * read").
The rootdn can always read and write EVERYTHING!
Pierangelo Masarati's avatar
Pierangelo Masarati committed
85
86
87
See
.BR slapd.access (5)
and the "OpenLDAP's Administrator's Guide" for details.
88
.TP
89
.B allow <features>
90
91
Specify a set of features (separated by white space) to
allow (default none).
92
.B bind_v2
Kurt Zeilenga's avatar
Kurt Zeilenga committed
93
94
allows acceptance of LDAPv2 bind requests.  Note that
.BR slapd (8)
95
does not truly implement LDAPv2 (RFC 1777), now Historic (RFC 3494).
96
.B bind_anon_cred
Howard Chu's avatar
Howard Chu committed
97
allows anonymous bind when credentials are not empty (e.g.
98
99
100
when DN is empty).
.B bind_anon_dn
allows unauthenticated (anonymous) bind when DN is not empty.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
101
102
103
.B update_anon
allow unauthenticated (anonymous) update operations to be processed
(subject to access controls and other administrative limits).
104
.TP
105
106
107
108
109
.B argsfile <filename>
The ( absolute ) name of a file that will hold the 
.B slapd
server's command line options
if started without the debugging command line option.
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
.TP
.B attributeoptions [option-name]...
Define tagging attribute options or option tag/range prefixes.
Options must not end with `-', prefixes must end with `-'.
The `lang-' prefix is predefined.
If you use the
.B attributeoptions
directive, `lang-' will no longer be defined and you must specify it
explicitly if you want it defined.

An attribute description with a tagging option is a subtype of that
attribute description without the option.
Except for that, options defined this way have no special semantics.
Prefixes defined this way work like the `lang-' options:
They define a prefix for tagging options starting with the prefix.
That is, if you define the prefix `x-foo-', you can use the option
`x-foo-bar'.
Furthermore, in a search or compare, a prefix or range name (with
a trailing `-') matches all options starting with that name, as well
as the option with the range name sans the trailing `-'.
That is, `x-foo-bar-' matches `x-foo-bar' and `x-foo-bar-baz'.

Kurt Zeilenga's avatar
Kurt Zeilenga committed
132
133
RFC 2251 reserves options beginning with `x-' for private experiments.
Other options should be registered with IANA, see RFC 3383 section 3.4.
134
135
OpenLDAP also has the `binary' option built in, but this is a transfer
option, not a tagging option.
136
137
.HP
.hy 0
138
139
.B attributetype "(\ <oid>\
 [NAME\ <name>]\
140
 [DESC\ <description>]\
141
142
143
144
145
146
147
148
149
150
 [OBSOLETE]\
 [SUP\ <oid>]\
 [EQUALITY\ <oid>]\
 [ORDERING\ <oid>]\
 [SUBSTR\ <oid>]\
 [SYNTAX\ <oidlen>]\
 [SINGLE\-VALUE]\
 [COLLECTIVE]\
 [NO\-USER\-MODIFICATION]\
 [USAGE\ <attributeUsage>]\ )"
151
.RS
152
Specify an attribute type using the LDAPv3 syntax defined in RFC 2252.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
153
154
155
The slapd parser extends the RFC 2252 definition by allowing string
forms as well as numeric OIDs to be used for the attribute OID and
attribute syntax OID.
156
(See the
157
.B objectidentifier
158
description.) 
159
.RE
160
.TP
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
.B authz-policy <policy>
Used to specify which rules to use for Proxy Authorization.  Proxy
authorization allows a client to authenticate to the server using one
user's credentials, but specify a different identity to use for authorization
and access control purposes. It essentially allows user A to login as user
B, using user A's password.
The
.B none
flag disables proxy authorization. This is the default setting.
The
.B from
flag will use rules in the
.I authzFrom
attribute of the authorization DN.
The
.B to
flag will use rules in the
.I authzTo
attribute of the authentication DN.
The
.B any
flag, an alias for the deprecated value of
.BR both ,
will allow any of the above, whatever succeeds first (checked in
.BR to ,
.B from
sequence.
The
.B all
flag requires both authorizations to succeed.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
191
192
193
.LP
.RS
The rules are mechanisms to specify which identities are allowed 
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
to perform proxy authorization.
The
.I authzFrom
attribute in an entry specifies which other users
are allowed to proxy login to this entry. The
.I authzTo
attribute in
an entry specifies which other users this user can authorize as.  Use of
.I authzTo
rules can be easily
abused if users are allowed to write arbitrary values to this attribute.
In general the
.I authzTo
attribute must be protected with ACLs such that
only privileged users can modify it.
The value of
.I authzFrom
and
.I authzTo
describes an 
.B identity 
or a set of identities; it can take three forms:
.RS
.TP
.B ldap:///<base>??[<scope>]?<filter>
.RE
.RS
.B dn[.<dnstyle>]:<pattern>
.RE
.RS
.B u[<mech>[<realm>]]:<pattern>
.RE
.RS
Pierangelo Masarati's avatar
Pierangelo Masarati committed
227
228
229
.B group[/objectClass[/attributeType]]:<pattern>
.RE
.RS
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
.B <pattern>
.RE
.RS

.B <dnstyle>:={exact|onelevel|children|subtree|regex}

.RE
The first form is a valid LDAP
.B URI
where the 
.IR <host>:<port> ,
the
.I <attrs>
and the
.I <extensions>
portions must be absent, so that the search occurs locally on either
.I authzFrom
or 
.IR authzTo .
The second form is a 
.BR DN ,
with the optional style modifiers
.IR exact ,
.IR onelevel ,
.IR children ,
and
.I subtree
for exact, onelevel, children and subtree matches, which cause 
.I <pattern>
to be normalized according to the DN normalization rules, or the special
.I regex
261
style, which causes the
262
.I <pattern>
263
264
265
266
267
to be treated as a POSIX (''extended'') regular expression, as
discussed in
.BR regex (7)
and/or
.BR re_format (7).
Pierangelo Masarati's avatar
Pierangelo Masarati committed
268
269
270
A pattern of
.I *
means any non-anonymous DN.
271
272
273
274
275
276
277
278
279
280
281
282
283
The third form is a SASL
.BR id ,
with the optional fields
.I <mech>
and
.I <realm>
that allow to specify a SASL
.BR mechanism ,
and eventually a SASL
.BR realm ,
for those mechanisms that support one.
The need to allow the specification of a mechanism is still debated, 
and users are strongly discouraged to rely on this possibility.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
284
285
286
287
288
289
290
291
292
293
294
295
The fourth form is a group specification, consisting of the keyword
.BR group ,
optionally followed by the specification of the group
.B objectClass
and member
.BR attributeType .
The group with DN
.B <pattern>
is searched with base scope, and in case of match, the values of the
member
.B attributeType
are searched for the asserted DN.
296
297
298
299
300
301
302
303
304
305
306
307
308
For backwards compatibility, if no identity type is provided, i.e. only
.B <pattern>
is present, an
.I exact DN
is assumed; as a consequence, 
.B <pattern>
is subjected to DN normalization.
Since the interpretation of
.I authzFrom
and
.I authzTo
can impact security, users are strongly encouraged 
to explicitly set the type of identity specification that is being used.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
309
310
311
312
313
314
315
A subset of these rules can be used as third arg in the 
.B authz-regexp
statement (see below); significantly, the 
.I URI
and the
.I dn.exact:<dn> 
forms.
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
.RE
.TP
.B authz-regexp <match> <replace>
Used by the authentication framework to convert simple user names,
such as provided by SASL subsystem, to an LDAP DN used for
authorization purposes.  Note that the resultant DN need not refer
to an existing entry to be considered valid.  When an authorization
request is received from the SASL subsystem, the SASL 
.BR USERNAME ,
.BR REALM , 
and
.B MECHANISM
are taken, when available, and combined into a name of the form
.RS
.RS
.TP
Pierangelo Masarati's avatar
typo    
Pierangelo Masarati committed
332
.B UID=<username>[[,CN=<realm>],CN=<mechanism>],CN=auth
333
334
335
336

.RE
This name is then compared against the
.B match
337
338
POSIX (''extended'') regular expression, and if the match is successful,
the name is replaced with the
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
.B replace
string.  If there are wildcard strings in the 
.B match
regular expression that are enclosed in parenthesis, e.g. 
.RS
.TP
.B UID=([^,]*),CN=.*

.RE
then the portion of the name that matched the wildcard will be stored
in the numbered placeholder variable $1. If there are other wildcard strings
in parenthesis, the matching strings will be in $2, $3, etc. up to $9. The 
placeholders can then be used in the 
.B replace
string, e.g. 
.RS
.TP
.B UID=$1,OU=Accounts,DC=example,DC=com 

.RE
359
360
361
The replaced name can be either a DN, i.e. a string prefixed by "dn:",
or an LDAP URI.
If the latter, the server will use the URI to search its own database(s)
362
363
and, if the search returns exactly one entry, the name is
replaced by the DN of that entry.   The LDAP URI must have no
364
365
hostport, attrs, or extensions components, but the filter is mandatory,
e.g.
366
367
368
369
370
.RS
.TP
.B ldap:///OU=Accounts,DC=example,DC=com??one?(UID=$1)

.RE
371
372
373
The protocol portion of the URI must be strictly
.BR ldap .

374
375
376
377
378
379
380
381
382
383
384
385
Multiple 
.B authz-regexp 
options can be given in the configuration file to allow for multiple matching 
and replacement patterns. The matching patterns are checked in the order they 
appear in the file, stopping at the first successful match.

.\".B Caution:
.\"Because the plus sign + is a character recognized by the regular expression engine,
.\"and it will appear in names that include a REALM, be careful to escape the
.\"plus sign with a backslash \\+ to remove the character's special meaning.
.RE
.TP
386
387
.B concurrency <integer>
Specify a desired level of concurrency.  Provided to the underlying
388
thread system as a hint.  The default is not to provide any hint.
389
390
391
392
393
394
395
396
397
398
.TP
.B conn_max_pending <integer>
Specify the maximum number of pending requests for an anonymous session.
If requests are submitted faster than the server can process them, they
will be queued up to this limit. If the limit is exceeded, the session
is closed. The default is 100.
.TP
.B conn_max_pending_auth <integer>
Specify the maximum number of pending requests for an authenticated session.
The default is 1000.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
399
.TP
400
401
402
403
.B defaultsearchbase <dn>
Specify a default search base to use when client submits a
non-base search request with an empty base DN.
.TP
404
.B disallow <features>
405
406
Specify a set of features (separated by white space) to
disallow (default none).
407
408
.B bind_anon
disables acceptance of anonymous bind requests.
409
410
.B bind_simple
disables simple (bind) authentication.
411
412
413
.B tls_2_anon
disables Start TLS from forcing session to anonymous status (see also
.BR tls_authc ).
414
415
416
.B tls_authc
disables StartTLS if authenticated (see also
.BR tls_2_anon ).
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
.HP
.hy 0
.B ditcontentrule "(\ <oid>\
 [NAME\ <name>]\
 [DESC\ <description>]\
 [OBSOLETE]\
 [AUX\ <oids>]\
 [MUST\ <oids>]\
 [MAY\ <oids>]\
 [NOT\ <oids>]\ )"
.RS
Specify an DIT Content Rule using the LDAPv3 syntax defined in RFC 2252.
The slapd parser extends the RFC 2252 definition by allowing string
forms as well as numeric OIDs to be used for the attribute OID and
attribute syntax OID.
(See the
.B objectidentifier
description.) 
.RE
436
.TP
437
438
439
440
.B gentlehup { on | off }
A SIGHUP signal will only cause a 'gentle' shutdown-attempt:
.B Slapd
will stop listening for new connections, but will not close the
441
442
connections to the current clients.  Future write operations return
unwilling-to-perform, though.  Slapd terminates when all clients
443
444
445
446
447
448
449
450
451
452
453
have closed their connections (if they ever do), or \- as before \-
if it receives a SIGTERM signal.  This can be useful if you wish to
terminate the server and start a new
.B slapd
server
.B with another database,
without disrupting the currently active clients.
The default is off.  You may wish to use
.B idletimeout
along with this option.
.TP
454
455
.B idletimeout <integer>
Specify the number of seconds to wait before forcibly closing
456
an idle client connection.  A idletimeout of 0 disables this
457
458
feature.  The default is 0.
.TP
Kurt Zeilenga's avatar
Kurt Zeilenga committed
459
460
461
.B include <filename>
Read additional configuration information from the given file before
continuing with the next line of the current file.
Howard Chu's avatar
Howard Chu committed
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
.TP
.B index_substr_if_minlen <integer>
Specify the minimum length for subinitial and subfinal indices. An
attribute value must have at least this many characters in order to be
processed by the indexing functions. The default is 2.
.TP
.B index_substr_if_maxlen <integer>
Specify the maximum length for subinitial and subfinal indices. Only
this many characters of an attribute value will be processed by the
indexing functions; any excess characters are ignored. The default is 4.
.TP
.B index_substr_any_len <integer>
Specify the length used for subany indices. An attribute value must have
at least this many characters in order to be processed. Attribute values
longer than this length will be processed in segments of this length. The
default is 4. The subany index will also be used in subinitial and
subfinal index lookups when the filter string is longer than the
.I index_substr_if_maxlen
value.
.TP
.B index_substr_any_step <integer>
Specify the steps used in subany index lookups. This value sets the offset
for the segments of a filter string that are processed for a subany index
lookup. The default is 2. For example, with the default values, a search
using this filter "cn=*abcdefgh*" would generate index lookups for
"abcd", "cdef", and "efgh".

489
.\"-- NEW_LOGGING option --
490
491
492
493
494
.\".TP
.\".B logfile <filename>
.\"Specify a file for recording debug log messages. By default these messages
.\"only go to stderr and are not recorded anywhere else. Specifying a logfile
.\"copies messages to both stderr and the logfile.
495
.TP
496
497
498
499
500
501
.B localSSF <SSF>
Specifies the Security Strength Factor (SSF) to be given local LDAP sessions,
such as those to the ldapi:// listener.  For a description of SSF values,
see 
.BR sasl-secprops 's
.B minssf
Kurt Zeilenga's avatar
Kurt Zeilenga committed
502
option description.  The default is 71.
503
.TP
504
.B loglevel <integer> [...]
Kurt Zeilenga's avatar
Kurt Zeilenga committed
505
506
507
508
509
510
511
512
513
514
Specify the level at which debugging statements and operation 
statistics should be syslogged (currently logged to the
.BR syslogd (8) 
LOG_LOCAL4 facility).  Log levels are additive, and available levels
are:
.RS
.RS
.PD 0
.TP
.B 1
515
.B (trace)
Kurt Zeilenga's avatar
Kurt Zeilenga committed
516
517
518
trace function calls
.TP
.B 2
519
.B (packet)
Kurt Zeilenga's avatar
Kurt Zeilenga committed
520
521
522
debug packet handling
.TP
.B 4
523
.B (args)
Kurt Zeilenga's avatar
Kurt Zeilenga committed
524
525
526
heavy trace debugging
.TP
.B 8
527
.B (conns)
Kurt Zeilenga's avatar
Kurt Zeilenga committed
528
529
530
connection management
.TP
.B 16
531
.B (BER)
Kurt Zeilenga's avatar
Kurt Zeilenga committed
532
533
534
print out packets sent and received
.TP
.B 32
535
.B (filter)
Kurt Zeilenga's avatar
Kurt Zeilenga committed
536
537
538
search filter processing
.TP
.B 64
539
.B (config)
Kurt Zeilenga's avatar
Kurt Zeilenga committed
540
541
542
configuration file processing
.TP
.B 128
543
.B (ACL)
Kurt Zeilenga's avatar
Kurt Zeilenga committed
544
545
546
access control list processing
.TP
.B 256
547
.B (stats)
Kurt Zeilenga's avatar
Kurt Zeilenga committed
548
549
550
stats log connections/operations/results
.TP
.B 512
551
.B (stats2)
Kurt Zeilenga's avatar
Kurt Zeilenga committed
552
553
554
stats log entries sent
.TP
.B 1024
555
.B (shell)
Kurt Zeilenga's avatar
Kurt Zeilenga committed
556
557
558
print communication with shell backends
.TP
.B 2048
559
.B (parse)
Kurt Zeilenga's avatar
Kurt Zeilenga committed
560
561
562
entry parsing
.PD
.RE
563
564
The desired log level can be input as a single integer that combines 
the (ORed) desired levels, as a list of integers (that are ORed internally),
565
566
567
568
569
570
571
572
573
574
575
576
or as a list of the names that are shown between brackets, such that
.LP
.nf
    loglevel 129
    loglevel 128 1
    loglevel acl trace
.fi
.LP
are equivalent.
The keyword 
.B any
can be used as a shortcut to enable logging at all levels (equivalent to -1).
Kurt Zeilenga's avatar
Kurt Zeilenga committed
577
.RE
578
579
580
581
582
583
584
585
586
587
588
589
590
.TP
.B moduleload <filename>
Specify the name of a dynamically loadable module to load. The filename
may be an absolute path name or a simple filename. Non-absolute names
are searched for in the directories specified by the
.B modulepath
option. This option and the
.B modulepath
option are only usable if slapd was compiled with --enable-modules.
.TP
.B modulepath <pathspec>
Specify a list of directories to search for loadable modules. Typically
the path is colon-separated but this depends on the operating system.
591
.HP
592
593
594
595
596
597
598
599
.hy 0
.B objectclass "(\ <oid>\
 [NAME\ <name>]\
 [DESC\ <description]\
 [OBSOLETE]\
 [SUP\ <oids>]\
 [{ ABSTRACT | STRUCTURAL | AUXILIARY }]\
 [MUST\ <oids>] [MAY\ <oids>] )"
600
.RS
601
Specify an objectclass using the LDAPv3 syntax defined in RFC 2252.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
602
603
604
The slapd parser extends the RFC 2252 definition by allowing string
forms as well as numeric OIDs to be used for the object class OID.
(See the
605
606
.B
objectidentifier
Kurt Zeilenga's avatar
Kurt Zeilenga committed
607
description.)  Object classes are "STRUCTURAL" by default.
608
.RE
609
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
610
.B objectidentifier <name> "{ <oid> | <name>[:<suffix>] }"
611
612
613
614
Define a string name that equates to the given OID. The string can be used
in place of the numeric OID in objectclass and attribute definitions. The
name can also be used with a suffix of the form ":xx" in which case the
value "oid.xx" will be used.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
615
.TP
616
617
618
.B password-hash <hash> [<hash>...]
This option configures one or more hashes to be used in generation of user
passwords stored in the userPassword attribute during processing of
Kurt Zeilenga's avatar
Kurt Zeilenga committed
619
LDAP Password Modify Extended Operations (RFC 3062).
620
The <hash> must be one of
621
622
623
624
.BR {SSHA} ,
.BR {SHA} ,
.BR {SMD5} ,
.BR {MD5} ,
625
.BR {CRYPT} ,
626
and
627
.BR {CLEARTEXT} .
628
629
The default is
.BR {SSHA} .
630

631
632
633
634
.B {SHA}
and
.B {SSHA}
use the SHA-1 algorithm (FIPS 160-1), the latter with a seed.
635

636
637
638
639
.B {MD5}
and
.B {SMD5}
use the MD5 algorithm (RFC 1321), the latter with a seed.
640

641
642
643
.B {CRYPT}
uses the
.BR crypt (3).
644

645
646
647
.B {CLEARTEXT}
indicates that the new password should be
added to userPassword as clear text.
648

649
Note that this option does not alter the normal user applications
650
handling of userPassword during LDAP Add, Modify, or other LDAP operations.
651
.TP
652
.B password\-crypt\-salt\-format <format>
653
654
Specify the format of the salt passed to
.BR crypt (3)
655
656
657
658
when generating {CRYPT} passwords (see
.BR password\-hash )
during processing of LDAP Password Modify Extended Operations (RFC 3062).

659
660
661
This string needs to be in
.BR sprintf (3)
format and may include one (and only one) %s conversion.
662
This conversion will be substituted with a string of random
663
664
665
666
667
668
characters from [A\-Za\-z0\-9./].  For example, "%.2s"
provides a two character salt and "$1$%.8s" tells some
versions of crypt(3) to use an MD5 algorithm and provides
8 random characters of salt.  The default is "%s", which
provides 31 characters of salt.
.TP
Kurt Zeilenga's avatar
Kurt Zeilenga committed
669
670
671
672
673
674
675
.B pidfile <filename>
The ( absolute ) name of a file that will hold the 
.B slapd
server's process ID ( see
.BR getpid (2)
) if started without the debugging command line option.
.TP
Kurt Zeilenga's avatar
Kurt Zeilenga committed
676
677
678
679
.B referral <url>
Specify the referral to pass back when
.BR slapd (8)
cannot find a local database to handle a request.
680
If specified multiple times, each url is provided.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
681
.TP
682
683
684
685
686
687
688
689
690
691
692
693
694
.B replica-argsfile
The ( absolute ) name of a file that will hold the 
.B slurpd
server's command line options
if started without the debugging command line option.
.TP
.B replica-pidfile
The ( absolute ) name of a file that will hold the 
.B slurpd
server's process ID ( see
.BR getpid (2)
) if started without the debugging command line option.
.TP
695
696
697
698
699
.B replicationinterval
The number of seconds 
.B slurpd 
waits before checking the replogfile for changes.
.TP
700
.B require <conditions>
701
702
Specify a set of conditions (separated by white space) to
require (default none).
703
704
705
706
707
708
709
710
711
712
713
The directive may be specified globally and/or per-database.
.B bind
requires bind operation prior to directory operations.
.B LDAPv3
requires session to be using LDAP version 3.
.B authc
requires authentication prior to directory operations.
.B SASL
requires SASL authentication prior to directory operations.
.B strong
requires strong authentication prior to directory operations.
714
715
The strong keyword allows protected "simple" authentication
as well as SASL authentication.
716
717
718
719
.B none
may be used to require no conditions (useful for clearly globally
set conditions within a particular database).
.TP
720
.B reverse-lookup on | off
721
722
Enable/disable client name unverified reverse lookup (default is 
.BR off 
723
724
if compiled with --enable-rlookups).
.TP
Kurt Zeilenga's avatar
Kurt Zeilenga committed
725
.B rootDSE <file>
726
727
728
729
Specify the name of an LDIF(5) file containing user defined attributes
for the root DSE.  These attributes are returned in addition to the
attributes normally produced by slapd.
.TP
Kurt Zeilenga's avatar
Kurt Zeilenga committed
730
731
732
.B sasl-host <fqdn>
Used to specify the fully qualified domain name used for SASL processing.
.TP
Kurt Zeilenga's avatar
Kurt Zeilenga committed
733
734
.B sasl-realm <realm>
Specify SASL realm.  Default is empty.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
735
.TP
Kurt Zeilenga's avatar
Kurt Zeilenga committed
736
737
738
739
.B sasl-secprops <properties>
Used to specify Cyrus SASL security properties.
The
.B none
740
flag (without any other properties) causes the flag properties
Kurt Zeilenga's avatar
Kurt Zeilenga committed
741
742
743
744
745
746
747
748
749
750
751
default, "noanonymous,noplain", to be cleared.
The
.B noplain
flag disables mechanisms susceptible to simple passive attacks.
The
.B noactive
flag disables mechanisms susceptible to active attacks.
The
.B nodict
flag disables mechanisms susceptible to passive dictionary attacks.
The
Kurt Zeilenga's avatar
Kurt Zeilenga committed
752
.B noanonymous
Kurt Zeilenga's avatar
Kurt Zeilenga committed
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
flag disables mechanisms which support anonymous login.
The
.B forwardsec
flag require forward secrecy between sessions.
The
.B passcred
require mechanisms which pass client credentials (and allow
mechanisms which can pass credentials to do so).
The
.B minssf=<factor> 
property specifies the minimum acceptable
.I security strength factor
as an integer approximate to effective key length used for
encryption.  0 (zero) implies no protection, 1 implies integrity
protection only, 56 allows DES or other weak ciphers, 112
allows triple DES and other strong ciphers, 128 allows RC4,
Blowfish and other modern strong ciphers.  The default is 0.
The
.B maxssf=<factor> 
property specifies the maximum acceptable
.I security strength factor
as an integer (see minssf description).  The default is INT_MAX.
The
Kurt Zeilenga's avatar
Kurt Zeilenga committed
776
.B maxbufsize=<size> 
Kurt Zeilenga's avatar
Kurt Zeilenga committed
777
778
779
property specifies the maximum security layer receive buffer
size allowed.  0 disables security layers.  The default is 65536.
.TP
780
781
782
783
.B schemadn <dn>
Specify the distinguished name for the subschema subentry that
controls the entries on this server.  The default is "cn=Subschema".
.TP
784
.B security <factors>
Kurt Zeilenga's avatar
Kurt Zeilenga committed
785
786
787
788
789
Specify a set of security strength factors (separated by white space)
to require (see
.BR sasl-secprops 's
.B minssf
option for a description of security strength factors).
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
The directive may be specified globally and/or per-database.
.B ssf=<n>
specifies the overall security strength factor.
.B transport=<n>
specifies the transport security strength factor.
.B tls=<n>
specifies the TLS security strength factor.
.B sasl=<n>
specifies the SASL security strength factor.
.B update_ssf=<n>
specifies the overall security strength factor to require for
directory updates.
.B update_transport=<n>
specifies the transport security strength factor to require for
directory updates.
.B update_tls=<n>
specifies the TLS security strength factor to require for
directory updates.
.B update_sasl=<n>
specifies the SASL security strength factor to require for
directory updates.
811
812
813
814
.B simple_bind=<n>
specifies the security strength factor required for
.I simple
username/password authentication.
815
816
817
818
819
Note that the
.B transport
factor is measure of security provided by the underlying transport,
e.g. ldapi:// (and eventually IPSEC).  It is not normally used.
.TP
820
.B sizelimit {<integer>|unlimited}
821
.TP
822
.B sizelimit size[.{soft|hard|unchecked}]=<integer> [...]
Kurt Zeilenga's avatar
Kurt Zeilenga committed
823
824
Specify the maximum number of entries to return from a search operation.
The default size limit is 500.
825
826
827
Use
.B unlimited
to specify no limits.
828
The second format allows a fine grain setting of the size limits.
829
Extra args can be added on the same line.
830
831
832
See
.BR limits
for an explanation of the different flags.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
833
.TP
Kurt Zeilenga's avatar
Kurt Zeilenga committed
834
.B sockbuf_max_incoming <integer>
835
836
837
838
839
840
Specify the maximum incoming LDAP PDU size for anonymous sessions.
The default is 262143.
.TP
.B sockbuf_max_incoming_auth <integer>
Specify the maximum incoming LDAP PDU size for authenticated sessions.
The default is 4194303.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
841
.TP
842
843
.B threads <integer>
Specify the maximum size of the primary thread pool.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
844
The default is 16.
845
.TP
846
.B timelimit {<integer>|unlimited}
847
.TP
848
.B timelimit time[.{soft|hard}]=<integer> [...]
Kurt Zeilenga's avatar
Kurt Zeilenga committed
849
850
851
Specify the maximum number of seconds (in real time)
.B slapd
will spend answering a search request.  The default time limit is 3600.
852
853
854
Use
.B unlimited
to specify no limits.
855
The second format allows a fine grain setting of the time limits.
856
Extra args can be added on the same line.
857
858
859
See
.BR limits
for an explanation of the different flags.
860
861
862
.TP
.B ucdata-path <path>
Specify the path to the directory containing the Unicode character
Kurt Zeilenga's avatar
Kurt Zeilenga committed
863
tables. The default path is DATADIR/ucdata.
864
865
866
.SH TLS OPTIONS
If
.B slapd
867
is built with support for Transport Layer Security, there are more options
868
869
870
871
872
873
874
875
876
877
878
879
you can specify.
.TP
.B TLSCipherSuite <cipher-suite-spec>
Permits configuring what ciphers will be accepted and the preference order.
<cipher-suite-spec> should be a cipher specification for OpenSSL.  Example:

TLSCipherSuite HIGH:MEDIUM:+SSLv2

To check what ciphers a given spec selects, use:

openssl ciphers -v <cipher-suite-spec>
.TP
880
881
882
883
884
885
.B TLSCACertificateFile <filename>
Specifies the file that contains certificates for all of the Certificate
Authorities that
.B slapd
will recognize.
.TP
886
887
888
889
890
.B TLSCACertificatePath <path>
Specifies the path of a directory that contains Certificate Authority
certificates in separate individual files. Usually only one of this
or the TLSCACertificateFile is used.
.TP
891
892
893
894
895
896
897
898
899
900
901
902
.B TLSCertificateFile <filename>
Specifies the file that contains the
.B slapd
server certificate.
.TP
.B TLSCertificateKeyFile <filename>
Specifies the file that contains the
.B slapd
server private key that matches the certificate stored in the
.B TLSCertificateFile
file.  Currently, the private key must not be protected with a password, so
it is of critical importance that it is protected carefully. 
Kurt Zeilenga's avatar
Kurt Zeilenga committed
903
904
905
906
907
.TP
.B TLSRandFile <filename>
Specifies the file to obtain random bits from when /dev/[u]random
is not available.  Generally set to the name of the EGD/PRNGD socket.
The environment variable RANDFILE can also be used to specify the filename.
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
.TP
.B TLSVerifyClient <level>
Specifies what checks to perform on client certificates in an
incoming TLS session, if any.
The
.B <level>
can be specified as one of the following keywords:
.RS
.TP
.B never
This is the default.
.B slapd
will not ask the client for a certificate.
.TP
.B allow
The client certificate is requested.  If no certificate is provided,
the session proceeds normally.  If a bad certificate is provided,
it will be ignored and the session proceeds normally.
.TP
.B try
The client certificate is requested.  If no certificate is provided,
the session proceeds normally.  If a bad certificate is provided,
the session is immediately terminated.
.TP
.B demand | hard | true
These keywords are all equivalent, for compatibility reasons.
The client certificate is requested.  If no certificate is provided,
or a bad certificate is provided, the session is immediately terminated.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
936

937
938
939
940
941
942
Note that a valid client certificate is required in order to use the
SASL EXTERNAL authentication mechanism with a TLS session.  As such,
a non-default
.B TLSVerifyClient
setting must be chosen to enable SASL EXTERNAL authentication.
.RE
943
944
945
.TP
.B TLSCRLCheck <level>
Specifies if the Certificate Revocation List (CRL) of the CA should be 
Kurt Zeilenga's avatar
Kurt Zeilenga committed
946
used to verify if the client certificates have not been revoked. This
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
requires
.B TLSCACertificatePath
parameter to be set.
.B <level>
can be specified as one of the following keywords:
.RS
.TP
.B none
No CRL checks are performed
.TP
.B peer
Check the CRL of the peer certificate
.TP
.B all
Check the CRL for a whole certificate chain
.RE
Kurt Zeilenga's avatar
Kurt Zeilenga committed
963
964
.SH GENERAL BACKEND OPTIONS
Options in this section only apply to the configuration file section
965
966
967
968
969
970
for the specified backend.  They are supported by every
type of backend.
.TP
.B backend <databasetype>
Mark the beginning of a backend definition. <databasetype>
should be one of
Pierangelo Masarati's avatar
Pierangelo Masarati committed
971
.BR bdb ,
Kurt Zeilenga's avatar
Kurt Zeilenga committed
972
.BR config ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
973
.BR dnssrv ,
Kurt Zeilenga's avatar
Kurt Zeilenga committed
974
.BR hdb ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
975
976
.BR ldap ,
.BR ldbm ,
Kurt Zeilenga's avatar
Kurt Zeilenga committed
977
.BR ldif ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
978
979
980
981
982
983
984
.BR meta ,
.BR monitor ,
.BR null ,
.BR passwd ,
.BR perl ,
.BR relay ,
.BR shell ,
985
or
Kurt Zeilenga's avatar
Kurt Zeilenga committed
986
.BR sql ,
987
988
989
990
991
depending on which backend will serve the database.

.SH GENERAL DATABASE OPTIONS
Options in this section only apply to the configuration file section
for the database in which they are defined.  They are supported by every
992
993
994
995
996
type of backend.  Note that the
.B database
and at least one
.B suffix
option are mandatory for each database.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
997
998
999
1000
.TP
.B database <databasetype>
Mark the beginning of a new database instance definition. <databasetype>
should be one of
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1001
.BR bdb ,
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1002
.BR config ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1003
.BR dnssrv ,
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1004
.BR hdb ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1005
1006
.BR ldap ,
.BR ldbm ,
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1007
.BR ldif ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1008
1009
1010
1011
1012
1013
1014
.BR meta ,
.BR monitor ,
.BR null ,
.BR passwd ,
.BR perl ,
.BR relay ,
.BR shell ,
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1015
or
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1016
.BR sql ,
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1017
1018
1019
1020
1021
1022
1023
depending on which backend will serve the database.
.TP
.B lastmod on | off
Controls whether
.B slapd
will automatically maintain the 
modifiersName, modifyTimestamp, creatorsName, and 
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1024
createTimestamp attributes for entries.  By default, lastmod is on.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1025
.TP
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
.B limits <who> <limit> [<limit> [...]]
Specify time and size limits based on who initiated an operation.
The argument
.B who
can be any of
.RS
.RS
.TP
anonymous | users | [dn[.<style>]=]<pattern> | group[/oc[/at]]=<pattern>

.RE
with
.RS
.TP
<style> ::= exact | base | onelevel | subtree | children | regex | anonymous

.RE
The term
.B anonymous
matches all unauthenticated clients.
The term
.B users
matches all authenticated clients;
otherwise an
.B exact
dn pattern is assumed unless otherwise specified by qualifying 
the (optional) key string
.B dn
with 
.B exact
or
.B base
(which are synonyms), to require an exact match; with
.BR onelevel , 
to require exactly one level of depth match; with
.BR subtree ,
to allow any level of depth match, including the exact match; with
.BR children ,
to allow any level of depth match, not including the exact match;
.BR regex
1066
1067
explicitly requires the (default) match based on POSIX (''extended'')
regular expression pattern.
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
Finally,
.B anonymous
matches unbound operations; the 
.B pattern
field is ignored.
The same behavior is obtained by using the 
.B anonymous
form of the
.B who
clause.
The term
.BR group ,
with the optional objectClass
.B oc
and attributeType
.B at
fields, followed by
.BR pattern ,
sets the limits for any DN listed in the values of the
.B at
attribute (default
.BR member )
of the 
.B oc
group objectClass (default
.BR groupOfNames )
whose DN exactly matches
.BR pattern .

The currently supported limits are 
.B size
and 
.BR time .

The syntax for time limits is 
.BR time[.{soft|hard}]=<integer> ,
where 
1105
.I integer
1106
1107
1108
1109
1110
is the number of seconds slapd will spend answering a search request.
If no time limit is explicitly requested by the client, the 
.BR soft
limit is used; if the requested time limit exceeds the
.BR hard
1111
1112
1113
1114
.\"limit, an
.\".I "Administrative limit exceeded"
.\"error is returned.
limit, the value of the limit is used instead.
1115
1116
If the
.BR hard
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1117
limit is set to the keyword 
1118
.IR soft ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1119
the soft limit is used in either case; if it is set to the keyword 
1120
.IR unlimited , 
1121
1122
1123
1124
no hard limit is enforced.
Explicit requests for time limits smaller or equal to the
.BR hard 
limit are honored.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1125
If no limit specifier is set, the value is assigned to the 
1126
1127
1128
.BR soft 
limit, and the
.BR hard
1129
1130
1131
limit is set to
.IR soft ,
to preserve the original behavior.
1132
1133
1134
1135

The syntax for size limits is
.BR size[.{soft|hard|unchecked}]=<integer> ,
where
1136
.I integer
1137
1138
1139
1140
1141
1142
is the maximum number of entries slapd will return answering a search 
request.
If no size limit is explicitly requested by the client, the
.BR soft
limit is used; if the requested size limit exceeds the
.BR hard
1143
1144
1145
1146
.\"limit, an 
.\".I "Administrative limit exceeded"
.\"error is returned.
limit, the value of the limit is used instead.
1147
1148
If the 
.BR hard
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1149
limit is set to the keyword 
1150
.IR soft , 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1151
the soft limit is used in either case; if it is set to the keyword
1152
.IR unlimited , 
1153
1154
1155
1156
1157
1158
no hard limit is enforced.
Explicit requests for size limits smaller or equal to the
.BR hard
limit are honored.
The
.BR unchecked
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1159
specifier sets a limit on the number of candidates a search request is allowed
1160
to examine.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1161
The rationale behind it is that searches for non-properly indexed
1162
1163
1164
1165
1166
attributes may result in large sets of candidates, which must be 
examined by
.BR slapd (8)
to determine whether they match the search filter or not.
The
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1167
.B unchecked
1168
1169
limit provides a means to drop such operations before they are even 
started.
1170
1171
1172
If the selected candidates exceed the 
.BR unchecked
limit, the search will abort with 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1173
1174
.IR "Unwilling to perform" .
If it is set to the keyword 
1175
.IR unlimited , 
1176
1177
1178
1179
1180
no limit is applied (the default).
If it is set to
.IR disable ,
the search is not even performed; this can be used to disallow searches
for a specific set of users.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1181
If no limit specifier is set, the value is assigned to the
1182
1183
1184
.BR soft 
limit, and the
.BR hard
1185
1186
1187
limit is set to
.IR soft ,
to preserve the original behavior.
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201

In case of no match, the global limits are used.
The default values are the same of
.B sizelimit
and
.BR timelimit ;
no limit is set on 
.BR unchecked .

If 
.B pagedResults
control is requested, the 
.B hard
size limit is used by default, because the request of a specific page size
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1202
is considered an explicit request for a limitation on the number
1203
1204
1205
1206
of entries to be returned.
However, the size limit applies to the total count of entries returned within
the search, and not to a single page.
Additional size limits may be enforced; the syntax is
1207
.BR size.pr={<integer>|noEstimate|unlimited} ,
1208
where
1209
.I integer
1210
1211
is the max page size if no explicit limit is set; the keyword
.I noEstimate
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1212
inhibits the server from returning an estimate of the total number
1213
1214
1215
1216
of entries that might be returned
(note: the current implementation does not return any estimate).
The keyword
.I unlimited
1217
1218
indicates that no limit is applied to the pagedResults control page size.
The syntax
1219
.B size.prtotal={<integer>|unlimited|disabled}
1220
1221
1222
1223
1224
1225
allows to set a limit on the total number of entries that a pagedResults
control allows to return.
By default it is set to the 
.B hard
limit.
When set, 
1226
.I integer
1227
1228
1229
is the max number of entries that the whole search with pagedResults control
can return.
Use 
1230
1231
1232
1233
.I unlimited
to allow unlimited number of entries to be returned, e.g. to allow
the use of the pagedResults control as a means to circumvent size 
limitations on regular searches; the keyword
1234
1235
.I disabled
disables the control, i.e. no paged results can be returned.
1236
1237
1238
1239
1240
1241
1242
1243
Note that the total number of entries returned when the pagedResults control 
is requested cannot exceed the 
.B hard 
size limit of regular searches unless extended by the
.B prtotal
switch.
.RE
.TP
1244
1245
.B maxderefdepth <depth>
Specifies the maximum number of aliases to dereference when trying to
1246
resolve an entry, used to avoid infinite alias loops. The default is 1.
1247
.TP
Howard Chu's avatar
Howard Chu committed
1248
1249
1250
1251
1252
1253
1254
1255
.B overlay <overlay-name>
Add the specified overlay to this database. An overlay is a piece of
code that intercepts database operations in order to extend or change
them. Overlays are pushed onto
a stack over the database, and so they will execute in the reverse
of the order in which they were configured and the database itself
will receive control last of all.
.TP
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1256
1257
1258
1259
.B readonly on | off
This option puts the database into "read-only" mode.  Any attempts to 
modify the database will return an "unwilling to perform" error.  By
default, readonly is off.
1260
.HP
1261
.hy 0
1262
1263
.B replica uri=ldap[s]://<hostname>[:port]|host=<hostname>[:port] 
.B [starttls=yes|critical]
1264
.B [suffix=<suffix> [...]]
1265
.B bindmethod=simple|sasl [binddn=<simple DN>] [credentials=<simple password>]
Howard Chu's avatar
Howard Chu committed
1266
1267
.B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>]
.B [authcId=<authentication ID>] [authzId=<authorization ID>]
1268
.B [attr[!]=<attr list>]
1269
.RS
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1270
Specify a replication site for this database.  Refer to the "OpenLDAP 
1271
Administrator's Guide" for detailed information on setting up a replicated
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1272
.B slapd
1273
1274
1275
directory service. Zero or more
.B suffix
instances can be used to select the subtrees that will be replicated
1276
1277
1278
1279
1280
1281
1282
1283
(defaults to all the database). 
.B host
is deprecated in favor of the
.B uri
option.
.B uri
allows the replica LDAP server to be specified as an LDAP URI. 
A
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
.B bindmethod
of
.B simple
requires the options
.B binddn 
and
.B credentials  
and should only be used when adequate security services 
(e.g TLS or IPSEC) are in place. A
.B bindmethod 
of
.B sasl 
requires the option
.B saslmech. 
Howard Chu's avatar
Howard Chu committed
1298
1299
1300
1301
1302
1303
1304
Specific security properties (as with the
.B sasl-secprops
keyword above) for a SASL bind can be set with the
.B secprops
option. A non-default SASL realm can be set with the
.B realm
option.
1305
1306
1307
1308
If the 
.B mechanism
will use Kerberos, a kerberos instance should be given in 
.B authcId.
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
An
.B attr list
can be given after the 
.B attr
keyword to allow the selective replication of the listed attributes only;
if the optional 
.B !
mark is used, the list is considered exclusive, i.e. the listed attributes
are not replicated.
If an objectClass is listed, all the related attributes
are (are not) replicated.
1320
.RE
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1321
1322
1323
1324
1325
1326
1327
1328
1329
.TP
.B replogfile <filename>
Specify the name of the replication log file to log changes to.  
The replication log is typically written by
.BR slapd (8)
and read by
.BR slurpd (8).
See
.BR slapd.replog (5)
1330
1331
1332
for more information.  The specified file should be located
in a directory with limited read/write/execute access as the replication
logs may contain sensitive information.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1333
.TP
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
.B restrict <oplist>
Specify a whitespace separated list of operations that are restricted.
If defined inside a database specification, restrictions apply only
to that database, otherwise they are global.
Operations can be any of 
.BR add ,
.BR bind ,
.BR compare ,
.BR delete ,
.BR extended[=<OID>] ,
.BR modify ,
.BR rename ,
.BR search ,
or the special pseudo-operations
.B read
and
.BR write ,
which respectively summarize read and write operations.
The use of 
.I restrict write
is equivalent to 
.I readonly on
(see above).
The 
.B extended
keyword allows to indicate the OID of the specific operation
to be restricted.
.TP
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1362
.B rootdn <dn>
1363
Specify the distinguished name that is not subject to access control 
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1364
or administrative limit restrictions for operations on this database.
1365
This DN may or may not be associated with an entry.  An empty root
1366
1367
DN (the default) specifies no root access is to be granted.  It is
recommended that the rootdn only be specified when needed (such as
1368
1369
1370
1371
when initially populating a database).  If the rootdn is within
a namingContext (suffix) of the database, a simple bind password
may also be provided using the
.B rootpw
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1372
directive. Note that the rootdn is always needed when using syncrepl.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1373
1374
.TP
.B rootpw <password>
1375
1376
1377
Specify a password (or hash of the password) for the rootdn.  The
password can only be set if the rootdn is within the namingContext
(suffix) of the database.
1378
This option accepts all RFC 2307 userPassword formats known to
1379
1380
the server (see 
.B password-hash
1381
description) as well as cleartext.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1382
1383
.BR slappasswd (8) 
may be used to generate a hash of a password.  Cleartext
1384
1385
and \fB{CRYPT}\fP passwords are not recommended.  If empty
(the default), authentication of the root DN is by other means
1386
(e.g. SASL).  Use of SASL is encouraged.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1387
1388
1389
1390
1391
.TP
.B suffix <dn suffix>
Specify the DN suffix of queries that will be passed to this 
backend database.  Multiple suffix lines can be given and at least one is 
required for each database definition.
1392
1393
If the suffix of one database is "inside" that of another, the database
with the inner suffix must come first in the configuration file.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
.TP
.B subordinate [advertise]
Specify that the current backend database is a subordinate of another
backend database. A subordinate  database may have only one suffix. This
option may be used to glue multiple databases into a single namingContext.
If the suffix of the current database is within the namingContext of a
superior database, searches against the superior database will be
propagated to the subordinate as well. All of the databases
associated with a single namingContext should have identical rootdns.
Behavior of other LDAP operations is unaffected by this setting. In
particular, it is not possible to use moddn to move an entry from
one subordinate to another subordinate within the namingContext.

If the optional \fBadvertise\fP flag is supplied, the naming context of
this database is advertised in the root DSE. The default is to hide this
database context, so that only the superior context is visible.

If the slap tools
.BR slapcat (8),
.BR slapadd (8),
or
.BR slapindex (8)
are used on the superior database, any glued subordinates that support
these tools are opened as well.

Databases that are glued together should usually be configured with the
same indices (assuming they support indexing), even for attributes that
only exist in some of these databases. In general, all of the glued
databases should be configured as similarly as possible, since the intent
is to provide the appearance of a single directory.
1424
.HP
1425
.hy 0
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
1426
.B syncrepl rid=<replica ID>
1427
.B provider=ldap[s]://<hostname>[:port]
1428
1429
.B [type=refreshOnly|refreshAndPersist]
.B [interval=dd:hh:mm:ss]
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
1430
.B [retry=[<retry interval> <# of retries>]+]
1431
1432
.B [searchbase=<base DN>]
.B [filter=<filter str>]
1433
.B [scope=sub|one|base]
1434
.B [attrs=<attr list>]
1435
1436
1437
.B [attrsonly]
.B [sizelimit=<limit>]
.B [timelimit=<limit>]
1438
.B [schemachecking=on|off]
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1439
.B [starttls=yes|critical]
1440
1441
1442
1443
1444
1445
1446
1447
.B [bindmethod=simple|sasl]
.B [binddn=<dn>]
.B [saslmech=<mech>]
.B [authcid=<identity>]
.B [authzid=<identity>]
.B [credentials=<passwd>]
.B [realm=<realm>]
.B [secprops=<properties>]
1448
.RS
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
Specify the current database as a replica which is kept up-to-date with the 
master content by establishing the current
.BR slapd (8)
as a replication consumer site running a
.B syncrepl
replication engine.
The replica content is kept synchronized to the master content using
the LDAP Content Synchronization protocol. Refer to the
"OpenLDAP Administrator's Guide" for detailed information on
setting up a replicated
.B slapd
directory service using the 
.B syncrepl
replication engine.
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
1463
.B rid
1464
1465
identifies the current
.B syncrepl
1466
directive within the replication consumer site.
1467
It is a non-negative integer having no more than three digits.
1468
.B provider
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
specifies the replication provider site containing the master content
as an LDAP URI. If <port> is not given, the standard LDAP port number
(389 or 636) is used. The content of the
.B syncrepl
replica is defined using a search
specification as its result set. The consumer
.B slapd
will send search requests to the provider
.B slapd
according to the search specification. The search specification includes
.B searchbase, scope, filter, attrs, attrsonly, sizelimit,
and
.B timelimit
parameters as in the normal search specification.
The search specification for the LDAP Content Synchronization operation
has the same value syntax and the same default values as in the
.BR ldapsearch (1)
client search tool.
The LDAP Content Synchronization protocol has two operation types.
In the
.B refreshOnly
operation, the next synchronization search operation
is periodically rescheduled at an interval time (specified by 
.B interval
parameter; 1 day by default)
after each synchronization operation finishes.
In the
.B refreshAndPersist
operation, a synchronization search remains persistent in the provider slapd.
Further updates to the master replica will generate
.B searchResultEntry
to the consumer slapd as the search responses to the persistent
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
1501
1502
1503
1504
1505
synchronization search.
If an error occurs during replication, the consumer will attempt to
reconnect according to the
.B retry
parameter which is a list of the <retry interval> and <# of retries> pairs.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
1506
1507
1508
For example, retry="60 10 300 3" lets the consumer retry every 60 seconds
for the first 10 times and then retry every 300 seconds for the next 3
times before stop retrying. The `+' in <# of retries> means indefinite
Jong Hyuk Choi's avatar
Jong Hyuk Choi committed
1509
number of retries until success.
1510
The schema checking can be enforced at the LDAP Sync
1511
consumer site by turning on the
1512
.B schemachecking
1513
1514
parameter. The default is off.
The
Kurt Zeilenga's avatar
Kurt Zeilenga committed
1515
1516
1517
1518
1519
1520
.B starttls
parameter specifies use of the StartTLS extended operation
to establish a TLS session before Binding to the provider. If the
.B critical
argument is supplied, the session will be aborted if the StartTLS request
fails. Otherwise the syncrepl session continues without TLS.
1521
1522
1523
1524
1525
1526
1527
1528
A
.B bindmethod
of 
.B simple
requires the options 
.B binddn
and 
.B credentials
1529
1530
and should only be used when adequate security services
(e.g. TLS or IPSEC) are in place.
1531
1532
1533
1534
1535
1536
A
.B bindmethod
of
.B sasl
requires the option
.B saslmech.
1537
1538
1539
1540
1541
1542
1543
1544
Depending on the mechanism, an authentication identity and/or
credentials can be specified using
.B authcid
and
.B credentials.
The
.B authzid
parameter may be used to specify an authorization identity.
1545
Specific security properties (as with the
1546
.B sasl-secprops
1547
1548
1549
1550
1551
keyword above) for a SASL bind can be set with the
.B secprops
option. A non default SASL realm can be set with the
.B realm 
option.
1552
1553
1554
1555
.RE
.TP
.B updatedn <dn>
This option is only applicable in a slave