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