]> git.sur5r.net Git - openldap/blob - doc/guide/admin/slapdconf2.sdf
Preliminary slapd.d info, very incomplete
[openldap] / doc / guide / admin / slapdconf2.sdf
1 # $OpenLDAP$
2 # Copyright 2005, The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5 H1: Configuring slapd
6
7 Once the software has been built and installed, you are ready
8 to configure {{slapd}}(8) for use at your site. Unlike previous
9 OpenLDAP releases, the slapd runtime configuration in 2.3 is
10 fully LDAP-enabled and can be managed using the standard LDAP
11 operations with data in LDIF. The LDAP configuration engine
12 allows all of slapd's configuration options to be changed on the fly,
13 generally without requiring a server restart for the changes
14 to take effect. The old style {{slapd.conf}}(5) file is still
15 supported, but must be converted to the new {{slapd.d}}(5) format
16 to allow runtime changes to be saved. While the old style
17 configuration uses a single file, normally installed as
18 {{F:/usr/local/etc/openldap/slapd.conf}}, the new style
19 uses a slapd backend database to store the configuration. The
20 the configuration database normally resides in the
21 {{F:/usr/local/etc/openldap/slapd.d}} directory.
22
23 An alternate configuration directory (or file) can be specified via a
24 command-line option to {{slapd}}(8) or {{slurpd}}(8). This chapter
25 describes the general format of the configuration system , followed by a
26 detailed description of commonly used config directives.
27
28
29 H2: Configuration Layout
30
31 The slapd configuration is stored as a special LDAP directory with
32 a predefined schema and DIT. There are specific objectClasses used to
33 carry global configuration options, schema definitions, backend and
34 database definitions, and assorted other items. A sample config tree
35 is shown in Figure 5.1.
36
37 !import "config_dit.gif"; align="center"; title="Sample configuration tree"
38 FT[align="Center"] Figure 5.1: Sample configuration tree.
39
40 Other objects may be part of the configuration but were omitted from
41 the illustration for clarity.
42
43 The {{slapd.d}} configuration tree has a very specific structure. The
44 root of the tree is named {{EX:cn=config}} and contains global configuration
45 settings. Additional settings are contained in separate child entries:
46 * Include files
47 .. Usually these are just pathnames left over from a converted
48 {{EX:slapd.conf}} file.
49 .. Otherwise use of Include files is deprecated.
50 * Dynamically loaded modules
51 .. These may only be used if the {{EX:--enable-modules}} option was
52 used to configure the software.
53 * Schema definitions
54 .. The {{EX:cn=schema,cn=config}} entry contains the system schema (all
55 the schema that is hard-coded in slapd).
56 .. Child entries of {{EX:cn=schema,cn=config}} contain user schema as
57 loaded from config files or added at runtime.
58 * Backend-specific configuration 
59 * Database-specific configuration
60 .. Overlays are defined in children of the Database entry.
61 .. Databases and Overlays may also have other miscellaneous children.
62
63 The usual rules for LDIF files apply to the configuration information:
64 Comment lines beginning with a '{{EX:#}}' character
65 are ignored.  If a line begins with white space, it is considered a
66 continuation of the previous line (even if the previous line is a
67 comment). Entries are separated by blank lines.
68
69 The general layout of the config LDIF is as follows:
70
71 >       # global configuration settings
72 >       dn: cn=config
73 >       objectClass: olcGlobal
74 >       cn: config
75 >       <global config settings>
76 >
77 >       # schema definitions
78 >       dn: cn=schema,cn=config
79 >       objectClass: olcSchemaConfig
80 >       cn: schema
81 >       <system schema>
82 >
83 >       dn: cn={X}core,cn=schema,cn=config
84 >       objectClass: olcSchemaConfig
85 >       cn: {X}core
86 >       <core schema>
87 >
88 >       # additional user-specified schema
89 >       ...
90 >
91 >       # backend definitions
92 >       dn: olcBackend={X}<typeA>,cn=config
93 >       objectClass: olcBackendConfig
94 >       olcBackend: {X}<typeA>
95 >       <backend-specific settings>
96 >
97 >       # database definitions
98 >       dn: olcDatabase={X}<typeA>,cn=config
99 >       objectClass: olcDatabaseConfig
100 >       olcDatabase: {X}<typeA>
101 >       <database-specific settings>
102 >
103 >       # subsequent definitions and settings
104 >       ...
105
106 Some of the entries listed above have a numeric index {{EX:"{X}"}} in
107 their names. While most configuration settings have an inherent ordering
108 dependency (i.e., one setting must take effect before a subsequent one
109 may be set), LDAP databases are inherently unordered. The numeric index
110 is used to enforce a consistent ordering in the configuration database,
111 so that all ordering dependencies are preserved. In most cases the index
112 does not have to be provided; it will be automatically generated based
113 on the order in which entries are created.
114
115 A configuration directive may take arguments.  If so, they are
116 separated by white space.  If an argument contains white space,
117 the argument should be enclosed in double quotes {{EX:"like this"}}. If
118 an argument contains a double quote or a backslash character `{{EX:\}}',
119 the character should be preceded by a backslash character `{{EX:\}}'.
120
121 The distribution contains an example configuration file that will
122 be installed in the {{F: /usr/local/etc/openldap}} directory.
123 A number of files containing schema definitions (attribute types
124 and object classes) are also provided in the
125 {{F: /usr/local/etc/openldap/schema}} directory.
126
127
128 H2: Configuration Directives
129
130 This section details commonly used configuration directives.  For
131 a complete list, see the {{slapd.d}}(5) manual page.  This section
132 separates the configuration directives into global,
133 backend-specific and data-specific categories, describing each
134 directive and its default value (if any), and giving an example of
135 its use.
136
137 Most of the attributes and objectClasses used in the slapd
138 configuration have a prefix of {{EX:"olc"}} (OpenLDAP Configuration)
139 in their names.
140
141
142
143 H3: Global Directives
144
145 Directives described in this section apply to all backends
146 and databases unless specifically overridden in a backend or
147 database definition.  Arguments that should be replaced
148 by actual text are shown in brackets {{EX:<>}}.
149
150
151 H4: access to <what> [ by <who> <accesslevel> <control> ]+
152
153 This directive grants access (specified by <accesslevel>) to a
154 set of entries and/or attributes (specified by <what>) by one or
155 more requesters (specified by <who>).
156 See the {{SECT:Access Control}} section of this chapter for a
157 summary of basic usage.
158
159 !if 0
160 More details discussion of this directive can be found in the
161 {{SECT:Advanced Access Control}} chapter.
162 !endif
163
164 Note: If no {{EX:access}} directives are specified, the default
165 access control policy, {{EX:access to * by * read}}, allows all
166 both authenticated and anonymous users read access.
167
168
169 H4: attributetype <{{REF:RFC2252}} Attribute Type Description>
170
171 This directive defines an attribute type.
172 Please see the {{SECT:Schema Specification}} chapter
173 for information regarding how to use this directive.
174
175 H4: idletimeout <integer>
176
177 Specify the number of seconds to wait before forcibly closing
178 an idle client connection.  An idletimeout of 0, the default,
179 disables this feature.
180
181
182 H4: include <filename>
183
184 This directive specifies that slapd should read additional
185 configuration information from the given file before continuing
186 with the next line of the current file. The included file should
187 follow the normal slapd config file format.  The file is commonly
188 used to include files containing schema specifications.
189
190 Note: You should be careful when using this directive - there is
191 no small limit on the number of nested include directives, and no
192 loop detection is done.
193
194 H4: loglevel <integer>
195
196 This directive specifies the level at which debugging statements
197 and operation statistics should be syslogged (currently logged to
198 the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have
199 configured OpenLDAP {{EX:--enable-debug}} (the default) for this
200 to work (except for the two statistics levels, which are always
201 enabled).  Log levels are additive. To display what numbers
202 correspond to what kind of debugging, invoke slapd with {{EX:-?}}
203 or consult the table below. The possible values for <integer> are:
204
205 !block table; colaligns="RL"; align=Center; \
206         title="Table 5.1: Debugging Levels"
207 Level   Description
208 -1      enable all debugging
209 0       no debugging
210 1       trace function calls
211 2       debug packet handling
212 4       heavy trace debugging
213 8       connection management
214 16      print out packets sent and received
215 32      search filter processing
216 64      configuration file processing
217 128     access control list processing
218 256     stats log connections/operations/results
219 512     stats log entries sent
220 1024    print communication with shell backends
221 2048    print entry parsing debugging
222 !endblock
223
224 \Example:
225
226 E: loglevel -1
227
228 This will cause lots and lots of debugging information to be
229 logged.
230
231 \Default:
232
233 E: loglevel 256
234
235
236 H4: objectclass <{{REF:RFC2252}} Object Class Description>
237
238 This directive defines an object class.
239 Please see the {{SECT:Schema Specification}} chapter for
240 information regarding how to use this directive.
241
242
243 H4: referral <URI>
244
245 This directive specifies the referral to pass back when slapd
246 cannot find a local database to handle a request.
247
248 \Example:
249
250 >       referral ldap://root.openldap.org
251
252 This will refer non-local queries to the global root LDAP server
253 at the OpenLDAP Project. Smart LDAP clients can re-ask their
254 query at that server, but note that most of these clients are
255 only going to know how to handle simple LDAP URLs that
256 contain a host part and optionally a distinguished name part.
257
258
259 H4: sizelimit <integer>
260
261 This directive specifies the maximum number of entries to return
262 from a search operation.
263
264 \Default:
265
266 >       sizelimit 500
267
268
269 H4: timelimit <integer>
270
271 This directive specifies the maximum number of seconds (in real
272 time) slapd will spend answering a search request. If a
273 request is not finished in this time, a result indicating an
274 exceeded timelimit will be returned.
275
276 \Default:
277
278 >       timelimit 3600
279
280
281 H3: General Backend Directives
282
283 Directives in this section apply only to the backend in which
284 they are defined. They are supported by every type of backend.
285 Backend directives apply to all databases instances of the
286 same type and, depending on the directive, may be overridden
287 by database directives.
288
289 H4: backend <type>
290
291 This directive marks the beginning of a backend declaration.
292 {{EX:<type>}} should be one of the
293 supported backend types listed in Table 5.2.
294
295 !block table; align=Center; coltags="EX,N"; \
296         title="Table 5.2: Database Backends"
297 Types   Description
298 bdb     Berkeley DB transactional backend
299 dnssrv  DNS SRV backend
300 ldap    Lightweight Directory Access Protocol (Proxy) backend
301 ldbm    Lightweight DBM backend
302 meta    Meta Directory backend
303 monitor Monitor backend
304 passwd  Provides read-only access to {{passwd}}(5)
305 perl    Perl Programmable backend
306 shell   Shell (extern program) backend
307 sql     SQL Programmable backend
308 !endblock
309
310 \Example:
311
312 >       backend bdb
313
314 This marks the beginning of a new {{TERM:BDB}} backend
315 definition.
316
317
318 H3: General Database Directives
319
320 Directives in this section apply only to the database in which
321 they are defined. They are supported by every type of database.
322
323 H4: database <type>
324
325 This directive marks the beginning of a database instance
326 declaration.
327 {{EX:<type>}} should be one of the
328 supported backend types listed in Table 5.2.
329
330 \Example:
331
332 >       database bdb
333
334 This marks the beginning of a new {{TERM:BDB}} database instance
335 declaration.
336
337
338 H4: readonly { on | off }
339
340 This directive puts the database into "read-only" mode. Any
341 attempts to modify the database will return an "unwilling to
342 perform" error.
343
344 \Default:
345
346 >       readonly off
347
348 H4: replica
349
350 >       replica uri=ldap[s]://<hostname>[:<port>] | host=<hostname>[:<port>]
351 >               [bindmethod={simple|kerberos|sasl}]
352 >               ["binddn=<DN>"]
353 >               [saslmech=<mech>]
354 >               [authcid=<identity>]
355 >               [authzid=<identity>]
356 >               [credentials=<password>]
357 >               [srvtab=<filename>]
358
359 This directive specifies a replication site for this database. The
360 {{EX:uri=}} parameter specifies a scheme, a host and optionally a port where
361 the slave slapd instance can be found. Either a domain name
362 or IP address may be used for <hostname>. If <port> is not
363 given, the standard LDAP port number (389 or 636) is used.
364
365 {{EX:host}} is deprecated in favor of the {{EX:uri}} parameter.
366
367 {{EX:uri}} allows the replica LDAP server to be specified as an LDAP 
368 URI such as {{EX:ldap://slave.example.com:389}} or
369 {{EX:ldaps://slave.example.com:636}}.
370
371 The {{EX:binddn=}} parameter gives the DN to bind as for updates
372 to the slave slapd. It should be a DN which has read/write access
373 to the slave slapd's database.  It must also match the {{EX:updatedn}}
374 directive in the slave slapd's config file.  Generally, this DN
375 {{should not}} be the same as the {{EX:rootdn}} of the master
376 database.  Since DNs are likely to contain embedded spaces, the
377 entire {{EX:"binddn=<DN>"}} string should be enclosed in double
378 quotes.
379
380 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:kerberos}} or {{EX:sasl}},
381 depending on whether simple password-based authentication or Kerberos
382 authentication or {{TERM:SASL}} authentication is to be used when connecting
383 to the slave slapd.
384
385 Simple authentication should not be used unless adequate data
386 integrity and confidentiality protections are in place (e.g. TLS
387 or IPSEC).  Simple authentication requires specification of
388 {{EX:binddn}} and {{EX:credentials}} parameters.
389
390 Kerberos authentication is deprecated in favor of SASL authentication
391 mechanisms, in particular the {{EX:KERBEROS_V4}} and {{EX:GSSAPI}}
392 mechanisms.  Kerberos authentication requires {{EX:binddn}} and
393 {{EX:srvtab}} parameters.
394
395 SASL authentication is generally recommended.  SASL authentication
396 requires specification of a mechanism using the {{EX:saslmech}} parameter.
397 Depending on the mechanism, an authentication identity and/or
398 credentials can be specified using {{EX:authcid}} and {{EX:credentials}}
399 respectively.  The {{EX:authzid}} parameter may be used to specify
400 an authorization identity.
401
402 See the chapter entitled {{SECT:Replication with slurpd}} for more
403 information on how to use this directive.
404
405
406 H4: replogfile <filename>
407
408 This directive specifies the name of the replication log file to
409 which slapd will log changes. The replication log is typically
410 written by slapd and read by slurpd. Normally, this directive is
411 only used if slurpd is being used to replicate the database.
412 However, you can also use it to generate a transaction log, if
413 slurpd is not running. In this case, you will need to periodically
414 truncate the file, since it will grow indefinitely otherwise.
415
416 See the chapter entitled {{SECT:Replication with slurpd}} for more
417 information on how to use this directive.
418
419
420 H4: rootdn <DN>
421
422 This directive specifies the DN that is not subject to
423 access control or administrative limit restrictions for
424 operations on this database.  The DN need not refer to
425 an entry in this database or even in the directory. The
426 DN may refer to a SASL identity.
427
428 Entry-based Example:
429
430 >       rootdn "cn=Manager,dc=example,dc=com"
431
432 SASL-based Example:
433
434 >       rootdn "uid=root,cn=example.com,cn=digest-md5,cn=auth"
435
436 See the {{SECT:SASL Authentication}} section for information on
437 SASL authentication identities.
438
439
440 H4: rootpw <password>
441
442 This directive can be used to specifies a password for the DN for
443 the rootdn (when the rootdn is set to a DN within the database).
444
445 \Example:
446
447 >       rootpw secret
448
449 It is also permissible to provide hash of the password in RFC 2307
450 form.  {{slappasswd}}(8) may be used to generate the password hash.
451
452 \Example:
453
454 >       rootpw {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN
455
456 The hash was generated using the command {{EX:slappasswd -s secret}}.
457
458
459 H4: suffix <dn suffix>
460
461 This directive specifies the DN suffix of queries that will be
462 passed to this backend database. Multiple suffix lines can be
463 given, and at least one is required for each database
464 definition.
465
466 \Example:
467
468 >       suffix "dc=example,dc=com"
469
470 Queries with a DN ending in "dc=example,dc=com"
471 will be passed to this backend.
472
473 Note: When the backend to pass a query to is selected, slapd
474 looks at the suffix line(s) in each database definition in the
475 order they appear in the file. Thus, if one database suffix is a
476 prefix of another, it must appear after it in the config file.
477
478
479 H4: syncrepl
480
481 >       syncrepl rid=<replica ID>
482 >               provider=ldap[s]://<hostname>[:port]
483 >               [type=refreshOnly|refreshAndPersist]
484 >               [interval=dd:hh:mm:ss]
485 >               [retry=[<retry interval> <# of retries>]+]
486 >               [searchbase=<base DN>]
487 >               [filter=<filter str>]
488 >               [scope=sub|one|base]
489 >               [attrs=<attr list>]
490 >               [attrsonly]
491 >               [sizelimit=<limit>]
492 >               [timelimit=<limit>]
493 >               [schemachecking=on|off]
494 >               [bindmethod=simple|sasl]
495 >               [binddn=<DN>]
496 >               [saslmech=<mech>]
497 >               [authcid=<identity>]
498 >               [authzid=<identity>]
499 >               [credentials=<passwd>]
500 >               [realm=<realm>]
501 >               [secprops=<properties>]
502
503
504 This directive specifies the current database as a replica of the
505 master content by establishing the current {{slapd}}(8) as a
506 replication consumer site running a syncrepl replication engine.
507 The master database is located at the replication provider site
508 specified by the {{EX:provider}} parameter. The replica database is
509 kept up-to-date with the master content using the LDAP Content
510 Synchronization protocol. See {{EX:draft-zeilenga-ldup-sync-xx.txt}}
511 ({{a work in progress}}) for more information on the protocol.
512
513 The {{EX:rid}} parameter is used for identification of the current
514 {{EX:syncrepl}} directive within the replication consumer server,
515 where {{EX:<replica ID>}} uniquely identifies the syncrepl specification
516 described by the current {{EX:syncrepl}} directive. {{EX:<replica ID>}}
517 is non-negative and is no more than three decimal digits in length.
518
519 The {{EX:provider}} parameter specifies the replication provider site
520 containing the master content as an LDAP URI. The {{EX:provider}}
521 parameter specifies a scheme, a host and optionally a port where the
522 provider slapd instance can be found. Either a domain name or IP
523 address may be used for <hostname>. Examples are
524 {{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}.
525 If <port> is not given, the standard LDAP port number (389 or 636) is used.
526 Note that the syncrepl uses a consumer-initiated protocol, and hence its
527 specification is located at the consumer site, whereas the {{EX:replica}}
528 specification is located at the provider site. {{EX:syncrepl}} and
529 {{EX:replica}} directives define two independent replication
530 mechanisms. They do not represent the replication peers of each other.
531
532 The content of the syncrepl replica is defined using a search
533 specification as its result set. The consumer slapd will
534 send search requests to the provider slapd according to the search
535 specification. The search specification includes {{EX:searchbase}},
536 {{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:attrsonly}},
537 {{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal
538 search specification. The syncrepl search specification has
539 the same value syntax and the same default values as in the
540 {{ldapsearch}}(1) client search tool.
541
542 The LDAP Content Synchronization protocol has two operation
543 types: {{EX:refreshOnly}} and {{EX:refreshAndPersist}}.
544 The operation type is specified by the {{EX:type}} parameter.
545 In the {{EX:refreshOnly}} operation, the next synchronization search operation
546 is periodically rescheduled at an interval time after each
547 synchronization operation finishes. The interval is specified
548 by the {{EX:interval}} parameter. It is set to one day by default.
549 In the {{EX:refreshAndPersist}} operation, a synchronization search
550 remains persistent in the provider slapd. Further updates to the
551 master replica will generate {{EX:searchResultEntry}} to the consumer slapd
552 as the search responses to the persistent synchronization search.
553
554 If an error occurs during replication, the consumer will attempt to reconnect
555 according to the retry parameter which is a list of the <retry interval>
556 and <# of retries> pairs. For example, retry="60 5 300 3" lets the consumer
557 retry every 60 seconds for the first 10 times and then retry every 300 seconds
558 for the next three times before stop retrying. + in <#  of retries> means
559 indefinite number of retries until success.
560
561 The schema checking can be enforced at the LDAP Sync consumer site
562 by turning on the {{EX:schemachecking}} parameter.
563 If it is turned on, every replicated entry will be checked for its
564 schema as the entry is stored into the replica content.
565 Every entry in the replica should contain those attributes
566 required by the schema definition.
567 If it is turned off, entries will be stored without checking
568 schema conformance. The default is off.
569
570 The {{EX:binddn}} parameter gives the DN to bind as for the
571 syncrepl searches to the provider slapd. It should be a DN
572 which has read access to the replication content in the
573 master database. 
574
575 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
576 depending on whether simple password-based authentication or
577 {{TERM:SASL}} authentication is to be used when connecting
578 to the provider slapd.
579
580 Simple authentication should not be used unless adequate data
581 integrity and confidentiality protections are in place (e.g. TLS
582 or IPSEC). Simple authentication requires specification of {{EX:binddn}}
583 and {{EX:credentials}} parameters.
584
585 SASL authentication is generally recommended.  SASL authentication
586 requires specification of a mechanism using the {{EX:saslmech}} parameter.
587 Depending on the mechanism, an authentication identity and/or
588 credentials can be specified using {{EX:authcid}} and {{EX:credentials}},
589 respectively.  The {{EX:authzid}} parameter may be used to specify
590 an authorization identity.
591
592 The {{EX:realm}} parameter specifies a realm which a certain
593 mechanisms authenticate the identity within. The {{EX:secprops}}
594 parameter specifies Cyrus SASL security properties.
595
596 The syncrepl replication mechanism is supported by the
597 three native backends: back-bdb, back-hdb, and back-ldbm.
598
599 See the {{SECT:LDAP Sync Replication}} chapter of the admin guide
600 for more information on how to use this directive.
601
602
603 H4: updatedn <DN>
604
605 This directive is only applicable in a slave slapd. It specifies
606 the DN allowed to make changes to the replica.  This may be the DN
607 {{slurpd}}(8) binds as when making changes to the replica or the DN
608 associated with a SASL identity.
609
610 Entry-based Example:
611
612 >       updatedn "cn=Update Daemon,dc=example,dc=com"
613
614 SASL-based Example:
615
616 >       updatedn "uid=slurpd,cn=example.com,cn=digest-md5,cn=auth"
617
618 See the {{SECT:Replication with slurpd}} chapter for more information
619 on how to use this directive.
620
621 H4: updateref <URL>
622
623 This directive is only applicable in a slave slapd. It
624 specifies the URL to return to clients which submit update
625 requests upon the replica.
626 If specified multiple times, each {{TERM:URL}} is provided.
627
628 \Example:
629
630 >       updateref       ldap://master.example.net
631
632
633 H3: BDB Database Directives
634
635 Directives in this category only apply to a {{TERM:BDB}} database.
636 That is, they must follow a "database bdb" line and come before any
637 subsequent "backend" or "database" line.  For a complete reference
638 of BDB configuration directives, see {{slapd-bdb}}(5).
639
640
641 H4: directory <directory>
642
643 This directive specifies the directory where the BDB files
644 containing the database and associated indices live.
645
646 \Default:
647
648 >       directory /usr/local/var/openldap-data
649
650
651 H3: LDBM Database Directives
652
653 Directives in this category only apply to a {{TERM:LDBM}} database.
654 That is, they must follow a "database ldbm" line and come before
655 any subsequent "backend" or "database" line.  For a complete reference
656 of LDBM configuration directives, see {{slapd-ldbm}}(5).
657
658 H4: cachesize <integer>
659
660 This directive specifies the size in entries of the in-memory
661 cache maintained by the LDBM backend database instance.
662
663 \Default:
664
665 >       cachesize 1000
666
667
668 H4: dbcachesize <integer>
669
670 This directive specifies the size in bytes of the in-memory cache
671 associated with each open index file. If not supported by the
672 underlying database method, this directive is ignored without
673 comment. Increasing this number uses more memory but can
674 cause a dramatic performance increase, especially during
675 modifies or when building indices.
676
677 \Default:
678
679 >       dbcachesize 100000
680
681
682 H4: dbnolocking
683
684 This option, if present, disables database locking.
685 Enabling this option may improve performance at the expense
686 of data security.
687
688
689 H4: dbnosync
690
691 This option causes on-disk database contents to not be immediately
692 synchronized with in memory changes upon change.  Enabling this option
693 may improve performance at the expense of data integrity.
694
695
696 H4: directory <directory>
697
698 This directive specifies the directory where the LDBM files
699 containing the database and associated indices live.
700
701 \Default:
702
703 >       directory /usr/local/var/openldap-data
704
705
706 H4: index {<attrlist> | default} [pres,eq,approx,sub,none]
707
708 This directive specifies the indices to maintain for the given
709 attribute. If only an {{EX:<attrlist>}} is given, the default
710 indices are maintained.
711
712 \Example:
713
714 >       index default pres,eq
715 >       index uid
716 >       index cn,sn pres,eq,sub
717 >       index objectClass eq
718
719 The first line sets the default set of indices to maintain to
720 present and equality.  The second line causes the default (pres,eq)
721 set of indices to be maintained for the {{EX:uid}} attribute type.
722 The third line causes present, equality, and substring indices to
723 be maintained for {{EX:cn}} and {{EX:sn}} attribute types.  The
724 fourth line causes an equality index for the {{EX:objectClass}}
725 attribute type.
726
727 By default, no indices are maintained.  It is generally advised
728 that minimally an equality index upon objectClass be maintained.
729
730 >       index objectClass eq
731
732
733
734 H4: mode <integer>
735
736 This directive specifies the file protection mode that newly
737 created database index files should have.
738
739 \Default:
740
741 >       mode 0600
742
743
744 H2: Access Control
745
746 Access to slapd entries and attributes is controlled by the
747 access configuration file directive. The general form of an
748 access line is:
749
750 >       <access directive> ::= access to <what>
751 >               [by <who> <access> <control>]+
752 >       <what> ::= * |
753 >               [dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>]
754 >               [filter=<ldapfilter>] [attrs=<attrlist>]
755 >       <basic-style> ::= regex | exact
756 >       <scope-style> ::= base | one | subtree | children
757 >       <attrlist> ::= <attr> [val[.<basic-style>]=<regex>] | <attr> , <attrlist>
758 >       <attr> ::= <attrname> | entry | children
759 >       <who> ::= * | [anonymous | users | self
760 >                       | dn[.<basic-style>]=<regex> | dn.<scope-style>=<DN>] 
761 >               [dnattr=<attrname>]
762 >               [group[/<objectclass>[/<attrname>][.<basic-style>]]=<regex>]
763 >               [peername[.<basic-style>]=<regex>]
764 >               [sockname[.<basic-style>]=<regex>]
765 >               [domain[.<basic-style>]=<regex>]
766 >               [sockurl[.<basic-style>]=<regex>]
767 >               [set=<setspec>]
768 >               [aci=<attrname>]
769 >       <access> ::= [self]{<level>|<priv>}
770 >       <level> ::= none | auth | compare | search | read | write
771 >       <priv> ::= {=|+|-}{w|r|s|c|x|0}+
772 >       <control> ::= [stop | continue | break]
773
774 where the <what> part selects the entries and/or attributes to which
775 the access applies, the {{EX:<who>}} part specifies which entities
776 are granted access, and the {{EX:<access>}} part specifies the
777 access granted. Multiple {{EX:<who> <access> <control>}} triplets
778 are supported, allowing many entities to be granted different access
779 to the same set of entries and attributes. Not all of these access
780 control options are described here; for more details see the
781 {{slapd.access}}(5) man page.
782
783
784 H3: What to control access to
785
786 The <what> part of an access specification determines the entries
787 and attributes to which the access control applies.  Entries are
788 commonly selected in two ways: by DN and by filter.  The following
789 qualifiers select entries by DN:
790
791 >       to *
792 >       to dn[.<basic-style>]=<regex>
793 >       to dn.<scope-style>=<DN>
794
795 The first form is used to select all entries.  The second form may
796 be used to select entries by matching a regular expression against
797 the target entry's {{normalized DN}}.   (The second form is not
798 discussed further in this document.)  The third form is used to
799 select entries which are within the requested scope of DN.  The
800 <DN> is a string representation of the Distinguished Name, as
801 described in {{REF:RFC2253}}.
802
803 The scope can be either {{EX:base}}, {{EX:one}}, {{EX:subtree}},
804 or {{EX:children}}.  Where {{EX:base}} matches only the entry with
805 provided DN, {{EX:one}} matches the entries whose parent is the
806 provided DN, {{EX:subtree}} matches all entries in the subtree whose
807 root is the provided DN, and {{EX:children}} matches all entries
808 under the DN (but not the entry named by the DN).
809
810 For example, if the directory contained entries named:
811
812 >       0: o=suffix
813 >       1: cn=Manager,o=suffix
814 >       2: ou=people,o=suffix
815 >       3: uid=kdz,ou=people,o=suffix
816 >       4: cn=addresses,uid=kdz,ou=people,o=suffix
817 >       5: uid=hyc,ou=people,o=suffix
818
819 \Then:
820 . {{EX:dn.base="ou=people,o=suffix"}} match 2;
821 . {{EX:dn.one="ou=people,o=suffix"}} match 3, and 5;
822 . {{EX:dn.subtree="ou=people,o=suffix"}} match 2, 3, 4, and 5; and
823 . {{EX:dn.children="ou=people,o=suffix"}} match 3, 4, and 5.
824
825
826 Entries may also be selected using a filter:
827
828 >       to filter=<ldap filter>
829
830 where <ldap filter> is a string representation of an LDAP
831 search filter, as described in {{REF:RFC2254}}.  For example:
832
833 >       to filter=(objectClass=person)
834
835 Note that entries may be selected by both DN and filter by
836 including both qualifiers in the <what> clause.
837
838 >       to dn.one="ou=people,o=suffix" filter=(objectClass=person)
839
840 Attributes within an entry are selected by including a comma-separated
841 list of attribute names in the <what> selector:
842
843 >       attrs=<attribute list>
844
845 A specific value of an attribute is selected by using a single
846 attribute name and also using a value selector:
847
848 >       attrs=<attribute> val[.<style>]=<regex>
849
850 There are two special {{pseudo}} attributes {{EX:entry}} and
851 {{EX:children}}.  To read (and hence return) a target entry, the
852 subject must have {{EX:read}} access to the target's {{entry}}
853 attribute.  To add or delete an entry, the subject must have
854 {{EX:write}} access to the entry's {{EX:entry}} attribute AND must
855 have {{EX:write}} access to the entry's parent's {{EX:children}}
856 attribute.  To rename an entry, the subject must have {{EX:write}}
857 access to entry's {{EX:entry}} attribute AND have {{EX:write}}
858 access to both the old parent's and new parent's {{EX:children}}
859 attributes.  The complete examples at the end of this section should
860 help clear things up.
861
862 Lastly, there is a special entry selector {{EX:"*"}} that is used to
863 select any entry.  It is used when no other {{EX:<what>}}
864 selector has been provided.  It's equivalent to "{{EX:dn=.*}}"
865
866
867 H3: Who to grant access to
868
869 The <who> part identifies the entity or entities being granted
870 access. Note that access is granted to "entities" not "entries."
871 The following table summarizes entity specifiers:
872
873 !block table; align=Center; coltags="EX,N"; \
874         title="Table 5.3: Access Entity Specifiers"
875 Specifier|Entities
876 *|All, including anonymous and authenticated users
877 anonymous|Anonymous (non-authenticated) users
878 users|Authenticated users
879 self|User associated with target entry
880 dn[.<basic-style>]=<regex>|Users matching a regular expression
881 dn.<scope-style>=<DN>|Users within scope of a DN
882 !endblock
883
884 The DN specifier behaves much like <what> clause DN specifiers.
885
886 Other control factors are also supported.  For example, a {{EX:<who>}}
887 can be restricted by an entry listed in a DN-valued attribute in
888 the entry to which the access applies:
889
890 >       dnattr=<dn-valued attribute name>
891
892 The dnattr specification is used to give access to an entry
893 whose DN is listed in an attribute of the entry (e.g., give
894 access to a group entry to whoever is listed as the owner of
895 the group entry).
896
897 Some factors may not be appropriate in all environments (or any).
898 For example, the domain factor relies on IP to domain name lookups.
899 As these can easily spoofed, the domain factor should not be avoided.
900
901
902 H3: The access to grant
903
904
905 The kind of <access> granted can be one of the following:
906
907
908 !block table; colaligns="LRL"; coltags="EX,EX,N"; align=Center; \
909         title="Table 5.4: Access Levels"
910 Level   Privileges      Description
911 none    =0              no access
912 auth    =x              needed to bind
913 compare =cx             needed to compare
914 search  =scx            needed to apply search filters
915 read    =rscx           needed to read search results
916 write   =wrscx          needed to modify/rename
917 !endblock
918
919 Each level implies all lower levels of access. So, for
920 example, granting someone {{EX:write}} access to an entry also
921 grants them {{EX:read}}, {{EX:search}}, {{EX:compare}}, and 
922 {{EX:auth}} access.  However, one may use the privileges specifier
923 to grant specific permissions.
924
925
926 H3: Access Control Evaluation
927
928 When evaluating whether some requester should be given access to
929 an entry and/or attribute, slapd compares the entry and/or attribute
930 to the {{EX:<what>}} selectors given in the configuration file.
931 For each entry, access controls provided in the database which holds
932 the entry (or the first database if not held in any database) apply
933 first, followed by the global access directives.  Within this
934 priority, access directives are examined in the order in which they
935 appear in the config file.  Slapd stops with the first {{EX:<what>}}
936 selector that matches the entry and/or attribute. The corresponding
937 access directive is the one slapd will use to evaluate access.
938
939 Next, slapd compares the entity requesting access to the {{EX:<who>}}
940 selectors within the access directive selected above in the order
941 in which they appear. It stops with the first {{EX:<who>}} selector
942 that matches the requester. This determines the access the entity
943 requesting access has to the entry and/or attribute.
944
945 Finally, slapd compares the access granted in the selected
946 {{EX:<access>}} clause to the access requested by the client. If
947 it allows greater or equal access, access is granted. Otherwise,
948 access is denied.
949
950 The order of evaluation of access directives makes their placement
951 in the configuration file important. If one access directive is
952 more specific than another in terms of the entries it selects, it
953 should appear first in the config file. Similarly, if one {{EX:<who>}}
954 selector is more specific than another it should come first in the
955 access directive. The access control examples given below should
956 help make this clear.
957
958
959
960 H3: Access Control Examples
961
962 The access control facility described above is quite powerful.  This
963 section shows some examples of its use for descriptive purposes.
964
965 A simple example:
966
967 >       access to * by * read
968
969 This access directive grants read access to everyone.
970
971 >       access to *
972 >               by self write
973 >               by anonymous auth
974 >               by * read
975
976 This directive allows the user to modify their entry, allows anonymous
977 to authentication against these entries, and allows all others to
978 read these entries.  Note that only the first {{EX:by <who>}} clause
979 which matches applies.  Hence, the anonymous users are granted
980 {{EX:auth}}, not {{EX:read}}.  The last clause could just as well
981 have been "{{EX:by users read}}".
982
983 It is often desirable to restrict operations based upon the level
984 of protection in place.  The following shows how security strength
985 factors (SSF) can be used.
986
987 >       access to *
988 >               by ssf=128 self write
989 >               by ssf=64 anonymous auth
990 >               by ssf=64 users read
991
992 This directive allows users to modify their own entries if security
993 protections have of strength 128 or better have been established,
994 allows authentication access to anonymous users, and read access
995 when 64 or better security protections have been established.  If
996 client has not establish sufficient security protections, the
997 implicit {{EX:by * none}} clause would be applied.
998
999 The following example shows the use of a style specifiers to select
1000 the entries by DN in two access directives where ordering is
1001 significant.
1002
1003 >       access to dn.children="dc=example,dc=com"
1004 >               by * search
1005 >       access to dn.children="dc=com"
1006 >               by * read
1007
1008 Read access is granted to entries under the {{EX:dc=com}} subtree,
1009 except for those entries under the {{EX:dc=example,dc=com}} subtree,
1010 to which search access is granted.  No access is granted to
1011 {{EX:dc=com}} as neither access directive matches this DN.  If the
1012 order of these access directives was reversed, the trailing directive
1013 would never be reached, since all entries under {{EX:dc=example,dc=com}}
1014 are also under {{EX:dc=com}} entries.
1015
1016 Also note that if no {{EX:access to}} directive matches or no {{EX:by
1017 <who>}} clause, {{B:access is denied}}.  That is, every {{EX:access
1018 to}} directive ends with an implicit {{EX:by * none}} clause and
1019 every access list ends with an implicit {{EX:access to * by * none}}
1020 directive.
1021
1022 The next example again shows the importance of ordering, both of
1023 the access directives and the {{EX:by <who>}} clauses.  It also
1024 shows the use of an attribute selector to grant access to a specific
1025 attribute and various {{EX:<who>}} selectors.
1026
1027 >       access to dn.subtree="dc=example,dc=com" attr=homePhone
1028 >               by self write
1029 >               by dn.children=dc=example,dc=com" search
1030 >               by peername.regex=IP:10\..+ read
1031 >       access to dn.subtree="dc=example,dc=com"
1032 >               by self write
1033 >               by dn.children="dc=example,dc=com" search
1034 >               by anonymous auth
1035
1036 This example applies to entries in the "{{EX:dc=example,dc=com}}"
1037 subtree. To all attributes except {{EX:homePhone}}, an entry can
1038 write to itself, entries under {{EX:example.com}} entries can search
1039 by them, anybody else has no access (implicit {{EX:by * none}})
1040 excepting for authentication/authorization (which is always done
1041 anonymously).  The {{EX:homePhone}} attribute is writable by the
1042 entry, searchable by entries under {{EX:example.com}}, readable by
1043 clients connecting from network 10, and otherwise not readable
1044 (implicit {{EX:by * none}}).  All other access is denied by the
1045 implicit {{EX:access to * by * none}}.
1046
1047 Sometimes it is useful to permit a particular DN to add or
1048 remove itself from an attribute. For example, if you would like to
1049 create a group and allow people to add and remove only
1050 their own DN from the member attribute, you could accomplish
1051 it with an access directive like this:
1052
1053 >       access to attr=member,entry
1054 >               by dnattr=member selfwrite
1055
1056 The dnattr {{EX:<who>}} selector says that the access applies to
1057 entries listed in the {{EX:member}} attribute. The {{EX:selfwrite}} access
1058 selector says that such members can only add or delete their
1059 own DN from the attribute, not other values. The addition of
1060 the entry attribute is required because access to the entry is
1061 required to access any of the entry's attributes.
1062
1063 !if 0
1064 For more details on how to use the {{EX:access}} directive,
1065 consult the {{Advanced Access Control}} chapter.
1066 !endif
1067
1068
1069 H2: Configuration File Example
1070
1071 The following is an example configuration file, interspersed
1072 with explanatory text. It defines two databases to handle
1073 different parts of the {{TERM:X.500}} tree; both are {{TERM:BDB}}
1074 database instances. The line numbers shown are provided for
1075 reference only and are not included in the actual file. First, the
1076 global configuration section:
1077
1078 E:  1.  # example config file - global configuration section
1079 E:  2.  include /usr/local/etc/schema/core.schema
1080 E:  3.  referral ldap://root.openldap.org
1081 E:  4.  access to * by * read
1082  
1083 Line 1 is a comment. Line 2 includes another config file
1084 which contains {{core}} schema definitions.
1085 The {{EX:referral}} directive on line 3
1086 means that queries not local to one of the databases defined
1087 below will be referred to the LDAP server running on the
1088 standard port (389) at the host {{EX:root.openldap.org}}.
1089
1090 Line 4 is a global access control.  It applies to all
1091 entries (after any applicable database-specific access
1092 controls).
1093
1094 The next section of the configuration file defines a BDB
1095 backend that will handle queries for things in the
1096 "dc=example,dc=com" portion of the tree. The
1097 database is to be replicated to two slave slapds, one on
1098 truelies, the other on judgmentday. Indices are to be
1099 maintained for several attributes, and the {{EX:userPassword}}
1100 attribute is to be protected from unauthorized access.
1101
1102 E:  5.  # BDB definition for the example.com
1103 E:  6.  database bdb
1104 E:  7.  suffix "dc=example,dc=com"
1105 E:  8.  directory /usr/local/var/openldap-data
1106 E:  9.  rootdn "cn=Manager,dc=example,dc=com"
1107 E: 10.  rootpw secret
1108 E: 11.  # replication directives
1109 E: 12.  replogfile /usr/local/var/openldap/slapd.replog
1110 E: 13.  replica uri=ldap://slave1.example.com:389
1111 E: 14.          binddn="cn=Replicator,dc=example,dc=com"
1112 E: 15.          bindmethod=simple credentials=secret
1113 E: 16.  replica uri=ldaps://slave2.example.com:636
1114 E: 17.          binddn="cn=Replicator,dc=example,dc=com"
1115 E: 18.          bindmethod=simple credentials=secret
1116 E: 19.  # indexed attribute definitions
1117 E: 20.  index uid pres,eq
1118 E: 21.  index cn,sn,uid pres,eq,approx,sub
1119 E: 22.  index objectClass eq
1120 E: 23.  # database access control definitions
1121 E: 24.  access to attr=userPassword
1122 E: 25.          by self write
1123 E: 26.          by anonymous auth
1124 E: 27.          by dn.base="cn=Admin,dc=example,dc=com" write
1125 E: 28.          by * none
1126 E: 29.  access to *
1127 E: 30.          by self write
1128 E: 31.          by dn.base="cn=Admin,dc=example,dc=com" write
1129 E: 32.          by * read
1130
1131 Line 5 is a comment. The start of the database definition is marked
1132 by the database keyword on line 6. Line 7 specifies the DN suffix
1133 for queries to pass to this database. Line 8 specifies the directory
1134 in which the database files will live.
1135
1136 Lines 9 and 10 identify the database {{super-user}} entry and associated
1137 password. This entry is not subject to access control or size or
1138 time limit restrictions.
1139
1140 Lines 11 through 18 are for replication. Line 12 specifies the
1141 replication log file (where changes to the database are logged -
1142 this file is written by slapd and read by slurpd). Lines 13 through
1143 15 specify the hostname and port for a replicated host, the DN to
1144 bind as when performing updates, the bind method (simple) and the
1145 credentials (password) for the binddn. Lines 16 through 18 specify
1146 a second replication site.  See the {{SECT:Replication with slurpd}}
1147 chapter for more information on these directives.
1148
1149 Lines 20 through 22 indicate the indices to maintain for various
1150 attributes.
1151
1152 Lines 24 through 32 specify access control for entries in this
1153 database.  As this is the first database, the controls also apply
1154 to entries not held in any database (such as the Root DSE).  For
1155 all applicable entries, the {{EX:userPassword}} attribute is writable
1156 by the entry itself and by the "admin" entry.  It may be used for
1157 authentication/authorization purposes, but is otherwise not readable.
1158 All other attributes are writable by the entry and the "admin"
1159 entry, but may be read by all users (authenticated or not).
1160
1161 The next section of the example configuration file defines another
1162 BDB database. This one handles queries involving the
1163 {{EX:dc=example,dc=net}} subtree but is managed by the same entity
1164 as the first database.  Note that without line 39, the read access
1165 would be allowed due to the global access rule at line 4.
1166
1167 E: 33.  # BDB definition for example.net
1168 E: 34.  database bdb
1169 E: 35.  suffix "dc=example,dc=net"
1170 E: 36.  directory /usr/local/var/openldap-data-net
1171 E: 37.  rootdn "cn=Manager,dc=example,dc=com"
1172 E: 38.  index objectClass eq
1173 E: 39.  access to * by users read