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