2 # Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
5 H1: The slapd Configuration File
7 Once the software has been built and installed, you are ready
8 to configure {{slapd}}(8) for use at your site. The slapd
9 runtime configuration is primarily accomplished through the
10 {{slapd.conf}}(5) file, normally installed in the
11 {{EX:/usr/local/etc/openldap}} directory.
13 An alternate configuration file can be specified via a
14 command-line option to {{slapd}}(8) or {{slurpd}}(8). This chapter
15 describes the general format of the config file, followed by a
16 detailed description of commonly used config file directives.
19 H2: Configuration File Format
21 The {{slapd.conf}}(5) file consists of three types of configuration
22 information: global, backend specific, and database specific. Global
23 information is specified first, followed by information associated
24 with a particular backend type, which is then followed by information
25 associated with a particular database instance. Global directives can
26 be overridden in backend and/or database directives, and backend directives
27 can be overridden by database directives.
29 Blank lines and comment lines beginning with a '{{EX:#}}' character
30 are ignored. If a line begins with white space, it is considered a
31 continuation of the previous line (even if the previous line is a
34 The general format of slapd.conf is as follows:
36 > # global configuration directives
37 > <global config directives>
39 > # backend definition
41 > <backend-specific directives>
43 > # first database definition & config directives
45 > <database-specific directives>
47 > # second database definition & config directives
49 > <database-specific directives>
51 > # second database definition & config directives
53 > <database-specific directives>
55 > # subsequent backend & database definitions & config directives
58 A configuration directive may take arguments. If so, they are
59 separated by white space. If an argument contains white space,
60 the argument should be enclosed in double quotes {{EX:"like this"}}. If
61 an argument contains a double quote or a backslash character `{{EX:\}}',
62 the character should be preceded by a backslash character `{{EX:\}}'.
64 The distribution contains an example configuration file that will
65 be installed in the {{F: /usr/local/etc/openldap}} directory.
66 A number of files containing schema definitions (attribute types
67 and object classes) are also provided in the
68 {{F: /usr/local/etc/openldap/schema}} directory.
71 H2: Configuration File Directives
73 This section details commonly used configuration directives. For
74 a complete list, see the {{slapd.conf}}(5) manual page. This section
75 separates the configuration file directives into global,
76 backend-specific and data-specific categories, describing each
77 directive and its default value (if any), and giving an example of
84 Directives described in this section apply to all backends
85 and databases unless specifically overridden in a backend or
86 database definition. Arguments that should be replaced
87 by actual text are shown in brackets {{EX:<>}}.
90 H4: access to <what> [ by <who> <accesslevel> <control> ]+
92 This directive grants access (specified by <accesslevel>) to a
93 set of entries and/or attributes (specified by <what>) by one or
94 more requesters (specified by <who>).
95 See the {{SECT:Access Control}} section of this chapter for a
96 summary of basic usage.
99 More details discussion of this directive can be found in the
100 {{SECT:Advanced Access Control}} chapter.
103 Note: If no {{EX:access}} directives are specified, the default
104 access control policy, {{EX:access to * by * read}}, allows all
105 both authenticated and anonymous users read access.
108 H4: attributetype <{{REF:RFC2252}} Attribute Type Description>
110 This directive defines an attribute type.
111 Please see the {{SECT:Schema Specification}} chapter
112 for information regarding how to use this directive.
114 H4: idletimeout <integer>
116 Specify the number of seconds to wait before forcibly closing
117 an idle client connection. An idletimeout of 0, the default,
118 disables this feature.
121 H4: include <filename>
123 This directive specifies that slapd should read additional
124 configuration information from the given file before continuing
125 with the next line of the current file. The included file should
126 follow the normal slapd config file format. The file is commonly
127 used to include files containing schema specifications.
129 Note: You should be careful when using this directive - there is
130 no small limit on the number of nested include directives, and no
131 loop detection is done.
133 H4: loglevel <integer>
135 This directive specifies the level at which debugging statements
136 and operation statistics should be syslogged (currently logged to
137 the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have
138 configured OpenLDAP {{EX:--enable-debug}} (the default) for this
139 to work (except for the two statistics levels, which are always
140 enabled). Log levels are additive. To display what numbers
141 correspond to what kind of debugging, invoke slapd with {{EX:-?}}
142 or consult the table below. The possible values for <integer> are:
144 !block table; colaligns="RL"; align=Center; \
145 title="Table 5.1: Debugging Levels"
147 -1 enable all debugging
149 1 trace function calls
150 2 debug packet handling
151 4 heavy trace debugging
152 8 connection management
153 16 print out packets sent and received
154 32 search filter processing
155 64 configuration file processing
156 128 access control list processing
157 256 stats log connections/operations/results
158 512 stats log entries sent
159 1024 print communication with shell backends
160 2048 print entry parsing debugging
167 This will cause lots and lots of debugging information to be
175 H4: objectclass <{{REF:RFC2252}} Object Class Description>
177 This directive defines an object class.
178 Please see the {{SECT:Schema Specification}} chapter for
179 information regarding how to use this directive.
184 This directive specifies the referral to pass back when slapd
185 cannot find a local database to handle a request.
189 > referral ldap://root.openldap.org
191 This will refer non-local queries to the global root LDAP server
192 at the OpenLDAP Project. Smart LDAP clients can re-ask their
193 query at that server, but note that most of these clients are
194 only going to know how to handle simple LDAP URLs that
195 contain a host part and optionally a distinguished name part.
198 H4: sizelimit <integer>
200 This directive specifies the maximum number of entries to return
201 from a search operation.
208 H4: timelimit <integer>
210 This directive specifies the maximum number of seconds (in real
211 time) slapd will spend answering a search request. If a
212 request is not finished in this time, a result indicating an
213 exceeded timelimit will be returned.
220 H3: General Backend Directives
222 Directives in this section apply only to the backend in which
223 they are defined. They are supported by every type of backend.
224 Backend directives apply to all databases instances of the
225 same type and, depending on the directive, may be overridden
226 by database directives.
230 This directive marks the beginning of a backend declaration.
231 {{EX:<type>}} should be one of the
232 supported backend types listed in Table 5.2.
234 !block table; align=Center; coltags="EX,N"; \
235 title="Table 5.2: Database Backends"
237 bdb Berkeley DB transactional backend
238 dnssrv DNS SRV backend
239 ldap Lightweight Directory Access Protocol (Proxy) backend
240 ldbm Lightweight DBM backend
241 meta Meta Directory backend
242 monitor Monitor backend
243 passwd Provides read-only access to {{passwd}}(5)
244 perl Perl Programmable backend
245 shell Shell (extern program) backend
246 sql SQL Programmable backend
253 This marks the beginning of a new {{TERM:BDB}} backend
257 H3: General Database Directives
259 Directives in this section apply only to the database in which
260 they are defined. They are supported by every type of database.
264 This directive marks the beginning of a database instance
266 {{EX:<type>}} should be one of the
267 supported backend types listed in Table 5.2.
273 This marks the beginning of a new {{TERM:BDB}} database instance
277 H4: readonly { on | off }
279 This directive puts the database into "read-only" mode. Any
280 attempts to modify the database will return an "unwilling to
289 > replica uri=ldap[s]://<hostname>[:<port>] | host=<hostname>[:<port>]
290 > [bindmethod={simple|kerberos|sasl}]
293 > [authcid=<identity>]
294 > [authzid=<identity>]
295 > [credentials=<password>]
296 > [srvtab=<filename>]
298 This directive specifies a replication site for this database. The
299 {{EX:uri=}} parameter specifies a scheme, a host and optionally a port where
300 the slave slapd instance can be found. Either a domain name
301 or IP address may be used for <hostname>. If <port> is not
302 given, the standard LDAP port number (389 or 636) is used.
304 {{EX:host}} is deprecated in favor of the {{EX:uri}} parameter.
306 {{EX:uri}} allows the replica LDAP server to be specified as an LDAP
307 URI such as {{EX:ldap://slave.example.com:389}} or
308 {{EX:ldaps://slave.example.com:636}}.
310 The {{EX:binddn=}} parameter gives the DN to bind as for updates
311 to the slave slapd. It should be a DN which has read/write access
312 to the slave slapd's database. It must also match the {{EX:updatedn}}
313 directive in the slave slapd's config file. Generally, this DN
314 {{should not}} be the same as the {{EX:rootdn}} of the master
315 database. Since DNs are likely to contain embedded spaces, the
316 entire {{EX:"binddn=<DN>"}} string should be enclosed in double
319 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:kerberos}} or {{EX:sasl}},
320 depending on whether simple password-based authentication or Kerberos
321 authentication or {{TERM:SASL}} authentication is to be used when connecting
324 Simple authentication should not be used unless adequate integrity
325 and privacy protections are in place (e.g. TLS or IPSEC). Simple
326 authentication requires specification of {{EX:binddn}} and
327 {{EX:credentials}} parameters.
329 Kerberos authentication is deprecated in favor of SASL authentication
330 mechanisms, in particular the {{EX:KERBEROS_V4}} and {{EX:GSSAPI}}
331 mechanisms. Kerberos authentication requires {{EX:binddn}} and
332 {{EX:srvtab}} parameters.
334 SASL authentication is generally recommended. SASL authentication
335 requires specification of a mechanism using the {{EX:saslmech}} parameter.
336 Depending on the mechanism, an authentication identity and/or
337 credentials can be specified using {{EX:authcid}} and {{EX:credentials}}
338 respectively. The {{EX:authzid}} parameter may be used to specify
339 an authorization identity.
341 See the chapter entitled {{SECT:Replication with slurpd}} for more
342 information on how to use this directive.
345 H4: replogfile <filename>
347 This directive specifies the name of the replication log file to
348 which slapd will log changes. The replication log is typically
349 written by slapd and read by slurpd. Normally, this directive is
350 only used if slurpd is being used to replicate the database.
351 However, you can also use it to generate a transaction log, if
352 slurpd is not running. In this case, you will need to periodically
353 truncate the file, since it will grow indefinitely otherwise.
355 See the chapter entitled {{SECT:Replication with slurpd}} for more
356 information on how to use this directive.
361 This directive specifies the DN that is not subject to
362 access control or administrative limit restrictions for
363 operations on this database. The DN need not refer to
364 an entry in this database or even in the directory. The
365 DN may refer to a SASL identity.
369 > rootdn "cn=Manager,dc=example,dc=com"
373 > rootdn "uid=root,cn=example.com,cn=digest-md5,cn=auth"
375 See the {{SECT:SASL Authentication}} section for information on
376 SASL authentication identities.
379 H4: rootpw <password>
381 This directive can be used to specifies a password for the DN for
382 the rootdn (when the rootdn is set to a DN within the database).
388 It is also permissible to provide hash of the password in RFC 2307
389 form. {{slappasswd}}(8) may be used to generate the password hash.
393 > rootpw {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN
395 The hash was generated using the command {{EX:slappasswd -s secret}}.
398 H4: suffix <dn suffix>
400 This directive specifies the DN suffix of queries that will be
401 passed to this backend database. Multiple suffix lines can be
402 given, and at least one is required for each database
407 > suffix "dc=example,dc=com"
409 Queries with a DN ending in "dc=example,dc=com"
410 will be passed to this backend.
412 Note: When the backend to pass a query to is selected, slapd
413 looks at the suffix line(s) in each database definition in the
414 order they appear in the file. Thus, if one database suffix is a
415 prefix of another, it must appear after it in the config file.
420 > syncrepl rid=<replica ID>
421 > provider=ldap[s]://<hostname>[:port]
422 > [type=refreshOnly|refreshAndPersist]
423 > [interval=dd:hh:mm:ss]
424 > [retry=[<retry interval> <# of retries>]+]
425 > [searchbase=<base DN>]
426 > [filter=<filter str>]
427 > [scope=sub|one|base]
428 > [attrs=<attr list>]
430 > [sizelimit=<limit>]
431 > [timelimit=<limit>]
432 > [schemachecking=on|off]
434 > [bindmethod=simple|sasl]
437 > [authcid=<identity>]
438 > [authzid=<identity>]
439 > [credentials=<passwd>]
441 > [secprops=<properties>]
444 This directive specifies the current database as a replica of the
445 master content by establishing the current {{slapd}}(8) as a
446 replication consumer site running a syncrepl replication engine.
447 The master database is located at the replication provider site
448 specified by the {{EX:provider}} parameter. The replica database is
449 kept up-to-date with the master content using the LDAP Content
450 Synchronization protocol. See {{EX:draft-zeilenga-ldup-sync-xx.txt}}
451 ({{a work in progress}}) for more information on the protocol.
453 The {{EX:rid}} parameter is used for identification of the current
454 {{EX:syncrepl}} directive within the replication consumer server,
455 where {{EX:<replica ID>}} uniquely identifies the syncrepl specification
456 described by the current {{EX:syncrepl}} directive. {{EX:<replica ID>}}
457 is non-negative and is no more than three decimal digits in length.
459 The {{EX:provider}} parameter specifies the replication provider site
460 containing the master content as an LDAP URI. The {{EX:provider}}
461 parameter specifies a scheme, a host and optionally a port where the
462 provider slapd instance can be found. Either a domain name or IP
463 address may be used for <hostname>. Examples are
464 {{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}.
465 If <port> is not given, the standard LDAP port number (389 or 636) is used.
466 Note that the syncrepl uses a consumer-initiated protocol, and hence its
467 specification is located at the consumer site, whereas the {{EX:replica}}
468 specification is located at the provider site. {{EX:syncrepl}} and
469 {{EX:replica}} directives define two independent replication
470 mechanisms. They do not represent the replication peers of each other.
472 The content of the syncrepl replica is defined using a search
473 specification as its result set. The consumer slapd will
474 send search requests to the provider slapd according to the search
475 specification. The search specification includes {{EX:searchbase}},
476 {{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:attrsonly}},
477 {{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal
478 search specification. The syncrepl search specification has
479 the same value syntax and the same default values as in the
480 {{ldapsearch}}(1) client search tool.
482 The LDAP Content Synchronization protocol has two operation
483 types: {{EX:refreshOnly}} and {{EX:refreshAndPersist}}.
484 The operation type is specified by the {{EX:type}} parameter.
485 In the {{EX:refreshOnly}} operation, the next synchronization search operation
486 is periodically rescheduled at an interval time after each
487 synchronization operation finishes. The interval is specified
488 by the {{EX:interval}} parameter. It is set to one day by default.
489 In the {{EX:refreshAndPersist}} operation, a synchronization search
490 remains persistent in the provider slapd. Further updates to the
491 master replica will generate {{EX:searchResultEntry}} to the consumer slapd
492 as the search responses to the persistent synchronization search.
494 If an error occurs during replication, the consumer will attempt to reconnect
495 according to the retry parameter which is a list of the <retry interval>
496 and <# of retries> pairs. For example, retry="60 5 300 3" lets the consumer
497 retry every 60 seconds for the first 10 times and then retry every 300 seconds
498 for the next three times before stop retrying. + in <# of retries> means
499 indefinite number of retries until success.
501 The schema checking can be enforced at the LDAP Sync consumer site
502 by turning on the {{EX:schemachecking}} parameter.
503 If it is turned on, every replicated entry will be checked for its
504 schema as the entry is stored into the replica content.
505 Every entry in the replica should contain those attributes
506 required by the schema definition.
507 If it is turned off, entries will be stored without checking
508 schema conformance. The default is off.
510 The {{EX:updatedn}} parameter specifies the DN in the consumer site
511 which is allowed to make changes to the replica. This DN is used
512 locally by the syncrepl engine when updating the replica with the
513 entries received from the provider site by using the internal
514 operation mechanism. The update of the replica content is subject
515 to the access control privileges of the DN. The DN should have
516 read/write access to the replica database. Generally, this DN
517 {{should not}} be the same as {{EX:rootdn}}.
519 The {{EX:binddn}} parameter gives the DN to bind as for the
520 syncrepl searches to the provider slapd. It should be a DN
521 which has read access to the replication content in the
524 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
525 depending on whether simple password-based authentication or
526 {{TERM:SASL}} authentication is to be used when connecting
527 to the provider slapd.
529 Simple authentication should not be used unless adequate integrity
530 and privacy protections are in place (e.g. TLS or IPSEC). Simple
531 authentication requires specification of {{EX:binddn}} and
532 {{EX:credentials}} parameters.
534 SASL authentication is generally recommended. SASL authentication
535 requires specification of a mechanism using the {{EX:saslmech}} parameter.
536 Depending on the mechanism, an authentication identity and/or
537 credentials can be specified using {{EX:authcid}} and {{EX:credentials}},
538 respectively. The {{EX:authzid}} parameter may be used to specify
539 an authorization identity.
541 The {{EX:realm}} parameter specifies a realm which a certain
542 mechanisms authenticate the identity within. The {{EX:secprops}}
543 parameter specifies Cyrus SASL security properties.
545 The syncrepl replication mechanism is supported by the
546 three native backends: back-bdb, back-hdb, and back-ldbm.
548 See the {{SECT:LDAP Sync Replication}} chapter of the admin guide
549 for more information on how to use this directive.
554 This directive is only applicable in a slave slapd. It specifies
555 the DN allowed to make changes to the replica. This may be the DN
556 {{slurpd}}(8) binds as when making changes to the replica or the DN
557 associated with a SASL identity.
561 > updatedn "cn=Update Daemon,dc=example,dc=com"
565 > updatedn "uid=slurpd,cn=example.com,cn=digest-md5,cn=auth"
567 See the {{SECT:Replication with slurpd}} chapter for more information
568 on how to use this directive.
572 This directive is only applicable in a slave slapd. It
573 specifies the URL to return to clients which submit update
574 requests upon the replica.
575 If specified multiple times, each {{TERM:URL}} is provided.
579 > updateref ldap://master.example.net
582 H3: BDB Database Directives
584 Directives in this category only apply to a {{TERM:BDB}} database.
585 That is, they must follow a "database bdb" line and come before any
586 subsequent "backend" or "database" line. For a complete reference
587 of BDB configuration directives, see {{slapd-bdb}}(5).
590 H4: directory <directory>
592 This directive specifies the directory where the BDB files
593 containing the database and associated indices live.
597 > directory /usr/local/var/openldap-data
600 H4: sessionlog <sid> <limit>
602 This directive specifies a session log store in the syncrepl
603 replication provider server which contains information on
604 the entries that have been scoped out of the replication
605 content identified by {{EX:<sid>}}.
606 The first syncrepl search request having the same {{EX:<sid>}} value
607 in the cookie establishes the session log store in the provider server.
608 The number of the entries in the session log store is limited
609 by {{EX:<limit>}}. Excessive entries are removed from the store
610 in the FIFO order. Both {{EX:<sid>}} and {{EX:<limit>}} are
611 non-negative integers. {{EX:<sid>}} has no more than three decimal digits.
613 The LDAP Content Synchronization operation that falls into a pre-existing
614 session can use the session log store in order to reduce the amount
615 of synchronization traffic. If the replica is not so outdated that
616 it can be made up-to-date by the information in the session store,
617 the provider slapd will send the consumer slapd the identities of the
618 scoped-out entries together with the in-scope entries added to or
619 modified within the replication content. If the replica status is
620 outdated too much and beyond the coverage of the history store,
621 then the provider slapd will send the identities of the unchanged
622 in-scope entries along with the changed in-scope entries.
623 The consumer slapd will then remove those entries in the replica
624 which are not identified as present in the provider content.
627 H3: LDBM Database Directives
629 Directives in this category only apply to a {{TERM:LDBM}} database.
630 That is, they must follow a "database ldbm" line and come before
631 any subsequent "backend" or "database" line. For a complete reference
632 of LDBM configuration directives, see {{slapd-ldbm}}(5).
634 H4: cachesize <integer>
636 This directive specifies the size in entries of the in-memory
637 cache maintained by the LDBM backend database instance.
644 H4: dbcachesize <integer>
646 This directive specifies the size in bytes of the in-memory cache
647 associated with each open index file. If not supported by the
648 underlying database method, this directive is ignored without
649 comment. Increasing this number uses more memory but can
650 cause a dramatic performance increase, especially during
651 modifies or when building indices.
660 This option, if present, disables database locking.
661 Enabling this option may improve performance at the expense
667 This option causes on-disk database contents to not be immediately
668 synchronized with in memory changes upon change. Enabling this option
669 may improve performance at the expense of data integrity.
672 H4: directory <directory>
674 This directive specifies the directory where the LDBM files
675 containing the database and associated indices live.
679 > directory /usr/local/var/openldap-data
682 H4: index {<attrlist> | default} [pres,eq,approx,sub,none]
684 This directive specifies the indices to maintain for the given
685 attribute. If only an {{EX:<attrlist>}} is given, the default
686 indices are maintained.
690 > index default pres,eq
692 > index cn,sn pres,eq,sub
693 > index objectClass eq
695 The first line sets the default set of indices to maintain to
696 present and equality. The second line causes the default (pres,eq)
697 set of indices to be maintained for the {{EX:uid}} attribute type.
698 The third line causes present, equality, and substring indices to
699 be maintained for {{EX:cn}} and {{EX:sn}} attribute types. The
700 fourth line causes an equality index for the {{EX:objectClass}}
703 By default, no indices are maintained. It is generally advised
704 that minimally an equality index upon objectClass be maintained.
706 > index objectClass eq
712 This directive specifies the file protection mode that newly
713 created database index files should have.
722 Access to slapd entries and attributes is controlled by the
723 access configuration file directive. The general form of an
726 > <access directive> ::= access to <what>
727 > [by <who> <access> <control>]+
729 > [dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
730 > [filter=<ldapfilter>] [attrs=<attrlist>]
731 > <basic-style> ::= regex | exact
732 > <scope-style> ::= base | one | subtree | children
733 > <attrlist> ::= <attr> [val[.<basic-style>]=<regex>] | <attr> , <attrlist>
734 > <attr> ::= <attrname> | entry | children
735 > <who> ::= * | [anonymous | users | self
736 > | dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
737 > [dnattr=<attrname>]
738 > [group[/<objectclass>[/<attrname>][.<basic-style>]]=<regex>]
739 > [peername[.<basic-style>]=<regex>]
740 > [sockname[.<basic-style>]=<regex>]
741 > [domain[.<basic-style>]=<regex>]
742 > [sockurl[.<basic-style>]=<regex>]
745 > <access> ::= [self]{<level>|<priv>}
746 > <level> ::= none | auth | compare | search | read | write
747 > <priv> ::= {=|+|-}{w|r|s|c|x|0}+
748 > <control> ::= [stop | continue | break]
750 where the <what> part selects the entries and/or attributes to which
751 the access applies, the {{EX:<who>}} part specifies which entities
752 are granted access, and the {{EX:<access>}} part specifies the
753 access granted. Multiple {{EX:<who> <access> <control>}} triplets
754 are supported, allowing many entities to be granted different access
755 to the same set of entries and attributes. Not all of these access
756 control options are described here; for more details see the
757 {{slapd.access}}(5) man page.
760 H3: What to control access to
762 The <what> part of an access specification determines the entries
763 and attributes to which the access control applies. Entries are
764 commonly selected in two ways: by DN and by filter. The following
765 qualifiers select entries by DN:
768 > to dn[.<basic-style>]=<regex>
769 > to dn.<scope-style>=<DN>
771 The first form is used to select all entries. The second form may
772 be used to select entries by matching a regular expression against
773 the target entry's {{normalized DN}}. (The second form is not
774 discussed further in this document.) The third form is used to
775 select entries which are within the requested scope of DN. The
776 <DN> is a string representation of the Distinguished Name, as
777 described in {{REF:RFC2253}}.
779 The scope can be either {{EX:base}}, {{EX:one}}, {{EX:subtree}},
780 or {{EX:children}}. Where {{EX:base}} matches only the entry with
781 provided DN, {{EX:one}} matches the entries whose parent is the
782 provided DN, {{EX:subtree}} matches all entries in the subtree whose
783 root is the provided DN, and {{EX:children}} matches all entries
784 under the DN (but not the entry named by the DN).
786 For example, if the directory contained entries named:
789 > 1: cn=Manager,o=suffix
790 > 2: ou=people,o=suffix
791 > 3: uid=kdz,ou=people,o=suffix
792 > 4: cn=addresses,uid=kdz,ou=people,o=suffix
793 > 5: uid=hyc,ou=people,o=suffix
796 . {{EX:dn.base="ou=people,o=suffix"}} match 2;
797 . {{EX:dn.one="ou=people,o=suffix"}} match 3, and 5;
798 . {{EX:dn.subtree="ou=people,o=suffix"}} match 2, 3, 4, and 5; and
799 . {{EX:dn.children="ou=people,o=suffix"}} match 3, 4, and 5.
802 Entries may also be selected using a filter:
804 > to filter=<ldap filter>
806 where <ldap filter> is a string representation of an LDAP
807 search filter, as described in {{REF:RFC2254}}. For example:
809 > to filter=(objectClass=person)
811 Note that entries may be selected by both DN and filter by
812 including both qualifiers in the <what> clause.
814 > to dn.one="ou=people,o=suffix" filter=(objectClass=person)
816 Attributes within an entry are selected by including a comma-separated
817 list of attribute names in the <what> selector:
819 > attrs=<attribute list>
821 A specific value of an attribute is selected by using a single
822 attribute name and also using a value selector:
824 > attrs=<attribute> val[.<style>]=<regex>
826 There are two special {{pseudo}} attributes {{EX:entry}} and
827 {{EX:children}}. To read (and hence return) a target entry, the
828 subject must have {{EX:read}} access to the target's {{entry}}
829 attribute. To add or delete an entry, the subject must have
830 {{EX:write}} access to the entry's {{EX:entry}} attribute AND must
831 have {{EX:write}} access to the entry's parent's {{EX:children}}
832 attribute. To rename an entry, the subject must have {{EX:write}}
833 access to entry's {{EX:entry}} attribute AND have {{EX:write}}
834 access to both the old parent's and new parent's {{EX:children}}
835 attributes. The complete examples at the end of this section should
836 help clear things up.
838 Lastly, there is a special entry selector {{EX:"*"}} that is used to
839 select any entry. It is used when no other {{EX:<what>}}
840 selector has been provided. It's equivalent to "{{EX:dn=.*}}"
843 H3: Who to grant access to
845 The <who> part identifies the entity or entities being granted
846 access. Note that access is granted to "entities" not "entries."
847 The following table summarizes entity specifiers:
849 !block table; align=Center; coltags="EX,N"; \
850 title="Table 5.3: Access Entity Specifiers"
852 *|All, including anonymous and authenticated users
853 anonymous|Anonymous (non-authenticated) users
854 users|Authenticated users
855 self|User associated with target entry
856 dn[.<basic-style>]=<regex>|Users matching a regular expression
857 dn.<scope-style>=<DN>|Users within scope of a DN
860 The DN specifier behaves much like <what> clause DN specifiers.
862 Other control factors are also supported. For example, a {{EX:<who>}}
863 can be restricted by an entry listed in a DN-valued attribute in
864 the entry to which the access applies:
866 > dnattr=<dn-valued attribute name>
868 The dnattr specification is used to give access to an entry
869 whose DN is listed in an attribute of the entry (e.g., give
870 access to a group entry to whoever is listed as the owner of
873 Some factors may not be appropriate in all environments (or any).
874 For example, the domain factor relies on IP to domain name lookups.
875 As these can easily spoofed, the domain factor should not be avoided.
878 H3: The access to grant
881 The kind of <access> granted can be one of the following:
884 !block table; colaligns="LRL"; coltags="EX,EX,N"; align=Center; \
885 title="Table 5.4: Access Levels"
886 Level Privileges Description
888 auth =x needed to bind
889 compare =cx needed to compare
890 search =scx needed to apply search filters
891 read =rscx needed to read search results
892 write =wrscx needed to modify/rename
895 Each level implies all lower levels of access. So, for
896 example, granting someone {{EX:write}} access to an entry also
897 grants them {{EX:read}}, {{EX:search}}, {{EX:compare}}, and
898 {{EX:auth}} access. However, one may use the privileges specifier
899 to grant specific permissions.
902 H3: Access Control Evaluation
904 When evaluating whether some requester should be given access to
905 an entry and/or attribute, slapd compares the entry and/or attribute
906 to the {{EX:<what>}} selectors given in the configuration file.
907 For each entry, access controls provided in the database which holds
908 the entry (or the first database if not held in any database) apply
909 first, followed by the global access directives. Within this
910 priority, access directives are examined in the order in which they
911 appear in the config file. Slapd stops with the first {{EX:<what>}}
912 selector that matches the entry and/or attribute. The corresponding
913 access directive is the one slapd will use to evaluate access.
915 Next, slapd compares the entity requesting access to the {{EX:<who>}}
916 selectors within the access directive selected above in the order
917 in which they appear. It stops with the first {{EX:<who>}} selector
918 that matches the requester. This determines the access the entity
919 requesting access has to the entry and/or attribute.
921 Finally, slapd compares the access granted in the selected
922 {{EX:<access>}} clause to the access requested by the client. If
923 it allows greater or equal access, access is granted. Otherwise,
926 The order of evaluation of access directives makes their placement
927 in the configuration file important. If one access directive is
928 more specific than another in terms of the entries it selects, it
929 should appear first in the config file. Similarly, if one {{EX:<who>}}
930 selector is more specific than another it should come first in the
931 access directive. The access control examples given below should
932 help make this clear.
936 H3: Access Control Examples
938 The access control facility described above is quite powerful. This
939 section shows some examples of its use for descriptive purposes.
943 > access to * by * read
945 This access directive grants read access to everyone.
952 This directive allows the user to modify their entry, allows anonymous
953 to authentication against these entries, and allows all others to
954 read these entries. Note that only the first {{EX:by <who>}} clause
955 which matches applies. Hence, the anonymous users are granted
956 {{EX:auth}}, not {{EX:read}}. The last clause could just as well
957 have been "{{EX:by users read}}".
959 It is often desirable to restrict operations based upon the level
960 of protection in place. The following shows how security strength
961 factors (SSF) can be used.
964 > by ssf=128 self write
965 > by ssf=64 anonymous auth
966 > by ssf=64 users read
968 This directive allows users to modify their own entries if security
969 protections have of strength 128 or better have been established,
970 allows authentication access to anonymous users, and read access
971 when 64 or better security protections have been established. If
972 client has not establish sufficient security protections, the
973 implicit {{EX:by * none}} clause would be applied.
975 The following example shows the use of a style specifiers to select
976 the entries by DN in two access directives where ordering is
979 > access to dn.children="dc=example,dc=com"
981 > access to dn.children="dc=com"
984 Read access is granted to entries under the {{EX:dc=com}} subtree,
985 except for those entries under the {{EX:dc=example,dc=com}} subtree,
986 to which search access is granted. No access is granted to
987 {{EX:dc=com}} as neither access directive matches this DN. If the
988 order of these access directives was reversed, the trailing directive
989 would never be reached, since all entries under {{EX:dc=example,dc=com}}
990 are also under {{EX:dc=com}} entries.
992 Also note that if no {{EX:access to}} directive matches or no {{EX:by
993 <who>}} clause, {{B:access is denied}}. That is, every {{EX:access
994 to}} directive ends with an implicit {{EX:by * none}} clause and
995 every access list ends with an implicit {{EX:access to * by * none}}
998 The next example again shows the importance of ordering, both of
999 the access directives and the {{EX:by <who>}} clauses. It also
1000 shows the use of an attribute selector to grant access to a specific
1001 attribute and various {{EX:<who>}} selectors.
1003 > access to dn.subtree="dc=example,dc=com" attr=homePhone
1005 > by dn.children=dc=example,dc=com" search
1006 > by peername.regex=IP:10\..+ read
1007 > access to dn.subtree="dc=example,dc=com"
1009 > by dn.children="dc=example,dc=com" search
1012 This example applies to entries in the "{{EX:dc=example,dc=com}}"
1013 subtree. To all attributes except {{EX:homePhone}}, an entry can
1014 write to itself, entries under {{EX:example.com}} entries can search
1015 by them, anybody else has no access (implicit {{EX:by * none}})
1016 excepting for authentication/authorization (which is always done
1017 anonymously). The {{EX:homePhone}} attribute is writable by the
1018 entry, searchable by entries under {{EX:example.com}}, readable by
1019 clients connecting from network 10, and otherwise not readable
1020 (implicit {{EX:by * none}}). All other access is denied by the
1021 implicit {{EX:access to * by * none}}.
1023 Sometimes it is useful to permit a particular DN to add or
1024 remove itself from an attribute. For example, if you would like to
1025 create a group and allow people to add and remove only
1026 their own DN from the member attribute, you could accomplish
1027 it with an access directive like this:
1029 > access to attr=member,entry
1030 > by dnattr=member selfwrite
1032 The dnattr {{EX:<who>}} selector says that the access applies to
1033 entries listed in the {{EX:member}} attribute. The {{EX:selfwrite}} access
1034 selector says that such members can only add or delete their
1035 own DN from the attribute, not other values. The addition of
1036 the entry attribute is required because access to the entry is
1037 required to access any of the entry's attributes.
1040 For more details on how to use the {{EX:access}} directive,
1041 consult the {{Advanced Access Control}} chapter.
1045 H2: Configuration File Example
1047 The following is an example configuration file, interspersed
1048 with explanatory text. It defines two databases to handle
1049 different parts of the {{TERM:X.500}} tree; both are {{TERM:BDB}}
1050 database instances. The line numbers shown are provided for
1051 reference only and are not included in the actual file. First, the
1052 global configuration section:
1054 E: 1. # example config file - global configuration section
1055 E: 2. include /usr/local/etc/schema/core.schema
1056 E: 3. referral ldap://root.openldap.org
1057 E: 4. access to * by * read
1059 Line 1 is a comment. Line 2 includes another config file
1060 which contains {{core}} schema definitions.
1061 The {{EX:referral}} directive on line 3
1062 means that queries not local to one of the databases defined
1063 below will be referred to the LDAP server running on the
1064 standard port (389) at the host {{EX:root.openldap.org}}.
1066 Line 4 is a global access control. It applies to all
1067 entries (after any applicable database-specific access
1070 The next section of the configuration file defines a BDB
1071 backend that will handle queries for things in the
1072 "dc=example,dc=com" portion of the tree. The
1073 database is to be replicated to two slave slapds, one on
1074 truelies, the other on judgmentday. Indices are to be
1075 maintained for several attributes, and the {{EX:userPassword}}
1076 attribute is to be protected from unauthorized access.
1078 E: 5. # BDB definition for the example.com
1080 E: 7. suffix "dc=example,dc=com"
1081 E: 8. directory /usr/local/var/openldap-data
1082 E: 9. rootdn "cn=Manager,dc=example,dc=com"
1083 E: 10. rootpw secret
1084 E: 11. # replication directives
1085 E: 12. replogfile /usr/local/var/openldap/slapd.replog
1086 E: 13. replica uri=ldap://slave1.example.com:389
1087 E: 14. binddn="cn=Replicator,dc=example,dc=com"
1088 E: 15. bindmethod=simple credentials=secret
1089 E: 16. replica uri=ldaps://slave2.example.com:636
1090 E: 17. binddn="cn=Replicator,dc=example,dc=com"
1091 E: 18. bindmethod=simple credentials=secret
1092 E: 19. # indexed attribute definitions
1093 E: 20. index uid pres,eq
1094 E: 21. index cn,sn,uid pres,eq,approx,sub
1095 E: 22. index objectClass eq
1096 E: 23. # database access control definitions
1097 E: 24. access to attr=userPassword
1098 E: 25. by self write
1099 E: 26. by anonymous auth
1100 E: 27. by dn.base="cn=Admin,dc=example,dc=com" write
1103 E: 30. by self write
1104 E: 31. by dn.base="cn=Admin,dc=example,dc=com" write
1107 Line 5 is a comment. The start of the database definition is marked
1108 by the database keyword on line 6. Line 7 specifies the DN suffix
1109 for queries to pass to this database. Line 8 specifies the directory
1110 in which the database files will live.
1112 Lines 9 and 10 identify the database {{super-user}} entry and associated
1113 password. This entry is not subject to access control or size or
1114 time limit restrictions.
1116 Lines 11 through 18 are for replication. Line 12 specifies the
1117 replication log file (where changes to the database are logged -
1118 this file is written by slapd and read by slurpd). Lines 13 through
1119 15 specify the hostname and port for a replicated host, the DN to
1120 bind as when performing updates, the bind method (simple) and the
1121 credentials (password) for the binddn. Lines 16 through 18 specify
1122 a second replication site. See the {{SECT:Replication with slurpd}}
1123 chapter for more information on these directives.
1125 Lines 20 through 22 indicate the indices to maintain for various
1128 Lines 24 through 32 specify access control for entries in this
1129 database. As this is the first database, the controls also apply
1130 to entries not held in any database (such as the Root DSE). For
1131 all applicable entries, the {{EX:userPassword}} attribute is writable
1132 by the entry itself and by the "admin" entry. It may be used for
1133 authentication/authorization purposes, but is otherwise not readable.
1134 All other attributes are writable by the entry and the "admin"
1135 entry, but may be read by all users (authenticated or not).
1137 The next section of the example configuration file defines another
1138 BDB database. This one handles queries involving the
1139 {{EX:dc=example,dc=net}} subtree but is managed by the same entity
1140 as the first database. Note that without line 39, the read access
1141 would be allowed due to the global access rule at line 4.
1143 E: 33. # BDB definition for example.net
1145 E: 35. suffix "dc=example,dc=net"
1146 E: 36. directory /usr/local/var/openldap-data-net
1147 E: 37. rootdn "cn=Manager,dc=example,dc=com"
1148 E: 38. index objectClass eq
1149 E: 39. access to * by users read