]> git.sur5r.net Git - openldap/blob - doc/guide/admin/slapdconf2.sdf
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / guide / admin / slapdconf2.sdf
1 # $OpenLDAP$
2 # Copyright 2005-2012 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5 H1: Configuring slapd
6
7 Once the software has been built and installed, you are ready
8 to configure {{slapd}}(8) for use at your site.
9
10 OpenLDAP 2.3 and later have transitioned to using a dynamic runtime
11 configuration engine, {{slapd-config}}(5).  {{slapd-config}}(5)
12 * is fully LDAP-enabled
13 * is managed using the standard LDAP operations
14 * stores its configuration data in an {{TERM:LDIF}} database, generally
15 in the {{F:/usr/local/etc/openldap/slapd.d}} directory.
16 * allows all of slapd's configuration options to be changed on the fly,
17 generally without requiring a server restart for the changes
18 to take effect.
19
20 This chapter describes the general format of the {{slapd-config}}(5)
21 configuration system, followed by a detailed description of commonly used
22 settings.
23
24 The older style {{slapd.conf}}(5) file is still supported, but its use
25 is deprecated and support for it will be withdrawn in a future OpenLDAP
26 release.  Configuring {{slapd}}(8) via {{slapd.conf}}(5) is described in
27 the next chapter.
28
29 Refer to {{slapd}}(8) for information on how to have slapd automatically
30 convert from {{slapd.conf}}(5) to {{slapd-config}}(5).
31
32
33 Note: Although the {{slapd-config}}(5) system stores its configuration
34 as (text-based) LDIF files, you should {{1:never}} edit any of
35 the LDIF files directly.  Configuration changes should be performed via LDAP
36 operations, e.g. {{ldapadd}}(1), {{ldapdelete}}(1), or {{ldapmodify}}(1).
37
38
39 Note: You will need to continue to use the older {{slapd.conf}}(5)
40 configuration system if your OpenLDAP installation requires the use of one
41 or more backends or overlays that have not been updated to use the
42 {{slapd-config}}(5) system.  As of OpenLDAP 2.4.25, the only official backends
43 that have not yet been updated to use {{slapd-config}}(5) are {{slapd-meta}}(5)
44 and {{slapd-sql}}(5).  There may be additional contributed or experimental
45 overlays that also have not been updated.
46
47
48 H2: Configuration Layout
49
50 The slapd configuration is stored as a special LDAP directory with
51 a predefined schema and DIT. There are specific objectClasses used to
52 carry global configuration options, schema definitions, backend and
53 database definitions, and assorted other items. A sample config tree
54 is shown in Figure 5.1.
55
56 !import "config_dit.png"; align="center"; title="Sample configuration tree"
57 FT[align="Center"] Figure 5.1: Sample configuration tree.
58
59 Other objects may be part of the configuration but were omitted from
60 the illustration for clarity.
61
62 The {{slapd-config}} configuration tree has a very specific structure. The
63 root of the tree is named {{EX:cn=config}} and contains global configuration
64 settings. Additional settings are contained in separate child entries:
65 * Dynamically loaded modules
66 .. These may only be used if the {{EX:--enable-modules}} option was
67 used to configure the software.
68 * Schema definitions
69 .. The {{EX:cn=schema,cn=config}} entry contains the system schema (all
70 the schema that is hard-coded in slapd).
71 .. Child entries of {{EX:cn=schema,cn=config}} contain user schema as
72 loaded from config files or added at runtime.
73 * Backend-specific configuration 
74 * Database-specific configuration
75 .. Overlays are defined in children of the Database entry.
76 .. Databases and Overlays may also have other miscellaneous children.
77
78 The usual rules for LDIF files apply to the configuration information:
79 Comment lines beginning with a '{{EX:#}}' character
80 are ignored.  If a line begins with a single space, it is considered a
81 continuation of the previous line (even if the previous line is a
82 comment) and the single leading space is removed. Entries are separated by blank lines.
83
84 The general layout of the config LDIF is as follows:
85
86 >       # global configuration settings
87 >       dn: cn=config
88 >       objectClass: olcGlobal
89 >       cn: config
90 >       <global config settings>
91 >
92 >       # schema definitions
93 >       dn: cn=schema,cn=config
94 >       objectClass: olcSchemaConfig
95 >       cn: schema
96 >       <system schema>
97 >
98 >       dn: cn={X}core,cn=schema,cn=config
99 >       objectClass: olcSchemaConfig
100 >       cn: {X}core
101 >       <core schema>
102 >
103 >       # additional user-specified schema
104 >       ...
105 >
106 >       # backend definitions
107 >       dn: olcBackend=<typeA>,cn=config
108 >       objectClass: olcBackendConfig
109 >       olcBackend: <typeA>
110 >       <backend-specific settings>
111 >
112 >       # database definitions
113 >       dn: olcDatabase={X}<typeA>,cn=config
114 >       objectClass: olcDatabaseConfig
115 >       olcDatabase: {X}<typeA>
116 >       <database-specific settings>
117 >
118 >       # subsequent definitions and settings
119 >       ...
120
121 Some of the entries listed above have a numeric index {{EX:"{X}"}} in
122 their names. While most configuration settings have an inherent ordering
123 dependency (i.e., one setting must take effect before a subsequent one
124 may be set), LDAP databases are inherently unordered. The numeric index
125 is used to enforce a consistent ordering in the configuration database,
126 so that all ordering dependencies are preserved. In most cases the index
127 does not have to be provided; it will be automatically generated based
128 on the order in which entries are created.
129
130 Configuration directives are specified as values of individual
131 attributes.
132 Most of the attributes and objectClasses used in the slapd
133 configuration have a prefix of {{EX:"olc"}} (OpenLDAP Configuration)
134 in their names. Generally there is a one-to-one correspondence
135 between the attributes and the old-style {{EX:slapd.conf}} configuration
136 keywords, using the keyword as the attribute name, with the "olc"
137 prefix attached.
138
139 A configuration directive may take arguments.  If so, the arguments are
140 separated by whitespace.  If an argument contains whitespace,
141 the argument should be enclosed in double quotes {{EX:"like this"}}.
142 In the descriptions that follow, arguments that should be replaced
143 by actual text are shown in brackets {{EX:<>}}.
144
145 The distribution contains an example configuration file that will
146 be installed in the {{F: /usr/local/etc/openldap}} directory.
147 A number of files containing schema definitions (attribute types
148 and object classes) are also provided in the
149 {{F: /usr/local/etc/openldap/schema}} directory.
150
151
152 H2: Configuration Directives
153
154 This section details commonly used configuration directives.  For
155 a complete list, see the {{slapd-config}}(5) manual page.  This section
156 will treat the configuration directives in a top-down order, starting
157 with the global directives in the {{EX:cn=config}} entry. Each
158 directive will be described along with its default value (if any) and
159 an example of its use.
160
161
162 H3: cn=config
163
164 Directives contained in this entry generally apply to the server as a whole.
165 Most of them are system or connection oriented, not database related. This
166 entry must have the {{EX:olcGlobal}} objectClass.
167
168
169 H4: olcIdleTimeout: <integer>
170
171 Specify the number of seconds to wait before forcibly closing
172 an idle client connection.  A value of 0, the default,
173 disables this feature.
174
175
176 H4: olcLogLevel: <level>
177
178 This directive specifies the level at which debugging statements
179 and operation statistics should be syslogged (currently logged to
180 the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have
181 configured OpenLDAP {{EX:--enable-debug}} (the default) for this
182 to work (except for the two statistics levels, which are always
183 enabled). Log levels may be specified as integers or by keyword.
184 Multiple log levels may be used and the levels are additive.
185 To display what levels
186 correspond to what kind of debugging, invoke slapd with {{EX:-d?}}
187 or consult the table below. The possible values for <level> are:
188
189 !block table; colaligns="RL"; align=Center; \
190         title="Table 5.1: Debugging Levels"
191 Level   Keyword         Description
192 -1      any             enable all debugging
193 0                       no debugging
194 1       (0x1 trace)     trace function calls
195 2       (0x2 packets)   debug packet handling
196 4       (0x4 args)      heavy trace debugging
197 8       (0x8 conns)     connection management
198 16      (0x10 BER)      print out packets sent and received
199 32      (0x20 filter)   search filter processing
200 64      (0x40 config)   configuration processing
201 128     (0x80 ACL)      access control list processing
202 256     (0x100 stats)   stats log connections/operations/results
203 512     (0x200 stats2)  stats log entries sent
204 1024    (0x400 shell)   print communication with shell backends
205 2048    (0x800 parse)   print entry parsing debugging
206 16384   (0x4000 sync)   syncrepl consumer processing
207 32768   (0x8000 none)   only messages that get logged whatever log level is set
208 !endblock
209
210 The desired log level can be input as a single integer that
211 combines the (ORed) desired levels, both in decimal or in hexadecimal 
212 notation, as a list of integers (that are ORed internally), or as a list of the names that are shown between brackets, such that
213
214 >               olcLogLevel 129
215 >               olcLogLevel 0x81
216 >               olcLogLevel 128 1
217 >               olcLogLevel 0x80 0x1
218 >               olcLogLevel acl trace
219
220 are equivalent.
221
222 \Examples:
223
224 E: olcLogLevel -1
225
226 This will cause lots and lots of debugging information to be
227 logged.
228
229 E: olcLogLevel conns filter
230
231 Just log the connection and search filter processing.
232
233 E: olcLogLevel none
234
235 Log those messages that are logged regardless of the configured loglevel. This
236 differs from setting the log level to 0, when no logging occurs. At least the
237 {{EX:None}} level is required to have high priority messages logged.
238
239 \Default:
240
241 E: olcLogLevel stats
242
243 Basic stats logging is configured by default. However, if no olcLogLevel is
244 defined, no logging occurs (equivalent to a 0 level).
245
246
247 H4: olcReferral <URI>
248
249 This directive specifies the referral to pass back when slapd
250 cannot find a local database to handle a request.
251
252 \Example:
253
254 >       olcReferral: ldap://root.openldap.org
255
256 This will refer non-local queries to the global root LDAP server
257 at the OpenLDAP Project. Smart LDAP clients can re-ask their
258 query at that server, but note that most of these clients are
259 only going to know how to handle simple LDAP URLs that
260 contain a host part and optionally a distinguished name part.
261
262
263 H4: Sample Entry
264
265 >dn: cn=config
266 >objectClass: olcGlobal
267 >cn: config
268 >olcIdleTimeout: 30
269 >olcLogLevel: Stats
270 >olcReferral: ldap://root.openldap.org
271
272
273 H3: cn=module
274
275 If support for dynamically loaded modules was enabled when configuring
276 slapd, {{EX:cn=module}} entries may be used to specify sets of modules to load.
277 Module entries must have the {{EX:olcModuleList}} objectClass.
278
279
280 H4: olcModuleLoad: <filename>
281
282 Specify the name of a dynamically loadable module to load. The filename
283 may be an absolute path name or a simple filename. Non-absolute names
284 are searched for in the directories specified by the {{EX:olcModulePath}}
285 directive.
286
287
288 H4: olcModulePath: <pathspec>
289
290 Specify a list of directories to search for loadable modules. Typically the
291 path is colon-separated but this depends on the operating system.
292
293
294 H4: Sample Entries
295
296 >dn: cn=module{0},cn=config
297 >objectClass: olcModuleList
298 >cn: module{0}
299 >olcModuleLoad: /usr/local/lib/smbk5pwd.la
300 >
301 >dn: cn=module{1},cn=config
302 >objectClass: olcModuleList
303 >cn: module{1}
304 >olcModulePath: /usr/local/lib:/usr/local/lib/slapd
305 >olcModuleLoad: accesslog.la
306 >olcModuleLoad: pcache.la
307
308
309 H3: cn=schema
310
311 The cn=schema entry holds all of the schema definitions that are hard-coded
312 in slapd. As such, the values in this entry are generated by slapd so no
313 schema values need to be provided in the config file. The entry must still
314 be defined though, to serve as a base for the user-defined schema to add
315 in underneath. Schema entries must have the {{EX:olcSchemaConfig}}
316 objectClass.
317
318
319 H4: olcAttributeTypes: <{{REF:RFC4512}} Attribute Type Description>
320
321 This directive defines an attribute type.
322 Please see the {{SECT:Schema Specification}} chapter
323 for information regarding how to use this directive.
324
325
326 H4: olcObjectClasses: <{{REF:RFC4512}} Object Class Description>
327
328 This directive defines an object class.
329 Please see the {{SECT:Schema Specification}} chapter for
330 information regarding how to use this directive.
331
332
333 H4: Sample Entries
334
335 >dn: cn=schema,cn=config
336 >objectClass: olcSchemaConfig
337 >cn: schema
338 >
339 >dn: cn=test,cn=schema,cn=config
340 >objectClass: olcSchemaConfig
341 >cn: test
342 >olcAttributeTypes: ( 1.1.1
343 >  NAME 'testAttr'
344 >  EQUALITY integerMatch
345 >  SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 )
346 >olcAttributeTypes: ( 1.1.2 NAME 'testTwo' EQUALITY caseIgnoreMatch
347 >  SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 )
348 >olcObjectClasses: ( 1.1.3 NAME 'testObject'
349 >  MAY ( testAttr $ testTwo ) AUXILIARY )
350
351
352 H3: Backend-specific Directives
353
354 Backend directives apply to all database instances of the
355 same type and, depending on the directive, may be overridden
356 by database directives. Backend entries must have the
357 {{EX:olcBackendConfig}} objectClass.
358
359 H4: olcBackend: <type>
360
361 This directive names a backend-specific configuration entry.
362 {{EX:<type>}} should be one of the
363 supported backend types listed in Table 5.2.
364
365 !block table; align=Center; coltags="EX,N"; \
366         title="Table 5.2: Database Backends"
367 Types   Description
368 bdb     Berkeley DB transactional backend
369 config  Slapd configuration backend
370 dnssrv  DNS SRV backend
371 hdb     Hierarchical variant of bdb backend
372 ldap    Lightweight Directory Access Protocol (Proxy) backend
373 ldif    Lightweight Data Interchange Format backend
374 meta    Meta Directory backend
375 monitor Monitor backend
376 passwd  Provides read-only access to {{passwd}}(5)
377 perl    Perl Programmable backend
378 shell   Shell (extern program) backend
379 sql     SQL Programmable backend
380 !endblock
381
382 \Example:
383
384 >       olcBackend: bdb
385
386 There are no other directives defined for this entry.  Specific backend
387 types may define additional attributes for their particular use but so
388 far none have ever been defined.  As such, these directives usually do
389 not appear in any actual configurations.
390
391
392 H4: Sample Entry
393
394 > dn: olcBackend=bdb,cn=config
395 > objectClass: olcBackendConfig
396 > olcBackend: bdb
397
398
399 H3: Database-specific Directives
400
401 Directives in this section are supported by every type of database.
402 Database entries must have the {{EX:olcDatabaseConfig}} objectClass.
403
404 H4: olcDatabase: [{<index>}]<type>
405
406 This directive names a specific database instance. The numeric {<index>} may
407 be provided to distinguish multiple databases of the same type. Usually the
408 index can be omitted, and slapd will generate it automatically.
409 {{EX:<type>}} should be one of the
410 supported backend types listed in Table 5.2 or the {{EX:frontend}} type.
411
412 The {{EX:frontend}} is a special database that is used to hold
413 database-level options that should be applied to all the other
414 databases. Subsequent database definitions may also override some
415 frontend settings.
416
417 The {{EX:config}} database is also special; both the {{EX:config}} and
418 the {{EX:frontend}} databases are always created implicitly even if they
419 are not explicitly configured, and they are created before any other
420 databases.
421
422 \Example:
423
424 >       olcDatabase: bdb
425
426 This marks the beginning of a new {{TERM:BDB}} database instance.
427
428
429 H4: olcAccess: to <what> [ by <who> [<accesslevel>] [<control>] ]+
430
431 This directive grants access (specified by <accesslevel>) to a
432 set of entries and/or attributes (specified by <what>) by one or
433 more requestors (specified by <who>).
434 See the {{SECT:Access Control}} section of this guide for basic usage.
435
436 !if 0
437 More detailed discussion of this directive can be found in the
438 {{SECT:Advanced Access Control}} chapter.
439 !endif
440
441 Note: If no {{EX:olcAccess}} directives are specified, the default
442 access control policy, {{EX:to * by * read}}, allows all
443 users (both authenticated and anonymous) read access.
444
445 Note: Access controls defined in the frontend are appended to all
446 other databases' controls.
447
448
449 H4: olcReadonly { TRUE | FALSE }
450
451 This directive puts the database into "read-only" mode. Any
452 attempts to modify the database will return an "unwilling to
453 perform" error.
454
455 \Default:
456
457 >       olcReadonly: FALSE
458
459
460 H4: olcRootDN: <DN>
461
462 This directive specifies the DN that is not subject to
463 access control or administrative limit restrictions for
464 operations on this database.  The DN need not refer to
465 an entry in this database or even in the directory. The
466 DN may refer to a SASL identity.
467
468 Entry-based Example:
469
470 >       olcRootDN: "cn=Manager,dc=example,dc=com"
471
472 SASL-based Example:
473
474 >       olcRootDN: "uid=root,cn=example.com,cn=digest-md5,cn=auth"
475
476 See the {{SECT:SASL Authentication}} section for information on
477 SASL authentication identities.
478
479
480 H4: olcRootPW: <password>
481
482 This directive can be used to specify a password for the DN for
483 the rootdn (when the rootdn is set to a DN within the database).
484
485 \Example:
486
487 >       olcRootPW: secret
488
489 It is also permissible to provide a hash of the password in
490 {{REF:RFC2307}} form.  {{slappasswd}}(8) may be used to generate
491 the password hash.
492
493 \Example:
494
495 >       olcRootPW: {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN
496
497 The hash was generated using the command {{EX:slappasswd -s secret}}.
498
499
500 H4: olcSizeLimit: <integer>
501
502 This directive specifies the maximum number of entries to return
503 from a search operation.
504
505 \Default:
506
507 >       olcSizeLimit: 500
508
509 See the {{SECT:Limits}} section of this guide and slapd-config(5)
510 for more details.
511
512
513 H4: olcSuffix: <dn suffix>
514
515 This directive specifies the DN suffix of queries that will be
516 passed to this backend database. Multiple suffix lines can be
517 given, and usually at least one is required for each database
518 definition. (Some backend types, such as {{EX:frontend}} and
519 {{EX:monitor}} use a hard-coded suffix which may not be overridden
520 in the configuration.)
521
522 \Example:
523
524 >       olcSuffix: "dc=example,dc=com"
525
526 Queries with a DN ending in "dc=example,dc=com"
527 will be passed to this backend.
528
529 Note: When the backend to pass a query to is selected, slapd
530 looks at the suffix value(s) in each database definition in the
531 order in which they were configured. Thus, if one database suffix is a
532 prefix of another, it must appear after it in the configuration.
533
534
535 H4: olcSyncrepl
536
537 >       olcSyncrepl: rid=<replica ID>
538 >               provider=ldap[s]://<hostname>[:port]
539 >               [type=refreshOnly|refreshAndPersist]
540 >               [interval=dd:hh:mm:ss]
541 >               [retry=[<retry interval> <# of retries>]+]
542 >               searchbase=<base DN>
543 >               [filter=<filter str>]
544 >               [scope=sub|one|base]
545 >               [attrs=<attr list>]
546 >               [attrsonly]
547 >               [sizelimit=<limit>]
548 >               [timelimit=<limit>]
549 >               [schemachecking=on|off]
550 >               [bindmethod=simple|sasl]
551 >               [binddn=<DN>]
552 >               [saslmech=<mech>]
553 >               [authcid=<identity>]
554 >               [authzid=<identity>]
555 >               [credentials=<passwd>]
556 >               [realm=<realm>]
557 >               [secprops=<properties>]
558 >               [starttls=yes|critical]
559 >               [tls_cert=<file>]
560 >               [tls_key=<file>]
561 >               [tls_cacert=<file>]
562 >               [tls_cacertdir=<path>]
563 >               [tls_reqcert=never|allow|try|demand]
564 >               [tls_ciphersuite=<ciphers>]
565 >               [tls_crlcheck=none|peer|all]
566 >               [logbase=<base DN>]
567 >               [logfilter=<filter str>]
568 >               [syncdata=default|accesslog|changelog]
569
570
571 This directive specifies the current database as a replica of the
572 master content by establishing the current {{slapd}}(8) as a
573 replication consumer site running a syncrepl replication engine.
574 The master database is located at the replication provider site
575 specified by the {{EX:provider}} parameter. The replica database is
576 kept up-to-date with the master content using the LDAP Content
577 Synchronization protocol. See {{REF:RFC4533}}
578 for more information on the protocol.
579
580 The {{EX:rid}} parameter is used for identification of the current
581 {{EX:syncrepl}} directive within the replication consumer server,
582 where {{EX:<replica ID>}} uniquely identifies the syncrepl specification
583 described by the current {{EX:syncrepl}} directive. {{EX:<replica ID>}}
584 is non-negative and is no more than three decimal digits in length.
585
586 The {{EX:provider}} parameter specifies the replication provider site
587 containing the master content as an LDAP URI. The {{EX:provider}}
588 parameter specifies a scheme, a host and optionally a port where the
589 provider slapd instance can be found. Either a domain name or IP
590 address may be used for <hostname>. Examples are
591 {{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}.
592 If <port> is not given, the standard LDAP port number (389 or 636) is used.
593 Note that the syncrepl uses a consumer-initiated protocol, and hence its
594 specification is located at the consumer site, whereas the {{EX:replica}}
595 specification is located at the provider site. {{EX:syncrepl}} and
596 {{EX:replica}} directives define two independent replication
597 mechanisms. They do not represent the replication peers of each other.
598
599 The content of the syncrepl replica is defined using a search
600 specification as its result set. The consumer slapd will
601 send search requests to the provider slapd according to the search
602 specification. The search specification includes {{EX:searchbase}},
603 {{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:attrsonly}},
604 {{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal
605 search specification. The {{EX:searchbase}} parameter has no
606 default value and must always be specified. The {{EX:scope}} defaults
607 to {{EX:sub}}, the {{EX:filter}} defaults to {{EX:(objectclass=*)}},
608 {{EX:attrs}} defaults to {{EX:"*,+"}} to replicate all user and operational
609 attributes, and {{EX:attrsonly}} is unset by default. Both {{EX:sizelimit}}
610 and {{EX:timelimit}} default to "unlimited", and only positive integers
611 or "unlimited" may be specified.
612
613 The {{TERM[expand]LDAP Sync}} protocol has two operation
614 types: {{EX:refreshOnly}} and {{EX:refreshAndPersist}}.
615 The operation type is specified by the {{EX:type}} parameter.
616 In the {{EX:refreshOnly}} operation, the next synchronization search operation
617 is periodically rescheduled at an interval time after each
618 synchronization operation finishes. The interval is specified
619 by the {{EX:interval}} parameter. It is set to one day by default.
620 In the {{EX:refreshAndPersist}} operation, a synchronization search
621 remains persistent in the provider {{slapd}} instance. Further updates to the
622 master replica will generate {{EX:searchResultEntry}} to the consumer slapd
623 as the search responses to the persistent synchronization search.
624
625 If an error occurs during replication, the consumer will attempt to reconnect
626 according to the retry parameter which is a list of the <retry interval>
627 and <# of retries> pairs. For example, retry="60 10 300 3" lets the consumer
628 retry every 60 seconds for the first 10 times and then retry every 300 seconds
629 for the next three times before stop retrying. + in <#  of retries> means
630 indefinite number of retries until success.
631
632 The schema checking can be enforced at the LDAP Sync consumer site
633 by turning on the {{EX:schemachecking}} parameter.
634 If it is turned on, every replicated entry will be checked for its
635 schema as the entry is stored into the replica content.
636 Every entry in the replica should contain those attributes
637 required by the schema definition.
638 If it is turned off, entries will be stored without checking
639 schema conformance. The default is off.
640
641 The {{EX:binddn}} parameter gives the DN to bind as for the
642 syncrepl searches to the provider slapd. It should be a DN
643 which has read access to the replication content in the
644 master database. 
645
646 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
647 depending on whether simple password-based authentication or
648 {{TERM:SASL}} authentication is to be used when connecting
649 to the provider {{slapd}} instance.
650
651 Simple authentication should not be used unless adequate data
652 integrity and confidentiality protections are in place (e.g. TLS
653 or IPsec). Simple authentication requires specification of {{EX:binddn}}
654 and {{EX:credentials}} parameters.
655
656 SASL authentication is generally recommended.  SASL authentication
657 requires specification of a mechanism using the {{EX:saslmech}} parameter.
658 Depending on the mechanism, an authentication identity and/or
659 credentials can be specified using {{EX:authcid}} and {{EX:credentials}},
660 respectively.  The {{EX:authzid}} parameter may be used to specify
661 an authorization identity.
662
663 The {{EX:realm}} parameter specifies a realm which a certain
664 mechanisms authenticate the identity within. The {{EX:secprops}}
665 parameter specifies Cyrus SASL security properties.
666
667 The {{EX:starttls}} parameter specifies use of the StartTLS extended
668 operation to establish a TLS session before authenticating to the provider.
669 If the {{EX:critical}} argument is supplied, the session will be aborted
670 if the StartTLS request fails.  Otherwise the syncrepl session continues
671 without TLS.  Note that the main slapd TLS settings are not used by the
672 syncrepl engine; by default the TLS parameters from a {{ldap.conf}}(5)
673 configuration file will be used.  TLS settings may be specified here,
674 in which case any {{ldap.conf}}(5) settings will be completely ignored.
675
676 Rather than replicating whole entries, the consumer can query logs
677 of data modifications.  This mode of operation is referred to as
678 {{delta syncrepl}}.  In addition to the above parameters, the
679 {{EX:logbase}} and {{EX:logfilter}} parameters must be set appropriately
680 for the log that will be used. The {{EX:syncdata}} parameter must
681 be set to either {{EX:"accesslog"}} if the log conforms to the
682 {{slapo-accesslog}}(5) log format, or {{EX:"changelog"}} if the log
683 conforms to the obsolete {{changelog}} format. If the {{EX:syncdata}}
684 parameter is omitted or set to {{EX:"default"}} then the log
685 parameters are ignored.
686
687 The {{syncrepl}} replication mechanism is supported by the {{bdb}} and
688 {{hdb}} backends.
689
690 See the {{SECT:LDAP Sync Replication}} chapter of this guide for
691 more information on how to use this directive.
692
693
694 H4: olcTimeLimit: <integer>
695
696 This directive specifies the maximum number of seconds (in real
697 time) slapd will spend answering a search request. If a
698 request is not finished in this time, a result indicating an
699 exceeded timelimit will be returned.
700
701 \Default:
702
703 >       olcTimeLimit: 3600
704
705 See the {{SECT:Limits}} section of this guide and slapd-config(5)
706 for more details.
707
708
709 H4: olcUpdateref: <URL>
710
711 This directive is only applicable in a slave slapd. It
712 specifies the URL to return to clients which submit update
713 requests upon the replica.
714 If specified multiple times, each {{TERM:URL}} is provided.
715
716 \Example:
717
718 >       olcUpdateref:   ldap://master.example.net
719
720
721 H4: Sample Entries
722
723 >dn: olcDatabase=frontend,cn=config
724 >objectClass: olcDatabaseConfig
725 >objectClass: olcFrontendConfig
726 >olcDatabase: frontend
727 >olcReadOnly: FALSE
728 >
729 >dn: olcDatabase=config,cn=config
730 >objectClass: olcDatabaseConfig
731 >olcDatabase: config
732 >olcRootDN: cn=Manager,dc=example,dc=com
733
734
735 H3: BDB and HDB Database Directives
736
737 Directives in this category apply to both the {{TERM:BDB}}
738 and the {{TERM:HDB}} database.
739 They are used in an olcDatabase entry in addition to the generic
740 database directives defined above.  For a complete reference
741 of BDB/HDB configuration directives, see {{slapd-bdb}}(5). In
742 addition to the {{EX:olcDatabaseConfig}} objectClass, BDB and HDB
743 database entries must have the {{EX:olcBdbConfig}} and
744 {{EX:olcHdbConfig}} objectClass, respectively.
745
746
747 H4: olcDbDirectory: <directory>
748
749 This directive specifies the directory where the BDB files
750 containing the database and associated indices live.
751
752 \Default:
753
754 >       olcDbDirectory: /usr/local/var/openldap-data
755
756
757 H4: olcDbCachesize: <integer>
758
759 This directive specifies the size in entries of the in-memory
760 cache maintained by the BDB backend database instance.
761
762 \Default:
763
764 >       olcDbCachesize: 1000
765
766
767 H4: olcDbCheckpoint: <kbyte> <min>
768
769 This directive specifies how often to checkpoint the BDB transaction log.
770 A checkpoint operation flushes the database buffers to disk and writes a
771 checkpoint record in the log.
772 The checkpoint will occur if either <kbyte> data has been written or
773 <min> minutes have passed since the last checkpoint. Both arguments default
774 to zero, in which case they are ignored. When the <min> argument is
775 non-zero, an internal task will run every <min> minutes to perform the
776 checkpoint. See the Berkeley DB reference guide for more details.
777
778 \Example:
779
780 >       olcDbCheckpoint: 1024 10
781
782
783 H4: olcDbConfig: <DB_CONFIG setting>
784
785 This attribute specifies a configuration directive to be placed in the
786 {{EX:DB_CONFIG}} file of the database directory. At server startup time, if
787 no such file exists yet, the {{EX:DB_CONFIG}} file will be created and the
788 settings in this attribute will be written to it. If the file exists,
789 its contents will be read and displayed in this attribute. The attribute
790 is multi-valued, to accommodate multiple configuration directives. No default
791 is provided, but it is essential to use proper settings here to get the
792 best server performance.
793
794 Any changes made to this attribute will be written to the {{EX:DB_CONFIG}}
795 file and will cause the database environment to be reset so the changes
796 can take immediate effect. If the environment cache is large and has not
797 been recently checkpointed, this reset operation may take a long time. It
798 may be advisable to manually perform a single checkpoint using the Berkeley DB
799 {{db_checkpoint}} utility before using LDAP Modify to change this
800 attribute.
801
802 \Example:
803
804 >       olcDbConfig: set_cachesize 0 10485760 0
805 >       olcDbConfig: set_lg_bsize 2097512
806 >       olcDbConfig: set_lg_dir /var/tmp/bdb-log
807 >       olcDbConfig: set_flags DB_LOG_AUTOREMOVE
808
809 In this example, the BDB cache is set to 10MB, the BDB transaction log
810 buffer size is set to 2MB, and the transaction log files are to be stored
811 in the /var/tmp/bdb-log directory. Also a flag is set to tell BDB to
812 delete transaction log files as soon as their contents have been
813 checkpointed and they are no longer needed. Without this setting the
814 transaction log files will continue to accumulate until some other
815 cleanup procedure removes them. See the Berkeley DB documentation for the
816 {{EX:db_archive}} command for details. For a complete list of Berkeley DB 
817 flags please see - {{URL:http://www.oracle.com/technology/documentation/berkeley-db/db/api_c/env_set_flags.html}}
818
819 Ideally the BDB cache must be
820 at least as large as the working set of the database, the log buffer size
821 should be large enough to accommodate most transactions without overflowing,
822 and the log directory must be on a separate physical disk from the main
823 database files. And both the database directory and the log directory
824 should be separate from disks used for regular system activities such as
825 the root, boot, or swap filesystems. See the FAQ-o-Matic and the Berkeley DB
826 documentation for more details.
827
828
829 H4: olcDbNosync: { TRUE | FALSE }
830
831 This option causes on-disk database contents to not be immediately
832 synchronized with in memory changes upon change.  Setting this option
833 to {{EX:TRUE}} may improve performance at the expense of data integrity. This
834 directive has the same effect as using
835 >       olcDbConfig: set_flags DB_TXN_NOSYNC
836
837
838 H4: olcDbIDLcacheSize: <integer>
839
840 Specify the size of the in-memory index cache, in index slots. The
841 default is zero. A larger value will speed up frequent searches of
842 indexed entries. The optimal size will depend on the data and search
843 characteristics of the database, but using a number three times
844 the entry cache size is a good starting point.
845
846 \Example:
847
848 >       olcDbIDLcacheSize: 3000
849
850
851 H4: olcDbIndex: {<attrlist> | default} [pres,eq,approx,sub,none]
852
853 This directive specifies the indices to maintain for the given
854 attribute. If only an {{EX:<attrlist>}} is given, the default
855 indices are maintained. The index keywords correspond to the
856 common types of matches that may be used in an LDAP search filter.
857
858 \Example:
859
860 >       olcDbIndex: default pres,eq
861 >       olcDbIndex: uid
862 >       olcDbIndex: cn,sn pres,eq,sub
863 >       olcDbIndex: objectClass eq
864
865 The first line sets the default set of indices to maintain to
866 present and equality.  The second line causes the default (pres,eq)
867 set of indices to be maintained for the {{EX:uid}} attribute type.
868 The third line causes present, equality, and substring indices to
869 be maintained for {{EX:cn}} and {{EX:sn}} attribute types.  The
870 fourth line causes an equality index for the {{EX:objectClass}}
871 attribute type.
872
873 There is no index keyword for inequality matches. Generally these
874 matches do not use an index. However, some attributes do support
875 indexing for inequality matches, based on the equality index.
876
877 A substring index can be more explicitly specified as {{EX:subinitial}},
878 {{EX:subany}}, or {{EX:subfinal}}, corresponding to the three 
879 possible components
880 of a substring match filter. A subinitial index only indexes
881 substrings that appear at the beginning of an attribute value.
882 A subfinal index only indexes substrings that appear at the end
883 of an attribute value, while subany indexes substrings that occur
884 anywhere in a value.
885
886 Note that by default, setting an index for an attribute also
887 affects every subtype of that attribute. E.g., setting an equality
888 index on the {{EX:name}} attribute causes {{EX:cn}}, {{EX:sn}}, and every other
889 attribute that inherits from {{EX:name}} to be indexed.
890
891 By default, no indices are maintained.  It is generally advised
892 that minimally an equality index upon objectClass be maintained.
893
894 >       olcDbindex: objectClass eq
895
896 Additional indices should be configured corresponding to the
897 most common searches that are used on the database.
898 Presence indexing should not be configured for an attribute
899 unless the attribute occurs very rarely in the database, and
900 presence searches on the attribute occur very frequently during
901 normal use of the directory. Most applications don't use presence
902 searches, so usually presence indexing is not very useful.
903
904 If this setting is changed while slapd is running, an internal task
905 will be run to generate the changed index data. All server operations
906 can continue as normal while the indexer does its work.  If slapd is
907 stopped before the index task completes, indexing will have to be
908 manually completed using the slapindex tool.
909
910
911 H4: olcDbLinearIndex: { TRUE | FALSE }
912
913 If this setting is {{EX:TRUE}} slapindex will index one attribute
914 at a time. The default settings is {{EX:FALSE}} in which case all
915 indexed attributes of an entry are processed at the same time. When
916 enabled, each indexed attribute is processed individually, using
917 multiple passes through the entire database. This option improves
918 slapindex performance when the database size exceeds the BDB cache
919 size. When the BDB cache is large enough, this option is not needed
920 and will decrease performance. Also by default, slapadd performs
921 full indexing and so a separate slapindex run is not needed. With
922 this option, slapadd does no indexing and slapindex must be used.
923
924
925 H4: olcDbMode: { <octal> | <symbolic> }
926
927 This directive specifies the file protection mode that newly
928 created database index files should have. This can be in the form
929 {{EX:0600}} or {{EX:-rw-------}}
930
931 \Default:
932
933 >       olcDbMode: 0600
934
935
936 H4: olcDbSearchStack: <integer>
937
938 Specify the depth of the stack used for search filter evaluation.
939 Search filters are evaluated on a stack to accommodate nested {{EX:AND}} /
940 {{EX:OR}} clauses. An individual stack is allocated for each server thread.
941 The depth of the stack determines how complex a filter can be evaluated
942 without requiring any additional memory allocation. Filters that are
943 nested deeper than the search stack depth will cause a separate stack to
944 be allocated for that particular search operation. These separate allocations
945 can have a major negative impact on server performance, but specifying
946 too much stack will also consume a great deal of memory. Each search
947 uses 512K bytes per level on a 32-bit machine, or 1024K bytes per level
948 on a 64-bit machine. The default stack depth is 16, thus 8MB or 16MB
949 per thread is used on 32 and 64 bit machines, respectively. Also the
950 512KB size of a single stack slot is set by a compile-time constant which
951 may be changed if needed; the code must be recompiled for the change
952 to take effect.
953
954 \Default:
955
956 >       olcDbSearchStack: 16
957
958
959 H4: olcDbShmKey: <integer>
960
961 Specify a key for a shared memory BDB environment. By default the BDB
962 environment uses memory mapped files. If a non-zero value is specified,
963 it will be used as the key to identify a shared memory region that will
964 house the environment.
965
966 \Example:
967
968 >       olcDbShmKey: 42
969
970
971 H4: Sample Entry
972
973 >dn: olcDatabase=hdb,cn=config
974 >objectClass: olcDatabaseConfig
975 >objectClass: olcHdbConfig
976 >olcDatabase: hdb
977 >olcSuffix: "dc=example,dc=com"
978 >olcDbDirectory: /usr/local/var/openldap-data
979 >olcDbCacheSize: 1000
980 >olcDbCheckpoint: 1024 10
981 >olcDbConfig: set_cachesize 0 10485760 0
982 >olcDbConfig: set_lg_bsize 2097152
983 >olcDbConfig: set_lg_dir /var/tmp/bdb-log
984 >olcDbConfig: set_flags DB_LOG_AUTOREMOVE
985 >olcDbIDLcacheSize: 3000
986 >olcDbIndex: objectClass eq
987
988
989 H2: Configuration Example
990
991 The following is an example configuration, interspersed
992 with explanatory text. It defines two databases to handle
993 different parts of the {{TERM:X.500}} tree; both are {{TERM:BDB}}
994 database instances. The line numbers shown are provided for
995 reference only and are not included in the actual file. First, the
996 global configuration section:
997
998 E:  1.    # example config file - global configuration entry
999 E:  2.    dn: cn=config
1000 E:  3.    objectClass: olcGlobal
1001 E:  4.    cn: config
1002 E:  5.    olcReferral: ldap://root.openldap.org
1003 E:  6.    
1004
1005 Line 1 is a comment. Lines 2-4 identify this as the global
1006 configuration entry.
1007 The {{EX:olcReferral:}} directive on line 5
1008 means that queries not local to one of the databases defined
1009 below will be referred to the LDAP server running on the
1010 standard port (389) at the host {{EX:root.openldap.org}}.
1011 Line 6 is a blank line, indicating the end of this entry.
1012
1013 E:  7.    # internal schema
1014 E:  8.    dn: cn=schema,cn=config
1015 E:  9.    objectClass: olcSchemaConfig
1016 E: 10.    cn: schema
1017 E: 11.    
1018
1019 Line 7 is a comment. Lines 8-10 identify this as the root of
1020 the schema subtree. The actual schema definitions in this entry
1021 are hardcoded into slapd so no additional attributes are specified here.
1022 Line 11 is a blank line, indicating the end of this entry.
1023
1024 E: 12.    # include the core schema
1025 E: 13.    include: file:///usr/local/etc/openldap/schema/core.ldif
1026 E: 14.    
1027
1028 Line 12 is a comment. Line 13 is an LDIF include directive which
1029 accesses the {{core}} schema definitions in LDIF format. Line 14
1030 is a blank line.
1031
1032 Next comes the database definitions. The first database is the
1033 special {{EX:frontend}} database whose settings are applied globally
1034 to all the other databases.
1035
1036 E: 15.    # global database parameters
1037 E: 16.    dn: olcDatabase=frontend,cn=config
1038 E: 17.    objectClass: olcDatabaseConfig
1039 E: 18.    olcDatabase: frontend
1040 E: 19.    olcAccess: to * by * read
1041 E: 20.    
1042
1043 Line 15 is a comment. Lines 16-18 identify this entry as the global
1044 database entry. Line 19 is a global access control. It applies to all
1045 entries (after any applicable database-specific access controls).
1046 Line 20 is a blank line.
1047
1048 The next entry defines the config backend.
1049
1050 E: 21.    # set a rootpw for the config database so we can bind.
1051 E: 22.    # deny access to everyone else.
1052 E: 23.    dn: olcDatabase=config,cn=config
1053 E: 24.    objectClass: olcDatabaseConfig
1054 E: 25.    olcDatabase: config
1055 E: 26.    olcRootPW: {SSHA}XKYnrjvGT3wZFQrDD5040US592LxsdLy
1056 E: 27.    olcAccess: to * by * none
1057 E: 28.
1058
1059 Lines 21-22 are comments. Lines 23-25 identify this entry as the config
1060 database entry. Line 26 defines the {{super-user}} password for this
1061 database. (The DN defaults to {{"cn=config"}}.) Line 27 denies all access
1062 to this database, so only the super-user will be able to access it. (This
1063 is already the default access on the config database. It is just listed
1064 here for illustration, and to reiterate that unless a means to authenticate
1065 as the super-user is explicitly configured, the config database will be
1066 inaccessible.)
1067
1068 Line 28 is a blank line.
1069
1070 The next entry defines a BDB backend that will handle queries for things
1071 in the "dc=example,dc=com" portion of the tree. Indices are to be maintained
1072 for several attributes, and the {{EX:userPassword}} attribute is to be
1073 protected from unauthorized access.
1074
1075 E: 29.    # BDB definition for example.com
1076 E: 30.    dn: olcDatabase=bdb,cn=config
1077 E: 31.    objectClass: olcDatabaseConfig
1078 E: 32.    objectClass: olcBdbConfig
1079 E: 33.    olcDatabase: bdb
1080 E: 34.    olcSuffix: "dc=example,dc=com"
1081 E: 35.    olcDbDirectory: /usr/local/var/openldap-data
1082 E: 36.    olcRootDN: "cn=Manager,dc=example,dc=com"
1083 E: 37.    olcRootPW: secret
1084 E: 38.    olcDbIndex: uid pres,eq
1085 E: 39.    olcDbIndex: cn,sn,uid pres,eq,approx,sub
1086 E: 40.    olcDbIndex: objectClass eq
1087 E: 41.    olcAccess: to attrs=userPassword
1088 E: 42.      by self write
1089 E: 43.      by anonymous auth
1090 E: 44.      by dn.base="cn=Admin,dc=example,dc=com" write
1091 E: 45.      by * none
1092 E: 46.    olcAccess: to *
1093 E: 47.      by self write
1094 E: 48.      by dn.base="cn=Admin,dc=example,dc=com" write
1095 E: 49.      by * read
1096 E: 50.    
1097
1098 Line 29 is a comment. Lines 30-33 identify this entry as a BDB database
1099 configuration entry.  Line 34 specifies the DN suffix
1100 for queries to pass to this database. Line 35 specifies the directory
1101 in which the database files will live.
1102
1103 Lines 36 and 37 identify the database {{super-user}} entry and associated
1104 password. This entry is not subject to access control or size or
1105 time limit restrictions.
1106
1107 Lines 38 through 40 indicate the indices to maintain for various
1108 attributes.
1109
1110 Lines 41 through 49 specify access control for entries in this
1111 database. For all applicable entries, the {{EX:userPassword}} attribute is writable
1112 by the entry itself and by the "admin" entry.  It may be used for
1113 authentication/authorization purposes, but is otherwise not readable.
1114 All other attributes are writable by the entry and the "admin"
1115 entry, but may be read by all users (authenticated or not).
1116
1117 Line 50 is a blank line, indicating the end of this entry.
1118
1119 The next entry defines another
1120 BDB database. This one handles queries involving the
1121 {{EX:dc=example,dc=net}} subtree but is managed by the same entity
1122 as the first database.  Note that without line 60, the read access
1123 would be allowed due to the global access rule at line 19.
1124
1125 E: 51.    # BDB definition for example.net
1126 E: 52.    dn: olcDatabase=bdb,cn=config
1127 E: 53.    objectClass: olcDatabaseConfig
1128 E: 54.    objectClass: olcBdbConfig
1129 E: 55.    olcDatabase: bdb
1130 E: 56.    olcSuffix: "dc=example,dc=net"
1131 E: 57.    olcDbDirectory: /usr/local/var/openldap-data-net
1132 E: 58.    olcRootDN: "cn=Manager,dc=example,dc=com"
1133 E: 59.    olcDbIndex: objectClass eq
1134 E: 60.    olcAccess: to * by users read
1135
1136
1137 H2: Converting old style {{slapd.conf}}(5) file to {{cn=config}} format
1138
1139 Before converting to the {{cn=config}} format you should make sure that the
1140 config backend is properly configured in your existing config file. While
1141 the config backend is always present inside slapd, by default it is only
1142 accessible by its rootDN, and there are no default credentials assigned
1143 so unless you explicitly configure a means to authenticate to it, it will be
1144 unusable.
1145
1146 If you do not already have a {{EX:database config}} section, add something
1147 like this to the end of {{EX:slapd.conf}}
1148
1149 > database config
1150 > rootpw VerySecret
1151
1152 Note: Since the config backend can be used to load arbitrary code into the
1153 slapd process, it is extremely important to carefully guard whatever
1154 credentials are used to access it. Since simple passwords are vulnerable to
1155 password guessing attacks, it is usually better to omit the rootpw and only
1156 use SASL authentication for the config rootDN.
1157
1158 An existing {{slapd.conf}}(5) file can be converted to the new format using
1159 {{slaptest}}(8) or any of the slap tools:
1160
1161 >       slaptest -f /usr/local/etc/openldap/slapd.conf -F /usr/local/etc/openldap/slapd.d
1162
1163 Test that you can access entries under {{EX:cn=config}} using the
1164 default {{rootdn}} and the {{rootpw}} configured above:
1165
1166 >       ldapsearch -x -D cn=config -w VerySecret -b cn=config
1167
1168 You can then discard the old {{slapd.conf}}(5) file. Make sure to launch
1169 {{slapd}}(8) with the {{-F}} option to specify the configuration directory
1170 if you are not using the default directory path.
1171
1172 Note: When converting from the slapd.conf format to slapd.d format, any
1173 included files will also be integrated into the resulting configuration
1174 database.