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