Chapter 6. LDAP Configuration

This chapter describes, in mind-numbing detail, all parameters and directives used to control the LDAP systems covered in this Guide. Specifically OpenLDAP's 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 sample slapd.conf.

Significant changes to slapd where introduced with version 2.3 and 2.4 these are described. The most important change is that, while slapd.conf is still supported (as of 2.4), increasingly OpenLDAP is moving toward Run-Time Configuration (RTC) - 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, cn=config is described and will increasingly become the normal method of describing configuration in this guide.

Contents

6.1 slapd.conf Overview
6.1.1 Converting slapd.conf to use cn=config/slapd.d
6.2 slapd.conf List of Directives
6.3 slapd.conf Global Section Directives
6.3.1 slapd.conf TLS Directives
6.4 slapd.conf Backend Section Directives
6.5 slapd.conf Database Section Directives
6.5.1 slapd.conf Overlay Directive
6.6 ldap.conf Directives
6.7 ApacheDS Configuration

Note: slapd daemon command line options.

6.1 slapd.conf Overview

slapd.conf parameters are divided into global, backend and database or (DIT) specific. The following notes may useful:

1. OpenLDAP version 2.3 introduced a significant, but optional, change to the method by which configuration directives 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 real-time configuration - variously and confusing known as zero down-time configuration, cn=config or slapd.d configuration. The procedures, effects and conversion are described.

2. global parameters apply to the LDAP server they typically include environmental parameters, such as the location of files.

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

4. Lines beginning with # are ignored and assumed to be comments

5. Blank lines are ignored - BUT lines beginning with a space are assumed to 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 section.

7. There must be one database 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 sections. There can be any number of these sections. The first database entry is given the database number 1 the second 2 etc.

8. slapd.conf is normally located in:

   [fc] /etc/openldap
   [bsd] /usr/local/etc/openldap
   

6.1.1 Converting slapd.conf to use cn=config/slapd.d

OpenLDAP version 2.3 introduced an alternative method to control and configure slapd. The alternative method allows slapd to be controlled at run-time using a special DIT entry called cn=config. For information on how to convert and subsequently control slapd.

6.2 slapd.conf List of Directives

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

Global Directives

access to
argsfile
attributetype
concurrency
conn_max_pending
con_max_auth
defaultaccess
defaultsearchbase
gentlehup
idletimeout
include
index
logfile
loglevel
moduleload
modulepath
objectclass
pidfile
referral
replicationinterval
reverse-lookup
rootDSE
schemadn
security
ServerID
sizelimit
sockbuf_max_incoming
sockbuf_max_incoming_auth
threads
timelimit

TLS/SSL Directives (Global Section)

TLS Server overview - what is a TLS Server

Server (Provider) Directives

TLSCACertificateFile
TLSCertificateFile
TLSCertificateKeyFile
TLSCipherSuite
TLSRandFile
TLSEphemeralDHParamFile
TLSVerifyClient

Client (Consumer) Directives

TLS Server overview - what is a TLS Client
TLS_CACERT

Backend Directives

backend

Database Directives

access to
database
index
mirrormode
overlay
readonly
replica
replogfile
rootdn
rootpw
suffix
syncrepl
updatedn
updateref

6.3 slapd.conf Global Section Directives

Access to

Format:

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

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

The 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 access to directives may be included in either or both of the global section or a specific DIT (database section) of slapd.conf. If the access to directive is defined in the global 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.

access to 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 access to 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 access to 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 access 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 expression does not have ()
access to dn="ou=[^,]+,cn=([^,]+),dc=example,dc=com"
 by dn.exact="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 ...

# access to the defined DN and all lower levels
# dnstyle is missing so regex is defaulted
# covers all DNs below the defined DN as well
access to dn="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

# 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!

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 access to directives:

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

2. If there is no access 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 either defined as regex (regular expression) or not defined (defaults to regex) the supplied pattern is used in regular expression matching so dn="dc=example,dc=com" will apply to all subtree entries e.g. "ou=people,dc=example,dc=com" and will use a lot of 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 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: Each new line within the directive must be indented by at least one space.

6. One or more access directives may be used and each by <who> rule may have a <control>. Example:

   # Access directive 1
   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 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 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.

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
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

We will force all external users to authenticate, allow local network users anonymous read access, 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) 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
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 database

We are going to build 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
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
# ACL1
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="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
# allow user to create entries in their own addressbook; no-one else can access it
# needs write access to the entries ENTRY attribute (ACL5) and 
# the entries CHILDREN (ACL4)
access to dn.regex="ou=addressbook,cn=([^,]+),ou=people,dc=example,dc=com$"
   attrs=children
  by dn.regex="cn=$1,ou=people,dc=example,dc=com" write
  by users none

