Chapter 6. OpenLDAP slapd.conf

This chapter describes, in mind-numbing detail, all (eventually) parameters and directives used to control the LDAP systems covered in this Guide. Specifically OpenLDAP's sladp.conf, OpenLDAP's ldap.conf and ApacheDS configuration (server.xml).

If you want to get something simple going for OpenLDAP use the sample slad.conf.

Significant changes to slapd where introduced with version 2.3 and 2.4 these are described.

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

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 procecedures, 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 overriden by database directives. If a directive is specified in a global section and is not overriden its scope (infulenece) 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 altenative method allows slapd to be controled 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
loglevel
moduleload
modulepath
objectclass
pidfile
referral
replicationinterval
reverse-lookup
rootDSE
schemadn
ServerID
sizelimit
sockbuf_max_incoming
sockbuf_max_incoming_auth
threads
timelimit

Backend Directives

backend

Database Directives

access to
database
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 statements create what is sometimes known as Access Control Lists (ACL) or Access Control Policies (ACP).

The access directive may be placed in either the global or the database section of the slapd.conf file and grants access (specified by <accesslevel>) to a set of entries and/or attributes (specified by <what>) by one or more requesters (specified by <who>). Multiple access directives may be included.

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 the access directive 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. We document the raw parameters first which include limited examples then provide some worked examples which illustrate the major points.

# 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

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

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

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

Access worked examples

First some general notes about access directives:

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

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

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

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

Examples

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

OpenLDAP Default Access

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 OpenLDAP terminates every access directive with this rule to close any remaining doors - anything not covered by a preceding clause can do nothing. In the above case it is meaningless for reading since the previous clause allows read access (but at other times it is comforting to know) but it also prevents any write access by any normal user. Only the rootdn (superuser) and its rootpw can be used to write to the directory.

Limiting Access to Authenticated users

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 addititive 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 addititive 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 dirctive (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 addititive 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 chidren 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 addititive 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 specifies the time in seconds after which an idle client is forcibly logged out (unbind forced).

If no idletimeout directive is defined the feature is disabled i.e. idle clients are not logged out (no unbind forced). Examples:

idletimeout 0
# do not logout idle clients
idletimeout 30
# logout idle clients after 30 seconds

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

loglevel

OpenLDAP logs via syslogd LOCAL4. To stream the log to a separate file add a line like this to syslog.conf (normally /etc/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.

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 passible 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 a database type) 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 OpenLADAP 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 - permament 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:

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 each master in a Multi-master configuration must be uniquely identified. The number parameter is an arbitray 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. It is not at all clear what the URI form would be used for but one suspects collateral damage from a previous implementation. Examples:

serverid 001
# or
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 integer

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

sockbuf_man_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_man_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.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
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):

Examples:

database bdb
# uses the Berkeley (sleepy cat) Database

overlay

The overlay directive indicates the use of an overlay (or extension). It is defined in a database section should always be defined afte all other dataebase section directives. Each overlay directive will be followed by one or more overlay specific directive whichh are defined by the overlays documentation (see below). Mutile over directives may be defined for eacg database section (each followed by one or more overlay specific directives) and in this case they will executed in the reveser order to that in which they will be defined - that is the overlay defined last will be executed first. The overlay directive has the following format:

overlay overlay-name

# example - two overlays with directives
# (overlay accesslog proccesed 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+):

readonly Directive

The readonly directive disables modify requests (they will return '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 readonly mode for all clients except that specified by updatedn directive and this directive must not be defined.

readonly on|off

# example
# disable modify operations for this DIT
readonly on

replica Directive

Obsoleted in OpenLDAP 2.4. The replica directive is used (together with the replogfile 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 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 surpd style replication). In version 2.4 the replica directive was obsoleted and replaced with the syncrepl 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 rootn 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.exmple.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.exmple.com 
# with a SSHA encoded password
replica uri=ldap://ldap-rep1.example.com bindmethod=simple
  binddn="uid=admin,ou=admin,dc=example,dc=com" 
  credentials={SSHA}gkgkjdgkjgdkhg.ugsdbdnsj

replogfile Directive

Obsoleted in OpenLDAP 2.4. 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 surpd style replication). In version 2.4 the replogfile directive was obsoleted and has no equivalient 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.

rootdn Directive

Defines the DN of a root (unfortunate and misleading term in this context) or superuser that will have no access limits applied - it does not obey the rules defined for normal access directives. If it is NOT present no superuser priviledges are granted. This entry is normally required when initially building the directory but once established can (and ideally should) be removed for security reasons.

The superuser is a magic entry and does not require to be defined in a normal entry ie. it does need to be visible in the DIT structure even though many documents suggest it is necessary.

The rootdn should normally lie inside the name space of the DIT being defined for this database section in which case you can supply a rootpw to provide some security. If it lies outside this DIT's namespace access may result in a referral.

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

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

rootpw Directive

Defines the password that will be applied to the root or superuser for the DIT defined by this database section and is only effective if the rootdn lies inside this database sections's name space. The password may be cleartext (the weakest) or may use a password-hash (or {crypt}) format (created with slappasswd utility).

If the parameter is omitted then one of the other security methods (e.g. SASL) are used.

suffix Directive

One of the many confusing terms in LDAP (a.k.a root and base). This directive defines the Distinguished Name that forms the topmost node in the DIT handled by this database section. You can have multiple DITs each of which has a separate database 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 a suffix directive. Root DN naming can be angst ridden.

# RFC 2377 format
suffix "dc=example,dc=com"

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

syncrepl Directive

