2 # Copyright 1999-2008 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
5 H1: The slapd Configuration File
7 Once the software has been built and installed, you are ready
8 to configure {{slapd}}(8) for use at your site. The slapd
9 runtime configuration is primarily accomplished through the
10 {{slapd.conf}}(5) file, normally installed in the
11 {{EX:/usr/local/etc/openldap}} directory.
13 An alternate configuration file location can be specified via a command-line
14 option to {{slapd}}(8). This chapter describes the general format
15 of the {{slapd.conf}}(5) configuration file, followed by a detailed
16 description of commonly used config file directives.
19 H2: Configuration File Format
21 The {{slapd.conf}}(5) file consists of three types of configuration
22 information: global, backend specific, and database specific. Global
23 information is specified first, followed by information associated
24 with a particular backend type, which is then followed by information
25 associated with a particular database instance. Global directives can
26 be overridden in backend and/or database directives, and backend directives
27 can be overridden by database directives.
29 Blank lines and comment lines beginning with a '{{EX:#}}' character
30 are ignored. If a line begins with white space, it is considered a
31 continuation of the previous line (even if the previous line is a
34 The general format of slapd.conf is as follows:
36 > # global configuration directives
37 > <global config directives>
39 > # backend definition
41 > <backend-specific directives>
43 > # first database definition & config directives
45 > <database-specific directives>
47 > # second database definition & config directives
49 > <database-specific directives>
51 > # second database definition & config directives
53 > <database-specific directives>
55 > # subsequent backend & database definitions & config directives
58 A configuration directive may take arguments. If so, they are
59 separated by white space. If an argument contains white space,
60 the argument should be enclosed in double quotes {{EX:"like this"}}. If
61 an argument contains a double quote or a backslash character `{{EX:\}}',
62 the character should be preceded by a backslash character `{{EX:\}}'.
64 The distribution contains an example configuration file that will
65 be installed in the {{F: /usr/local/etc/openldap}} directory.
66 A number of files containing schema definitions (attribute types
67 and object classes) are also provided in the
68 {{F: /usr/local/etc/openldap/schema}} directory.
71 H2: Configuration File Directives
73 This section details commonly used configuration directives. For
74 a complete list, see the {{slapd.conf}}(5) manual page. This section
75 separates the configuration file directives into global,
76 backend-specific and data-specific categories, describing each
77 directive and its default value (if any), and giving an example of
84 Directives described in this section apply to all backends
85 and databases unless specifically overridden in a backend or
86 database definition. Arguments that should be replaced
87 by actual text are shown in brackets {{EX:<>}}.
90 H4: access to <what> [ by <who> [<accesslevel>] [<control>] ]+
92 This directive grants access (specified by <accesslevel>) to a set
93 of entries and/or attributes (specified by <what>) by one or more
94 requestors (specified by <who>). See the {{SECT:Access Control}} section of
95 this guide for basic usage.
98 More details discussion of this directive can be found in the
99 {{SECT:Advanced Access Control}} chapter.
102 Note: If no {{EX:access}} directives are specified, the default
103 access control policy, {{EX:access to * by * read}}, allows all
104 both authenticated and anonymous users read access.
107 H4: attributetype <{{REF:RFC4512}} Attribute Type Description>
109 This directive defines an attribute type.
110 Please see the {{SECT:Schema Specification}} chapter
111 for information regarding how to use this directive.
113 H4: idletimeout <integer>
115 Specify the number of seconds to wait before forcibly closing
116 an idle client connection. An idletimeout of 0, the default,
117 disables this feature.
120 H4: include <filename>
122 This directive specifies that slapd should read additional
123 configuration information from the given file before continuing
124 with the next line of the current file. The included file should
125 follow the normal slapd config file format. The file is commonly
126 used to include files containing schema specifications.
128 Note: You should be careful when using this directive - there is
129 no small limit on the number of nested include directives, and no
130 loop detection is done.
132 H4: loglevel <integer>
134 This directive specifies the level at which debugging statements
135 and operation statistics should be syslogged (currently logged to
136 the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have
137 configured OpenLDAP {{EX:--enable-debug}} (the default) for this
138 to work (except for the two statistics levels, which are always
139 enabled). Log levels are additive. To display what numbers
140 correspond to what kind of debugging, invoke slapd with {{EX:-?}}
141 or consult the table below. The possible values for <integer> are:
143 !block table; colaligns="RL"; align=Center; \
144 title="Table 6.1: Debugging Levels"
146 -1 enable all debugging
148 1 trace function calls
149 2 debug packet handling
150 4 heavy trace debugging
151 8 connection management
152 16 print out packets sent and received
153 32 search filter processing
154 64 configuration file processing
155 128 access control list processing
156 256 stats log connections/operations/results
157 512 stats log entries sent
158 1024 print communication with shell backends
159 2048 print entry parsing debugging
166 This will cause lots and lots of debugging information to be
174 H4: objectclass <{{REF:RFC4512}} Object Class Description>
176 This directive defines an object class.
177 Please see the {{SECT:Schema Specification}} chapter for
178 information regarding how to use this directive.
183 This directive specifies the referral to pass back when slapd
184 cannot find a local database to handle a request.
188 > referral ldap://root.openldap.org
190 This will refer non-local queries to the global root LDAP server
191 at the OpenLDAP Project. Smart LDAP clients can re-ask their
192 query at that server, but note that most of these clients are
193 only going to know how to handle simple LDAP URLs that
194 contain a host part and optionally a distinguished name part.
197 H4: sizelimit <integer>
199 This directive specifies the maximum number of entries to return
200 from a search operation.
207 H4: timelimit <integer>
209 This directive specifies the maximum number of seconds (in real
210 time) slapd will spend answering a search request. If a
211 request is not finished in this time, a result indicating an
212 exceeded timelimit will be returned.
219 H3: General Backend Directives
221 Directives in this section apply only to the backend in which
222 they are defined. They are supported by every type of backend.
223 Backend directives apply to all databases instances of the
224 same type and, depending on the directive, may be overridden
225 by database directives.
229 This directive marks the beginning of a backend declaration.
230 {{EX:<type>}} should be one of the
231 supported backend types listed in Table 6.2.
233 !block table; align=Center; coltags="EX,N"; \
234 title="Table 5.2: Database Backends"
236 bdb Berkeley DB transactional backend
237 dnssrv DNS SRV backend
238 hdb Hierarchical variant of bdb backend
239 ldap Lightweight Directory Access Protocol (Proxy) backend
240 meta Meta Directory backend
241 monitor Monitor backend
242 passwd Provides read-only access to {{passwd}}(5)
243 perl Perl Programmable backend
244 shell Shell (extern program) backend
245 sql SQL Programmable backend
252 This marks the beginning of a new {{TERM:BDB}} backend
256 H3: General Database Directives
258 Directives in this section apply only to the database in which
259 they are defined. They are supported by every type of database.
263 This directive marks the beginning of a database instance
265 {{EX:<type>}} should be one of the
266 supported backend types listed in Table 6.2.
272 This marks the beginning of a new {{TERM:BDB}} database instance
276 H4: readonly { on | off }
278 This directive puts the database into "read-only" mode. Any
279 attempts to modify the database will return an "unwilling to
289 This directive specifies the DN that is not subject to
290 access control or administrative limit restrictions for
291 operations on this database. The DN need not refer to
292 an entry in this database or even in the directory. The
293 DN may refer to a SASL identity.
297 > rootdn "cn=Manager,dc=example,dc=com"
301 > rootdn "uid=root,cn=example.com,cn=digest-md5,cn=auth"
303 See the {{SECT:SASL Authentication}} section for information on
304 SASL authentication identities.
307 H4: rootpw <password>
309 This directive can be used to specifies a password for the DN for
310 the rootdn (when the rootdn is set to a DN within the database).
316 It is also permissible to provide hash of the password in {{REF:RFC2307}}
317 form. {{slappasswd}}(8) may be used to generate the password hash.
321 > rootpw {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN
323 The hash was generated using the command {{EX:slappasswd -s secret}}.
326 H4: suffix <dn suffix>
328 This directive specifies the DN suffix of queries that will be
329 passed to this backend database. Multiple suffix lines can be
330 given, and at least one is required for each database
335 > suffix "dc=example,dc=com"
337 Queries with a DN ending in "dc=example,dc=com"
338 will be passed to this backend.
340 Note: When the backend to pass a query to is selected, slapd
341 looks at the suffix line(s) in each database definition in the
342 order they appear in the file. Thus, if one database suffix is a
343 prefix of another, it must appear after it in the config file.
348 > syncrepl rid=<replica ID>
349 > provider=ldap[s]://<hostname>[:port]
350 > [type=refreshOnly|refreshAndPersist]
351 > [interval=dd:hh:mm:ss]
352 > [retry=[<retry interval> <# of retries>]+]
353 > searchbase=<base DN>
354 > [filter=<filter str>]
355 > [scope=sub|one|base]
356 > [attrs=<attr list>]
358 > [sizelimit=<limit>]
359 > [timelimit=<limit>]
360 > [schemachecking=on|off]
361 > [bindmethod=simple|sasl]
364 > [authcid=<identity>]
365 > [authzid=<identity>]
366 > [credentials=<passwd>]
368 > [secprops=<properties>]
371 This directive specifies the current database as a replica of the
372 master content by establishing the current {{slapd}}(8) as a
373 replication consumer site running a syncrepl replication engine.
374 The master database is located at the replication provider site
375 specified by the {{EX:provider}} parameter. The replica database is
376 kept up-to-date with the master content using the LDAP Content
377 Synchronization protocol. See {{REF:RFC4533}}
378 for more information on the protocol.
380 The {{EX:rid}} parameter is used for identification of the current
381 {{EX:syncrepl}} directive within the replication consumer server,
382 where {{EX:<replica ID>}} uniquely identifies the syncrepl specification
383 described by the current {{EX:syncrepl}} directive. {{EX:<replica ID>}}
384 is non-negative and is no more than three decimal digits in length.
386 The {{EX:provider}} parameter specifies the replication provider site
387 containing the master content as an LDAP URI. The {{EX:provider}}
388 parameter specifies a scheme, a host and optionally a port where the
389 provider slapd instance can be found. Either a domain name or IP
390 address may be used for <hostname>. Examples are
391 {{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}.
392 If <port> is not given, the standard LDAP port number (389 or 636) is used.
393 Note that the syncrepl uses a consumer-initiated protocol, and hence its
394 specification is located at the consumer site, whereas the {{EX:replica}}
395 specification is located at the provider site. {{EX:syncrepl}} and
396 {{EX:replica}} directives define two independent replication
397 mechanisms. They do not represent the replication peers of each other.
399 The content of the syncrepl replica is defined using a search
400 specification as its result set. The consumer slapd will
401 send search requests to the provider slapd according to the search
402 specification. The search specification includes {{EX:searchbase}},
403 {{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:attrsonly}},
404 {{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal
405 search specification. The {{EX:searchbase}} parameter has no
406 default value and must always be specified. The {{EX:scope}} defaults
407 to {{EX:sub}}, the {{EX:filter}} defaults to {{EX:(objectclass=*)}},
408 {{EX:attrs}} defaults to {{EX:"*,+"}} to replicate all user and operational
409 attributes, and {{EX:attrsonly}} is unset by default. Both {{EX:sizelimit}}
410 and {{EX:timelimit}} default to "unlimited", and only integers
411 or "unlimited" may be specified.
413 The LDAP Content Synchronization protocol has two operation
414 types: {{EX:refreshOnly}} and {{EX:refreshAndPersist}}.
415 The operation type is specified by the {{EX:type}} parameter.
416 In the {{EX:refreshOnly}} operation, the next synchronization search operation
417 is periodically rescheduled at an interval time after each
418 synchronization operation finishes. The interval is specified
419 by the {{EX:interval}} parameter. It is set to one day by default.
420 In the {{EX:refreshAndPersist}} operation, a synchronization search
421 remains persistent in the provider slapd. Further updates to the
422 master replica will generate {{EX:searchResultEntry}} to the consumer slapd
423 as the search responses to the persistent synchronization search.
425 If an error occurs during replication, the consumer will attempt to reconnect
426 according to the retry parameter which is a list of the <retry interval>
427 and <# of retries> pairs. For example, retry="60 10 300 3" lets the consumer
428 retry every 60 seconds for the first 10 times and then retry every 300 seconds
429 for the next three times before stop retrying. + in <# of retries> means
430 indefinite number of retries until success.
432 The schema checking can be enforced at the LDAP Sync consumer site
433 by turning on the {{EX:schemachecking}} parameter.
434 If it is turned on, every replicated entry will be checked for its
435 schema as the entry is stored into the replica content.
436 Every entry in the replica should contain those attributes
437 required by the schema definition.
438 If it is turned off, entries will be stored without checking
439 schema conformance. The default is off.
441 The {{EX:binddn}} parameter gives the DN to bind as for the
442 syncrepl searches to the provider slapd. It should be a DN
443 which has read access to the replication content in the
446 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
447 depending on whether simple password-based authentication or
448 {{TERM:SASL}} authentication is to be used when connecting
449 to the provider slapd.
451 Simple authentication should not be used unless adequate data
452 integrity and confidentiality protections are in place (e.g. TLS
453 or IPsec). Simple authentication requires specification of {{EX:binddn}}
454 and {{EX:credentials}} parameters.
456 SASL authentication is generally recommended. SASL authentication
457 requires specification of a mechanism using the {{EX:saslmech}} parameter.
458 Depending on the mechanism, an authentication identity and/or
459 credentials can be specified using {{EX:authcid}} and {{EX:credentials}},
460 respectively. The {{EX:authzid}} parameter may be used to specify
461 an authorization identity.
463 The {{EX:realm}} parameter specifies a realm which a certain
464 mechanisms authenticate the identity within. The {{EX:secprops}}
465 parameter specifies Cyrus SASL security properties.
467 The syncrepl replication mechanism is supported by the two primary
468 database backends: back-bdb and back-hdb.
470 See the {{SECT:LDAP Sync Replication}} chapter of the admin guide
471 for more information on how to use this directive.
476 This directive is only applicable in a {{slave}} (or {{shadow}})
477 {{slapd}}(8) instance. It
478 specifies the URL to return to clients which submit update
479 requests upon the replica.
480 If specified multiple times, each {{TERM:URL}} is provided.
484 > updateref ldap://master.example.net
487 H3: BDB and HDB Database Directives
489 Directives in this category only apply to both the {{TERM:BDB}}
490 and the {{TERM:HDB}} database.
491 That is, they must follow a "database bdb" or "database hdb" line
493 subsequent "backend" or "database" line. For a complete reference
494 of BDB/HDB configuration directives, see {{slapd-bdb}}(5).
497 H4: directory <directory>
499 This directive specifies the directory where the BDB files
500 containing the database and associated indices live.
504 > directory /usr/local/var/openldap-data