2 # Copyright 2005, 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 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.
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.
29 H2: Configuration Layout
31 The slapd configuration is stored as a special LDAP directory with
32 a predefined schema and DIT. There are specific objectClasses used to
33 carry global configuration options, schema definitions, backend and
34 database definitions, and assorted other items. A sample config tree
35 is shown in Figure 5.1.
37 !import "config_dit.gif"; align="center"; title="Sample configuration tree"
38 FT[align="Center"] Figure 5.1: Sample configuration tree.
40 Other objects may be part of the configuration but were omitted from
41 the illustration for clarity.
43 The {{slapd.d}} configuration tree has a very specific structure. The
44 root of the tree is named {{EX:cn=config}} and contains global configuration
45 settings. Additional settings are contained in separate child entries:
47 .. Usually these are just pathnames left over from a converted
48 {{EX:slapd.conf}} file.
49 .. Otherwise use of Include files is deprecated.
50 * Dynamically loaded modules
51 .. These may only be used if the {{EX:--enable-modules}} option was
52 used to configure the software.
54 .. The {{EX:cn=schema,cn=config}} entry contains the system schema (all
55 the schema that is hard-coded in slapd).
56 .. Child entries of {{EX:cn=schema,cn=config}} contain user schema as
57 loaded from config files or added at runtime.
58 * Backend-specific configuration
59 * Database-specific configuration
60 .. Overlays are defined in children of the Database entry.
61 .. Databases and Overlays may also have other miscellaneous children.
63 The usual rules for LDIF files apply to the configuration information:
64 Comment lines beginning with a '{{EX:#}}' character
65 are ignored. If a line begins with white space, it is considered a
66 continuation of the previous line (even if the previous line is a
67 comment). Entries are separated by blank lines.
69 The general layout of the config LDIF is as follows:
71 > # global configuration settings
73 > objectClass: olcGlobal
75 > <global config settings>
77 > # schema definitions
78 > dn: cn=schema,cn=config
79 > objectClass: olcSchemaConfig
83 > dn: cn={X}core,cn=schema,cn=config
84 > objectClass: olcSchemaConfig
88 > # additional user-specified schema
91 > # backend definitions
92 > dn: olcBackend=<typeA>,cn=config
93 > objectClass: olcBackendConfig
95 > <backend-specific settings>
97 > # database definitions
98 > dn: olcDatabase={X}<typeA>,cn=config
99 > objectClass: olcDatabaseConfig
100 > olcDatabase: {X}<typeA>
101 > <database-specific settings>
103 > # subsequent definitions and settings
106 Some of the entries listed above have a numeric index {{EX:"{X}"}} in
107 their names. While most configuration settings have an inherent ordering
108 dependency (i.e., one setting must take effect before a subsequent one
109 may be set), LDAP databases are inherently unordered. The numeric index
110 is used to enforce a consistent ordering in the configuration database,
111 so that all ordering dependencies are preserved. In most cases the index
112 does not have to be provided; it will be automatically generated based
113 on the order in which entries are created.
115 Configuration directives are specified as values of individual
117 Most of the attributes and objectClasses used in the slapd
118 configuration have a prefix of {{EX:"olc"}} (OpenLDAP Configuration)
119 in their names. Generally there is a one-to-one correspondence
120 between the attributes and the old-style {{EX:slapd.conf}} configuration
121 keywords, using the keyword as the attribute name, with the "olc"
124 A configuration directive may take arguments. If so, the arguments are
125 separated by white space. If an argument contains white space,
126 the argument should be enclosed in double quotes {{EX:"like this"}}. If
127 an argument contains a double quote or a backslash character `{{EX:\}}',
128 the character should be preceded by a backslash character `{{EX:\}}'.
129 In the descriptions that follow, arguments that should be replaced
130 by actual text are shown in brackets {{EX:<>}}.
132 The distribution contains an example configuration file that will
133 be installed in the {{F: /usr/local/etc/openldap}} directory.
134 A number of files containing schema definitions (attribute types
135 and object classes) are also provided in the
136 {{F: /usr/local/etc/openldap/schema}} directory.
139 H2: Configuration Directives
141 This section details commonly used configuration directives. For
142 a complete list, see the {{slapd.d}}(5) manual page. This section
143 will treat the configuration directives in a top-down order, starting
144 with the global directives in the {{EX:cn=config}} entry. Each
145 directive will be described along with its default value (if any) and
146 an example of its use.
151 Directives contained in this entry generally apply to the server as a whole.
152 Most of them are system or connection oriented, not database related. This
153 entry must have the {{EX:olcGlobal}} objectClass.
156 H4: olcIdleTimeout: <integer>
158 Specify the number of seconds to wait before forcibly closing
159 an idle client connection. A value of 0, the default,
160 disables this feature.
163 H4: olcLogLevel: <level>
165 This directive specifies the level at which debugging statements
166 and operation statistics should be syslogged (currently logged to
167 the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have
168 configured OpenLDAP {{EX:--enable-debug}} (the default) for this
169 to work (except for the two statistics levels, which are always
170 enabled). Log levels may be specified as integers or by keyword.
171 Multiple log levels may be used and the levels are additive.
172 To display what levels
173 correspond to what kind of debugging, invoke slapd with {{EX:-?}}
174 or consult the table below. The possible values for <level> are:
176 !block table; colaligns="RL"; align=Center; \
177 title="Table 5.1: Debugging Levels"
178 Level Keyword Description
179 -1 Any enable all debugging
181 1 Trace trace function calls
182 2 Packets debug packet handling
183 4 Args heavy trace debugging
184 8 Conns connection management
185 16 BER print out packets sent and received
186 32 Filter search filter processing
187 64 Config configuration processing
188 128 ACL access control list processing
189 256 Stats stats log connections/operations/results
190 512 Stats2 stats log entries sent
191 1024 Shell print communication with shell backends
192 2048 Parse print entry parsing debugging
193 4096 Cache database cache processing
194 8192 Index database indexing
195 16384 Sync syncrepl consumer processing
202 This will cause lots and lots of debugging information to be
205 E: olcLogLevel: Conns Filter
207 Just log the connection and search filter processing.
211 E: olcLogLevel: Stats
214 H4: olcReferral <URI>
216 This directive specifies the referral to pass back when slapd
217 cannot find a local database to handle a request.
221 > olcReferral: ldap://root.openldap.org
223 This will refer non-local queries to the global root LDAP server
224 at the OpenLDAP Project. Smart LDAP clients can re-ask their
225 query at that server, but note that most of these clients are
226 only going to know how to handle simple LDAP URLs that
227 contain a host part and optionally a distinguished name part.
233 >objectClass: olcGlobal
237 >olcReferral: ldap://root.openldap.org
243 An include entry holds the pathname of one include file. Include files
244 are part of the old style slapd.conf configuration system and must be in
245 slapd.conf format. Include files were commonly used to load schema
246 specifications. While they are still supported, their use is deprecated.
247 Include entries must have the {{EX:olcIncludeFile}} objectClass.
250 H4: olcInclude: <filename>
252 This directive specifies that slapd should read additional
253 configuration information from the given file.
255 Note: You should be careful when using this directive - there is
256 no small limit on the number of nested include directives, and no
257 loop detection is done.
262 >dn: cn=include{0},cn=config
263 >objectClass: olcIncludeFile
265 >olcInclude: ./schema/core.schema
267 >dn: cn=include{1},cn=config
268 >objectClass: olcIncludeFile
270 >olcInclude: ./schema/cosine.schema
275 The cn=schema entry holds all of the schema definitions that are hard-coded
276 in slapd. As such, the values in this entry are generated by slapd so no
277 schema values need to be provided in the config file. The entry must still
278 be defined though, to serve as a base for the user-defined schema to add
279 in underneath. Schema entries must have the {{EX:olcSchemaConfig}}
283 H4: olcAttributeTypes: <{{REF:RFC2252}} Attribute Type Description>
285 This directive defines an attribute type.
286 Please see the {{SECT:Schema Specification}} chapter
287 for information regarding how to use this directive.
290 H4: olcObjectClasses: <{{REF:RFC2252}} Object Class Description>
292 This directive defines an object class.
293 Please see the {{SECT:Schema Specification}} chapter for
294 information regarding how to use this directive.
299 >dn: cn=schema,cn=config
300 >objectClass: olcSchemaConfig
303 >dn: cn=test,cn=schema,cn=config
304 >objectClass: olcSchemaConfig
306 >olcAttributeTypes: ( 1.1.1
308 > EQUALITY integerMatch
309 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 )
310 >olcAttributeTypes: ( 1.1.2 NAME 'testTwo' EQUALITY caseIgnoreMatch
311 > SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 )
312 >olcObjectClasses: ( 1.1.3 NAME 'testObject'
313 > MAY ( testAttr $ testTwo ) AUXILIARY )
316 H3: Backend-specific Directives
318 Backend directives apply to all database instances of the
319 same type and, depending on the directive, may be overridden
320 by database directives. Backend entries must have the
321 {{EX:olcBackendConfig}} objectClass.
323 H4: olcBackend: <type>
325 This directive names a backend-specific configuration entry.
326 {{EX:<type>}} should be one of the
327 supported backend types listed in Table 5.2.
329 !block table; align=Center; coltags="EX,N"; \
330 title="Table 5.2: Database Backends"
332 bdb Berkeley DB transactional backend
333 dnssrv DNS SRV backend
334 ldap Lightweight Directory Access Protocol (Proxy) backend
335 ldbm Lightweight DBM backend
336 ldif Lightweight Data Interchange Format backend
337 meta Meta Directory backend
338 monitor Monitor backend
339 passwd Provides read-only access to {{passwd}}(5)
340 perl Perl Programmable backend
341 shell Shell (extern program) backend
342 sql SQL Programmable backend
349 There are no other directives defined for this entry, so generally
350 it will not be needed. However, specific backend types may define
351 additional attributes for their particular use.
356 > dn: olcBackend=bdb,cn=config
357 > objectClass: olcBackendConfig
361 H3: Database-specific Directives
363 Directives in this section are supported by every type of database.
364 Database entries must have the {{EX:olcDatabaseConfig}} objectClass.
366 H4: olcDatabase: [{<index>}]<type>
368 This directive names a specific database instance. The numeric {<index>} may
369 be provided to distinguish multiple databases of the same type. Usually the
370 index can be omitted, and slapd will generate it automatically.
371 {{EX:<type>}} should be one of the
372 supported backend types listed in Table 5.2 or the {{EX:frontend}} type.
374 The {{EX:frontend}} is a special database that is used to hold
375 database-level options that should be applied to all the other
376 databases. Subsequent database definitions may also override some
383 This marks the beginning of a new {{TERM:BDB}} database instance.
386 H4: olcAccess: to <what> [ by <who> <accesslevel> <control> ]+
388 This directive grants access (specified by <accesslevel>) to a
389 set of entries and/or attributes (specified by <what>) by one or
390 more requesters (specified by <who>).
391 See the {{SECT:Access Control}} section of this chapter for a
392 summary of basic usage.
395 More detailed discussion of this directive can be found in the
396 {{SECT:Advanced Access Control}} chapter.
399 Note: If no {{EX:olcAccess}} directives are specified, the default
400 access control policy, {{EX:to * by * read}}, allows all
401 users (both authenticated and anonymous) read access.
403 Note: Access controls defined in the frontend are appended to all
404 other databases' controls.
407 H4: olcReadonly { TRUE | FALSE }
409 This directive puts the database into "read-only" mode. Any
410 attempts to modify the database will return an "unwilling to
420 > olcReplica: uri=ldap[s]://<hostname>[:<port>] | host=<hostname>[:<port>]
421 > [bindmethod={simple|sasl}]
424 > [authcid=<identity>]
425 > [authzid=<identity>]
426 > [credentials=<password>]
428 This directive specifies a replication site for this database for
430 {{EX:uri=}} parameter specifies a scheme, a host and optionally a port where
431 the slave slapd instance can be found. Either a domain name
432 or IP address may be used for <hostname>. If <port> is not
433 given, the standard LDAP port number (389 or 636) is used.
435 {{EX:host}} is deprecated in favor of the {{EX:uri}} parameter.
437 {{EX:uri}} allows the replica LDAP server to be specified as an LDAP
438 URI such as {{EX:ldap://slave.example.com:389}} or
439 {{EX:ldaps://slave.example.com:636}}.
441 The {{EX:binddn=}} parameter gives the DN to bind as for updates
442 to the slave slapd. It should be a DN which has read/write access
443 to the slave slapd's database. It must also match the {{EX:updatedn}}
444 directive in the slave slapd's config file. Generally, this DN
445 {{should not}} be the same as the {{EX:rootdn}} of the master
446 database. Since DNs are likely to contain embedded spaces, the
447 entire {{EX:"binddn=<DN>"}} string should be enclosed in double
450 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
451 depending on whether simple password-based authentication
452 or {{TERM:SASL}} authentication is to be used when connecting
455 Simple authentication should not be used unless adequate data
456 integrity and confidentiality protections are in place (e.g. TLS
457 or IPSEC). Simple authentication requires specification of
458 {{EX:binddn}} and {{EX:credentials}} parameters.
460 SASL authentication is generally recommended. SASL authentication
461 requires specification of a mechanism using the {{EX:saslmech}} parameter.
462 Depending on the mechanism, an authentication identity and/or
463 credentials can be specified using {{EX:authcid}} and {{EX:credentials}}
464 respectively. The {{EX:authzid}} parameter may be used to specify
465 an authorization identity.
467 See the chapter entitled {{SECT:Replication with slurpd}} for more
468 information on how to use this directive.
471 H4: olcReplogfile: <filename>
473 This directive specifies the name of the replication log file to
474 which slapd will log changes. The replication log is typically
475 written by slapd and read by slurpd. Normally, this directive is
476 only used if slurpd is being used to replicate the database.
477 However, you can also use it to generate a transaction log, if
478 slurpd is not running. In this case, you will need to periodically
479 truncate the file, since it will grow indefinitely otherwise.
481 See the chapter entitled {{SECT:Replication with slurpd}} for more
482 information on how to use this directive.
487 This directive specifies the DN that is not subject to
488 access control or administrative limit restrictions for
489 operations on this database. The DN need not refer to
490 an entry in this database or even in the directory. The
491 DN may refer to a SASL identity.
495 > olcRootDN: "cn=Manager,dc=example,dc=com"
499 > olcRootDN: "uid=root,cn=example.com,cn=digest-md5,cn=auth"
501 See the {{SECT:SASL Authentication}} section for information on
502 SASL authentication identities.
505 H4: olcRootPW: <password>
507 This directive can be used to specify a password for the DN for
508 the rootdn (when the rootdn is set to a DN within the database).
514 It is also permissible to provide a hash of the password in RFC 2307
515 form. {{slappasswd}}(8) may be used to generate the password hash.
519 > olcRootPW: {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN
521 The hash was generated using the command {{EX:slappasswd -s secret}}.
524 H4: olcSizeLimit: <integer>
526 This directive specifies the maximum number of entries to return
527 from a search operation.
535 H4: olcSuffix: <dn suffix>
537 This directive specifies the DN suffix of queries that will be
538 passed to this backend database. Multiple suffix lines can be
539 given, and usually at least one is required for each database
540 definition. (Some backend types, such as {{EX:frontend}} and
541 {{EX:monitor}} use a hard-coded suffix which may not be overridden
542 in the configuration.)
546 > olcSuffix: "dc=example,dc=com"
548 Queries with a DN ending in "dc=example,dc=com"
549 will be passed to this backend.
551 Note: When the backend to pass a query to is selected, slapd
552 looks at the suffix value(s) in each database definition in the
553 order in which they were configured. Thus, if one database suffix is a
554 prefix of another, it must appear after it in the configuration.
559 > olcSyncrepl: rid=<replica ID>
560 > provider=ldap[s]://<hostname>[:port]
561 > [type=refreshOnly|refreshAndPersist]
562 > [interval=dd:hh:mm:ss]
563 > [retry=[<retry interval> <# of retries>]+]
564 > [searchbase=<base DN>]
565 > [filter=<filter str>]
566 > [scope=sub|one|base]
567 > [attrs=<attr list>]
569 > [sizelimit=<limit>]
570 > [timelimit=<limit>]
571 > [schemachecking=on|off]
572 > [bindmethod=simple|sasl]
575 > [authcid=<identity>]
576 > [authzid=<identity>]
577 > [credentials=<passwd>]
579 > [secprops=<properties>]
582 This directive specifies the current database as a replica of the
583 master content by establishing the current {{slapd}}(8) as a
584 replication consumer site running a syncrepl replication engine.
585 The master database is located at the replication provider site
586 specified by the {{EX:provider}} parameter. The replica database is
587 kept up-to-date with the master content using the LDAP Content
588 Synchronization protocol. See {{EX:draft-zeilenga-ldup-sync-xx.txt}}
589 ({{a work in progress}}) for more information on the protocol.
591 The {{EX:rid}} parameter is used for identification of the current
592 {{EX:syncrepl}} directive within the replication consumer server,
593 where {{EX:<replica ID>}} uniquely identifies the syncrepl specification
594 described by the current {{EX:syncrepl}} directive. {{EX:<replica ID>}}
595 is non-negative and is no more than three decimal digits in length.
597 The {{EX:provider}} parameter specifies the replication provider site
598 containing the master content as an LDAP URI. The {{EX:provider}}
599 parameter specifies a scheme, a host and optionally a port where the
600 provider slapd instance can be found. Either a domain name or IP
601 address may be used for <hostname>. Examples are
602 {{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}.
603 If <port> is not given, the standard LDAP port number (389 or 636) is used.
604 Note that the syncrepl uses a consumer-initiated protocol, and hence its
605 specification is located at the consumer site, whereas the {{EX:replica}}
606 specification is located at the provider site. {{EX:syncrepl}} and
607 {{EX:replica}} directives define two independent replication
608 mechanisms. They do not represent the replication peers of each other.
610 The content of the syncrepl replica is defined using a search
611 specification as its result set. The consumer slapd will
612 send search requests to the provider slapd according to the search
613 specification. The search specification includes {{EX:searchbase}},
614 {{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:attrsonly}},
615 {{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal
616 search specification. The syncrepl search specification has
617 the same value syntax and the same default values as in the
618 {{ldapsearch}}(1) client search tool.
620 The LDAP Content Synchronization protocol has two operation
621 types: {{EX:refreshOnly}} and {{EX:refreshAndPersist}}.
622 The operation type is specified by the {{EX:type}} parameter.
623 In the {{EX:refreshOnly}} operation, the next synchronization search operation
624 is periodically rescheduled at an interval time after each
625 synchronization operation finishes. The interval is specified
626 by the {{EX:interval}} parameter. It is set to one day by default.
627 In the {{EX:refreshAndPersist}} operation, a synchronization search
628 remains persistent in the provider slapd. Further updates to the
629 master replica will generate {{EX:searchResultEntry}} to the consumer slapd
630 as the search responses to the persistent synchronization search.
632 If an error occurs during replication, the consumer will attempt to reconnect
633 according to the retry parameter which is a list of the <retry interval>
634 and <# of retries> pairs. For example, retry="60 10 300 3" lets the consumer
635 retry every 60 seconds for the first 10 times and then retry every 300 seconds
636 for the next three times before stop retrying. + in <# of retries> means
637 indefinite number of retries until success.
639 The schema checking can be enforced at the LDAP Sync consumer site
640 by turning on the {{EX:schemachecking}} parameter.
641 If it is turned on, every replicated entry will be checked for its
642 schema as the entry is stored into the replica content.
643 Every entry in the replica should contain those attributes
644 required by the schema definition.
645 If it is turned off, entries will be stored without checking
646 schema conformance. The default is off.
648 The {{EX:binddn}} parameter gives the DN to bind as for the
649 syncrepl searches to the provider slapd. It should be a DN
650 which has read access to the replication content in the
653 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
654 depending on whether simple password-based authentication or
655 {{TERM:SASL}} authentication is to be used when connecting
656 to the provider slapd.
658 Simple authentication should not be used unless adequate data
659 integrity and confidentiality protections are in place (e.g. TLS
660 or IPSEC). Simple authentication requires specification of {{EX:binddn}}
661 and {{EX:credentials}} parameters.
663 SASL authentication is generally recommended. SASL authentication
664 requires specification of a mechanism using the {{EX:saslmech}} parameter.
665 Depending on the mechanism, an authentication identity and/or
666 credentials can be specified using {{EX:authcid}} and {{EX:credentials}},
667 respectively. The {{EX:authzid}} parameter may be used to specify
668 an authorization identity.
670 The {{EX:realm}} parameter specifies a realm which a certain
671 mechanisms authenticate the identity within. The {{EX:secprops}}
672 parameter specifies Cyrus SASL security properties.
674 The syncrepl replication mechanism is supported by the
675 three native backends: back-bdb, back-hdb, and back-ldbm.
677 See the {{SECT:LDAP Sync Replication}} chapter of the admin guide
678 for more information on how to use this directive.
681 H4: olcTimeLimit: <integer>
683 This directive specifies the maximum number of seconds (in real
684 time) slapd will spend answering a search request. If a
685 request is not finished in this time, a result indicating an
686 exceeded timelimit will be returned.
693 H4: olcUpdateDN: <DN>
695 This directive is only applicable in a slave slapd. It specifies
696 the DN allowed to make changes to the replica. This may be the DN
697 {{slurpd}}(8) binds as when making changes to the replica or the DN
698 associated with a SASL identity.
702 > olcUpdateDN: "cn=Update Daemon,dc=example,dc=com"
706 > olcUpdateDN: "uid=slurpd,cn=example.com,cn=digest-md5,cn=auth"
708 See the {{SECT:Replication with slurpd}} chapter for more information
709 on how to use this directive.
711 H4: olcUpdateref: <URL>
713 This directive is only applicable in a slave slapd. It
714 specifies the URL to return to clients which submit update
715 requests upon the replica.
716 If specified multiple times, each {{TERM:URL}} is provided.
720 > olcUpdateref: ldap://master.example.net
725 >dn: olcDatabase=frontend,cn=config
726 >objectClass: olcDatabaseConfig
727 >olcDatabase: frontend
730 H3: BDB Database Directives
732 Directives in this category only apply to a {{TERM:BDB}} database.
733 They are used in an olcDatabase entry in addition to the generic
734 database directives defined above. For a complete reference
735 of BDB configuration directives, see {{slapd-bdb}}(5). BDB database
736 entries must have the {{EX:olcBdbConfig}} objectClass.
739 H4: olcDbDirectory: <directory>
741 This directive specifies the directory where the BDB files
742 containing the database and associated indices live.
746 > olcDbDirectory: /usr/local/var/openldap-data
751 >dn: olcDatabase=bdb,cn=config
752 >objectClass: olcDatabaseConfig
753 >objectClass: olcBdbConfig
755 >olcSuffix: "dc=example,dc=com"
756 >olcDbDirectory: /usr/local/var/openldap-data
758 H3: LDBM Database Directives
760 Directives in this category only apply to a {{TERM:LDBM}} database.
761 That is, they must follow a "database ldbm" line and come before
762 any subsequent "backend" or "database" line. For a complete reference
763 of LDBM configuration directives, see {{slapd-ldbm}}(5).
765 H4: cachesize <integer>
767 This directive specifies the size in entries of the in-memory
768 cache maintained by the LDBM backend database instance.
775 H4: dbcachesize <integer>
777 This directive specifies the size in bytes of the in-memory cache
778 associated with each open index file. If not supported by the
779 underlying database method, this directive is ignored without
780 comment. Increasing this number uses more memory but can
781 cause a dramatic performance increase, especially during
782 modifies or when building indices.
791 This option, if present, disables database locking.
792 Enabling this option may improve performance at the expense
798 This option causes on-disk database contents to not be immediately
799 synchronized with in memory changes upon change. Enabling this option
800 may improve performance at the expense of data integrity.
803 H4: directory <directory>
805 This directive specifies the directory where the LDBM files
806 containing the database and associated indices live.
810 > directory /usr/local/var/openldap-data
813 H4: index {<attrlist> | default} [pres,eq,approx,sub,none]
815 This directive specifies the indices to maintain for the given
816 attribute. If only an {{EX:<attrlist>}} is given, the default
817 indices are maintained.
821 > index default pres,eq
823 > index cn,sn pres,eq,sub
824 > index objectClass eq
826 The first line sets the default set of indices to maintain to
827 present and equality. The second line causes the default (pres,eq)
828 set of indices to be maintained for the {{EX:uid}} attribute type.
829 The third line causes present, equality, and substring indices to
830 be maintained for {{EX:cn}} and {{EX:sn}} attribute types. The
831 fourth line causes an equality index for the {{EX:objectClass}}
834 By default, no indices are maintained. It is generally advised
835 that minimally an equality index upon objectClass be maintained.
837 > index objectClass eq
843 This directive specifies the file protection mode that newly
844 created database index files should have.
853 Access to slapd entries and attributes is controlled by the
854 access configuration file directive. The general form of an
857 > <access directive> ::= access to <what>
858 > [by <who> <access> <control>]+
860 > [dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
861 > [filter=<ldapfilter>] [attrs=<attrlist>]
862 > <basic-style> ::= regex | exact
863 > <scope-style> ::= base | one | subtree | children
864 > <attrlist> ::= <attr> [val[.<basic-style>]=<regex>] | <attr> , <attrlist>
865 > <attr> ::= <attrname> | entry | children
866 > <who> ::= * | [anonymous | users | self
867 > | dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
868 > [dnattr=<attrname>]
869 > [group[/<objectclass>[/<attrname>][.<basic-style>]]=<regex>]
870 > [peername[.<basic-style>]=<regex>]
871 > [sockname[.<basic-style>]=<regex>]
872 > [domain[.<basic-style>]=<regex>]
873 > [sockurl[.<basic-style>]=<regex>]
876 > <access> ::= [self]{<level>|<priv>}
877 > <level> ::= none | auth | compare | search | read | write
878 > <priv> ::= {=|+|-}{w|r|s|c|x|0}+
879 > <control> ::= [stop | continue | break]
881 where the <what> part selects the entries and/or attributes to which
882 the access applies, the {{EX:<who>}} part specifies which entities
883 are granted access, and the {{EX:<access>}} part specifies the
884 access granted. Multiple {{EX:<who> <access> <control>}} triplets
885 are supported, allowing many entities to be granted different access
886 to the same set of entries and attributes. Not all of these access
887 control options are described here; for more details see the
888 {{slapd.access}}(5) man page.
891 H3: What to control access to
893 The <what> part of an access specification determines the entries
894 and attributes to which the access control applies. Entries are
895 commonly selected in two ways: by DN and by filter. The following
896 qualifiers select entries by DN:
899 > to dn[.<basic-style>]=<regex>
900 > to dn.<scope-style>=<DN>
902 The first form is used to select all entries. The second form may
903 be used to select entries by matching a regular expression against
904 the target entry's {{normalized DN}}. (The second form is not
905 discussed further in this document.) The third form is used to
906 select entries which are within the requested scope of DN. The
907 <DN> is a string representation of the Distinguished Name, as
908 described in {{REF:RFC2253}}.
910 The scope can be either {{EX:base}}, {{EX:one}}, {{EX:subtree}},
911 or {{EX:children}}. Where {{EX:base}} matches only the entry with
912 provided DN, {{EX:one}} matches the entries whose parent is the
913 provided DN, {{EX:subtree}} matches all entries in the subtree whose
914 root is the provided DN, and {{EX:children}} matches all entries
915 under the DN (but not the entry named by the DN).
917 For example, if the directory contained entries named:
920 > 1: cn=Manager,o=suffix
921 > 2: ou=people,o=suffix
922 > 3: uid=kdz,ou=people,o=suffix
923 > 4: cn=addresses,uid=kdz,ou=people,o=suffix
924 > 5: uid=hyc,ou=people,o=suffix
927 . {{EX:dn.base="ou=people,o=suffix"}} match 2;
928 . {{EX:dn.one="ou=people,o=suffix"}} match 3, and 5;
929 . {{EX:dn.subtree="ou=people,o=suffix"}} match 2, 3, 4, and 5; and
930 . {{EX:dn.children="ou=people,o=suffix"}} match 3, 4, and 5.
933 Entries may also be selected using a filter:
935 > to filter=<ldap filter>
937 where <ldap filter> is a string representation of an LDAP
938 search filter, as described in {{REF:RFC2254}}. For example:
940 > to filter=(objectClass=person)
942 Note that entries may be selected by both DN and filter by
943 including both qualifiers in the <what> clause.
945 > to dn.one="ou=people,o=suffix" filter=(objectClass=person)
947 Attributes within an entry are selected by including a comma-separated
948 list of attribute names in the <what> selector:
950 > attrs=<attribute list>
952 A specific value of an attribute is selected by using a single
953 attribute name and also using a value selector:
955 > attrs=<attribute> val[.<style>]=<regex>
957 There are two special {{pseudo}} attributes {{EX:entry}} and
958 {{EX:children}}. To read (and hence return) a target entry, the
959 subject must have {{EX:read}} access to the target's {{entry}}
960 attribute. To add or delete an entry, the subject must have
961 {{EX:write}} access to the entry's {{EX:entry}} attribute AND must
962 have {{EX:write}} access to the entry's parent's {{EX:children}}
963 attribute. To rename an entry, the subject must have {{EX:write}}
964 access to entry's {{EX:entry}} attribute AND have {{EX:write}}
965 access to both the old parent's and new parent's {{EX:children}}
966 attributes. The complete examples at the end of this section should
967 help clear things up.
969 Lastly, there is a special entry selector {{EX:"*"}} that is used to
970 select any entry. It is used when no other {{EX:<what>}}
971 selector has been provided. It's equivalent to "{{EX:dn=.*}}"
974 H3: Who to grant access to
976 The <who> part identifies the entity or entities being granted
977 access. Note that access is granted to "entities" not "entries."
978 The following table summarizes entity specifiers:
980 !block table; align=Center; coltags="EX,N"; \
981 title="Table 5.3: Access Entity Specifiers"
983 *|All, including anonymous and authenticated users
984 anonymous|Anonymous (non-authenticated) users
985 users|Authenticated users
986 self|User associated with target entry
987 dn[.<basic-style>]=<regex>|Users matching a regular expression
988 dn.<scope-style>=<DN>|Users within scope of a DN
991 The DN specifier behaves much like <what> clause DN specifiers.
993 Other control factors are also supported. For example, a {{EX:<who>}}
994 can be restricted by an entry listed in a DN-valued attribute in
995 the entry to which the access applies:
997 > dnattr=<dn-valued attribute name>
999 The dnattr specification is used to give access to an entry
1000 whose DN is listed in an attribute of the entry (e.g., give
1001 access to a group entry to whoever is listed as the owner of
1004 Some factors may not be appropriate in all environments (or any).
1005 For example, the domain factor relies on IP to domain name lookups.
1006 As these can easily spoofed, the domain factor should not be avoided.
1009 H3: The access to grant
1012 The kind of <access> granted can be one of the following:
1015 !block table; colaligns="LRL"; coltags="EX,EX,N"; align=Center; \
1016 title="Table 5.4: Access Levels"
1017 Level Privileges Description
1019 auth =x needed to bind
1020 compare =cx needed to compare
1021 search =scx needed to apply search filters
1022 read =rscx needed to read search results
1023 write =wrscx needed to modify/rename
1026 Each level implies all lower levels of access. So, for
1027 example, granting someone {{EX:write}} access to an entry also
1028 grants them {{EX:read}}, {{EX:search}}, {{EX:compare}}, and
1029 {{EX:auth}} access. However, one may use the privileges specifier
1030 to grant specific permissions.
1033 H3: Access Control Evaluation
1035 When evaluating whether some requester should be given access to
1036 an entry and/or attribute, slapd compares the entry and/or attribute
1037 to the {{EX:<what>}} selectors given in the configuration file.
1038 For each entry, access controls provided in the database which holds
1039 the entry (or the first database if not held in any database) apply
1040 first, followed by the global access directives. Within this
1041 priority, access directives are examined in the order in which they
1042 appear in the config file. Slapd stops with the first {{EX:<what>}}
1043 selector that matches the entry and/or attribute. The corresponding
1044 access directive is the one slapd will use to evaluate access.
1046 Next, slapd compares the entity requesting access to the {{EX:<who>}}
1047 selectors within the access directive selected above in the order
1048 in which they appear. It stops with the first {{EX:<who>}} selector
1049 that matches the requester. This determines the access the entity
1050 requesting access has to the entry and/or attribute.
1052 Finally, slapd compares the access granted in the selected
1053 {{EX:<access>}} clause to the access requested by the client. If
1054 it allows greater or equal access, access is granted. Otherwise,
1057 The order of evaluation of access directives makes their placement
1058 in the configuration file important. If one access directive is
1059 more specific than another in terms of the entries it selects, it
1060 should appear first in the config file. Similarly, if one {{EX:<who>}}
1061 selector is more specific than another it should come first in the
1062 access directive. The access control examples given below should
1063 help make this clear.
1067 H3: Access Control Examples
1069 The access control facility described above is quite powerful. This
1070 section shows some examples of its use for descriptive purposes.
1074 > access to * by * read
1076 This access directive grants read access to everyone.
1083 This directive allows the user to modify their entry, allows anonymous
1084 to authentication against these entries, and allows all others to
1085 read these entries. Note that only the first {{EX:by <who>}} clause
1086 which matches applies. Hence, the anonymous users are granted
1087 {{EX:auth}}, not {{EX:read}}. The last clause could just as well
1088 have been "{{EX:by users read}}".
1090 It is often desirable to restrict operations based upon the level
1091 of protection in place. The following shows how security strength
1092 factors (SSF) can be used.
1095 > by ssf=128 self write
1096 > by ssf=64 anonymous auth
1097 > by ssf=64 users read
1099 This directive allows users to modify their own entries if security
1100 protections have of strength 128 or better have been established,
1101 allows authentication access to anonymous users, and read access
1102 when 64 or better security protections have been established. If
1103 client has not establish sufficient security protections, the
1104 implicit {{EX:by * none}} clause would be applied.
1106 The following example shows the use of a style specifiers to select
1107 the entries by DN in two access directives where ordering is
1110 > access to dn.children="dc=example,dc=com"
1112 > access to dn.children="dc=com"
1115 Read access is granted to entries under the {{EX:dc=com}} subtree,
1116 except for those entries under the {{EX:dc=example,dc=com}} subtree,
1117 to which search access is granted. No access is granted to
1118 {{EX:dc=com}} as neither access directive matches this DN. If the
1119 order of these access directives was reversed, the trailing directive
1120 would never be reached, since all entries under {{EX:dc=example,dc=com}}
1121 are also under {{EX:dc=com}} entries.
1123 Also note that if no {{EX:access to}} directive matches or no {{EX:by
1124 <who>}} clause, {{B:access is denied}}. That is, every {{EX:access
1125 to}} directive ends with an implicit {{EX:by * none}} clause and
1126 every access list ends with an implicit {{EX:access to * by * none}}
1129 The next example again shows the importance of ordering, both of
1130 the access directives and the {{EX:by <who>}} clauses. It also
1131 shows the use of an attribute selector to grant access to a specific
1132 attribute and various {{EX:<who>}} selectors.
1134 > access to dn.subtree="dc=example,dc=com" attr=homePhone
1136 > by dn.children=dc=example,dc=com" search
1137 > by peername.regex=IP:10\..+ read
1138 > access to dn.subtree="dc=example,dc=com"
1140 > by dn.children="dc=example,dc=com" search
1143 This example applies to entries in the "{{EX:dc=example,dc=com}}"
1144 subtree. To all attributes except {{EX:homePhone}}, an entry can
1145 write to itself, entries under {{EX:example.com}} entries can search
1146 by them, anybody else has no access (implicit {{EX:by * none}})
1147 excepting for authentication/authorization (which is always done
1148 anonymously). The {{EX:homePhone}} attribute is writable by the
1149 entry, searchable by entries under {{EX:example.com}}, readable by
1150 clients connecting from network 10, and otherwise not readable
1151 (implicit {{EX:by * none}}). All other access is denied by the
1152 implicit {{EX:access to * by * none}}.
1154 Sometimes it is useful to permit a particular DN to add or
1155 remove itself from an attribute. For example, if you would like to
1156 create a group and allow people to add and remove only
1157 their own DN from the member attribute, you could accomplish
1158 it with an access directive like this:
1160 > access to attr=member,entry
1161 > by dnattr=member selfwrite
1163 The dnattr {{EX:<who>}} selector says that the access applies to
1164 entries listed in the {{EX:member}} attribute. The {{EX:selfwrite}} access
1165 selector says that such members can only add or delete their
1166 own DN from the attribute, not other values. The addition of
1167 the entry attribute is required because access to the entry is
1168 required to access any of the entry's attributes.
1171 For more details on how to use the {{EX:access}} directive,
1172 consult the {{Advanced Access Control}} chapter.
1176 H2: Configuration File Example
1178 The following is an example configuration file, interspersed
1179 with explanatory text. It defines two databases to handle
1180 different parts of the {{TERM:X.500}} tree; both are {{TERM:BDB}}
1181 database instances. The line numbers shown are provided for
1182 reference only and are not included in the actual file. First, the
1183 global configuration section:
1185 E: 1. # example config file - global configuration section
1186 E: 2. include /usr/local/etc/schema/core.schema
1187 E: 3. referral ldap://root.openldap.org
1188 E: 4. access to * by * read
1190 Line 1 is a comment. Line 2 includes another config file
1191 which contains {{core}} schema definitions.
1192 The {{EX:referral}} directive on line 3
1193 means that queries not local to one of the databases defined
1194 below will be referred to the LDAP server running on the
1195 standard port (389) at the host {{EX:root.openldap.org}}.
1197 Line 4 is a global access control. It applies to all
1198 entries (after any applicable database-specific access
1201 The next section of the configuration file defines a BDB
1202 backend that will handle queries for things in the
1203 "dc=example,dc=com" portion of the tree. The
1204 database is to be replicated to two slave slapds, one on
1205 truelies, the other on judgmentday. Indices are to be
1206 maintained for several attributes, and the {{EX:userPassword}}
1207 attribute is to be protected from unauthorized access.
1209 E: 5. # BDB definition for the example.com
1211 E: 7. suffix "dc=example,dc=com"
1212 E: 8. directory /usr/local/var/openldap-data
1213 E: 9. rootdn "cn=Manager,dc=example,dc=com"
1214 E: 10. rootpw secret
1215 E: 11. # replication directives
1216 E: 12. replogfile /usr/local/var/openldap/slapd.replog
1217 E: 13. replica uri=ldap://slave1.example.com:389
1218 E: 14. binddn="cn=Replicator,dc=example,dc=com"
1219 E: 15. bindmethod=simple credentials=secret
1220 E: 16. replica uri=ldaps://slave2.example.com:636
1221 E: 17. binddn="cn=Replicator,dc=example,dc=com"
1222 E: 18. bindmethod=simple credentials=secret
1223 E: 19. # indexed attribute definitions
1224 E: 20. index uid pres,eq
1225 E: 21. index cn,sn,uid pres,eq,approx,sub
1226 E: 22. index objectClass eq
1227 E: 23. # database access control definitions
1228 E: 24. access to attr=userPassword
1229 E: 25. by self write
1230 E: 26. by anonymous auth
1231 E: 27. by dn.base="cn=Admin,dc=example,dc=com" write
1234 E: 30. by self write
1235 E: 31. by dn.base="cn=Admin,dc=example,dc=com" write
1238 Line 5 is a comment. The start of the database definition is marked
1239 by the database keyword on line 6. Line 7 specifies the DN suffix
1240 for queries to pass to this database. Line 8 specifies the directory
1241 in which the database files will live.
1243 Lines 9 and 10 identify the database {{super-user}} entry and associated
1244 password. This entry is not subject to access control or size or
1245 time limit restrictions.
1247 Lines 11 through 18 are for replication. Line 12 specifies the
1248 replication log file (where changes to the database are logged -
1249 this file is written by slapd and read by slurpd). Lines 13 through
1250 15 specify the hostname and port for a replicated host, the DN to
1251 bind as when performing updates, the bind method (simple) and the
1252 credentials (password) for the binddn. Lines 16 through 18 specify
1253 a second replication site. See the {{SECT:Replication with slurpd}}
1254 chapter for more information on these directives.
1256 Lines 20 through 22 indicate the indices to maintain for various
1259 Lines 24 through 32 specify access control for entries in this
1260 database. As this is the first database, the controls also apply
1261 to entries not held in any database (such as the Root DSE). For
1262 all applicable entries, the {{EX:userPassword}} attribute is writable
1263 by the entry itself and by the "admin" entry. It may be used for
1264 authentication/authorization purposes, but is otherwise not readable.
1265 All other attributes are writable by the entry and the "admin"
1266 entry, but may be read by all users (authenticated or not).
1268 The next section of the example configuration file defines another
1269 BDB database. This one handles queries involving the
1270 {{EX:dc=example,dc=net}} subtree but is managed by the same entity
1271 as the first database. Note that without line 39, the read access
1272 would be allowed due to the global access rule at line 4.
1274 E: 33. # BDB definition for example.net
1276 E: 35. suffix "dc=example,dc=net"
1277 E: 36. directory /usr/local/var/openldap-data-net
1278 E: 37. rootdn "cn=Manager,dc=example,dc=com"
1279 E: 38. index objectClass eq
1280 E: 39. access to * by users read