Form version 2.2+. Defines the the current database (DIT) as a replica which is kept up-to-date with the master (or another master) DIT content by establishing the current server as a replication consumer running a syncrepl replication engine. The corresponding master (provider) is configuraed with a overlay syncprov directive. The replica content is kept synchronized to the master content using the LDAP Content Synchronization protocol (RFC 4533). From 2.4 OpenLDAP now supports both classic Master-Slave and Multi-Master configurations. More information and configuration examples.

syncrepl rid=replica-ID 
  provider=ldap[s]://hostname[:port]
  [type=refreshOnly|refreshAndPersist]
  [interval=dd:hh:mm:ss]
  [retry=[retry-interval num-retries | + ] 
  searchbase=base DN
  [filter=filter str]
  [scope=sub|one|base]
  [attrs= attr list>]
  [attrsonly]
  [sizelimit=number-of-entries | unlimited]
  [timelimit=time-in-secs | unlimited]
  [schemachecking=on|off]
  [starttls=yes|critical]
  [bindmethod=simple|sasl]
  [binddn=dn]
  [saslmech=mech]
  [authcid=identity]
  [authzid= identity]
  [credentials=passwd]
  [realm=realm]
  [secprops=properties]
  [logbase=base DN]
  [logfilter=filter str]
  [syncdata=default|accesslog|changelog]

rid identifies the current syncrepl directive within the replication consumer site. It is an arbitrary, unique, non-negative integer having no more than three digits. provider specifies the replication provider site containing the master content as an LDAP URI. If port is not given, the standard LDAP port number (389 or 636) is used.

The content of the syncrepl replica is defined using a search specification as its result set - thus it is possible for a consumer to replicate the whole or part of any DIT. The consumer server will send search requests to the provider server according to the search specification. The search specification is defined by searchbase (quoted string), scope (default is sub), filter (default is (objectclass=*)), attrs (default "*,+" - all user and operational attributes), attrsonly (default false), sizelimit (default is unlimited), and timelimit (default is unlimited) parameters as in a normal search specification.

The LDAP Content Synchronization protocol supports two operation types. In refreshOnly operation, the synchronization (search) operations are periodically scheduled at an interval time (1 day by default, 86400 secs)) on completion of the synchronization session a syncCookie is returned by the provider and the connection is terminated. Another session is initiated by the consumer after interval time and the last session's syncCookie is provided to scope the changes - essentially only changes since the last session only are provided (if possible). When a new replication is initiated there is no syncCookie so the scope of synchronization is the whole search base (typically the whole DIT) and thus permits a new replication to start with an empty consumer DIT. Where large DITs are involved this can take a considerable period of time. When type is refreshAndPersist, the start of the session is the same as refreshOnly type but once intial synchronization is completed the connection is maintained and changes (within the synchronization search scope) are sent from the provider to the consumer as they occur providing almost instantaneous update propagation.

If an error occur during replication (either refreshOnly or refreshAndPersist), the consumer will attempt to reconnect according to the retry parameter which is a list of retry-interval and num-retries pairs. For example, retry="60 10 300 3" directs the consumer to retry every 60 seconds for the first 10 times and then retry every 300 seconds for the next 3 times before it stops retrying. If num-retries is `+' the consumer will retry indefinitely. schemachecking performs normal schema checks. The default is off.

The starttls parameter specifies use of the StartTLS extended operation to establish a TLS session before Binding to the provider. If the StartTLS request fails and the critical argument was used, the session will be aborted. Otherwise the syncrepl session continues without TLS.

A bindmethod of simple requires the options binddn (quoted string) and credentials and should only be used when adequate security services (e.g. TLS or IPSEC) are in place. {CRYPT}, {MD5}, {SMD5}, {SSHA}, {SHA} and {CLEARTEXT} forms are supported (depending on the server). A bindmethod of sasl requires the patramater saslmech. Depending on the mechanism, an authentication identity and/or credentials can be specified using authcid and credentials. The authzid parameter may be used to specify an authorization identity. Specific security properties (as the sasl-secprops keyword above) for a SASL bind can be set with the secprops parameter. A non default SASL realm can be set with the realm option.

Rather than replicating whole entries, the consumer can query logs of data modifications using the syncdata parameter. This mode of operation is referred to as delta syncrepl. In addition to the above parameters, the logbase and logfilter parameters must be set appropriately for the log that will be used. To invoke delta replication the syncdata parameter must be set to "accesslog" if the log conforms (assumes use of overlay accesslog). "changelog" defines the obsolete changelog format. If the syncdata parameter is omitted or set to "default" then the log parameter is ignored.

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

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 willretry every 5 seconds for 5 attempts and then every 300 seconds (5 minutes) indefinetly. The whole DIT is covered (assuming the master suffix is dc=example,dc=com). All entries are transfered (no filter parameter) and all user attrs (attrs=*). The bind is simple with an SSHA encoded password to cn=admin,ou=people,dc=example,dc=com.

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={SSHA};gj;jjglsdknjghkjhgsdajggbjsdjb

For more information and configuration examples.

updatedn Directive

Obsoleted in OpenLDAP 2.4. 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 simmple) 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"

updateref Directive

The updateref directive is only applicable in a slave (or consumer slapd.conf) file 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.

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:

updateref uri

#examples
# defaults to 389
updateref ldap://ldap.example.com

# non standard port
updateref ldap://ldap.example.com:10389

# secure ldap default port (636)
updateref ldaps://ldaps.example.com

6.5.7 slapd.conf Database Specific Directives - null

6.5.8 slapd.conf Database Specific Directives - passwd