]> git.sur5r.net Git - openldap/blob - doc/guide/admin/slapdconfig.sdf
happy new year
[openldap] / doc / guide / admin / slapdconfig.sdf
1 # $OpenLDAP$
2 # Copyright 1999-2007 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5 H1: The slapd Configuration File
6
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.
12
13 An alternate configuration file location can be specified via a command-line
14 option to {{slapd}}(8). This chapter describes the general format
15 of the {{slapd.conf}}(5) configuration file, followed by a detailed
16 description of commonly used config file directives.
17
18
19 H2: Configuration File Format
20
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.
28
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
32 comment).
33
34 The general format of slapd.conf is as follows:
35
36 >       # global configuration directives
37 >       <global config directives>
38 >
39 >       # backend definition
40 >       backend <typeA>
41 >       <backend-specific directives>
42 >
43 >       # first database definition & config directives
44 >       database <typeA>
45 >       <database-specific directives>
46 >
47 >       # second database definition & config directives
48 >       database <typeB>
49 >       <database-specific directives>
50 >
51 >       # second database definition & config directives
52 >       database <typeA>
53 >       <database-specific directives>
54 >
55 >       # subsequent backend & database definitions & config directives
56 >       ...
57
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:\}}'.
63
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.
69
70
71 H2: Configuration File Directives
72
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
78 its use.
79
80
81
82 H3: Global Directives
83
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:<>}}.
88
89
90 H4: access to <what> [ by <who> [<accesslevel>] [<control>] ]+
91
92 This directive grants access (specified by <accesslevel>) to a set
93 of entries and/or attributes (specified by <what>) by one or more
94 requesters (specified by <who>).  See the {{SECT:The access
95 Configuration Directive}} section of this chapter for a summary of
96 basic usage.
97
98 !if 0
99 More details discussion of this directive can be found in the
100 {{SECT:Advanced Access Control}} chapter.
101 !endif
102
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.
106
107
108 H4: attributetype <{{REF:RFC4512}} Attribute Type Description>
109
110 This directive defines an attribute type.
111 Please see the {{SECT:Schema Specification}} chapter
112 for information regarding how to use this directive.
113
114 H4: idletimeout <integer>
115
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.
119
120
121 H4: include <filename>
122
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.
128
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.
132
133 H4: loglevel <integer>
134
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:
143
144 !block table; colaligns="RL"; align=Center; \
145         title="Table 6.1: Debugging Levels"
146 Level   Description
147 -1      enable all debugging
148 0       no 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
161 !endblock
162
163 \Example:
164
165 E: loglevel -1
166
167 This will cause lots and lots of debugging information to be
168 logged.
169
170 \Default:
171
172 E: loglevel 256
173
174
175 H4: objectclass <{{REF:RFC4512}} Object Class Description>
176
177 This directive defines an object class.
178 Please see the {{SECT:Schema Specification}} chapter for
179 information regarding how to use this directive.
180
181
182 H4: referral <URI>
183
184 This directive specifies the referral to pass back when slapd
185 cannot find a local database to handle a request.
186
187 \Example:
188
189 >       referral ldap://root.openldap.org
190
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.
196
197
198 H4: sizelimit <integer>
199
200 This directive specifies the maximum number of entries to return
201 from a search operation.
202
203 \Default:
204
205 >       sizelimit 500
206
207
208 H4: timelimit <integer>
209
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.
214
215 \Default:
216
217 >       timelimit 3600
218
219
220 H3: General Backend Directives
221
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.
227
228 H4: backend <type>
229
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 6.2.
233
234 !block table; align=Center; coltags="EX,N"; \
235         title="Table 5.2: Database Backends"
236 Types   Description
237 bdb     Berkeley DB transactional backend
238 dnssrv  DNS SRV backend
239 hdb     Hierarchical variant of bdb backend
240 ldap    Lightweight Directory Access Protocol (Proxy) 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
247 !endblock
248
249 \Example:
250
251 >       backend bdb
252
253 This marks the beginning of a new {{TERM:BDB}} backend
254 definition.
255
256
257 H3: General Database Directives
258
259 Directives in this section apply only to the database in which
260 they are defined. They are supported by every type of database.
261
262 H4: database <type>
263
264 This directive marks the beginning of a database instance
265 declaration.
266 {{EX:<type>}} should be one of the
267 supported backend types listed in Table 6.2.
268
269 \Example:
270
271 >       database bdb
272
273 This marks the beginning of a new {{TERM:BDB}} database instance
274 declaration.
275
276
277 H4: readonly { on | off }
278
279 This directive puts the database into "read-only" mode. Any
280 attempts to modify the database will return an "unwilling to
281 perform" error.
282
283 \Default:
284
285 >       readonly off
286
287 H4: replica
288
289 >       replica uri=ldap[s]://<hostname>[:<port>] | host=<hostname>[:<port>]
290 >               [bindmethod={simple|sasl}]
291 >               ["binddn=<DN>"]
292 >               [saslmech=<mech>]
293 >               [authcid=<identity>]
294 >               [authzid=<identity>]
295 >               [credentials=<password>]
296
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.
302
303 {{EX:host}} is deprecated in favor of the {{EX:uri}} parameter.
304
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}}.
308
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
316 quotes.
317
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.
321
322 Simple authentication should not be used unless adequate data
323 integrity and confidentiality protections are in place (e.g. TLS
324 or {{TERM:IPsec}}).  Simple authentication requires specification of
325 {{EX:binddn}} and {{EX:credentials}} parameters.
326
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.
333
334 See the chapter entitled {{SECT:Replication with slurpd}} for more
335 information on how to use this directive.
336
337 H4: replogfile <filename>
338
339 This directive specifies the name of the replication log file to
340 which slapd will log changes. The replication log is typically
341 written by slapd and read by slurpd. Normally, this directive is
342 only used if slurpd is being used to replicate the database.
343 However, you can also use it to generate a transaction log, if
344 slurpd is not running. In this case, you will need to periodically
345 truncate the file, since it will grow indefinitely otherwise.
346
347 See the chapter entitled {{SECT:Replication with slurpd}} for more
348 information on how to use this directive.
349
350
351 H4: rootdn <DN>
352
353 This directive specifies the DN that is not subject to
354 access control or administrative limit restrictions for
355 operations on this database.  The DN need not refer to
356 an entry in this database or even in the directory. The
357 DN may refer to a SASL identity.
358
359 Entry-based Example:
360
361 >       rootdn "cn=Manager,dc=example,dc=com"
362
363 SASL-based Example:
364
365 >       rootdn "uid=root,cn=example.com,cn=digest-md5,cn=auth"
366
367 See the {{SECT:SASL Authentication}} section for information on
368 SASL authentication identities.
369
370
371 H4: rootpw <password>
372
373 This directive can be used to specifies a password for the DN for
374 the rootdn (when the rootdn is set to a DN within the database).
375
376 \Example:
377
378 >       rootpw secret
379
380 It is also permissible to provide hash of the password in {{REF:RFC2307}}
381 form.  {{slappasswd}}(8) may be used to generate the password hash.
382
383 \Example:
384
385 >       rootpw {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN
386
387 The hash was generated using the command {{EX:slappasswd -s secret}}.
388
389
390 H4: suffix <dn suffix>
391
392 This directive specifies the DN suffix of queries that will be
393 passed to this backend database. Multiple suffix lines can be
394 given, and at least one is required for each database
395 definition.
396
397 \Example:
398
399 >       suffix "dc=example,dc=com"
400
401 Queries with a DN ending in "dc=example,dc=com"
402 will be passed to this backend.
403
404 Note: When the backend to pass a query to is selected, slapd
405 looks at the suffix line(s) in each database definition in the
406 order they appear in the file. Thus, if one database suffix is a
407 prefix of another, it must appear after it in the config file.
408
409
410 H4: syncrepl
411
412 >       syncrepl rid=<replica ID>
413 >               provider=ldap[s]://<hostname>[:port]
414 >               [type=refreshOnly|refreshAndPersist]
415 >               [interval=dd:hh:mm:ss]
416 >               [retry=[<retry interval> <# of retries>]+]
417 >               searchbase=<base DN>
418 >               [filter=<filter str>]
419 >               [scope=sub|one|base]
420 >               [attrs=<attr list>]
421 >               [attrsonly]
422 >               [sizelimit=<limit>]
423 >               [timelimit=<limit>]
424 >               [schemachecking=on|off]
425 >               [bindmethod=simple|sasl]
426 >               [binddn=<DN>]
427 >               [saslmech=<mech>]
428 >               [authcid=<identity>]
429 >               [authzid=<identity>]
430 >               [credentials=<passwd>]
431 >               [realm=<realm>]
432 >               [secprops=<properties>]
433
434
435 This directive specifies the current database as a replica of the
436 master content by establishing the current {{slapd}}(8) as a
437 replication consumer site running a syncrepl replication engine.
438 The master database is located at the replication provider site
439 specified by the {{EX:provider}} parameter. The replica database is
440 kept up-to-date with the master content using the LDAP Content
441 Synchronization protocol. See {{REF:RFC4533}}
442 for more information on the protocol.
443
444 The {{EX:rid}} parameter is used for identification of the current
445 {{EX:syncrepl}} directive within the replication consumer server,
446 where {{EX:<replica ID>}} uniquely identifies the syncrepl specification
447 described by the current {{EX:syncrepl}} directive. {{EX:<replica ID>}}
448 is non-negative and is no more than three decimal digits in length.
449
450 The {{EX:provider}} parameter specifies the replication provider site
451 containing the master content as an LDAP URI. The {{EX:provider}}
452 parameter specifies a scheme, a host and optionally a port where the
453 provider slapd instance can be found. Either a domain name or IP
454 address may be used for <hostname>. Examples are
455 {{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}.
456 If <port> is not given, the standard LDAP port number (389 or 636) is used.
457 Note that the syncrepl uses a consumer-initiated protocol, and hence its
458 specification is located at the consumer site, whereas the {{EX:replica}}
459 specification is located at the provider site. {{EX:syncrepl}} and
460 {{EX:replica}} directives define two independent replication
461 mechanisms. They do not represent the replication peers of each other.
462
463 The content of the syncrepl replica is defined using a search
464 specification as its result set. The consumer slapd will
465 send search requests to the provider slapd according to the search
466 specification. The search specification includes {{EX:searchbase}},
467 {{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:attrsonly}},
468 {{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal
469 search specification. The {{EX:searchbase}} parameter has no
470 default value and must always be specified. The {{EX:scope}} defaults
471 to {{EX:sub}}, the {{EX:filter}} defaults to {{EX:(objectclass=*)}},
472 {{EX:attrs}} defaults to {{EX:"*,+"}} to replicate all user and operational
473 attributes, and {{EX:attrsonly}} is unset by default. Both {{EX:sizelimit}}
474 and {{EX:timelimit}} default to "unlimited", and only integers
475 or "unlimited" may be specified.
476
477 The LDAP Content Synchronization protocol has two operation
478 types: {{EX:refreshOnly}} and {{EX:refreshAndPersist}}.
479 The operation type is specified by the {{EX:type}} parameter.
480 In the {{EX:refreshOnly}} operation, the next synchronization search operation
481 is periodically rescheduled at an interval time after each
482 synchronization operation finishes. The interval is specified
483 by the {{EX:interval}} parameter. It is set to one day by default.
484 In the {{EX:refreshAndPersist}} operation, a synchronization search
485 remains persistent in the provider slapd. Further updates to the
486 master replica will generate {{EX:searchResultEntry}} to the consumer slapd
487 as the search responses to the persistent synchronization search.
488
489 If an error occurs during replication, the consumer will attempt to reconnect
490 according to the retry parameter which is a list of the <retry interval>
491 and <# of retries> pairs. For example, retry="60 10 300 3" lets the consumer
492 retry every 60 seconds for the first 10 times and then retry every 300 seconds
493 for the next three times before stop retrying. + in <#  of retries> means
494 indefinite number of retries until success.
495
496 The schema checking can be enforced at the LDAP Sync consumer site
497 by turning on the {{EX:schemachecking}} parameter.
498 If it is turned on, every replicated entry will be checked for its
499 schema as the entry is stored into the replica content.
500 Every entry in the replica should contain those attributes
501 required by the schema definition.
502 If it is turned off, entries will be stored without checking
503 schema conformance. The default is off.
504
505 The {{EX:binddn}} parameter gives the DN to bind as for the
506 syncrepl searches to the provider slapd. It should be a DN
507 which has read access to the replication content in the
508 master database. 
509
510 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
511 depending on whether simple password-based authentication or
512 {{TERM:SASL}} authentication is to be used when connecting
513 to the provider slapd.
514
515 Simple authentication should not be used unless adequate data
516 integrity and confidentiality protections are in place (e.g. TLS
517 or IPsec). Simple authentication requires specification of {{EX:binddn}}
518 and {{EX:credentials}} parameters.
519
520 SASL authentication is generally recommended.  SASL authentication
521 requires specification of a mechanism using the {{EX:saslmech}} parameter.
522 Depending on the mechanism, an authentication identity and/or
523 credentials can be specified using {{EX:authcid}} and {{EX:credentials}},
524 respectively.  The {{EX:authzid}} parameter may be used to specify
525 an authorization identity.
526
527 The {{EX:realm}} parameter specifies a realm which a certain
528 mechanisms authenticate the identity within. The {{EX:secprops}}
529 parameter specifies Cyrus SASL security properties.
530
531 The syncrepl replication mechanism is supported by the two primary
532 database backends: back-bdb and back-hdb.
533
534 See the {{SECT:LDAP Sync Replication}} chapter of the admin guide
535 for more information on how to use this directive.
536
537
538 H4: updatedn <DN>
539
540 This directive is only applicable in a {{slave}} (or {{shadow}})
541 {{slapd(8)}} instance.  It specifies the DN allowed to make changes to
542 the replica.  This may be the DN
543 {{slurpd}}(8) binds as when making changes to the replica or the DN
544 associated with a SASL identity.
545
546
547 Entry-based Example:
548
549 >       updatedn "cn=Update Daemon,dc=example,dc=com"
550
551 SASL-based Example:
552
553 >       updatedn "uid=slurpd,cn=example.com,cn=digest-md5,cn=auth"
554
555 See the {{SECT:Replication with slurpd}} chapter for more information
556 on how to use this directive.
557
558 H4: updateref <URL>
559
560 This directive is only applicable in a {{slave}} (or {{shadow}})
561 {{slapd}}(8) instance. It
562 specifies the URL to return to clients which submit update
563 requests upon the replica.
564 If specified multiple times, each {{TERM:URL}} is provided.
565
566 \Example:
567
568 >       updateref       ldap://master.example.net
569
570
571 H3: BDB and HDB Database Directives
572
573 Directives in this category only apply to both the {{TERM:BDB}}
574 and the {{TERM:HDB}} database.
575 That is, they must follow a "database bdb" or "database hdb" line
576 and come before any
577 subsequent "backend" or "database" line.  For a complete reference
578 of BDB/HDB configuration directives, see {{slapd-bdb}}(5).
579
580
581 H4: directory <directory>
582
583 This directive specifies the directory where the BDB files
584 containing the database and associated indices live.
585
586 \Default:
587
588 >       directory /usr/local/var/openldap-data
589
590
591 H2: The access Configuration Directive
592
593 Access to entries and attributes is controlled by the
594 access configuration file directive. The general form of an
595 access line is:
596
597 >       <access directive> ::= access to <what>
598 >               [by <who> [<access>] [<control>] ]+
599 >       <what> ::= * |
600 >               [dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
601 >               [filter=<ldapfilter>] [attrs=<attrlist>]
602 >       <basic-style> ::= regex | exact
603 >       <scope-style> ::= base | one | subtree | children
604 >       <attrlist> ::= <attr> [val[.<basic-style>]=<regex>] | <attr> , <attrlist>
605 >       <attr> ::= <attrname> | entry | children
606 >       <who> ::= * | [anonymous | users | self
607 >                       | dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>] 
608 >               [dnattr=<attrname>]
609 >               [group[/<objectclass>[/<attrname>][.<basic-style>]]=<regex>]
610 >               [peername[.<basic-style>]=<regex>]
611 >               [sockname[.<basic-style>]=<regex>]
612 >               [domain[.<basic-style>]=<regex>]
613 >               [sockurl[.<basic-style>]=<regex>]
614 >               [set=<setspec>]
615 >               [aci=<attrname>]
616 >       <access> ::= [self]{<level>|<priv>}
617 >       <level> ::= none | disclose | auth | compare | search | read | write | manage
618 >       <priv> ::= {=|+|-}{m|w|r|s|c|x|d|0}+
619 >       <control> ::= [stop | continue | break]
620
621 where the <what> part selects the entries and/or attributes to which
622 the access applies, the {{EX:<who>}} part specifies which entities
623 are granted access, and the {{EX:<access>}} part specifies the
624 access granted. Multiple {{EX:<who> <access> <control>}} triplets
625 are supported, allowing many entities to be granted different access
626 to the same set of entries and attributes. Not all of these access
627 control options are described here; for more details see the
628 {{slapd.access}}(5) man page.
629
630
631 H3: What to control access to
632
633 The <what> part of an access specification determines the entries
634 and attributes to which the access control applies.  Entries are
635 commonly selected in two ways: by DN and by filter.  The following
636 qualifiers select entries by DN:
637
638 >       to *
639 >       to dn[.<basic-style>]=<regex>
640 >       to dn.<scope-style>=<DN>
641
642 The first form is used to select all entries.  The second form may
643 be used to select entries by matching a regular expression against
644 the target entry's {{normalized DN}}.   (The second form is not
645 discussed further in this document.)  The third form is used to
646 select entries which are within the requested scope of DN.  The
647 <DN> is a string representation of the Distinguished Name, as
648 described in {{REF:RFC4514}}.
649
650 The scope can be either {{EX:base}}, {{EX:one}}, {{EX:subtree}},
651 or {{EX:children}}.  Where {{EX:base}} matches only the entry with
652 provided DN, {{EX:one}} matches the entries whose parent is the
653 provided DN, {{EX:subtree}} matches all entries in the subtree whose
654 root is the provided DN, and {{EX:children}} matches all entries
655 under the DN (but not the entry named by the DN).
656
657 For example, if the directory contained entries named:
658
659 >       0: o=suffix
660 >       1: cn=Manager,o=suffix
661 >       2: ou=people,o=suffix
662 >       3: uid=kdz,ou=people,o=suffix
663 >       4: cn=addresses,uid=kdz,ou=people,o=suffix
664 >       5: uid=hyc,ou=people,o=suffix
665
666 \Then:
667 . {{EX:dn.base="ou=people,o=suffix"}} match 2;
668 . {{EX:dn.one="ou=people,o=suffix"}} match 3, and 5;
669 . {{EX:dn.subtree="ou=people,o=suffix"}} match 2, 3, 4, and 5; and
670 . {{EX:dn.children="ou=people,o=suffix"}} match 3, 4, and 5.
671
672
673 Entries may also be selected using a filter:
674
675 >       to filter=<ldap filter>
676
677 where <ldap filter> is a string representation of an LDAP
678 search filter, as described in {{REF:RFC4515}}.  For example:
679
680 >       to filter=(objectClass=person)
681
682 Note that entries may be selected by both DN and filter by
683 including both qualifiers in the <what> clause.
684
685 >       to dn.one="ou=people,o=suffix" filter=(objectClass=person)
686
687 Attributes within an entry are selected by including a comma-separated
688 list of attribute names in the <what> selector:
689
690 >       attrs=<attribute list>
691
692 A specific value of an attribute is selected by using a single
693 attribute name and also using a value selector:
694
695 >       attrs=<attribute> val[.<style>]=<regex>
696
697 There are two special {{pseudo}} attributes {{EX:entry}} and
698 {{EX:children}}.  To read (and hence return) a target entry, the
699 subject must have {{EX:read}} access to the target's {{entry}}
700 attribute.  To add or delete an entry, the subject must have
701 {{EX:write}} access to the entry's {{EX:entry}} attribute AND must
702 have {{EX:write}} access to the entry's parent's {{EX:children}}
703 attribute.  To rename an entry, the subject must have {{EX:write}}
704 access to entry's {{EX:entry}} attribute AND have {{EX:write}}
705 access to both the old parent's and new parent's {{EX:children}}
706 attributes.  The complete examples at the end of this section should
707 help clear things up.
708
709 Lastly, there is a special entry selector {{EX:"*"}} that is used to
710 select any entry.  It is used when no other {{EX:<what>}}
711 selector has been provided.  It's equivalent to "{{EX:dn=.*}}"
712
713
714 H3: Who to grant access to
715
716 The <who> part identifies the entity or entities being granted
717 access. Note that access is granted to "entities" not "entries."
718 The following table summarizes entity specifiers:
719
720 !block table; align=Center; coltags="EX,N"; \
721         title="Table 6.3: Access Entity Specifiers"
722 Specifier|Entities
723 *|All, including anonymous and authenticated users
724 anonymous|Anonymous (non-authenticated) users
725 users|Authenticated users
726 self|User associated with target entry
727 dn[.<basic-style>]=<regex>|Users matching a regular expression
728 dn.<scope-style>=<DN>|Users within scope of a DN
729 !endblock
730
731 The DN specifier behaves much like <what> clause DN specifiers.
732
733 Other control factors are also supported.  For example, a {{EX:<who>}}
734 can be restricted by an entry listed in a DN-valued attribute in
735 the entry to which the access applies:
736
737 >       dnattr=<dn-valued attribute name>
738
739 The dnattr specification is used to give access to an entry
740 whose DN is listed in an attribute of the entry (e.g., give
741 access to a group entry to whoever is listed as the owner of
742 the group entry).
743
744 Some factors may not be appropriate in all environments (or any).
745 For example, the domain factor relies on IP to domain name lookups.
746 As these can easily spoofed, the domain factor should not be avoided.
747
748
749 H3: The access to grant
750
751 The kind of <access> granted can be one of the following:
752
753 !block table; colaligns="LRL"; coltags="EX,EX,N"; align=Center; \
754         title="Table 6.4: Access Levels"
755 Level           Privileges      Description
756 none            =0                      no access
757 disclose        =d                      needed for information disclosure on error
758 auth            =dx                     needed to authenticate (bind)
759 compare         =cdx            needed to compare
760 search          =scdx           needed to apply search filters
761 read            =rscdx          needed to read search results
762 write           =wrscdx         needed to modify/rename
763 manage          =mwrscdx        needed to manage
764 !endblock
765
766 Each level implies all lower levels of access. So, for example,
767 granting someone {{EX:write}} access to an entry also grants them
768 {{EX:read}}, {{EX:search}}, {{EX:compare}}, {{EX:auth}} and
769 {{EX:disclose}} access.  However, one may use the privileges specifier
770 to grant specific permissions.
771
772
773 H3: Access Control Evaluation
774
775 When evaluating whether some requester should be given access to
776 an entry and/or attribute, slapd compares the entry and/or attribute
777 to the {{EX:<what>}} selectors given in the configuration file.
778 For each entry, access controls provided in the database which holds
779 the entry (or the first database if not held in any database) apply
780 first, followed by the global access directives.  Within this
781 priority, access directives are examined in the order in which they
782 appear in the config file.  Slapd stops with the first {{EX:<what>}}
783 selector that matches the entry and/or attribute. The corresponding
784 access directive is the one slapd will use to evaluate access.
785
786 Next, slapd compares the entity requesting access to the {{EX:<who>}}
787 selectors within the access directive selected above in the order
788 in which they appear. It stops with the first {{EX:<who>}} selector
789 that matches the requester. This determines the access the entity
790 requesting access has to the entry and/or attribute.
791
792 Finally, slapd compares the access granted in the selected
793 {{EX:<access>}} clause to the access requested by the client. If
794 it allows greater or equal access, access is granted. Otherwise,
795 access is denied.
796
797 The order of evaluation of access directives makes their placement
798 in the configuration file important. If one access directive is
799 more specific than another in terms of the entries it selects, it
800 should appear first in the config file. Similarly, if one {{EX:<who>}}
801 selector is more specific than another it should come first in the
802 access directive. The access control examples given below should
803 help make this clear.
804
805
806
807 H3: Access Control Examples
808
809 The access control facility described above is quite powerful.  This
810 section shows some examples of its use for descriptive purposes.
811
812 A simple example:
813
814 >       access to * by * read
815
816 This access directive grants read access to everyone.
817
818 >       access to *
819 >               by self write
820 >               by anonymous auth
821 >               by * read
822
823 This directive allows the user to modify their entry, allows anonymous
824 to authentication against these entries, and allows all others to
825 read these entries.  Note that only the first {{EX:by <who>}} clause
826 which matches applies.  Hence, the anonymous users are granted
827 {{EX:auth}}, not {{EX:read}}.  The last clause could just as well
828 have been "{{EX:by users read}}".
829
830 It is often desirable to restrict operations based upon the level
831 of protection in place.  The following shows how security strength
832 factors (SSF) can be used.
833
834 >       access to *
835 >               by ssf=128 self write
836 >               by ssf=64 anonymous auth
837 >               by ssf=64 users read
838
839 This directive allows users to modify their own entries if security
840 protections have of strength 128 or better have been established,
841 allows authentication access to anonymous users, and read access
842 when 64 or better security protections have been established.  If
843 client has not establish sufficient security protections, the
844 implicit {{EX:by * none}} clause would be applied.
845
846 The following example shows the use of a style specifiers to select
847 the entries by DN in two access directives where ordering is
848 significant.
849
850 >       access to dn.children="dc=example,dc=com"
851 >               by * search
852 >       access to dn.children="dc=com"
853 >               by * read
854
855 Read access is granted to entries under the {{EX:dc=com}} subtree,
856 except for those entries under the {{EX:dc=example,dc=com}} subtree,
857 to which search access is granted.  No access is granted to
858 {{EX:dc=com}} as neither access directive matches this DN.  If the
859 order of these access directives was reversed, the trailing directive
860 would never be reached, since all entries under {{EX:dc=example,dc=com}}
861 are also under {{EX:dc=com}} entries.
862
863 Also note that if no {{EX:access to}} directive matches or no {{EX:by
864 <who>}} clause, {{B:access is denied}}.  That is, every {{EX:access
865 to}} directive ends with an implicit {{EX:by * none}} clause and
866 every access list ends with an implicit {{EX:access to * by * none}}
867 directive.
868
869 The next example again shows the importance of ordering, both of
870 the access directives and the {{EX:by <who>}} clauses.  It also
871 shows the use of an attribute selector to grant access to a specific
872 attribute and various {{EX:<who>}} selectors.
873
874 >       access to dn.subtree="dc=example,dc=com" attr=homePhone
875 >               by self write
876 >               by dn.children="dc=example,dc=com" search
877 >               by peername.regex=IP:10\..+ read
878 >       access to dn.subtree="dc=example,dc=com"
879 >               by self write
880 >               by dn.children="dc=example,dc=com" search
881 >               by anonymous auth
882
883 This example applies to entries in the "{{EX:dc=example,dc=com}}"
884 subtree. To all attributes except {{EX:homePhone}}, an entry can
885 write to itself, entries under {{EX:example.com}} entries can search
886 by them, anybody else has no access (implicit {{EX:by * none}})
887 excepting for authentication/authorization (which is always done
888 anonymously).  The {{EX:homePhone}} attribute is writable by the
889 entry, searchable by entries under {{EX:example.com}}, readable by
890 clients connecting from network 10, and otherwise not readable
891 (implicit {{EX:by * none}}).  All other access is denied by the
892 implicit {{EX:access to * by * none}}.
893
894 Sometimes it is useful to permit a particular DN to add or
895 remove itself from an attribute. For example, if you would like to
896 create a group and allow people to add and remove only
897 their own DN from the member attribute, you could accomplish
898 it with an access directive like this:
899
900 >       access to attr=member,entry
901 >               by dnattr=member selfwrite
902
903 The dnattr {{EX:<who>}} selector says that the access applies to
904 entries listed in the {{EX:member}} attribute. The {{EX:selfwrite}} access
905 selector says that such members can only add or delete their
906 own DN from the attribute, not other values. The addition of
907 the entry attribute is required because access to the entry is
908 required to access any of the entry's attributes.
909
910 !if 0
911 For more details on how to use the {{EX:access}} directive,
912 consult the {{Advanced Access Control}} chapter.
913 !endif
914
915
916 H2: Configuration File Example
917
918 The following is an example configuration file, interspersed
919 with explanatory text. It defines two databases to handle
920 different parts of the {{TERM:X.500}} tree; both are {{TERM:BDB}}
921 database instances. The line numbers shown are provided for
922 reference only and are not included in the actual file. First, the
923 global configuration section:
924
925 E:  1.  # example config file - global configuration section
926 E:  2.  include /usr/local/etc/schema/core.schema
927 E:  3.  referral ldap://root.openldap.org
928 E:  4.  access to * by * read
929  
930 Line 1 is a comment. Line 2 includes another config file
931 which contains {{core}} schema definitions.
932 The {{EX:referral}} directive on line 3
933 means that queries not local to one of the databases defined
934 below will be referred to the LDAP server running on the
935 standard port (389) at the host {{EX:root.openldap.org}}.
936
937 Line 4 is a global access control.  It applies to all
938 entries (after any applicable database-specific access
939 controls).
940
941 The next section of the configuration file defines a BDB
942 backend that will handle queries for things in the
943 "dc=example,dc=com" portion of the tree. The
944 database is to be replicated to two slave slapds, one on
945 truelies, the other on judgmentday. Indices are to be
946 maintained for several attributes, and the {{EX:userPassword}}
947 attribute is to be protected from unauthorized access.
948
949 E:  5.  # BDB definition for the example.com
950 E:  6.  database bdb
951 E:  7.  suffix "dc=example,dc=com"
952 E:  8.  directory /usr/local/var/openldap-data
953 E:  9.  rootdn "cn=Manager,dc=example,dc=com"
954 E: 10.  rootpw secret
955 E: 11.  # replication directives
956 E: 12.  replogfile /usr/local/var/openldap/slapd.replog
957 E: 13.  replica uri=ldap://slave1.example.com:389
958 E: 14.          binddn="cn=Replicator,dc=example,dc=com"
959 E: 15.          bindmethod=simple credentials=secret
960 E: 16.  replica uri=ldaps://slave2.example.com:636
961 E: 17.          binddn="cn=Replicator,dc=example,dc=com"
962 E: 18.          bindmethod=simple credentials=secret
963 E: 19.  # indexed attribute definitions
964 E: 20.  index uid pres,eq
965 E: 21.  index cn,sn,uid pres,eq,approx,sub
966 E: 22.  index objectClass eq
967 E: 23.  # database access control definitions
968 E: 24.  access to attr=userPassword
969 E: 25.          by self write
970 E: 26.          by anonymous auth
971 E: 27.          by dn.base="cn=Admin,dc=example,dc=com" write
972 E: 28.          by * none
973 E: 29.  access to *
974 E: 30.          by self write
975 E: 31.          by dn.base="cn=Admin,dc=example,dc=com" write
976 E: 32.          by * read
977
978 Line 5 is a comment. The start of the database definition is marked
979 by the database keyword on line 6. Line 7 specifies the DN suffix
980 for queries to pass to this database. Line 8 specifies the directory
981 in which the database files will live.
982
983 Lines 9 and 10 identify the database {{super-user}} entry and associated
984 password. This entry is not subject to access control or size or
985 time limit restrictions.
986
987 Lines 11 through 18 are for replication. Line 12 specifies the
988 replication log file (where changes to the database are logged -
989 this file is written by slapd and read by slurpd). Lines 13 through
990 15 specify the hostname and port for a replicated host, the DN to
991 bind as when performing updates, the bind method (simple) and the
992 credentials (password) for the binddn. Lines 16 through 18 specify
993 a second replication site.  See the {{SECT:Replication with slurpd}}
994 chapter for more information on these directives.
995
996 Lines 20 through 22 indicate the indices to maintain for various
997 attributes.
998
999 Lines 24 through 32 specify access control for entries in this
1000 database.  As this is the first database, the controls also apply
1001 to entries not held in any database (such as the Root DSE).  For
1002 all applicable entries, the {{EX:userPassword}} attribute is writable
1003 by the entry itself and by the "admin" entry.  It may be used for
1004 authentication/authorization purposes, but is otherwise not readable.
1005 All other attributes are writable by the entry and the "admin"
1006 entry, but may be read by all users (authenticated or not).
1007
1008 The next section of the example configuration file defines another
1009 BDB database. This one handles queries involving the
1010 {{EX:dc=example,dc=net}} subtree but is managed by the same entity
1011 as the first database.  Note that without line 39, the read access
1012 would be allowed due to the global access rule at line 4.
1013
1014 E: 33.  # BDB definition for example.net
1015 E: 34.  database bdb
1016 E: 35.  suffix "dc=example,dc=net"
1017 E: 36.  directory /usr/local/var/openldap-data-net
1018 E: 37.  rootdn "cn=Manager,dc=example,dc=com"
1019 E: 38.  index objectClass eq
1020 E: 39.  access to * by users read