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