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