2 # Copyright 2005-2007 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
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(8) runtime configuration in 2.3 (and later)
10 is 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-config}}(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. When
22 converting from the slapd.conf format to slapd.d format, any
23 include files will also be integrated into the resulting configuration
26 An alternate configuration directory (or file) can be specified via
27 a command-line option to {{slapd}}(8). This chapter describes the
28 general format of the configuration system, followed by a detailed
29 description of commonly used config settings.
31 Note: some of the backends and of the distributed overlays
32 do not support runtime configuration yet. In those cases,
33 the old style {{slapd.conf}}(5) file must be used.
35 Note: the current version of {{slurpd}} has not been updated for
36 compatibility with this new configuration engine. If you must use
37 slurpd for replication at your site, you will have to maintain an
38 old-style {{slapd.conf}} file for slurpd to use.
41 H2: Configuration Layout
43 The slapd configuration is stored as a special LDAP directory with
44 a predefined schema and DIT. There are specific objectClasses used to
45 carry global configuration options, schema definitions, backend and
46 database definitions, and assorted other items. A sample config tree
47 is shown in Figure 5.1.
49 !import "config_dit.gif"; align="center"; title="Sample configuration tree"
50 FT[align="Center"] Figure 5.1: Sample configuration tree.
52 Other objects may be part of the configuration but were omitted from
53 the illustration for clarity.
55 The {{slapd-config}} configuration tree has a very specific structure. The
56 root of the tree is named {{EX:cn=config}} and contains global configuration
57 settings. Additional settings are contained in separate child entries:
58 * Dynamically loaded modules
59 .. These may only be used if the {{EX:--enable-modules}} option was
60 used to configure the software.
62 .. The {{EX:cn=schema,cn=config}} entry contains the system schema (all
63 the schema that is hard-coded in slapd).
64 .. Child entries of {{EX:cn=schema,cn=config}} contain user schema as
65 loaded from config files or added at runtime.
66 * Backend-specific configuration
67 * Database-specific configuration
68 .. Overlays are defined in children of the Database entry.
69 .. Databases and Overlays may also have other miscellaneous children.
71 The usual rules for LDIF files apply to the configuration information:
72 Comment lines beginning with a '{{EX:#}}' character
73 are ignored. If a line begins with a single space, it is considered a
74 continuation of the previous line (even if the previous line is a
75 comment) and the single leading space is removed. Entries are separated by blank lines.
77 The general layout of the config LDIF is as follows:
79 > # global configuration settings
81 > objectClass: olcGlobal
83 > <global config settings>
85 > # schema definitions
86 > dn: cn=schema,cn=config
87 > objectClass: olcSchemaConfig
91 > dn: cn={X}core,cn=schema,cn=config
92 > objectClass: olcSchemaConfig
96 > # additional user-specified schema
99 > # backend definitions
100 > dn: olcBackend=<typeA>,cn=config
101 > objectClass: olcBackendConfig
102 > olcBackend: <typeA>
103 > <backend-specific settings>
105 > # database definitions
106 > dn: olcDatabase={X}<typeA>,cn=config
107 > objectClass: olcDatabaseConfig
108 > olcDatabase: {X}<typeA>
109 > <database-specific settings>
111 > # subsequent definitions and settings
114 Some of the entries listed above have a numeric index {{EX:"{X}"}} in
115 their names. While most configuration settings have an inherent ordering
116 dependency (i.e., one setting must take effect before a subsequent one
117 may be set), LDAP databases are inherently unordered. The numeric index
118 is used to enforce a consistent ordering in the configuration database,
119 so that all ordering dependencies are preserved. In most cases the index
120 does not have to be provided; it will be automatically generated based
121 on the order in which entries are created.
123 Configuration directives are specified as values of individual
125 Most of the attributes and objectClasses used in the slapd
126 configuration have a prefix of {{EX:"olc"}} (OpenLDAP Configuration)
127 in their names. Generally there is a one-to-one correspondence
128 between the attributes and the old-style {{EX:slapd.conf}} configuration
129 keywords, using the keyword as the attribute name, with the "olc"
132 A configuration directive may take arguments. If so, the arguments are
133 separated by white space. If an argument contains white space,
134 the argument should be enclosed in double quotes {{EX:"like this"}}.
135 In the descriptions that follow, arguments that should be replaced
136 by actual text are shown in brackets {{EX:<>}}.
138 The distribution contains an example configuration file that will
139 be installed in the {{F: /usr/local/etc/openldap}} directory.
140 A number of files containing schema definitions (attribute types
141 and object classes) are also provided in the
142 {{F: /usr/local/etc/openldap/schema}} directory.
145 H2: Configuration Directives
147 This section details commonly used configuration directives. For
148 a complete list, see the {{slapd-config}}(5) manual page. This section
149 will treat the configuration directives in a top-down order, starting
150 with the global directives in the {{EX:cn=config}} entry. Each
151 directive will be described along with its default value (if any) and
152 an example of its use.
157 Directives contained in this entry generally apply to the server as a whole.
158 Most of them are system or connection oriented, not database related. This
159 entry must have the {{EX:olcGlobal}} objectClass.
162 H4: olcIdleTimeout: <integer>
164 Specify the number of seconds to wait before forcibly closing
165 an idle client connection. A value of 0, the default,
166 disables this feature.
169 H4: olcLogLevel: <level>
171 This directive specifies the level at which debugging statements
172 and operation statistics should be syslogged (currently logged to
173 the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have
174 configured OpenLDAP {{EX:--enable-debug}} (the default) for this
175 to work (except for the two statistics levels, which are always
176 enabled). Log levels may be specified as integers or by keyword.
177 Multiple log levels may be used and the levels are additive.
178 To display what levels
179 correspond to what kind of debugging, invoke slapd with {{EX:-?}}
180 or consult the table below. The possible values for <level> are:
182 !block table; colaligns="RL"; align=Center; \
183 title="Table 5.1: Debugging Levels"
184 Level Keyword Description
185 -1 Any enable all debugging
187 1 Trace trace function calls
188 2 Packets debug packet handling
189 4 Args heavy trace debugging
190 8 Conns connection management
191 16 BER print out packets sent and received
192 32 Filter search filter processing
193 64 Config configuration processing
194 128 ACL access control list processing
195 256 Stats stats log connections/operations/results
196 512 Stats2 stats log entries sent
197 1024 Shell print communication with shell backends
198 2048 Parse print entry parsing debugging
199 4096 Cache database cache processing
200 8192 Index database indexing
201 16384 Sync syncrepl consumer processing
208 This will cause lots and lots of debugging information to be
211 E: olcLogLevel: Conns Filter
213 Just log the connection and search filter processing.
217 E: olcLogLevel: Stats
220 H4: olcReferral <URI>
222 This directive specifies the referral to pass back when slapd
223 cannot find a local database to handle a request.
227 > olcReferral: ldap://root.openldap.org
229 This will refer non-local queries to the global root LDAP server
230 at the OpenLDAP Project. Smart LDAP clients can re-ask their
231 query at that server, but note that most of these clients are
232 only going to know how to handle simple LDAP URLs that
233 contain a host part and optionally a distinguished name part.
239 >objectClass: olcGlobal
243 >olcReferral: ldap://root.openldap.org
248 If support for dynamically loaded modules was enabled when configuring
249 slapd, {{EX:cn=module}} entries may be used to specify sets of modules to load.
250 Module entries must have the {{EX:olcModuleList}} objectClass.
253 H4: olcModuleLoad: <filename>
255 Specify the name of a dynamically loadable module to load. The filename
256 may be an absolute path name or a simple filename. Non-absolute names
257 are searched for in the directories specified by the {{EX:olcModulePath}}
261 H4: olcModulePath: <pathspec>
263 Specify a list of directories to search for loadable modules. Typically the
264 path is colon-separated but this depends on the operating system.
269 >dn: cn=module{0},cn=config
270 >objectClass: olcModuleList
272 >olcModuleLoad: /usr/local/lib/smbk5pwd.la
274 >dn: cn=module{1},cn=config
275 >objectClass: olcModuleList
277 >olcModulePath: /usr/local/lib:/usr/local/lib/slapd
278 >olcModuleLoad: accesslog.la
279 >olcModuleLoad: pcache.la
284 The cn=schema entry holds all of the schema definitions that are hard-coded
285 in slapd. As such, the values in this entry are generated by slapd so no
286 schema values need to be provided in the config file. The entry must still
287 be defined though, to serve as a base for the user-defined schema to add
288 in underneath. Schema entries must have the {{EX:olcSchemaConfig}}
292 H4: olcAttributeTypes: <{{REF:RFC4512}} Attribute Type Description>
294 This directive defines an attribute type.
295 Please see the {{SECT:Schema Specification}} chapter
296 for information regarding how to use this directive.
299 H4: olcObjectClasses: <{{REF:RFC4512}} Object Class Description>
301 This directive defines an object class.
302 Please see the {{SECT:Schema Specification}} chapter for
303 information regarding how to use this directive.
308 >dn: cn=schema,cn=config
309 >objectClass: olcSchemaConfig
312 >dn: cn=test,cn=schema,cn=config
313 >objectClass: olcSchemaConfig
315 >olcAttributeTypes: ( 1.1.1
317 > EQUALITY integerMatch
318 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 )
319 >olcAttributeTypes: ( 1.1.2 NAME 'testTwo' EQUALITY caseIgnoreMatch
320 > SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 )
321 >olcObjectClasses: ( 1.1.3 NAME 'testObject'
322 > MAY ( testAttr $ testTwo ) AUXILIARY )
325 H3: Backend-specific Directives
327 Backend directives apply to all database instances of the
328 same type and, depending on the directive, may be overridden
329 by database directives. Backend entries must have the
330 {{EX:olcBackendConfig}} objectClass.
332 H4: olcBackend: <type>
334 This directive names a backend-specific configuration entry.
335 {{EX:<type>}} should be one of the
336 supported backend types listed in Table 5.2.
338 !block table; align=Center; coltags="EX,N"; \
339 title="Table 5.2: Database Backends"
341 bdb Berkeley DB transactional backend
342 config Slapd configuration backend
343 dnssrv DNS SRV backend
344 hdb Hierarchical variant of bdb backend
345 ldap Lightweight Directory Access Protocol (Proxy) backend
346 ldif Lightweight Data Interchange Format backend
347 meta Meta Directory backend
348 monitor Monitor backend
349 passwd Provides read-only access to {{passwd}}(5)
350 perl Perl Programmable backend
351 shell Shell (extern program) backend
352 sql SQL Programmable backend
359 There are no other directives defined for this entry. Specific backend
360 types may define additional attributes for their particular use but so
361 far none have ever been defined. As such, these directives usually do
362 not appear in any actual configurations.
367 > dn: olcBackend=bdb,cn=config
368 > objectClass: olcBackendConfig
372 H3: Database-specific Directives
374 Directives in this section are supported by every type of database.
375 Database entries must have the {{EX:olcDatabaseConfig}} objectClass.
377 H4: olcDatabase: [{<index>}]<type>
379 This directive names a specific database instance. The numeric {<index>} may
380 be provided to distinguish multiple databases of the same type. Usually the
381 index can be omitted, and slapd will generate it automatically.
382 {{EX:<type>}} should be one of the
383 supported backend types listed in Table 5.2 or the {{EX:frontend}} type.
385 The {{EX:frontend}} is a special database that is used to hold
386 database-level options that should be applied to all the other
387 databases. Subsequent database definitions may also override some
390 The {{EX:config}} database is also special; both the {{EX:config}} and
391 the {{EX:frontend}} databases are always created implicitly even if they
392 are not explicitly configured, and they are created before any other
399 This marks the beginning of a new {{TERM:BDB}} database instance.
402 H4: olcAccess: to <what> [ by <who> [<accesslevel>] [<control>] ]+
404 This directive grants access (specified by <accesslevel>) to a
405 set of entries and/or attributes (specified by <what>) by one or
406 more requesters (specified by <who>).
407 See the {{SECT:Access Control}} section of this chapter for a
408 summary of basic usage.
411 More detailed discussion of this directive can be found in the
412 {{SECT:Advanced Access Control}} chapter.
415 Note: If no {{EX:olcAccess}} directives are specified, the default
416 access control policy, {{EX:to * by * read}}, allows all
417 users (both authenticated and anonymous) read access.
419 Note: Access controls defined in the frontend are appended to all
420 other databases' controls.
423 H4: olcReadonly { TRUE | FALSE }
425 This directive puts the database into "read-only" mode. Any
426 attempts to modify the database will return an "unwilling to
436 > olcReplica: uri=ldap[s]://<hostname>[:<port>] | host=<hostname>[:<port>]
437 > [bindmethod={simple|sasl}]
440 > [authcid=<identity>]
441 > [authzid=<identity>]
442 > [credentials=<password>]
444 This directive specifies a replication site for this database for
446 {{EX:uri=}} parameter specifies a scheme, a host and optionally a port where
447 the slave slapd instance can be found. Either a domain name
448 or IP address may be used for <hostname>. If <port> is not
449 given, the standard LDAP port number (389 or 636) is used.
451 {{EX:host}} is deprecated in favor of the {{EX:uri}} parameter.
453 {{EX:uri}} allows the replica LDAP server to be specified as an LDAP
454 URI such as {{EX:ldap://slave.example.com:389}} or
455 {{EX:ldaps://slave.example.com:636}}.
457 The {{EX:binddn=}} parameter gives the DN to bind as for updates
458 to the slave slapd. It should be a DN which has read/write access
459 to the slave slapd's database. It must also match the {{EX:updatedn}}
460 directive in the slave slapd's config file. Generally, this DN
461 {{should not}} be the same as the {{EX:rootdn}} of the master
462 database. Since DNs are likely to contain embedded spaces, the
463 entire {{EX:"binddn=<DN>"}} string should be enclosed in double
466 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
467 depending on whether simple password-based authentication
468 or {{TERM:SASL}} authentication is to be used when connecting
471 Simple authentication should not be used unless adequate data
472 integrity and confidentiality protections are in place (e.g. TLS
473 or {{TERM:IPsec}}). Simple authentication requires specification
474 of {{EX:binddn}} and {{EX:credentials}} parameters.
476 SASL authentication is generally recommended. SASL authentication
477 requires specification of a mechanism using the {{EX:saslmech}} parameter.
478 Depending on the mechanism, an authentication identity and/or
479 credentials can be specified using {{EX:authcid}} and {{EX:credentials}}
480 respectively. The {{EX:authzid}} parameter may be used to specify
481 an authorization identity.
483 See the chapter entitled {{SECT:Replication with slurpd}} for more
484 information on how to use this directive.
487 H4: olcReplogfile: <filename>
489 This directive specifies the name of the replication log file to
490 which slapd will log changes. The replication log is typically
491 written by {{slapd}}(8) and read by {{slurpd}}(8). Normally, this
492 directive is only used if {{slurpd}}(8) is being used to replicate
493 the database. However, you can also use it to generate a transaction
494 log, if {{slurpd}}(8) is not running. In this case, you will need to
495 periodically truncate the file, since it will grow indefinitely
498 See the chapter entitled {{SECT:Replication with slurpd}} for more
499 information on how to use this directive.
504 This directive specifies the DN that is not subject to
505 access control or administrative limit restrictions for
506 operations on this database. The DN need not refer to
507 an entry in this database or even in the directory. The
508 DN may refer to a SASL identity.
512 > olcRootDN: "cn=Manager,dc=example,dc=com"
516 > olcRootDN: "uid=root,cn=example.com,cn=digest-md5,cn=auth"
518 See the {{SECT:SASL Authentication}} section for information on
519 SASL authentication identities.
522 H4: olcRootPW: <password>
524 This directive can be used to specify a password for the DN for
525 the rootdn (when the rootdn is set to a DN within the database).
531 It is also permissible to provide a hash of the password in
532 {{REF:RFC2307}} form. {{slappasswd}}(8) may be used to generate
537 > olcRootPW: {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN
539 The hash was generated using the command {{EX:slappasswd -s secret}}.
542 H4: olcSizeLimit: <integer>
544 This directive specifies the maximum number of entries to return
545 from a search operation.
553 H4: olcSuffix: <dn suffix>
555 This directive specifies the DN suffix of queries that will be
556 passed to this backend database. Multiple suffix lines can be
557 given, and usually at least one is required for each database
558 definition. (Some backend types, such as {{EX:frontend}} and
559 {{EX:monitor}} use a hard-coded suffix which may not be overridden
560 in the configuration.)
564 > olcSuffix: "dc=example,dc=com"
566 Queries with a DN ending in "dc=example,dc=com"
567 will be passed to this backend.
569 Note: When the backend to pass a query to is selected, slapd
570 looks at the suffix value(s) in each database definition in the
571 order in which they were configured. Thus, if one database suffix is a
572 prefix of another, it must appear after it in the configuration.
577 > olcSyncrepl: rid=<replica ID>
578 > provider=ldap[s]://<hostname>[:port]
579 > [type=refreshOnly|refreshAndPersist]
580 > [interval=dd:hh:mm:ss]
581 > [retry=[<retry interval> <# of retries>]+]
582 > searchbase=<base DN>
583 > [filter=<filter str>]
584 > [scope=sub|one|base]
585 > [attrs=<attr list>]
587 > [sizelimit=<limit>]
588 > [timelimit=<limit>]
589 > [schemachecking=on|off]
590 > [bindmethod=simple|sasl]
593 > [authcid=<identity>]
594 > [authzid=<identity>]
595 > [credentials=<passwd>]
597 > [secprops=<properties>]
598 > [starttls=yes|critical]
601 > [tls_cacert=<file>]
602 > [tls_cacertdir=<path>]
603 > [tls_reqcert=never|allow|try|demand]
604 > [tls_ciphersuite=<ciphers>]
605 > [tls_crlcheck=none|peer|all]
606 > [logbase=<base DN>]
607 > [logfilter=<filter str>]
608 > [syncdata=default|accesslog|changelog]
611 This directive specifies the current database as a replica of the
612 master content by establishing the current {{slapd}}(8) as a
613 replication consumer site running a syncrepl replication engine.
614 The master database is located at the replication provider site
615 specified by the {{EX:provider}} parameter. The replica database is
616 kept up-to-date with the master content using the LDAP Content
617 Synchronization protocol. See {{REF:RFC4533}}
618 for more information on the protocol.
620 The {{EX:rid}} parameter is used for identification of the current
621 {{EX:syncrepl}} directive within the replication consumer server,
622 where {{EX:<replica ID>}} uniquely identifies the syncrepl specification
623 described by the current {{EX:syncrepl}} directive. {{EX:<replica ID>}}
624 is non-negative and is no more than three decimal digits in length.
626 The {{EX:provider}} parameter specifies the replication provider site
627 containing the master content as an LDAP URI. The {{EX:provider}}
628 parameter specifies a scheme, a host and optionally a port where the
629 provider slapd instance can be found. Either a domain name or IP
630 address may be used for <hostname>. Examples are
631 {{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}.
632 If <port> is not given, the standard LDAP port number (389 or 636) is used.
633 Note that the syncrepl uses a consumer-initiated protocol, and hence its
634 specification is located at the consumer site, whereas the {{EX:replica}}
635 specification is located at the provider site. {{EX:syncrepl}} and
636 {{EX:replica}} directives define two independent replication
637 mechanisms. They do not represent the replication peers of each other.
639 The content of the syncrepl replica is defined using a search
640 specification as its result set. The consumer slapd will
641 send search requests to the provider slapd according to the search
642 specification. The search specification includes {{EX:searchbase}},
643 {{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:attrsonly}},
644 {{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal
645 search specification. The {{EX:searchbase}} parameter has no
646 default value and must always be specified. The {{EX:scope}} defaults
647 to {{EX:sub}}, the {{EX:filter}} defaults to {{EX:(objectclass=*)}},
648 {{EX:attrs}} defaults to {{EX:"*,+"}} to replicate all user and operational
649 attributes, and {{EX:attrsonly}} is unset by default. Both {{EX:sizelimit}}
650 and {{EX:timelimit}} default to "unlimited", and only positive integers
651 or "unlimited" may be specified.
653 The {{TERM[expand]LDAP Sync}} protocol has two operation
654 types: {{EX:refreshOnly}} and {{EX:refreshAndPersist}}.
655 The operation type is specified by the {{EX:type}} parameter.
656 In the {{EX:refreshOnly}} operation, the next synchronization search operation
657 is periodically rescheduled at an interval time after each
658 synchronization operation finishes. The interval is specified
659 by the {{EX:interval}} parameter. It is set to one day by default.
660 In the {{EX:refreshAndPersist}} operation, a synchronization search
661 remains persistent in the provider {{slapd}} instance. Further updates to the
662 master replica will generate {{EX:searchResultEntry}} to the consumer slapd
663 as the search responses to the persistent synchronization search.
665 If an error occurs during replication, the consumer will attempt to reconnect
666 according to the retry parameter which is a list of the <retry interval>
667 and <# of retries> pairs. For example, retry="60 10 300 3" lets the consumer
668 retry every 60 seconds for the first 10 times and then retry every 300 seconds
669 for the next three times before stop retrying. + in <# of retries> means
670 indefinite number of retries until success.
672 The schema checking can be enforced at the LDAP Sync consumer site
673 by turning on the {{EX:schemachecking}} parameter.
674 If it is turned on, every replicated entry will be checked for its
675 schema as the entry is stored into the replica content.
676 Every entry in the replica should contain those attributes
677 required by the schema definition.
678 If it is turned off, entries will be stored without checking
679 schema conformance. The default is off.
681 The {{EX:binddn}} parameter gives the DN to bind as for the
682 syncrepl searches to the provider slapd. It should be a DN
683 which has read access to the replication content in the
686 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
687 depending on whether simple password-based authentication or
688 {{TERM:SASL}} authentication is to be used when connecting
689 to the provider {{slapd}} instance.
691 Simple authentication should not be used unless adequate data
692 integrity and confidentiality protections are in place (e.g. TLS
693 or IPsec). Simple authentication requires specification of {{EX:binddn}}
694 and {{EX:credentials}} parameters.
696 SASL authentication is generally recommended. SASL authentication
697 requires specification of a mechanism using the {{EX:saslmech}} parameter.
698 Depending on the mechanism, an authentication identity and/or
699 credentials can be specified using {{EX:authcid}} and {{EX:credentials}},
700 respectively. The {{EX:authzid}} parameter may be used to specify
701 an authorization identity.
703 The {{EX:realm}} parameter specifies a realm which a certain
704 mechanisms authenticate the identity within. The {{EX:secprops}}
705 parameter specifies Cyrus SASL security properties.
707 The {{EX:starttls}} parameter specifies use of the StartTLS extended
708 operation to establish a TLS session before authenticating to the provider.
709 If the {{EX:critical}} argument is supplied, the session will be aborted
710 if the StartTLS request fails. Otherwise the syncrepl session continues
711 without TLS. Note that the main slapd TLS settings are not used by the
712 syncrepl engine; by default the TLS parameters from a {{ldap.conf}}(5)
713 configuration file will be used. TLS settings may be specified here,
714 in which case any {{ldap.conf}}(5) settings will be completely ignored.
716 Rather than replicating whole entries, the consumer can query logs
717 of data modifications. This mode of operation is referred to as
718 {{delta syncrepl}}. In addition to the above parameters, the
719 {{EX:logbase}} and {{EX:logfilter}} parameters must be set appropriately
720 for the log that will be used. The {{EX:syncdata}} parameter must
721 be set to either {{EX:"accesslog"}} if the log conforms to the
722 {{slapo-accesslog}}(5) log format, or {{EX:"changelog"}} if the log
723 conforms to the obsolete {{changelog}} format. If the {{EX:syncdata}}
724 parameter is omitted or set to {{EX:"default"}} then the log
725 parameters are ignored.
727 The {{syncrepl}} replication mechanism is supported by the {{bdb}} and
730 See the {{SECT:LDAP Sync Replication}} chapter of this guide for
731 more information on how to use this directive.
734 H4: olcTimeLimit: <integer>
736 This directive specifies the maximum number of seconds (in real
737 time) slapd will spend answering a search request. If a
738 request is not finished in this time, a result indicating an
739 exceeded timelimit will be returned.
746 H4: olcUpdateDN: <DN>
748 This directive is only applicable in a slave slapd. It specifies
749 the DN allowed to make changes to the replica. This may be the DN
750 {{slurpd}}(8) binds as when making changes to the replica or the DN
751 associated with a SASL identity.
755 > olcUpdateDN: "cn=Update Daemon,dc=example,dc=com"
759 > olcUpdateDN: "uid=slurpd,cn=example.com,cn=digest-md5,cn=auth"
761 See the {{SECT:Replication with slurpd}} chapter for more information
762 on how to use this directive.
764 H4: olcUpdateref: <URL>
766 This directive is only applicable in a slave slapd. It
767 specifies the URL to return to clients which submit update
768 requests upon the replica.
769 If specified multiple times, each {{TERM:URL}} is provided.
773 > olcUpdateref: ldap://master.example.net
778 >dn: olcDatabase=frontend,cn=config
779 >objectClass: olcDatabaseConfig
780 >objectClass: olcFrontendConfig
781 >olcDatabase: frontend
784 >dn: olcDatabase=config,cn=config
785 >objectClass: olcDatabaseConfig
787 >olcRootDN: cn=Manager,dc=example,dc=com
790 H3: BDB and HDB Database Directives
792 Directives in this category apply to both the {{TERM:BDB}}
793 and the {{TERM:HDB}} database.
794 They are used in an olcDatabase entry in addition to the generic
795 database directives defined above. For a complete reference
796 of BDB/HDB configuration directives, see {{slapd-bdb}}(5). In
797 addition to the {{EX:olcDatabaseConfig}} objectClass, BDB and HDB
798 database entries must have the {{EX:olcBdbConfig}} and
799 {{EX:olcHdbConfig}} objectClass, respectively.
802 H4: olcDbDirectory: <directory>
804 This directive specifies the directory where the BDB files
805 containing the database and associated indices live.
809 > olcDbDirectory: /usr/local/var/openldap-data
812 H4: olcDbCachesize: <integer>
814 This directive specifies the size in entries of the in-memory
815 cache maintained by the BDB backend database instance.
819 > olcDbCachesize: 1000
822 H4: olcDbCheckpoint: <kbyte> <min>
824 This directive specifies how often to checkpoint the BDB transaction log.
825 A checkpoint operation flushes the database buffers to disk and writes a
826 checkpoint record in the log.
827 The checkpoint will occur if either <kbyte> data has been written or
828 <min> minutes have passed since the last checkpont. Both arguments default
829 to zero, in which case they are ignored. When the <min> argument is
830 non-zero, an internal task will run every <min> minutes to perform the
831 checkpoint. See the Berkeley DB reference guide for more details.
835 > olcDbCheckpoint: 1024 10
838 H4: olcDbConfig: <DB_CONFIG setting>
840 This attribute specifies a configuration directive to be placed in the
841 {{EX:DB_CONFIG}} file of the database directory. At server startup time, if
842 no such file exists yet, the {{EX:DB_CONFIG}} file will be created and the
843 settings in this attribute will be written to it. If the file exists,
844 its contents will be read and displayed in this attribute. The attribute
845 is multi-valued, to accomodate multiple configuration directives. No default
846 is provided, but it is essential to use proper settings here to get the
847 best server performance.
849 Any changes made to this attribute will be written to the {{EX:DB_CONFIG}}
850 file and will cause the database environment to be reset so the changes
851 can take immediate effect. If the environment cache is large and has not
852 been recently checkpointed, this reset operation may take a long time. It
853 may be advisable to manually perform a single checkpoint using the Berkeley DB
854 {{db_checkpoint}} utility before using LDAP Modify to change this
859 > olcDbConfig: set_cachesize 0 10485760 0
860 > olcDbConfig: set_lg_bsize 2097512
861 > olcDbConfig: set_lg_dir /var/tmp/bdb-log
862 > olcDbConfig: set_flags DB_LOG_AUTOREMOVE
864 In this example, the BDB cache is set to 10MB, the BDB transaction log
865 buffer size is set to 2MB, and the transaction log files are to be stored
866 in the /var/tmp/bdb-log directory. Also a flag is set to tell BDB to
867 delete transaction log files as soon as their contents have been
868 checkpointed and they are no longer needed. Without this setting the
869 transaction log files will continue to accumulate until some other
870 cleanup procedure removes them. See the Berkeley DB documentation for the
871 {{EX:db_archive}} command for details.
873 Ideally the BDB cache must be
874 at least as large as the working set of the database, the log buffer size
875 should be large enough to accomodate most transactions without overflowing,
876 and the log directory must be on a separate physical disk from the main
877 database files. And both the database directory and the log directory
878 should be separate from disks used for regular system activities such as
879 the root, boot, or swap filesystems. See the FAQ-o-Matic and the Berkeley DB
880 documentation for more details.
883 H4: olcDbNosync: { TRUE | FALSE }
885 This option causes on-disk database contents to not be immediately
886 synchronized with in memory changes upon change. Setting this option
887 to {{EX:TRUE}} may improve performance at the expense of data integrity. This
888 directive has the same effect as using
889 > olcDbConfig: set_flags DB_TXN_NOSYNC
892 H4: olcDbIDLcacheSize: <integer>
894 Specify the size of the in-memory index cache, in index slots. The
895 default is zero. A larger value will speed up frequent searches of
896 indexed entries. The optimal size will depend on the data and search
897 characteristics of the database, but using a number three times
898 the entry cache size is a good starting point.
902 > olcDbIDLcacheSize: 3000
905 H4: olcDbIndex: {<attrlist> | default} [pres,eq,approx,sub,none]
907 This directive specifies the indices to maintain for the given
908 attribute. If only an {{EX:<attrlist>}} is given, the default
909 indices are maintained. The index keywords correspond to the
910 common types of matches that may be used in an LDAP search filter.
914 > olcDbIndex: default pres,eq
916 > olcDbIndex: cn,sn pres,eq,sub
917 > olcDbIndex: objectClass eq
919 The first line sets the default set of indices to maintain to
920 present and equality. The second line causes the default (pres,eq)
921 set of indices to be maintained for the {{EX:uid}} attribute type.
922 The third line causes present, equality, and substring indices to
923 be maintained for {{EX:cn}} and {{EX:sn}} attribute types. The
924 fourth line causes an equality index for the {{EX:objectClass}}
927 There is no index keyword for inequality matches. Generally these
928 matches do not use an index. However, some attributes do support
929 indexing for inequality matches, based on the equality index.
931 A substring index can be more explicitly specified as {{EX:subinitial}},
932 {{EX:subany}}, or {{EX:subfinal}}, corresponding to the three
934 of a substring match filter. A subinitial index only indexes
935 substrings that appear at the beginning of an attribute value.
936 A subfinal index only indexes substrings that appear at the end
937 of an attribute value, while subany indexes substrings that occur
940 Note that by default, setting an index for an attribute also
941 affects every subtype of that attribute. E.g., setting an equality
942 index on the {{EX:name}} attribute causes {{EX:cn}}, {{EX:sn}}, and every other
943 attribute that inherits from {{EX:name}} to be indexed.
945 By default, no indices are maintained. It is generally advised
946 that minimally an equality index upon objectClass be maintained.
948 > olcDbindex: objectClass eq
950 Additional indices should be configured corresponding to the
951 most common searches that are used on the database.
952 Presence indexing should not be configured for an attribute
953 unless the attribute occurs very rarely in the database, and
954 presence searches on the attribute occur very frequently during
955 normal use of the directory. Most applications don't use presence
956 searches, so usually presence indexing is not very useful.
958 If this setting is changed while slapd is running, an internal task
959 will be run to generate the changed index data. All server operations
960 can continue as normal while the indexer does its work. If slapd is
961 stopped before the index task completes, indexing will have to be
962 manually completed using the slapindex tool.
965 H4: olcDbLinearIndex: { TRUE | FALSE }
967 If this setting is {{EX:TRUE}} slapindex will index one attribute
968 at a time. The default settings is {{EX:FALSE}} in which case all
969 indexed attributes of an entry are processed at the same time. When
970 enabled, each indexed attribute is processed individually, using
971 multiple passes through the entire database. This option improves
972 slapindex performance when the database size exceeds the BDB cache
973 size. When the BDB cache is large enough, this option is not needed
974 and will decrease performance. Also by default, slapadd performs
975 full indexing and so a separate slapindex run is not needed. With
976 this option, slapadd does no indexing and slapindex must be used.
979 H4: olcDbMode: <integer>
981 This directive specifies the file protection mode that newly
982 created database index files should have.
989 H4: olcDbSearchStack: <integer>
991 Specify the depth of the stack used for search filter evaluation.
992 Search filters are evaluated on a stack to accomodate nested {{EX:AND}} /
993 {{EX:OR}} clauses. An individual stack is allocated for each server thread.
994 The depth of the stack determines how complex a filter can be evaluated
995 without requiring any additional memory allocation. Filters that are
996 nested deeper than the search stack depth will cause a separate stack to
997 be allocated for that particular search operation. These separate allocations
998 can have a major negative impact on server performance, but specifying
999 too much stack will also consume a great deal of memory. Each search
1000 uses 512K bytes per level on a 32-bit machine, or 1024K bytes per level
1001 on a 64-bit machine. The default stack depth is 16, thus 8MB or 16MB
1002 per thread is used on 32 and 64 bit machines, respectively. Also the
1003 512KB size of a single stack slot is set by a compile-time constant which
1004 may be changed if needed; the code must be recompiled for the change
1009 > olcDbSearchStack: 16
1012 H4: olcDbShmKey: <integer>
1014 Specify a key for a shared memory BDB environment. By default the BDB
1015 environment uses memory mapped files. If a non-zero value is specified,
1016 it will be used as the key to identify a shared memory region that will
1017 house the environment.
1026 >dn: olcDatabase=hdb,cn=config
1027 >objectClass: olcDatabaseConfig
1028 >objectClass: olcHdbConfig
1030 >olcSuffix: "dc=example,dc=com"
1031 >olcDbDirectory: /usr/local/var/openldap-data
1032 >olcDbCacheSize: 1000
1033 >olcDbCheckpoint: 1024 10
1034 >olcDbConfig: set_cachesize 0 10485760 0
1035 >olcDbConfig: set_lg_bsize 2097152
1036 >olcDbConfig: set_lg_dir /var/tmp/bdb-log
1037 >olcDbConfig: set_flags DB_LOG_AUTOREMOVE
1038 >olcDbIDLcacheSize: 3000
1039 >olcDbIndex: objectClass eq
1044 Access to slapd entries and attributes is controlled by the
1045 olcAccess attribute, whose values are a sequence of access directives.
1046 The general form of the olcAccess configuration is:
1048 > olcAccess: <access directive>
1049 > <access directive> ::= to <what>
1050 > [by <who> [<access>] [<control>] ]+
1052 > [dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
1053 > [filter=<ldapfilter>] [attrs=<attrlist>]
1054 > <basic-style> ::= regex | exact
1055 > <scope-style> ::= base | one | subtree | children
1056 > <attrlist> ::= <attr> [val[.<basic-style>]=<regex>] | <attr> , <attrlist>
1057 > <attr> ::= <attrname> | entry | children
1058 > <who> ::= * | [anonymous | users | self
1059 > | dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
1060 > [dnattr=<attrname>]
1061 > [group[/<objectclass>[/<attrname>][.<basic-style>]]=<regex>]
1062 > [peername[.<basic-style>]=<regex>]
1063 > [sockname[.<basic-style>]=<regex>]
1064 > [domain[.<basic-style>]=<regex>]
1065 > [sockurl[.<basic-style>]=<regex>]
1068 > <access> ::= [self]{<level>|<priv>}
1069 > <level> ::= none | disclose | auth | compare | search | read | write | manage
1070 > <priv> ::= {=|+|-}{m|w|r|s|c|x|d|0}+
1071 > <control> ::= [stop | continue | break]
1073 where the <what> part selects the entries and/or attributes to which
1074 the access applies, the {{EX:<who>}} part specifies which entities
1075 are granted access, and the {{EX:<access>}} part specifies the
1076 access granted. Multiple {{EX:<who> <access> <control>}} triplets
1077 are supported, allowing many entities to be granted different access
1078 to the same set of entries and attributes. Not all of these access
1079 control options are described here; for more details see the
1080 {{slapd.access}}(5) man page.
1083 H3: What to control access to
1085 The <what> part of an access specification determines the entries
1086 and attributes to which the access control applies. Entries are
1087 commonly selected in two ways: by DN and by filter. The following
1088 qualifiers select entries by DN:
1091 > to dn[.<basic-style>]=<regex>
1092 > to dn.<scope-style>=<DN>
1094 The first form is used to select all entries. The second form may
1095 be used to select entries by matching a regular expression against
1096 the target entry's {{normalized DN}}. (The second form is not
1097 discussed further in this document.) The third form is used to
1098 select entries which are within the requested scope of DN. The
1099 <DN> is a string representation of the Distinguished Name, as
1100 described in {{REF:RFC4514}}.
1102 The scope can be either {{EX:base}}, {{EX:one}}, {{EX:subtree}},
1103 or {{EX:children}}. Where {{EX:base}} matches only the entry with
1104 provided DN, {{EX:one}} matches the entries whose parent is the
1105 provided DN, {{EX:subtree}} matches all entries in the subtree whose
1106 root is the provided DN, and {{EX:children}} matches all entries
1107 under the DN (but not the entry named by the DN).
1109 For example, if the directory contained entries named:
1112 > 1: cn=Manager,o=suffix
1113 > 2: ou=people,o=suffix
1114 > 3: uid=kdz,ou=people,o=suffix
1115 > 4: cn=addresses,uid=kdz,ou=people,o=suffix
1116 > 5: uid=hyc,ou=people,o=suffix
1119 . {{EX:dn.base="ou=people,o=suffix"}} match 2;
1120 . {{EX:dn.one="ou=people,o=suffix"}} match 3, and 5;
1121 . {{EX:dn.subtree="ou=people,o=suffix"}} match 2, 3, 4, and 5; and
1122 . {{EX:dn.children="ou=people,o=suffix"}} match 3, 4, and 5.
1125 Entries may also be selected using a filter:
1127 > to filter=<ldap filter>
1129 where <ldap filter> is a string representation of an LDAP
1130 search filter, as described in {{REF:RFC4515}}. For example:
1132 > to filter=(objectClass=person)
1134 Note that entries may be selected by both DN and filter by
1135 including both qualifiers in the <what> clause.
1137 > to dn.one="ou=people,o=suffix" filter=(objectClass=person)
1139 Attributes within an entry are selected by including a comma-separated
1140 list of attribute names in the <what> selector:
1142 > attrs=<attribute list>
1144 A specific value of an attribute is selected by using a single
1145 attribute name and also using a value selector:
1147 > attrs=<attribute> val[.<style>]=<regex>
1149 There are two special {{pseudo}} attributes {{EX:entry}} and
1150 {{EX:children}}. To read (and hence return) a target entry, the
1151 subject must have {{EX:read}} access to the target's {{entry}}
1152 attribute. To add or delete an entry, the subject must have
1153 {{EX:write}} access to the entry's {{EX:entry}} attribute AND must
1154 have {{EX:write}} access to the entry's parent's {{EX:children}}
1155 attribute. To rename an entry, the subject must have {{EX:write}}
1156 access to entry's {{EX:entry}} attribute AND have {{EX:write}}
1157 access to both the old parent's and new parent's {{EX:children}}
1158 attributes. The complete examples at the end of this section should
1159 help clear things up.
1161 Lastly, there is a special entry selector {{EX:"*"}} that is used to
1162 select any entry. It is used when no other {{EX:<what>}}
1163 selector has been provided. It's equivalent to "{{EX:dn=.*}}"
1166 H3: Who to grant access to
1168 The <who> part identifies the entity or entities being granted
1169 access. Note that access is granted to "entities" not "entries."
1170 The following table summarizes entity specifiers:
1172 !block table; align=Center; coltags="EX,N"; \
1173 title="Table 5.3: Access Entity Specifiers"
1175 *|All, including anonymous and authenticated users
1176 anonymous|Anonymous (non-authenticated) users
1177 users|Authenticated users
1178 self|User associated with target entry
1179 dn[.<basic-style>]=<regex>|Users matching a regular expression
1180 dn.<scope-style>=<DN>|Users within scope of a DN
1183 The DN specifier behaves much like <what> clause DN specifiers.
1185 Other control factors are also supported. For example, a {{EX:<who>}}
1186 can be restricted by an entry listed in a DN-valued attribute in
1187 the entry to which the access applies:
1189 > dnattr=<dn-valued attribute name>
1191 The dnattr specification is used to give access to an entry
1192 whose DN is listed in an attribute of the entry (e.g., give
1193 access to a group entry to whoever is listed as the owner of
1196 Some factors may not be appropriate in all environments (or any).
1197 For example, the domain factor relies on IP to domain name lookups.
1198 As these can easily spoofed, the domain factor should not be avoided.
1201 H3: The access to grant
1203 The kind of <access> granted can be one of the following:
1205 !block table; colaligns="LRL"; coltags="EX,EX,N"; align=Center; \
1206 title="Table 5.4: Access Levels"
1207 Level Privileges Description
1209 disclose =d needed for information disclosure on error
1210 auth =dx needed to authenticate (bind)
1211 compare =cdx needed to compare
1212 search =scdx needed to apply search filters
1213 read =rscdx needed to read search results
1214 write =wrscdx needed to modify/rename
1215 manage =mwrscdx needed to manage
1218 Each level implies all lower levels of access. So, for example,
1219 granting someone {{EX:write}} access to an entry also grants them
1220 {{EX:read}}, {{EX:search}}, {{EX:compare}}, {{EX:auth}} and
1221 {{EX:disclose}} access. However, one may use the privileges specifier
1222 to grant specific permissions.
1225 H3: Access Control Evaluation
1227 When evaluating whether some requester should be given access to
1228 an entry and/or attribute, slapd compares the entry and/or attribute
1229 to the {{EX:<what>}} selectors given in the configuration. For
1230 each entry, access controls provided in the database which holds
1231 the entry (or the first database if not held in any database) apply
1232 first, followed by the global access directives (which are held in
1233 the {{EX:frontend}} database definition). Within this priority,
1234 access directives are examined in the order in which they appear
1235 in the configuration attribute. Slapd stops with the first
1236 {{EX:<what>}} selector that matches the entry and/or attribute. The
1237 corresponding access directive is the one slapd will use to evaluate
1240 Next, slapd compares the entity requesting access to the {{EX:<who>}}
1241 selectors within the access directive selected above in the order
1242 in which they appear. It stops with the first {{EX:<who>}} selector
1243 that matches the requester. This determines the access the entity
1244 requesting access has to the entry and/or attribute.
1246 Finally, slapd compares the access granted in the selected
1247 {{EX:<access>}} clause to the access requested by the client. If
1248 it allows greater or equal access, access is granted. Otherwise,
1251 The order of evaluation of access directives makes their placement
1252 in the configuration file important. If one access directive is
1253 more specific than another in terms of the entries it selects, it
1254 should appear first in the configuration. Similarly, if one {{EX:<who>}}
1255 selector is more specific than another it should come first in the
1256 access directive. The access control examples given below should
1257 help make this clear.
1261 H3: Access Control Examples
1263 The access control facility described above is quite powerful. This
1264 section shows some examples of its use for descriptive purposes.
1268 > olcAccess: to * by * read
1270 This access directive grants read access to everyone.
1277 This directive allows the user to modify their entry, allows anonymous
1278 to authenticate against these entries, and allows all others to
1279 read these entries. Note that only the first {{EX:by <who>}} clause
1280 which matches applies. Hence, the anonymous users are granted
1281 {{EX:auth}}, not {{EX:read}}. The last clause could just as well
1282 have been "{{EX:by users read}}".
1284 It is often desirable to restrict operations based upon the level
1285 of protection in place. The following shows how security strength
1286 factors (SSF) can be used.
1289 > by ssf=128 self write
1290 > by ssf=64 anonymous auth
1291 > by ssf=64 users read
1293 This directive allows users to modify their own entries if security
1294 protections of strength 128 or better have been established,
1295 allows authentication access to anonymous users, and read access
1296 when strength 64 or better security protections have been established. If
1297 the client has not establish sufficient security protections, the
1298 implicit {{EX:by * none}} clause would be applied.
1300 The following example shows the use of style specifiers to select
1301 the entries by DN in two access directives where ordering is
1304 > olcAccess: to dn.children="dc=example,dc=com"
1306 > olcAccess: to dn.children="dc=com"
1309 Read access is granted to entries under the {{EX:dc=com}} subtree,
1310 except for those entries under the {{EX:dc=example,dc=com}} subtree,
1311 to which search access is granted. No access is granted to
1312 {{EX:dc=com}} as neither access directive matches this DN. If the
1313 order of these access directives was reversed, the trailing directive
1314 would never be reached, since all entries under {{EX:dc=example,dc=com}}
1315 are also under {{EX:dc=com}} entries.
1317 Also note that if no {{EX:olcAccess: to}} directive matches or no {{EX:by
1318 <who>}} clause, {{B:access is denied}}. That is, every {{EX:olcAccess:
1319 to}} directive ends with an implicit {{EX:by * none}} clause and
1320 every access list ends with an implicit {{EX:olcAccess: to * by * none}}
1323 The next example again shows the importance of ordering, both of
1324 the access directives and the {{EX:by <who>}} clauses. It also
1325 shows the use of an attribute selector to grant access to a specific
1326 attribute and various {{EX:<who>}} selectors.
1328 > olcAccess: to dn.subtree="dc=example,dc=com" attrs=homePhone
1330 > by dn.children=dc=example,dc=com" search
1331 > by peername.regex=IP:10\..+ read
1332 > olcAccess: to dn.subtree="dc=example,dc=com"
1334 > by dn.children="dc=example,dc=com" search
1337 This example applies to entries in the "{{EX:dc=example,dc=com}}"
1338 subtree. To all attributes except {{EX:homePhone}}, an entry can
1339 write to itself, entries under {{EX:example.com}} entries can search
1340 by them, anybody else has no access (implicit {{EX:by * none}})
1341 excepting for authentication/authorization (which is always done
1342 anonymously). The {{EX:homePhone}} attribute is writable by the
1343 entry, searchable by entries under {{EX:example.com}}, readable by
1344 clients connecting from network 10, and otherwise not readable
1345 (implicit {{EX:by * none}}). All other access is denied by the
1346 implicit {{EX:access to * by * none}}.
1348 Sometimes it is useful to permit a particular DN to add or
1349 remove itself from an attribute. For example, if you would like to
1350 create a group and allow people to add and remove only
1351 their own DN from the member attribute, you could accomplish
1352 it with an access directive like this:
1354 > olcAccess: to attrs=member,entry
1355 > by dnattr=member selfwrite
1357 The dnattr {{EX:<who>}} selector says that the access applies to
1358 entries listed in the {{EX:member}} attribute. The {{EX:selfwrite}} access
1359 selector says that such members can only add or delete their
1360 own DN from the attribute, not other values. The addition of
1361 the entry attribute is required because access to the entry is
1362 required to access any of the entry's attributes.
1366 H3: Access Control Ordering
1368 Since the ordering of {{EX:olcAccess}} directives is essential to their
1369 proper evaluation, but LDAP attributes normally do not preserve the
1370 ordering of their values, OpenLDAP uses a custom schema extension to
1371 maintain a fixed ordering of these values. This ordering is maintained
1372 by prepending a {{EX:"{X}"}} numeric index to each value, similarly to
1373 the approach used for ordering the configuration entries. These index
1374 tags are maintained automatically by slapd and do not need to be specified
1375 when originally defining the values. For example, when you create the
1378 > olcAccess: to attrs=member,entry
1379 > by dnattr=member selfwrite
1380 > olcAccess: to dn.children="dc=example,dc=com"
1382 > olcAccess: to dn.children="dc=com"
1385 when you read them back using slapcat or ldapsearch they will contain
1387 > olcAccess: {0}to attrs=member,entry
1388 > by dnattr=member selfwrite
1389 > olcAccess: {1}to dn.children="dc=example,dc=com"
1391 > olcAccess: {2}to dn.children="dc=com"
1394 The numeric index may be used to specify a particular value to change
1395 when using ldapmodify to edit the access rules. This index can be used
1396 instead of (or in addition to) the actual access value. Using this
1397 numeric index is very helpful when multiple access rules are being managed.
1399 For example, if we needed to change the second rule above to grant
1400 write access instead of search, we could try this LDIF:
1402 > changetype: modify
1404 > olcAccess: to dn.children="dc=example,dc=com" by * search
1407 > olcAccess: to dn.children="dc=example,dc=com" by * write
1410 But this example {{B:will not}} guarantee that the existing values remain in
1411 their original order, so it will most likely yield a broken security
1412 configuration. Instead, the numeric index should be used:
1414 > changetype: modify
1419 > olcAccess: {1}to dn.children="dc=example,dc=com" by * write
1422 This example deletes whatever rule is in value #1 of the {{EX:olcAccess}}
1423 attribute (regardless of its value) and adds a new value that is
1424 explicitly inserted as value #1. The result will be
1426 > olcAccess: {0}to attrs=member,entry
1427 > by dnattr=member selfwrite
1428 > olcAccess: {1}to dn.children="dc=example,dc=com"
1430 > olcAccess: {2}to dn.children="dc=com"
1433 which is exactly what was intended.
1436 For more details on how to use the {{EX:access}} directive,
1437 consult the {{Advanced Access Control}} chapter.
1441 H2: Configuration Example
1443 The following is an example configuration, interspersed
1444 with explanatory text. It defines two databases to handle
1445 different parts of the {{TERM:X.500}} tree; both are {{TERM:BDB}}
1446 database instances. The line numbers shown are provided for
1447 reference only and are not included in the actual file. First, the
1448 global configuration section:
1450 E: 1. # example config file - global configuration entry
1452 E: 3. objectClass: olcGlobal
1454 E: 5. olcReferral: ldap://root.openldap.org
1457 Line 1 is a comment. Lines 2-4 identify this as the global
1458 configuration entry.
1459 The {{EX:olcReferral:}} directive on line 5
1460 means that queries not local to one of the databases defined
1461 below will be referred to the LDAP server running on the
1462 standard port (389) at the host {{EX:root.openldap.org}}.
1463 Line 6 is a blank line, indicating the end of this entry.
1465 E: 7. # internal schema
1466 E: 8. dn: cn=schema,cn=config
1467 E: 9. objectClass: olcSchemaConfig
1471 Line 7 is a comment. Lines 8-10 identify this as the root of
1472 the schema subtree. The actual schema definitions in this entry
1473 are hardcoded into slapd so no additional attributes are specified here.
1474 Line 11 is a blank line, indicating the end of this entry.
1476 E: 12. # include the core schema
1477 E: 13. include: file:///usr/local/etc/openldap/schema/core.ldif
1480 Line 12 is a comment. Line 13 is an LDIF include directive which
1481 accesses the {{core}} schema definitions in LDIF format. Line 14
1484 Next comes the database definitions. The first database is the
1485 special {{EX:frontend}} database whose settings are applied globally
1486 to all the other databases.
1488 E: 15. # global database parameters
1489 E: 16. dn: olcDatabase=frontend,cn=config
1490 E: 17. objectClass: olcDatabaseConfig
1491 E: 18. olcDatabase: frontend
1492 E: 19. olcAccess: to * by * read
1495 Line 15 is a comment. Lines 16-18 identify this entry as the global
1496 database entry. Line 19 is a global access control. It applies to all
1497 entries (after any applicable database-specific access controls).
1499 The next entry defines a BDB backend that will handle queries for things
1500 in the "dc=example,dc=com" portion of the tree. Indices are to be maintained
1501 for several attributes, and the {{EX:userPassword}} attribute is to be
1502 protected from unauthorized access.
1504 E: 21. # BDB definition for example.com
1505 E: 22. dn: olcDatabase=bdb,cn=config
1506 E: 23. objectClass: olcDatabaseConfig
1507 E: 24. objectClass: olcBdbConfig
1508 E: 25. olcDatabase: bdb
1509 E: 26. olcSuffix: "dc=example,dc=com"
1510 E: 27. olcDbDirectory: /usr/local/var/openldap-data
1511 E: 28. olcRootDN: "cn=Manager,dc=example,dc=com"
1512 E: 29. olcRootPW: secret
1513 E: 30. olcDbIndex: uid pres,eq
1514 E: 31. olcDbIndex: cn,sn,uid pres,eq,approx,sub
1515 E: 32. olcDbIndex: objectClass eq
1516 E: 33. olcAccess: to attrs=userPassword
1517 E: 34. by self write
1518 E: 35. by anonymous auth
1519 E: 36. by dn.base="cn=Admin,dc=example,dc=com" write
1521 E: 38. olcAccess: to *
1522 E: 39. by self write
1523 E: 40. by dn.base="cn=Admin,dc=example,dc=com" write
1527 Line 21 is a comment. Lines 22-25 identify this entry as a BDB database
1528 configuration entry. Line 26 specifies the DN suffix
1529 for queries to pass to this database. Line 27 specifies the directory
1530 in which the database files will live.
1532 Lines 28 and 29 identify the database {{super-user}} entry and associated
1533 password. This entry is not subject to access control or size or
1534 time limit restrictions.
1536 Lines 30 through 32 indicate the indices to maintain for various
1539 Lines 33 through 41 specify access control for entries in this
1540 database. As this is the first database, the controls also apply
1541 to entries not held in any database (such as the Root DSE). For
1542 all applicable entries, the {{EX:userPassword}} attribute is writable
1543 by the entry itself and by the "admin" entry. It may be used for
1544 authentication/authorization purposes, but is otherwise not readable.
1545 All other attributes are writable by the entry and the "admin"
1546 entry, but may be read by all users (authenticated or not).
1548 Line 42 is a blank line, indicating the end of this entry.
1550 The next section of the example configuration file defines another
1551 BDB database. This one handles queries involving the
1552 {{EX:dc=example,dc=net}} subtree but is managed by the same entity
1553 as the first database. Note that without line 51, the read access
1554 would be allowed due to the global access rule at line 19.
1556 E: 42. # BDB definition for example.net
1557 E: 43. dn: olcDatabase=bdb,cn=config
1558 E: 44. objectClass: olcDatabaseConfig
1559 E: 45. objectClass: olcBdbConfig
1560 E: 46. olcDatabase: bdb
1561 E: 47. olcSuffix: "dc=example,dc=net"
1562 E: 48. olcDbDirectory: /usr/local/var/openldap-data-net
1563 E: 49. olcRootDN: "cn=Manager,dc=example,dc=com"
1564 E: 50. olcDbIndex: objectClass eq
1565 E: 51. olcAccess: to * by users read