# ACL5
# allow one to create entries in its own addressbook; no-one else can access it
# needs write access to the entries ENTRY attribute (ACL5) 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
# 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

# LDAP 2.2+ replace ACL5 and ACL6 with
#access to dn.regex="ou=addressbook,cn=([^,]+),ou=people,dc=example,dc=com$"
#   attrs=entry,@inetorgperson
#  by dn.regex="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=zytrax,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. expand is a keyword that performs substitution of $1 with the users cn (obtained from regex above. The use of exact,expand is faster that using a regular expression again - we could have used dn.regex"cn=[^,],ou=people,dc=example,dc=com". 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

   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.regex,expand="cn=$1,ou=people,dc=example,dc=com" write. expand is a keyword that indicates to performs substitution of $1 with the users cn - this is done before the regular expression match. This regular expression 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 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 children partner of ACL4

   1. 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. 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. ACL7

   1. ACL7 access to dn.one="ou=customers,dc=zytrax,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.

8. 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).

9. 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.

argsfile

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

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.

attributetype

OpenLDAP - as an artifact of schema processing - allows the definition of one or more attributetypes in the slapd.conf file. attributetype definition is explained here. It is not clear why you would want to add attributes 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.

concurrency

Format:

concurrency integer

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

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 concurrency directive and the threads directive.

conn_max_pending

Format:

conn_max_pending integer

The conn_max_pending 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:

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

conn_max_auth

Format:

conn_max_auth integer

The conn_max_auth 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:

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.

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

defaultsearchbase

Format:

defaultsearchbase dn

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

defaultsearchbase dc=mydomain,dc=com
# will return search results as if
# the above dn has been supplied instead of blank

It is not clear what is the relationship between the concurrency directive and the threads directive.

gentlehup

Format:

gentlehup on | off

The gentlehup directive if on allows OpenLDAP to perform a graceful shutdown when it receives a SIGHUP signal e.g.:

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 idletimeout and timelimit directives are in operation. OpenLDAP will as always respond immediately to a SIGTERM signal. Default is off.

Examples:

gentlehup on
# allows possible graceful shutdown to SIGHUP

gentlehup off
# treats SIGHUP as SIGTERM

It is not clear what is the relationship between the concurrency directive and the threads directive.

idletimeout

Format:

idletimeout integer

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

If no idletimeout directive is defined or an idletimeout 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:

idletimeout 0
# do not logout idle clients
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 the syncrepl directive 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 idletimeout 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

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

index

index attrlist | default indices

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

# simple use of the default value
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

logfile

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

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

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 logfile directive may be used.

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 loglevel 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.

moduleload

