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. The general format of slapd.conf is
34 > # global configuration directives
35 > <global config directives>
37 > # backend definition
39 > <backend-specific directives>
41 > # first database definition & config directives
43 > <database-specific directives>
45 > # second database definition & config directives
47 > <database-specific directives>
49 > # second database definition & config directives
51 > <database-specific directives>
53 > # subsequent backend & database definitions & config directives
56 A configuration directive may take arguments. If so, they are
57 separated by white space. If an argument contains white space,
58 the argument should be enclosed in double quotes {{EX:"like this"}}. If
59 an argument contains a double quote or a backslash character `{{EX:\}}',
60 the character should be preceded by a backslash character `{{EX:\}}'.
62 The distribution contains an example configuration file that will
63 be installed in the {{F: /usr/local/etc/openldap}} directory.
64 A number of files containing schema definitions (attribute types
65 and object classes) are also provided in the
66 {{F: /usr/local/etc/openldap/schema}} directory.
69 H2: Configuration File Directives
71 This section details commonly used configuration directives. For
72 a complete list, see the {{slapd.conf}}(5) manual page. This section
73 separates the configuration file directives into global,
74 backend-specific and data-specific categories, describing each
75 directive and its default value (if any), and giving an example of
82 Directives described in this section apply to all backends
83 and databases unless specifically overridden in a backend or
84 database definition. Arguments that should be replaced
85 by actual text are shown in brackets {{EX:<>}}.
88 H4: access to <what> [ by <who> <accesslevel> <control> ]+
90 This directive grants access (specified by <accesslevel>) to a
91 set of entries and/or attributes (specified by <what>) by one or
92 more requesters (specified by <who>).
93 See the {{SECT:Access Control}} section of this chapter for a
94 summary of basic usage.
97 More details discussion of this directive can be found in the
98 {{SECT:Advanced Access Control}} chapter.
101 Note: If no {{EX:access}} directives are specified, the default
102 access control policy, {{EX:access to * by * read}}, allows all
103 both authenticated and anonymous users read access.
106 H4: attributetype <{{REF:RFC2252}} Attribute Type Description>
108 This directive defines an attribute type.
109 Please see the {{SECT:Schema Specification}} chapter
110 for information regarding how to use this directive.
112 H4: idletimeout <integer>
114 Specify the number of seconds to wait before forcibly closing
115 an idle client connection. An idletimeout of 0, the default,
116 disables this feature.
119 H4: include <filename>
121 This directive specifies that slapd should read additional
122 configuration information from the given file before continuing
123 with the next line of the current file. The included file should
124 follow the normal slapd config file format. The file is commonly
125 used to include files containing schema specifications.
127 Note: You should be careful when using this directive - there is
128 no small limit on the number of nested include directives, and no
129 loop detection is done.
131 H4: loglevel <integer>
133 This directive specifies the level at which debugging statements
134 and operation statistics should be syslogged (currently logged to
135 the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have
136 configured OpenLDAP {{EX:--enable-debug}} (the default) for this
137 to work (except for the two statistics levels, which are always
138 enabled). Log levels are additive. To display what numbers
139 correspond to what kind of debugging, invoke slapd with {{EX:-?}}
140 or consult the table below. The possible values for <integer> are:
142 !block table; colaligns="RL"; align=Center; \
143 title="Table 5.1: Debugging Levels"
145 -1 enable all debugging
147 1 trace function calls
148 2 debug packet handling
149 4 heavy trace debugging
150 8 connection management
151 16 print out packets sent and received
152 32 search filter processing
153 64 configuration file processing
154 128 access control list processing
155 256 stats log connections/operations/results
156 512 stats log entries sent
157 1024 print communication with shell backends
158 2048 print entry parsing debugging
165 This will cause lots and lots of debugging information to be
173 H4: objectclass <{{REF:RFC2252}} Object Class Description>
175 This directive defines an object class.
176 Please see the {{SECT:Schema Specification}} chapter for
177 information regarding how to use this directive.
182 This directive specifies the referral to pass back when slapd
183 cannot find a local database to handle a request.
187 > referral ldap://root.openldap.org
189 This will refer non-local queries to the global root LDAP server
190 at the OpenLDAP Project. Smart LDAP clients can re-ask their
191 query at that server, but note that most of these clients are
192 only going to know how to handle simple LDAP URLs that
193 contain a host part and optionally a distinguished name part.
196 H4: sizelimit <integer>
198 This directive specifies the maximum number of entries to return
199 from a search operation.
206 H4: timelimit <integer>
208 This directive specifies the maximum number of seconds (in real
209 time) slapd will spend answering a search request. If a
210 request is not finished in this time, a result indicating an
211 exceeded timelimit will be returned.
218 H3: General Backend Directives
220 Directives in this section apply only to the backend in which
221 they are defined. They are supported by every type of backend.
222 Backend directives apply to all databases instances of the
223 same type and, depending on the directive, may be overridden
224 by database directives.
228 This directive marks the beginning of a backend declaration.
229 {{EX:<type>}} should be one of the
230 supported backend types listed in Table 5.2.
232 !block table; align=Center; coltags="EX,N"; \
233 title="Table 5.2: Database Backends"
235 bdb Berkeley DB transactional backend
236 dnssrv DNS SRV backend
237 ldap Lightweight Directory Access Protocol (Proxy) backend
238 ldbm Lightweight DBM backend
239 meta Meta Directory backend
240 monitor Monitor backend
241 passwd Provides read-only access to {{passwd}}(5)
242 perl Perl Programmable backend
243 shell Shell (extern program) backend
244 sql SQL Programmable backend
251 This marks the beginning of a new {{TERM:BDB}} backend
255 H3: General Database Directives
257 Directives in this section apply only to the database in which
258 they are defined. They are supported by every type of database.
262 This directive marks the beginning of a database instance
264 {{EX:<type>}} should be one of the
265 supported backend types listed in Table 5.2.
271 This marks the beginning of a new {{TERM:BDB}} database instance
275 H4: readonly { on | off }
277 This directive puts the database into "read-only" mode. Any
278 attempts to modify the database will return an "unwilling to
287 > replica host=<hostname>[:<port>]
288 > [bindmethod={simple|kerberos|sasl}]
291 > [authcid=<identity>]
292 > [authzid=<identity>]
293 > [credentials=<password>]
294 > [srvtab=<filename>]
296 This directive specifies a replication site for this database. The
297 {{EX:host=}} parameter specifies a host and optionally a port where
298 the slave slapd instance can be found. Either a domain name
299 or IP address may be used for <hostname>. If <port> is not
300 given, the standard LDAP port number (389) is used.
302 The {{EX:binddn=}} parameter gives the DN to bind as for updates to
303 the slave slapd. It should be a DN which has read/write
304 access to the slave slapd's database, typically given as a
305 {{EX:rootdn}} in the slave's config file. It must also match the
306 {{EX:updatedn}} directive in the slave slapd's config file. Since DNs are
307 likely to contain embedded spaces, the entire {{EX:"binddn=<DN>"}}
308 string should be enclosed in double quotes.
310 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:kerberos}} or {{EX:sasl}},
311 depending on whether simple password-based authentication or Kerberos
312 authentication or {{TERM:SASL}} authentication is to be used when connecting
315 Simple authentication should not be used unless adequate integrity
316 and privacy protections are in place (e.g. TLS or IPSEC). Simple
317 authentication requires specification of {{EX:binddn}} and
318 {{EX:credentials}} parameters.
320 Kerberos authentication is deprecated in favor of SASL authentication
321 mechanisms, in particular the {{EX:KERBEROS_V4}} and {{EX:GSSAPI}}
322 mechanisms. Kerberos authentication requires {{EX:binddn}} and
323 {{EX:srvtab}} parameters.
325 SASL authentication is generally recommended. SASL authentication
326 requires specification of a mechanism using the {{EX:saslmech}} parameter.
327 Depending on the mechanism, an authentication identity and/or
328 credentials can be specified using {{EX:authcid}} and {{EX:credentials}}
329 respectively. The {{EX:authzid}} parameter may be used to specify
330 an authorization identity.
332 See the chapter entitled {{SECT:Replication with slurpd}} for more
333 information on how to use this directive.
336 H4: replogfile <filename>
338 This directive specifies the name of the replication log file to
339 which slapd will log changes. The replication log is typically
340 written by slapd and read by slurpd. Normally, this directive is
341 only used if slurpd is being used to replicate the database.
342 However, you can also use it to generate a transaction log, if
343 slurpd is not running. In this case, you will need to periodically
344 truncate the file, since it will grow indefinitely otherwise.
346 See the chapter entitled {{SECT:Replication with slurpd}} for more
347 information on how to use this directive.
352 This directive specifies the DN that is not subject to
353 access control or administrative limit restrictions for
354 operations on this database. The DN need not refer to
355 an entry in this database or even in the directory. The
356 DN may refer to a SASL identity.
360 > rootdn "cn=Manager,dc=example,dc=com"
364 > rootdn "uid=root,cn=example.com,cn=digest-md5,cn=auth"
366 See the {{SECT:SASL Authentication}} section for information on
367 SASL authentication identities.
370 H4: rootpw <password>
372 This directive can be used to specifies a password for the DN for
373 the rootdn (when the rootdn is set to a DN within the database).
379 It is also permissible to provide hash of the password in RFC 2307
380 form. {{slappasswd}}(8) may be used to generate the password hash.
384 > rootpw {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN
386 The hash was generated using the command {{EX:slappasswd -s secret}}.
389 H4: suffix <dn suffix>
391 This directive specifies the DN suffix of queries that will be
392 passed to this backend database. Multiple suffix lines can be
393 given, and at least one is required for each database
398 > suffix "dc=example,dc=com"
400 Queries with a DN ending in "dc=example,dc=com"
401 will be passed to this backend.
403 Note: When the backend to pass a query to is selected, slapd
404 looks at the suffix line(s) in each database definition in the
405 order they appear in the file. Thus, if one database suffix is a
406 prefix of another, it must appear after it in the config file.
410 > syncrepl id=<replica ID>
411 > provider=ldap[s]://<hostname>[:port]
414 > [bindmethod=simple|sasl]
415 > [binddn=<simple DN>]
416 > [credentials=<simple passwd>]
417 > [saslmech=<SASL mech>]
418 > [secprops=<properties>]
420 > [authcId=<authentication ID>]
421 > [authzId=<authorization ID>]
422 > [searchbase=<base DN>]
423 > [filter=<filter str>]
424 > [attrs=<attr list>]
425 > [scope=sub|one|base]
426 > [schemachecking=on|off]
427 > [type=refreshOnly|refreshAndPersist]
428 > [interval=dd:hh:mm]
430 This directive specifies an LDAP Sync replication between this
431 database and the specified replication provider site. The id=
432 parameter identifies the LDAP Sync specification in the database.
433 The {{EX:provider=}} parameter specifies a replication provider site as
436 The LDAP Sync replication specification is based on the search
437 specification which defines the content of the replica. The replica
438 consists of the entries matching the search specification. As with
439 the normal searches, the search specification consists of
440 {{EX:searchbase}}, {{EX:scope}}, {{EX:filter}}, and EX:attrs}}
443 The LDAP Sync replication has two types of operating modes. In the
444 {{EX:refreshOnly}} mode, the next synchronization session is
445 rescheduled at the interval time after the current session finishes.
446 The default interval is set to one day. In the {{EX:refreshAndPersist}}
447 mode, the LDAP Sync search remains persistent in the provider LDAP
448 server. Further updates to the provider replica will generate
449 searchResultEntry to the consumer.
451 The schema checking can be enforced at the LDAP Sync consumer site
452 by turning on the {{EX:schemachecking}} parameter. The default is off.
454 The {{EX:binddn=}} parameter gives the DN for the LDAP Sync search
455 to bind as to the provider slapd. The content of the replica will
456 be subject to the access control privileges of the DN.
458 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}}, depending
459 on whether simple password-based authentication or SASL authentication
460 is to be used when connecting to the provider slapd.
462 Simple authentication should not be used unless adequate integrity
463 and data confidential protections are in place (e.g. TLS or IPSEC).
464 Simple authentication requires specification of {{EX:binddn}} and
465 {{EX:credentials}} parameters.
467 SASL authentication is generally recommended. SASL authentication
468 requires specification of a mechanism using the {{EX:mech}} parameter.
469 Depending on the mechanism, an authentication identity and/or
470 credentials can be specified using {{EX:authcid}} and {{EX:credentials}}
471 respectively. The {{EX:authzid}} parameter may be used to specify
472 a proxy authorization identity.
474 The LDAP Sync replication is supported in three native backends:
475 back-bdb, back-hdb, and back-ldbm.
477 See the {{SECT:LDAP Sync Replication}} chapter for more information
478 on how to use this directive.
483 This directive is only applicable in a slave slapd. It specifies
484 the DN allowed to make changes to the replica. This may be the DN
485 {{slurpd}}(8) binds as when making changes to the replica or the DN
486 associated with a SASL identity.
490 > updatedn "cn=Update Daemon,dc=example,dc=com"
494 > updatedn "uid=slurpd,cn=example.com,cn=digest-md5,cn=auth"
496 See the {{SECT:Replication with slurpd}} chapter for more information
497 on how to use this directive.
501 This directive is only applicable in a slave slapd. It
502 specifies the URL to return to clients which submit update
503 requests upon the replica.
504 If specified multiple times, each {{TERM:URL}} is provided.
508 > updateref ldap://master.example.net
511 H3: BDB Database Directives
513 Directives in this category only apply to a {{TERM:BDB}} database.
514 That is, they must follow a "database bdb" line and come before any
515 subsequent "backend" or "database" line. For a complete reference
516 of BDB configuration directives, see {{slapd-bdb}}(5).
518 H4: directory <directory>
520 This directive specifies the directory where the BDB files
521 containing the database and associated indices live.
525 > directory /usr/local/var/openldap-data
528 H3: LDBM Database Directives
530 Directives in this category only apply to a {{TERM:LDBM}} database.
531 That is, they must follow a "database ldbm" line and come before
532 any subsequent "backend" or "database" line. For a complete reference
533 of LDBM configuration directives, see {{slapd-ldbm}}(5).
535 H4: cachesize <integer>
537 This directive specifies the size in entries of the in-memory
538 cache maintained by the LDBM backend database instance.
545 H4: dbcachesize <integer>
547 This directive specifies the size in bytes of the in-memory cache
548 associated with each open index file. If not supported by the
549 underlying database method, this directive is ignored without
550 comment. Increasing this number uses more memory but can
551 cause a dramatic performance increase, especially during
552 modifies or when building indices.
561 This option, if present, disables database locking.
562 Enabling this option may improve performance at the expense
568 This option causes on-disk database contents to not be immediately
569 synchronized with in memory changes upon change. Enabling this option
570 may improve performance at the expense of data integrity.
573 H4: directory <directory>
575 This directive specifies the directory where the LDBM files
576 containing the database and associated indices live.
580 > directory /usr/local/var/openldap-data
583 H4: index {<attrlist> | default} [pres,eq,approx,sub,none]
585 This directive specifies the indices to maintain for the given
586 attribute. If only an {{EX:<attrlist>}} is given, the default
587 indices are maintained.
591 > index default pres,eq
593 > index cn,sn pres,eq,sub
594 > index objectClass eq
596 The first line sets the default set of indices to maintain to
597 present and equality. The second line causes the default (pres,eq)
598 set of indices to be maintained for the {{EX:uid}} attribute type.
599 The third line causes present, equality, and substring indices to
600 be maintained for {{EX:cn}} and {{EX:sn}} attribute types. The
601 fourth line causes an equality index for the {{EX:objectClass}}
604 By default, no indices are maintained. It is generally advised
605 that minimally an equality index upon objectClass be maintained.
607 > index objectClass eq
613 This directive specifies the file protection mode that newly
614 created database index files should have.
623 Access to slapd entries and attributes is controlled by the
624 access configuration file directive. The general form of an
627 > <access directive> ::= access to <what>
628 > [by <who> <access> <control>]+
630 > [dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
631 > [filter=<ldapfilter>] [attrs=<attrlist>]
632 > <basic-style> ::= regex | exact
633 > <scope-style> ::= base | one | subtree | children
634 > <attrlist> ::= <attr> [val[.<basic-style>]=<regex>] | <attr> , <attrlist>
635 > <attr> ::= <attrname> | entry | children
636 > <who> ::= * | [anonymous | users | self
637 > | dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
638 > [dnattr=<attrname>]
639 > [group[/<objectclass>[/<attrname>][.<basic-style>]]=<regex>]
640 > [peername[.<basic-style>]=<regex>]
641 > [sockname[.<basic-style>]=<regex>]
642 > [domain[.<basic-style>]=<regex>]
643 > [sockurl[.<basic-style>]=<regex>]
646 > <access> ::= [self]{<level>|<priv>}
647 > <level> ::= none | auth | compare | search | read | write
648 > <priv> ::= {=|+|-}{w|r|s|c|x}+
649 > <control> ::= [stop | continue | break]
651 where the <what> part selects the entries and/or attributes to which
652 the access applies, the {{EX:<who>}} part specifies which entities
653 are granted access, and the {{EX:<access>}} part specifies the
654 access granted. Multiple {{EX:<who> <access> <control>}} triplets
655 are supported, allowing many entities to be granted different access
656 to the same set of entries and attributes. Not all of these access
657 control options are described here; for more details see the
658 {{slapd.access}}(5) man page.
661 H3: What to control access to
663 The <what> part of an access specification determines the entries
664 and attributes to which the access control applies. Entries are
665 commonly selected in two ways: by DN and by filter. The following
666 qualifiers select entries by DN:
669 > by dn[.<basic-style>]=<regex>
670 > by dn.<scope-style>=<DN>
672 The first form is used to select all entries. The second form may
673 be used to select entries by matching a regular expression against
674 the target entry's {{normalized DN}}. (The second form is not
675 discussed further in this document.) The third form is used to
676 select entries which are within the requested scope of DN. The
677 <DN> is a string representation of the Distinguished Name, as
678 described in {{REF:RFC2253}}.
680 The scope can be either {{EX:base}}, {{EX:one}}, {{EX:subtree}},
681 or {{EX:children}}. Where {{EX:base}} matches only the entry with
682 provided DN, {{EX:one}} matches the entries whose parent is the
683 provided DN, {{EX:subtree}} matches all entries in the subtree whose
684 root is the provided DN, and {{EX:children}} matches all entries
685 under the DN (but not the entry named by the DN).
687 For example, if the directory contained entries named:
690 > 1: cn=Manager,o=suffix
691 > 2: ou=people,o=suffix
692 > 3: uid=kdz,ou=people,o=suffix
693 > 4: cn=addresses,uid=kdz,ou=people,o=suffix
694 > 5: uid=hyc,ou=people,o=suffix
697 . {{EX:dn.base="ou=people,o=suffix"}} match 2;
698 . {{EX:dn.one="ou=people,o=suffix"}} match 3, and 5;
699 . {{EX:dn.subtree="ou=people,o=suffix"}} match 2, 3, 4, and 5; and
700 . {{EX:dn.children="ou=people,o=suffix"}} match 3, 4, and 5.
703 Entries may also be selected using a filter:
705 > by filter=<ldap filter>
707 where <ldap filter> is a string representation of an LDAP
708 search filter, as described in {{REF:RFC2254}}. For example:
710 > by filter=(objectClass=person)
712 Note that entries may be selected by both DN and filter by
713 including both qualifiers in the <what> clause.
715 > by dn.one="ou=people,o=suffix" filter=(objectClass=person)
717 Attributes within an entry are selected by including a comma-separated
718 list of attribute names in the <what> selector:
720 > attrs=<attribute list>
722 A specific value of an attribute is selected by using a single
723 attribute name and also using a value selector:
725 > attrs=<attribute> val[.<style>]=<regex>
727 There are two special {{pseudo}} attributes {{EX:entry}} and
728 {{EX:children}}. To read (and hence return) a target entry, the
729 subject must have {{EX:read}} access to the target's {{entry}}
730 attribute. To add or delete an entry, the subject must have
731 {{EX:write}} access to the entry's {{EX:entry}} attribute AND must
732 have {{EX:write}} access to the entry's parent's {{EX:children}}
733 attribute. To rename an entry, the subject must have {{EX:write}}
734 access to entry's {{EX:entry}} attribute AND have {{EX:write}}
735 access to both the old parent's and new parent's {{EX:children}}
736 attributes. The complete examples at the end of this section should
737 help clear things up.
739 Lastly, there is a special entry selector {{EX:"*"}} that is used to
740 select any entry. It is used when no other {{EX:<what>}}
741 selector has been provided. It's equivalent to "{{EX:dn=.*}}"
744 H3: Who to grant access to
746 The <who> part identifies the entity or entities being granted
747 access. Note that access is granted to "entities" not "entries."
748 The following table summarizes entity specifiers:
750 !block table; align=Center; coltags="EX,N"; \
751 title="Table 5.3: Access Entity Specifiers"
753 *|All, including anonymous and authenticated users
754 anonymous|Anonymous (non-authenticated) users
755 users|Authenticated users
756 self|User associated with target entry
757 dn[.<basic-style>]=<regex>|Users matching a regular expression
758 dn.<scope-style>=<DN>|Users within scope of a DN
761 The DN specifier behaves much like <what> clause DN specifiers.
763 Other control factors are also supported. For example, a {{EX:<who>}}
764 can be restricted by an entry listed in a DN-valued attribute in
765 the entry to which the access applies:
767 > dnattr=<dn-valued attribute name>
769 The dnattr specification is used to give access to an entry
770 whose DN is listed in an attribute of the entry (e.g., give
771 access to a group entry to whoever is listed as the owner of
774 Some factors may not be appropriate in all environments (or any).
775 For example, the domain factor relies on IP to domain name lookups.
776 As these can easily spoofed, the domain factor should not be avoided.
779 H3: The access to grant
782 The kind of <access> granted can be one of the following:
785 !block table; colaligns="LRL"; coltags="EX,EX,N"; align=Center; \
786 title="Table 5.4: Access Levels"
787 Level Privileges Description
789 auth =x needed to bind
790 compare =cx needed to compare
791 search =scx needed to apply search filters
792 read =rscx needed to read search results
793 write =wrscx needed to modify/rename
796 Each level implies all lower levels of access. So, for
797 example, granting someone {{EX:write}} access to an entry also
798 grants them {{EX:read}}, {{EX:search}}, {{EX:compare}}, and
799 {{EX:auth}} access. However, one may use the privileges specifier
800 to grant specific permissions.
803 H3: Access Control Evaluation
805 When evaluating whether some requester should be given access to
806 an entry and/or attribute, slapd compares the entry and/or attribute
807 to the {{EX:<what>}} selectors given in the configuration file.
808 For each entry, access controls provided in the database which holds
809 the entry (or the first database if not held in any database) apply
810 first, followed by the global access directives. Within this
811 priority, access directives are examined in the order in which they
812 appear in the config file. Slapd stops with the first {{EX:<what>}}
813 selector that matches the entry and/or attribute. The corresponding
814 access directive is the one slapd will use to evaluate access.
816 Next, slapd compares the entity requesting access to the {{EX:<who>}}
817 selectors within the access directive selected above in the order
818 in which they appear. It stops with the first {{EX:<who>}} selector
819 that matches the requester. This determines the access the entity
820 requesting access has to the entry and/or attribute.
822 Finally, slapd compares the access granted in the selected
823 {{EX:<access>}} clause to the access requested by the client. If
824 it allows greater or equal access, access is granted. Otherwise,
827 The order of evaluation of access directives makes their placement
828 in the configuration file important. If one access directive is
829 more specific than another in terms of the entries it selects, it
830 should appear first in the config file. Similarly, if one {{EX:<who>}}
831 selector is more specific than another it should come first in the
832 access directive. The access control examples given below should
833 help make this clear.
837 H3: Access Control Examples
839 The access control facility described above is quite powerful.
840 This section shows some examples of its use. First, some
843 > access to * by * read
845 This access directive grants read access to everyone.
852 This directive allows the user to modify their entry, allows anonymous
853 to authentication against these entries, and allows all others to
854 read these entries. Note that only the first {{EX:by <who>}} clause
855 which matches applies. Hence, the anonymous users are granted
856 {{EX:auth}}, not {{EX:read}}. The last clause could just as well
857 have been "{{EX:by users read}}".
859 It is often desirable to restrict operations based upon the level
860 of protection in place. The following shows how security strength
861 factors (SSF) can be used.
864 > by ssf=128 self write
865 > by ssf=64 anonymous auth
866 > by ssf=64 users read
868 This directive allows users to modify their own entries if security
869 protections have of strength 128 or better have been established,
870 allows authentication access to anonymous users, and read access
871 when 64 or better security protections have been established. If
872 client has not establish sufficient security protections, the
873 implicit {{EX:by * none}} clause would be applied.
875 The following example shows the use of a style specifiers
876 to select the entries by DN in two access directives where
877 ordering is significant.
879 > access to dn.children="dc=example,dc=com"
881 > access to dn.children="dc=com"
884 Read access is granted to entries under the {{EX:dc=com}} subtree,
885 except for those entries under the {{EX:dc=example,dc=com}} subtree,
886 to which search access is granted. No access is granted to
887 {{EX:dc=com}} as neither access directive matches this DN. If the
888 order of these access directives was reversed, the trailing directive
889 would never be reached, since all entries under {{EX:dc=example,dc=com}}
890 are also under {{EX:dc=com}} entries.
892 Also note that if no {{EX:access to}} directive matches or no {{EX:by
893 <who>}} clause, {{B:access is denied}}. That is, every {{EX:access
894 to}} directive ends with an implicit {{EX:by * none}} clause and
895 every access list ends with an implicit {{EX:access to * by * none}}
898 The next example again shows the importance of ordering, both of
899 the access directives and the {{EX:by <who>}} clauses. It also
900 shows the use of an attribute selector to grant access to a specific
901 attribute and various {{EX:<who>}} selectors.
903 > access to dn.subtree="dc=example,dc=com" attr=homePhone
905 > by dn.children=dc=example,dc=com" search
906 > by peername=IP:10\..+ read
907 > access to dn.subtree="dc=example,dc=com"
909 > by dn.children="dc=example,dc=com" search
912 This example applies to entries in the "{{EX:dc=example,dc=com}}"
913 subtree. To all attributes except {{EX:homePhone}}, an entry can
914 write to itself, entries under {{EX:example.com}} entries can search
915 by them, anybody else has no access (implicit {{EX:by * none}})
916 excepting for authentication/authorization (which is always done
917 anonymously). The {{EX:homePhone}} attribute is writable by the
918 entry, searchable by entries under {{EX:example.com}}, readable by
919 clients connecting from network 10, and otherwise not readable
920 (implicit {{EX:by * none}}). All other access is denied by the
921 implicit {{EX:access to * by * none}}.
923 Sometimes it is useful to permit a particular DN to add or
924 remove itself from an attribute. For example, if you would like to
925 create a group and allow people to add and remove only
926 their own DN from the member attribute, you could accomplish
927 it with an access directive like this:
929 > access to attr=member,entry
930 > by dnattr=member selfwrite
932 The dnattr {{EX:<who>}} selector says that the access applies to
933 entries listed in the {{EX:member}} attribute. The {{EX:selfwrite}} access
934 selector says that such members can only add or delete their
935 own DN from the attribute, not other values. The addition of
936 the entry attribute is required because access to the entry is
937 required to access any of the entry's attributes.
940 For more details on how to use the {{EX:access}} directive,
941 consult the {{Advanced Access Control}} chapter.
945 H2: Configuration File Example
947 The following is an example configuration file, interspersed
948 with explanatory text. It defines two databases to handle
949 different parts of the {{TERM:X.500}} tree; both are {{TERM:BDB}}
950 database instances. The line numbers shown are provided for
951 reference only and are not included in the actual file. First, the
952 global configuration section:
954 E: 1. # example config file - global configuration section
955 E: 2. include /usr/local/etc/schema/core.schema
956 E: 3. referral ldap://root.openldap.org
957 E: 4. access to * by * read
959 Line 1 is a comment. Line 2 includes another config file
960 which contains {{core}} schema definitions.
961 The {{EX:referral}} directive on line 3
962 means that queries not local to one of the databases defined
963 below will be referred to the LDAP server running on the
964 standard port (389) at the host {{EX:root.openldap.org}}.
966 Line 4 is a global access control. It applies to all
967 entries (after any applicable database-specific access
970 The next section of the configuration file defines a BDB
971 backend that will handle queries for things in the
972 "dc=example,dc=com" portion of the tree. The
973 database is to be replicated to two slave slapds, one on
974 truelies, the other on judgmentday. Indices are to be
975 maintained for several attributes, and the {{EX:userPassword}}
976 attribute is to be protected from unauthorized access.
978 E: 5. # BDB definition for the example.com
980 E: 7. suffix "dc=example,dc=com"
981 E: 8. directory /usr/local/var/openldap-data
982 E: 9. rootdn "cn=Manager,dc=example,dc=com"
984 E: 11. # replication directives
985 E: 12. replogfile /usr/local/var/openldap/slapd.replog
986 E: 13. replica host=slave1.example.com:389
987 E: 14. binddn="cn=Replicator,dc=example,dc=com"
988 E: 15. bindmethod=simple credentials=secret
989 E: 16. replica host=slave2.example.com
990 E: 17. binddn="cn=Replicator,dc=example,dc=com"
991 E: 18. bindmethod=simple credentials=secret
992 E: 19. # indexed attribute definitions
993 E: 20. index uid pres,eq
994 E: 21. index cn,sn,uid pres,eq,approx,sub
995 E: 22. index objectClass eq
996 E: 23. # database access control definitions
997 E: 24. access to attr=userPassword
999 E: 26. by anonymous auth
1000 E: 27. by dn.base="cn=Admin,dc=example,dc=com" write
1003 E: 30. by self write
1004 E: 31. by dn.base="cn=Admin,dc=example,dc=com" write
1007 Line 5 is a comment. The start of the database definition is marked
1008 by the database keyword on line 6. Line 7 specifies the DN suffix
1009 for queries to pass to this database. Line 8 specifies the directory
1010 in which the database files will live.
1012 Lines 9 and 10 identify the database {{super-user}} entry and associated
1013 password. This entry is not subject to access control or size or
1014 time limit restrictions.
1016 Lines 11 through 18 are for replication. Line 12 specifies the
1017 replication log file (where changes to the database are logged -
1018 this file is written by slapd and read by slurpd). Lines 13 through
1019 15 specify the hostname and port for a replicated host, the DN to
1020 bind as when performing updates, the bind method (simple) and the
1021 credentials (password) for the binddn. Lines 16 through 18 specify
1022 a second replication site. See the {{SECT:Replication with slurpd}}
1023 chapter for more information on these directives.
1025 Lines 20 through 22 indicate the indices to maintain for various
1028 Lines 24 through 32 specify access control for entries in this
1029 database. As this is the first database, the controls also apply
1030 to entries not held in any database (such as the Root DSE). For
1031 all applicable entries, the {{EX:userPassword}} attribute is writable
1032 by the entry itself and by the "admin" entry. It may be used for
1033 authentication/authorization purposes, but is otherwise not readable.
1034 All other attributes are writable by the entry and the "admin"
1035 entry, but may be read by all users (authenticated or not).
1037 The next section of the example configuration file defines another
1038 BDB database. This one handles queries involving the
1039 {{EX:dc=example,dc=net}} subtree but is managed by the same entity
1040 as the first database. Note that without line 39, the read access
1041 would be allowed due to the global access rule at line 4.
1043 E: 33. # BDB definition for example.net
1045 E: 35. suffix "dc=example,dc=net"
1046 E: 36. directory /usr/local/var/openldap-data-net
1047 E: 37. rootdn "cn=Manager,dc=example,dc=com"
1048 E: 38. index objectClass eq
1049 E: 39. access to * by users read