]> git.sur5r.net Git - openldap/blob - doc/man/man5/slapd-config.5
Delete olcInclude stuff
[openldap] / doc / man / man5 / slapd-config.5
1 .TH SLAPD-CONFIG 5 "RELEASEDATE" "OpenLDAP LDVERSION"
2 .\" Copyright 1998-2007 The OpenLDAP Foundation All Rights Reserved.
3 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
4 .\" $OpenLDAP$
5 .SH NAME
6 slapd-config \- configuration backend
7 .SH SYNOPSIS
8 ETCDIR/slapd.d
9 .SH DESCRIPTION
10 The
11 .B config
12 backend manages all of the configuration information for the
13 .BR slapd (8)
14 daemon.  This configuration information is also used by the SLAPD tools
15 .BR slapacl (8),
16 .BR slapadd (8),
17 .BR slapauth (8),
18 .BR slapcat (8),
19 .BR slapdn (8),
20 .BR slapindex (8),
21 and
22 .BR slaptest (8).
23 .LP
24 The
25 .B config
26 backend is backward compatible with the older
27 .BR slapd.conf (5)
28 file but provides the ability to change the configuration dynamically
29 at runtime. If slapd is run with only a
30 .B slapd.conf
31 file dynamic changes will be allowed but they will not persist across
32 a server restart. Dynamic changes are only saved when slapd is running
33 from a
34 .B slapd.d
35 configuration directory.
36 .LP
37
38 Unlike other backends, there can only be one instance of the
39 .B config
40 backend, and most of its structure is predefined. The root of the
41 database is hardcoded to
42 .B "cn=config"
43 and this root entry contains
44 global settings for slapd. Multiple child entries underneath the
45 root entry are used to carry various other settings:
46 .RS
47 .TP
48 .B cn=Module
49 dynamically loaded modules
50 .TP
51 .B cn=Schema
52 schema definitions
53 .TP
54 .B olcBackend=xxx
55 backend-specific settings
56 .TP
57 .B olcDatabase=xxx
58 database-specific settings
59 .RE
60
61 The
62 .B cn=Module
63 entries will only appear in configurations where slapd
64 was built with support for dynamically loaded modules. There can be
65 multiple entries, one for each configured module path. Within each
66 entry there will be values recorded for each module loaded on a
67 given path. These entries have no children.
68
69 The
70 .B cn=Schema
71 entry contains all of the hardcoded schema elements.
72 The children of this entry contain all user-defined schema elements.
73 In schema that were loaded from include files, the child entry will
74 be named after the include file from which the schema was loaded.
75 Typically the first child in this subtree will be
76 .BR cn=core,cn=schema,cn=config .
77
78 .B olcBackend
79 entries are for storing settings specific to a single
80 backend type (and thus global to all database instances of that type).
81 At present there are no backends that implement settings of this
82 nature, so usually there will not be any olcBackend entries.
83
84 .B olcDatabase
85 entries store settings specific to a single database
86 instance. These entries may have
87 .B olcOverlay
88 child entries corresponding
89 to any overlays configured on the database. The olcDatabase and
90 olcOverlay entries may also have miscellaneous child entries for
91 other settings as needed. There are two special database entries
92 that are predefined - one is an entry for the config database itself,
93 and the other is for the "frontend" database. Settings in the
94 frontend database are inherited by the other databases, unless
95 they are explicitly overridden in a specific database.
96 .LP
97 The specific configuration options available are discussed below in the
98 Global Configuration Options, General Backend Options, and General Database
99 Options. Options are set by defining LDAP attributes with specific values.
100 In general the names of the LDAP attributes are the same as the corresponding
101 .B slapd.conf
102 keyword, with an "olc" prefix added on.
103
104 The parser for many of these attributes is the same as used for parsing
105 the slapd.conf keywords. As such, slapd.conf keywords that allow multiple
106 items to be specified on one line, separated by whitespace, will allow
107 multiple items to be specified in one attribute value. However, when
108 reading the attribute via LDAP, the items will be returned as individual
109 attribute values.
110
111 Backend-specific options are discussed in the
112 .B slapd-<backend>(5)
113 manual pages.  Refer to the "OpenLDAP Administrator's Guide" for more
114 details on configuring slapd.
115 .SH GLOBAL CONFIGURATION OPTIONS
116 Options described in this section apply to the server as a whole.
117 Arguments that should be replaced by 
118 actual text are shown in brackets <>.
119
120 These options may only be specified in the
121 .B cn=config
122 entry. This entry must have an objectClass of
123 .BR olcGlobal .
124
125 .TP
126 .B olcAllows: <features>
127 Specify a set of features to allow (default none).
128 .B bind_v2
129 allows acceptance of LDAPv2 bind requests.  Note that
130 .BR slapd (8)
131 does not truly implement LDAPv2 (RFC 1777), now Historic (RFC 3494).
132 .B bind_anon_cred
133 allows anonymous bind when credentials are not empty (e.g.
134 when DN is empty).
135 .B bind_anon_dn
136 allows unauthenticated (anonymous) bind when DN is not empty.
137 .B update_anon
138 allows unauthenticated (anonymous) update operations to be processed
139 (subject to access controls and other administrative limits).
140 .B proxy_authz_anon
141 allows unauthenticated (anonymous) proxy authorization control to be processed
142 (subject to access controls, authorization and other administrative limits).
143 .TP
144 .B olcArgsFile: <filename>
145 The ( absolute ) name of a file that will hold the 
146 .B slapd
147 server's command line options
148 if started without the debugging command line option.
149 .TP
150 .B olcAttributeOptions: <option-name>...
151 Define tagging attribute options or option tag/range prefixes.
152 Options must not end with `-', prefixes must end with `-'.
153 The `lang-' prefix is predefined.
154 If you use the
155 .B olcAttributeOptions
156 directive, `lang-' will no longer be defined and you must specify it
157 explicitly if you want it defined.
158
159 An attribute description with a tagging option is a subtype of that
160 attribute description without the option.
161 Except for that, options defined this way have no special semantics.
162 Prefixes defined this way work like the `lang-' options:
163 They define a prefix for tagging options starting with the prefix.
164 That is, if you define the prefix `x-foo-', you can use the option
165 `x-foo-bar'.
166 Furthermore, in a search or compare, a prefix or range name (with
167 a trailing `-') matches all options starting with that name, as well
168 as the option with the range name sans the trailing `-'.
169 That is, `x-foo-bar-' matches `x-foo-bar' and `x-foo-bar-baz'.
170
171 RFC 4520 reserves options beginning with `x-' for private experiments.
172 Other options should be registered with IANA, see RFC 4520 section 3.5.
173 OpenLDAP also has the `binary' option built in, but this is a transfer
174 option, not a tagging option.
175 .TP
176 .B olcAuthzPolicy: <policy>
177 Used to specify which rules to use for Proxy Authorization.  Proxy
178 authorization allows a client to authenticate to the server using one
179 user's credentials, but specify a different identity to use for authorization
180 and access control purposes. It essentially allows user A to login as user
181 B, using user A's password.
182 The
183 .B none
184 flag disables proxy authorization. This is the default setting.
185 The
186 .B from
187 flag will use rules in the
188 .I authzFrom
189 attribute of the authorization DN.
190 The
191 .B to
192 flag will use rules in the
193 .I authzTo
194 attribute of the authentication DN.
195 The
196 .B any
197 flag, an alias for the deprecated value of
198 .BR both ,
199 will allow any of the above, whatever succeeds first (checked in
200 .BR to ,
201 .B from
202 sequence.
203 The
204 .B all
205 flag requires both authorizations to succeed.
206 .LP
207 .RS
208 The rules are mechanisms to specify which identities are allowed 
209 to perform proxy authorization.
210 The
211 .I authzFrom
212 attribute in an entry specifies which other users
213 are allowed to proxy login to this entry. The
214 .I authzTo
215 attribute in
216 an entry specifies which other users this user can authorize as.  Use of
217 .I authzTo
218 rules can be easily
219 abused if users are allowed to write arbitrary values to this attribute.
220 In general the
221 .I authzTo
222 attribute must be protected with ACLs such that
223 only privileged users can modify it.
224 The value of
225 .I authzFrom
226 and
227 .I authzTo
228 describes an 
229 .B identity 
230 or a set of identities; it can take five forms:
231 .RS
232 .TP
233 .B ldap:///<base>??[<scope>]?<filter>
234 .RE
235 .RS
236 .B dn[.<dnstyle>]:<pattern>
237 .RE
238 .RS
239 .B u[<mech>[<realm>]]:<pattern>
240 .RE
241 .RS
242 .B group[/objectClass[/attributeType]]:<pattern>
243 .RE
244 .RS
245 .B <pattern>
246 .RE
247 .RS
248
249 .B <dnstyle>:={exact|onelevel|children|subtree|regex}
250
251 .RE
252 The first form is a valid LDAP
253 .B URI
254 where the 
255 .IR <host>:<port> ,
256 the
257 .I <attrs>
258 and the
259 .I <extensions>
260 portions must be absent, so that the search occurs locally on either
261 .I authzFrom
262 or 
263 .IR authzTo .
264 The second form is a 
265 .BR DN ,
266 with the optional style modifiers
267 .IR exact ,
268 .IR onelevel ,
269 .IR children ,
270 and
271 .I subtree
272 for exact, onelevel, children and subtree matches, which cause 
273 .I <pattern>
274 to be normalized according to the DN normalization rules, or the special
275 .I regex
276 style, which causes the
277 .I <pattern>
278 to be treated as a POSIX (''extended'') regular expression, as
279 discussed in
280 .BR regex (7)
281 and/or
282 .BR re_format (7).
283 A pattern of
284 .I *
285 means any non-anonymous DN.
286 The third form is a SASL
287 .BR id ,
288 with the optional fields
289 .I <mech>
290 and
291 .I <realm>
292 that allow to specify a SASL
293 .BR mechanism ,
294 and eventually a SASL
295 .BR realm ,
296 for those mechanisms that support one.
297 The need to allow the specification of a mechanism is still debated, 
298 and users are strongly discouraged to rely on this possibility.
299 The fourth form is a group specification, consisting of the keyword
300 .BR group ,
301 optionally followed by the specification of the group
302 .B objectClass
303 and member
304 .BR attributeType .
305 The group with DN
306 .B <pattern>
307 is searched with base scope, and in case of match, the values of the
308 member
309 .B attributeType
310 are searched for the asserted DN.
311 For backwards compatibility, if no identity type is provided, i.e. only
312 .B <pattern>
313 is present, an
314 .I exact DN
315 is assumed; as a consequence, 
316 .B <pattern>
317 is subjected to DN normalization.
318 Since the interpretation of
319 .I authzFrom
320 and
321 .I authzTo
322 can impact security, users are strongly encouraged 
323 to explicitly set the type of identity specification that is being used.
324 A subset of these rules can be used as third arg in the 
325 .B olcAuthzRegexp
326 statement (see below); significantly, the 
327 .I URI
328 and the
329 .I dn.exact:<dn> 
330 forms.
331 .RE
332 .TP
333 .B olcAuthzRegexp: <match> <replace>
334 Used by the authentication framework to convert simple user names,
335 such as provided by SASL subsystem, to an LDAP DN used for
336 authorization purposes.  Note that the resultant DN need not refer
337 to an existing entry to be considered valid.  When an authorization
338 request is received from the SASL subsystem, the SASL 
339 .BR USERNAME ,
340 .BR REALM , 
341 and
342 .B MECHANISM
343 are taken, when available, and combined into a name of the form
344 .RS
345 .RS
346 .TP
347 .B UID=<username>[[,CN=<realm>],CN=<mechanism>],CN=auth
348
349 .RE
350 This name is then compared against the
351 .B match
352 POSIX (''extended'') regular expression, and if the match is successful,
353 the name is replaced with the
354 .B replace
355 string.  If there are wildcard strings in the 
356 .B match
357 regular expression that are enclosed in parenthesis, e.g. 
358 .RS
359 .TP
360 .B UID=([^,]*),CN=.*
361
362 .RE
363 then the portion of the name that matched the wildcard will be stored
364 in the numbered placeholder variable $1. If there are other wildcard strings
365 in parenthesis, the matching strings will be in $2, $3, etc. up to $9. The 
366 placeholders can then be used in the 
367 .B replace
368 string, e.g. 
369 .RS
370 .TP
371 .B UID=$1,OU=Accounts,DC=example,DC=com 
372
373 .RE
374 The replaced name can be either a DN, i.e. a string prefixed by "dn:",
375 or an LDAP URI.
376 If the latter, the server will use the URI to search its own database(s)
377 and, if the search returns exactly one entry, the name is
378 replaced by the DN of that entry.   The LDAP URI must have no
379 hostport, attrs, or extensions components, but the filter is mandatory,
380 e.g.
381 .RS
382 .TP
383 .B ldap:///OU=Accounts,DC=example,DC=com??one?(UID=$1)
384
385 .RE
386 The protocol portion of the URI must be strictly
387 .BR ldap .
388 Note that this search is subject to access controls.  Specifically,
389 the authentication identity must have "auth" access in the subject.
390
391 Multiple 
392 .B olcAuthzRegexp 
393 values can be specified to allow for multiple matching 
394 and replacement patterns. The matching patterns are checked in the order they 
395 appear in the attribute, stopping at the first successful match.
396
397 .\".B Caution:
398 .\"Because the plus sign + is a character recognized by the regular expression engine,
399 .\"and it will appear in names that include a REALM, be careful to escape the
400 .\"plus sign with a backslash \\+ to remove the character's special meaning.
401 .RE
402 .TP
403 .B olcConcurrency: <integer>
404 Specify a desired level of concurrency.  Provided to the underlying
405 thread system as a hint.  The default is not to provide any hint. This setting
406 is only meaningful on some platforms where there is not a one to one
407 correspondence between user threads and kernel threads.
408 .TP
409 .B olcConnMaxPending: <integer>
410 Specify the maximum number of pending requests for an anonymous session.
411 If requests are submitted faster than the server can process them, they
412 will be queued up to this limit. If the limit is exceeded, the session
413 is closed. The default is 100.
414 .TP
415 .B olcConnMaxPendingAuth: <integer>
416 Specify the maximum number of pending requests for an authenticated session.
417 The default is 1000.
418 .TP
419 .B olcDisallows: <features>
420 Specify a set of features to disallow (default none).
421 .B bind_anon
422 disables acceptance of anonymous bind requests.  Note that this setting
423 does not prohibit anonymous directory access (See "require authc").
424 .B bind_simple
425 disables simple (bind) authentication.
426 .B tls_2_anon
427 disables forcing session to anonymous status (see also
428 .BR tls_authc )
429 upon StartTLS operation receipt.
430 .B tls_authc
431 disallows the StartTLS operation if authenticated (see also
432 .BR tls_2_anon ).
433 .TP
434 .B olcGentleHUP: { TRUE | FALSE }
435 A SIGHUP signal will only cause a 'gentle' shutdown-attempt:
436 .B Slapd
437 will stop listening for new connections, but will not close the
438 connections to the current clients.  Future write operations return
439 unwilling-to-perform, though.  Slapd terminates when all clients
440 have closed their connections (if they ever do), or \- as before \-
441 if it receives a SIGTERM signal.  This can be useful if you wish to
442 terminate the server and start a new
443 .B slapd
444 server
445 .B with another database,
446 without disrupting the currently active clients.
447 The default is FALSE.  You may wish to use
448 .B olcIdletTmeout
449 along with this option.
450 .TP
451 .B olcIdleTimeout: <integer>
452 Specify the number of seconds to wait before forcibly closing
453 an idle client connection.  A setting of 0 disables this
454 feature.  The default is 0.
455 .TP
456 .B olcIndexSubstrIfMaxlen: <integer>
457 Specify the maximum length for subinitial and subfinal indices. Only
458 this many characters of an attribute value will be processed by the
459 indexing functions; any excess characters are ignored. The default is 4.
460 .TP
461 .B olcIndexSubstrIfMinlen: <integer>
462 Specify the minimum length for subinitial and subfinal indices. An
463 attribute value must have at least this many characters in order to be
464 processed by the indexing functions. The default is 2.
465 .TP
466 .B olcIndexSubstrAnyLen: <integer>
467 Specify the length used for subany indices. An attribute value must have
468 at least this many characters in order to be processed. Attribute values
469 longer than this length will be processed in segments of this length. The
470 default is 4. The subany index will also be used in subinitial and
471 subfinal index lookups when the filter string is longer than the
472 .I olcIndexSubstrIfMaxlen
473 value.
474 .TP
475 .B olcIndexSubstrAnyStep: <integer>
476 Specify the steps used in subany index lookups. This value sets the offset
477 for the segments of a filter string that are processed for a subany index
478 lookup. The default is 2. For example, with the default values, a search
479 using this filter "cn=*abcdefgh*" would generate index lookups for
480 "abcd", "cdef", and "efgh".
481
482 .TP
483 .B olcLocalSSF: <SSF>
484 Specifies the Security Strength Factor (SSF) to be given local LDAP sessions,
485 such as those to the ldapi:// listener.  For a description of SSF values,
486 see 
487 .BR olcSaslSecProps 's
488 .B minssf
489 option description.  The default is 71.
490 .TP
491 .B olcLogLevel: <integer> [...]
492 Specify the level at which debugging statements and operation 
493 statistics should be syslogged (currently logged to the
494 .BR syslogd (8) 
495 LOG_LOCAL4 facility).
496 They must be considered subsystems rather than increasingly verbose 
497 log levels.
498 Some messages with higher priority are logged regardless 
499 of the configured loglevel as soon as some logging is configured,
500 otherwise anything is logged at all.
501 Log levels are additive, and available levels are:
502 .RS
503 .RS
504 .PD 0
505 .TP
506 .B 1
507 .B (0x1 trace)
508 trace function calls
509 .TP
510 .B 2
511 .B (0x2 packets)
512 debug packet handling
513 .TP
514 .B 4
515 .B (0x4 args)
516 heavy trace debugging (function args)
517 .TP
518 .B 8
519 .B (0x8 conns)
520 connection management
521 .TP
522 .B 16
523 .B (0x10 BER)
524 print out packets sent and received
525 .TP
526 .B 32
527 .B (0x20 filter)
528 search filter processing
529 .TP
530 .B 64
531 .B (0x40 config)
532 configuration file processing
533 .TP
534 .B 128
535 .B (0x80 ACL)
536 access control list processing
537 .TP
538 .B 256
539 .B (0x100 stats)
540 stats log connections/operations/results
541 .TP
542 .B 512
543 .B (0x200 stats2)
544 stats log entries sent
545 .TP
546 .B 1024
547 .B (0x400 shell)
548 print communication with shell backends
549 .TP
550 .B 2048
551 .B (0x800 parse)
552 entry parsing
553 \".TP
554 \".B 4096
555 \".B (0x1000 cache)
556 \"caching (unused)
557 \".TP
558 \".B 8192
559 \".B (0x2000 index)
560 \"data indexing (unused)
561 .TP
562 .B 16384
563 .B (0x4000 sync)
564 LDAPSync replication
565 .TP
566 .B 32768
567 .B (0x8000 none)
568 only messages that get logged whatever log level is set
569 .PD
570 .RE
571 The desired log level can be input as a single integer that combines 
572 the (ORed) desired levels, both in decimal or in hexadecimal notation,
573 as a list of integers (that are ORed internally),
574 or as a list of the names that are shown between brackets, such that
575 .LP
576 .nf
577     olcLogLevel: 129
578     olcLogLevel: 0x81
579     olcLogLevel: 128 1
580     olcLogLevel: 0x80 0x1
581     olcLogLevel: acl trace
582 .fi
583 .LP
584 are equivalent.
585 The keyword 
586 .B any
587 can be used as a shortcut to enable logging at all levels (equivalent to -1).
588 The keyword
589 .BR none ,
590 or the equivalent integer representation, causes those messages
591 that are logged regardless of the configured olcLogLevel to be logged.
592 In fact, if no olcLogLevel (or a 0 level) is defined, no logging occurs, 
593 so at least the 
594 .B none
595 level is required to have high priority messages logged.
596 .RE
597 .TP
598 .B olcPasswordCryptSaltFormat: <format>
599 Specify the format of the salt passed to
600 .BR crypt (3)
601 when generating {CRYPT} passwords (see
602 .BR olcPasswordHash )
603 during processing of LDAP Password Modify Extended Operations (RFC 3062).
604
605 This string needs to be in
606 .BR sprintf (3)
607 format and may include one (and only one) %s conversion.
608 This conversion will be substituted with a string of random
609 characters from [A\-Za\-z0\-9./].  For example, "%.2s"
610 provides a two character salt and "$1$%.8s" tells some
611 versions of crypt(3) to use an MD5 algorithm and provides
612 8 random characters of salt.  The default is "%s", which
613 provides 31 characters of salt.
614 .TP
615 .B olcPasswordHash: <hash> [<hash>...]
616 This option configures one or more hashes to be used in generation of user
617 passwords stored in the userPassword attribute during processing of
618 LDAP Password Modify Extended Operations (RFC 3062).
619 The <hash> must be one of
620 .BR {SSHA} ,
621 .BR {SHA} ,
622 .BR {SMD5} ,
623 .BR {MD5} ,
624 .BR {CRYPT} ,
625 and
626 .BR {CLEARTEXT} .
627 The default is
628 .BR {SSHA} .
629
630 .B {SHA}
631 and
632 .B {SSHA}
633 use the SHA-1 algorithm (FIPS 160-1), the latter with a seed.
634
635 .B {MD5}
636 and
637 .B {SMD5}
638 use the MD5 algorithm (RFC 1321), the latter with a seed.
639
640 .B {CRYPT}
641 uses the
642 .BR crypt (3).
643
644 .B {CLEARTEXT}
645 indicates that the new password should be
646 added to userPassword as clear text.
647
648 Note that this option does not alter the normal user applications
649 handling of userPassword during LDAP Add, Modify, or other LDAP operations.
650 .TP
651 .B olcPidFile: <filename>
652 The ( absolute ) name of a file that will hold the 
653 .B slapd
654 server's process ID ( see
655 .BR getpid (2)
656 ) if started without the debugging command line option.
657 .TP
658 .B olcPluginLogFile: <filename>
659 The ( absolute ) name of a file that will contain log
660 messages from
661 .B SLAPI
662 plugins. See
663 .BR slapd.plugin (5)
664 for details.
665 .TP
666 .B olcReferral: <url>
667 Specify the referral to pass back when
668 .BR slapd (8)
669 cannot find a local database to handle a request.
670 If multiple values are specified, each url is provided.
671 .\" slurpd-related keywords are all deprecated
672 .\".TP
673 .\".B replica-argsfile
674 .\"The ( absolute ) name of a file that will hold the 
675 .\".B slurpd
676 .\"server's command line options
677 .\"if started without the debugging command line option.
678 .\"If it appears after a
679 .\".B replogfile
680 .\"directive, the args file is specific to the 
681 .\".BR slurpd (8)
682 .\"instance that handles that replication log.
683 .\".TP
684 .\".B replica-pidfile
685 .\"The ( absolute ) name of a file that will hold the 
686 .\".B slurpd
687 .\"server's process ID ( see
688 .\".BR getpid (2)
689 .\") if started without the debugging command line option.
690 .\"If it appears after a
691 .\".B replogfile
692 .\"directive, the pid file is specific to the 
693 .\".BR slurpd (8)
694 .\"instance that handles that replication log.
695 .\".TP
696 .\".B replicationinterval
697 .\"The number of seconds 
698 .\".B slurpd 
699 .\"waits before checking the replogfile for changes.
700 .\"If it appears after a
701 .\".B replogfile
702 .\"directive, the replication interval is specific to the 
703 .\".BR slurpd (8)
704 .\"instance that handles that replication log.
705 .TP
706 .B olcReverseLookup: TRUE | FALSE
707 Enable/disable client name unverified reverse lookup (default is 
708 .BR FALSE 
709 if compiled with --enable-rlookups).
710 .TP
711 .B olcRootDSE: <file>
712 Specify the name of an LDIF(5) file containing user defined attributes
713 for the root DSE.  These attributes are returned in addition to the
714 attributes normally produced by slapd.
715 .TP
716 .B olcSaslHost: <fqdn>
717 Used to specify the fully qualified domain name used for SASL processing.
718 .TP
719 .B olcSaslRealm: <realm>
720 Specify SASL realm.  Default is empty.
721 .TP
722 .B olcSaslSecProps: <properties>
723 Used to specify Cyrus SASL security properties.
724 The
725 .B none
726 flag (without any other properties) causes the flag properties
727 default, "noanonymous,noplain", to be cleared.
728 The
729 .B noplain
730 flag disables mechanisms susceptible to simple passive attacks.
731 The
732 .B noactive
733 flag disables mechanisms susceptible to active attacks.
734 The
735 .B nodict
736 flag disables mechanisms susceptible to passive dictionary attacks.
737 The
738 .B noanonymous
739 flag disables mechanisms which support anonymous login.
740 The
741 .B forwardsec
742 flag require forward secrecy between sessions.
743 The
744 .B passcred
745 require mechanisms which pass client credentials (and allow
746 mechanisms which can pass credentials to do so).
747 The
748 .B minssf=<factor> 
749 property specifies the minimum acceptable
750 .I security strength factor
751 as an integer approximate to effective key length used for
752 encryption.  0 (zero) implies no protection, 1 implies integrity
753 protection only, 56 allows DES or other weak ciphers, 112
754 allows triple DES and other strong ciphers, 128 allows RC4,
755 Blowfish and other modern strong ciphers.  The default is 0.
756 The
757 .B maxssf=<factor> 
758 property specifies the maximum acceptable
759 .I security strength factor
760 as an integer (see minssf description).  The default is INT_MAX.
761 The
762 .B maxbufsize=<size> 
763 property specifies the maximum security layer receive buffer
764 size allowed.  0 disables security layers.  The default is 65536.
765 .TP
766 .B olcSockbufMaxIncoming: <integer>
767 Specify the maximum incoming LDAP PDU size for anonymous sessions.
768 The default is 262143.
769 .TP
770 .B olcSockbufMaxIncomingAuth: <integer>
771 Specify the maximum incoming LDAP PDU size for authenticated sessions.
772 The default is 4194303.
773 .TP
774 .B olcThreads: <integer>
775 Specify the maximum size of the primary thread pool.
776 The default is 16; the minimum value is 2.
777 .TP
778 .B olcToolThreads: <integer>
779 Specify the maximum number of threads to use in tool mode.
780 This should not be greater than the number of CPUs in the system.
781 The default is 1.
782 .\"ucdata-path is obsolete / ignored...
783 .\".TP
784 .\".B ucdata-path <path>
785 .\"Specify the path to the directory containing the Unicode character
786 .\"tables. The default path is DATADIR/ucdata.
787 .SH TLS OPTIONS
788 If
789 .B slapd
790 is built with support for Transport Layer Security, there are more options
791 you can specify.
792 .TP
793 .B olcTLSCipherSuite: <cipher-suite-spec>
794 Permits configuring what ciphers will be accepted and the preference order.
795 <cipher-suite-spec> should be a cipher specification for OpenSSL.  Example:
796
797 olcTLSCipherSuite: HIGH:MEDIUM:+SSLv2
798
799 To check what ciphers a given spec selects, use:
800
801 openssl ciphers -v <cipher-suite-spec>
802 .TP
803 .B olcTLSCACertificateFile: <filename>
804 Specifies the file that contains certificates for all of the Certificate
805 Authorities that
806 .B slapd
807 will recognize.
808 .TP
809 .B olcTLSCACertificatePath: <path>
810 Specifies the path of a directory that contains Certificate Authority
811 certificates in separate individual files. Usually only one of this
812 or the olcTLSCACertificateFile is defined. If both are specified, both
813 locations will be used.
814 .TP
815 .B olcTLSCertificateFile: <filename>
816 Specifies the file that contains the
817 .B slapd
818 server certificate.
819 .TP
820 .B olcTLSCertificateKeyFile: <filename>
821 Specifies the file that contains the
822 .B slapd
823 server private key that matches the certificate stored in the
824 .B olcTLSCertificateFile
825 file. If the private key is protected with a password, the password must
826 be manually typed in when slapd starts.  Usually the private key is not
827 protected with a password, to allow slapd to start without manual
828 intervention, so
829 it is of critical importance that the file is protected carefully. 
830 .TP
831 .B olcTLSDHParamFile: <filename>
832 This directive specifies the file that contains parameters for Diffie-Hellman
833 ephemeral key exchange.  This is required in order to use a DSA certificate on
834 the server. If multiple sets of parameters are present in the file, all of
835 them will be processed.  Note that setting this option may also enable
836 Anonymous Diffie-Hellman key exchanges in certain non-default cipher suites.
837 You should append "!ADH" to your cipher suites if you have changed them
838 from the default, otherwise no certificate exchanges or verification will
839 be done.
840 .TP
841 .B olcTLSRandFile: <filename>
842 Specifies the file to obtain random bits from when /dev/[u]random
843 is not available.  Generally set to the name of the EGD/PRNGD socket.
844 The environment variable RANDFILE can also be used to specify the filename.
845 .TP
846 .B olcTLSVerifyClient: <level>
847 Specifies what checks to perform on client certificates in an
848 incoming TLS session, if any.
849 The
850 .B <level>
851 can be specified as one of the following keywords:
852 .RS
853 .TP
854 .B never
855 This is the default.
856 .B slapd
857 will not ask the client for a certificate.
858 .TP
859 .B allow
860 The client certificate is requested.  If no certificate is provided,
861 the session proceeds normally.  If a bad certificate is provided,
862 it will be ignored and the session proceeds normally.
863 .TP
864 .B try
865 The client certificate is requested.  If no certificate is provided,
866 the session proceeds normally.  If a bad certificate is provided,
867 the session is immediately terminated.
868 .TP
869 .B demand | hard | true
870 These keywords are all equivalent, for compatibility reasons.
871 The client certificate is requested.  If no certificate is provided,
872 or a bad certificate is provided, the session is immediately terminated.
873
874 Note that a valid client certificate is required in order to use the
875 SASL EXTERNAL authentication mechanism with a TLS session.  As such,
876 a non-default
877 .B olcTLSVerifyClient
878 setting must be chosen to enable SASL EXTERNAL authentication.
879 .RE
880 .TP
881 .B olcTLSCRLCheck: <level>
882 Specifies if the Certificate Revocation List (CRL) of the CA should be 
883 used to verify if the client certificates have not been revoked. This
884 requires
885 .B olcTLSCACertificatePath
886 parameter to be set.
887 .B <level>
888 can be specified as one of the following keywords:
889 .RS
890 .TP
891 .B none
892 No CRL checks are performed
893 .TP
894 .B peer
895 Check the CRL of the peer certificate
896 .TP
897 .B all
898 Check the CRL for a whole certificate chain
899 .RE
900 .SH DYNAMIC MODULE OPTIONS
901 If
902 .B slapd
903 is compiled with --enable-modules then the module-related entries will
904 be available. These entries are named
905 .B cn=module{x},cn=config
906 and
907 must have the olcModuleList objectClass. One entry should be created
908 per
909 .B olcModulePath.
910 Normally the config engine generates the "{x}" index in the RDN
911 automatically, so it can be omitted when initially loading these entries.
912 .TP
913 .B olcModuleLoad: <filename>
914 Specify the name of a dynamically loadable module to load. The filename
915 may be an absolute path name or a simple filename. Non-absolute names
916 are searched for in the directories specified by the
917 .B olcModulePath
918 option.
919 .TP
920 .B olcModulePath: <pathspec>
921 Specify a list of directories to search for loadable modules. Typically
922 the path is colon-separated but this depends on the operating system.
923 .SH SCHEMA OPTIONS
924 Schema definitions are created as entries in the
925 .B cn=schema,cn=config
926 subtree. These entries must have the olcSchemaConfig objectClass.
927 As noted above, the actual
928 .B cn=schema,cn=config
929 entry is predefined and any values specified for it are ignored.
930
931 .HP
932 .hy 0
933 .B olcAttributetypes: "(\ <oid>\
934  [NAME\ <name>]\
935  [DESC\ <description>]\
936  [OBSOLETE]\
937  [SUP\ <oid>]\
938  [EQUALITY\ <oid>]\
939  [ORDERING\ <oid>]\
940  [SUBSTR\ <oid>]\
941  [SYNTAX\ <oidlen>]\
942  [SINGLE\-VALUE]\
943  [COLLECTIVE]\
944  [NO\-USER\-MODIFICATION]\
945  [USAGE\ <attributeUsage>]\ )"
946 .RS
947 Specify an attribute type using the LDAPv3 syntax defined in RFC 4512.
948 The slapd parser extends the RFC 4512 definition by allowing string
949 forms as well as numeric OIDs to be used for the attribute OID and
950 attribute syntax OID.
951 (See the
952 .B olcObjectIdentifier
953 description.) 
954 .RE
955
956 .HP
957 .hy 0
958 .B olcDitContentRules: "(\ <oid>\
959  [NAME\ <name>]\
960  [DESC\ <description>]\
961  [OBSOLETE]\
962  [AUX\ <oids>]\
963  [MUST\ <oids>]\
964  [MAY\ <oids>]\
965  [NOT\ <oids>]\ )"
966 .RS
967 Specify an DIT Content Rule using the LDAPv3 syntax defined in RFC 4512.
968 The slapd parser extends the RFC 4512 definition by allowing string
969 forms as well as numeric OIDs to be used for the attribute OID and
970 attribute syntax OID.
971 (See the
972 .B olcObjectIdentifier
973 description.) 
974 .RE
975
976 .HP
977 .hy 0
978 .B olcObjectClasses: "(\ <oid>\
979  [NAME\ <name>]\
980  [DESC\ <description>]\
981  [OBSOLETE]\
982  [SUP\ <oids>]\
983  [{ ABSTRACT | STRUCTURAL | AUXILIARY }]\
984  [MUST\ <oids>] [MAY\ <oids>] )"
985 .RS
986 Specify an objectclass using the LDAPv3 syntax defined in RFC 4512.
987 The slapd parser extends the RFC 4512 definition by allowing string
988 forms as well as numeric OIDs to be used for the object class OID.
989 (See the
990 .B
991 olcObjectIdentifier
992 description.)  Object classes are "STRUCTURAL" by default.
993 .RE
994 .TP
995 .B olcObjectIdentifier: <name> "{ <oid> | <name>[:<suffix>] }"
996 Define a string name that equates to the given OID. The string can be used
997 in place of the numeric OID in objectclass and attribute definitions. The
998 name can also be used with a suffix of the form ":xx" in which case the
999 value "oid.xx" will be used.
1000
1001 .SH GENERAL BACKEND OPTIONS
1002 Options in these entries only apply to the configuration of a single
1003 type of backend. All backends may support this class of options.
1004 The entry must be named
1005 .B olcBackend=<databasetype>,cn=config
1006 and must have the olcBackendConfig objectClass.
1007 <databasetype>
1008 should be one of
1009 .BR bdb ,
1010 .BR config ,
1011 .BR dnssrv ,
1012 .BR hdb ,
1013 .BR ldap ,
1014 .BR ldif ,
1015 .BR meta ,
1016 .BR monitor ,
1017 .BR null ,
1018 .BR passwd ,
1019 .BR perl ,
1020 .BR relay ,
1021 .BR shell ,
1022 or
1023 .BR sql .
1024 At present, no backend implements any options of this type.
1025
1026 .SH DATABASE OPTIONS
1027 Database options are set in entries named
1028 .B olcDatabase={x}<databasetype>,cn=config
1029 and must have the olcDatabaseConfig objectClass. Normally the config
1030 engine generates the "{x}" index in the RDN automatically, so it
1031 can be omitted when initially loading these entries.
1032
1033 The special frontend database is always numbered "{-1}" and the config
1034 database is always numbered "{0}".
1035
1036 .SH GLOBAL DATABASE OPTIONS
1037 Options in this section may be set in the special "frontend" database
1038 and inherited in all the other databases. These options may be altered
1039 by further settings in each specific database. The frontend entry must
1040 be named
1041 .B olcDatabase=frontend,cn=config
1042 and must have the olcFrontendConfig objectClass.
1043 .TP
1044 .B olcAccess: to <what> "[ by <who> <access> <control> ]+"
1045 Grant access (specified by <access>) to a set of entries and/or
1046 attributes (specified by <what>) by one or more requestors (specified
1047 by <who>).
1048 If no access controls are present, the default policy
1049 allows anyone and everyone to read anything but restricts
1050 updates to rootdn.  (e.g., "olcAccess: to * by * read").
1051 See
1052 .BR slapd.access (5)
1053 and the "OpenLDAP Administrator's Guide" for details.
1054
1055 Access controls set in the frontend are appended to any access
1056 controls set on the specific databases.
1057 The rootdn of a database can always read and write EVERYTHING
1058 in that database.
1059
1060 Extra special care must be taken with the access controls on the
1061 config database. Unlike other databases, the default policy for the
1062 config database is to only allow access to the rootdn. Regular users
1063 should not have read access, and write access should be granted very
1064 carefully to privileged administrators.
1065
1066 .TP
1067 .B olcDefaultSearchBase: <dn>
1068 Specify a default search base to use when client submits a
1069 non-base search request with an empty base DN.
1070 Base scoped search requests with an empty base DN are not affected.
1071 This setting is only allowed in the frontend entry.
1072 .TP
1073 .B olcReadOnly: TRUE | FALSE
1074 This option puts the database into "read-only" mode.  Any attempts to 
1075 modify the database will return an "unwilling to perform" error.  By
1076 default, olcReadOnly is FALSE. Note that when this option is set
1077 TRUE on the frontend, it cannot be reset without restarting the
1078 server, since further writes to the config database will be rejected.
1079 .TP
1080 .B olcRequires: <conditions>
1081 Specify a set of conditions to require (default none).
1082 The directive may be specified globally and/or per-database;
1083 databases inherit global conditions, so per-database specifications
1084 are additive.
1085 .B bind
1086 requires bind operation prior to directory operations.
1087 .B LDAPv3
1088 requires session to be using LDAP version 3.
1089 .B authc
1090 requires authentication prior to directory operations.
1091 .B SASL
1092 requires SASL authentication prior to directory operations.
1093 .B strong
1094 requires strong authentication prior to directory operations.
1095 The strong keyword allows protected "simple" authentication
1096 as well as SASL authentication.
1097 .B none
1098 may be used to require no conditions (useful to clear out globally
1099 set conditions within a particular database); it must occur first
1100 in the list of conditions.
1101 .TP
1102 .B olcRestrict: <oplist>
1103 Specify a list of operations that are restricted.
1104 Restrictions on a specific database override any frontend setting.
1105 Operations can be any of 
1106 .BR add ,
1107 .BR bind ,
1108 .BR compare ,
1109 .BR delete ,
1110 .BR extended[=<OID>] ,
1111 .BR modify ,
1112 .BR rename ,
1113 .BR search ,
1114 or the special pseudo-operations
1115 .B read
1116 and
1117 .BR write ,
1118 which respectively summarize read and write operations.
1119 The use of 
1120 .I restrict write
1121 is equivalent to 
1122 .I olcReadOnly: TRUE
1123 (see above).
1124 The 
1125 .B extended
1126 keyword allows to indicate the OID of the specific operation
1127 to be restricted.
1128 .TP
1129 .B olcSchemaDN: <dn>
1130 Specify the distinguished name for the subschema subentry that
1131 controls the entries on this server.  The default is "cn=Subschema".
1132 .TP
1133 .B olcSecurity: <factors>
1134 Specify a set of security strength factors (separated by white space)
1135 to require (see
1136 .BR olcSaslSecprops 's
1137 .B minssf
1138 option for a description of security strength factors).
1139 The directive may be specified globally and/or per-database.
1140 .B ssf=<n>
1141 specifies the overall security strength factor.
1142 .B transport=<n>
1143 specifies the transport security strength factor.
1144 .B tls=<n>
1145 specifies the TLS security strength factor.
1146 .B sasl=<n>
1147 specifies the SASL security strength factor.
1148 .B update_ssf=<n>
1149 specifies the overall security strength factor to require for
1150 directory updates.
1151 .B update_transport=<n>
1152 specifies the transport security strength factor to require for
1153 directory updates.
1154 .B update_tls=<n>
1155 specifies the TLS security strength factor to require for
1156 directory updates.
1157 .B update_sasl=<n>
1158 specifies the SASL security strength factor to require for
1159 directory updates.
1160 .B simple_bind=<n>
1161 specifies the security strength factor required for
1162 .I simple
1163 username/password authentication.
1164 Note that the
1165 .B transport
1166 factor is measure of security provided by the underlying transport,
1167 e.g. ldapi:// (and eventually IPSEC).  It is not normally used.
1168 .TP
1169 .B olcSizeLimit: {<integer>|unlimited}
1170 .TP
1171 .B olcSizeLimit: size[.{soft|hard|unchecked}]=<integer> [...]
1172 Specify the maximum number of entries to return from a search operation.
1173 The default size limit is 500.
1174 Use
1175 .B unlimited
1176 to specify no limits.
1177 The second format allows a fine grain setting of the size limits.
1178 Extra args can be added in the same value or as additional values.
1179 See
1180 .BR olcLimits
1181 for an explanation of the different flags.
1182 .TP
1183 .B olcTimeLimit: {<integer>|unlimited}
1184 .TP
1185 .B olcTimeLimit: time[.{soft|hard}]=<integer> [...]
1186 Specify the maximum number of seconds (in real time)
1187 .B slapd
1188 will spend answering a search request.  The default time limit is 3600.
1189 Use
1190 .B unlimited
1191 to specify no limits.
1192 The second format allows a fine grain setting of the time limits.
1193 Extra args can be added in the same value or as additional values.
1194 See
1195 .BR olcLimits
1196 for an explanation of the different flags.
1197
1198 .SH GENERAL DATABASE OPTIONS
1199 Options in this section only apply to the specific database for
1200 which they are defined.  They are supported by every
1201 type of backend. All of the Global Database Options may also be
1202 used here.
1203 .TP
1204 .B olcLastMod: TRUE | FALSE
1205 Controls whether
1206 .B slapd
1207 will automatically maintain the 
1208 modifiersName, modifyTimestamp, creatorsName, and 
1209 createTimestamp attributes for entries. It also controls
1210 the entryCSN and entryUUID attributes, which are needed
1211 by the syncrepl provider. By default, olcLastMod is TRUE.
1212 .TP
1213 .B olcLimits: <who> <limit> [<limit> [...]]
1214 Specify time and size limits based on who initiated an operation.
1215 The argument
1216 .B who
1217 can be any of
1218 .RS
1219 .RS
1220 .TP
1221 anonymous | users | [dn[.<style>]=]<pattern> | group[/oc[/at]]=<pattern>
1222
1223 .RE
1224 with
1225 .RS
1226 .TP
1227 <style> ::= exact | base | onelevel | subtree | children | regex | anonymous
1228
1229 .RE
1230 The term
1231 .B anonymous
1232 matches all unauthenticated clients.
1233 The term
1234 .B users
1235 matches all authenticated clients;
1236 otherwise an
1237 .B exact
1238 dn pattern is assumed unless otherwise specified by qualifying 
1239 the (optional) key string
1240 .B dn
1241 with 
1242 .B exact
1243 or
1244 .B base
1245 (which are synonyms), to require an exact match; with
1246 .BR onelevel , 
1247 to require exactly one level of depth match; with
1248 .BR subtree ,
1249 to allow any level of depth match, including the exact match; with
1250 .BR children ,
1251 to allow any level of depth match, not including the exact match;
1252 .BR regex
1253 explicitly requires the (default) match based on POSIX (''extended'')
1254 regular expression pattern.
1255 Finally,
1256 .B anonymous
1257 matches unbound operations; the 
1258 .B pattern
1259 field is ignored.
1260 The same behavior is obtained by using the 
1261 .B anonymous
1262 form of the
1263 .B who
1264 clause.
1265 The term
1266 .BR group ,
1267 with the optional objectClass
1268 .B oc
1269 and attributeType
1270 .B at
1271 fields, followed by
1272 .BR pattern ,
1273 sets the limits for any DN listed in the values of the
1274 .B at
1275 attribute (default
1276 .BR member )
1277 of the 
1278 .B oc
1279 group objectClass (default
1280 .BR groupOfNames )
1281 whose DN exactly matches
1282 .BR pattern .
1283
1284 The currently supported limits are 
1285 .B size
1286 and 
1287 .BR time .
1288
1289 The syntax for time limits is 
1290 .BR time[.{soft|hard}]=<integer> ,
1291 where 
1292 .I integer
1293 is the number of seconds slapd will spend answering a search request.
1294 If no time limit is explicitly requested by the client, the 
1295 .BR soft
1296 limit is used; if the requested time limit exceeds the
1297 .BR hard
1298 .\"limit, an
1299 .\".I "Administrative limit exceeded"
1300 .\"error is returned.
1301 limit, the value of the limit is used instead.
1302 If the
1303 .BR hard
1304 limit is set to the keyword 
1305 .IR soft ,
1306 the soft limit is used in either case; if it is set to the keyword 
1307 .IR unlimited , 
1308 no hard limit is enforced.
1309 Explicit requests for time limits smaller or equal to the
1310 .BR hard 
1311 limit are honored.
1312 If no limit specifier is set, the value is assigned to the 
1313 .BR soft 
1314 limit, and the
1315 .BR hard
1316 limit is set to
1317 .IR soft ,
1318 to preserve the original behavior.
1319
1320 The syntax for size limits is
1321 .BR size[.{soft|hard|unchecked}]=<integer> ,
1322 where
1323 .I integer
1324 is the maximum number of entries slapd will return answering a search 
1325 request.
1326 If no size limit is explicitly requested by the client, the
1327 .BR soft
1328 limit is used; if the requested size limit exceeds the
1329 .BR hard
1330 .\"limit, an 
1331 .\".I "Administrative limit exceeded"
1332 .\"error is returned.
1333 limit, the value of the limit is used instead.
1334 If the 
1335 .BR hard
1336 limit is set to the keyword 
1337 .IR soft , 
1338 the soft limit is used in either case; if it is set to the keyword
1339 .IR unlimited , 
1340 no hard limit is enforced.
1341 Explicit requests for size limits smaller or equal to the
1342 .BR hard
1343 limit are honored.
1344 The
1345 .BR unchecked
1346 specifier sets a limit on the number of candidates a search request is allowed
1347 to examine.
1348 The rationale behind it is that searches for non-properly indexed
1349 attributes may result in large sets of candidates, which must be 
1350 examined by
1351 .BR slapd (8)
1352 to determine whether they match the search filter or not.
1353 The
1354 .B unchecked
1355 limit provides a means to drop such operations before they are even 
1356 started.
1357 If the selected candidates exceed the 
1358 .BR unchecked
1359 limit, the search will abort with 
1360 .IR "Unwilling to perform" .
1361 If it is set to the keyword 
1362 .IR unlimited , 
1363 no limit is applied (the default).
1364 If it is set to
1365 .IR disable ,
1366 the search is not even performed; this can be used to disallow searches
1367 for a specific set of users.
1368 If no limit specifier is set, the value is assigned to the
1369 .BR soft 
1370 limit, and the
1371 .BR hard
1372 limit is set to
1373 .IR soft ,
1374 to preserve the original behavior.
1375
1376 In case of no match, the global limits are used.
1377 The default values are the same as
1378 .B olcSizeLimit
1379 and
1380 .BR olcTimeLimit ;
1381 no limit is set on 
1382 .BR unchecked .
1383
1384 If 
1385 .B pagedResults
1386 control is requested, the 
1387 .B hard
1388 size limit is used by default, because the request of a specific page size
1389 is considered an explicit request for a limitation on the number
1390 of entries to be returned.
1391 However, the size limit applies to the total count of entries returned within
1392 the search, and not to a single page.
1393 Additional size limits may be enforced; the syntax is
1394 .BR size.pr={<integer>|noEstimate|unlimited} ,
1395 where
1396 .I integer
1397 is the max page size if no explicit limit is set; the keyword
1398 .I noEstimate
1399 inhibits the server from returning an estimate of the total number
1400 of entries that might be returned
1401 (note: the current implementation does not return any estimate).
1402 The keyword
1403 .I unlimited
1404 indicates that no limit is applied to the pagedResults control page size.
1405 The syntax
1406 .B size.prtotal={<integer>|unlimited|disabled}
1407 allows to set a limit on the total number of entries that a pagedResults
1408 control allows to return.
1409 By default it is set to the 
1410 .B hard
1411 limit.
1412 When set, 
1413 .I integer
1414 is the max number of entries that the whole search with pagedResults control
1415 can return.
1416 Use 
1417 .I unlimited
1418 to allow unlimited number of entries to be returned, e.g. to allow
1419 the use of the pagedResults control as a means to circumvent size 
1420 limitations on regular searches; the keyword
1421 .I disabled
1422 disables the control, i.e. no paged results can be returned.
1423 Note that the total number of entries returned when the pagedResults control 
1424 is requested cannot exceed the 
1425 .B hard 
1426 size limit of regular searches unless extended by the
1427 .B prtotal
1428 switch.
1429 .RE
1430 .TP
1431 .B olcMaxDerefDepth: <depth>
1432 Specifies the maximum number of aliases to dereference when trying to
1433 resolve an entry, used to avoid infinite alias loops. The default is 1.
1434 .TP
1435 .B olcMirrorMode: TRUE | FALSE
1436 This option puts a replica database into "mirror" mode.  Update
1437 operations will be accepted from any user, not just the updatedn.  The
1438 database must already be configured as syncrepl consumer
1439 before this keyword may be set.  This mode must be used with extreme
1440 care, as it does not offer any consistency guarantees.  This feature
1441 is intended to be used with an external frontend that guarantees that
1442 writes are only directed to a single master, switching to an alternate
1443 server only if the original master goes down.
1444 By default, this setting is FALSE.
1445 .TP
1446 .B olcPlugin: <plugin_type> <lib_path> <init_function> [<arguments>]
1447 Configure a SLAPI plugin. See the
1448 .BR slapd.plugin (5)
1449 manpage for more details.
1450 .\".HP
1451 .\".hy 0
1452 .\".B replica uri=ldap[s]://<hostname>[:port]|host=<hostname>[:port] 
1453 .\".B [starttls=yes|critical]
1454 .\".B [suffix=<suffix> [...]]
1455 .\".B bindmethod=simple|sasl [binddn=<simple DN>] [credentials=<simple password>]
1456 .\".B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>]
1457 .\".B [authcId=<authentication ID>] [authzId=<authorization ID>]
1458 .\".B [attrs[!]=<attr list>]
1459 .\".RS
1460 .\"Specify a replication site for this database.  Refer to the "OpenLDAP 
1461 .\"Administrator's Guide" for detailed information on setting up a replicated
1462 .\".B slapd
1463 .\"directory service. Zero or more
1464 .\".B suffix
1465 .\"instances can be used to select the subtrees that will be replicated
1466 .\"(defaults to all the database). 
1467 .\".B host
1468 .\"is deprecated in favor of the
1469 .\".B uri
1470 .\"option.
1471 .\".B uri
1472 .\"allows the replica LDAP server to be specified as an LDAP URI. 
1473 .\"A
1474 .\".B bindmethod
1475 .\"of
1476 .\".B simple
1477 .\"requires the options
1478 .\".B binddn 
1479 .\"and
1480 .\".B credentials  
1481 .\"and should only be used when adequate security services 
1482 .\"(e.g TLS or IPSEC) are in place. A
1483 .\".B bindmethod 
1484 .\"of
1485 .\".B sasl 
1486 .\"requires the option
1487 .\".B saslmech. 
1488 .\"Specific security properties (as with the
1489 .\".B sasl-secprops
1490 .\"keyword above) for a SASL bind can be set with the
1491 .\".B secprops
1492 .\"option. A non-default SASL realm can be set with the
1493 .\".B realm
1494 .\"option.
1495 .\"If the 
1496 .\".B mechanism
1497 .\"will use Kerberos, a kerberos instance should be given in 
1498 .\".B authcId.
1499 .\"An
1500 .\".B attr list
1501 .\"can be given after the 
1502 .\".B attrs
1503 .\"keyword to allow the selective replication of the listed attributes only;
1504 .\"if the optional 
1505 .\".B !
1506 .\"mark is used, the list is considered exclusive, i.e. the listed attributes
1507 .\"are not replicated.
1508 .\"If an objectClass is listed, all the related attributes
1509 .\"are (are not) replicated.
1510 .\".RE
1511 .\".TP
1512 .\".B replogfile <filename>
1513 .\"Specify the name of the replication log file to log changes to.  
1514 .\"The replication log is typically written by
1515 .\".BR slapd (8)
1516 .\"and read by
1517 .\".BR slurpd (8).
1518 .\"See
1519 .\".BR slapd.replog (5)
1520 .\"for more information.  The specified file should be located
1521 .\"in a directory with limited read/write/execute access as the replication
1522 .\"logs may contain sensitive information.
1523 .TP
1524 .B olcRootDN: <dn>
1525 Specify the distinguished name that is not subject to access control 
1526 or administrative limit restrictions for operations on this database.
1527 This DN may or may not be associated with an entry.  An empty root
1528 DN (the default) specifies no root access is to be granted.  It is
1529 recommended that the rootdn only be specified when needed (such as
1530 when initially populating a database).  If the rootdn is within
1531 a namingContext (suffix) of the database, a simple bind password
1532 may also be provided using the
1533 .B olcRootPW
1534 directive. Note that the rootdn is always needed when using syncrepl.
1535 .TP
1536 .B olcRootPW: <password>
1537 Specify a password (or hash of the password) for the rootdn.  The
1538 password can only be set if the rootdn is within the namingContext
1539 (suffix) of the database.
1540 This option accepts all RFC 2307 userPassword formats known to
1541 the server (see 
1542 .B olcPasswordHash
1543 description) as well as cleartext.
1544 .BR slappasswd (8) 
1545 may be used to generate a hash of a password.  Cleartext
1546 and \fB{CRYPT}\fP passwords are not recommended.  If empty
1547 (the default), authentication of the root DN is by other means
1548 (e.g. SASL).  Use of SASL is encouraged.
1549 .TP
1550 .B olcSubordinate: [TRUE | FALSE | advertise]
1551 Specify that the current backend database is a subordinate of another
1552 backend database. A subordinate  database may have only one suffix. This
1553 option may be used to glue multiple databases into a single namingContext.
1554 If the suffix of the current database is within the namingContext of a
1555 superior database, searches against the superior database will be
1556 propagated to the subordinate as well. All of the databases
1557 associated with a single namingContext should have identical rootdns.
1558 Behavior of other LDAP operations is unaffected by this setting. In
1559 particular, it is not possible to use moddn to move an entry from
1560 one subordinate to another subordinate within the namingContext.
1561
1562 If the optional \fBadvertise\fP flag is supplied, the naming context of
1563 this database is advertised in the root DSE. The default is to hide this
1564 database context, so that only the superior context is visible.
1565
1566 If the slap tools
1567 .BR slapcat (8),
1568 .BR slapadd (8),
1569 or
1570 .BR slapindex (8)
1571 are used on the superior database, any glued subordinates that support
1572 these tools are opened as well.
1573
1574 Databases that are glued together should usually be configured with the
1575 same indices (assuming they support indexing), even for attributes that
1576 only exist in some of these databases. In general, all of the glued
1577 databases should be configured as similarly as possible, since the intent
1578 is to provide the appearance of a single directory.
1579
1580 Note that the subordinate functionality is implemented internally
1581 by the \fIglue\fP overlay and as such its behavior will interact with other
1582 overlays in use. By default, the glue overlay is automatically configured as
1583 the last overlay on the superior database. Its position on the database
1584 can be explicitly configured by setting an \fBoverlay glue\fP directive
1585 at the desired position. This explicit configuration is necessary e.g.
1586 when using the \fIsyncprov\fP overlay, which needs to follow \fIglue\fP
1587 in order to work over all of the glued databases. E.g.
1588 .RS
1589 .nf
1590         dn: olcDatabase={1}bdb,cn=config
1591         olcSuffix: dc=example,dc=com
1592         ...
1593
1594         dn: olcOverlay={0}glue,olcDatabase={1}bdb,cn=config
1595         ...
1596
1597         dn: olcOverlay={1}syncprov,olcDatabase={1}bdb,cn=config
1598         ...
1599 .fi
1600 .RE
1601 See the Overlays section below for more details.
1602 .TP
1603 .B olcSuffix: <dn suffix>
1604 Specify the DN suffix of queries that will be passed to this 
1605 backend database.  Multiple suffix lines can be given and at least one is 
1606 required for each database definition.
1607 If the suffix of one database is "inside" that of another, the database
1608 with the inner suffix must come first in the configuration file.
1609 .HP
1610 .hy 0
1611 .B olcSyncrepl: rid=<replica ID>
1612 .B provider=ldap[s]://<hostname>[:port]
1613 .B searchbase=<base DN>
1614 .B [type=refreshOnly|refreshAndPersist]
1615 .B [interval=dd:hh:mm:ss]
1616 .B [retry=[<retry interval> <# of retries>]+]
1617 .B [filter=<filter str>]
1618 .B [scope=sub|one|base|subord]
1619 .B [attrs=<attr list>]
1620 .B [exattrs=<attr list>]
1621 .B [attrsonly]
1622 .B [sizelimit=<limit>]
1623 .B [timelimit=<limit>]
1624 .B [schemachecking=on|off]
1625 .B [bindmethod=simple|sasl]
1626 .B [binddn=<dn>]
1627 .B [saslmech=<mech>]
1628 .B [authcid=<identity>]
1629 .B [authzid=<identity>]
1630 .B [credentials=<passwd>]
1631 .B [realm=<realm>]
1632 .B [secprops=<properties>]
1633 .B [starttls=yes|critical]
1634 .B [tls_cert=<file>]
1635 .B [tls_key=<file>]
1636 .B [tls_cacert=<file>]
1637 .B [tls_cacertdir=<path>]
1638 .B [tls_reqcert=never|allow|try|demand]
1639 .B [tls_ciphersuite=<ciphers>]
1640 .B [tls_crlcheck=none|peer|all]
1641 .B [logbase=<base DN>]
1642 .B [logfilter=<filter str>]
1643 .B [syncdata=default|accesslog|changelog]
1644 .RS
1645 Specify the current database as a replica which is kept up-to-date with the 
1646 master content by establishing the current
1647 .BR slapd (8)
1648 as a replication consumer site running a
1649 .B syncrepl
1650 replication engine.
1651 The replica content is kept synchronized to the master content using
1652 the LDAP Content Synchronization protocol. Refer to the
1653 "OpenLDAP Administrator's Guide" for detailed information on
1654 setting up a replicated
1655 .B slapd
1656 directory service using the 
1657 .B syncrepl
1658 replication engine.
1659
1660 .B rid
1661 identifies the current
1662 .B syncrepl
1663 directive within the replication consumer site.
1664 It is a non-negative integer having no more than three digits.
1665
1666 .B provider
1667 specifies the replication provider site containing the master content
1668 as an LDAP URI. If <port> is not given, the standard LDAP port number
1669 (389 or 636) is used.
1670
1671 The content of the
1672 .B syncrepl
1673 replica is defined using a search
1674 specification as its result set. The consumer
1675 .B slapd
1676 will send search requests to the provider
1677 .B slapd
1678 according to the search specification. The search specification includes
1679 .B searchbase, scope, filter, attrs, attrsonly, sizelimit,
1680 and
1681 .B timelimit
1682 parameters as in the normal search specification. The
1683 .B exattrs
1684 option may also be used to specify attributes that should be omitted
1685 from incoming entries.
1686 The \fBscope\fP defaults to \fBsub\fP, the \fBfilter\fP defaults to
1687 \fB(objectclass=*)\fP, and there is no default \fBsearchbase\fP. The
1688 \fBattrs\fP list defaults to \fB"*,+"\fP to return all user and operational
1689 attributes, and \fBattrsonly\fP and \fBexattrs\fP are unset by default.
1690 The \fBsizelimit\fP and \fBtimelimit\fP only
1691 accept "unlimited" and positive integers, and both default to "unlimited".
1692 Note, however, that any provider-side limits for the replication identity
1693 will be enforced by the provider regardless of the limits requested
1694 by the LDAP Content Synchronization operation, much like for any other
1695 search operation.
1696
1697 The LDAP Content Synchronization protocol has two operation types.
1698 In the
1699 .B refreshOnly
1700 operation, the next synchronization search operation
1701 is periodically rescheduled at an interval time (specified by 
1702 .B interval
1703 parameter; 1 day by default)
1704 after each synchronization operation finishes.
1705 In the
1706 .B refreshAndPersist
1707 operation, a synchronization search remains persistent in the provider slapd.
1708 Further updates to the master replica will generate
1709 .B searchResultEntry
1710 to the consumer slapd as the search responses to the persistent
1711 synchronization search.
1712
1713 If an error occurs during replication, the consumer will attempt to
1714 reconnect according to the
1715 .B retry
1716 parameter which is a list of the <retry interval> and <# of retries> pairs.
1717 For example, retry="60 10 300 3" lets the consumer retry every 60 seconds
1718 for the first 10 times and then retry every 300 seconds for the next 3
1719 times before stop retrying. The `+' in <# of retries> means indefinite
1720 number of retries until success.
1721
1722 The schema checking can be enforced at the LDAP Sync
1723 consumer site by turning on the
1724 .B schemachecking
1725 parameter. The default is off.
1726
1727 A
1728 .B bindmethod
1729 of 
1730 .B simple
1731 requires the options 
1732 .B binddn
1733 and 
1734 .B credentials
1735 and should only be used when adequate security services
1736 (e.g. TLS or IPSEC) are in place.
1737 A
1738 .B bindmethod
1739 of
1740 .B sasl
1741 requires the option
1742 .B saslmech.
1743 Depending on the mechanism, an authentication identity and/or
1744 credentials can be specified using
1745 .B authcid
1746 and
1747 .B credentials.
1748 The
1749 .B authzid
1750 parameter may be used to specify an authorization identity.
1751 Specific security properties (as with the
1752 .B sasl-secprops
1753 keyword above) for a SASL bind can be set with the
1754 .B secprops
1755 option. A non default SASL realm can be set with the
1756 .B realm 
1757 option.
1758 The provider, other than allow authentication of the syncrepl identity,
1759 should grant that identity appropriate access privileges to the data 
1760 that is being replicated (\fBaccess\fP directive), and appropriate time 
1761 and size limits (\fBlimits\fP directive).
1762
1763
1764 The
1765 .B starttls
1766 parameter specifies use of the StartTLS extended operation
1767 to establish a TLS session before Binding to the provider. If the
1768 .B critical
1769 argument is supplied, the session will be aborted if the StartTLS request
1770 fails. Otherwise the syncrepl session continues without TLS. The
1771 tls_reqcert setting defaults to "demand" and the other TLS settings
1772 default to the same as the main slapd TLS settings.
1773
1774 Rather than replicating whole entries, the consumer can query logs of
1775 data modifications. This mode of operation is referred to as \fIdelta
1776 syncrepl\fP. In addition to the above parameters, the
1777 .B logbase
1778 and
1779 .B logfilter
1780 parameters must be set appropriately for the log that will be used. The
1781 .B syncdata
1782 parameter must be set to either "accesslog" if the log conforms to the
1783 .BR slapo-accesslog (5)
1784 log format, or "changelog" if the log conforms
1785 to the obsolete \fIchangelog\fP format. If the
1786 .B syncdata
1787 parameter is omitted or set to "default" then the log parameters are
1788 ignored.
1789 .RE
1790 .TP
1791 .B olcUpdateDN: <dn>
1792 This option is only applicable in a slave
1793 database.
1794 It specifies the DN permitted to update (subject to access controls)
1795 the replica (typically, this is the DN
1796 .BR slurpd (8)
1797 binds to update the replica).  Generally, this DN
1798 .I should not
1799 be the same as the
1800 .B rootdn 
1801 used at the master.
1802 .TP
1803 .B olcUpdateRef: <url>
1804 Specify the referral to pass back when
1805 .BR slapd (8)
1806 is asked to modify a replicated local database.
1807 If multiple values are specified, each url is provided.
1808
1809 .SH DATABASE-SPECIFIC OPTIONS
1810 Each database may allow specific configuration options; they are
1811 documented separately in the backends' manual pages. See the
1812 .BR slapd.backends (5)
1813 manual page for an overview of available backends.
1814 .SH OVERLAYS
1815 An overlay is a piece of
1816 code that intercepts database operations in order to extend or change
1817 them. Overlays are pushed onto
1818 a stack over the database, and so they will execute in the reverse
1819 of the order in which they were configured and the database itself
1820 will receive control last of all.
1821
1822 Overlays must be configured as child entries of a specific database. The
1823 entry's RDN must be of the form
1824 .B olcOverlay={x}<overlaytype>
1825 and the entry must have the olcOverlayConfig objectClass. Normally the
1826 config engine generates the "{x}" index in the RDN automatically, so
1827 it can be omitted when initially loading these entries.
1828
1829 See the
1830 .BR slapd.overlays (5)
1831 manual page for an overview of available overlays.
1832 .SH EXAMPLES
1833 .LP
1834 Here is a short example of a configuration in LDIF suitable for use with
1835 .BR slapadd (8)
1836 :
1837 .LP
1838 .RS
1839 .nf
1840 dn: cn=config
1841 objectClass: olcGlobal
1842 cn: config
1843 olcPidFile: LOCALSTATEDIR/run/slapd.pid
1844 olcAttributeOptions: x-hidden lang-
1845
1846 dn: cn=schema,cn=config
1847 objectClass: olcSchemaConfig
1848 cn: schema
1849
1850 include: SYSCONFDIR/schema/core.ldif
1851
1852 dn: olcDatabase=frontend,cn=config
1853 objectClass: olcDatabaseConfig
1854 objectClass: olcFrontendConfig
1855 olcDatabase: frontend
1856 # Subtypes of "name" (e.g. "cn" and "ou") with the
1857 # option ";x-hidden" can be searched for/compared,
1858 # but are not shown.  See \fBslapd.access\fP(5).
1859 olcAccess: to attrs=name;x-hidden by * =cs
1860 # Protect passwords.  See \fBslapd.access\fP(5).
1861 olcAccess: to attrs=userPassword  by * auth
1862 # Read access to other attributes and entries.
1863 olcAccess: to * by * read
1864
1865 # set a rootpw for the config database so we can bind.
1866 # deny access to everyone else.
1867 dn: olcDatabase=config,cn=config
1868 objectClass: olcDatabaseConfig
1869 olcDatabase: config
1870 olcRootPW: {SSHA}XKYnrjvGT3wZFQrDD5040US592LxsdLy
1871 olcAccess: to * by * none
1872
1873 dn: olcDatabase=bdb,cn=config
1874 objectClass: olcDatabaseConfig
1875 objectClass: olcBdbConfig
1876 olcDatabase: bdb
1877 olcSuffix: "dc=our-domain,dc=com"
1878 # The database directory MUST exist prior to
1879 # running slapd AND should only be accessible
1880 # by the slapd/tools. Mode 0700 recommended.
1881 olcDbDirectory: LOCALSTATEDIR/openldap-data
1882 # Indices to maintain
1883 olcDbIndex:     objectClass  eq
1884 olcDbIndex:     cn,sn,mail   pres,eq,approx,sub
1885
1886 # We serve small clients that do not handle referrals,
1887 # so handle remote lookups on their behalf.
1888 dn: olcDatabase=ldap,cn=config
1889 objectClass: olcDatabaseConfig
1890 objectClass: olcLdapConfig
1891 olcDatabase: ldap
1892 olcSuffix: ""
1893 olcDbUri: ldap://ldap.some-server.com/
1894 .fi
1895 .RE
1896 .LP
1897 Assuming the above data was saved in a file named "config.ldif" and the
1898 ETCDIR/slapd.d directory has been created, this command will initialize
1899 the configuration:
1900 .RS
1901 .nf
1902 slapadd -F ETCDIR/slapd.d -n 0 -l config.ldif
1903 .fi
1904 .RE
1905
1906 .LP
1907 "OpenLDAP Administrator's Guide" contains a longer annotated
1908 example of a slapd configuration.
1909
1910 Alternatively, an existing slapd.conf file can be converted to the new
1911 format using slapd or any of the slap tools:
1912 .RS
1913 .nf
1914 slaptest -f ETCDIR/slapd.conf -F ETCDIR/slapd.d
1915 .fi
1916 .RE
1917
1918 .SH FILES
1919 .TP
1920 ETCDIR/slapd.conf
1921 default slapd configuration file
1922 .TP
1923 ETCDIR/slapd.d
1924 default slapd configuration directory
1925 .SH SEE ALSO
1926 .BR ldap (3),
1927 .BR ldif (5),
1928 .BR slapd.access (5),
1929 .BR slapd.backends (5),
1930 .BR slapd.conf (5),
1931 .BR slapd.overlays (5),
1932 .BR slapd.plugin (5),
1933 .BR slapd.replog (5),
1934 .BR slapd (8),
1935 .BR slapacl (8),
1936 .BR slapadd (8),
1937 .BR slapauth (8),
1938 .BR slapcat (8),
1939 .BR slapdn (8),
1940 .BR slapindex (8),
1941 .BR slappasswd (8),
1942 .BR slaptest (8),
1943 .BR slurpd (8).
1944 .LP
1945 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
1946 .SH ACKNOWLEDGEMENTS
1947 .so ../Project