A stunning 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 moduleload 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 modulepath directive or the PATH, LTDL_LIBRARY_PATH and LD_LIBRARY_PATH if modulepath is not defined. This directive and the modulepath 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 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 moduleload 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 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 built ([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 moduleload 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.

moduleload module-name

# example - permanent load of the syncprov overlay
loadmodule syncprov.la

# absolute path format
loadmodule /usr/local/libexec/openldap/syncprov.la

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 moduleload.

objectclass

OpenLDAP - as an artifact of schema processing - allows the definition of one or more objectclass 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.

pidfile

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

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 a pidfile directive is not included no pid file will be created. Many scripts for starting and stopping slapd will only work when there is a PID file. You only alternative is to use a Kill command.

referral

Format:

referral uri

The referral 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 (using a suffix 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:

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

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 referral 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. 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.

reverse-lookup

Format:

reverse-lookup on | off

The reverse-lookup directive if on causes OpenLDAP to use DNS reverse lookup for each client access. The default is off. Directive is only effective if the build option --enable-rlookups was used. Examples:

reverse-lookup on
# causes OpenLDAP to perform a DNS reverse lookup for 
# each client access

rootDSE

Format:

rootDSE /path/to/ldif/file

The rootDSE 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. Examples:

security

security ssf-policy [...]

When using secure connections (either TLS or SASL) the security 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 minimum 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.

schemadn

Format:

schemadn cn=name

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

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

ServerID

Format:

serverid number [URI]

Version 2.4+. The serverid directive defines a unique number (a.k.a SID) for this server. It 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 parameter of the updated (in 2.4) CSN) to uniquely identify a host as the source of an update. If the optional URI form is used the directive may appear multiple times. Many multi-master configuration show all the servers within the multi-master group as being defined with their associated URIs. Experiments have shown this to be not required (the provider information is defined in the syncrepl directive) and one is left with the feeling that the URI form may be collateral damage from a previous good idea. Finally there is no relationship between the SID (server ID) and the rid parameter used in the syncrepl directive. Examples:

serverid 001
# or equivalent
serverid 1

sizelimit

The sizelimit directive specifies the number of entries to return to a search request. There are two forms of this command, first 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:

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 "Unwilling to perform". 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:

sizelimit 0
# do not logout idle clients
sizelimit 100
# limit responses to a maximum of 100

# extended form
sizelimit size=100
# behaves exactly the same as sizelimit 100
sizelimit size.soft=100 size.hard=200
# if no client limit = 100
# if client limit > 200 - rejected
# no limits to number of candidates searched
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

sockbuf_max_incoming

Format:

sockbuf_max_incoming bytes

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

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

sockbuf_max_incoming_auth

Format:

sockbuf_max_incoming_auth integer

The sockbuf_max_incoming_auth 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 

threads

Format:

threads integer

The threads 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:

threads 25
# allows a maximum of 25 threads

It is not clear what is the relationship between the threads directive and the concurrency directive.

timelimit

The timelimit 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:

timelimit number | unlimited

Where integer 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:

timelimit time[.{soft|hard}]=integer [..]

Where integer 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:

timelimit 15
# allow 15 seconds to complete the search 
# else return time limit exceeded error
timelimit 0
# disables the feature (default = 3600)
timelimit unlimited
# no time limit is applied

# extended format
timelimit time=15
# behaves exactly the same as timelimit 15
timelimit time.soft=15 time.hard=20
# client defines no limit 15 seconds is used
# if client requests time limit > 20 - rejected
timelimit time.soft=15
# client defines no limit 15 seconds is used
# if client requests any time limit - accepted
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/SSL Directives

TLS Overview - What is a TLS Server/Client

OpenLDAP differentiates between the 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 is a bit more complicated than that. 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 directives. The key difference is that a TLS Server never initiates communication whereas a TLS Client always does. This difference occurs at the database section level thus one database 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 directives in any database section and has no overlay chain directives is only a TLS server.

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

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

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

5. A LDAP server containing a overlay chain 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 slapd.conf. All TLS Client directives are added to ldap.conf.

TLSCACertificateFile

TLSCACertificateFile /path/to/CA/cert/file.pem

TLS Server 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 (TLSVerifyClient is one of try|demand|allow) - if the 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 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 syncrepl directive the required CA (root) certificate is added as a TLS_CACERT directive to ldap.conf.

TLSCertificateFile

TLSCertificateFile /path/to/cert/file.pem

TLS Server directive. Defines the path and file name of the operational X.509 server certificate (the subject DN's cn= field 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 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).

TLSCertificateKeyFile

TLSCertificateKeyFile /path/to/private/key/file.pem

TLS Server directive. Defines the location of the private key whose public key is contained in the server certificate (defined in 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:

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/*

TLSCipherSuite

TLSCipherSuite cipher-list

TLS Server directive. 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 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 TLSCertificateFile 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. 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 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)
TLSCipherSuite TLSv1+RSA

# Cipher-list contains only RSA based
# authentication and key-exchange suites 
# supported by TLSv1 (and SSLv3)
# excludes EXPORT and NULL suites
TLSCipherSuite TLSv1+RSA:!EXPORT:!NULL

# Ordered list of RSA based
# authentication and key-exchange suites
TLSCipherSuite DES-CBC-SHA:DES-CBC3-SHA:RC4-SHA:RC4-MD5

Note: OpenSSL supports a number of cipher suites which will result in NULL bulk data and MAC values. This means that while authentication is performed securely all data is subsequently send 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.

TLSRandFile

TLSRandFile /path/to/random/file/name

TLS Server directive. This directive is typically only required on systems that do not support /dev/urandom or /dev/random. Since most *nix systems, such as Linux and BSD, support either /dev/urandom or /dev/random this directive is not typically required. The 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.

TLSEphemeralDHParamFile

TLSEphemeralDHParamFile /path/to/file

TLS Server directive. This 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 TLSCertificateFile (and 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.

TLSVerifyClient

TLSVerifyClient  never | allow | try | demand  

TLS Server 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). TLSVerifyClient defines how the TLS server will implement mutual X.509 certificate authentication: never 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 slapd.conf Backend Directives

backend

Format:

backend type

The backend directive defines the name of the backend to be used. The following are valid type values supported by OpenLDAP (slapd):

Examples:

backend bdb
# uses the Berkeley (sleepy cat) Database

Note: This directive appears to be not strictly required - viable slapd.conf configurations can be created by omitting it entirely. It is especially confusing since it should appear immediately before a database 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 section) little is, in practise, gained.

6.5 slapd.conf Database Directives

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

access to
database
index
mirrormode
overlay
readonly
replica
replogfile
rootdn
rootpw
suffix
syncrepl
updatedn
updateref

Database Directive

Format:

database type

The database directive defines the beginning of a DIT and how it mapped onto the file system. The following are valid type values supported by OpenLDAP (slapd):