Chapter 6. LDAP Configuration

This chapter describes, in mind-numbing detail, all parameters and attributes/directives used to control the LDAP systems covered in this Guide (well, eventually it will). Specifically OpenLDAP's OLC (cn=config) and slapd.conf (Server configuration), OpenLDAP's ldap.conf (Client and some Server configuration) and ApacheDS configuration (server.xml).

If you want to get something simple going for OpenLDAP use the samples.

Significant changes to slapd were introduced with version 2.3 and 2.4. The most significant change is that, while slapd.conf is still supported (as of 2.4), increasingly OpenLDAP is moving toward On-Line Configuration (OLC) - frequently also known as cn=config or slapd.d configuration. This method enables most configuration changes to be made without starting and stopping the LDAP server. Converting to, and using, OLC (cn=config) is documented and will increasingly become the normal method of describing configuration in this guide. In general the equivalent cn=config entry consists of the slapd.conf directive name preceded by "olc", as an example the Access directive becomes olcAccess when used in cn=config systems.

Contents

1. 6.1 Configuration Overview
   1. 6.1.1 Using and converting to OLC (cn=config/slapd.d)
   2. 6.1.1.1 OLC (cn=config) Overview
   3. 6.1.1.2 Converting from slapd.conf to OLC (cn=config)
   4. 6.1.1.3 OLC (cn=config) Layout
   5. 6.1.1.4 Using OLC (cn=config)(Read, Modify)
      1. 6.1.1.4.1 OLC (cn=config)General Notes
      2. 6.1.1.4.2 Add/Delete Schemas using OLC (cn=schema,cn=config)
      3. 6.1.1.4.3 Add/Delete ACPs/ACLs using OLC (cn=config)
      4. 6.1.1.4.4 Add/Delete Modules using OLC (cn=module{0},cn=config)
      5. 6.1.1.4.5 Add/Delete Databases using OLC (olcDatabase={Z}xxx,cn=config)
      6. 6.1.1.4.6 Add/Delete overlays using OLC (olcOverlay={Z}xxx,olcDatabase= {Z}xxx,cn=config)
2. 6.2 List of attributes (OLC (cn=config)) or Directives ( slapd.conf)
   
