]> git.sur5r.net Git - openldap/blob - doc/guide/admin/slapdconf2.sdf
More tweaks for BDB
[openldap] / doc / guide / admin / slapdconf2.sdf
1 # $OpenLDAP$
2 # Copyright 2005, 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. Unlike previous
9 OpenLDAP releases, the slapd runtime configuration in 2.3 is
10 fully LDAP-enabled and can be managed using the standard LDAP
11 operations with data in {{TERM:LDIF}}. The LDAP configuration engine
12 allows all of slapd's configuration options to be changed on the fly,
13 generally without requiring a server restart for the changes
14 to take effect. The old style {{slapd.conf}}(5) file is still
15 supported, but must be converted to the new {{slapd.d}}(5) format
16 to allow runtime changes to be saved. While the old style
17 configuration uses a single file, normally installed as
18 {{F:/usr/local/etc/openldap/slapd.conf}}, the new style
19 uses a slapd backend database to store the configuration. The
20 configuration database normally resides in the
21 {{F:/usr/local/etc/openldap/slapd.d}} directory.
22
23 An alternate configuration directory (or file) can be specified via a
24 command-line option to {{slapd}}(8) or {{slurpd}}(8). This chapter
25 describes the general format of the configuration system, followed by a
26 detailed description of commonly used config settings.
27
28
29 H2: Configuration Layout
30
31 The slapd configuration is stored as a special LDAP directory with
32 a predefined schema and DIT. There are specific objectClasses used to
33 carry global configuration options, schema definitions, backend and
34 database definitions, and assorted other items. A sample config tree
35 is shown in Figure 5.1.
36
37 !import "config_dit.gif"; align="center"; title="Sample configuration tree"
38 FT[align="Center"] Figure 5.1: Sample configuration tree.
39
40 Other objects may be part of the configuration but were omitted from
41 the illustration for clarity.
42
43 The {{slapd.d}} configuration tree has a very specific structure. The
44 root of the tree is named {{EX:cn=config}} and contains global configuration
45 settings. Additional settings are contained in separate child entries:
46 * Include files
47 .. Usually these are just pathnames left over from a converted
48 {{EX:slapd.conf}} file.
49 .. Otherwise use of Include files is deprecated.
50 * Dynamically loaded modules
51 .. These may only be used if the {{EX:--enable-modules}} option was
52 used to configure the software.
53 * Schema definitions
54 .. The {{EX:cn=schema,cn=config}} entry contains the system schema (all
55 the schema that is hard-coded in slapd).
56 .. Child entries of {{EX:cn=schema,cn=config}} contain user schema as
57 loaded from config files or added at runtime.
58 * Backend-specific configuration 
59 * Database-specific configuration
60 .. Overlays are defined in children of the Database entry.
61 .. Databases and Overlays may also have other miscellaneous children.
62
63 The usual rules for LDIF files apply to the configuration information:
64 Comment lines beginning with a '{{EX:#}}' character
65 are ignored.  If a line begins with white space, it is considered a
66 continuation of the previous line (even if the previous line is a
67 comment). Entries are separated by blank lines.
68
69 The general layout of the config LDIF is as follows:
70
71 >       # global configuration settings
72 >       dn: cn=config
73 >       objectClass: olcGlobal
74 >       cn: config
75 >       <global config settings>
76 >
77 >       # schema definitions
78 >       dn: cn=schema,cn=config
79 >       objectClass: olcSchemaConfig
80 >       cn: schema
81 >       <system schema>
82 >
83 >       dn: cn={X}core,cn=schema,cn=config
84 >       objectClass: olcSchemaConfig
85 >       cn: {X}core
86 >       <core schema>
87 >
88 >       # additional user-specified schema
89 >       ...
90 >
91 >       # backend definitions
92 >       dn: olcBackend=<typeA>,cn=config
93 >       objectClass: olcBackendConfig
94 >       olcBackend: <typeA>
95 >       <backend-specific settings>
96 >
97 >       # database definitions
98 >       dn: olcDatabase={X}<typeA>,cn=config
99 >       objectClass: olcDatabaseConfig
100 >       olcDatabase: {X}<typeA>
101 >       <database-specific settings>
102 >
103 >       # subsequent definitions and settings
104 >       ...
105
106 Some of the entries listed above have a numeric index {{EX:"{X}"}} in
107 their names. While most configuration settings have an inherent ordering
108 dependency (i.e., one setting must take effect before a subsequent one
109 may be set), LDAP databases are inherently unordered. The numeric index
110 is used to enforce a consistent ordering in the configuration database,
111 so that all ordering dependencies are preserved. In most cases the index
112 does not have to be provided; it will be automatically generated based
113 on the order in which entries are created.
114
115 Configuration directives are specified as values of individual
116 attributes.
117 Most of the attributes and objectClasses used in the slapd
118 configuration have a prefix of {{EX:"olc"}} (OpenLDAP Configuration)
119 in their names. Generally there is a one-to-one correspondence
120 between the attributes and the old-style {{EX:slapd.conf}} configuration
121 keywords, using the keyword as the attribute name, with the "olc"
122 prefix attached.
123
124 A configuration directive may take arguments.  If so, the arguments are
125 separated by white space.  If an argument contains white space,
126 the argument should be enclosed in double quotes {{EX:"like this"}}. If
127 an argument contains a double quote or a backslash character `{{EX:\}}',
128 the character should be preceded by a backslash character `{{EX:\}}'.
129 In the descriptions that follow, arguments that should be replaced
130 by actual text are shown in brackets {{EX:<>}}.
131
132 The distribution contains an example configuration file that will
133 be installed in the {{F: /usr/local/etc/openldap}} directory.
134 A number of files containing schema definitions (attribute types
135 and object classes) are also provided in the
136 {{F: /usr/local/etc/openldap/schema}} directory.
137
138
139 H2: Configuration Directives
140
141 This section details commonly used configuration directives.  For
142 a complete list, see the {{slapd.d}}(5) manual page.  This section
143 will treat the configuration directives in a top-down order, starting
144 with the global directives in the {{EX:cn=config}} entry. Each
145 directive will be described along with its default value (if any) and
146 an example of its use.
147
148
149 H3: cn=config
150
151 Directives contained in this entry generally apply to the server as a whole.
152 Most of them are system or connection oriented, not database related.
153
154
155 H4: olcIdleTimeout: <integer>
156
157 Specify the number of seconds to wait before forcibly closing
158 an idle client connection.  A value of 0, the default,
159 disables this feature.
160
161
162 H4: olcLogLevel: <level>
163
164 This directive specifies the level at which debugging statements
165 and operation statistics should be syslogged (currently logged to
166 the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have
167 configured OpenLDAP {{EX:--enable-debug}} (the default) for this
168 to work (except for the two statistics levels, which are always
169 enabled). Log levels may be specified as integers or by keyword.
170 Multiple log levels may be used and the levels are additive.
171 To display what levels
172 correspond to what kind of debugging, invoke slapd with {{EX:-?}}
173 or consult the table below. The possible values for <level> are:
174
175 !block table; colaligns="RL"; align=Center; \
176         title="Table 5.1: Debugging Levels"
177 Level   Keyword Description
178 -1      Any     enable all debugging
179 0               no debugging
180 1       Trace   trace function calls
181 2       Packets debug packet handling
182 4       Args    heavy trace debugging
183 8       Conns   connection management
184 16      BER     print out packets sent and received
185 32      Filter  search filter processing
186 64      Config  configuration processing
187 128     ACL     access control list processing
188 256     Stats   stats log connections/operations/results
189 512     Stats2  stats log entries sent
190 1024    Shell   print communication with shell backends
191 2048    Parse   print entry parsing debugging
192 4096    Cache   database cache processing
193 8192    Index   database indexing
194 16384   Sync    syncrepl consumer processing
195 !endblock
196
197 \Example:
198
199 E: olcLogLevel: -1
200
201 This will cause lots and lots of debugging information to be
202 logged.
203
204 E: olcLogLevel: Conns Filter
205
206 Just log the connection and search filter processing.
207
208 \Default:
209
210 E: olcLogLevel: Stats
211
212
213 H4: olcReferral <URI>
214
215 This directive specifies the referral to pass back when slapd
216 cannot find a local database to handle a request.
217
218 \Example:
219
220 >       olcReferral: ldap://root.openldap.org
221
222 This will refer non-local queries to the global root LDAP server
223 at the OpenLDAP Project. Smart LDAP clients can re-ask their
224 query at that server, but note that most of these clients are
225 only going to know how to handle simple LDAP URLs that
226 contain a host part and optionally a distinguished name part.
227
228
229 H4: Sample Entry
230
231 >dn: cn=config
232 >objectClass: olcGlobal
233 >cn: config
234 >olcIdleTimeout: 30
235 >olcLogLevel: Stats
236 >olcReferral: ldap://root.openldap.org
237
238
239
240 H3: cn=include
241
242 An include entry holds the pathname of one include file. Include files
243 are part of the old style slapd.conf configuration system and must be in
244 slapd.conf format. Include files were commonly used to load schema
245 specifications. While they are still supported, their use is deprecated.
246
247
248 H4: olcInclude: <filename>
249
250 This directive specifies that slapd should read additional
251 configuration information from the given file. 
252
253 Note: You should be careful when using this directive - there is
254 no small limit on the number of nested include directives, and no
255 loop detection is done.
256
257
258 H4: Sample Entries
259
260 >dn: cn=include{0},cn=config
261 >objectClass: olcIncludeFile
262 >cn: include{0}
263 >olcInclude: ./schema/core.schema
264 >
265 >dn: cn=include{1},cn=config
266 >objectClass: olcIncludeFile
267 >cn: include{1}
268 >olcInclude: ./schema/cosine.schema
269
270
271 H3: cn=schema
272
273 The cn=schema entry holds all of the schema definitions that are hard-coded
274 in slapd. As such, the values in this entry are generated by slapd so no
275 schema values need to be provided in the config file. The entry must still
276 be defined though, to serve as a base for the user-defined schema to add
277 in underneath.
278
279
280 H4: olcAttributeTypes: <{{REF:RFC2252}} Attribute Type Description>
281
282 This directive defines an attribute type.
283 Please see the {{SECT:Schema Specification}} chapter
284 for information regarding how to use this directive.
285
286
287 H4: olcObjectClasses: <{{REF:RFC2252}} Object Class Description>
288
289 This directive defines an object class.
290 Please see the {{SECT:Schema Specification}} chapter for
291 information regarding how to use this directive.
292
293
294 H4: Sample Entries
295
296 >dn: cn=schema,cn=config
297 >objectClass: olcSchemaConfig
298 >cn: schema
299 >
300 >dn: cn=test,cn=schema,cn=config
301 >objectClass: olcSchemaConfig
302 >cn: test
303 >olcAttributeTypes: ( 1.1.1
304 > NAME 'testAttr'
305 > EQUALITY integerMatch
306 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 )
307 >olcAttributeTypes: ( 1.1.2 NAME 'testTwo' EQUALITY caseIgnoreMatch
308 > SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 )
309 >olcObjectClasses: ( 1.1.3 NAME 'testObject'
310 > MAY ( testAttr $ testTwo ) AUXILIARY )
311
312
313 H3: Backend-specific Directives
314
315 Backend directives apply to all database instances of the
316 same type and, depending on the directive, may be overridden
317 by database directives.
318
319 H4: olcBackend: <type>
320
321 This directive names a backend-specific configuration entry.
322 {{EX:<type>}} should be one of the
323 supported backend types listed in Table 5.2.
324
325 !block table; align=Center; coltags="EX,N"; \
326         title="Table 5.2: Database Backends"
327 Types   Description
328 bdb     Berkeley DB transactional backend
329 dnssrv  DNS SRV backend
330 ldap    Lightweight Directory Access Protocol (Proxy) backend
331 ldbm    Lightweight DBM backend
332 ldif    Lightweight Data Interchange Format backend
333 meta    Meta Directory backend
334 monitor Monitor backend
335 passwd  Provides read-only access to {{passwd}}(5)
336 perl    Perl Programmable backend
337 shell   Shell (extern program) backend
338 sql     SQL Programmable backend
339 !endblock
340
341 \Example:
342
343 >       olcBackend: bdb
344
345 There are no other directives defined for this entry, so generally
346 it will not be needed. However, specific backend types may define
347 additional attributes for their particular use.
348
349
350 H4: Sample Entry
351
352 > dn: olcBackend=bdb,cn=config
353 > objectClass: olcBackendConfig
354 > olcBackend: bdb
355
356
357 H3: Database-specific Directives
358
359 Directives in this section are supported by every type of database.
360
361 H4: olcDatabase: [{<index>}]<type>
362
363 This directive names a specific database instance. The numeric {<index>} may
364 be provided to distinguish multiple databases of the same type. Usually the
365 index can be omitted, and slapd will generate it automatically.
366 {{EX:<type>}} should be one of the
367 supported backend types listed in Table 5.2 or the {{EX:frontend}} type.
368
369 The {{EX:frontend}} is a special database that is used to hold
370 database-level options that should be applied to all the other
371 databases. Subsequent database definitions may also override some
372 frontend settings.
373
374 \Example:
375
376 >       olcDatabase: bdb
377
378 This marks the beginning of a new {{TERM:BDB}} database instance.
379
380
381 H4: olcAccess: to <what> [ by <who> <accesslevel> <control> ]+
382
383 This directive grants access (specified by <accesslevel>) to a
384 set of entries and/or attributes (specified by <what>) by one or
385 more requesters (specified by <who>).
386 See the {{SECT:Access Control}} section of this chapter for a
387 summary of basic usage.
388
389 !if 0
390 More detailed discussion of this directive can be found in the
391 {{SECT:Advanced Access Control}} chapter.
392 !endif
393
394 Note: If no {{EX:olcAccess}} directives are specified, the default
395 access control policy, {{EX:to * by * read}}, allows all
396 users (both authenticated and anonymous) read access.
397
398 Note: Access controls defined in the frontend are appended to all
399 other databases' controls.
400
401
402 H4: olcReadonly { TRUE | FALSE }
403
404 This directive puts the database into "read-only" mode. Any
405 attempts to modify the database will return an "unwilling to
406 perform" error.
407
408 \Default:
409
410 >       olcReadonly: FALSE
411
412
413 H4: olcReplica
414
415 >       olcReplica: uri=ldap[s]://<hostname>[:<port>] | host=<hostname>[:<port>]
416 >               [bindmethod={simple|sasl}]
417 >               ["binddn=<DN>"]
418 >               [saslmech=<mech>]
419 >               [authcid=<identity>]
420 >               [authzid=<identity>]
421 >               [credentials=<password>]
422
423 This directive specifies a replication site for this database for
424 use with slurpd. The
425 {{EX:uri=}} parameter specifies a scheme, a host and optionally a port where
426 the slave slapd instance can be found. Either a domain name
427 or IP address may be used for <hostname>. If <port> is not
428 given, the standard LDAP port number (389 or 636) is used.
429
430 {{EX:host}} is deprecated in favor of the {{EX:uri}} parameter.
431
432 {{EX:uri}} allows the replica LDAP server to be specified as an LDAP 
433 URI such as {{EX:ldap://slave.example.com:389}} or
434 {{EX:ldaps://slave.example.com:636}}.
435
436 The {{EX:binddn=}} parameter gives the DN to bind as for updates
437 to the slave slapd. It should be a DN which has read/write access
438 to the slave slapd's database.  It must also match the {{EX:updatedn}}
439 directive in the slave slapd's config file.  Generally, this DN
440 {{should not}} be the same as the {{EX:rootdn}} of the master
441 database.  Since DNs are likely to contain embedded spaces, the
442 entire {{EX:"binddn=<DN>"}} string should be enclosed in double
443 quotes.
444
445 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
446 depending on whether simple password-based authentication
447 or {{TERM:SASL}} authentication is to be used when connecting
448 to the slave slapd.
449
450 Simple authentication should not be used unless adequate data
451 integrity and confidentiality protections are in place (e.g. TLS
452 or IPSEC).  Simple authentication requires specification of
453 {{EX:binddn}} and {{EX:credentials}} parameters.
454
455 SASL authentication is generally recommended.  SASL authentication
456 requires specification of a mechanism using the {{EX:saslmech}} parameter.
457 Depending on the mechanism, an authentication identity and/or
458 credentials can be specified using {{EX:authcid}} and {{EX:credentials}}
459 respectively.  The {{EX:authzid}} parameter may be used to specify
460 an authorization identity.
461
462 See the chapter entitled {{SECT:Replication with slurpd}} for more
463 information on how to use this directive.
464
465
466 H4: olcReplogfile: <filename>
467
468 This directive specifies the name of the replication log file to
469 which slapd will log changes. The replication log is typically
470 written by slapd and read by slurpd. Normally, this directive is
471 only used if slurpd is being used to replicate the database.
472 However, you can also use it to generate a transaction log, if
473 slurpd is not running. In this case, you will need to periodically
474 truncate the file, since it will grow indefinitely otherwise.
475
476 See the chapter entitled {{SECT:Replication with slurpd}} for more
477 information on how to use this directive.
478
479
480 H4: olcRootDN: <DN>
481
482 This directive specifies the DN that is not subject to
483 access control or administrative limit restrictions for
484 operations on this database.  The DN need not refer to
485 an entry in this database or even in the directory. The
486 DN may refer to a SASL identity.
487
488 Entry-based Example:
489
490 >       olcRootDN: "cn=Manager,dc=example,dc=com"
491
492 SASL-based Example:
493
494 >       olcRootDN: "uid=root,cn=example.com,cn=digest-md5,cn=auth"
495
496 See the {{SECT:SASL Authentication}} section for information on
497 SASL authentication identities.
498
499
500 H4: olcRootPW: <password>
501
502 This directive can be used to specify a password for the DN for
503 the rootdn (when the rootdn is set to a DN within the database).
504
505 \Example:
506
507 >       olcRootPW: secret
508
509 It is also permissible to provide a hash of the password in RFC 2307
510 form.  {{slappasswd}}(8) may be used to generate the password hash.
511
512 \Example:
513
514 >       olcRootPW: {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN
515
516 The hash was generated using the command {{EX:slappasswd -s secret}}.
517
518
519 H4: olcSizeLimit: <integer>
520
521 This directive specifies the maximum number of entries to return
522 from a search operation.
523
524 \Default:
525
526 >       olcSizeLimit: 500
527
528
529
530 H4: olcSuffix: <dn suffix>
531
532 This directive specifies the DN suffix of queries that will be
533 passed to this backend database. Multiple suffix lines can be
534 given, and usually at least one is required for each database
535 definition. (Some backend types, such as {{EX:frontend}} and
536 {{EX:monitor}} use a hard-coded suffix which may not be overridden
537 in the configuration.)
538
539 \Example:
540
541 >       olcSuffix: "dc=example,dc=com"
542
543 Queries with a DN ending in "dc=example,dc=com"
544 will be passed to this backend.
545
546 Note: When the backend to pass a query to is selected, slapd
547 looks at the suffix value(s) in each database definition in the
548 order in which they were configured. Thus, if one database suffix is a
549 prefix of another, it must appear after it in the configuration.
550
551
552 H4: olcSyncrepl
553
554 >       olcSyncrepl: rid=<replica ID>
555 >               provider=ldap[s]://<hostname>[:port]
556 >               [type=refreshOnly|refreshAndPersist]
557 >               [interval=dd:hh:mm:ss]
558 >               [retry=[<retry interval> <# of retries>]+]
559 >               [searchbase=<base DN>]
560 >               [filter=<filter str>]
561 >               [scope=sub|one|base]
562 >               [attrs=<attr list>]
563 >               [attrsonly]
564 >               [sizelimit=<limit>]
565 >               [timelimit=<limit>]
566 >               [schemachecking=on|off]
567 >               [bindmethod=simple|sasl]
568 >               [binddn=<DN>]
569 >               [saslmech=<mech>]
570 >               [authcid=<identity>]
571 >               [authzid=<identity>]
572 >               [credentials=<passwd>]
573 >               [realm=<realm>]
574 >               [secprops=<properties>]
575
576
577 This directive specifies the current database as a replica of the
578 master content by establishing the current {{slapd}}(8) as a
579 replication consumer site running a syncrepl replication engine.
580 The master database is located at the replication provider site
581 specified by the {{EX:provider}} parameter. The replica database is
582 kept up-to-date with the master content using the LDAP Content
583 Synchronization protocol. See {{EX:draft-zeilenga-ldup-sync-xx.txt}}
584 ({{a work in progress}}) for more information on the protocol.
585
586 The {{EX:rid}} parameter is used for identification of the current
587 {{EX:syncrepl}} directive within the replication consumer server,
588 where {{EX:<replica ID>}} uniquely identifies the syncrepl specification
589 described by the current {{EX:syncrepl}} directive. {{EX:<replica ID>}}
590 is non-negative and is no more than three decimal digits in length.
591
592 The {{EX:provider}} parameter specifies the replication provider site
593 containing the master content as an LDAP URI. The {{EX:provider}}
594 parameter specifies a scheme, a host and optionally a port where the
595 provider slapd instance can be found. Either a domain name or IP
596 address may be used for <hostname>. Examples are
597 {{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}.
598 If <port> is not given, the standard LDAP port number (389 or 636) is used.
599 Note that the syncrepl uses a consumer-initiated protocol, and hence its
600 specification is located at the consumer site, whereas the {{EX:replica}}
601 specification is located at the provider site. {{EX:syncrepl}} and
602 {{EX:replica}} directives define two independent replication
603 mechanisms. They do not represent the replication peers of each other.
604
605 The content of the syncrepl replica is defined using a search
606 specification as its result set. The consumer slapd will
607 send search requests to the provider slapd according to the search
608 specification. The search specification includes {{EX:searchbase}},
609 {{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:attrsonly}},
610 {{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal
611 search specification. The syncrepl search specification has
612 the same value syntax and the same default values as in the
613 {{ldapsearch}}(1) client search tool.
614
615 The LDAP Content Synchronization protocol has two operation
616 types: {{EX:refreshOnly}} and {{EX:refreshAndPersist}}.
617 The operation type is specified by the {{EX:type}} parameter.
618 In the {{EX:refreshOnly}} operation, the next synchronization search operation
619 is periodically rescheduled at an interval time after each
620 synchronization operation finishes. The interval is specified
621 by the {{EX:interval}} parameter. It is set to one day by default.
622 In the {{EX:refreshAndPersist}} operation, a synchronization search
623 remains persistent in the provider slapd. Further updates to the
624 master replica will generate {{EX:searchResultEntry}} to the consumer slapd
625 as the search responses to the persistent synchronization search.
626
627 If an error occurs during replication, the consumer will attempt to reconnect
628 according to the retry parameter which is a list of the <retry interval>
629 and <# of retries> pairs. For example, retry="60 5 300 3" lets the consumer
630 retry every 60 seconds for the first 10 times and then retry every 300 seconds
631 for the next three times before stop retrying. + in <#  of retries> means
632 indefinite number of retries until success.
633
634 The schema checking can be enforced at the LDAP Sync consumer site
635 by turning on the {{EX:schemachecking}} parameter.
636 If it is turned on, every replicated entry will be checked for its
637 schema as the entry is stored into the replica content.
638 Every entry in the replica should contain those attributes
639 required by the schema definition.
640 If it is turned off, entries will be stored without checking
641 schema conformance. The default is off.
642
643 The {{EX:binddn}} parameter gives the DN to bind as for the
644 syncrepl searches to the provider slapd. It should be a DN
645 which has read access to the replication content in the
646 master database. 
647
648 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
649 depending on whether simple password-based authentication or
650 {{TERM:SASL}} authentication is to be used when connecting
651 to the provider slapd.
652
653 Simple authentication should not be used unless adequate data
654 integrity and confidentiality protections are in place (e.g. TLS
655 or IPSEC). Simple authentication requires specification of {{EX:binddn}}
656 and {{EX:credentials}} parameters.
657
658 SASL authentication is generally recommended.  SASL authentication
659 requires specification of a mechanism using the {{EX:saslmech}} parameter.
660 Depending on the mechanism, an authentication identity and/or
661 credentials can be specified using {{EX:authcid}} and {{EX:credentials}},
662 respectively.  The {{EX:authzid}} parameter may be used to specify
663 an authorization identity.
664
665 The {{EX:realm}} parameter specifies a realm which a certain
666 mechanisms authenticate the identity within. The {{EX:secprops}}
667 parameter specifies Cyrus SASL security properties.
668
669 The syncrepl replication mechanism is supported by the
670 three native backends: back-bdb, back-hdb, and back-ldbm.
671
672 See the {{SECT:LDAP Sync Replication}} chapter of the admin guide
673 for more information on how to use this directive.
674
675
676 H4: olcTimeLimit: <integer>
677
678 This directive specifies the maximum number of seconds (in real
679 time) slapd will spend answering a search request. If a
680 request is not finished in this time, a result indicating an
681 exceeded timelimit will be returned.
682
683 \Default:
684
685 >       olcTimeLimit: 3600
686
687
688 H4: olcUpdateDN: <DN>
689
690 This directive is only applicable in a slave slapd. It specifies
691 the DN allowed to make changes to the replica.  This may be the DN
692 {{slurpd}}(8) binds as when making changes to the replica or the DN
693 associated with a SASL identity.
694
695 Entry-based Example:
696
697 >       olcUpdateDN: "cn=Update Daemon,dc=example,dc=com"
698
699 SASL-based Example:
700
701 >       olcUpdateDN: "uid=slurpd,cn=example.com,cn=digest-md5,cn=auth"
702
703 See the {{SECT:Replication with slurpd}} chapter for more information
704 on how to use this directive.
705
706 H4: olcUpdateref: <URL>
707
708 This directive is only applicable in a slave slapd. It
709 specifies the URL to return to clients which submit update
710 requests upon the replica.
711 If specified multiple times, each {{TERM:URL}} is provided.
712
713 \Example:
714
715 >       olcUpdateref:   ldap://master.example.net
716
717
718 H4: Sample Entry
719
720 >dn: olcDatabase=frontend,cn=config
721 >objectClass: olcDatabaseConfig
722 >olcDatabase: frontend
723 >olcReadOnly: FALSE
724
725 H3: BDB Database Directives
726
727 Directives in this category only apply to a {{TERM:BDB}} database.
728 They are used in an olcDatabase entry in addition to the generic
729 database directives defined above. Their use requires the database
730 entry to also use the {{EX:olcBdbConfig}} objectClass.
731 For a complete reference
732 of BDB configuration directives, see {{slapd-bdb}}(5).
733
734
735 H4: olcDbDirectory: <directory>
736
737 This directive specifies the directory where the BDB files
738 containing the database and associated indices live.
739
740 \Default:
741
742 >       olcDbDirectory: /usr/local/var/openldap-data
743
744
745 H4: Sample Entry
746
747 >dn: olcDatabase=bdb,cn=config
748 >objectClass: olcDatabaseConfig
749 >objectClass: olcBdbConfig
750 >olcDatabase: bdb
751 >olcSuffix: "dc=example,dc=com"
752 >olcDbDirectory: /usr/local/var/openldap-data
753
754 H3: LDBM Database Directives
755
756 Directives in this category only apply to a {{TERM:LDBM}} database.
757 That is, they must follow a "database ldbm" line and come before
758 any subsequent "backend" or "database" line.  For a complete reference
759 of LDBM configuration directives, see {{slapd-ldbm}}(5).
760
761 H4: cachesize <integer>
762
763 This directive specifies the size in entries of the in-memory
764 cache maintained by the LDBM backend database instance.
765
766 \Default:
767
768 >       cachesize 1000
769
770
771 H4: dbcachesize <integer>
772
773 This directive specifies the size in bytes of the in-memory cache
774 associated with each open index file. If not supported by the
775 underlying database method, this directive is ignored without
776 comment. Increasing this number uses more memory but can
777 cause a dramatic performance increase, especially during
778 modifies or when building indices.
779
780 \Default:
781
782 >       dbcachesize 100000
783
784
785 H4: dbnolocking
786
787 This option, if present, disables database locking.
788 Enabling this option may improve performance at the expense
789 of data security.
790
791
792 H4: dbnosync
793
794 This option causes on-disk database contents to not be immediately
795 synchronized with in memory changes upon change.  Enabling this option
796 may improve performance at the expense of data integrity.
797
798
799 H4: directory <directory>
800
801 This directive specifies the directory where the LDBM files
802 containing the database and associated indices live.
803
804 \Default:
805
806 >       directory /usr/local/var/openldap-data
807
808
809 H4: index {<attrlist> | default} [pres,eq,approx,sub,none]
810
811 This directive specifies the indices to maintain for the given
812 attribute. If only an {{EX:<attrlist>}} is given, the default
813 indices are maintained.
814
815 \Example:
816
817 >       index default pres,eq
818 >       index uid
819 >       index cn,sn pres,eq,sub
820 >       index objectClass eq
821
822 The first line sets the default set of indices to maintain to
823 present and equality.  The second line causes the default (pres,eq)
824 set of indices to be maintained for the {{EX:uid}} attribute type.
825 The third line causes present, equality, and substring indices to
826 be maintained for {{EX:cn}} and {{EX:sn}} attribute types.  The
827 fourth line causes an equality index for the {{EX:objectClass}}
828 attribute type.
829
830 By default, no indices are maintained.  It is generally advised
831 that minimally an equality index upon objectClass be maintained.
832
833 >       index objectClass eq
834
835
836
837 H4: mode <integer>
838
839 This directive specifies the file protection mode that newly
840 created database index files should have.
841
842 \Default:
843
844 >       mode 0600
845
846
847 H2: Access Control
848
849 Access to slapd entries and attributes is controlled by the
850 access configuration file directive. The general form of an
851 access line is:
852
853 >       <access directive> ::= access to <what>
854 >               [by <who> <access> <control>]+
855 >       <what> ::= * |
856 >               [dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
857 >               [filter=<ldapfilter>] [attrs=<attrlist>]
858 >       <basic-style> ::= regex | exact
859 >       <scope-style> ::= base | one | subtree | children
860 >       <attrlist> ::= <attr> [val[.<basic-style>]=<regex>] | <attr> , <attrlist>
861 >       <attr> ::= <attrname> | entry | children
862 >       <who> ::= * | [anonymous | users | self
863 >                       | dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>] 
864 >               [dnattr=<attrname>]
865 >               [group[/<objectclass>[/<attrname>][.<basic-style>]]=<regex>]
866 >               [peername[.<basic-style>]=<regex>]
867 >               [sockname[.<basic-style>]=<regex>]
868 >               [domain[.<basic-style>]=<regex>]
869 >               [sockurl[.<basic-style>]=<regex>]
870 >               [set=<setspec>]
871 >               [aci=<attrname>]
872 >       <access> ::= [self]{<level>|<priv>}
873 >       <level> ::= none | auth | compare | search | read | write
874 >       <priv> ::= {=|+|-}{w|r|s|c|x|0}+
875 >       <control> ::= [stop | continue | break]
876
877 where the <what> part selects the entries and/or attributes to which
878 the access applies, the {{EX:<who>}} part specifies which entities
879 are granted access, and the {{EX:<access>}} part specifies the
880 access granted. Multiple {{EX:<who> <access> <control>}} triplets
881 are supported, allowing many entities to be granted different access
882 to the same set of entries and attributes. Not all of these access
883 control options are described here; for more details see the
884 {{slapd.access}}(5) man page.
885
886
887 H3: What to control access to
888
889 The <what> part of an access specification determines the entries
890 and attributes to which the access control applies.  Entries are
891 commonly selected in two ways: by DN and by filter.  The following
892 qualifiers select entries by DN:
893
894 >       to *
895 >       to dn[.<basic-style>]=<regex>
896 >       to dn.<scope-style>=<DN>
897
898 The first form is used to select all entries.  The second form may
899 be used to select entries by matching a regular expression against
900 the target entry's {{normalized DN}}.   (The second form is not
901 discussed further in this document.)  The third form is used to
902 select entries which are within the requested scope of DN.  The
903 <DN> is a string representation of the Distinguished Name, as
904 described in {{REF:RFC2253}}.
905
906 The scope can be either {{EX:base}}, {{EX:one}}, {{EX:subtree}},
907 or {{EX:children}}.  Where {{EX:base}} matches only the entry with
908 provided DN, {{EX:one}} matches the entries whose parent is the
909 provided DN, {{EX:subtree}} matches all entries in the subtree whose
910 root is the provided DN, and {{EX:children}} matches all entries
911 under the DN (but not the entry named by the DN).
912
913 For example, if the directory contained entries named:
914
915 >       0: o=suffix
916 >       1: cn=Manager,o=suffix
917 >       2: ou=people,o=suffix
918 >       3: uid=kdz,ou=people,o=suffix
919 >       4: cn=addresses,uid=kdz,ou=people,o=suffix
920 >       5: uid=hyc,ou=people,o=suffix
921
922 \Then:
923 . {{EX:dn.base="ou=people,o=suffix"}} match 2;
924 . {{EX:dn.one="ou=people,o=suffix"}} match 3, and 5;
925 . {{EX:dn.subtree="ou=people,o=suffix"}} match 2, 3, 4, and 5; and
926 . {{EX:dn.children="ou=people,o=suffix"}} match 3, 4, and 5.
927
928
929 Entries may also be selected using a filter:
930
931 >       to filter=<ldap filter>
932
933 where <ldap filter> is a string representation of an LDAP
934 search filter, as described in {{REF:RFC2254}}.  For example:
935
936 >       to filter=(objectClass=person)
937
938 Note that entries may be selected by both DN and filter by
939 including both qualifiers in the <what> clause.
940
941 >       to dn.one="ou=people,o=suffix" filter=(objectClass=person)
942
943 Attributes within an entry are selected by including a comma-separated
944 list of attribute names in the <what> selector:
945
946 >       attrs=<attribute list>
947
948 A specific value of an attribute is selected by using a single
949 attribute name and also using a value selector:
950
951 >       attrs=<attribute> val[.<style>]=<regex>
952
953 There are two special {{pseudo}} attributes {{EX:entry}} and
954 {{EX:children}}.  To read (and hence return) a target entry, the
955 subject must have {{EX:read}} access to the target's {{entry}}
956 attribute.  To add or delete an entry, the subject must have
957 {{EX:write}} access to the entry's {{EX:entry}} attribute AND must
958 have {{EX:write}} access to the entry's parent's {{EX:children}}
959 attribute.  To rename an entry, the subject must have {{EX:write}}
960 access to entry's {{EX:entry}} attribute AND have {{EX:write}}
961 access to both the old parent's and new parent's {{EX:children}}
962 attributes.  The complete examples at the end of this section should
963 help clear things up.
964
965 Lastly, there is a special entry selector {{EX:"*"}} that is used to
966 select any entry.  It is used when no other {{EX:<what>}}
967 selector has been provided.  It's equivalent to "{{EX:dn=.*}}"
968
969
970 H3: Who to grant access to
971
972 The <who> part identifies the entity or entities being granted
973 access. Note that access is granted to "entities" not "entries."
974 The following table summarizes entity specifiers:
975
976 !block table; align=Center; coltags="EX,N"; \
977         title="Table 5.3: Access Entity Specifiers"
978 Specifier|Entities
979 *|All, including anonymous and authenticated users
980 anonymous|Anonymous (non-authenticated) users
981 users|Authenticated users
982 self|User associated with target entry
983 dn[.<basic-style>]=<regex>|Users matching a regular expression
984 dn.<scope-style>=<DN>|Users within scope of a DN
985 !endblock
986
987 The DN specifier behaves much like <what> clause DN specifiers.
988
989 Other control factors are also supported.  For example, a {{EX:<who>}}
990 can be restricted by an entry listed in a DN-valued attribute in
991 the entry to which the access applies:
992
993 >       dnattr=<dn-valued attribute name>
994
995 The dnattr specification is used to give access to an entry
996 whose DN is listed in an attribute of the entry (e.g., give
997 access to a group entry to whoever is listed as the owner of
998 the group entry).
999
1000 Some factors may not be appropriate in all environments (or any).
1001 For example, the domain factor relies on IP to domain name lookups.
1002 As these can easily spoofed, the domain factor should not be avoided.
1003
1004
1005 H3: The access to grant
1006
1007
1008 The kind of <access> granted can be one of the following:
1009
1010
1011 !block table; colaligns="LRL"; coltags="EX,EX,N"; align=Center; \
1012         title="Table 5.4: Access Levels"
1013 Level   Privileges      Description
1014 none    =0              no access
1015 auth    =x              needed to bind
1016 compare =cx             needed to compare
1017 search  =scx            needed to apply search filters
1018 read    =rscx           needed to read search results
1019 write   =wrscx          needed to modify/rename
1020 !endblock
1021
1022 Each level implies all lower levels of access. So, for
1023 example, granting someone {{EX:write}} access to an entry also
1024 grants them {{EX:read}}, {{EX:search}}, {{EX:compare}}, and 
1025 {{EX:auth}} access.  However, one may use the privileges specifier
1026 to grant specific permissions.
1027
1028
1029 H3: Access Control Evaluation
1030
1031 When evaluating whether some requester should be given access to
1032 an entry and/or attribute, slapd compares the entry and/or attribute
1033 to the {{EX:<what>}} selectors given in the configuration file.
1034 For each entry, access controls provided in the database which holds
1035 the entry (or the first database if not held in any database) apply
1036 first, followed by the global access directives.  Within this
1037 priority, access directives are examined in the order in which they
1038 appear in the config file.  Slapd stops with the first {{EX:<what>}}
1039 selector that matches the entry and/or attribute. The corresponding
1040 access directive is the one slapd will use to evaluate access.
1041
1042 Next, slapd compares the entity requesting access to the {{EX:<who>}}
1043 selectors within the access directive selected above in the order
1044 in which they appear. It stops with the first {{EX:<who>}} selector
1045 that matches the requester. This determines the access the entity
1046 requesting access has to the entry and/or attribute.
1047
1048 Finally, slapd compares the access granted in the selected
1049 {{EX:<access>}} clause to the access requested by the client. If
1050 it allows greater or equal access, access is granted. Otherwise,
1051 access is denied.
1052
1053 The order of evaluation of access directives makes their placement
1054 in the configuration file important. If one access directive is
1055 more specific than another in terms of the entries it selects, it
1056 should appear first in the config file. Similarly, if one {{EX:<who>}}
1057 selector is more specific than another it should come first in the
1058 access directive. The access control examples given below should
1059 help make this clear.
1060
1061
1062
1063 H3: Access Control Examples
1064
1065 The access control facility described above is quite powerful.  This
1066 section shows some examples of its use for descriptive purposes.
1067
1068 A simple example:
1069
1070 >       access to * by * read
1071
1072 This access directive grants read access to everyone.
1073
1074 >       access to *
1075 >               by self write
1076 >               by anonymous auth
1077 >               by * read
1078
1079 This directive allows the user to modify their entry, allows anonymous
1080 to authentication against these entries, and allows all others to
1081 read these entries.  Note that only the first {{EX:by <who>}} clause
1082 which matches applies.  Hence, the anonymous users are granted
1083 {{EX:auth}}, not {{EX:read}}.  The last clause could just as well
1084 have been "{{EX:by users read}}".
1085
1086 It is often desirable to restrict operations based upon the level
1087 of protection in place.  The following shows how security strength
1088 factors (SSF) can be used.
1089
1090 >       access to *
1091 >               by ssf=128 self write
1092 >               by ssf=64 anonymous auth
1093 >               by ssf=64 users read
1094
1095 This directive allows users to modify their own entries if security
1096 protections have of strength 128 or better have been established,
1097 allows authentication access to anonymous users, and read access
1098 when 64 or better security protections have been established.  If
1099 client has not establish sufficient security protections, the
1100 implicit {{EX:by * none}} clause would be applied.
1101
1102 The following example shows the use of a style specifiers to select
1103 the entries by DN in two access directives where ordering is
1104 significant.
1105
1106 >       access to dn.children="dc=example,dc=com"
1107 >               by * search
1108 >       access to dn.children="dc=com"
1109 >               by * read
1110
1111 Read access is granted to entries under the {{EX:dc=com}} subtree,
1112 except for those entries under the {{EX:dc=example,dc=com}} subtree,
1113 to which search access is granted.  No access is granted to
1114 {{EX:dc=com}} as neither access directive matches this DN.  If the
1115 order of these access directives was reversed, the trailing directive
1116 would never be reached, since all entries under {{EX:dc=example,dc=com}}
1117 are also under {{EX:dc=com}} entries.
1118
1119 Also note that if no {{EX:access to}} directive matches or no {{EX:by
1120 <who>}} clause, {{B:access is denied}}.  That is, every {{EX:access
1121 to}} directive ends with an implicit {{EX:by * none}} clause and
1122 every access list ends with an implicit {{EX:access to * by * none}}
1123 directive.
1124
1125 The next example again shows the importance of ordering, both of
1126 the access directives and the {{EX:by <who>}} clauses.  It also
1127 shows the use of an attribute selector to grant access to a specific
1128 attribute and various {{EX:<who>}} selectors.
1129
1130 >       access to dn.subtree="dc=example,dc=com" attr=homePhone
1131 >               by self write
1132 >               by dn.children=dc=example,dc=com" search
1133 >               by peername.regex=IP:10\..+ read
1134 >       access to dn.subtree="dc=example,dc=com"
1135 >               by self write
1136 >               by dn.children="dc=example,dc=com" search
1137 >               by anonymous auth
1138
1139 This example applies to entries in the "{{EX:dc=example,dc=com}}"
1140 subtree. To all attributes except {{EX:homePhone}}, an entry can
1141 write to itself, entries under {{EX:example.com}} entries can search
1142 by them, anybody else has no access (implicit {{EX:by * none}})
1143 excepting for authentication/authorization (which is always done
1144 anonymously).  The {{EX:homePhone}} attribute is writable by the
1145 entry, searchable by entries under {{EX:example.com}}, readable by
1146 clients connecting from network 10, and otherwise not readable
1147 (implicit {{EX:by * none}}).  All other access is denied by the
1148 implicit {{EX:access to * by * none}}.
1149
1150 Sometimes it is useful to permit a particular DN to add or
1151 remove itself from an attribute. For example, if you would like to
1152 create a group and allow people to add and remove only
1153 their own DN from the member attribute, you could accomplish
1154 it with an access directive like this:
1155
1156 >       access to attr=member,entry
1157 >               by dnattr=member selfwrite
1158
1159 The dnattr {{EX:<who>}} selector says that the access applies to
1160 entries listed in the {{EX:member}} attribute. The {{EX:selfwrite}} access
1161 selector says that such members can only add or delete their
1162 own DN from the attribute, not other values. The addition of
1163 the entry attribute is required because access to the entry is
1164 required to access any of the entry's attributes.
1165
1166 !if 0
1167 For more details on how to use the {{EX:access}} directive,
1168 consult the {{Advanced Access Control}} chapter.
1169 !endif
1170
1171
1172 H2: Configuration File Example
1173
1174 The following is an example configuration file, interspersed
1175 with explanatory text. It defines two databases to handle
1176 different parts of the {{TERM:X.500}} tree; both are {{TERM:BDB}}
1177 database instances. The line numbers shown are provided for
1178 reference only and are not included in the actual file. First, the
1179 global configuration section:
1180
1181 E:  1.  # example config file - global configuration section
1182 E:  2.  include /usr/local/etc/schema/core.schema
1183 E:  3.  referral ldap://root.openldap.org
1184 E:  4.  access to * by * read
1185  
1186 Line 1 is a comment. Line 2 includes another config file
1187 which contains {{core}} schema definitions.
1188 The {{EX:referral}} directive on line 3
1189 means that queries not local to one of the databases defined
1190 below will be referred to the LDAP server running on the
1191 standard port (389) at the host {{EX:root.openldap.org}}.
1192
1193 Line 4 is a global access control.  It applies to all
1194 entries (after any applicable database-specific access
1195 controls).
1196
1197 The next section of the configuration file defines a BDB
1198 backend that will handle queries for things in the
1199 "dc=example,dc=com" portion of the tree. The
1200 database is to be replicated to two slave slapds, one on
1201 truelies, the other on judgmentday. Indices are to be
1202 maintained for several attributes, and the {{EX:userPassword}}
1203 attribute is to be protected from unauthorized access.
1204
1205 E:  5.  # BDB definition for the example.com
1206 E:  6.  database bdb
1207 E:  7.  suffix "dc=example,dc=com"
1208 E:  8.  directory /usr/local/var/openldap-data
1209 E:  9.  rootdn "cn=Manager,dc=example,dc=com"
1210 E: 10.  rootpw secret
1211 E: 11.  # replication directives
1212 E: 12.  replogfile /usr/local/var/openldap/slapd.replog
1213 E: 13.  replica uri=ldap://slave1.example.com:389
1214 E: 14.          binddn="cn=Replicator,dc=example,dc=com"
1215 E: 15.          bindmethod=simple credentials=secret
1216 E: 16.  replica uri=ldaps://slave2.example.com:636
1217 E: 17.          binddn="cn=Replicator,dc=example,dc=com"
1218 E: 18.          bindmethod=simple credentials=secret
1219 E: 19.  # indexed attribute definitions
1220 E: 20.  index uid pres,eq
1221 E: 21.  index cn,sn,uid pres,eq,approx,sub
1222 E: 22.  index objectClass eq
1223 E: 23.  # database access control definitions
1224 E: 24.  access to attr=userPassword
1225 E: 25.          by self write
1226 E: 26.          by anonymous auth
1227 E: 27.          by dn.base="cn=Admin,dc=example,dc=com" write
1228 E: 28.          by * none
1229 E: 29.  access to *
1230 E: 30.          by self write
1231 E: 31.          by dn.base="cn=Admin,dc=example,dc=com" write
1232 E: 32.          by * read
1233
1234 Line 5 is a comment. The start of the database definition is marked
1235 by the database keyword on line 6. Line 7 specifies the DN suffix
1236 for queries to pass to this database. Line 8 specifies the directory
1237 in which the database files will live.
1238
1239 Lines 9 and 10 identify the database {{super-user}} entry and associated
1240 password. This entry is not subject to access control or size or
1241 time limit restrictions.
1242
1243 Lines 11 through 18 are for replication. Line 12 specifies the
1244 replication log file (where changes to the database are logged -
1245 this file is written by slapd and read by slurpd). Lines 13 through
1246 15 specify the hostname and port for a replicated host, the DN to
1247 bind as when performing updates, the bind method (simple) and the
1248 credentials (password) for the binddn. Lines 16 through 18 specify
1249 a second replication site.  See the {{SECT:Replication with slurpd}}
1250 chapter for more information on these directives.
1251
1252 Lines 20 through 22 indicate the indices to maintain for various
1253 attributes.
1254
1255 Lines 24 through 32 specify access control for entries in this
1256 database.  As this is the first database, the controls also apply
1257 to entries not held in any database (such as the Root DSE).  For
1258 all applicable entries, the {{EX:userPassword}} attribute is writable
1259 by the entry itself and by the "admin" entry.  It may be used for
1260 authentication/authorization purposes, but is otherwise not readable.
1261 All other attributes are writable by the entry and the "admin"
1262 entry, but may be read by all users (authenticated or not).
1263
1264 The next section of the example configuration file defines another
1265 BDB database. This one handles queries involving the
1266 {{EX:dc=example,dc=net}} subtree but is managed by the same entity
1267 as the first database.  Note that without line 39, the read access
1268 would be allowed due to the global access rule at line 4.
1269
1270 E: 33.  # BDB definition for example.net
1271 E: 34.  database bdb
1272 E: 35.  suffix "dc=example,dc=net"
1273 E: 36.  directory /usr/local/var/openldap-data-net
1274 E: 37.  rootdn "cn=Manager,dc=example,dc=com"
1275 E: 38.  index objectClass eq
1276 E: 39.  access to * by users read