2 # Copyright 1999-2017 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
5 H1: The slapd Configuration File
7 This chapter describes configuring {{slapd}}(8) via the {{slapd.conf}}(5)
8 configuration file. {{slapd.conf}}(5) has been deprecated and should
9 only be used if your site requires one of the backends that hasn't yet
10 been updated to work with the newer {{slapd-config}}(5) system. Configuring
11 {{slapd}}(8) via {{slapd-config}}(5) is described in the previous chapter.
13 The {{slapd.conf}}(5) file is normally installed in the
14 {{EX:/usr/local/etc/openldap}} directory. An alternate configuration
15 file location can be specified via a command-line option to {{slapd}}(8).
18 H2: Configuration File Format
20 The {{slapd.conf}}(5) file consists of three types of configuration
21 information: global, backend specific, and database specific. Global
22 information is specified first, followed by information associated
23 with a particular backend type, which is then followed by information
24 associated with a particular database instance. Global directives can
25 be overridden in backend and/or database directives, and backend directives
26 can be overridden by database directives.
28 Blank lines and comment lines beginning with a '{{EX:#}}' character
29 are ignored. If a line begins with whitespace, it is considered a
30 continuation of the previous line (even if the previous line is a
33 The general format of slapd.conf is as follows:
35 > # global configuration directives
36 > <global config directives>
38 > # backend definition
40 > <backend-specific directives>
42 > # first database definition & config directives
44 > <database-specific directives>
46 > # second database definition & config directives
48 > <database-specific directives>
50 > # second database definition & config directives
52 > <database-specific directives>
54 > # subsequent backend & database definitions & config directives
57 A configuration directive may take arguments. If so, they are
58 separated by whitespace. If an argument contains whitespace,
59 the argument should be enclosed in double quotes {{EX:"like this"}}. If
60 an argument contains a double quote or a backslash character `{{EX:\}}',
61 the character should be preceded by a backslash character `{{EX:\}}'.
63 The distribution contains an example configuration file that will
64 be installed in the {{F: /usr/local/etc/openldap}} directory.
65 A number of files containing schema definitions (attribute types
66 and object classes) are also provided in the
67 {{F: /usr/local/etc/openldap/schema}} directory.
70 H2: Configuration File Directives
72 This section details commonly used configuration directives. For
73 a complete list, see the {{slapd.conf}}(5) manual page. This section
74 separates the configuration file directives into global,
75 backend-specific and data-specific categories, describing each
76 directive and its default value (if any), and giving an example of
83 Directives described in this section apply to all backends
84 and databases unless specifically overridden in a backend or
85 database definition. Arguments that should be replaced
86 by actual text are shown in brackets {{EX:<>}}.
89 H4: access to <what> [ by <who> [<accesslevel>] [<control>] ]+
91 This directive grants access (specified by <accesslevel>) to a set
92 of entries and/or attributes (specified by <what>) by one or more
93 requestors (specified by <who>). See the {{SECT:Access Control}} section of
94 this guide for basic usage.
97 More details discussion of this directive can be found in the
98 {{SECT:Advanced Access Control}} chapter.
101 Note: If no {{EX:access}} directives are specified, the default
102 access control policy, {{EX:access to * by * read}}, allows all
103 both authenticated and anonymous users read access.
106 H4: attributetype <{{REF:RFC4512}} Attribute Type Description>
108 This directive defines an attribute type.
109 Please see the {{SECT:Schema Specification}} chapter
110 for information regarding how to use this directive.
112 H4: idletimeout <integer>
114 Specify the number of seconds to wait before forcibly closing
115 an idle client connection. An idletimeout of 0, the default,
116 disables this feature.
119 H4: include <filename>
121 This directive specifies that slapd should read additional
122 configuration information from the given file before continuing
123 with the next line of the current file. The included file should
124 follow the normal slapd config file format. The file is commonly
125 used to include files containing schema specifications.
127 Note: You should be careful when using this directive - there is
128 no small limit on the number of nested include directives, and no
129 loop detection is done.
133 This directive specifies the level at which debugging statements
134 and operation statistics should be syslogged (currently logged to
135 the {{syslogd}}(8) {{EX:LOG_LOCAL4}} facility). You must have
136 configured OpenLDAP {{EX:--enable-debug}} (the default) for this
137 to work (except for the two statistics levels, which are always
138 enabled). Log levels may be specified as integers or by keyword.
139 Multiple log levels may be used and the levels are additive. To display what
140 numbers correspond to what kind of debugging, invoke slapd with {{EX:-d?}}
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"
145 Level Keyword Description
146 -1 any enable all debugging
148 1 (0x1 trace) trace function calls
149 2 (0x2 packets) debug packet handling
150 4 (0x4 args) heavy trace debugging
151 8 (0x8 conns) connection management
152 16 (0x10 BER) print out packets sent and received
153 32 (0x20 filter) search filter processing
154 64 (0x40 config) configuration processing
155 128 (0x80 ACL) access control list processing
156 256 (0x100 stats) stats log connections/operations/results
157 512 (0x200 stats2) stats log entries sent
158 1024 (0x400 shell) print communication with shell backends
159 2048 (0x800 parse) print entry parsing debugging
160 16384 (0x4000 sync) syncrepl consumer processing
161 32768 (0x8000 none) only messages that get logged whatever log level is set
164 The desired log level can be input as a single integer that
165 combines the (ORed) desired levels, both in decimal or in hexadecimal
166 notation, as a list of integers (that are ORed internally), or as a list of the names that are shown between brackets, such that
180 This will cause lots and lots of debugging information to be
183 E: loglevel conns filter
185 Just log the connection and search filter processing.
189 Log those messages that are logged regardless of the configured loglevel. This
190 differs from setting the log level to 0, when no logging occurs. At least the
191 {{EX:None}} level is required to have high priority messages logged.
197 Basic stats logging is configured by default. However, if no loglevel is
198 defined, no logging occurs (equivalent to a 0 level).
200 H4: objectclass <{{REF:RFC4512}} Object Class Description>
202 This directive defines an object class.
203 Please see the {{SECT:Schema Specification}} chapter for
204 information regarding how to use this directive.
209 This directive specifies the referral to pass back when slapd
210 cannot find a local database to handle a request.
214 > referral ldap://root.openldap.org
216 This will refer non-local queries to the global root LDAP server
217 at the OpenLDAP Project. Smart LDAP clients can re-ask their
218 query at that server, but note that most of these clients are
219 only going to know how to handle simple LDAP URLs that
220 contain a host part and optionally a distinguished name part.
223 H4: sizelimit <integer>
225 This directive specifies the maximum number of entries to return
226 from a search operation.
232 See the {{SECT:Limits}} section of this guide and {{slapd.conf}}(5)
235 H4: timelimit <integer>
237 This directive specifies the maximum number of seconds (in real
238 time) slapd will spend answering a search request. If a
239 request is not finished in this time, a result indicating an
240 exceeded timelimit will be returned.
246 See the {{SECT:Limits}} section of this guide and {{slapd.conf}}(5)
250 H3: General Backend Directives
252 Directives in this section apply only to the backend in which
253 they are defined. They are supported by every type of backend.
254 Backend directives apply to all databases instances of the
255 same type and, depending on the directive, may be overridden
256 by database directives.
260 This directive marks the beginning of a backend declaration.
261 {{EX:<type>}} should be one of the
262 supported backend types listed in Table 6.2.
264 !block table; align=Center; coltags="EX,N"; \
265 title="Table 6.2: Database Backends"
267 bdb Berkeley DB transactional backend (deprecated)
268 dnssrv DNS SRV backend
269 hdb Hierarchical variant of bdb backend (deprecated)
270 ldap Lightweight Directory Access Protocol (Proxy) backend
271 mdb Memory-Mapped DB backend
272 meta Meta Directory backend
273 monitor Monitor backend
274 passwd Provides read-only access to {{passwd}}(5)
275 perl Perl Programmable backend
276 shell Shell (extern program) backend
277 sql SQL Programmable backend
284 This marks the beginning of a new {{TERM:BDB}} backend
288 H3: General Database Directives
290 Directives in this section apply only to the database in which
291 they are defined. They are supported by every type of database.
295 This directive marks the beginning of a database instance
297 {{EX:<type>}} should be one of the
298 supported backend types listed in Table 6.2.
304 This marks the beginning of a new {{TERM:BDB}} database instance
308 H4: limits <selector> <limit> [<limit> [...]]
310 Specify time and size limits based on the operation's initiator or base
313 See the {{SECT:Limits}} section of this guide and {{slapd.conf}}(5)
317 H4: readonly { on | off }
319 This directive puts the database into "read-only" mode. Any
320 attempts to modify the database will return an "unwilling to
321 perform" error. If set on a consumer, modifications sent by
322 syncrepl will still occur.
331 This directive specifies the DN that is not subject to
332 access control or administrative limit restrictions for
333 operations on this database. The DN need not refer to
334 an entry in this database or even in the directory. The
335 DN may refer to a SASL identity.
339 > rootdn "cn=Manager,dc=example,dc=com"
343 > rootdn "uid=root,cn=example.com,cn=digest-md5,cn=auth"
345 See the {{SECT:SASL Authentication}} section for information on
346 SASL authentication identities.
349 H4: rootpw <password>
351 This directive can be used to specifies a password for the DN for
352 the rootdn (when the rootdn is set to a DN within the database).
358 It is also permissible to provide hash of the password in {{REF:RFC2307}}
359 form. {{slappasswd}}(8) may be used to generate the password hash.
363 > rootpw {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN
365 The hash was generated using the command {{EX:slappasswd -s secret}}.
368 H4: suffix <dn suffix>
370 This directive specifies the DN suffix of queries that will be
371 passed to this backend database. Multiple suffix lines can be
372 given, and at least one is required for each database
377 > suffix "dc=example,dc=com"
379 Queries with a DN ending in "dc=example,dc=com"
380 will be passed to this backend.
382 Note: When the backend to pass a query to is selected, slapd
383 looks at the suffix line(s) in each database definition in the
384 order they appear in the file. Thus, if one database suffix is a
385 prefix of another, it must appear after it in the config file.
390 > syncrepl rid=<replica ID>
391 > provider=ldap[s]://<hostname>[:port]
392 > searchbase=<base DN>
393 > [type=refreshOnly|refreshAndPersist]
394 > [interval=dd:hh:mm:ss]
395 > [retry=[<retry interval> <# of retries>]+]
396 > [filter=<filter str>]
397 > [scope=sub|one|base]
398 > [attrs=<attr list>]
399 > [exattrs=<attr list>]
401 > [sizelimit=<limit>]
402 > [timelimit=<limit>]
403 > [schemachecking=on|off]
404 > [network-timeout=<seconds>]
405 > [timeout=<seconds>]
406 > [bindmethod=simple|sasl]
409 > [authcid=<identity>]
410 > [authzid=<identity>]
411 > [credentials=<passwd>]
413 > [secprops=<properties>]
414 > [keepalive=<idle>:<probes>:<interval>]
415 > [starttls=yes|critical]
418 > [tls_cacert=<file>]
419 > [tls_cacertdir=<path>]
420 > [tls_reqcert=never|allow|try|demand]
421 > [tls_cipher_suite=<ciphers>]
422 > [tls_crlcheck=none|peer|all]
423 > [tls_protocol_min=<major>[.<minor>]]
424 > [suffixmassage=<real DN>]
425 > [logbase=<base DN>]
426 > [logfilter=<filter str>]
427 > [syncdata=default|accesslog|changelog]
430 This directive specifies the current database as a replica of the
431 master content by establishing the current {{slapd}}(8) as a
432 replication consumer site running a syncrepl replication engine.
433 The master database is located at the replication provider site
434 specified by the {{EX:provider}} parameter. The replica database is
435 kept up-to-date with the master content using the LDAP Content
436 Synchronization protocol. See {{REF:RFC4533}}
437 for more information on the protocol.
439 The {{EX:rid}} parameter is used for identification of the current
440 {{EX:syncrepl}} directive within the replication consumer server,
441 where {{EX:<replica ID>}} uniquely identifies the syncrepl specification
442 described by the current {{EX:syncrepl}} directive. {{EX:<replica ID>}}
443 is non-negative and is no more than three decimal digits in length.
445 The {{EX:provider}} parameter specifies the replication provider site
446 containing the master content as an LDAP URI. The {{EX:provider}}
447 parameter specifies a scheme, a host and optionally a port where the
448 provider slapd instance can be found. Either a domain name or IP
449 address may be used for <hostname>. Examples are
450 {{EX:ldap://provider.example.com:389}} or {{EX:ldaps://192.168.1.1:636}}.
451 If <port> is not given, the standard LDAP port number (389 or 636) is used.
452 Note that the syncrepl uses a consumer-initiated protocol, and hence its
453 specification is located at the consumer site, whereas the {{EX:replica}}
454 specification is located at the provider site. {{EX:syncrepl}} and
455 {{EX:replica}} directives define two independent replication
456 mechanisms. They do not represent the replication peers of each other.
458 The content of the syncrepl replica is defined using a search
459 specification as its result set. The consumer slapd will
460 send search requests to the provider slapd according to the search
461 specification. The search specification includes {{EX:searchbase}},
462 {{EX:scope}}, {{EX:filter}}, {{EX:attrs}}, {{EX:exattrs}}, {{EX:attrsonly}},
463 {{EX:sizelimit}}, and {{EX:timelimit}} parameters as in the normal
464 search specification. The {{EX:searchbase}} parameter has no
465 default value and must always be specified. The {{EX:scope}} defaults
466 to {{EX:sub}}, the {{EX:filter}} defaults to {{EX:(objectclass=*)}},
467 {{EX:attrs}} defaults to {{EX:"*,+"}} to replicate all user and operational
468 attributes, and {{EX:attrsonly}} is unset by default. Both {{EX:sizelimit}}
469 and {{EX:timelimit}} default to "unlimited", and only positive integers
470 or "unlimited" may be specified. The {{EX:exattrs}} option may also be used
471 to specify attributes that should be omitted from incoming entries.
473 The {{TERM[expand]LDAP Sync}} protocol has two operation
474 types: {{EX:refreshOnly}} and {{EX:refreshAndPersist}}.
475 The operation type is specified by the {{EX:type}} parameter.
476 In the {{EX:refreshOnly}} operation, the next synchronization search operation
477 is periodically rescheduled at an interval time after each
478 synchronization operation finishes. The interval is specified
479 by the {{EX:interval}} parameter. It is set to one day by default.
480 In the {{EX:refreshAndPersist}} operation, a synchronization search
481 remains persistent in the provider {{slapd}} instance. Further updates to the
482 master replica will generate {{EX:searchResultEntry}} to the consumer slapd
483 as the search responses to the persistent synchronization search.
485 If an error occurs during replication, the consumer will attempt to reconnect
486 according to the retry parameter which is a list of the <retry interval>
487 and <# of retries> pairs. For example, retry="60 10 300 3" lets the consumer
488 retry every 60 seconds for the first 10 times and then retry every 300 seconds
489 for the next three times before stop retrying. + in <# of retries> means
490 indefinite number of retries until success.
492 The schema checking can be enforced at the LDAP Sync consumer site
493 by turning on the {{EX:schemachecking}} parameter.
494 If it is turned on, every replicated entry will be checked for its
495 schema as the entry is stored into the replica content.
496 Every entry in the replica should contain those attributes
497 required by the schema definition.
498 If it is turned off, entries will be stored without checking
499 schema conformance. The default is off.
501 The {{EX:network-timeout}} parameter sets how long the consumer will
502 wait to establish a network connection to the provider. Once a
503 connection is established, the {{EX:timeout}} parameter determines how
504 long the consumer will wait for the initial Bind request to complete. The
505 defaults for these parameters come from {{ldap.conf}}(5).
507 The {{EX:binddn}} parameter gives the DN to bind as for the
508 syncrepl searches to the provider slapd. It should be a DN
509 which has read access to the replication content in the
512 The {{EX:bindmethod}} is {{EX:simple}} or {{EX:sasl}},
513 depending on whether simple password-based authentication or
514 {{TERM:SASL}} authentication is to be used when connecting
515 to the provider {{slapd}} instance.
517 Simple authentication should not be used unless adequate data
518 integrity and confidentiality protections are in place (e.g. TLS
519 or IPsec). Simple authentication requires specification of {{EX:binddn}}
520 and {{EX:credentials}} parameters.
522 SASL authentication is generally recommended. SASL authentication
523 requires specification of a mechanism using the {{EX:saslmech}} parameter.
524 Depending on the mechanism, an authentication identity and/or
525 credentials can be specified using {{EX:authcid}} and {{EX:credentials}},
526 respectively. The {{EX:authzid}} parameter may be used to specify
527 an authorization identity.
529 The {{EX:realm}} parameter specifies a realm which a certain
530 mechanisms authenticate the identity within. The {{EX:secprops}}
531 parameter specifies Cyrus SASL security properties.
533 The {{EX:keepalive} parameter sets the values of idle, probes, and interval
534 used to check whether a socket is alive; idle is the number of seconds a
535 connection needs to remain idle before TCP starts sending keepalive probes;
536 probes is the maximum number of keepalive probes TCP should send before
537 dropping the connection; interval is interval in seconds between individual
538 keepalive probes. Only some systems support the customization of these
539 values; the keepalive parameter is ignored otherwise, and system-wide
540 settings are used. For example, keepalive="240:10:30" will send a keepalive
541 probe 10 times, every 30 seconds, after 240 seconds of idle activity. If
542 no response to the probes is received, the connection will be dropped.
544 The {{EX:starttls}} parameter specifies use of the StartTLS extended
545 operation to establish a TLS session before authenticating to the provider.
546 If the {{EX:critical}} argument is supplied, the session will be aborted
547 if the StartTLS request fails. Otherwise the syncrepl session continues
548 without TLS. The tls_reqcert setting defaults to {{EX:"demand"}} and the
549 other TLS settings default to the same as the main slapd TLS settings.
551 The {{EX:suffixmassage}} parameter allows the consumer to pull entries
552 from a remote directory whose DN suffix differs from the local directory.
553 The portion of the remote entries' DNs that matches the searchbase will
554 be replaced with the suffixmassage DN.
556 Rather than replicating whole entries, the consumer can query logs
557 of data modifications. This mode of operation is referred to as
558 {{delta syncrepl}}. In addition to the above parameters, the
559 {{EX:logbase}} and {{EX:logfilter}} parameters must be set appropriately
560 for the log that will be used. The {{EX:syncdata}} parameter must
561 be set to either {{EX:"accesslog"}} if the log conforms to the
562 {{slapo-accesslog}}(5) log format, or {{EX:"changelog"}} if the log
563 conforms to the obsolete {{changelog}} format. If the {{EX:syncdata}}
564 parameter is omitted or set to {{EX:"default"}} then the log
565 parameters are ignored.
567 The {{syncrepl}} replication mechanism is supported by the {{bdb}},
568 {{hdb}}, and {{mdb}} backends.
570 See the {{SECT:LDAP Sync Replication}} chapter of this guide for
571 more information on how to use this directive.
576 This directive is only applicable in a {{slave}} (or {{shadow}})
577 {{slapd}}(8) instance. It
578 specifies the URL to return to clients which submit update
579 requests upon the replica.
580 If specified multiple times, each {{TERM:URL}} is provided.
584 > updateref ldap://master.example.net
587 H3: BDB and HDB Database Directives
589 Directives in this category only apply to both the {{TERM:BDB}}
590 and the {{TERM:HDB}} database.
591 That is, they must follow a "database bdb" or "database hdb" line
593 subsequent "backend" or "database" line. For a complete reference
594 of BDB/HDB configuration directives, see {{slapd-bdb}}(5).
597 H4: directory <directory>
599 This directive specifies the directory where the BDB files
600 containing the database and associated indices live.
604 > directory /usr/local/var/openldap-data
607 H2: Configuration File Example
609 The following is an example configuration file, interspersed
610 with explanatory text. It defines two databases to handle
611 different parts of the {{TERM:X.500}} tree; both are {{TERM:BDB}}
612 database instances. The line numbers shown are provided for
613 reference only and are not included in the actual file. First, the
614 global configuration section:
616 E: 1. # example config file - global configuration section
617 E: 2. include /usr/local/etc/schema/core.schema
618 E: 3. referral ldap://root.openldap.org
619 E: 4. access to * by * read
621 Line 1 is a comment. Line 2 includes another config file
622 which contains {{core}} schema definitions.
623 The {{EX:referral}} directive on line 3
624 means that queries not local to one of the databases defined
625 below will be referred to the LDAP server running on the
626 standard port (389) at the host {{EX:root.openldap.org}}.
628 Line 4 is a global access control. It applies to all
629 entries (after any applicable database-specific access
632 The next section of the configuration file defines a BDB
633 backend that will handle queries for things in the
634 "dc=example,dc=com" portion of the tree. The
635 database is to be replicated to two slave slapds, one on
636 truelies, the other on judgmentday. Indices are to be
637 maintained for several attributes, and the {{EX:userPassword}}
638 attribute is to be protected from unauthorized access.
640 E: 5. # BDB definition for the example.com
642 E: 7. suffix "dc=example,dc=com"
643 E: 8. directory /usr/local/var/openldap-data
644 E: 9. rootdn "cn=Manager,dc=example,dc=com"
646 E: 11. # indexed attribute definitions
647 E: 12. index uid pres,eq
648 E: 13. index cn,sn pres,eq,approx,sub
649 E: 14. index objectClass eq
650 E: 15. # database access control definitions
651 E: 16. access to attrs=userPassword
653 E: 18. by anonymous auth
654 E: 19. by dn.base="cn=Admin,dc=example,dc=com" write
658 E: 23. by dn.base="cn=Admin,dc=example,dc=com" write
661 Line 5 is a comment. The start of the database definition is marked
662 by the database keyword on line 6. Line 7 specifies the DN suffix
663 for queries to pass to this database. Line 8 specifies the directory
664 in which the database files will live.
666 Lines 9 and 10 identify the database {{super-user}} entry and associated
667 password. This entry is not subject to access control or size or
668 time limit restrictions.
670 Lines 12 through 14 indicate the indices to maintain for various
673 Lines 16 through 24 specify access control for entries in this
674 database. For all applicable entries, the {{EX:userPassword}} attribute is writable
675 by the entry itself and by the "admin" entry. It may be used for
676 authentication/authorization purposes, but is otherwise not readable.
677 All other attributes are writable by the entry and the "admin"
678 entry, but may be read by all users (authenticated or not).
680 The next section of the example configuration file defines another
681 BDB database. This one handles queries involving the
682 {{EX:dc=example,dc=net}} subtree but is managed by the same entity
683 as the first database. Note that without line 39, the read access
684 would be allowed due to the global access rule at line 4.
686 E: 33. # BDB definition for example.net
688 E: 35. suffix "dc=example,dc=net"
689 E: 36. directory /usr/local/var/openldap-data-net
690 E: 37. rootdn "cn=Manager,dc=example,dc=com"
691 E: 38. index objectClass eq
692 E: 39. access to * by users read