3. 6.3 Global Section attributes ((OLC (cn=config)) or Directives (slapd.conf)
4. 6.3.1 TLS attributes (OLC (cn=config)) or Directives (slapd.conf)
5. 6.4 Backend Section attributes (OLC (cn=config)) or Directives (slapd.conf)
6. 6.5 Database Section attributes (OLC (cn=config)) or Directives (slapd.conf)
7. 6.5.1 Overlay attributes (OLC (cn=config)) or Directives (slapd.conf)
8. 6.6 ldap.conf Directives
9. 6.7 ApacheDS Configuration

Note: slapd daemon command line options.

6.1 Configuration Overview

Configuration parameters are divided into global and database or (DIT) specific. The following notes may be useful:

1. OpenLDAP version 2.3 introduced a significant, but as of 2.4 optional, change to the method by which configuration changes may be applied to slapd. From version 2.3 the existing slapd.conf file may continue to be used OR a one-time conversion may be made to on-line configuration (OLC) - variously and confusing known as zero down-time configuration, cn=config or slapd.d configuration and which, for brevity, this guide refers to as simply OLC. In summary, the equivalent OLC (cn=config) attribute typically (there are two or three gotchas) consists of the slapd.conf directive name preceded by "olc", as an example the Access directive becomes olcAccess when used in OLC (cn=config) systems. In the descriptions that follow both the OLC (cn=config) attribute and slapd.conf directive form are shown. The procedures, effects, conversion and usage are described. OLC (cn=config) layout and entries.

2. Global attributes (or global slapd.conf Directives) apply to the LDAP server. They typically include environmental parameters, such as the location of files. In OLC they are defined using the olcGlobal objectClass in the cn=config entry.

3. Attributes/Directives form a strict hierarchy: global can be overridden by backend or database directives, backend can be overridden by database directives. If a attribute/directive is specified in a global section and is not overridden its scope (influence) is all the lower sections (backend and database).

4. In slapd.conf files all lines beginning with # are ignored and assumed to be comments

5. In slapd.conf files blank lines are ignored - BUT lines beginning with a space are assumed to be the continuation of the previous line. This can have painful consequences. Be very careful. In general slapd.conf is very picky about spaces and blanks.

6. Every DIT and its properties is defined in a database entry (using a base objectClass of olcDatabaseConfig or slapd.conf file section.

7. There must be one database entry (or slapd.conf section) for each DIT, for example, if two root DNs are required such as dc=example,dc=com and dc=example,dc=net then there will be two database entries (or slapd.conf sections). There can be any number of these entries (or slapd.conf sections). Each Database is numbered. see this section for OLC (cn=config) entry numbering. In slapd.conf the first database section is given the database number 1, the second 2 and so on.

8. Configuration information is normally located in:

   # OLC (cn=config)
   [fc] /etc/openldap/slapd.d
   [bsd] /usr/local/etc/openldap/slapd.d
   
   # slapd.conf
   [fc] /etc/openldap
   [bsd] /usr/local/etc/openldap
   

6.2 List of Attributes (OLC (cn=config)) or Directives (slapd.conf)

Unless otherwise noted all the attributes/directives below can appear in the global, backend or database entries/sections.

Global Attributes/Directives

olcAccess attribute (access to directive)
olcAllows attribute (allow directive)
olcArgsFile attribute (argsfile directive)
attributetype (olcAttributeTypes)
concurrency (olcConcurrency)
conn_max_pending (olcConnMaxPending)
conn_max_auth (olcConnMaxPendingAuth)
defaultaccess
defaultsearchbase (olcDefaultSearchBase)
disallow (olcDisallows)
gentlehup (olcGentleHUP)
idletimeout (olcIdleTimeout)
include
olcDbIndex (index)
logfile (olcLogFile)
loglevel (olcLogLevel)
olcModuleLoad (moduleload)
modulepath (olcModulePath)
objectclass (olcObjectClasses)
password-hash (olcPasswordHash)
pidfile (olcPidFile)
referral (olcReferral)
replicationinterval
require (olcRequires)
reverse-lookup (olcReverseLookup)
olcRootDSE (rootDSE)
olcSchemaDN (schemadn)
security (olcSecurity)
olcServerID (serverid)
sizelimit (olcSizeLimit)
sockbuf_max_incoming (olcSockBufMaxIncoming)
sockbuf_max_incoming_auth (olcSockBufMaxIncomingAuth)
threads (olcThreads)
timelimit (olcTimeLimit)

TLS/SSL Directives (Global Section)

TLS Server overview - what is a TLS Server

Server (Provider) Directives

TLSCACertificateFile (olcTLSCACertificateFile)
TLSCertificateFile (olcTLSCertificateFile)
TLSCertificateKeyFile (olcTLSCertificateKeyFile)
TLSCipherSuite (olcTLSCipherSuite)
TLSRandFile (olcTLSRandFile)
TLSEphemeralDHParamFile (olcTLSDHParamFile)
TLSVerifyClient (olcTLSVerifyClient)

Client (Consumer) Directives

TLS Server overview - what is a TLS Client
TLS_CACERT

Backend Directives

1. backend (olcBackend)

Database Directives

1. access to (olcAccess)
2. database (olcDatabase)
3. olcDbIndex (index)
4. mirrormode (olcMirrorMode)
5. overlay (olcOverlay)
6. readonly (olcReadOnly)
7. replica (olcReplica)
8. replogfile (olcReplogFile)
9. require (olcRequires)
10. rootdn (olcRootDN)
11. rootpw (olcRootPW)
12. suffix (olcSuffix)
13. syncrepl (olcSyncrepl)
14. updatedn (olcUpdateDN)
15. updateref (olcUpdateref)

6.3 Global Section Directives (OLC (cn=config) and slapd.conf)

In all appropriate cases the OLC (cn=config) form is shown first followed by the slapd.conf form in parentheses to reflect the move to OLC (cn=config) form of configuration. In OLC (cn=config) global attributes are defined in the cn=config entry using the olcGlobal objectclass. (See also OLC layout/entry format).

olcAccess (Access to)

Format:

olcAccess: to <what> [ by <who> [<accesslevel>] [<control>] ]+
access to <what> [ by <who> [<accesslevel>] [<control>] ]+

A set of olcAccess (access to) attributes/directives create what are known as either Access Control Lists (ACLs) or Access Control Policies (ACPs).

The olcAccess (access to) directive grants access (specified by <accesslevel>) to a set of entries and/or attributes (specified by <what>) by one or more requesters or requester characteristics (defined in by <who>). The optional <control> parameter defines an exit condition for each by <who> element and if not present defaults to the value stop.

One or more olcAccess (access to) attributes/directives may be included in either or both of the cn=config entry (global section) or a specific DIT (by inclusion in either the olcDatabase={Z}xxx,cn=config entry or a database section of slapd.conf). If the olcAccess (access to) attribute/directive is defined in the global entry/section then it is applied, additively, to any ACLs in all subsequent database section(s) (DITs). This feature can be either a useful shortcut or a nightmare.

olcaccess (access to) attributes/directives work by first matching the <what> condition. If that evaluates to a match then processing continues with each by <who> element. If any of these conditions match the optional <control> part is executed (defaults to stop) and the access control result is success. If, at the end of the olcAccess (access to) attribute/directive none of the by <who> conditions has been met then an implicit <control> of stop is assumed and the access control result is fail. If access to <what> fails to match then control is passed to the next ACL and the process repeats. If no more ACLs exist then an implicit <control> of stop is assumed and the access control result is fail.

The access directive (ACL) is brutally complex. It allows very fine control over who can access what objects and attributes and under what conditions. The side-effect of this complexity and power is that it is very easy to get olcAccess (access to) attributes/directives horribly wrong. You must thoroughly test ACL directives with all possible permissions. slapacl is an automated tool to test access to specific attributes and entries based on the current olcAccess (access to) attributes/directives.

The following section documents the raw parameters first, some of which include limited examples, then provides some worked examples which illustrate the major points. Perhaps the best way to understand this directive is to skim through the detail descriptions, go to the examples, then go back and re-read the detail section to clarify understanding. An alternative strategy is to follow the entire samples section (Chapter 5) which progressively add and use the ACLs described in the worked examples.

# assume supplied dn 
# is "ou=something,cn=my name,dc=example,dc=com"
# then $1 = 'my name' at end of match below
# because first regular expression does not have ()
access to dn.regex="ou=[^,]+,cn=([^,]+),dc=example,dc=com"
 by dn.exact,expand="cn=$1,dc=example,dc=com"

Examples:

# NOTE: These are snippets only - the dots (...) 
#       indicate that there may be more data
#       the dots should not be present on final directive

# access to the defined attributes
access to attrs=userpassword,homephone ...

# OPENLDAP UNTIL VERSION 2.1
# access to the defined DN and all lower levels
# type is missing so regex is defaulted
# covers all DNs below the defined DN as well
access to dn="ou=people,dc=example,dc=com" ...

# OPENLDAP FROM VERSION 2.2
# functionally equivalent to above from version 2.2
# and this format (no default) will work with versions
# prior to 2.2 as well
# access to the defined DN and all lower levels
access to dn.subtree="ou=people,dc=example,dc=com" ...

# access to one level below the defined DN only
access to dn.one="ou=people,dc=example,dc=com" ...

# access to one level below the defined DN only
# for attribute userpassword only
access to dn.one="ou=people,dc=example,dc=com" attrs=userpassword 
 ...

... by anonymous auth

access to 
 dn.regex="^cn=([^,]+),ou=People,dc=example,dc=com$"
# assume cn=my entry,ou=People,dc=example,dc=com
# $1 has the value 'my entry' which is substituted below
 by dn.exact,expand="cn=$1,ou=People,dc=example,dc=com" read

# the following two access to directives are 
# functionally identical and allow read access 
# to everything below example.com
 access to dn.children="dc=example,dc=com"
  by dn.base,expand="$0" read
	
access to dn.children="dc=example,dc=com"
  by dn.base,expand="$1" read

# simple IPv4 format
peername.ip=192.168.2.0

# IPv4 netmask format
peername.ip=192.168.2.0%255.255.255.0

# IPv4 from port 5000 only
peername.ip=192.168.2.0{5000}

# simple IPv6 format
peername.ipv6=2001:db8::1

# IPv6 from port 5000 only
peername.ipv6=2001:db8::1{5000)

# indicates the user requesting access 
# MUST be using a TLS/SSL session with a minimum 
# cipher key length of 40 (allows for EXPORT grade ciphers)
 by tls_ssf=40

# indicates the user requesting access 
# MUST be using a TLS/SSL session with a minimum 
# cipher key length of 128 (excludes EXPORT grade
# ciphers and many others e.g. DES)
 by tls_ssf=40
 
# indicates the user requesting access 
# MUST be using SASL with any cipher (don't care)
 by sasl_ssf=1
 
# indicates the user requesting access 
# MUST be using either SASL or TLS/SSL with a cipher
# key length of 64 or greater
 by ssf=64

[self]{<level>|<priv>}

{=|+|-}{w|r|s|c|x}+

And that is all there is to the access directive. Pretty simple really!

olcAccess (Access to) worked examples

1. Introductory notes
2. Default Access
3. Limiting Access to Authenticated Users
4. Using Groups to control Access
5. Public and Private Address Books

Introductory Notes

First some general notes about olcAccess (access to) attributes/directives:

1. If the binding is to the olcRootDN (rootdn) of the DIT (the superuser) then it is assumed to have magical powers and all ACL rules are ignored. The olcRootDN/rootdn can do anything to anything. No holds barred.

2. If there is no olcAccess (access) attribute/directive OpenLDAP defaults to:

   access to *
          by anonymous  read
          by *          none
   

   Explanation:

   1. access to * means the policy applies to all attributes and entries in the DIT.
   2. by anonymous read means anyone (unauthenticated) can read any DIT value including passwords.
   3. by * none indicates that any user (*) has no access privileges. OpenLDAP also implicitly terminates every access directive with this rule (whether present or not) to close any remaining doors - anything not covered by a preceding clause can do nothing. Given only this access directive (or no access directive which defaults to this one) only the rootdn (superuser) and its rootpw could be used to write to the DIT.

3. In any parameter formats which contain dnstyle and where dnstyle is defined as regex (regular expression) the supplied pattern is used in regular expression matching so dn="dc=example,dc=com" will apply to all subtree entries, for instance, "ou=people,dc=example,dc=com" but will use a lot of CPU power to achieve the same result as dn.subtree="dc=example,dc=com". It is always wise to avoid the use of regex if another format can be used even if it means more than one directive.

4. access directives are processed each time a directory access is made starting with the first one defined - order is very important - and are additive. The seconds adds to the functionality of the first and so on. The ACL checking stops as soon as a by <who> rule is hit that grants access or rejects access.

5. access directive style. The format allowed is freeform and to simplify understanding may be written as:

   access to <parameters>
          by <parameters>
          by <parameters>
          ...
   

   Note 1: Each new line within the directive must be indented by at least one space.

   Note 2: While the layout of the olcAccess (access to) attribute/directive is very flexible you cannot place comments (lines beginning with #) anywhere within an olcAccess (access to) attribute/directive.

6. One or more olcAccess (access) attributes/directives may be present and each by <who> rule may have a <control>. Example:

   # Access directive 1
   # OLC (cn=config form
   olcAccess: to <what>
          by <who1> break
          by <who2> read
          ...
   # slapd.conf form
   access to <what>
          by <who1> break
          by <who2> read
          ...
   # Access directive 2
   access to <what>
          by <who> write
   

   Explanation:

   1. In Access directive 1, if the by <who1> break condition is met (true) then processing will immediately move to Access directive 2. The break indicates 'go to next ACL'.
   2. In Access directive 1, if the by <who2> read condition is met (true) processing will stop with a result of success and Access directive 2 will not be executed. The value stop is defaulted in the absence of any explicit <control> value. This line could have written as by <who2> read stop if that makes it more understandable.

7. Each olcAccess (access) attribute/directive is terminated by the (normally) silent by * none stop. Conditions not satisfied by preceding by <who> clauses will thus terminate processing. Especially when using global olcAccess (access) attributes/directives (though in other conditions as well) this may not have the intended consequences, thus given:

   # global section
   # Access directive 1
   # OLC (cn=config) form
   olcAccess: to <what>
          by <who1> read
          ...
   #slapd.conf form
   access to <what>
          by <who1> read
          ...
   # database section
   # Access directive 2
   access to <what>
          by <who> write
   

   In Access directive 1, if the by <who1> condition is not met (false) then processing will stop and the Access directive 2 will never be accessed.

   To enable Access directive 2 for all processing which does not meet by <who1> the following form should be used:

   # global section
   # Access directive 1
   access to <what>
          by <who1> read
          by * break
          ...
   # database section
   # Access directive 2
   access to <what>
          by <who> write
   

   The break in Access directive 1 will cause all values that fail the by <who1> to proceed to Access directive 2 with no rights granted.

Examples

Limiting Access to Authenticated users

These ACLs are progressively introduced in the samples samples (Chapter 5) to progressively limit access to the target DIT.

Policy: We will force all users to authenticate, disallow access to the password for everyone except the entries owner, allow only the owner to write to (update) their entry, all other authenticated users can read all entries (except password as noted above). This example assumes at least the person objectclass (for userpassword):

# ACL1
# OLC (cn=config) form
olcAccess: to attrs=userpassword
       by self       write
       by anonymous  auth
       by *          none
# slapd.conf form
access to attrs=userpassword
       by self       write
       by anonymous  auth
       by *          none
# ACL2
access to *
       by self       write
       by users      read
       by *          none

Explanation:

1. ACL1

   1. ACL1 access to attrs=password means this policy applies to the attribute userpassword only.
   2. ACL1 by self write grants only the owner of the entry (they authenticated with the userpassword of this entry) write permission to this attribute.
   3. ACL1 by anonymous auth grants an anonymous user access to this attribute only for authentication purposes (it is used internally by OpenLDAP to authenticate).
   4. ACL1 by * none means that anything not covered by a previous clause is not permitted, thus any non-owner cannot write to userpassword and even authenticated users cannot read the attribute (no read access is granted).

2. ACL2

   1. ACL2 access to * Because access directives are additive this directive means this policy applies to all attributes except userpassword because it was previously defined to have its own rules.
   2. ACL2 by self write grants only the owner of the entry write permission to the attributes covered by this directive. Since ACL1 granted self access to the attribute userpassword the owner can write all the attributes of their entry.
   3. ACL2 by users read grants any authenticated user read permission to all the attributes covered by this policy (all except those defined by ACL1 i.e. userpassword). If we had wanted to grant full anonymous read permission (except to userpassword) we could have used by anonymous read.
   4. ACL2 by * none in this case it means that any non-owner cannot write to any attribute and non-authenticated users cannot read, search or perform any operations on any entry or attribute.

Anonymous access locally

This example forces all external users to authenticate, allows local network users anonymous read access, disallows access to the password for everyone except the entries owner, allows only the owner to write to (update) their entry. All other authenticated users can read all entries (except password as noted above). This example assumes at least the person objectclass (for userpassword) and assumes that the local network is on the class b private network address 192.168.1.0 - 255 (192.168.1.0/24):

# ACL1
# OLC (cn=config) form
olcAccess: to attrs=userpassword
       by self                 write
       by anonymous            auth
       by *                    none
# slapd.conf form
access to attrs=userpassword
       by self                 write
       by anonymous            auth
       by *                    none
# ACL2
access to *
       by self                 write
       by users                read
       by peername=192.168.1.* read
       by *                    none

Explanation:

1. ACL1

   1. ACL1 access to attrs=password means this policy applies to the attribute userpassword only.
   2. ACL1 by self write grants only the owner of the entry (they authenticated with the userpassword of this entry) write permission to this attribute.
   3. ACL1 by anonymous auth grants an anonymous user access to this attribute only for authentication purposes (it is used internally by OpenLDAP to authenticate).
   4. ACL1 by * none in this case it means that any non-owner cannot write to userpassword and any authenticated users cannot read the attribute (no read access is granted).

2. ACL2

   1. ACL2 access to * Because access directives are additive this directive means this policy applies to all attributes except userpassword because it was previously defined to have its own rules.
   2. ACL2 by self write grants only the owner of the entry write permission to the attributes covered by this directive (all). Since ACL1 granted self access to the attribute userpassword the owner can write all the attributes.
   3. ACL2 by users read grants any authenticated user read permission to all the attributes covered by this policy (all except those defined by ACL1 i.e. userpassword). If we had wanted to grant full anonymous read permission (except to userpassword) we could have used by anonymous read.
   4. ACL2 by peername=192.168.1.* grants any user on the local network (192.168.1.0 to 192.168.1.255) anonymous read permission to all the attributes covered by this policy (all except those defined by ACL1 i.e. userpassword). This directive uses a regular expression test we could have written it as peername.regex=192.168.1.*.
   5. ACL2 by * none in this case it means that any non-owner cannot write to any attribute and any non-authenticated users cannot read, search or perform any operations on any entry or attribute.

Limiting Access to Parts of the DIT

Building an Access Control Policy (ACP a.k.a. ACL) based on a Corporate Policy (wow) which states:

1. The directory entry owner is able to see and update ALL the directory attributes including passwords.

2. Human Resources must be able to update ANY entry but must not be able to read or write the users password.

3. The Directory entries carlicence, homepostaddress and homephone must not be readable by anyone except human resources and the owner of the directory entry.

4. All users must authenticate (anonymous access is not allowed).

5. The IT department must be able to update or change the password entry on all directory entries.

This example assumes at least the inetorgperson objectclass (for carlicense and other attributes) and we assume that two groups of users called hrpeople and itpeople exist:

# ACL1
# OLC (cn=config) form
olcAccess: to attrs=userpassword
       by self       write
       by anonymous  auth
       by group.exact="cn=itpeople,ou=groups,dc=example,dc=com"
                     write
       by *          none
# slapd.conf form
access to attrs=userpassword
       by self       write
       by anonymous  auth
       by group.exact="cn=itpeople,ou=groups,dc=example,dc=com"
                     write
       by *          none
# ACL2
access to attrs=carlicense,homepostaladdress,homephone
       by self       write
       by group.exact="cn=hrpeople,ou=groups,dc=example,dc=com"
                     write
       by *          none
# ACL3
access to *
       by self       write
       by group.exact="cn=hrpeople,ou=groups,dc=example,dc=com"
                     write
       by users      read
       by *          none

Explanation:

1. ACL1

   1. ACL1 access to attrs=password means this policy applies to the attribute userpassword only.
   2. ACL1 by self write grants the owner of the entry (they authenticated with the userpassword of this entry) write permission to this attribute.
   3. ACL1 by anonymous auth grants any user access to this attribute only for authentication purposes (it is used internally by OpenLDAP to authenticate and is not visible externally).
   4. ACL1 by group.exact="cn=itpeople,ou=groups,dc=example,dc=com" write grants write permission to this attribute to any member of the itpeople group. exact improves performance by removing the default regex if it were not present.
   5. ACL1 by * none in this case it means that any non-owner or non itpeople group cannot write to userpassword and any other authenticated users cannot read the attribute (no read access is granted).

2. ACL2

   1. ACL2 access to attrs=carlicense,homepostaladdress,homephone means this policy applies to these attributes only.
   2. ACL2 by self write grants the owner of the entry (they authenticated with the userpassword of this entry) write permission to these attributes.
   3. ACL2 by group.exact="cn=hrpeople,ou=groups,dc=example,dc=com" write grants write permission to this attribute to any member of the hrpeople group.
   4. ACL2 by * none in this case it means that any non-owner or non hrpeople group cannot write to the attributes and any other authenticated users cannot read the attribute (no read access is granted).

3. ACL3

   1. ACL3 access to * Because access directives are additive this directive means this policy applies to all attributes except userpassword, carlicense, homepostaladdress and homephone because they were previously defined to have their own rules.
   2. ACL3 by self write grants the owner of the entry write permission to the attributes covered by this directive. Since ACL1 and ACL2 granted self access to the other attributes the owner can write all the attributes of their own entries.
   3. ACL3 by group.exact="cn=hrpeople,ou=groups,dc=example,dc=com" write grants write permission to any member of the hrpeople group to all the attributes in this ACL and in the previous ACL2 to the attributes carlicense, homepostaladdress and homephone but does not grant this group either read or write permission to userpassword (ACL1 denied this).
   4. ACL3 by users read grants any authenticated user read permission to all the attributes covered by this policy (all except those defined by ACL1 and ACL2). If we had wanted to grant full anonymous read permission (except to those attributes covered by ACL1 and ACL2) we could have used by anonymous read.
   5. ACL3 by * none in this case it means that any non-owner or non hrpeople group cannot write to any attribute and any non-authenticated users cannot read, search or perform any operations on any entry or attribute.

Public and Private Address Books

This example will create public and private address books as shown in the diagram below:

The policy to be adopted is:

1. All users must be authenticated to access the directory.

2. All authenticated users can see the Public (under customers branch) Address book.

3. Only the sales group (salespeople) can write to the customers address book.

4. The itpeople group will be able to create an addressbook entry under each entry in the people branch.

5. The owner of an addressbook will be able to read and write to it - no one else can even see the addressbook (except itpeople to create addressbook but not any of its entries). The user will not be able to delete the addressbook entry.

6. The IT department must be able to update or change the password entry on all directory entries.

7. Human resources group hrpeople must be able to update or change all user entries except the userpassword - and must not be able to read or change the users addressbook.

This example assumes at least the inetorgperson objectclass (for carlicense and other attributes) and we assume that two groups of users called hrpeople and itpeople exist. Both the addressbook and customers entries use the inteorgperson objectclass:

# ACL Notes
# The following additional notes apply for 2.4:
# 1. attrs is now used instead of attr (to reduce warning messages)
# 2. Removed the ,expand modifier with all regex expressions since
#    2.4 rejected some (but not all) ACL's which contained this modifier
# 3. 2.4 checking is much more rigorous and rejected ACL 8 since it contained
#    attributes to be added later
# 4. If exact or base contains a regular expression substitution then
#    the expand keyword must be used
# ACL1
# OLC (cn=config) form
olcAccess: to attrs=userpassword
  by self       write
  by anonymous  auth
  by group.exact="cn=itpeople,ou=groups,dc=example,dc=com" write
  by *          none
# slapd.conf form
access to attrs=userpassword
  by self       write
  by anonymous  auth
  by group.exact="cn=itpeople,ou=groups,dc=example,dc=com" write
  by *          none

# ACL2
# allow read of addressbook by owner and itpeople; no-one else see it
access to dn.regex="^ou=addressbook,cn=([^,]+),ou=people,dc=example,dc=com$"
    attrs=entry
  by dn.exact,expand="cn=$1,ou=people,dc=example,dc=com" read
  by group.exact="cn=itpeople,ou=groups,dc=example,dc=com" write
  by users none

# ACL3
# allow create of addressbook entry; cannot see entries
access to dn.regex="cn=[^,]+,ou=people,dc=example,dc=com$"
   attrs=children
  by group.exact="cn=itpeople,ou=groups,dc=example,dc=com" write
  by users none break

# ACL4
# allows creation of entries in own addressbook; no-one else can
# access it, needs write access to the ENTRY attribute (ACL5 or ACL6A) 
# and the entries CHILDREN (ACL4)
access to dn.regex="ou=addressbook,cn=([^,]+),ou=people,dc=example,dc=com$"
   attrs=children
  by dn.exact,expand="cn=$1,ou=people,dc=example,dc=com" write
  by users none

# ACL5 - required prior to 2.2
# allows creation of entries in own addressbook; no-one else can
# access it, needs write access to the ENTRY attribute (ACL5 or ACL6A) 
# and the entries CHILDREN (ACL4)
#access to dn.regex="ou=addressbook,cn=([^,]+),ou=people,dc=example,dc=com$"
#   attrs=entry
#  by dn.regex="cn=$1,ou=people,dc=example,dc=com" write
#  by users none

# ACL6 - required prior to 2.2
# allow access to all entries in own addressbook; no-one else can access it
#access to dn.regex="ou=addressbook,cn=([^,]+),ou=people,dc=example,dc=com$"
#   filter=(objectclass=inetorgperson)
#  by dn.regex="cn=$1,ou=people,dc=example,dc=com" write
#  by users none

# ACL6A - only possible from 2.2+ (combines ACL5 and ALC6)
access to dn.regex="ou=addressbook,cn=([^,]+),ou=people,dc=example,dc=com$"
   attrs=entry,@inetorgperson
  by dn.exact,expand="cn=$1,ou=people,dc=example,dc=com" write
  by users none

# ACL7
# allows sales to create entries in customers
# authenticated user can only read
access to dn.one="ou=customers,dc=example,dc=com"
   attrs=children
  by group.exact="cn=salespeople,ou=groups,dc=example,dc=com" write
  by users read

# ACL8
access to attrs=carlicense,homepostaladdress,homephone
  by self       write
  by group.exact="cn=hrpeople,ou=groups,dc=example,dc=com" write
  by *          none
# ACL9
access to *
  by self       write
  by group.exact="cn=hrpeople,ou=groups,dc=example,dc=com" write
  by users      read
  by *          none

Explanation:

1. ACL1

   1. ACL1 access to attrs=password means this policy applies to the attribute userpassword only.
   2. ACL1 by self write grants the owner of the entry (they authenticated with the userpassword of this entry) write permission to this attribute.
   3. ACL1 by anonymous auth grants an anonymous user access to this attribute only for authentication purposes (it is used internally by OpenLDAP to authenticate).
   4. ACL1 by group.exact="cn=itpeople,ou=groups,dc=example,dc=com" write grants write permission to this attribute to any member of the itpeople group. exact improves performance by avoiding the default regex if it were not present.
   5. ACL1 by * none means that any non-owner or non itpeople group cannot write to userpassword and any other authenticated users cannot read the attribute (no read access is granted).

2. ACL2

   1. ACL2 access to dn.regex="^ou=addressbook,cn=([^,]+),ou=people, dc=example,dc=com$" uses a regular expression to apply to entries that start with addressbook (anchored with ^). The variable $1 will contain the users cn (uses parenthesis = ([^,]+)))
   2. ACL2 attrs=entry a pseudo-attribute that refers to the entry (i.e. addressbook NOT the entries in the addressbook).
   3. ACL2 by dn.exact,expand="cn=$1,ou=people,dc=example,dc=com" read grants the owner of the entry (they authenticated with the userpassword of this entry) read permission to addressbook. $1 performs substitution with the users cn (obtained from regex above. The effect of this ACL is to allow only the user of the entry to see the private addressbook.
   4. ACL2 by group.exact="cn=itpeople,ou=groups,dc=example,dc=com" write grants write permission to this entry to any member of the itpeople group. This is required to create the addressbook entry. To allow creation of an entry write permission is required to the entry AND the children of the parent (see ACL3 for children permission).
   5. ACL2 by users none in this case it means that any non-owner or non itpeople group cannot read the entry (no read access is granted).

3. ACL3 - children partner of ACL2

   1. ACL3 access to dn.regex="cn=[^,]+,ou=people,dc=example,dc=com$" uses a regular expression to apply to ANY entries under people (regex is NOT anchored with ^). This is used to give children access to every entry under cn.
   2. ACL3 attrs=children a pseudo-attribute that refers to the children of the entry under people (i.e. in this case addressbook).
   3. ACL3 by group.exact="cn=itpeople,ou=groups,dc=example,dc=com" write grants the itpeople group write permission to children of any entry under people. To allow creation of an entry write permission is required to the entry (ACL2) and the child of the parent - this is the children permission part. This ACL and ACL3 allows only itpeople to create and remove the addressbook entry (and NOT the user).
   4. ACL3 by users none break means that any non-owner or non itpeople group cannot read the entry addressbook (no read access is granted). break is very important since it allows OpenLDAP tests to continue - without break this ACL will fail as OpenLDAP passes through the addressbook level and before it gets to the addressbook entries i.e. the owner (cn), as well as every other user, will be given access permission of none - and hence a write to an entry in the addressbook will fail.

4. ACL4 - the children partner of ACL5/ACL6/ACL6A

   1. ACL4 access to dn.regex="ou=addressbook,cn=([^,]+),ou=people,dc=example,dc=com$" uses a regular expression to apply to ANY entries under addressbook (regex is NOT anchored with ^). This ACL gives write permission to the children of the addressbook (the address book entries) required as part of the ability to create an entry. The variable $1 will contain the users cn (uses parenthesis = ([^,]+)).
   2. ACL4 attrs=children a pseudo-attribute that refers to the children of the entry under people (i.e. in this case entries in the addressbook).
   3. ACL4 by dn.exact,expand="cn=$1,ou=people,dc=example,dc=com" write. $1 is substituted with the users cn obtained from regex above. This match grants the cn (owner) write permission to children of any entry under cn. To allow creation of an entry write permission is required as the entry (ACL2) and the child of the parent - this is the child permission. This ACL and ACL5/ACL6A allows only cn (owner) to create and remove entries in the addressbook.
   4. ACL4 by users none means that any non-owner cannot read the addressbook (no read access is granted).

5. ACL5 - the entry partner of ACL4

   1. Only required prior to version 2.2. Use ACL6A from 2.2. ACL5 - this is the entry permission partner of ACL4 and is required to allow creating of an new entry in the addressbook. It is exactly the same except for attrs=entry in this ACL. This ACL and ACL4 allows only cn (owner) to create and remove entries IN the addressbook. The order of children and entry are not important.

6. ACL6 - add any attributes to the addressbook

   1. Only required prior to 2.2. Use ACL6A from 2.2. ACL6 - this ACL has the same scope and syntax as ACL4 and ACL5 it is present to allow the owner to add any fields in the objectclass inetorgperson by using filter=(objectclass=inetorgperson). This required for OpenLDAP prior to 2.2. In 2.2+ ACL5 and ACL6 may be combined by using the syntax attrs=entry,@inetorgperson. This syntax is not supported prior to OpenLDAP 2.2.

7. ACL6A - add any attributes to the addressbook

   1. Only use ACL6A from 2.2, prior to 2.2 ACL5 and ACL6 are required.
   2. ACL6 - this ACL has the same scope and syntax as ACL4 and it is present to allow the owner to add any fields in the entry objectclass inetorgperson by using attrs=entry,@inetorgperson. This syntax is not supported prior to OpenLDAP 2.2.

8. ACL7

   1. ACL7 access to dn.one="ou=customers,dc=example,dc=com" means this policy applies to one level below customers (entries in the public address book).
   2. ACL7 attrs=children refers to the children of customers only (entries in the public address book).
   3. ACL7 by group.exact="cn=salespeople,ou=groups,dc=example,dc=com" write grants write permission to entries in the public address book to any member of the salespeople group.
   4. ACL7 by users read any authenticated user can read the public address book.

9. ACL8

   1. ACL8 access to attr=carlicense,homepostaladdress,homephone means this policy applies to these attributes only.
   2. ACL8 by self write grants the owner of the entry (they authenticated with the userpassword of this entry) write permission to these attributes.
   3. ACL8 by group.exact="cn=hrpeople,ou=groups,dc=example,dc=com" write grants write permission to this attribute to any member of the hrpeople group.
   4. ACL8 by * none in this case it means that any non-owner or non hrpeople group cannot write to the attributes and any other authenticated users cannot read the attribute (no read access is granted).

10. ACL9

    1. ACL9 access to * Because access directives are additive this directive means this policy applies to all attributes except userpassword, carlicense, homepostaladdress and homephone because they were previously defined to have their own rules.
    2. ACL9 by self write grants the owner of the entry write permission to the attributes covered by this directive (all). Since ACL1 and ACL2 granted self access to the other attributes the owner can write all the attributes.
    3. ACL9 by group.exact="cn=hrpeople,ou=groups,dc=example,dc=com" write grants write permission to any member of the hrpeople group to all the attributes in this ACL and in the previous ACL2 to the attributes carlicense, homepostaladdress and homephone but does not grant this group either read or write permission to userpassword.
    4. ACL9 by users read grants any authenticated user read permission to all the attributes covered by this policy (all except those defined by ACL1 and ACL2). If we had wanted to grant full anonymous read permission (except to those attributes covered by ACL1 and ACL2) we could have used by anonymous read.
    5. ACL9 by * none in this case it means that any non-owner or non hrpeople group cannot write to any attribute and any non-authenticated users cannot read, search or perform any operations on any entry or attribute.

olcAllows (allow)

allow feature [...]

This global attribute/directive defines features that are permitted by the server. One or more of the following values may be used (separated by white space, for example, space or TAB):

Examples:

# slapd.conf fragment
# global
...
allow bind_v2
...

# OLC (cn=config) form
olcAllows: bind_v2

olcArgsFile (argsfile)

Causes OpenLDAP to write the command line arguments with which it was started to the defined file. Example:

# OLC (cn=config) form
olcArgsFile: /var/run/ldap.args

# slapd.conf form
argsfile /var/run/ldap.args

Alternatively you can use a command such as:

ps ax |grep slapd

which will provide the command line args information. If an argsfile directive is not included no args file will be created.

olcAttributeTypes (attributetype)

OpenLDAP - as an artifact of schema processing - allows the definition of one or more attributetypes in the slapd.conf file or olcAttributeTypes in olc (cn=config) systems. attributetype definition is explained in gory detail. It is not clear why you would want to add attributes in this manner using slapd.conf - the preferred method would be to create a user schema file and add this using the include directive. Nevertheless you can if the fancy takes you. In OLC (cn=config) the olcAttributeTypes and olcObjectClasses attribute is used to load all schemas used by OLC (cn=config).

olcConcurrency (concurrency)

Format:

# OLC (cn=config) form
olcConcurrency: integer

# slapd.conf form
concurrency integer

The olcConcurrency (concurrency) attribute/directive if supplied provides a 'hint' to the OpenLDAP thread system. The default is none. Examples:

# OLC (cn=config) form
olcConcurrency: 25

# slapd.conf form
concurrency 25
# hints that 25 threads will be used 
# allowing support of 25 concurrent operations

It is not clear what is the relationship between the olcConcurrency (concurrency) attribute/directive and the olcThreads/threads attribute/directive.

olcConnMaxPending (conn_max_pending)

Format:

# OLC (cn=config) form
olcConnMaxPending: integer

# slapd.conf form
conn_max_pending integer

The olcConnMaxPending (conn_max_pending) attribute/directive defines the number of pending (queued) requests within a single anonymous session. If the limit is exceeded the session is closed - but currently queued requests will be processed. The default is 100. Examples:

# OLC (cn=config) form
olcConnMaxPending: 10

# slapd.conf form
conn_max_pending 10
# if more that 10 outstanding requests are queued from a 
# single anonymous client session - session will be terminated

olcConnMaxPendingAuth (conn_max_auth)

Format:

# OLC (cn=config) form
olcConnMaxPendingAuth: integer

# slapd.conf form
conn_max_auth integer

The olcConnMaxPendingAuth (conn_max_auth) attribute/directive defines the number of pending (queued) requests within a single authenticated session. If the limit is exceeded the session is closed - but currently queued requests will be processed. The default is 1000. Examples:

# OLC (cn=config) form
olcConnMaxPendingAuth: 100

# slapd.conf form
conn_max_auth 100
# if more that 100 outstanding requests are queued from a 
# single authenticated client session - session will be terminated

defaultaccess

Deprecated from OpenLDAP 2.1 - use access to directive. Not supported by OLC (cn=config) other than to allow conversion of slapd.conf files.

The defaultaccess is a catch-all - if you define no access to directive(s) you can use this as global default. The format is:

defaultaccess { none | compare | search | read | write }

The list above is hierarchical to the RIGHT i.e. read access allows search and compare but not write, write will allow read, search and compare. The default if no defaultaccess or access to directives are supplied is:

defaultaccess read
# allows read, search and compare but NOT write

olcDefaultSearchBase (defaultsearchbase)

Format:

# OLC (cn=config) form
olcDefaultSearchBase: dn

# slapd.conf form
defaultsearchbase dn

The olcDefaultSearchBase (defaultsearchbase) attribute/directive if supplied provides a dn that will be used if search with scope of one or sub with a blank DN. The default is the search will be rejected NoSuchObject. Examples:

# OLC (cn=config) form
olcDefaultSearchBase: dc=example,dc=com

# slapd.conf form
defaultsearchbase dc=example,dc=com
# will return search results as if
# the above dn has been supplied instead of blank

When added using OLC (cn=config) this attribute is added to the olcDatabase={-1}frontend,cn=config entry unlike all other global attributes which are added to the cn=config entry.

olcDisallows (disallow)

# OLC (cn=config) form
olcDisallows: feature [...]

# slapd.conf form
disallow feature [...]

This global attribute/directive defines features that are not permitted by the server. One or more of the following keyword values may be used (separated by white space, for example, space or TAB):

Examples:

# OLC (cn=config) form
olcDisallows: bind_anon

# slapd.conf form

disallow bind_anon 
# server does not permit anonymous binds

olcGentleHUP (gentlehup)

Format:

# OLC (cn=config) form
olcGentleHUP: TRUE | FALSE

# slapd.conf form
gentlehup on | off

The olcgentleHUP (gentlehup) attribute/directive if TRUE (or on) allows OpenLDAP to perform a graceful shutdown when it receives a SIGHUP signal, such as:

kill -HUP PID

OpenLDAP will:

1. stop listening to new incoming requests
2. continue to process pending or current requests
3. return 'unwilling to perform' to pending writes
4. shut down when all current operations have terminated

This command is made more effective if olcIdleTimeout/idletimeout and olcTimeLimit/timelimit attributes/directives are in operation. OpenLDAP will as always respond immediately to a SIGTERM signal. Default is FALSE (or off).

Examples:

# OLC (cn=config) form
olcGentleHUP: TRUE

# slapd.conf form
gentlehup on
# allows graceful shutdown to SIGHUP

# OLC (cn=config) form
olcGentleHUP: FALSE

# slapd.conf form
gentlehup off
# default - treats SIGHUP as SIGTERM

olcIdleTimeout (idletimeout)

Format:

# OLC (cn=config) form
olcIdleTimeout: integer

# slapd.conf form
idletimeout integer

The olcIdleTimeout (idletimeout) attribute/directive defines the time in seconds after which an idle client bind connection is forcibly terminated (an unbind operation is forced).

If no olcIdleTimeout (idletimeout) attribute/directive is defined or an period of 0 is used the feature is disabled, that is idle clients bind connections are maintained indefinitely (no unbind operation is forced by the server). Examples:

# OLC (cn=config) form
olcIdleTimeout: 0

# slapd.conf form
idletimeout 0
# do not logout idle clients

# OLC (cn=config) form
olcIdleTimeout: 30

# slapd.conf form
idletimeout 30
# logout idle clients after 30 seconds

Caution: This is a server wide value so that all bind connections are affected by it. If this server is either a replication consumer (using olcSyncRepl/syncrepl with a type value of refreshAndPersist) or a provider (using the overlay syncprov directive with a one of more consumers with a type of refreshAndPersist) then it is highly likely that these links will remain idle for prolonged periods of time. Extreme caution should be used when defining the olcIdleTimeot/idletimeout attribute/directive in either of these conditions because the net effect may be to change such replication connections into type refreshOnly which may not be a welcome side effect.

include

This directive is, by its nature, redundant in OLC (cn=config) configurations and is only supported for slapd.conf conversion purposes. Schemas may be added to olc (cn=config) configurations using this process.

The include directive allows any file to be read in-situ. OpenLDAP performs no checking on this and thus nested include directives can cause problems. The directive format is:

include /path/to/include/file

There are two common uses for this directive:

1. including .schema files (normally in /usr/local/etc/openldap/schema or /etc/openldap/schema) which are pre-existing.
2. reading files which may contain sensitive information such as passwords which may be protected using chmod to limit access.

Examples:

include /usr/local/etc/openldap/schema/core.schema
# include the distribution core.schema
include /var/myschemas/myschema.schema
# include myschema.schema
include /var/passwords/userpass
# include user password file containing say 
# rootpw directive with chmod 0600

olcDbIndex (index)

The index directive of slapd.conf is only effective on initial load of the directory (using ldapadd). If indexes are subsequently changed the directory needs to be re-indexed using slapindex (caution: depending of the version must stop slapd first).

In OLC (cn=config) the attribute used is olcDbIndex which can only appear in an olcDatabase={0}config entry. Additionally re-indexing is done in real time so any change to an attribute immediately triggers an indexing change (slapindex is not required). However, it is not clear using OLC (cn=config) when re-indexing is completed - there is no visible sign to indicate completion.

Format:

# OLC (cn=config) form
olcDbIndex: attrlist | default indices

# slapd.conf form
index attrlist | default indices

# indices = [pres [,approx] [,eq] [,sub] [,special]]

The olcDbIndex/index attribute/directive defines what indexes will be maintained by OpenLDAP. Any number of index parameters may be included. If an attribute does not appear in an index directive it can still be used in a search filter - but if it occurs frequently it will hurt performance - once in a lifetime is not too bad!

attrlist may be either a single attribute or a comma separated list.

The optional parameter default stores the supplied indices and uses them on any subsequent index parameter that does does not have an indices entry. The default value must be defined before any olcDbIndex/index which does not have a indices value. A subsequent default will be used for index parameters following the new default.

pres should be used if use searches of the form 'objectclass=person' or 'attribute=mail' will be used.

approx MUST be used if use searches of the form 'sn~=person' (a 'sounds-like' search) will be used.

eq should be used if searches of the form 'sn=smith' will be used i.e no wildcards are included (uses the EQUALITY rule only).

sub should be used if use searches of the form 'sn=sm*' i.e wildcards are included (uses the SUBSTR rule). This rule may be enhanced by a using subinitial (optimised for 'sn=*s'), subany (optimised for 'sn=*n*') or subfinal (optimised for 'sn=th*'). One or more sub parameters may be included.

special may be either nolang or nosubtypes which are related to subtypes.

Careful attention to what indexes are maintained based on the application requirements will significantly affect directory read performance - conversely there is no point in indexing an attribute if no searches ever access it. If all the searches use EQUALITY rules only then there is no point in indexing for sub. Indexes (indeces) consume memory (more indexes = more memory) and write or modify operations will take longer due to index updates.

Examples:

# simple use of the default value
# OLC (cn=config) form
olcDbIndex: default pres,eq
olcDbIndex: cn,sn,uid

# slapd.conf form
index default pres,eq
index cn,sn,uid

# defines presence and equality indexes for 
# attributes cn, sn and uid
# exactly the same as the three index directives below
index cn pres,eq
index sn pres,eq
index uid pres,eq

index cn eq,sub,subinitial
# creates indexes for attribute cn (commonname)
# EQUALITY, SUBSTR searches and further optimises
# for sc=a* type searches

index sn eq,approx,sub
# creates indexes for sn (surname) on
# EQUALITY and SUBSTR searches
# NOTE: The approx index is a waste of time because
#       there is no ORDERING rule for sn approx is present
#       only to illustrate the parameter exists

index mail pres,eq,sub
# creates indexes for attribute mail on
# presence, EQUALITY and SUBSTR

index objectclass eq
# optimises searches of form objectclass=person

See also Performance chapter for a further review of performance.

olcLogFile (logfile)

OpenLDAP logs via syslogd (using LOCAL4) in all cases (see olcLogLevel/loglevel for configuration information on streaming syslogd LDAP messages to a separate file). In addition the olcLogFile (logfile) directive may be used to create a separate file containing just LDAP log information. Even when this directive is used OpenLDAP will only log the information via syslogd. Example:

# OLC (cn=config) form
olcLogFile: /path/to/ldap/log/file

# slapd.conf form
logfile /path/to/ldap/log/file

# file must exist prior to starting OpenLDAP
touch /path/to/ldap/log/file
chown ldap:ldap /path/to/ldap/log/file

olcLogLevel (loglevel)

OpenLDAP logs via syslogd LOCAL4. To stream the LDAP log to a separate file from syslog add a line like this to syslog.conf (normally /etc/syslog.conf):

# add to syslog.conf
local4.* /var/log/ldap.log

# create an empty log file
touch /var/log/ldap.log

# restart syslogd
killall -HUP syslogd
OR
/etc/rc.d/syslogd restart

The above command will log all levels of local4 (OpenLDAP) output to /var/log/ldap.log. Alternatively the olcLogFile/logfile directive may be used.

Note: The -d argument (if present) on the slapd command line overrides any value set in the olcLogLevel/loglevel parameters. When using OLC (cn=config) subsequent attempts to change the log level using olcLogLevel will be saved but not actioned.

The OpenLDAP logging level is set using the following directive:

loglevel number | hex-value | log-name

The possible values for number, hex-value and log-name are:

The loglevel directive takes a single value or a space separated list of values, each value may be any combination of number, hex-value or log-name from the table above. The results are OR'd together. It is also possible to set multiple entries in either the number or hex-value as shown in the following examples:

loglevel 255
# sets 1, 2, 4, 8, 16, 32, 64 and 128
# adds all the numbers

loglevel 2176
# 2048 + 128
loglevel 296
# 256 + 32 + 8

# using single hex-value (128)
loglevel 0x80

# multiple hex-values (1 + 128)
loglevel 0x81 
# same result as
loglevel 0x1 0x80

# using log-name (single value)
loglevel acl

# multiple log-name values
loglevel acl sync

# combined
loglevel 1 0x40 conns

If no olcLogLevel/loglevel attribute/directive is defined the log defaults to 256 (stats only).

Note: With the -1 setting slapd logs ferocious amounts of data. Reduce this value as quickly as possible to only those items you are interested in or buy new discs - lots of new discs.

olcModuleLoad (moduleload)

A stunning attribute/directive that is the collateral damage of a poorly implemented feature - in this case overlays. What should be automatic based on the configuration, requires manual definition based on a gruesome number of build and configure options which, if RPMs are used, are usually isolated from users. Clearly not from OpenLDAP users.

The olcModuleLoad/moduleload attribute/directive appears in the global section and specifies the name of a dynamically loadable module that is used in the configuration. It is essential if (a) the overlay is dynamic (see below) and (b) the overlay is used (for example in a database directive) or is defined in an overlay directive. The overlay name may be an absolute path name or a simple filename and must include the library suffix such as .la (libtool built library) or .so (shared object libraries). Non-absolute names are searched for in the directories specified by the olcModulePath/modulepath attribute/directive or the PATH, LTDL_LIBRARY_PATH and LD_LIBRARY_PATH if olcModulePath/modulepath is not defined. This directive and the olcModulePath/modulepath attribute/directive are only allowed if the build option --enable-modules (normal for most distributions) is specified.

It should be noted that OpenLDAP modules may be static or dynamic (only dynamic overlays require olcModuleLoad/moduleload directives). As an example to illustrate the difference between static and dynamic, the OpenLDAP configure directive, say, --enable-accesslog=mod builds a separate accesslog overlay and therefore MUST be defined in a olcModuleLoad/moduleload attribute/directive. If, however, the configure directive takes the form --enable-accesslog then this overlay is built into the base slapd - it is built as a static overlay. Specifying a olcModuleLoad/moduleload directive for accesslog in this case will fail since --enable-accesslog inhibits building of the overlay (use ./configure --help from the OpenLDAP's build directory to get a full list of configure options). The best rule of thumb is to look in the directory in which the modules are placed ([bsd] /usr/local/libexec/openldap) [fc] /usr/libexec/openldap or /usr/sbin/openldap) if the module exists and is used it must be defined in a olcModuleLoad/moduleload attribute/directive - else assume it is static. If a module is built with .la and .so suffixes - use .la unless it does not work in which case try .so. If both fail we recommend ritual suicide. Module names of overlays and database directives.

# OLC (cn=config) form
olcModuleLoad: module-name

# slapd.conf form 
moduleload module-name

# example - permanent load of the syncprov overlay
# OLC (cn=config) form
olcModuleLoad: syncprov.la

# slapd.conf form 
moduleload syncprov.la

# absolute path format
# OLC (cn=config) form
olcModuleLoad: /usr/local/libexec/openldap/syncprov.la

# slapd.conf form 
moduleload /usr/local/libexec/openldap/syncprov.la

Note: Both olcModuleLoad and olcModulePath are defined in the cn=modules{0},cn=config entry using the olcModuleList objectClass.

olcModulePath (modulepath)

Defines one or more directories to search for loadable modules (overlays). Multiple paths may be defined in which they are colon-separated (*nix) and semi-colon separated (windows). If not defined the PATH, LTDL_LIBRARY_PATH and LD_LIBRARY_PATH are searched. See also notes on olcModuleLoad/moduleload.

Note: When used in OLC (cn=config) olcModulePath is SINGLE-VALUE. Both olcModuleLoad and olcModulePath are defined in the cn=modules{0},cn=config entry using the olcModuleList objectClass.

olcObjectClasses (objectclass)

OpenLDAP - as an artifact of schema processing - allows the definition of one or more objectclass(es) in the slapd.conf file. objectclass definition is explained here. It is not clear why you would want to add objectclasses in this manner - the preferred method would be to create a user schema file and add this using the include directive. Nevertheless you can if the fancy takes you.

In OLC (cn=config) the attribute used is olcObjectClasses and is used to load schemas required by the olc (cn=config) system.

olcPasswordHash (password-hash)

Allows definition of one or more hash methods used when storing a new password in userPassword with an Extended Modify Password Operation (RFC 3602). Format:

# OLC (cn=config) form
olcPasswordHash: {hash}[,{hash} [, ...]]

# slapd.conf form 
password-hash {hash}[,{hash} [, ...]]

The value of hash must be one of the supported methods {SSHA}, {SHA}, {SMD5}, {MD5}, {CRYPT}, or {CLEARTEXT}. The default value is {SSHA}. Example:

# OLC (cn=config) form
olcPasswordHash: {SHA},{SSHA}

# slapd.conf form 
password-hash {SHA},{SSHA}

which will set the server-wide default hash to use {SHA) (FIPS-160 with no salt). If multiple values are supplied they must be comma separated with no spaces - otherwise choking sounds are emitted by slapd on loading or - more precisely - not loading.

When used with OLC (cn=config) this attribute appears in/is added to the olcDatabase={-1}frontend,cn=config entry not the global (cn=config) entry.

olcPidFile (pidfile)

Causes OpenLDAP (slapd) to write the PID to the defined file. Example:

# OLC (cn=config) form
olcPidFile:  /var/run/ldap.pid

# slapd.conf form 
pidfile /var/run/ldap.pid

The PID can be used to kill or send some other signal to ldap. Alternatively you can use a command such as:

ps ax |grep slapd

which will provide the PID information. If an olcPidFile/pidfile attribute/directive is not included no pid file will be created. Most slapd start/stop/restart scripts only work when there is a PID file and it is in the expected place. You have two alternatives: use a olcPidFile/pidfile attribute/directive to define the expected pid path and happily use all standard scripts; use no olcPidFile/pidfile or use a non-standard path for your system and use a manual stop/start process.

olcReferral (referral)

Format:

# OLC (cn=config) form
olcReferral: uri

# slapd.conf form 
referral uri

The olcReferral/referral attribute/directive allows OpenLDAP to return the specified uri as a referral when it cannot find the supplied DN value in any of its database(s)/DITs (defined in a olcSuffix/suffix attribute/directive). Not all clients may be capable of handling the returned uri which should be constructed as a full LDAP URL with as much information as possible and should sensibly point to a site which allows anonymous access using a sensible root DN. Examples:

# OLC (cn=config) form
olcReferral: ldap://ldap.openldap.org/

# slapd.conf form 
referral ldap://ldap.openldap.org/
# this URL would attempt to access the rootDSE
# of the openldap site which might not succeed!

# OLC (cn=config) form
olcReferral: ldap://ldap.example.com/dc=example,dc=com??one?(objectclass=*)

# slapd.conf form 
referral ldap://ldap.example.com/dc=example,dc=com??one?(objectclass=*)
# the ldap.example.com would be constructed to support these queries
# and return all first level entries supported by all LDAP servers
# at this site - a kind of generic services/scope overview

Note: The olcReferral/referral attribute/directive is used when the server cannot find the DN within its DIT structure. Referrals are normally configured using the referral ObjectClass within the DIT structure. More information and configuration examples of Referrals.

replicationinterval

Obsoleted in 2.4 and only provided in OLC (cn=config) for slapd.conf conversion. Defined in a master and used in slurpd style replication. The directive is read by slurpd and defines the interval in seconds that slurpd will wait before checking the replogfile file for slave updates.

replicationinterval seconds

# example check replogfile every 60 seconds
replicationinterval 60

The directive has a murky genus but seems to have been introduced in OpenLDAP 2.2. It is, like many other things in OpenLDAP, unclear what the default replication interval is if this directive is not present.

olcRequires (require)

# OLC (cn=config) form
olcRequires: policy [...]

# slapd.conf form 
require policy [...]

This directive, which may be used globally or within a database section, defines requirements that must be satisfied before any server access is permitted. If used within a database section the value persists until reset (olcRequires: none/require none). Subsequent olcRequires/require attributes/directives which do not reset the olcRequires/require attribute/directive are additive. One or more of the following values may be used (separated by white space, for example, space or TAB):

Examples:

# resets the value of olcRequires/require and forces
# LDAP authentication for this DIT
# OLC (cn=config) form
olcRequires: none authc

# slapd.conf form 
require none authc

olcReverseLookup (reverse-lookup)

Format:

# OLC (cn=config) form
olcReverseLookup: TRUE | FALSE

# slapd.conf form 
reverse-lookup on | off

The olcReverseLookup/reverse-lookup attribute/directive if TRUE (or on) causes OpenLDAP to use DNS reverse lookup for each client access. The default is FALSE (or off). This attribute/directive is only effective if the build option --enable-rlookups was used. Examples:

# OLC (cn=config) form
oldReverseLookup: TRUE

# slapd.conf form 
reverse-lookup on
# causes OpenLDAP to perform a DNS reverse lookup for 
# each client access

olcRootDSE (rootDSE)

Format:

# OLC (cn=config) form
olcRootDSE: /path/to/ldif/file

# slapd.conf form 
rootDSE /path/to/ldif/file

The olcRootDSE/rootDSE attribute/directive defines an LDIF file containing user defined operational attributes to be added to the existing rootDSE (visible under the subschema subentry). These attributes are additive - in addition to the standard (built-in) attributes.

olcSecurity (security)

# OLC (cn=config) form
olcSecurity: ssf-policy

# slapd.conf form 
security ssf-policy [...]

This attribute/directive may be defined in the global section/entry, in which case its scope includes all database sections, or it may be specified within a database section/entry in which case its scope is limited to that DIT only (overrriding any global directives if present). When using secure connections (either TLS or SASL) the olcSecurity/security attribute/directive defines the minimum Security Strength Factor (SSF) applied to either a security type (TLS or SASL) or required to execute a particular type of transaction. One or more ssf-policy values may be defined (separated by spaces) from the following list:

The value of n defines the level of security required expressed as the minimum number of bits in any cryptographic key being used - typically in the range 40 to 256 (normally values would be 40, 56, 64, 128, 164 and 256) depending on the algorithm involved. Thus a value of 1 would indicate that any level of cryptographic security is acceptable while a value of 128 would indicate that a cryptographic algorithm with a key length of 128 or higher will pass but one with a key length of, say, 56 will fail.

olcSchemaDN (schemadn)

Format:

# OLC (cn=config) form
olcSchemaDN: cn=name

# slapd.conf form 
schemadn cn=name

The olcSchemaDN/schemadn attribute/directive defines the name of the subschema subentry used by OpenLDAP. The default is 'cn=subschema'. Examples:

# OLC (cn=config) form
olcSchemaDN: cn=ldapsubschema

# slapd.conf form 
schemadn cn=ldapsubschema
# changed the name of the subschema subentry from
# (default) subschema to ldapsubschema

It is not at all clear why one would want to use this feature such except, perhaps, to retain compatability with another/previous LDAP implementation.

olcServerID (ServerID)

Format:

# OLC (cn=config) form
olcServerID: number [URL]

# slapd.conf form 
serverid number [URL]

Version 2.4+. olcServerID/serverid defines a method by which the server is uniquely identified using either a number (a.k.a SID) or a URL(s). The attribute/directive is used in Multi-master replication supported from OpenLDAP 2.4. The number parameter is an arbitrary 1-3 character number which uniquely defines the server within the Multi-master group. The default value is 000. The server ID (a.k.a SID) is used (as the rid value of the updated (in 2.4) CSN) to uniquely identify a host as the source of an update. If the optional URL form is used the directive may appear multiple times. Many multi-master configurations show all the servers within the multi-master group as being defined with their associated URLs. Experiments have shown this to be not required (the provider information is defined in the syncrepl directive) the number format works perfectly. The key characteristic is that the value defined (either by a number or a URL) uniquely identifies this server over time. Bear in mind two points when selecting this value. First, even though a ServerID number may be currently unique it may not remain unique, for instance, you may subsequently decide to replicate from a server which has already allocated a SID of 001. Second, if the server's cn=config is subsequently replicated to another server which has the same SID the result may be unpredictable. Use of the server's URL may provide a more unique value over time. On the other hand it may not - in which case ritual suicide may be the best option. Finally, there is no relationship between the SID (server ID) and rid parameter used in the olcSyncRepl/syncrepl. Examples:

# OLC (cn=config) form
olcServerID: 001

# slapd.conf form 
serverid 001
# or equivalent 1 character form
serverid 1

# URI form
# OLC (cn=config) form
olcServerID: ldap1.example.com

# slapd.conf form 
serverid ldap1.example.com

olcSizeLimit (sizelimit)

The olcSizeLimit/sizelimit attribute/directive specifies the number of entries to return to a search request. There are two forms of this command, first form:

# OLC (cn=config) form
olcSizeLimit: integer | unlimited

# slapd.conf form 
sizelimit integer | unlimited

Where integer is value between 1 and 65435. unlimited (or -1) places no limits on the number of returned results.

The second form provides more control over the number of returned results and has the following format:

# OLC (cn=config) form
olcSizeLimit: size[.{soft|hard|unchecked}]=integer

# slapd.conf form 
sizelimit size[.{soft|hard|unchecked}]=integer

Where integer is the maximum number of entries slapd will return answering a search request. The behaviour of the directive depends on the optional qualifier soft, hard or unchecked as follows:

1. If no size limit is explicitly requested by the client, the soft limit is used.
2. If the requested size limit exceeds the hard limit, an "Administrative limit exceeded" is returned.
3. If the hard limit is set to 0 or to the keyword "soft", the soft limit is used in either case.
4. If the hard limit is set to -1 or to the keyword "none", no hard limit is enforced.
5. Explicit requests for size limits smaller or equal to the hard limit are honored.
6. The unchecked qualifier sets a limit on the number of candidates a search request is allowed to examine. If the selected candidates exceed the unchecked limit, the search will abort with LDAP_UNWILLING_TO_PERFORM (53, x'35). If unchecked is set to -1 or to the keyword "none", no limit is applied (the default).
7. If no qualifier is present, the value is assigned to the soft limit, and the hard limit is set to zero, to preserve the original behavior.

If no sizelimit directive is defined the default is 500. Examples:

# OLC (cn=config) form
olcSizeLimit: 0

# slapd.conf form 
sizelimit 0
# do not logout idle clients

# OLC (cn=config) form
olcSizeLimit: 100

# slapd.conf form 
sizelimit 100
# limit responses to a maximum of 100

# extended form
# OLC (cn=config) form
olcSizeLimit: size=100

# slapd.conf form 
sizelimit size=100
# behaves exactly the same as sizelimit 100

# OLC (cn=config) form
olcSizeLimit: size.soft=100 size.hard=200

# slapd.conf form 
sizelimit size.soft=100 size.hard=200
# if no client limit = 100
# if client limit > 200 - rejected
# no limits to number of candidates searched

# OLC (cn=config) form
olcSizeLimit: size.unchecked=1000

# slapd.conf form 
sizelimit size.unchecked=1000
# if no client limit = 500 max returned (default)
# else client limit
# if client limit > 500 - rejected (default)
# if more than 1000 candidates - rejected

olcSockbufMaxIncoming (sockbuf_max_incoming)

Format:

# OLC (cn=config) form
olcSockbufMaxIncoming: bytes

# slapd.conf form 
sockbuf_max_incoming bytes

The olcSockbufMaxIncoming/sockbuf_max_incoming attribute/directive defines the maximum PDU (block size) in bytes for incoming anonymous sessions. The default is 262143. Examples:

# OLC (cn=config) form
olcSockbufMaxIncoming: 5000

# slapd.conf form 
sockbuf_max_incoming 5000
# limits the max PDU (block size) to 5000 bytes
# else rejected 

olcSockbufMaxIncomingAuth (sockbuf_max_incoming_auth)

Format:

# OLC (cn=config) form
olcSockbufMaxIncomingAuth: integer

# slapd.conf form 
sockbuf_max_incoming_auth integer

The olcSockbufMaxIncomingAuth/sockbuf_max_incoming_auth attribute/directive defines the maximum PDU (block size) for incoming authenticated sessions. The default is 4194303. Examples:

sockbuf_max_incoming_auth 5000
# limits the max PDU to 5000 bytes
# else rejected 

olcThreads (threads)

Format:

# OLC (cn=config) form
olcThreads: integer

# slapd.conf form 
threads integer

The olcThreads/threads attribute/directive defines the number of threads that can be used by OpenLDAP. The higher this value the larger the number of concurrent requests that can be handled. The default value is 16. Examples:

# OLC (cn=config) form
olcThreads: 25

# slapd.conf form 
threads 25
# allows a maximum of 25 threads

It is not clear what is the relationship between the olcThreads/threads attribute/directive and the olcConcurrency/concurrency attribute/directive.

olcTimeLimit (timelimit)

The olcTimeLimit/timelimit attribute/directive specifies the time in seconds slapd will spend answering a search request. If a request is not finished in this time, a result indicating an exceeded timelimit will be returned to the client. There are two forms of this command, first form:

# OLC (cn=config) form
olcTimeLimit: seconds | unlimited

# slapd.conf form 
timelimit seconds | unlimited

Where seconds is the number of seconds slapd will spend answering a search request, unlimited or -1 applies no limits to search time.

The second (extended) form provides more control over the number of returned results and has the following format:

# OLC (cn=config) form
olcTimeLimit: time[.{soft|hard}]=seconds [..]

# slapd.conf form 
timelimit time[.{soft|hard}]=seconds [..]

Where seconds is the number of seconds slapd will spend answering a search request. The optional qualifiers soft and hard determine the actions as follows:

1. If no time limit is explicitly requested by the client, the soft limit is used.
2. If the requested time limit exceeds the hard limit, an "Administrative limit exceeded" is returned.
3. If the hard limit is set to 0 or to the keyword "soft", the soft limit is used in both cases.
4. If the hard limit is set to -1 or to the keyword "none", no hard limit is enforced.
5. Explicit requests for time limits smaller or equal to the hard limit are honored.
6. If neither qualifier is defined, the value is assigned to the soft limit, and the hard limit is set to zero, to preserve the original behavior.

If no timelimit directive is defined a time limit of 3600 is applied (1 hour). Examples:

# OLC (cn=config) form
olcTimeLimit: 15

# slapd.conf form 
timelimit 15
# allow 15 seconds to complete the search 
# else return time limit exceeded error

# OLC (cn=config) form
olcTimeLimit: 0

# slapd.conf form 
timelimit 0
# disables the feature (default = 3600)
timelimit unlimited
# no time limit is applied

# extended format
# OLC (cn=config) form
olcTimeLimit: time=15

# slapd.conf form 
timelimit time=15
# behaves exactly the same as timelimit 15

# OLC (cn=config) form
olcTimeLimit: time.soft=15 time.hard=20

# slapd.conf form 
timelimit time.soft=15 time.hard=20
# client defines no limit 15 seconds is used
# if client requests time limit > 20 - rejected

# OLC (cn=config) form
olcTimeLimit: time.soft=15

# slapd.conf form 
timelimit time.soft=15
# client defines no limit 15 seconds is used
# if client requests any time limit - accepted

# OLC (cn=config) form
olcTimeLimit: time.soft=15 time.hard=none

# slapd.conf form 
timelimit time.soft=15 time.hard=none
# client defines no limit 15 seconds is used
# if client requests any time limit - accepted

6.3.1 TLS Directives (OLC (cn=config) and slapd.conf)

TLS Overview - What is a TLS Server/Client?

OpenLDAP differentiates between the attributes/directives necessary for a (TLS) Server and those of a (TLS) Client. The terms LDAP Clients are applied to, say, an LDAPBrowser or a Mail Client which reads an LDAP addressbook whereas OpenLDAP systems are Servers. However, TLS makes it a bit more complicated. What are called LDAP servers can in fact be TLS Servers or TLS Clients or even both TLS Clients and TLS Servers - in the latter case they will require both TLS server and TLS client attributes/directives. The key difference is that a TLS Server never initiates communication whereas a TLS Client always does. This difference occurs at the database entry/section level thus one database entry/section in a slapd.conf (or olcDatabase in cn=config) could be a TLS Server and another a TLS Client. Here are some examples:

1. An LDAP system which only provides access to external clients, has no syncrepl attributes/directives in any database entry/section and has no overlay chain attributes/directives is only a TLS server.

2. A database entry/section containing a overlay syncprov entry/directive in a master-slave replication configuration is always a TLS server (the consumer always connects to the provider).

3. A database entry/section containing a olcSyncrepl/syncrepl attribute/directive in a master-slave replication configuration is always a TLS Client (the consumer always connects to the provider).

4. A database entry/section containing a olcSyncrepl/syncrepl attribute/directive and a overlay syncprov entry/directive in a multi-master replication configuration is both a TLS Client (for the olcSyncrepl/syncrepl attribute(s)/directive(s) - consumer) and a TLS Server (for the syncprov - provider).

5. A LDAP server containing a overlay chain entry/directive may be both a TLS Client (for the chaining connections) and a TLS Server (for normal user access).

6. An LDAP Client such as an LDAP browser, Mail Client etc. you will be delighted to know is always a TLS Client!

A number of worked TLS/SSL configuration examples are defined in Chapter 15. All TLS Server directives are added to cn=config entry or the global section of slapd.conf. All TLS Client directives are added to ldap.conf.

olcTLSCACertificateFile (TLSCACertificateFile)

# OLC (cn=config) form
olcTLSCACertificateFile: /path/to/CA/cert/file.pem

# slapd.conf form 
TLSCACertificateFile /path/to/CA/cert/file.pem

TLS Server attribute/directive. Defines the path and file name of the Certificate Authority (CA) certificate (a.k.a the root certificate) and is only used to verify an incoming certificate. This directive is only required when a client certificate is accepted or required by the server (olcTLSVerifyClient/TLSVerifyClient is one of try|demand|allow) - if the olcTLSVerifyClient/TLSVerifyClient default (never) is used this directive is not required. If required it points to a CA root certificate which must be obtained from the X.509 certificate supplier (the CA). This file is normally in PEM (Privacy enhanced Mail) format (and typically has a .pem suffix or, if obtained from an MSIE browser installation, may have a .cer suffix). If the operational X.509 certificate (defined in olcTLSCertificateFile/TLSCertificateFile is signed by intermediate authorities then all these certificates must be present within this PEM format file. PEM is a text format and multiple certificates can edited into the same file in any order - see PEM format notes and samples. This file does not contain sensitive information and therefore no special permissions are required (an X.509 certificate contains only a public key).

Note: If the LDAP server is acting as an TLS Client, for example it has a olcSyncrepl/syncrepl attribute/directive the required CA (root) certificate is added as a TLS_CACERT directive to ldap.conf.

olcTLSCertificateFile (TLSCertificateFile)

# OLC (cn=config) form
olcTLSCertificateFile: /path/to/cert/file.pem

# slapd.conf form 
TLSCertificateFile /path/to/cert/file.pem

TLS Server attribute/directive. Defines the path and file name of the operational X.509 server certificate (the subject DN's cn= attribute will denote the URL name of the LDAP server, for example, ldap.example.com) which contains the public key that will be used in the key exchange part of the TLS protocol. This file is normally in PEM (Privacy Enhanced Mail) format (and typically has a .pem suffix). PEM is a text format - see PEM format notes and samples. If this is a self-signed certificate then a olcTLSCACertificateFile/TLSCACertificateFile may, or may not be required depending how the certificate was created. OpenLDAP self-signed certificate configuration examples. This file does not contain sensitive information and therefore no special access permissions are required (an X.509 certificate contains only the public key).

olcTLSCertificateKeyFile (TLSCertificateKeyFile)

# OLC (cn=config) form
olcTLSCertificateKeyFile: /path/to/private/key/file.pem

# slapd.conf form 
TLSCertificateKeyFile /path/to/private/key/file.pem

TLS Server attribute/directive. Defines the location of the private key whose public key is contained in the server certificate (defined in olcTLSCertificateFile/TLSCertificateFile) and which is used to decode the bulk data cipher pre-master key sent by the TLS Client during the TLS session handshake. It will typically have a .pem suffix. This private key is extremely sensitive data and ideally should be maintained in a separate directory structure with limited read permissions and, as a minimum, the file itself should have read-only permission (0400) for the account under which OpenLDAP runs - normally ldap. OpenLDAP self-signed certificate configuration examples. Example:

# OLC (cn=config) form
olcTLSCertificateKeyFile: /certs/ldapcert.pem

# slapd.conf form 
TLSCertificateKeyFile /certs/ldapcert.pem

# minimum security - file only permissions
# assuming ldap account
chown ldap:ldap /certs/ldapcert.pem
chmod 0400 /certs/ldapcert.pem

# directory plus file security
chown -R ldap:ldap /certs/*
chmod -R 0400 /certs/*

olcTLSCipherSuite (TLSCipherSuite)

# OLC (cn=config) form
olcTLSCipherSuite: cipher-list

# slapd.conf form 
TLSCipherSuite cipher-list

TLS Server attribute/directive. Optional directive and defaults to the value ALL (see below). Defines one or more cipher suites to be used during the TLS handshake negotiation. During this negotiation the TLS Client offers a list of cipher suites and the TLS server will accept the first cipher suite defined in its list that matches one from the client. The term cipher-list used in this directive description defines a list (in OpenSSL format) that will be converted by OpenSSL routines to a list of cipher suites in TLS/SSL format. More information about the cipher-list format may be obtained from the OpenSSL ciphers documentation. OpenLDAP self-signed certificate configuration examples.

The list of acceptable cipher-suites (and hence the cipher-list) is determined by the format of the public key contained within the X.509 certificate defined by the olcTLSCerificateFile/TLSCertificateFile attribute/directive. Thus, if this certificate contains an RSA public key then only RSA public key cipher suites can be used for the key-exchange/authentication parts of the TLS handshake.

If mutal certificate validation is required (both the TLS Server and the TLS Client send certificates) then the public-key format of both the TLS Server and the TLS CLient certificates must either be known or the value ALL used (see commands below).

Individual items in the cipher-list are separated by a colon (:), comma or space. The following is a subset of RSA TLSv1 names that could appear in a cipher-list and their equivalent TLS cipher suite text values (they are converted to hex values when sent on the wire. Note: The word EXPORT (or EXP) that appears in some of the following names refers to export strength ciphers, that is, some ciphers are only permitted in certain countries (see US Dept of Commerce Bureau of Industry and Security(BIS) and the Wassenaar Arrangement) and should be considered when configuring TLS systems that will be used internationally.

TLS CIPHER-SUITE NAME                   OPENSSL CIPHER-LIST NAME
==============================          ===================
TLS_RSA_WITH_NULL_MD5                   NULL-MD5
TLS_RSA_WITH_NULL_SHA                   NULL-SHA
TLS_RSA_EXPORT_WITH_RC4_40_MD5          EXP-RC4-MD5
TLS_RSA_WITH_RC4_128_MD5                RC4-MD5
TLS_RSA_WITH_RC4_128_SHA                RC4-SHA
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5      EXP-RC2-CBC-MD5
TLS_RSA_WITH_IDEA_CBC_SHA               IDEA-CBC-SHA
TLS_RSA_EXPORT_WITH_DES40_CBC_SHA       EXP-DES-CBC-SHA
TLS_RSA_WITH_DES_CBC_SHA                DES-CBC-SHA
TLS_RSA_WITH_3DES_EDE_CBC_SHA           DES-CBC3-SHA
TLS_RSA_WITH_AES_128_CBC_SHA            AES128-SHA
TLS_RSA_WITH_AES_256_CBC_SHA            AES256-SHA
TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA     EXP1024-DES-CBC-SHA
TLS_RSA_EXPORT1024_WITH_RC4_56_SHA      EXP1024-RC4-SHA

To list the cipher-list values supported by the local OpenSSL installation use:

# ALL valid ciphers 
openssl ciphers -v ALL

# ALL valid ciphers for TLSv1 only
openssl ciphers -v -tls1 ALL

# valid ciphers for TLSv1 only that use RSA
# key exchange/authentication algorithm
openssl ciphers -v -tls1 RSA

# valid ciphers for TLSv1 only that use RSA
# key exchange/authentication algorithm
# exclude export strength ciphers
openssl ciphers -v -tls1 RSA:!EXP
# NOTE: on certain shells you need to escape !
openssl ciphers -v -tls1 RSA:\!EXP

# as above but also exclude NULL suites
openssl ciphers -v -tls1 RSA:!EXP:!NULL
# NOTE: on certain shells you need to escape !
openssl ciphers -v -tls1 RSA:\!EXP:\!NULL

# valid ciphers for TLSv1 only that use RSA
# key exchange/authentication algorithm
# only export strength ciphers
openssl ciphers -v -tls1 RSA:EXP
# OR
openssl ciphers -v TLSv1+RSA:EXP

When used with olcTLSCipherSuite/TLSCipherSuite either the generic parameters shown with openssl ciphers command above can be used (in which case the order of preference is defined by openssl) or an explicit list of ciphers can be defined in order of preference. One or more of the supported items in the cipher-list must be supported by the TLS Client. The cipher suite matching algorithm (which cipher suite is selected) is the first (highest preference) cipher suite provided by the client which is also supported by the server becomes the negotiated (session) cipher suite. The following examples use the TLSv1 (SSLv3) subset only:

# Cipher-list contains only RSA based
# authentication and key-exchange suites 
# supported by TLSv1 (and SSLv3)

# OLC (cn=config) form
olcTLSCipherSuite: TLSv1+RSA

# slapd.conf form 
TLSCipherSuite TLSv1+RSA

# Cipher-list contains only RSA based
# authentication and key-exchange suites 
# supported by TLSv1 (and SSLv3)
# excludes EXPORT and NULL suites
# OLC (cn=config) form
olcTLSCipherSuite: TLSv1+RSA:!EXPORT:!NULL

# slapd.conf form 
TLSCipherSuite TLSv1+RSA:!EXPORT:!NULL

# Ordered list of RSA based
# authentication and key-exchange suites
# OLC (cn=config) form
olcTLSCipherSuite: DES-CBC-SHA:DES-CBC3-SHA:RC4-SHA:RC4-MD5

# slapd.conf form 
TLSCipherSuite DES-CBC-SHA:DES-CBC3-SHA:RC4-SHA:RC4-MD5

# All ciphers excluding NULL
# OLC (cn=config) form
olcTLSCipherSuite: ALL:!NULL

# slapd.conf form 
TLSCipherSuite ALL:!NULL

# Default equivalent value if not defined
# OLC (cn=config) form
olcTLSCipherSuite: ALL

# slapd.conf form 
TLSCipherSuite ALL

Note: OpenSSL supports a number of cipher suites which may result in NULL bulk data and MAC values (if that is the only mutually supported value between the Server and Client). This means that while authentication is performed securely all data is subsequently sent in the clear. To prevent this from occurring either use the !NULL value in the cipher-list or define an explicit list that excludes NULL ciphers.

olcRandFile (TLSRandFile)

# OLC (cn=config) form
olcTLSRandFile: /path/to/random/file/name

# slapd.conf form 
TLSRandFile /path/to/random/file/name

TLS Server attribute/directive. Most *nix systems, such as Linux and BSD, support either /dev/urandom or /dev/random therefore this attribute/directive is not typically required. The attribute/directive may also be used to specify an alternative source of random data if either specialized requirements exist or /dev/urandom (/dev/random) is an unreliable source due to its use by other applications. If defined it specifies a file containing random bits. Alternative forms acceptable to OpenSSL (used by OpenLDAP for its TLS implementation) may be found in the OpenSSL FAQ.

olcTLSHDParamFile (TLSEphemeralDHParamFile)

# OLC (cn=config) form
olcTLSHDParamFile: /path/to/file

# slapd.conf form 
TLSEphemeralDHParamFile /path/to/file

TLS Server attribute/directive. This attribute/directive specifies the file that contains parameters for Diffie-Hellman ephemeral key exchange. This directive is only required if a DSA/DSS certificate is contained in the olcTLSCertificateFile/TLSCertificateFile (and olcTLSCertificateKeyFile/TLSCertificateKeyFile points to a DSA/DSS key). Parameters can be generated using the following command:

openssl dhparam [-dsaparam] -out <filename> <numbits>

Further information on DH parameters (dhparam) can be obtained from the openssl site.

olcTLSVerifyClient/TLSVerifyClient

# OLC (cn=config) form
olcTLSVerifyClient: never | allow | try | demand

# slapd.conf form 
TLSVerifyClient  never | allow | try | demand  

TLS Server attribute/directive. TLS allows for server only authentication (only the server has an X.509 certificate) or mutual authentication (both the client and server have X.509 certificates). olcTLSVerifyClient/TLSVerifyClient defines how the TLS server will implement mutual X.509 certificate authentication: never (default) indicates that the server will never request a client certificate; allow indicates the server will request a client certificate and if one is not provided the session will continue normally, if a client certificate is provided but cannot be verified (a corresponding CA (root) certificate cannot be found) then the certificate will be ignored and the session will continue normally; try indicates the server will request a client certificate and if none is provided the session will continue normally, if a client certificate is provided but cannot be verified (a corresponding CA (root) certificate cannot be found) the session will be terminated; demand indicates the server will request a client certificate and if none is provided the session will terminate, if the client certificate cannot be verified (a corresponding CA (root) certificate cannot be found) the session will also be terminated. The default is never.

6.4 Backend Section Directives (OLC (cn=config) and slapd.conf)

backend

Format:

backend type

The backend directive defines the name of the backend to be used. In OLC (cn=config) the backend is defined by an entry of the form olcBackend={Z}type,cn=config (where Z is an ordered set sequence number) using the olcBackendConfig objectClass. The full list of supported backend types is exactly the same as for the olcDatabase/database attribute/directive - see the note below.

Example:

backend bdb
# uses the Berkeley (Oracle) Database

Note: This entry/directive appears to be not strictly required - viable OLC (cn=config) and slapd.conf configurations can be created by omitting it entirely - indeed our configurations, OLC (cn=config) or slapd.conf) never use a backend. It is especially confusing since it should appear immediately before a database entry/directive with exactly the same value. But hey, what do we know. Perhaps the OpenLDAP designers had an idea for a set of 'generic parameters' that would apply to all databases minimising the need for typing (good idea). However, since many (most) LDAP installations use a single DIT (and hence database entry/section) little is, in practice, gained. In OLC (cn=config) the objectClass used is, essentially, an empty placeholder.

6.5 Database Section Directives (OLC (cn=config) and slapd.conf)

The attributes/directives in the database section consist of general attributes/directives that relate to almost all database types and specific attributes/directives which relate to the type, such as, bdb.

1. olcAccess (access to)
2. database entry/directive
3. olcDbIndex (index)
4. olcMirrorMode (mirrormode)
5. overlay entry/directive
6. olcReadOnly (readonly)
7. replica
8. replogfile
9. olcRootDN (rootdn)
10. olcRootPW (rootpw)
11. olcSuffix (suffix)
12. olcSyncrepl (syncrepl)
13. updatedn
14. olcUpdateRef (updateref)

Database Entry/Directive

Format:

# slapd.conf form
database type

The database entry/directive defines the beginning of a DIT and how it is mapped onto the file system.

In OLC (cn=config) databases are entries of the form olcDatabase={Z}type,cn=config. Description of the layout/organization of the cn=config DIT. Usage notes on Adding/Deleting Databases.

The following are valid type values supported by OpenLDAP:

Examples:

slapd.conf form
database bdb
# uses the Berkeley (sleepy cat) Database

olcMirrorMode (mirrormode)

# OLC (cn=config) form
olcMirrorMode: TRUE | FALSE

# slapd.conf form
mirrormode TRUE | FALSE

The olcMirrorMode/mirrormode attribute/directive is theoretically used to indicate that the database is running in "mirrormode" - a variation on multi-mastering developed prior to the availability of N-way multi-mastering with 2.4+. In a multi-master configuration olcMirrorMode/mirrormode TRUE must be present. In the case of slapd.conf this directive must appear AFTER ALL SYNCREPL DIRECTIVES, in every master database section to permit writes. In all cases (slapd.conf and OLC (cn=config)) failure to add this directive will cause write operations to fail in a multi-mastered DIT (one which has both a olcSyncRepl/syncrepl attribute/directive and a overlay syncprov entry/directive). Examples:

# slapd.conf example of positioning
# when used with multi-mastering
# global directives
...

# DIT (database) section fragment
database bdb
...
# first master provider
syncrepl
 ...
# second master provider
syncrepl
 ...
# provider definition
overlay syncprov
...
# after ALL syncrepl directives
mirrormode TRUE

olcOverlay (overlay)

The overlay entry/directive indicates the use of an overlay (or extension). In the case of slapd.conf it is defined in a database section and should always be defined after all other database section directives. Each overlay directive will be followed by one or more overlay specific directives which are described by the overlays documentation (see below). Multiple overlay directives may be defined for each database section (each followed by one or more overlay specific directives) and in this case they will executed in the reverse order to that in which they are defined - that is the overlay defined last will be executed first.

In OLC (cn=config) each overlay is a child entry of the database entry to which it applies and will have a form of olcOverlay={Z}name,olcDatabase={z}type,cn=config. Description of the layout/organization of the cn=config DIT. Usage notes on Adding/Deleting Overlays.

In slapd.conf the overlay directive has the following format:

# slapd.conf form
overlay overlay-name

# example - two overlays with directives
# (overlay accesslog processed first)

overlay syncprov
syncprov-checkpoint 10 100
...
overlay accesslog
logdb cn=accesslog
...

The following defines an incomplete list of overlay-names (complete list use 'man slapd.overlays' 2.4+):

olcReadOnly (readonly)

# OLC (cn=config) form
olcReadOnly: TRUE | FALSE

# slapd.conf form
readonly on | off

The olcReadOnly/readonly attribute/directive disables modify requests (they will return error 53 'unwilling to perform') making the DIT 'read-only'. When operating as a slave DIT (More information and configuration examples of Replication) the DIT is automatically placed in read only mode for all servers except that specified by an olcUpdateDN/updatedn attribute/directive (slurp replication) or that do not have a olcSyncrepl/syncrepl attribute/directive (syncrepl replication) and this directive MUST NOT be present. Example:

# disable modify operations for this DIT
# OLC (cn=config) form
olcReadOnly: TRUE

# slapd.conf form
readonly on

replica

Obsoleted in OpenLDAP 2.4, in OLC (cn=config) only supported to enable slapd.conf conversion. The replica directive is used (together with the replogfile directive) to describe one or more slave servers used in slurpd DIT replication. This directive appears only in the Master DIT definition (database section). The replica directive defines the location and access details of each SLAVE copies of the DIT. More information and configuration examples of Replication. The replica directive is only valid in OpenLDAP up to version 2.3 (using slurpd style replication). In version 2.4 the replica directive was obsoleted and replaced with the olcsyncrepl/syncrepl attribute/directive The generic format of the replica directive is:

replica uri=ldap[s]://hostname[:port]
 [bindmethod={simple|kerberos|sasl}]
 ["binddn=DN"]
 [saslmech=mech]
 [authcid=identity]
 [authzid=identity]
 [credentials=password]
 [srvtab=filename]

The uri= parameter specifies the scheme, host and optionally a port where the slave DIT instance is located. Either a domain name or IP address may be used for hostname. If port is not given, the standard LDAP port number (389 -ldap or 636 -ldaps) is used.

The binddn= parameter defines the DN (in quoted string format) to bind to when updating the slave DIT server instance of the Master. It must be a DN which has read/write access to the slave slapd's database and must also match the updatedn directive in the slave servers slapd.conf file. For reasons of security it is recommended that this DN should not be the same as the rootdn of the master database (though it can be). If the binddn is not the rootdn then it must point to a valid entry in the DIT with a userPassword (or authPassword) attribute.

The bindmethod may be simple or kerberos or sasl and defines the authentication method to be used when updating the slave copy of the DIT. Simple authentication is not recommended unless adequate integrity and privacy protections are in place (for example TLS or IPSEC). Simple authentication requires specification of binddn and credentials parameters.

Kerberos authentication is deprecated in favor of SASL authentication mechanisms, in particular the KERBEROS_V4 and GSSAPI mechanisms. Kerberos authentication requires binddn and srvtab parameters. It is not described further.

SASL authentication is generally recommended. SASL authentication requires specification of a mechanism using the saslmech parameter. Depending on the mechanism, an authentication identity and/or credentials can be specified using authcid and credentials respectively. The authzid parameter may be used to specify an authorization identity.

If multiple slave servers are required then a replica directive must defined for each slave instance.

Examples:

# simple security to slave located at ldap-rep1.example.com 
# with a cleartext password
replica uri=ldap://ldap-rep1.example.com bindmethod=simple
  binddn="uid=admin,ou=admin,dc=example,dc=com" credentials=guess

# simple security to slave located at ldap-rep1.example.com 
# with a cleartext password
replica uri=ldap://ldap-rep1.example.com bindmethod=simple
  binddn="uid=admin,ou=admin,dc=example,dc=com" 
  credentials=dirtysecret

replogfile

Obsoleted in OpenLDAP 2.4, in OLC (cn=config) only supported to enable slapd.conf conversion. The replogfile directive is used (together with the replica directive) to describe one or more slave servers used in slurpd style DIT replication. This directive appears only in the Master DIT definition (database section). The replogfile directive defines the location of the file used to store updates that slurpd will send to one or more slave servers. More information and configuration examples of Replication. The replogfile directive is only valid in OpenLDAP up to version 2.3 (using slurp style replication). In version 2.4 the replogfile directive was obsoleted and has no equivalent when used with syncrepl style replication. The generic format of the replogfile directive is:

replogfile path/to/logfile

Where path/to/logfile may be absolute or relative.

When used for replication this directive is read by slurpd to source the transactions to be sent to the slave defined by the replica directive(s). slurpd updates the file referenced by this directive so appropriate permissions must be applied.

Examples:

# relative format
replogfile ../log/slavedit.log

# absolute format
replogfile /var/log/ldap/slavedit.log

The replogfile directive may also be used without a corresponding replica directive and without running slurpd in which case it will simply generate a transaction log. In this case, the file should be periodically maintained since it will grow indefinitely large.

olcRootDN (rootdn)

Defines the DN of a root (unfortunate and misleading term in this context) or superuser for this DIT. When binding as the rootdn write privileges to all this DITs entries, objectsclases and attributes are automatically granted - no global or local ACLs are applied (it bypasses any rules defined in olcAccess/access attributes/directives). If it is NOT present no superuser privileges are granted. A rootdn is normally required when initially building the directory but once established it can be removed for security reasons. Only LDAP authenticated binds are allowed to the olcRootDN/rootdn.

The superuser is a magic entry and, provided it is used with a olcRootPW/rootpw, does not require to be defined in a normal entry that is, it does not need to be visible in the DIT structure. The user may decide, for security reasons, not to define a corresponding olcRootPW/rootpw attribute/directive. Since a password is always required to access the rootdn/superuser priviliges this password must be stored in valid entry within the DIT referenced by the olcRootDN/rootdn thus, in this case, the entry must be visible within the DIT and have a recongnized password attribute, for example, userPassword from the person objectclass.

The olcRootDN/rootdn should normally lie inside the name space of the DIT being defined in its database entry/section. Thus, if the olcSuffix/suffix is dc=example,dc=com then the olcRootDN/rootdn could be any DN that terminates in dc=example,dc=com such as cn=anything,dc=example,dc=com. If it lies outside this DIT's namespace access may result in a referral depending on other configuration parameters. The optional olcRootPW/rootpw attribute/directive provides authentication when binding to the olcRootDN/rootdn.

Many distributions have an example file with a olcrootDN/rootdn of "cn=Manager,dc=example,dc=com" or similar. The choice of the name cn=Manager is entirely arbitrary - it could just as easily have been cn=gobbledegook.

# OLC (cn=config) form
olcSuffix: dc=example,dc=com
# olcRootDN in this namespace
olcRootDN: cn=joeschmo,dc=example,dc=com

# slapd.conf form
suffix "dc=example,dc=com"
# rootdn DN in this DITs namespace
rootdn "cn=joeschmo,dc=example,dc=com"

olcRootPW (rootpw)

Defines the password that will be applied to the root or superuser for the DIT defined by this database entry/section and is only effective if the olcRootDN/rootdn lies inside this database entry/sections's name space. The password may be defined in cleartext or may use a password-hash format (created with slappasswd utility) for protection. It may also optionally be enclosed in quotes for convenience or when it contains a space character. It should be noted that when a hash is used this is merely a method to protect the password from unintentional leakage. An alternative (slapd.conf only) method could be to set permissions to only allow the ldap group to have read access - typically user = ldap and group = ldap - with a permission mask of 0740 or lower (slapd automatically ensures the correct permissions, changing if necessary, on slapd.conf load). Even when secured in OLC (cn=config) or slapd.conf using a hash when an LDAP client sends the root password for verification it is sent in the clear, any required hash is applied, and the result is compared to the stored olcRootPW/rootpw. Thus, the password is still prone to network snooping (TLS removes this threat).

If the olcRootPW/rootpd attribute/directive is omitted then one of the other security methods (for instance SASL) could be used. Examples:

# OLC (cn=config) form
olcRootDN: cn=good,dc=example,dc=com
# simple clear password version
# beware there are no spaces following secret unless required!
olcRootPW: secret
# delimited version
olcRootPW: "secret"
# SSHA version of secret
olcRootPW: {SSHA}HZvHCuZL/YcWfpi/WkqVWASiCxQnEzfW
# delimited version
olcRootPW: "{SSHA}HZvHCuZL/YcWfpi/WkqVWASiCxQnEzfW"

# slapd.conf form
rootdn "cn=good,dc=example,dc=com"
# simple clear password version
# beware there are no spaces following secret unless required!
rootpw secret
# delimited version
rootpw "secret"
# SSHA version of secret
rootpw {SSHA}HZvHCuZL/YcWfpi/WkqVWASiCxQnEzfW
# delimited version
rootpw "{SSHA}HZvHCuZL/YcWfpi/WkqVWASiCxQnEzfW"

Notes:

1. To edit the encrypted version of a password into OLC (cn=config) or slapd.conf file see notes at the end of slappasswd.
2. Most of the hashes supported by slappasswd have a salted version. Salt in this case refers to the addition of some random data to the password which significantly reduces the possibility of dictionary based attacks. In general if hashes are used a salted version should be selected.
3. To secure a password during transmission either use a SASL method or TLS/SSL.

olcSuffix (suffix)

Suffix is one of the many confusing terms in LDAP (a.k.a root and base). the olcSuffix/suffix attribute/directive defines the Distinguished Name that forms the topmost node in the DIT handled by this database entry/section. You can have multiple DITs each of which has a separate database entry/section. Note: The suffix for database config and database monitor are hardcoded as respectively cn=config and cn=monitor and cannot be changed by the use of an olcSuffix/suffix attribute/directive. Root DN naming can be angst ridden.

# OLC (cn=config) form
# RFC 2377 format
olcSuffix: dc=example,dc=com

# x.500 format
olcSuffix: ou=example,c=us

# slapd.conf form
# RFC 2377 format
suffix "dc=example,dc=com"

# X.500 format
suffix "ou=example,c=us"

olcSyncrepl (syncrepl)

Available from version 2.2+. Defines the current database (DIT) as a replica which is kept up-to-date with another DIT content by establishing the current server as a replication consumer running a syncrepl replication engine. The corresponding master (a.k.a provider) is configured with a overlay syncprov entry/directive. The replicated content is kept synchronized to the master content using the LDAP Content Synchronization protocol (RFC 4533, interestingly, still with EXPERIMENTAL status though widely implemented). From 2.4 OpenLDAP now supports both classic Master-Slave and Multi-Master configurations. More information and configuration examples.

Any consumer (slave) can have multiple simultaneous olcSyncrepl/syncrepl connections each described by a separate attribute/directive.

Notes:

1. While the majority of implementations may use replication for classic operational backup or simple load balancing which generally require complete copies to be maintained, the feature can be used for a variety of functions. For example, it is possible to extract data of a certain type only, say, jpegPhoto (though to create a viable DIT as a minimum objectClass, + and all mandatory attributes for all possible objectClasses would also have to included). Alternatively, in a multi-master environment it is possible to sync only those attributes to selected masters that the user wishes to be updated at those masters (information hiding). Creative readers will undoubtedly find more applications.

2. When connecting to the provider (the operation defined by olcSynrepl/syncrepl) slapd is acting as a client (not a server) and therefore sources its default parameters from ldap.conf not cn=config (or slapd.conf).

# OLC (cn=config) form
olcSynrepl:

# slapd.conf form
syncrepl 
 [attrs=attr-list]
 [attrsonly]
 [authcid=identity]
 [authzid=identity]
 [binddn=dn]
 [bindmethod=simple|sasl]
 [credentials=passwd]
 [filter=filter-str]
 [interval=dd:hh:mm:ss]
 [keepalive=idle-seconds:probe-number:interval-seconds]
 [logbase=base DN]
 [logfilter=filter str]
 [network-timeout=seconds]
 provider=ldap[s]://hostname[:port]
 [realm=realm]
 [retry=retry-interval num-retries | + ]
 rid=replica-ID 
 [saslmech=mech]
 [schemachecking=on|off]
 [scope=sub|one|base] 
 searchbase=base DN
 [secprops=properties]
 [sizelimit=number-of-entries | 0 (unlimited)]
 [starttls=yes|critical]
 [suffixmassage=rename-dn]
 [syncdata=default|accesslog|changelog]
 [timelimit=seconds | 0 (unlimited)]
 [timeout=seconds]
 [tls_cacert=/path/to/file.ext]
 [tls_certdir=/path/to/directory]
 [tls_cert=/path/to/file.ext]
 [tls_cipher-suite=cipher-list]
 [tls_crlcheck=none|peer|all]
 [tls_key=/path/to/file.ext]
 [tls_protocol_min=major[.minor]]
 [tls_reqcert=allow|demand|try]
 [type=refreshOnly|refreshAndPersist]

Mandatory parameters are rid, provider and searchbase all others are optional.

# starts with comment symbol - indicates explantory text only
# copy all attributes (user and operational) for every objectClass
# if omitted defaults to this value
attrs="*,+"

# @objectClass format
# following will include all user attributes for objectClass
# inetOrgPerson (but not operational attributes)
attrs="@inetOrgPerson"

# create an minimal DIT extract based on inetOrgPerson jpegPhoto
attrs="+,objectclass,sn,cn,jpegPhoto"

# send the authentication password in CLEARTEXT
# OLC (cn=config) form
olcSynrepl:
 ...
 bindmethod=simple
 binddn="cn=goodguy,dc=example,dc=com"
 credentials=dirtysecret
 ...
# slapd.conf form
syncrepl
 ...
 bindmethod=simple
 binddn="cn=goodguy,dc=example,dc=com"
 credentials=dirtysecret
 ...
 
# send the authentication password over TLS
# OLC (cn=config) form
olcSynrepl:
 ...
 provider=ldaps://ldap.example.com
 bindmethod=simple
 binddn="cn=goodguy,dc=example,dc=com"
 credentials=dirtysecret
 ...
# slapd.conf form
syncrepl
 ...
 provider=ldaps://ldap.example.com
 bindmethod=simple
 binddn="cn=goodguy,dc=example,dc=com"
 credentials=dirtysecret
 ...

# exclude one attribute only
# OLC (cn=config) form
olcSynrepl:
 ...
 attrs="*,+"
 exattrs="jpegPhoto"
 ...
# slapd.conf form
syncrepl
 ...
 attrs="*,+"
 exattrs="jpegPhoto"
 ...

# OLC (cn=config) form
olcSynrepl:
 ...
 syncdata=accesslog
 logfilter=(&(objectclass=auditWriteObject)(reqResult=0))

# slapd.conf form
syncrepl
 ...
 syncdata=accesslog
 logfilter=(&(objectclass=auditWriteObject)(reqResult=0))

# non-TLS connection using port 386
# OLC (cn=config) form
olcSynrepl:
 ...
 provider=ldap://ldap.example.com
# optionally use starttls
 starttls=yes
 ...
# slapd.conf form
syncrepl
 ...
 provider=ldap://ldap.example.com
# optionally use starttls
 starttls=yes
 ...
 
# TLS connection using port 636
# OLC (cn=config) form
olcSynrepl:
 ...
 provider=ldaps://ldap.example.com
 # starttls must not be present
 ...
# slapd.conf form
syncrepl
 ...
 provider=ldaps://ldap.example.com
# starttls must not be present
 ...
 

# replicate whole DIT
# OLC (cn=config) form
olcSynrepl:
 ...
 searchbase="dc=example,dc=com"
 ...
# slapd.conf form
syncrepl
 ...
 searchbase="dc=example,dc=com"
 ...
 
# replicate subset of same DIT
# OLC (cn=config) form
olcSynrepl:
 ...
 searchbase="ou=people,dc=example,dc=com"
 ...
# slapd.conf form
syncrepl
 ...
 searchbase="ou=people,dc=example,dc=com"
 ...

# renames incoming DNs from dc=example,dc=com to dc=example,dc=net
# OLC (cn=config) form
olcSynrepl:
 ...
 searchbase="dc=example,dc=com"
 suffixmassage="dc=example,dc=net"
 ...
# slapd.conf form
syncrepl
 ...
 searchbase="dc=example,dc=com"
 suffixmassage="dc=example,dc=net"
 ...

The syncrepl replication mechanism is supported by database backends back-bdb and back-hdb only (2.4.31).

Examples:

The consumer will request updates from the master every 1 hour from master-ldap.example.com (using default port 389). In the event of failure to access the provider (master) the consumer will retry every 5 seconds for 5 attempts and then every 300 seconds (5 minutes) indefinitely. The whole DIT is covered (assuming the master suffix is dc=example,dc=com). All entries are transfered (no filter parameter) and all user and operational attributes (attrs="*,+"). The bind is simple with a cleartext password for cn=admin,ou=people,dc=example,dc=com. More information and configuration examples.

# OLC (cn=config) form
olcSuffix: rid=000 
  provider=ldap://master-ldap.example.com
  type=refreshOnly
  interval=00:1:00:00
  retry="5 5 300 +" 
  searchbase="dc=example,dc=com"
  attrs="*,+"
  bindmethod=simple
  binddn="cn=admin,ou=people,dc=example,dc=com"
  credentials=guess
	
# slapd.conf form
syncrepl rid=000 
  provider=ldap://master-ldap.example.com
  type=refreshOnly
  interval=00:1:00:00
  retry="5 5 300 +" 
  searchbase="dc=example,dc=com"
  attrs="*,+"
  bindmethod=simple
  binddn="cn=admin,ou=people,dc=example,dc=com"
  credentials=guess

For more information and configuration examples.

updatedn

Obsoleted in OpenLDAP 2.4, in OLC (cn=config) only supported to enable slapd.conf conversion. This directive is only applicable in a slave server's DIT instance when using slurpd style replication in OpenLDAP up to version 2.3 (it is obsoleted in version 2.4 and replaced with the syncrepl directive). More information and configuration examples of Replication.

updatedn DN | SASL-identity

This may be the DN slurpd binds as when making changes to the replica (used when the replica directive of the master uses a bindmethod of simple) or the DN associated with a SASL identity (if the replica directive's bindmethod is sasl).

# DN Example:
updatedn "cn=admin,dc=example,dc=com"

# SASL-based Example:
updatedn "uid=slurpd,cn=example.com,cn=digest-md5,cn=auth"

olcUpdateRef (updateref)

The olcUpdateRef/updateref attribute/directive is only applicable in a slave (or consumer) configuration and is used with both slurpd and syncrepl style replication. More information and configuration examples of Replication. Since slave (or consumer) servers are read only it specifies the URL to return to clients which submit modify (update) requests to the slave DIT instance.

# OLC (cn=config) form
olcUpdateRef: uri 

# slapd.conf form
updateref uri

Where uri is in the normal scheme://host[:port] format. If updateref is defined multiple times, each URL is provided in the returned referral.

Examples:

# defaults to 389
# OLC (cn=config) form
olcUpdateRef: ldap://ldap.example.com

# slapd.conf form
updateref ldap://ldap.example.com

# non standard port
# OLC (cn=config) form
olcUpdateRef: ldap://ldap.example.com:10389

# slapd.conf form
updateref ldap://ldap.example.com:10389

# secure ldap default port (636)
# OLC (cn=config) form
olcUpdateRef: ldaps://ldaps.example.com

# slapd.conf form
updateref ldaps://ldaps.example.com

6.5.7 slapd.conf Database Specific Directives - null

Placeholder

6.5.8 slapd.conf Database Specific Directives - passwd

Placeholder

Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.