2 # Copyright 1999-2005, 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|sasl}]
293 > [authcid=<identity>]
294 > [authzid=<identity>]
295 > [credentials=<password>]
297 This directive specifies a replication site for this database. The
298 {{EX:uri=}} parameter specifies a scheme, a host and optionally a port where
299 the slave slapd instance can be found. Either a domain name
300 or IP address may be used for <hostname>. If <port> is not
301 given, the standard LDAP port number (389 or 636) is used.
303 {{EX:host}} is deprecated in favor of the {{EX:uri}} parameter.
305 {{EX:uri}} allows the replica LDAP server to be specified as an LDAP
306 URI such as {{EX:ldap://slave.example.com:389}} or
307 {{EX:ldaps://slave.example.com:636}}.
309 The {{EX:binddn=}} parameter gives the DN to bind as for updates
310 to the slave slapd. It should be a DN which has read/write access
311 to the slave slapd's database. It must also match the {{EX:updatedn}}
312 directive in the slave slapd's config file. Generally, this DN
313 {{should not}} be the same as the {{EX:rootdn}} of the master
314 database. Since DNs are likely to contain embedded spaces, the
315 entire {{EX:"binddn=<DN>"}} string should be enclosed in double
318 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}}, depending
319 on whether simple password-based authentication or {{TERM:SASL}}
320 authentication is to be used when connecting to the slave slapd.
322 Simple authentication should not be used unless adequate data
323 integrity and confidentiality protections are in place (e.g. TLS
324 or IPSEC). Simple authentication requires specification of
325 {{EX:binddn}} and {{EX:credentials}} parameters.
327 SASL authentication is generally recommended. SASL authentication
328 requires specification of a mechanism using the {{EX:saslmech}} parameter.
329 Depending on the mechanism, an authentication identity and/or
330 credentials can be specified using {{EX:authcid}} and {{EX:credentials}}
331 respectively. The {{EX:authzid}} parameter may be used to specify
332 an authorization identity.
334 See the chapter entitled {{SECT:Replication with slurpd}} for more
335 information on how to use this directive.
338 H4: replogfile <filename>
340 This directive specifies the name of the replication log file to
341 which slapd will log changes. The replication log is typically
342 written by slapd and read by slurpd. Normally, this directive is
343 only used if slurpd is being used to replicate the database.
344 However, you can also use it to generate a transaction log, if
345 slurpd is not running. In this case, you will need to periodically
346 truncate the file, since it will grow indefinitely otherwise.
348 See the chapter entitled {{SECT:Replication with slurpd}} for more
349 information on how to use this directive.
354 This directive specifies the DN that is not subject to
355 access control or administrative limit restrictions for
356 operations on this database. The DN need not refer to
357 an entry in this database or even in the directory. The
358 DN may refer to a SASL identity.
362 > rootdn "cn=Manager,dc=example,dc=com"
366 > rootdn "uid=root,cn=example.com,cn=digest-md5,cn=auth"
368 See the {{SECT:SASL Authentication}} section for information on
369 SASL authentication identities.
372 H4: rootpw <password>
374 This directive can be used to specifies a password for the DN for
375 the rootdn (when the rootdn is set to a DN within the database).
381 It is also permissible to provide hash of the password in RFC 2307
382 form. {{slappasswd}}(8) may be used to generate the password hash.
386 > rootpw {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN
388 The hash was generated using the command {{EX:slappasswd -s secret}}.
391 H4: suffix <dn suffix>
393 This directive specifies the DN suffix of queries that will be
394 passed to this backend database. Multiple suffix lines can be
395 given, and at least one is required for each database
400 > suffix "dc=example,dc=com"
402 Queries with a DN ending in "dc=example,dc=com"
403 will be passed to this backend.
405 Note: When the backend to pass a query to is selected, slapd
406 looks at the suffix line(s) in each database definition in the
407 order they appear in the file. Thus, if one database suffix is a
408 prefix of another, it must appear after it in the config file.
413 > syncrepl rid=<replica ID>
414 > provider=ldap[s]://<hostname>[:port]
415 > [type=refreshOnly|refreshAndPersist]
416 > [interval=dd:hh:mm:ss]
417 > [retry=[<retry interval> <# of retries>]+]
418 > [searchbase=<base DN>]
419 > [filter=<filter str>]
420 > [scope=sub|one|base]
421 > [attrs=<attr list>]
423 > [sizelimit=<limit>]
424 > [timelimit=<limit>]
425 > [schemachecking=on|off]
426 > [bindmethod=simple|sasl]
429 > [authcid=<identity>]
430 > [authzid=<identity>]
431 > [credentials=<passwd>]
433 > [secprops=<properties>]
436 This directive specifies the current database as a replica of the
437 master content by establishing the current {{slapd}}(8) as a
438 replication consumer site running a syncrepl replication engine.
439 The master database is located at the replication provider site
440 specified by the {{EX:provider}} parameter. The replica database is
441 kept up-to-date with the master content using the LDAP Content
442 Synchronization protocol. See {{EX:draft-zeilenga-ldup-sync-xx.txt}}
443 ({{a work in progress}}) for more information on the protocol.
445 The {{EX:rid}} parameter is used for identification of the current
446 {{EX:syncrepl}} directive within the replication consumer server,
447 where {{EX:<replica ID>}} uniquely identifies the syncrepl specification
448 described by the current {{EX:syncrepl}} directive. {{EX:<replica ID>}}
449 is non-negative and is no more than three decimal digits in length.
451 The {{EX:provider}} parameter specifies the replication provider site
452 containing the master content as an LDAP URI. The {{EX:provider}}
453 parameter specifies a scheme, a host and optionally a port where the
454 provider slapd instance can be found. Either a domain name or IP
455 address may be used for <hostname>. Examples are
456 {{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}.
457 If <port> is not given, the standard LDAP port number (389 or 636) is used.
458 Note that the syncrepl uses a consumer-initiated protocol, and hence its
459 specification is located at the consumer site, whereas the {{EX:replica}}
460 specification is located at the provider site. {{EX:syncrepl}} and
461 {{EX:replica}} directives define two independent replication
462 mechanisms. They do not represent the replication peers of each other.
464 The content of the syncrepl replica is defined using a search
465 specification as its result set. The consumer slapd will
466 send search requests to the provider slapd according to the search
467 specification. The search specification includes {{EX:searchbase}},
468 {{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:attrsonly}},
469 {{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal
470 search specification. The syncrepl search specification has
471 the same value syntax and the same default values as in the
472 {{ldapsearch}}(1) client search tool.
474 The LDAP Content Synchronization protocol has two operation
475 types: {{EX:refreshOnly}} and {{EX:refreshAndPersist}}.
476 The operation type is specified by the {{EX:type}} parameter.
477 In the {{EX:refreshOnly}} operation, the next synchronization search operation
478 is periodically rescheduled at an interval time after each
479 synchronization operation finishes. The interval is specified
480 by the {{EX:interval}} parameter. It is set to one day by default.
481 In the {{EX:refreshAndPersist}} operation, a synchronization search
482 remains persistent in the provider slapd. Further updates to the
483 master replica will generate {{EX:searchResultEntry}} to the consumer slapd
484 as the search responses to the persistent synchronization search.
486 If an error occurs during replication, the consumer will attempt to reconnect
487 according to the retry parameter which is a list of the <retry interval>
488 and <# of retries> pairs. For example, retry="60 5 300 3" lets the consumer
489 retry every 60 seconds for the first 10 times and then retry every 300 seconds
490 for the next three times before stop retrying. + in <# of retries> means
491 indefinite number of retries until success.
493 The schema checking can be enforced at the LDAP Sync consumer site
494 by turning on the {{EX:schemachecking}} parameter.
495 If it is turned on, every replicated entry will be checked for its
496 schema as the entry is stored into the replica content.
497 Every entry in the replica should contain those attributes
498 required by the schema definition.
499 If it is turned off, entries will be stored without checking
500 schema conformance. The default is off.
502 The {{EX:binddn}} parameter gives the DN to bind as for the
503 syncrepl searches to the provider slapd. It should be a DN
504 which has read access to the replication content in the
507 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
508 depending on whether simple password-based authentication or
509 {{TERM:SASL}} authentication is to be used when connecting
510 to the provider slapd.
512 Simple authentication should not be used unless adequate data
513 integrity and confidentiality protections are in place (e.g. TLS
514 or IPSEC). Simple authentication requires specification of {{EX:binddn}}
515 and {{EX:credentials}} parameters.
517 SASL authentication is generally recommended. SASL authentication
518 requires specification of a mechanism using the {{EX:saslmech}} parameter.
519 Depending on the mechanism, an authentication identity and/or
520 credentials can be specified using {{EX:authcid}} and {{EX:credentials}},
521 respectively. The {{EX:authzid}} parameter may be used to specify
522 an authorization identity.
524 The {{EX:realm}} parameter specifies a realm which a certain
525 mechanisms authenticate the identity within. The {{EX:secprops}}
526 parameter specifies Cyrus SASL security properties.
528 The syncrepl replication mechanism is supported by the
529 three native backends: back-bdb, back-hdb, and back-ldbm.
531 See the {{SECT:LDAP Sync Replication}} chapter of the admin guide
532 for more information on how to use this directive.
537 This directive is only applicable in a slave slapd. It specifies
538 the DN allowed to make changes to the replica. This may be the DN
539 {{slurpd}}(8) binds as when making changes to the replica or the DN
540 associated with a SASL identity.
544 > updatedn "cn=Update Daemon,dc=example,dc=com"
548 > updatedn "uid=slurpd,cn=example.com,cn=digest-md5,cn=auth"
550 See the {{SECT:Replication with slurpd}} chapter for more information
551 on how to use this directive.
555 This directive is only applicable in a slave slapd. It
556 specifies the URL to return to clients which submit update
557 requests upon the replica.
558 If specified multiple times, each {{TERM:URL}} is provided.
562 > updateref ldap://master.example.net
565 H3: BDB Database Directives
567 Directives in this category only apply to a {{TERM:BDB}} database.
568 That is, they must follow a "database bdb" line and come before any
569 subsequent "backend" or "database" line. For a complete reference
570 of BDB configuration directives, see {{slapd-bdb}}(5).
573 H4: directory <directory>
575 This directive specifies the directory where the BDB files
576 containing the database and associated indices live.
580 > directory /usr/local/var/openldap-data
583 H3: LDBM Database Directives
585 Directives in this category only apply to a {{TERM:LDBM}} database.
586 That is, they must follow a "database ldbm" line and come before
587 any subsequent "backend" or "database" line. For a complete reference
588 of LDBM configuration directives, see {{slapd-ldbm}}(5).
590 H4: cachesize <integer>
592 This directive specifies the size in entries of the in-memory
593 cache maintained by the LDBM backend database instance.
600 H4: dbcachesize <integer>
602 This directive specifies the size in bytes of the in-memory cache
603 associated with each open index file. If not supported by the
604 underlying database method, this directive is ignored without
605 comment. Increasing this number uses more memory but can
606 cause a dramatic performance increase, especially during
607 modifies or when building indices.
616 This option, if present, disables database locking.
617 Enabling this option may improve performance at the expense
623 This option causes on-disk database contents to not be immediately
624 synchronized with in memory changes upon change. Enabling this option
625 may improve performance at the expense of data integrity.
628 H4: directory <directory>
630 This directive specifies the directory where the LDBM files
631 containing the database and associated indices live.
635 > directory /usr/local/var/openldap-data
638 H4: index {<attrlist> | default} [pres,eq,approx,sub,none]
640 This directive specifies the indices to maintain for the given
641 attribute. If only an {{EX:<attrlist>}} is given, the default
642 indices are maintained.
646 > index default pres,eq
648 > index cn,sn pres,eq,sub
649 > index objectClass eq
651 The first line sets the default set of indices to maintain to
652 present and equality. The second line causes the default (pres,eq)
653 set of indices to be maintained for the {{EX:uid}} attribute type.
654 The third line causes present, equality, and substring indices to
655 be maintained for {{EX:cn}} and {{EX:sn}} attribute types. The
656 fourth line causes an equality index for the {{EX:objectClass}}
659 By default, no indices are maintained. It is generally advised
660 that minimally an equality index upon objectClass be maintained.
662 > index objectClass eq
668 This directive specifies the file protection mode that newly
669 created database index files should have.
678 Access to slapd entries and attributes is controlled by the
679 access configuration file directive. The general form of an
682 > <access directive> ::= access to <what>
683 > [by <who> <access> <control>]+
685 > [dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
686 > [filter=<ldapfilter>] [attrs=<attrlist>]
687 > <basic-style> ::= regex | exact
688 > <scope-style> ::= base | one | subtree | children
689 > <attrlist> ::= <attr> [val[.<basic-style>]=<regex>] | <attr> , <attrlist>
690 > <attr> ::= <attrname> | entry | children
691 > <who> ::= * | [anonymous | users | self
692 > | dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
693 > [dnattr=<attrname>]
694 > [group[/<objectclass>[/<attrname>][.<basic-style>]]=<regex>]
695 > [peername[.<basic-style>]=<regex>]
696 > [sockname[.<basic-style>]=<regex>]
697 > [domain[.<basic-style>]=<regex>]
698 > [sockurl[.<basic-style>]=<regex>]
701 > <access> ::= [self]{<level>|<priv>}
702 > <level> ::= none | auth | compare | search | read | write
703 > <priv> ::= {=|+|-}{w|r|s|c|x|0}+
704 > <control> ::= [stop | continue | break]
706 where the <what> part selects the entries and/or attributes to which
707 the access applies, the {{EX:<who>}} part specifies which entities
708 are granted access, and the {{EX:<access>}} part specifies the
709 access granted. Multiple {{EX:<who> <access> <control>}} triplets
710 are supported, allowing many entities to be granted different access
711 to the same set of entries and attributes. Not all of these access
712 control options are described here; for more details see the
713 {{slapd.access}}(5) man page.
716 H3: What to control access to
718 The <what> part of an access specification determines the entries
719 and attributes to which the access control applies. Entries are
720 commonly selected in two ways: by DN and by filter. The following
721 qualifiers select entries by DN:
724 > to dn[.<basic-style>]=<regex>
725 > to dn.<scope-style>=<DN>
727 The first form is used to select all entries. The second form may
728 be used to select entries by matching a regular expression against
729 the target entry's {{normalized DN}}. (The second form is not
730 discussed further in this document.) The third form is used to
731 select entries which are within the requested scope of DN. The
732 <DN> is a string representation of the Distinguished Name, as
733 described in {{REF:RFC2253}}.
735 The scope can be either {{EX:base}}, {{EX:one}}, {{EX:subtree}},
736 or {{EX:children}}. Where {{EX:base}} matches only the entry with
737 provided DN, {{EX:one}} matches the entries whose parent is the
738 provided DN, {{EX:subtree}} matches all entries in the subtree whose
739 root is the provided DN, and {{EX:children}} matches all entries
740 under the DN (but not the entry named by the DN).
742 For example, if the directory contained entries named:
745 > 1: cn=Manager,o=suffix
746 > 2: ou=people,o=suffix
747 > 3: uid=kdz,ou=people,o=suffix
748 > 4: cn=addresses,uid=kdz,ou=people,o=suffix
749 > 5: uid=hyc,ou=people,o=suffix
752 . {{EX:dn.base="ou=people,o=suffix"}} match 2;
753 . {{EX:dn.one="ou=people,o=suffix"}} match 3, and 5;
754 . {{EX:dn.subtree="ou=people,o=suffix"}} match 2, 3, 4, and 5; and
755 . {{EX:dn.children="ou=people,o=suffix"}} match 3, 4, and 5.
758 Entries may also be selected using a filter:
760 > to filter=<ldap filter>
762 where <ldap filter> is a string representation of an LDAP
763 search filter, as described in {{REF:RFC2254}}. For example:
765 > to filter=(objectClass=person)
767 Note that entries may be selected by both DN and filter by
768 including both qualifiers in the <what> clause.
770 > to dn.one="ou=people,o=suffix" filter=(objectClass=person)
772 Attributes within an entry are selected by including a comma-separated
773 list of attribute names in the <what> selector:
775 > attrs=<attribute list>
777 A specific value of an attribute is selected by using a single
778 attribute name and also using a value selector:
780 > attrs=<attribute> val[.<style>]=<regex>
782 There are two special {{pseudo}} attributes {{EX:entry}} and
783 {{EX:children}}. To read (and hence return) a target entry, the
784 subject must have {{EX:read}} access to the target's {{entry}}
785 attribute. To add or delete an entry, the subject must have
786 {{EX:write}} access to the entry's {{EX:entry}} attribute AND must
787 have {{EX:write}} access to the entry's parent's {{EX:children}}
788 attribute. To rename an entry, the subject must have {{EX:write}}
789 access to entry's {{EX:entry}} attribute AND have {{EX:write}}
790 access to both the old parent's and new parent's {{EX:children}}
791 attributes. The complete examples at the end of this section should
792 help clear things up.
794 Lastly, there is a special entry selector {{EX:"*"}} that is used to
795 select any entry. It is used when no other {{EX:<what>}}
796 selector has been provided. It's equivalent to "{{EX:dn=.*}}"
799 H3: Who to grant access to
801 The <who> part identifies the entity or entities being granted
802 access. Note that access is granted to "entities" not "entries."
803 The following table summarizes entity specifiers:
805 !block table; align=Center; coltags="EX,N"; \
806 title="Table 5.3: Access Entity Specifiers"
808 *|All, including anonymous and authenticated users
809 anonymous|Anonymous (non-authenticated) users
810 users|Authenticated users
811 self|User associated with target entry
812 dn[.<basic-style>]=<regex>|Users matching a regular expression
813 dn.<scope-style>=<DN>|Users within scope of a DN
816 The DN specifier behaves much like <what> clause DN specifiers.
818 Other control factors are also supported. For example, a {{EX:<who>}}
819 can be restricted by an entry listed in a DN-valued attribute in
820 the entry to which the access applies:
822 > dnattr=<dn-valued attribute name>
824 The dnattr specification is used to give access to an entry
825 whose DN is listed in an attribute of the entry (e.g., give
826 access to a group entry to whoever is listed as the owner of
829 Some factors may not be appropriate in all environments (or any).
830 For example, the domain factor relies on IP to domain name lookups.
831 As these can easily spoofed, the domain factor should not be avoided.
834 H3: The access to grant
837 The kind of <access> granted can be one of the following:
840 !block table; colaligns="LRL"; coltags="EX,EX,N"; align=Center; \
841 title="Table 5.4: Access Levels"
842 Level Privileges Description
844 auth =x needed to bind
845 compare =cx needed to compare
846 search =scx needed to apply search filters
847 read =rscx needed to read search results
848 write =wrscx needed to modify/rename
851 Each level implies all lower levels of access. So, for
852 example, granting someone {{EX:write}} access to an entry also
853 grants them {{EX:read}}, {{EX:search}}, {{EX:compare}}, and
854 {{EX:auth}} access. However, one may use the privileges specifier
855 to grant specific permissions.
858 H3: Access Control Evaluation
860 When evaluating whether some requester should be given access to
861 an entry and/or attribute, slapd compares the entry and/or attribute
862 to the {{EX:<what>}} selectors given in the configuration file.
863 For each entry, access controls provided in the database which holds
864 the entry (or the first database if not held in any database) apply
865 first, followed by the global access directives. Within this
866 priority, access directives are examined in the order in which they
867 appear in the config file. Slapd stops with the first {{EX:<what>}}
868 selector that matches the entry and/or attribute. The corresponding
869 access directive is the one slapd will use to evaluate access.
871 Next, slapd compares the entity requesting access to the {{EX:<who>}}
872 selectors within the access directive selected above in the order
873 in which they appear. It stops with the first {{EX:<who>}} selector
874 that matches the requester. This determines the access the entity
875 requesting access has to the entry and/or attribute.
877 Finally, slapd compares the access granted in the selected
878 {{EX:<access>}} clause to the access requested by the client. If
879 it allows greater or equal access, access is granted. Otherwise,
882 The order of evaluation of access directives makes their placement
883 in the configuration file important. If one access directive is
884 more specific than another in terms of the entries it selects, it
885 should appear first in the config file. Similarly, if one {{EX:<who>}}
886 selector is more specific than another it should come first in the
887 access directive. The access control examples given below should
888 help make this clear.
892 H3: Access Control Examples
894 The access control facility described above is quite powerful. This
895 section shows some examples of its use for descriptive purposes.
899 > access to * by * read
901 This access directive grants read access to everyone.
908 This directive allows the user to modify their entry, allows anonymous
909 to authentication against these entries, and allows all others to
910 read these entries. Note that only the first {{EX:by <who>}} clause
911 which matches applies. Hence, the anonymous users are granted
912 {{EX:auth}}, not {{EX:read}}. The last clause could just as well
913 have been "{{EX:by users read}}".
915 It is often desirable to restrict operations based upon the level
916 of protection in place. The following shows how security strength
917 factors (SSF) can be used.
920 > by ssf=128 self write
921 > by ssf=64 anonymous auth
922 > by ssf=64 users read
924 This directive allows users to modify their own entries if security
925 protections have of strength 128 or better have been established,
926 allows authentication access to anonymous users, and read access
927 when 64 or better security protections have been established. If
928 client has not establish sufficient security protections, the
929 implicit {{EX:by * none}} clause would be applied.
931 The following example shows the use of a style specifiers to select
932 the entries by DN in two access directives where ordering is
935 > access to dn.children="dc=example,dc=com"
937 > access to dn.children="dc=com"
940 Read access is granted to entries under the {{EX:dc=com}} subtree,
941 except for those entries under the {{EX:dc=example,dc=com}} subtree,
942 to which search access is granted. No access is granted to
943 {{EX:dc=com}} as neither access directive matches this DN. If the
944 order of these access directives was reversed, the trailing directive
945 would never be reached, since all entries under {{EX:dc=example,dc=com}}
946 are also under {{EX:dc=com}} entries.
948 Also note that if no {{EX:access to}} directive matches or no {{EX:by
949 <who>}} clause, {{B:access is denied}}. That is, every {{EX:access
950 to}} directive ends with an implicit {{EX:by * none}} clause and
951 every access list ends with an implicit {{EX:access to * by * none}}
954 The next example again shows the importance of ordering, both of
955 the access directives and the {{EX:by <who>}} clauses. It also
956 shows the use of an attribute selector to grant access to a specific
957 attribute and various {{EX:<who>}} selectors.
959 > access to dn.subtree="dc=example,dc=com" attr=homePhone
961 > by dn.children="dc=example,dc=com" search
962 > by peername.regex=IP:10\..+ read
963 > access to dn.subtree="dc=example,dc=com"
965 > by dn.children="dc=example,dc=com" search
968 This example applies to entries in the "{{EX:dc=example,dc=com}}"
969 subtree. To all attributes except {{EX:homePhone}}, an entry can
970 write to itself, entries under {{EX:example.com}} entries can search
971 by them, anybody else has no access (implicit {{EX:by * none}})
972 excepting for authentication/authorization (which is always done
973 anonymously). The {{EX:homePhone}} attribute is writable by the
974 entry, searchable by entries under {{EX:example.com}}, readable by
975 clients connecting from network 10, and otherwise not readable
976 (implicit {{EX:by * none}}). All other access is denied by the
977 implicit {{EX:access to * by * none}}.
979 Sometimes it is useful to permit a particular DN to add or
980 remove itself from an attribute. For example, if you would like to
981 create a group and allow people to add and remove only
982 their own DN from the member attribute, you could accomplish
983 it with an access directive like this:
985 > access to attr=member,entry
986 > by dnattr=member selfwrite
988 The dnattr {{EX:<who>}} selector says that the access applies to
989 entries listed in the {{EX:member}} attribute. The {{EX:selfwrite}} access
990 selector says that such members can only add or delete their
991 own DN from the attribute, not other values. The addition of
992 the entry attribute is required because access to the entry is
993 required to access any of the entry's attributes.
996 For more details on how to use the {{EX:access}} directive,
997 consult the {{Advanced Access Control}} chapter.
1001 H2: Configuration File Example
1003 The following is an example configuration file, interspersed
1004 with explanatory text. It defines two databases to handle
1005 different parts of the {{TERM:X.500}} tree; both are {{TERM:BDB}}
1006 database instances. The line numbers shown are provided for
1007 reference only and are not included in the actual file. First, the
1008 global configuration section:
1010 E: 1. # example config file - global configuration section
1011 E: 2. include /usr/local/etc/schema/core.schema
1012 E: 3. referral ldap://root.openldap.org
1013 E: 4. access to * by * read
1015 Line 1 is a comment. Line 2 includes another config file
1016 which contains {{core}} schema definitions.
1017 The {{EX:referral}} directive on line 3
1018 means that queries not local to one of the databases defined
1019 below will be referred to the LDAP server running on the
1020 standard port (389) at the host {{EX:root.openldap.org}}.
1022 Line 4 is a global access control. It applies to all
1023 entries (after any applicable database-specific access
1026 The next section of the configuration file defines a BDB
1027 backend that will handle queries for things in the
1028 "dc=example,dc=com" portion of the tree. The
1029 database is to be replicated to two slave slapds, one on
1030 truelies, the other on judgmentday. Indices are to be
1031 maintained for several attributes, and the {{EX:userPassword}}
1032 attribute is to be protected from unauthorized access.
1034 E: 5. # BDB definition for the example.com
1036 E: 7. suffix "dc=example,dc=com"
1037 E: 8. directory /usr/local/var/openldap-data
1038 E: 9. rootdn "cn=Manager,dc=example,dc=com"
1039 E: 10. rootpw secret
1040 E: 11. # replication directives
1041 E: 12. replogfile /usr/local/var/openldap/slapd.replog
1042 E: 13. replica uri=ldap://slave1.example.com:389
1043 E: 14. binddn="cn=Replicator,dc=example,dc=com"
1044 E: 15. bindmethod=simple credentials=secret
1045 E: 16. replica uri=ldaps://slave2.example.com:636
1046 E: 17. binddn="cn=Replicator,dc=example,dc=com"
1047 E: 18. bindmethod=simple credentials=secret
1048 E: 19. # indexed attribute definitions
1049 E: 20. index uid pres,eq
1050 E: 21. index cn,sn,uid pres,eq,approx,sub
1051 E: 22. index objectClass eq
1052 E: 23. # database access control definitions
1053 E: 24. access to attr=userPassword
1054 E: 25. by self write
1055 E: 26. by anonymous auth
1056 E: 27. by dn.base="cn=Admin,dc=example,dc=com" write
1059 E: 30. by self write
1060 E: 31. by dn.base="cn=Admin,dc=example,dc=com" write
1063 Line 5 is a comment. The start of the database definition is marked
1064 by the database keyword on line 6. Line 7 specifies the DN suffix
1065 for queries to pass to this database. Line 8 specifies the directory
1066 in which the database files will live.
1068 Lines 9 and 10 identify the database {{super-user}} entry and associated
1069 password. This entry is not subject to access control or size or
1070 time limit restrictions.
1072 Lines 11 through 18 are for replication. Line 12 specifies the
1073 replication log file (where changes to the database are logged -
1074 this file is written by slapd and read by slurpd). Lines 13 through
1075 15 specify the hostname and port for a replicated host, the DN to
1076 bind as when performing updates, the bind method (simple) and the
1077 credentials (password) for the binddn. Lines 16 through 18 specify
1078 a second replication site. See the {{SECT:Replication with slurpd}}
1079 chapter for more information on these directives.
1081 Lines 20 through 22 indicate the indices to maintain for various
1084 Lines 24 through 32 specify access control for entries in this
1085 database. As this is the first database, the controls also apply
1086 to entries not held in any database (such as the Root DSE). For
1087 all applicable entries, the {{EX:userPassword}} attribute is writable
1088 by the entry itself and by the "admin" entry. It may be used for
1089 authentication/authorization purposes, but is otherwise not readable.
1090 All other attributes are writable by the entry and the "admin"
1091 entry, but may be read by all users (authenticated or not).
1093 The next section of the example configuration file defines another
1094 BDB database. This one handles queries involving the
1095 {{EX:dc=example,dc=net}} subtree but is managed by the same entity
1096 as the first database. Note that without line 39, the read access
1097 would be allowed due to the global access rule at line 4.
1099 E: 33. # BDB definition for example.net
1101 E: 35. suffix "dc=example,dc=net"
1102 E: 36. directory /usr/local/var/openldap-data-net
1103 E: 37. rootdn "cn=Manager,dc=example,dc=com"
1104 E: 38. index objectClass eq
1105 E: 39. access to * by users read