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