OpenLDAP Software 2.4 Administrator's Guide Open LDAP Admin

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 266

Download
Open PDF In Browser	View PDF

OpenLDAP Software 2.4 Administrator's Guide

Table of Contents
Table of Contents.....................................................................................................................................1
Preface..................................................................................................................................................................1
Copyright.................................................................................................................................................1
Scope of this Document...........................................................................................................................1
Acknowledgments....................................................................................................................................2
Amendments............................................................................................................................................2
About this document................................................................................................................................3
1. Introduction to OpenLDAP Directory Services...........................................................................................3
1.1. What is a directory service?..............................................................................................................3
1.2. What is LDAP?.................................................................................................................................6
1.3. When should I use LDAP?...............................................................................................................6
1.4. When should I not use LDAP?.........................................................................................................6
1.5. How does LDAP work?....................................................................................................................7
1.6. What about X.500?...........................................................................................................................7
1.7. What is the difference between LDAPv2 and LDAPv3?.................................................................7
1.8. LDAP vs RDBMS............................................................................................................................9
1.9. What is slapd and what can it do?...................................................................................................11
2. A Quick-Start Guide.....................................................................................................................................15
3. The Big Picture - Configuration Choices....................................................................................................15
3.1. Local Directory Service..................................................................................................................15
3.2. Local Directory Service with Referrals..........................................................................................15
3.3. Replicated Directory Service..........................................................................................................16
3.4. Distributed Local Directory Service...............................................................................................17
4. Building and Installing OpenLDAP Software............................................................................................17
4.1. Obtaining and Extracting the Software...........................................................................................17
4.2. Prerequisite software.......................................................................................................................17
4.2.1. Transport Layer Security.......................................................................................................18
4.2.2. Simple Authentication and Security Layer...........................................................................18
4.2.3. Kerberos Authentication Service...........................................................................................18
4.2.4. Database Software.................................................................................................................19
4.2.5. Threads..................................................................................................................................19
4.2.6. TCP Wrappers.......................................................................................................................19
4.3. Running configure..........................................................................................................................20
4.4. Building the Software.....................................................................................................................20
4.5. Testing the Software.......................................................................................................................20
4.6. Installing the Software....................................................................................................................23
5. Configuring slapd..........................................................................................................................................23
5.1. Configuration Layout......................................................................................................................25
5.2. Configuration Directives.................................................................................................................26
5.2.1. cn=config...............................................................................................................................27
5.2.2. cn=module.............................................................................................................................28
5.2.3. cn=schema.............................................................................................................................29
i

OpenLDAP Software 2.4 Administrator's Guide

Table of Contents
5. Configuring slapd
5.2.4. Backend-specific Directives..................................................................................................29
5.2.5. Database-specific Directives.................................................................................................34
5.2.6. BDB and HDB Database Directives.....................................................................................38
5.3. Configuration Example...................................................................................................................40
5.4. Converting old style slapd.conf(5) file to cn=config format..........................................................43
6. The slapd Configuration File.......................................................................................................................43
6.1. Configuration File Format..............................................................................................................44
6.2. Configuration File Directives.........................................................................................................44
6.2.1. Global Directives...................................................................................................................46
6.2.2. General Backend Directives..................................................................................................47
6.2.3. General Database Directives.................................................................................................51
6.2.4. BDB and HDB Database Directives.....................................................................................51
6.3. Configuration File Example............................................................................................................53
7. Running slapd................................................................................................................................................53
7.1. Command-Line Options.................................................................................................................55
7.2. Starting slapd..................................................................................................................................55
7.3. Stopping slapd.................................................................................................................................57
8. Access Control...............................................................................................................................................57
8.1. Introduction.....................................................................................................................................57
8.2. Access Control via Static Configuration.........................................................................................58
8.2.1. What to control access to.......................................................................................................59
8.2.2. Who to grant access to...........................................................................................................60
8.2.3. The access to grant................................................................................................................60
8.2.4. Access Control Evaluation....................................................................................................61
8.2.5. Access Control Examples......................................................................................................62
8.3. Access Control via Dynamic Configuration...................................................................................63
8.3.1. What to control access to.......................................................................................................64
8.3.2. Who to grant access to...........................................................................................................65
8.3.3. The access to grant................................................................................................................65
8.3.4. Access Control Evaluation....................................................................................................66
8.3.5. Access Control Examples......................................................................................................67
8.3.6. Access Control Ordering.......................................................................................................68
8.4. Access Control Common Examples...............................................................................................68
8.4.1. Basic ACLs............................................................................................................................69
8.4.2. Matching Anonymous and Authenticated users....................................................................69
8.4.3. Controlling rootdn access......................................................................................................70
8.4.4. Managing access with Groups...............................................................................................71
8.4.5. Granting access to a subset of attributes...............................................................................71
8.4.6. Allowing a user write to all entries below theirs...................................................................72
8.4.7. Allowing entry creation.........................................................................................................73
8.4.8. Tips for using regular expressions in Access Control...........................................................74
8.4.9. Granting and Denying access based on security strength factors (ssf).................................74
8.4.10. When things aren't working as expected.............................................................................75
8.5. Sets - Granting rights based on relationships..................................................................................75
ii

OpenLDAP Software 2.4 Administrator's Guide

Table of Contents
8. Access Control
8.5.1. Groups of Groups..................................................................................................................76
8.5.2. Group ACLs without DN syntax...........................................................................................77
8.5.3. Following references.............................................................................................................79
9. Limits.............................................................................................................................................................79
9.1. Introduction.....................................................................................................................................79
9.2. Soft and Hard limits........................................................................................................................79
9.3. Global Limits..................................................................................................................................80
9.4. Per-Database Limits........................................................................................................................80
9.4.1. Specify who the limits apply to.............................................................................................80
9.4.2. Specify time limits.................................................................................................................81
9.4.3. Specifying size limits............................................................................................................81
9.4.4. Size limits and Paged Results................................................................................................81
9.5. Example Limit Configurations.......................................................................................................81
9.5.1. Simple Global Limits............................................................................................................82
9.5.2. Global Hard and Soft Limits.................................................................................................82
9.5.3. Giving specific users larger limits.........................................................................................82
9.5.4. Limiting who can do paged searches....................................................................................82
9.6. Further Information.........................................................................................................................83
10. Database Creation and Maintenance Tools..............................................................................................83
10.1. Creating a database over LDAP....................................................................................................84
10.2. Creating a database off-line..........................................................................................................85
10.2.1. The slapadd program...........................................................................................................86
10.2.2. The slapindex program........................................................................................................86
10.2.3. The slapcat program............................................................................................................86
10.3. The LDIF text entry format...........................................................................................................89
11. Backends......................................................................................................................................................89
11.1. Berkeley DB Backends.................................................................................................................89
11.1.1. Overview.............................................................................................................................89
11.1.2. back-bdb/back-hdb Configuration.......................................................................................89
11.1.3. Further Information.............................................................................................................89
11.2. LDAP............................................................................................................................................89
11.2.1. Overview.............................................................................................................................90
11.2.2. back-ldap Configuration......................................................................................................91
11.2.3. Further Information.............................................................................................................91
11.3. LDIF..............................................................................................................................................91
11.3.1. Overview.............................................................................................................................91
11.3.2. back-ldif Configuration.......................................................................................................92
11.3.3. Further Information.............................................................................................................92
11.4. LMDB...........................................................................................................................................92
11.4.1. Overview.............................................................................................................................92
11.4.2. back-mdb Configuration......................................................................................................92
11.4.3. Further Information.............................................................................................................92
11.5. Metadirectory................................................................................................................................93
11.5.1. Overview.............................................................................................................................93
iii

OpenLDAP Software 2.4 Administrator's Guide

Table of Contents
11. Backends
11.5.2. back-meta Configuration.....................................................................................................93
11.5.3. Further Information.............................................................................................................93
11.6. Monitor.........................................................................................................................................93
11.6.1. Overview.............................................................................................................................93
11.6.2. back-monitor Configuration................................................................................................94
11.6.3. Further Information.............................................................................................................94
11.7. Null...............................................................................................................................................94
11.7.1. Overview.............................................................................................................................95
11.7.2. back-null Configuration......................................................................................................95
11.7.3. Further Information.............................................................................................................95
11.8. Passwd..........................................................................................................................................95
11.8.1. Overview.............................................................................................................................95
11.8.2. back-passwd Configuration.................................................................................................96
11.8.3. Further Information.............................................................................................................96
11.9. Perl/Shell.......................................................................................................................................96
11.9.1. Overview.............................................................................................................................96
11.9.2. back-perl/back-shell Configuration.....................................................................................96
11.9.3. Further Information.............................................................................................................96
11.10. Relay...........................................................................................................................................97
11.10.1. Overview...........................................................................................................................97
11.10.2. back-relay Configuration...................................................................................................97
11.10.3. Further Information...........................................................................................................97
11.11. SQL.............................................................................................................................................97
11.11.1. Overview...........................................................................................................................97
11.11.2. back-sql Configuration......................................................................................................99
11.11.3. Further Information.........................................................................................................101
12. Overlays.....................................................................................................................................................102
12.1. Access Logging...........................................................................................................................102
12.1.1. Overview...........................................................................................................................102
12.1.2. Access Logging Configuration..........................................................................................103
12.1.3. Further Information...........................................................................................................103
12.2. Audit Logging.............................................................................................................................103
12.2.1. Overview...........................................................................................................................104
12.2.2. Audit Logging Configuration............................................................................................104
12.2.3. Further Information...........................................................................................................104
12.3. Chaining......................................................................................................................................105
12.3.1. Overview...........................................................................................................................105
12.3.2. Chaining Configuration.....................................................................................................106
12.3.3. Handling Chaining Errors.................................................................................................106
12.3.4. Read-Back of Chained Modifications...............................................................................106
12.3.5. Further Information...........................................................................................................106
12.4. Constraints..................................................................................................................................106
12.4.1. Overview...........................................................................................................................106
12.4.2. Constraint Configuration...................................................................................................107
12.4.3. Further Information...........................................................................................................107
12.5. Dynamic Directory Services.......................................................................................................107
iv

OpenLDAP Software 2.4 Administrator's Guide

Table of Contents
12. Overlays
12.5.1. Overview...........................................................................................................................107
12.5.2. Dynamic Directory Service Configuration........................................................................108
12.5.3. Further Information...........................................................................................................109
12.6. Dynamic Groups.........................................................................................................................109
12.6.1. Overview...........................................................................................................................109
12.6.2. Dynamic Group Configuration..........................................................................................109
12.7. Dynamic Lists.............................................................................................................................109
12.7.1. Overview...........................................................................................................................109
12.7.2. Dynamic List Configuration..............................................................................................111
12.7.3. Further Information...........................................................................................................111
12.8. Reverse Group Membership Maintenance..................................................................................111
12.8.1. Overview...........................................................................................................................111
12.8.2. Member Of Configuration.................................................................................................112
12.8.3. Further Information...........................................................................................................112
12.9. The Proxy Cache Engine............................................................................................................112
12.9.1. Overview...........................................................................................................................113
12.9.2. Proxy Cache Configuration...............................................................................................115
12.9.3. Further Information...........................................................................................................115
12.10. Password Policies.....................................................................................................................115
12.10.1. Overview.........................................................................................................................116
12.10.2. Password Policy Configuration.......................................................................................117
12.10.3. Further Information.........................................................................................................117
12.11. Referential Integrity..................................................................................................................118
12.11.1. Overview.........................................................................................................................118
12.11.2. Referential Integrity Configuration.................................................................................119
12.11.3. Further Information.........................................................................................................119
12.12. Return Code..............................................................................................................................119
12.12.1. Overview.........................................................................................................................119
12.12.2. Return Code Configuration.............................................................................................120
12.12.3. Further Information.........................................................................................................120
12.13. Rewrite/Remap.........................................................................................................................120
12.13.1. Overview.........................................................................................................................120
12.13.2. Rewrite/Remap Configuration........................................................................................120
12.13.3. Further Information.........................................................................................................120
12.14. Sync Provider............................................................................................................................121
12.14.1. Overview.........................................................................................................................121
12.14.2. Sync Provider Configuration...........................................................................................121
12.14.3. Further Information.........................................................................................................121
12.15. Translucent Proxy.....................................................................................................................121
12.15.1. Overview.........................................................................................................................121
12.15.2. Translucent Proxy Configuration....................................................................................123
12.15.3. Further Information.........................................................................................................123
12.16. Attribute Uniqueness................................................................................................................123
12.16.1. Overview.........................................................................................................................123
12.16.2. Attribute Uniqueness Configuration...............................................................................124
12.16.3. Further Information.........................................................................................................125
12.17. Value Sorting............................................................................................................................125
v

OpenLDAP Software 2.4 Administrator's Guide

Table of Contents
12. Overlays
12.17.1. Overview.........................................................................................................................125
12.17.2. Value Sorting Configuration...........................................................................................126
12.17.3. Further Information.........................................................................................................126
12.18. Overlay Stacking.......................................................................................................................126
12.18.1. Overview.........................................................................................................................126
12.18.2. Example Scenarios..........................................................................................................127
13. Schema Specification................................................................................................................................127
13.1. Distributed Schema Files............................................................................................................127
13.2. Extending Schema......................................................................................................................128
13.2.1. Object Identifiers...............................................................................................................129
13.2.2. Naming Elements..............................................................................................................129
13.2.3. Local schema file...............................................................................................................129
13.2.4. Attribute Type Specification.............................................................................................132
13.2.5. Object Class Specification.................................................................................................133
13.2.6. OID Macros.......................................................................................................................135
14. Security Considerations............................................................................................................................135
14.1. Network Security........................................................................................................................135
14.1.1. Selective Listening............................................................................................................135
14.1.2. IP Firewall.........................................................................................................................135
14.1.3. TCP Wrappers...................................................................................................................136
14.2. Data Integrity and Confidentiality Protection.............................................................................136
14.2.1. Security Strength Factors..................................................................................................136
14.3. Authentication Methods..............................................................................................................136
14.3.1. "simple" method................................................................................................................137
14.3.2. SASL method....................................................................................................................137
14.4. Password Storage........................................................................................................................138
14.4.1. SSHA password storage scheme.......................................................................................138
14.4.2. CRYPT password storage scheme....................................................................................138
14.4.3. MD5 password storage scheme.........................................................................................138
14.4.4. SMD5 password storage scheme.......................................................................................139
14.4.5. SHA password storage scheme.........................................................................................139
14.4.6. SASL password storage scheme........................................................................................139
14.5. Pass-Through authentication.......................................................................................................139
14.5.1. Configuring slapd to use an authentication provider.........................................................140
14.5.2. Configuring saslauthd........................................................................................................140
14.5.3. Testing pass-through authentication..................................................................................143
15. Using SASL................................................................................................................................................143
15.1. SASL Security Considerations...................................................................................................144
15.2. SASL Authentication..................................................................................................................144
15.2.1. GSSAPI.............................................................................................................................145
15.2.2. KERBEROS_V4...............................................................................................................146
15.2.3. DIGEST-MD5...................................................................................................................147
15.2.4. EXTERNAL......................................................................................................................147
15.2.5. Mapping Authentication Identities....................................................................................148
vi

OpenLDAP Software 2.4 Administrator's Guide

Table of Contents
15. Using SASL
15.2.6. Direct Mapping..................................................................................................................149
15.2.7. Search-based mappings.....................................................................................................150
15.3. SASL Proxy Authorization.........................................................................................................151
15.3.1. Uses of Proxy Authorization.............................................................................................151
15.3.2. SASL Authorization Identities..........................................................................................152
15.3.3. Proxy Authorization Rules................................................................................................155
16. Using TLS..................................................................................................................................................155
16.1. TLS Certificates..........................................................................................................................155
16.1.1. Server Certificates.............................................................................................................155
16.1.2. Client Certificates..............................................................................................................155
16.2. TLS Configuration......................................................................................................................155
16.2.1. Server Configuration.........................................................................................................158
16.2.2. Client Configuration..........................................................................................................161
17. Constructing a Distributed Directory Service........................................................................................161
17.1. Subordinate Knowledge Information..........................................................................................161
17.2. Superior Knowledge Information...............................................................................................162
17.3. The ManageDsaIT Control.........................................................................................................163
18. Replication.................................................................................................................................................163
18.1. Replication Technology..............................................................................................................163
18.1.1. LDAP Sync Replication....................................................................................................167
18.2. Deployment Alternatives............................................................................................................167
18.2.1. Delta-syncrepl replication.................................................................................................167
18.2.2. N-Way Multi-Master replication.......................................................................................168
18.2.3. MirrorMode replication.....................................................................................................169
18.2.4. Syncrepl Proxy Mode........................................................................................................170
18.3. Configuring the different replication types.................................................................................170
18.3.1. Syncrepl.............................................................................................................................172
18.3.2. Delta-syncrepl...................................................................................................................174
18.3.3. N-Way Multi-Master.........................................................................................................175
18.3.4. MirrorMode.......................................................................................................................177
18.3.5. Syncrepl Proxy..................................................................................................................183
19. Maintenance..............................................................................................................................................183
19.1. Directory Backups......................................................................................................................183
19.2. Berkeley DB Logs.......................................................................................................................185
19.3. Checkpointing.............................................................................................................................185
19.4. Migration....................................................................................................................................187
20. Monitoring.................................................................................................................................................187
20.1. Monitor configuration via cn=config(5).....................................................................................187
20.2. Monitor configuration via slapd.conf(5).....................................................................................188
20.3. Accessing Monitoring Information.............................................................................................189
20.4. Monitor Information...................................................................................................................190
20.4.1. Backends...........................................................................................................................191
vii

OpenLDAP Software 2.4 Administrator's Guide

Table of Contents
20. Monitoring
20.4.2. Connections.......................................................................................................................191
20.4.3. Databases...........................................................................................................................192
20.4.4. Listener..............................................................................................................................192
20.4.5. Log.....................................................................................................................................192
20.4.6. Operations.........................................................................................................................193
20.4.7. Overlays.............................................................................................................................193
20.4.8. SASL.................................................................................................................................193
20.4.9. Statistics.............................................................................................................................193
20.4.10. Threads............................................................................................................................194
20.4.11. Time.................................................................................................................................194
20.4.12. TLS..................................................................................................................................194
20.4.13. Waiters.............................................................................................................................195
21. Tuning........................................................................................................................................................195
21.1. Performance Factors...................................................................................................................195
21.1.1. Memory.............................................................................................................................195
21.1.2. Disks..................................................................................................................................195
21.1.3. Network Topology............................................................................................................195
21.1.4. Directory Layout Design...................................................................................................196
21.1.5. Expected Usage.................................................................................................................196
21.2. Indexes........................................................................................................................................196
21.2.1. Understanding how a search works...................................................................................196
21.2.2. What to index....................................................................................................................196
21.2.3. Presence indexing..............................................................................................................196
21.3. Logging.......................................................................................................................................197
21.3.1. What log level to use.........................................................................................................197
21.3.2. What to watch out for........................................................................................................197
21.3.3. Improving throughput........................................................................................................197
21.4. Caching.......................................................................................................................................198
21.4.1. Berkeley DB Cache...........................................................................................................200
21.4.2. slapd(8) Entry Cache (cachesize)......................................................................................200
21.4.3. IDL Cache (idlcachesize)..................................................................................................200
21.5. slapd(8) Threads..........................................................................................................................201
22. Troubleshooting........................................................................................................................................201
22.1. User or Software errors?.............................................................................................................201
22.2. Checklist.....................................................................................................................................201
22.3. OpenLDAP Bugs........................................................................................................................202
22.4. 3rd party software error..............................................................................................................202
22.5. How to contact the OpenLDAP Project......................................................................................202
22.6. How to present your problem.....................................................................................................202
22.7. Debugging slapd(8).....................................................................................................................202
22.8. Commercial Support...................................................................................................................203
A. Changes Since Previous Release...............................................................................................................203
A.1. New Guide Sections.....................................................................................................................203
A.2. New Features and Enhancements in 2.4......................................................................................203
viii

OpenLDAP Software 2.4 Administrator's Guide

Table of Contents
A. Changes Since Previous Release
A.2.1. Better cn=config functionality............................................................................................204
A.2.2. Better cn=schema functionality..........................................................................................204
A.2.3. More sophisticated Syncrepl configurations......................................................................204
A.2.4. N-Way Multimaster Replication........................................................................................204
A.2.5. Replicating slapd Configuration (syncrepl and cn=config)...............................................204
A.2.6. Push-Mode Replication......................................................................................................205
A.2.7. More extensive TLS configuration control........................................................................205
A.2.8. Performance enhancements................................................................................................205
A.2.9. New overlays......................................................................................................................205
A.2.10. New features in existing Overlays....................................................................................206
A.2.11. New features in slapd.......................................................................................................206
A.2.12. New features in libldap.....................................................................................................206
A.2.13. New clients, tools and tool enhancements........................................................................206
A.2.14. New build options.............................................................................................................206
A.3. Obsolete Features Removed From 2.4.........................................................................................206
A.3.1. Slurpd.................................................................................................................................206
A.3.2. back-ldbm...........................................................................................................................207
B. Upgrading from 2.3.x.................................................................................................................................207
B.1. cn=config olc* attributes..............................................................................................................207
B.2. ACLs: searches require privileges on the search base.................................................................209
C. Common errors encountered when using OpenLDAP Software..........................................................209
C.1. Common causes of LDAP errors.................................................................................................209
C.1.1. ldap_*: Can't contact LDAP server....................................................................................209
C.1.2. ldap_*: No such object.......................................................................................................210
C.1.3. ldap_*: Can't chase referral................................................................................................210
C.1.4. ldap_*: server is unwilling to perform................................................................................211
C.1.5. ldap_*: Insufficient access..................................................................................................211
C.1.6. ldap_*: Invalid DN syntax..................................................................................................211
C.1.7. ldap_*: Referral hop limit exceeded...................................................................................211
C.1.8. ldap_*: operations error......................................................................................................211
C.1.9. ldap_*: other error..............................................................................................................211
C.1.10. ldap_add/modify: Invalid syntax......................................................................................212
C.1.11. ldap_add/modify: Object class violation..........................................................................213
C.1.12. ldap_add: No such object..................................................................................................213
C.1.13. ldap add: invalid structural object class chain..................................................................214
C.1.14. ldap_add: no structuralObjectClass operational attribute.................................................214
C.1.15. ldap_add/modify/rename: Naming violation....................................................................215
C.1.16. ldap_add/delete/modify/rename: no global superior knowledge......................................215
C.1.17. ldap_bind: Insufficient access...........................................................................................215
C.1.18. ldap_bind: Invalid credentials...........................................................................................216
C.1.19. ldap_bind: Protocol error..................................................................................................216
C.1.20. ldap_modify: cannot modify object class.........................................................................216
C.1.21. ldap_sasl_interactive_bind_s: ..........................................................................................216
C.1.22. ldap_sasl_interactive_bind_s: No such Object.................................................................216
C.1.23. ldap_sasl_interactive_bind_s: No such attribute..............................................................217
ix

OpenLDAP Software 2.4 Administrator's Guide

Table of Contents
C. Common errors encountered when using OpenLDAP Software
C.1.24. ldap_sasl_interactive_bind_s: Unknown authentication method.....................................217
C.1.25. ldap_sasl_interactive_bind_s: Local error (82)................................................................217
C.1.26. ldap_search: Partial results and referral received.............................................................217
C.1.27. ldap_start_tls: Operations error........................................................................................217
C.2. Other Errors..................................................................................................................................217
C.2.1. ber_get_next on fd X failed errno=34 (Numerical result out of range)..............................217
C.2.2. ber_get_next on fd X failed errno=11 (Resource temporarily unavailable).......................218
C.2.3. daemon: socket() failed errno=97 (Address family not supported)....................................218
C.2.4. GSSAPI: gss_acquire_cred: Miscellaneous failure; Permission denied;...........................218
C.2.5. access from unknown denied..............................................................................................219
C.2.6. ldap_read: want=# error=Resource temporarily unavailable.............................................219
C.2.7. `make test' fails...................................................................................................................220
C.2.8. ldap_*: Internal (implementation specific) error (80) - additional info: entry index
delete failed............................................................................................................................220
C.2.9. ldap_sasl_interactive_bind_s: Can't contact LDAP server (-1)..........................................221
D. Recommended OpenLDAP Software Dependency Versions.................................................................221
D.1. Dependency Versions..................................................................................................................223
E. Real World OpenLDAP Deployments and Examples............................................................................225
F. OpenLDAP Software Contributions.........................................................................................................225
F.1. Client APIs...................................................................................................................................225
F.1.1. ldapc++................................................................................................................................225
F.1.2. ldaptcl..................................................................................................................................225
F.2. Overlays........................................................................................................................................225
F.2.1. acl........................................................................................................................................225
F.2.2. addpartial.............................................................................................................................225
F.2.3. allop.....................................................................................................................................225
F.2.4. autogroup.............................................................................................................................225
F.2.5. comp_match........................................................................................................................225
F.2.6. denyop.................................................................................................................................225
F.2.7. dsaschema...........................................................................................................................226
F.2.8. lastmod................................................................................................................................226
F.2.9. nops.....................................................................................................................................226
F.2.10. nssov..................................................................................................................................226
F.2.11. passwd...............................................................................................................................226
F.2.12. proxyOld...........................................................................................................................226
F.2.13. smbk5pwd.........................................................................................................................226
F.2.14. trace...................................................................................................................................226
F.2.15. usn.....................................................................................................................................226
F.3. Tools.............................................................................................................................................226
F.3.1. Statistic Logging.................................................................................................................226
F.4. SLAPI Plugins..............................................................................................................................227
F.4.1. addrdnvalues.......................................................................................................................229

OpenLDAP Software 2.4 Administrator's Guide

Table of Contents
G. Configuration File Examples....................................................................................................................229
G.1. slapd.conf.....................................................................................................................................229
G.2. ldap.conf.......................................................................................................................................229
G.3. a-n-other.conf...............................................................................................................................231
H. LDAP Result Codes...................................................................................................................................231
H.1. Non-Error Result Codes...............................................................................................................231
H.2. Result Codes................................................................................................................................231
H.3. success (0)....................................................................................................................................231
H.4. operationsError (1).......................................................................................................................231
H.5. protocolError (2)..........................................................................................................................232
H.6. timeLimitExceeded (3)................................................................................................................232
H.7. sizeLimitExceeded (4).................................................................................................................232
H.8. compareFalse (5)..........................................................................................................................232
H.9. compareTrue (6)...........................................................................................................................232
H.10. authMethodNotSupported (7)....................................................................................................232
H.11. strongerAuthRequired (8)..........................................................................................................232
H.12. referral (10)................................................................................................................................232
H.13. adminLimitExceeded (11)..........................................................................................................233
H.14. unavailableCriticalExtension (12)..............................................................................................233
H.15. confidentialityRequired (13)......................................................................................................233
H.16. saslBindInProgress (14).............................................................................................................233
H.17. noSuchAttribute (16)..................................................................................................................233
H.18. undefinedAttributeType (17).....................................................................................................233
H.19. inappropriateMatching (18).......................................................................................................233
H.20. constraintViolation (19).............................................................................................................233
H.21. attributeOrValueExists (20).......................................................................................................233
H.22. invalidAttributeSyntax (21).......................................................................................................233
H.23. noSuchObject (32).....................................................................................................................234
H.24. aliasProblem (33).......................................................................................................................234
H.25. invalidDNSyntax (34)................................................................................................................234
H.26. aliasDereferencingProblem (36)................................................................................................234
H.27. inappropriateAuthentication (48)...............................................................................................234
H.28. invalidCredentials (49)...............................................................................................................234
H.29. insufficientAccessRights (50)....................................................................................................234
H.30. busy (51)....................................................................................................................................234
H.31. unavailable (52)..........................................................................................................................234
H.32. unwillingToPerform (53)...........................................................................................................234
H.33. loopDetect (54)..........................................................................................................................235
H.34. namingViolation (64).................................................................................................................235
H.35. objectClassViolation (65)..........................................................................................................235
H.36. notAllowedOnNonLeaf (66)......................................................................................................235
H.37. notAllowedOnRDN (67)............................................................................................................235
H.38. entryAlreadyExists (68).............................................................................................................235
H.39. objectClassModsProhibited (69)................................................................................................235
H.40. affectsMultipleDSAs (71)..........................................................................................................235
H.41. other (80)....................................................................................................................................237

OpenLDAP Software 2.4 Administrator's Guide

Table of Contents
I. Glossary........................................................................................................................................................237
I.1. Terms.............................................................................................................................................240
I.2. Related Organizations....................................................................................................................240
I.3. Related Products............................................................................................................................241
I.4. References.....................................................................................................................................245
J. Generic configure Instructions..................................................................................................................249
K. OpenLDAP Software Copyright Notices.................................................................................................249
K.1. OpenLDAP Copyright Notice......................................................................................................249
K.2. Additional Copyright Notices......................................................................................................250
K.3. University of Michigan Copyright Notice...................................................................................251
L. OpenLDAP Public License.......................................................................................................................title

xii

Preface
Copyright
Copyright 1998-2012, The OpenLDAP Foundation, All Rights Reserved.
Copyright 1992-1996, Regents of the University of Michigan, All Rights Reserved.
This document is considered a part of OpenLDAP Software. This document is subject to terms of conditions
set forth in OpenLDAP Software Copyright Notices and the OpenLDAP Public License. Complete copies of
the notices and associated license can be found in Appendix K and L, respectively.
Portions of OpenLDAP Software and this document may be copyright by other parties and/or subject to
additional restrictions. Individual source files should be consulted for additional copyright notices.

Scope of this Document
This document provides a guide for installing OpenLDAP Software 2.4 (http://www.openldap.org/software/)
on UNIX (and UNIX-like) systems. The document is aimed at experienced system administrators with basic
understanding of LDAP-based directory services.
This document is meant to be used in conjunction with other OpenLDAP information resources provided with
the software package and on the project's site (http://www.OpenLDAP.org/) on the World Wide Web. The site
makes available a number of resources.
OpenLDAP Resources
Resource
URL
Document Catalog
http://www.OpenLDAP.org/doc/
Frequently Asked Questions http://www.OpenLDAP.org/faq/
Issue Tracking System
http://www.OpenLDAP.org/its/
Mailing Lists
http://www.OpenLDAP.org/lists/
Manual Pages
http://www.OpenLDAP.org/software/man.cgi
Software Pages
http://www.OpenLDAP.org/software/
Support Pages
http://www.OpenLDAP.org/support/
This document is not a complete reference for OpenLDAP software; the manual pages are the definitive
documentation. For best results, you should use the manual pages that were installed on your system with
your version of OpenLDAP software so that you're looking at documentation that matches the code. While the
OpenLDAP web site also provides the manual pages for convenience, you can not assume that they corresond
to the particular version you're running.

Acknowledgments
The OpenLDAP Project is comprised of a team of volunteers. This document would not be possible without
their contribution of time and energy.

OpenLDAP Software 2.4 Administrator's Guide
The OpenLDAP Project would also like to thank the University of Michigan LDAP Team for building the
foundation of LDAP software and information to which OpenLDAP Software is built upon. This document is
based upon University of Michigan document: The SLAPD and SLURPD Administrators Guide.

Amendments
Suggested enhancements and corrections to this document should be submitted using the OpenLDAP Issue
Tracking System (http://www.openldap.org/its/).

About this document
This document was produced using the Simple Document Format (SDF) documentation system
(http://search.cpan.org/src/IANC/sdf-2.001/doc/catalog.html) developed by Ian Clatworthy. Tools for SDF are
available from CPAN (http://search.cpan.org/search?query=SDF&mode=dist).

1. Introduction to OpenLDAP Directory Services
This document describes how to build, configure, and operate OpenLDAP Software to provide directory
services. This includes details on how to configure and run the Standalone LDAP Daemon, slapd(8). It is
intended for new and experienced administrators alike. This section provides a basic introduction to directory
services and, in particular, the directory services provided by slapd(8). This introduction is only intended to
provide enough information so one might get started learning about LDAP, X.500, and directory services.

1.1. What is a directory service?
A directory is a specialized database specifically designed for searching and browsing, in additional to
supporting basic lookup and update functions.
Note: A directory is defined by some as merely a database optimized for read access. This definition, at best,
is overly simplistic.
Directories tend to contain descriptive, attribute-based information and support sophisticated filtering
capabilities. Directories generally do not support complicated transaction or roll-back schemes found in
database management systems designed for handling high-volume complex updates. Directory updates are
typically simple all-or-nothing changes, if they are allowed at all. Directories are generally tuned to give quick
response to high-volume lookup or search operations. They may have the ability to replicate information
widely in order to increase availability and reliability, while reducing response time. When directory
information is replicated, temporary inconsistencies between the replicas may be okay, as long as
inconsistencies are resolved in a timely manner.
There are many different ways to provide a directory service. Different methods allow different kinds of
information to be stored in the directory, place different requirements on how that information can be
referenced, queried and updated, how it is protected from unauthorized access, etc. Some directory services
are local, providing service to a restricted context (e.g., the finger service on a single machine). Other services
are global, providing service to a much broader context (e.g., the entire Internet). Global services are usually
distributed, meaning that the data they contain is spread across many machines, all of which cooperate to
provide the directory service. Typically a global service defines a uniform namespace which gives the same
view of the data no matter where you are in relation to the data itself.
A web directory, such as provided by the Open Directory Project , is a good example of a
directory service. These services catalog web pages and are specifically designed to support browsing and
searching.
While some consider the Internet Domain Name System (DNS) is an example of a globally distributed
directory service, DNS is not browseable nor searchable. It is more properly described as a globally
distributed lookup service.

1.2. What is LDAP?
LDAP stands for Lightweight Directory Access Protocol. As the name suggests, it is a lightweight protocol
for accessing directory services, specifically X.500-based directory services. LDAP runs over TCP/IP or other
connection oriented transfer services. LDAP is an IETF Standard Track protocol and is specified in
"Lightweight Directory Access Protocol (LDAP) Technical Specification Road Map" RFC4510.

OpenLDAP Software 2.4 Administrator's Guide
This section gives an overview of LDAP from a user's perspective.
What kind of information can be stored in the directory? The LDAP information model is based on entries.
An entry is a collection of attributes that has a globally-unique Distinguished Name (DN). The DN is used to
refer to the entry unambiguously. Each of the entry's attributes has a type and one or more values. The types
are typically mnemonic strings, like "cn" for common name, or "mail" for email address. The syntax of
values depend on the attribute type. For example, a cn attribute might contain the value Babs Jensen. A
mail attribute might contain the value "babs@example.com". A jpegPhoto attribute would contain a
photograph in the JPEG (binary) format.
How is the information arranged? In LDAP, directory entries are arranged in a hierarchical tree-like structure.
Traditionally, this structure reflected the geographic and/or organizational boundaries. Entries representing
countries appear at the top of the tree. Below them are entries representing states and national organizations.
Below them might be entries representing organizational units, people, printers, documents, or just about
anything else you can think of. Figure 1.1 shows an example LDAP directory tree using traditional naming.

Figure 1.1: LDAP directory tree (traditional naming)
The tree may also be arranged based upon Internet domain names. This naming approach is becoming
increasing popular as it allows for directory services to be located using the DNS. Figure 1.2 shows an
example LDAP directory tree using domain-based naming.

OpenLDAP Software 2.4 Administrator's Guide

Figure 1.2: LDAP directory tree (Internet naming)
In addition, LDAP allows you to control which attributes are required and allowed in an entry through the use
of a special attribute called objectClass. The values of the objectClass attribute determine the
schema rules the entry must obey.
How is the information referenced? An entry is referenced by its distinguished name, which is constructed by
taking the name of the entry itself (called the Relative Distinguished Name or RDN) and concatenating the
names of its ancestor entries. For example, the entry for Barbara Jensen in the Internet naming example above
has an RDN of uid=babs and a DN of uid=babs,ou=People,dc=example,dc=com. The full DN
format is described in RFC4514, "LDAP: String Representation of Distinguished Names."
How is the information accessed? LDAP defines operations for interrogating and updating the directory.
Operations are provided for adding and deleting an entry from the directory, changing an existing entry, and
changing the name of an entry. Most of the time, though, LDAP is used to search for information in the
directory. The LDAP search operation allows some portion of the directory to be searched for entries that
match some criteria specified by a search filter. Information can be requested from each entry that matches the
criteria.
For example, you might want to search the entire directory subtree at and below dc=example,dc=com for
people with the name Barbara Jensen, retrieving the email address of each entry found. LDAP lets you
do this easily. Or you might want to search the entries directly below the st=California,c=US entry for
organizations with the string Acme in their name, and that have a fax number. LDAP lets you do this too. The
next section describes in more detail what you can do with LDAP and how it might be useful to you.
How is the information protected from unauthorized access? Some directory services provide no protection,
allowing anyone to see the information. LDAP provides a mechanism for a client to authenticate, or prove its
identity to a directory server, paving the way for rich access control to protect the information the server
contains. LDAP also supports data security (integrity and confidentiality) services.

OpenLDAP Software 2.4 Administrator's Guide

1.3. When should I use LDAP?
This is a very good question. In general, you should use a Directory server when you require data to be
centrally managed, stored and accessible via standards based methods.
Some common examples found throughout the industry are, but not limited to:
• Machine Authentication
• User Authentication
• User/System Groups
• Address book
• Organization Representation
• Asset Tracking
• Telephony Information Store
• User resource management
• E-mail address lookups
• Application Configuration store
• PBX Configuration store
• etc.....
There are various Distributed Schema Files that are standards based, but you can always create your own
Schema Specification.
There are always new ways to use a Directory and apply LDAP principles to address certain problems,
therefore there is no simple answer to this question.
If in doubt, join the general LDAP forum for non-commercial discussions and information relating to LDAP
at: http://www.umich.edu/~dirsvcs/ldap/mailinglist.html and ask

1.4. When should I not use LDAP?
When you start finding yourself bending the directory to do what you require, maybe a redesign is needed. Or
if you only require one application to use and manipulate your data (for discussion of LDAP vs RDBMS,
please read the LDAP vs RDBMS section).
It will become obvious when LDAP is the right tool for the job.

1.5. How does LDAP work?
LDAP utilizes a client-server model. One or more LDAP servers contain the data making up the directory
information tree (DIT). The client connects to servers and asks it a question. The server responds with an
answer and/or with a pointer to where the client can get additional information (typically, another LDAP
server). No matter which LDAP server a client connects to, it sees the same view of the directory; a name
presented to one LDAP server references the same entry it would at another LDAP server. This is an
important feature of a global directory service.

OpenLDAP Software 2.4 Administrator's Guide

1.6. What about X.500?
Technically, LDAP is a directory access protocol to an X.500 directory service, the OSI directory service.
Initially, LDAP clients accessed gateways to the X.500 directory service. This gateway ran LDAP between
the client and gateway and X.500's Directory Access Protocol (DAP) between the gateway and the X.500
server. DAP is a heavyweight protocol that operates over a full OSI protocol stack and requires a significant
amount of computing resources. LDAP is designed to operate over TCP/IP and provides most of the
functionality of DAP at a much lower cost.
While LDAP is still used to access X.500 directory service via gateways, LDAP is now more commonly
directly implemented in X.500 servers.
The Standalone LDAP Daemon, or slapd(8), can be viewed as a lightweight X.500 directory server. That is, it
does not implement the X.500's DAP nor does it support the complete X.500 models.
If you are already running a X.500 DAP service and you want to continue to do so, you can probably stop
reading this guide. This guide is all about running LDAP via slapd(8), without running X.500 DAP. If you are
not running X.500 DAP, want to stop running X.500 DAP, or have no immediate plans to run X.500 DAP,
read on.
It is possible to replicate data from an LDAP directory server to a X.500 DAP DSA. This requires an
LDAP/DAP gateway. OpenLDAP Software does not include such a gateway.

1.7. What is the difference between LDAPv2 and LDAPv3?
LDAPv3 was developed in the late 1990's to replace LDAPv2. LDAPv3 adds the following features to LDAP:
• Strong authentication and data security services via SASL
• Certificate authentication and data security services via TLS (SSL)
• Internationalization through the use of Unicode
• Referrals and Continuations
• Schema Discovery
• Extensibility (controls, extended operations, and more)
LDAPv2 is historic (RFC3494). As most so-called LDAPv2 implementations (including slapd(8)) do not
conform to the LDAPv2 technical specification, interoperability amongst implementations claiming LDAPv2
support is limited. As LDAPv2 differs significantly from LDAPv3, deploying both LDAPv2 and LDAPv3
simultaneously is quite problematic. LDAPv2 should be avoided. LDAPv2 is disabled by default.

1.8. LDAP vs RDBMS
This question is raised many times, in different forms. The most common, however, is: Why doesn't
OpenLDAP use a relational database management system (RDBMS) instead of an embedded key/value store
like LMDB? In general, expecting that the sophisticated algorithms implemented by commercial-grade
RDBMS would make OpenLDAP be faster or somehow better and, at the same time, permitting sharing of
data with other applications.
The short answer is that use of an embedded database and custom indexing system allows OpenLDAP to
provide greater performance and scalability without loss of reliability. OpenLDAP uses LMDB concurrent /
7

OpenLDAP Software 2.4 Administrator's Guide
transactional database software.
Now for the long answer. We are all confronted all the time with the choice RDBMSes vs. directories. It is a
hard choice and no simple answer exists.
It is tempting to think that having a RDBMS backend to the directory solves all problems. However, it is a
pig. This is because the data models are very different. Representing directory data with a relational database
is going to require splitting data into multiple tables.
Think for a moment about the person objectclass. Its definition requires attribute types objectclass, sn and cn
and allows attribute types userPassword, telephoneNumber, seeAlso and description. All of these attributes
are multivalued, so a normalization requires putting each attribute type in a separate table.
Now you have to decide on appropriate keys for those tables. The primary key might be a combination of the
DN, but this becomes rather inefficient on most database implementations.
The big problem now is that accessing data from one entry requires seeking on different disk areas. On some
applications this may be OK but in many applications performance suffers.
The only attribute types that can be put in the main table entry are those that are mandatory and single-value.
You may add also the optional single-valued attributes and set them to NULL or something if not present.
But wait, the entry can have multiple objectclasses and they are organized in an inheritance hierarchy. An
entry of objectclass organizationalPerson now has the attributes from person plus a few others and some
formerly optional attribute types are now mandatory.
What to do? Should we have different tables for the different objectclasses? This way the person would have
an entry on the person table, another on organizationalPerson, etc. Or should we get rid of person and put
everything on the second table?
But what do we do with a filter like (cn=*) where cn is an attribute type that appears in many, many
objectclasses. Should we search all possible tables for matching entries? Not very attractive.
Once this point is reached, three approaches come to mind. One is to do full normalization so that each
attribute type, no matter what, has its own separate table. The simplistic approach where the DN is part of the
primary key is extremely wasteful, and calls for an approach where the entry has a unique numeric id that is
used instead for the keys and a main table that maps DNs to ids. The approach, anyway, is very inefficient
when several attribute types from one or more entries are requested. Such a database, though cumbersomely,
can be managed from SQL applications.
The second approach is to put the whole entry as a blob in a table shared by all entries regardless of the
objectclass and have additional tables that act as indices for the first table. Index tables are not database
indices, but are fully managed by the LDAP server-side implementation. However, the database becomes
unusable from SQL. And, thus, a fully fledged database system provides little or no advantage. The full
generality of the database is unneeded. Much better to use something light and fast, like LMDB.
A completely different way to see this is to give up any hopes of implementing the directory data model. In
this case, LDAP is used as an access protocol to data that provides only superficially the directory data model.
For instance, it may be read only or, where updates are allowed, restrictions are applied, such as making
single-value attribute types that would allow for multiple values. Or the impossibility to add new objectclasses
to an existing entry or remove one of those present. The restrictions span the range from allowed restrictions
8

OpenLDAP Software 2.4 Administrator's Guide
(that might be elsewhere the result of access control) to outright violations of the data model. It can be,
however, a method to provide LDAP access to preexisting data that is used by other applications. But in the
understanding that we don't really have a "directory".
Existing commercial LDAP server implementations that use a relational database are either from the first kind
or the third. I don't know of any implementation that uses a relational database to do inefficiently what BDB
does efficiently. For those who are interested in "third way" (exposing EXISTING data from RDBMS as
LDAP tree, having some limitations compared to classic LDAP model, but making it possible to interoperate
between LDAP and SQL applications):
OpenLDAP includes back-sql - the backend that makes it possible. It uses ODBC + additional
metainformation about translating LDAP queries to SQL queries in your RDBMS schema, providing different
levels of access - from read-only to full access depending on RDBMS you use, and your schema.
For more information on concept and limitations, see slapd-sql(5) man page, or the Backends section. There
are also several examples for several RDBMSes in back-sql/rdbms_depend/* subdirectories.

1.9. What is slapd and what can it do?
slapd(8) is an LDAP directory server that runs on many different platforms. You can use it to provide a
directory service of your very own. Your directory can contain pretty much anything you want to put in it.
You can connect it to the global LDAP directory service, or run a service all by yourself. Some of slapd's
more interesting features and capabilities include:
LDAPv3: slapd implements version 3 of Lightweight Directory Access Protocol. slapd supports LDAP over
both IPv4 and IPv6 and Unix IPC.
Simple Authentication and Security Layer: slapd supports strong authentication and data security (integrity
and confidentiality) services through the use of SASL. slapd's SASL implementation utilizes Cyrus SASL
software which supports a number of mechanisms including DIGEST-MD5, EXTERNAL, and GSSAPI.
Transport Layer Security: slapd supports certificate-based authentication and data security (integrity and
confidentiality) services through the use of TLS (or SSL). slapd's TLS implementation can utilize OpenSSL,
GnuTLS, or MozNSS software.
Topology control: slapd can be configured to restrict access at the socket layer based upon network topology
information. This feature utilizes TCP wrappers.
Access control: slapd provides a rich and powerful access control facility, allowing you to control access to
the information in your database(s). You can control access to entries based on LDAP authorization
information, IP address, domain name and other criteria. slapd supports both static and dynamic access
control information.
Internationalization: slapd supports Unicode and language tags.
Choice of database backends: slapd comes with a variety of different database backends you can choose
from. They include MDB, a hierarchical high-performance transactional database backend; BDB, a
high-performance transactional database backend (deprecated); HDB, a hierarchical high-performance
transactional backend (deprecated); SHELL, a backend interface to arbitrary shell scripts; and PASSWD, a
simple backend interface to the passwd(5) file. The MDB backend utilizes LMDB, a high performance
9

OpenLDAP Software 2.4 Administrator's Guide
replacement for Oracle Corporation's Berkeley DB. The BDB and HDB backends utilize Oracle Corporation
Berkeley DB. These backends have been deprecated as LMDB provides significantly higher read and write
throughput and data reliability.
Multiple database instances: slapd can be configured to serve multiple databases at the same time. This
means that a single slapd server can respond to requests for many logically different portions of the LDAP
tree, using the same or different database backends.
Generic modules API: If you require even more customization, slapd lets you write your own modules
easily. slapd consists of two distinct parts: a front end that handles protocol communication with LDAP
clients; and modules which handle specific tasks such as database operations. Because these two pieces
communicate via a well-defined C API, you can write your own customized modules which extend slapd in
numerous ways. Also, a number of programmable database modules are provided. These allow you to expose
external data sources to slapd using popular programming languages (Perl, shell, and SQL).
Threads: slapd is threaded for high performance. A single multi-threaded slapd process handles all incoming
requests using a pool of threads. This reduces the amount of system overhead required while providing high
performance.
Replication: slapd can be configured to maintain shadow copies of directory information. This
single-master/multiple-slave replication scheme is vital in high-volume environments where a single slapd
installation just doesn't provide the necessary availability or reliability. For extremely demanding
environments where a single point of failure is not acceptable, multi-master replication is also available. slapd
includes support for LDAP Sync-based replication.
Proxy Cache: slapd can be configured as a caching LDAP proxy service.
Configuration: slapd is highly configurable through a single configuration file which allows you to change
just about everything you'd ever want to change. Configuration options have reasonable defaults, making your
job much easier. Configuration can also be performed dynamically using LDAP itself, which greatly improves
manageability.

2. A Quick-Start Guide
The following is a quick start guide to OpenLDAP Software 2.4, including the Standalone LDAP Daemon,
slapd(8).
It is meant to walk you through the basic steps needed to install and configure OpenLDAP Software. It should
be used in conjunction with the other chapters of this document, manual pages, and other materials provided
with the distribution (e.g. the INSTALL document) or on the OpenLDAP web site
(http://www.OpenLDAP.org), in particular the OpenLDAP Software FAQ
(http://www.OpenLDAP.org/faq/?file=2).
If you intend to run OpenLDAP Software seriously, you should review all of this document before attempting
to install the software.
Note: This quick start guide does not use strong authentication nor any integrity or confidential protection
services. These services are described in other chapters of the OpenLDAP Administrator's Guide.

1. Get the software
You can obtain a copy of the software by following the instructions on the OpenLDAP Software
download page (http://www.openldap.org/software/download/). It is recommended that new users
start with the latest release.
2. Unpack the distribution
Pick a directory for the source to live under, change directory to there, and unpack the distribution
using the following commands:
gunzip -c openldap-VERSION.tgz | tar xvfB then relocate yourself into the distribution directory:
cd openldap-VERSION
You'll have to replace VERSION with the version name of the release.
3. Review documentation
You should now review the COPYRIGHT, LICENSE, README and INSTALL documents provided
with the distribution. The COPYRIGHT and LICENSE provide information on acceptable use,
copying, and limitation of warranty of OpenLDAP Software.
You should also review other chapters of this document. In particular, the Building and Installing
OpenLDAP Software chapter of this document provides detailed information on prerequisite software
and installation procedures.
4. Run configure
You will need to run the provided configure script to configure the distribution for building on
your system. The configure script accepts many command line options that enable or disable
optional software features. Usually the defaults are okay, but you may want to change them. To get a
complete list of options that configure accepts, use the --help option:
./configure --help
However, given that you are using this guide, we'll assume you are brave enough to just let
configure determine what's best:
11

OpenLDAP Software 2.4 Administrator's Guide
./configure
Assuming configure doesn't dislike your system, you can proceed with building the software. If
configure did complain, well, you'll likely need to go to the Software FAQ Installation section
(http://www.openldap.org/faq/?file=8) and/or actually read the Building and Installing OpenLDAP
Software chapter of this document.
5. Build the software.
The next step is to build the software. This step has two parts, first we construct dependencies and
then we compile the software:
make depend
make
Both makes should complete without error.
6. Test the build.
To ensure a correct build, you should run the test suite (it only takes a few minutes):
make test
Tests which apply to your configuration will run and they should pass. Some tests, such as the
replication test, may be skipped.
7. Install the software.
You are now ready to install the software; this usually requires super-user privileges:
su root -c 'make install'
Everything should now be installed under /usr/local (or whatever installation prefix was used by
configure).
8. Edit the configuration file.
Use your favorite editor to edit the provided slapd.ldif example (usually installed as
/usr/local/etc/openldap/slapd.ldif) to contain a MDB database definition of the
form:
dn: olcDatabase=mdb,cn=config
objectClass: olcDatabaseConfig
objectClass: olcMdbConfig
olcDatabase: mdb
OlcDbMaxSize: 1073741824
olcSuffix: dc=,dc=
olcRootDN: cn=Manager,dc=,dc=
olcRootPW: secret
olcDbDirectory: /usr/local/var/openldap-data
olcDbIndex: objectClass eq
Be sure to replace and with the appropriate domain components of your
domain name. For example, for example.com, use:
dn: olcDatabase=mdb,cn=config
objectClass: olcDatabaseConfig
objectClass: olcMdbConfig
olcDatabase: mdb
OlcDbMaxSize: 1073741824
olcSuffix: dc=example,dc=com
olcRootDN: cn=Manager,dc=example,dc=com
olcRootPW: secret
olcDbDirectory: /usr/local/var/openldap-data
olcDbIndex: objectClass eq
12

OpenLDAP Software 2.4 Administrator's Guide
If your domain contains additional components, such as eng.uni.edu.eu, use:
dn: olcDatabase=mdb,cn=config
objectClass: olcDatabaseConfig
objectClass: olcMdbConfig
olcDatabase: mdb
OlcDbMaxSize: 1073741824
olcSuffix: dc=eng,dc=uni,dc=edu,dc=eu
olcRootDN: cn=Manager,dc=eng,dc=uni,dc=edu,dc=eu
olcRootPW: secret
olcDbDirectory: /usr/local/var/openldap-data
olcDbIndex: objectClass eq
Details regarding configuring slapd(8) can be found in the slapd-config(5) manual page and the
Configuring slapd chapter of this document. Note that the specified olcDbDirectory must exist prior
to starting slapd(8).
9. Import the configuration database
You are now ready to import your configration database for use by slapd(8), by running the
command:
su root -c /usr/local/sbin/slapadd -F /usr/local/etc/cn=config -l
/usr/local/etc/openldap/slapd.ldif
10. Start SLAPD.
You are now ready to start the Standalone LDAP Daemon, slapd(8), by running the command:
su root -c /usr/local/libexec/slapd -F /usr/local/etc/cn=config
To check to see if the server is running and configured correctly, you can run a search against it with
ldapsearch(1). By default, ldapsearch is installed as /usr/local/bin/ldapsearch:
ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts
Note the use of single quotes around command parameters to prevent special characters from being
interpreted by the shell. This should return:
dn:
namingContexts: dc=example,dc=com
Details regarding running slapd(8) can be found in the slapd(8) manual page and the Running slapd
chapter of this document.
11. Add initial entries to your directory.
You can use ldapadd(1) to add entries to your LDAP directory. ldapadd expects input in LDIF form.
We'll do it in two steps:
1. create an LDIF file
2. run ldapadd
Use your favorite editor and create an LDIF file that contains:
dn: dc=,dc=
objectclass: dcObject
objectclass: organization
o:
dc:
dn: cn=Manager,dc=,dc=
objectclass: organizationalRole
cn: Manager
Be sure to replace and with the appropriate domain components of your
13

OpenLDAP Software 2.4 Administrator's Guide
domain name. should be replaced with the name of your organization.
When you cut and paste, be sure to trim any leading and trailing whitespace from the example.
dn: dc=example,dc=com
objectclass: dcObject
objectclass: organization
o: Example Company
dc: example
dn: cn=Manager,dc=example,dc=com
objectclass: organizationalRole
cn: Manager
Now, you may run ldapadd(1) to insert these entries into your directory.
ldapadd -x -D "cn=Manager,dc=,dc=" -W -f
example.ldif
Be sure to replace and with the appropriate domain components of your
domain name. You will be prompted for the "secret" specified in slapd.conf. For example, for
example.com, use:
ldapadd -x -D "cn=Manager,dc=example,dc=com" -W -f example.ldif
where example.ldif is the file you created above.
Additional information regarding directory creation can be found in the Database Creation and
Maintenance Tools chapter of this document.
12. See if it works.
Now we're ready to verify the added entries are in your directory. You can use any LDAP client to do
this, but our example uses the ldapsearch(1) tool. Remember to replace dc=example,dc=com
with the correct values for your site:
ldapsearch -x -b 'dc=example,dc=com' '(objectclass=*)'
This command will search for and retrieve every entry in the database.
You are now ready to add more entries using ldapadd(1) or another LDAP client, experiment with various
configuration options, backend arrangements, etc..
Note that by default, the slapd(8) database grants read access to everybody excepting the super-user (as
specified by the rootdn configuration directive). It is highly recommended that you establish controls to
restrict access to authorized users. Access controls are discussed in the Access Control chapter. You are also
encouraged to read the Security Considerations, Using SASL and Using TLS sections.
The following chapters provide more detailed information on making, installing, and running slapd(8).

3. The Big Picture - Configuration Choices
This section gives a brief overview of various LDAP directory configurations, and how your Standalone
LDAP Daemon slapd(8) fits in with the rest of the world.

3.1. Local Directory Service
In this configuration, you run a slapd(8) instance which provides directory service for your local domain only.
It does not interact with other directory servers in any way. This configuration is shown in Figure 3.1.

Figure 3.1: Local service configuration.
Use this configuration if you are just starting out (it's the one the quick-start guide makes for you) or if you
want to provide a local service and are not interested in connecting to the rest of the world. It's easy to
upgrade to another configuration later if you want.

3.2. Local Directory Service with Referrals
In this configuration, you run a slapd(8) instance which provides directory service for your local domain and
configure it to return referrals to other servers capable of handling requests. You may run this service (or
services) yourself or use one provided to you. This configuration is shown in Figure 3.2.

Figure 3.2: Local service with referrals
Use this configuration if you want to provide local service and participate in the Global Directory, or you
want to delegate responsibility for subordinate entries to another server.

3.3. Replicated Directory Service
slapd(8) includes support for LDAP Sync-based replication, called syncrepl, which may be used to maintain
shadow copies of directory information on multiple directory servers. In its most basic configuration, the
master is a syncrepl provider and one or more slave (or shadow) are syncrepl consumers. An example
15

OpenLDAP Software 2.4 Administrator's Guide
master-slave configuration is shown in figure 3.3. Multi-Master configurations are also supported.

Figure 3.3: Replicated Directory Services
This configuration can be used in conjunction with either of the first two configurations in situations where a
single slapd(8) instance does not provide the required reliability or availability.

3.4. Distributed Local Directory Service
In this configuration, the local service is partitioned into smaller services, each of which may be replicated,
and glued together with superior and subordinate referrals.

4. Building and Installing OpenLDAP Software
This chapter details how to build and install the OpenLDAP Software package including slapd(8), the
Standalone LDAP Daemon. Building and installing OpenLDAP Software requires several steps: installing
prerequisite software, configuring OpenLDAP Software itself, making, and finally installing. The following
sections describe this process in detail.

4.1. Obtaining and Extracting the Software
You can obtain OpenLDAP Software from the project's download page at
http://www.openldap.org/software/download/ or directly from the project's FTP service at
ftp://ftp.openldap.org/pub/OpenLDAP/.
The project makes available two series of packages for general use. The project makes releases as new
features and bug fixes come available. Though the project takes steps to improve stability of these releases, it
is common for problems to arise only after release. The stable release is the latest release which has
demonstrated stability through general use.
Users of OpenLDAP Software can choose, depending on their desire for the latest features versus
demonstrated stability, the most appropriate series to install.
After downloading OpenLDAP Software, you need to extract the distribution from the compressed archive
file and change your working directory to the top directory of the distribution:
gunzip -c openldap-VERSION.tgz | tar xf cd openldap-VERSION
You'll have to replace VERSION with the version name of the release.
You should now review the COPYRIGHT, LICENSE, README and INSTALL documents provided with the
distribution. The COPYRIGHT and LICENSE provide information on acceptable use, copying, and limitation
of warranty of OpenLDAP Software. The README and INSTALL documents provide detailed information on
prerequisite software and installation procedures.

4.2. Prerequisite software
OpenLDAP Software relies upon a number of software packages distributed by third parties. Depending on
the features you intend to use, you may have to download and install a number of additional software
packages. This section details commonly needed third party software packages you might have to install.
However, for an up-to-date prerequisite information, the README document should be consulted. Note that
some of these third party packages may depend on additional software packages. Install each package per the
installation instructions provided with it.

4.2.1. Transport Layer Security
OpenLDAP clients and servers require installation of OpenSSL, GnuTLS, or MozNSS TLS libraries to
provide Transport Layer Security services. Though some operating systems may provide these libraries as part
of the base system or as an optional software component, OpenSSL, GnuTLS, and Mozilla NSS often require
separate installation.
17

OpenLDAP Software 2.4 Administrator's Guide
OpenSSL is available from http://www.openssl.org/. GnuTLS is available from
http://www.gnu.org/software/gnutls/. Mozilla NSS is available from http://developer.mozilla.org/en/NSS.
OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's configure detects a usable
TLS library.

4.2.2. Simple Authentication and Security Layer
OpenLDAP clients and servers require installation of Cyrus SASL libraries to provide Simple Authentication
and Security Layer services. Though some operating systems may provide this library as part of the base
system or as an optional software component, Cyrus SASL often requires separate installation.
Cyrus SASL is available from http://asg.web.cmu.edu/sasl/sasl-library.html. Cyrus SASL will make use of
OpenSSL and Kerberos/GSSAPI libraries if preinstalled.
OpenLDAP Software will not be fully LDAPv3 compliant unless OpenLDAP's configure detects a usable
Cyrus SASL installation.

4.2.3. Kerberos Authentication Service
OpenLDAP clients and servers support Kerberos authentication services. In particular, OpenLDAP supports
the Kerberos V GSS-API SASL authentication mechanism known as the GSSAPI mechanism. This feature
requires, in addition to Cyrus SASL libraries, either Heimdal or MIT Kerberos V libraries.
Heimdal Kerberos is available from http://www.pdc.kth.se/heimdal/. MIT Kerberos is available from
http://web.mit.edu/kerberos/www/.
Use of strong authentication services, such as those provided by Kerberos, is highly recommended.

4.2.4. Database Software
OpenLDAP's slapd(8) MDB primary database backend uses the LMDB software included with the
OpenLDAP source. There is no need to download any additional software to have MDB support.
OpenLDAP's slapd(8) BDB and HDB deprecated database backends require Oracle Corporation's Berkeley
DB. If not available at configure time, you will not be able to build slapd(8) with these deprecated database
backends.
Your operating system may provide a supported version of Berkeley DB in the base system or as an optional
software component. If not, you'll have to obtain and install it yourself. Berkeley DB is available from Oracle
Corporation's Berkeley DB download page if required.
There are several versions available from Oracle Corporation. Berkeley DB version 6.0.20 and later uses a
software license that is incompatible with LDAP technology and should not be used with OpenLDAP.
Note: Please see Recommended OpenLDAP Software Dependency Versions for more information.

OpenLDAP Software 2.4 Administrator's Guide

4.2.5. Threads
OpenLDAP is designed to take advantage of threads. OpenLDAP supports POSIX pthreads, Mach CThreads,
and a number of other varieties. configure will complain if it cannot find a suitable thread subsystem. If
this occurs, please consult the Software|Installation|Platform Hints section of the
OpenLDAP FAQ http://www.openldap.org/faq/.

4.2.6. TCP Wrappers
slapd(8) supports TCP Wrappers (IP level access control filters) if preinstalled. Use of TCP Wrappers or other
IP-level access filters (such as those provided by an IP-level firewall) is recommended for servers containing
non-public information.

4.3. Running configure
Now you should probably run the configure script with the --help option. This will give you a list of
options that you can change when building OpenLDAP. Many of the features of OpenLDAP can be enabled
or disabled using this method.
./configure --help

The configure script also looks for certain variables on the command line and in the environment. These
include:
Table 4.1: Variables
Variable
Description
CC
Specify alternative C Compiler
CFLAGS
Specify additional compiler flags
CPPFLAGS Specify C Preprocessor flags
LDFLAGS Specify linker flags
LIBS
Specify additional libraries
Now run the configure script with any desired configuration options or variables.
./configure [options] [variable=value ...]

As an example, let's assume that we want to install OpenLDAP with BDB backend and TCP Wrappers
support. By default, BDB is enabled and TCP Wrappers is not. So, we just need to specify
--enable-wrappers to include TCP Wrappers support:
./configure --enable-wrappers

However, this will fail to locate dependent software not installed in system directories. For example, if TCP
Wrappers headers and libraries are installed in /usr/local/include and /usr/local/lib
respectively, the configure script should typically be called as follows:
./configure --enable-wrappers \
CPPFLAGS="-I/usr/local/include" \
LDFLAGS="-L/usr/local/lib -Wl,-rpath,/usr/local/lib"

OpenLDAP Software 2.4 Administrator's Guide
The configure script will normally auto-detect appropriate settings. If you have problems at this stage,
consult any platform specific hints and check your configure options, if any.

4.4. Building the Software
Once you have run the configure script the last line of output should be:
Please "make depend" to build dependencies

If the last line of output does not match, configure has failed, and you will need to review its output to
determine what went wrong. You should not proceed until configure completes successfully.
To build dependencies, run:
make depend

Now build the software, this step will actually compile OpenLDAP.
make

You should examine the output of this command carefully to make sure everything is built correctly. Note that
this command builds the LDAP libraries and associated clients as well as slapd(8).

4.5. Testing the Software
Once the software has been properly configured and successfully made, you should run the test suite to verify
the build.
make test

Tests which apply to your configuration will run and they should pass. Some tests, such as the replication test,
may be skipped if not supported by your configuration.

4.6. Installing the Software
Once you have successfully tested the software, you are ready to install it. You will need to have write
permission to the installation directories you specified when you ran configure. By default OpenLDAP
Software is installed in /usr/local. If you changed this setting with the --prefix configure option, it
will be installed in the location you provided.
Typically, the installation requires super-user privileges. From the top level OpenLDAP source directory,
type:
su root -c 'make install'

and enter the appropriate password when requested.
You should examine the output of this command carefully to make sure everything is installed correctly. You
will find the configuration files for slapd(8) in /usr/local/etc/openldap by default. See the chapter
Configuring slapd for additional information.
20

OpenLDAP Software 2.4 Administrator's Guide

5. Configuring slapd
Once the software has been built and installed, you are ready to configure slapd(8) for use at your site.
OpenLDAP 2.3 and later have transitioned to using a dynamic runtime configuration engine, slapd-config(5).
slapd-config(5)
• is fully LDAP-enabled
• is managed using the standard LDAP operations
• stores its configuration data in an LDIF database, generally in the
/usr/local/etc/openldap/slapd.d directory.
• allows all of slapd's configuration options to be changed on the fly, generally without requiring a
server restart for the changes to take effect.
This chapter describes the general format of the slapd-config(5) configuration system, followed by a detailed
description of commonly used settings.
The older style slapd.conf(5) file is still supported, but its use is deprecated and support for it will be
withdrawn in a future OpenLDAP release. Configuring slapd(8) via slapd.conf(5) is described in the next
chapter.
Refer to slapd(8) for information on how to have slapd automatically convert from slapd.conf(5) to
slapd-config(5).
Note: Although the slapd-config(5) system stores its configuration as (text-based) LDIF files, you should
never edit any of the LDIF files directly. Configuration changes should be performed via LDAP operations,
e.g. ldapadd(1), ldapdelete(1), or ldapmodify(1).

Note: You will need to continue to use the older slapd.conf(5) configuration system if your OpenLDAP
installation requires the use of one or more backends or overlays that have not been updated to use the
slapd-config(5) system. As of OpenLDAP 2.4.33, all of the official backends have been updated. There may
be additional contributed or experimental overlays that also have not been updated.

5.1. Configuration Layout
The slapd configuration is stored as a special LDAP directory with a predefined schema and DIT. There are
specific objectClasses used to carry global configuration options, schema definitions, backend and database
definitions, and assorted other items. A sample config tree is shown in Figure 5.1.

OpenLDAP Software 2.4 Administrator's Guide

Figure 5.1: Sample configuration tree.
Other objects may be part of the configuration but were omitted from the illustration for clarity.
The slapd-config configuration tree has a very specific structure. The root of the tree is named cn=config
and contains global configuration settings. Additional settings are contained in separate child entries:
• Dynamically loaded modules
These may only be used if the --enable-modules option was used to configure the software.
• Schema definitions
The cn=schema,cn=config entry contains the system schema (all the schema that is hard-coded
in slapd).
Child entries of cn=schema,cn=config contain user schema as loaded from config files or added
at runtime.
• Backend-specific configuration
• Database-specific configuration
Overlays are defined in children of the Database entry.
Databases and Overlays may also have other miscellaneous children.
The usual rules for LDIF files apply to the configuration information: Comment lines beginning with a '#'
character are ignored. If a line begins with a single space, it is considered a continuation of the previous line
(even if the previous line is a comment) and the single leading space is removed. Entries are separated by
blank lines.
The general layout of the config LDIF is as follows:
# global configuration settings
dn: cn=config
objectClass: olcGlobal
cn: config

# schema definitions
dn: cn=schema,cn=config
objectClass: olcSchemaConfig
cn: schema

OpenLDAP Software 2.4 Administrator's Guide

dn: cn={X}core,cn=schema,cn=config
objectClass: olcSchemaConfig
cn: {X}core

# additional user-specified schema
...
# backend definitions
dn: olcBackend=,cn=config
objectClass: olcBackendConfig
olcBackend:

# database definitions
dn: olcDatabase={X},cn=config
objectClass: olcDatabaseConfig
olcDatabase: {X}

# subsequent definitions and settings
...

Some of the entries listed above have a numeric index "{X}" in their names. While most configuration
settings have an inherent ordering dependency (i.e., one setting must take effect before a subsequent one may
be set), LDAP databases are inherently unordered. The numeric index is used to enforce a consistent ordering
in the configuration database, so that all ordering dependencies are preserved. In most cases the index does
not have to be provided; it will be automatically generated based on the order in which entries are created.
Configuration directives are specified as values of individual attributes. Most of the attributes and
objectClasses used in the slapd configuration have a prefix of "olc" (OpenLDAP Configuration) in their
names. Generally there is a one-to-one correspondence between the attributes and the old-style slapd.conf
configuration keywords, using the keyword as the attribute name, with the "olc" prefix attached.
A configuration directive may take arguments. If so, the arguments are separated by whitespace. If an
argument contains whitespace, the argument should be enclosed in double quotes "like this". In the
descriptions that follow, arguments that should be replaced by actual text are shown in brackets <>.
The distribution contains an example configuration file that will be installed in the
/usr/local/etc/openldap directory. A number of files containing schema definitions (attribute types
and object classes) are also provided in the /usr/local/etc/openldap/schema directory.

5.2. Configuration Directives
This section details commonly used configuration directives. For a complete list, see the slapd-config(5)
manual page. This section will treat the configuration directives in a top-down order, starting with the global
directives in the cn=config entry. Each directive will be described along with its default value (if any) and
an example of its use.

OpenLDAP Software 2.4 Administrator's Guide

5.2.1. cn=config
Directives contained in this entry generally apply to the server as a whole. Most of them are system or
connection oriented, not database related. This entry must have the olcGlobal objectClass.
5.2.1.1. olcIdleTimeout:
Specify the number of seconds to wait before forcibly closing an idle client connection. A value of 0, the
default, disables this feature.
5.2.1.2. olcLogLevel:
This directive specifies the level at which debugging statements and operation statistics should be syslogged
(currently logged to the syslogd(8) LOG_LOCAL4 facility). You must have configured OpenLDAP
--enable-debug (the default) for this to work (except for the two statistics levels, which are always
enabled). Log levels may be specified as integers or by keyword. Multiple log levels may be used and the
levels are additive. To display what levels correspond to what kind of debugging, invoke slapd with -d? or
consult the table below. The possible values for are:
Table 5.1: Debugging Levels
Level Keyword
Description
-1 any
enable all debugging
0
no debugging
1 (0x1 trace)
trace function calls
2 (0x2 packets) debug packet handling
4 (0x4 args)
heavy trace debugging
8 (0x8 conns)
connection management
16 (0x10 BER)
print out packets sent and received
32 (0x20 filter)
search filter processing
64 (0x40 config) configuration processing
128 (0x80 ACL)
access control list processing
256 (0x100 stats) stats log connections/operations/results
512 (0x200 stats2) stats log entries sent
1024 (0x400 shell) print communication with shell backends
2048 (0x800 parse) print entry parsing debugging
16384 (0x4000 sync) syncrepl consumer processing
32768 (0x8000 none) only messages that get logged whatever log level is set
The desired log level can be input as a single integer that combines the (ORed) desired levels, both in decimal
or in hexadecimal notation, as a list of integers (that are ORed internally), or as a list of the names that are
shown between brackets, such that
olcLogLevel
olcLogLevel
olcLogLevel
olcLogLevel
olcLogLevel

129
0x81
128 1
0x80 0x1
acl trace

OpenLDAP Software 2.4 Administrator's Guide
are equivalent.
Examples:
olcLogLevel -1

This will cause lots and lots of debugging information to be logged.
olcLogLevel conns filter

Just log the connection and search filter processing.
olcLogLevel none

Log those messages that are logged regardless of the configured loglevel. This differs from setting the log
level to 0, when no logging occurs. At least the None level is required to have high priority messages logged.
Default:
olcLogLevel stats

Basic stats logging is configured by default. However, if no olcLogLevel is defined, no logging occurs
(equivalent to a 0 level).
5.2.1.3. olcReferral
This directive specifies the referral to pass back when slapd cannot find a local database to handle a request.
Example:
olcReferral: ldap://root.openldap.org

This will refer non-local queries to the global root LDAP server at the OpenLDAP Project. Smart LDAP
clients can re-ask their query at that server, but note that most of these clients are only going to know how to
handle simple LDAP URLs that contain a host part and optionally a distinguished name part.
5.2.1.4. Sample Entry
dn: cn=config
objectClass: olcGlobal
cn: config
olcIdleTimeout: 30
olcLogLevel: Stats
olcReferral: ldap://root.openldap.org

5.2.2. cn=module
If support for dynamically loaded modules was enabled when configuring slapd, cn=module entries may be
used to specify sets of modules to load. Module entries must have the olcModuleList objectClass.

OpenLDAP Software 2.4 Administrator's Guide
5.2.2.1. olcModuleLoad:
Specify the name of a dynamically loadable module to load. The filename may be an absolute path name or a
simple filename. Non-absolute names are searched for in the directories specified by the olcModulePath
directive.
5.2.2.2. olcModulePath:
Specify a list of directories to search for loadable modules. Typically the path is colon-separated but this
depends on the operating system.
5.2.2.3. Sample Entries
dn: cn=module{0},cn=config
objectClass: olcModuleList
cn: module{0}
olcModuleLoad: /usr/local/lib/smbk5pwd.la
dn: cn=module{1},cn=config
objectClass: olcModuleList
cn: module{1}
olcModulePath: /usr/local/lib:/usr/local/lib/slapd
olcModuleLoad: accesslog.la
olcModuleLoad: pcache.la

5.2.3. cn=schema
The cn=schema entry holds all of the schema definitions that are hard-coded in slapd. As such, the values in
this entry are generated by slapd so no schema values need to be provided in the config file. The entry must
still be defined though, to serve as a base for the user-defined schema to add in underneath. Schema entries
must have the olcSchemaConfig objectClass.
5.2.3.1. olcAttributeTypes:
This directive defines an attribute type. Please see the Schema Specification chapter for information regarding
how to use this directive.
5.2.3.2. olcObjectClasses:
This directive defines an object class. Please see the Schema Specification chapter for information regarding
how to use this directive.
5.2.3.3. Sample Entries
dn: cn=schema,cn=config
objectClass: olcSchemaConfig
cn: schema
dn: cn=test,cn=schema,cn=config
objectClass: olcSchemaConfig
cn: test
olcAttributeTypes: ( 1.1.1
NAME 'testAttr'
EQUALITY integerMatch

OpenLDAP Software 2.4 Administrator's Guide
SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 )
olcAttributeTypes: ( 1.1.2 NAME 'testTwo' EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 )
olcObjectClasses: ( 1.1.3 NAME 'testObject'
MAY ( testAttr $ testTwo ) AUXILIARY )

5.2.4. Backend-specific Directives
Backend directives apply to all database instances of the same type and, depending on the directive, may be
overridden by database directives. Backend entries must have the olcBackendConfig objectClass.
5.2.4.1. olcBackend:
This directive names a backend-specific configuration entry. should be one of the supported backend
types listed in Table 5.2.
Table 5.2: Database Backends
Types
bdb
config
dnssrv
hdb
ldap
ldif
meta
monitor
passwd
perl
shell
sql

Description
Berkeley DB transactional backend
Slapd configuration backend
DNS SRV backend
Hierarchical variant of bdb backend
Lightweight Directory Access Protocol (Proxy) backend
Lightweight Data Interchange Format backend
Meta Directory backend
Monitor backend
Provides read-only access to passwd(5)
Perl Programmable backend
Shell (extern program) backend
SQL Programmable backend

Example:
olcBackend: bdb

There are no other directives defined for this entry. Specific backend types may define additional attributes for
their particular use but so far none have ever been defined. As such, these directives usually do not appear in
any actual configurations.
5.2.4.2. Sample Entry
dn: olcBackend=bdb,cn=config
objectClass: olcBackendConfig
olcBackend: bdb

5.2.5. Database-specific Directives
Directives in this section are supported by every type of database. Database entries must have the
olcDatabaseConfig objectClass.
29

OpenLDAP Software 2.4 Administrator's Guide
5.2.5.1. olcDatabase: [{}]
This directive names a specific database instance. The numeric {} may be provided to distinguish
multiple databases of the same type. Usually the index can be omitted, and slapd will generate it
automatically. should be one of the supported backend types listed in Table 5.2 or the frontend
type.
The frontend is a special database that is used to hold database-level options that should be applied to all
the other databases. Subsequent database definitions may also override some frontend settings.
The config database is also special; both the config and the frontend databases are always created
implicitly even if they are not explicitly configured, and they are created before any other databases.
Example:
olcDatabase: bdb

This marks the beginning of a new BDB database instance.
5.2.5.2. olcAccess: to [ by [] [] ]+
This directive grants access (specified by ) to a set of entries and/or attributes (specified by
) by one or more requestors (specified by ). See the Access Control section of this guide for
basic usage.
Note: If no olcAccess directives are specified, the default access control policy, to * by * read,
allows all users (both authenticated and anonymous) read access.

Note: Access controls defined in the frontend are appended to all other databases' controls.
5.2.5.3. olcReadonly { TRUE | FALSE }
This directive puts the database into "read-only" mode. Any attempts to modify the database will return an
"unwilling to perform" error.
Default:
olcReadonly: FALSE

5.2.5.4. olcRootDN:
This directive specifies the DN that is not subject to access control or administrative limit restrictions for
operations on this database. The DN need not refer to an entry in this database or even in the directory. The
DN may refer to a SASL identity.
Entry-based Example:
olcRootDN: "cn=Manager,dc=example,dc=com"

SASL-based Example:
30

OpenLDAP Software 2.4 Administrator's Guide
olcRootDN: "uid=root,cn=example.com,cn=digest-md5,cn=auth"

See the SASL Authentication section for information on SASL authentication identities.
5.2.5.5. olcRootPW:
This directive can be used to specify a password for the DN for the rootdn (when the rootdn is set to a DN
within the database).
Example:
olcRootPW: secret

It is also permissible to provide a hash of the password in RFC2307 form. slappasswd(8) may be used to
generate the password hash.
Example:
olcRootPW: {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN

The hash was generated using the command slappasswd -s secret.
5.2.5.6. olcSizeLimit:
This directive specifies the maximum number of entries to return from a search operation.
Default:
olcSizeLimit: 500

See the Limits section of this guide and slapd-config(5) for more details.
5.2.5.7. olcSuffix:
This directive specifies the DN suffix of queries that will be passed to this backend database. Multiple suffix
lines can be given, and usually at least one is required for each database definition. (Some backend types, such
as frontend and monitor use a hard-coded suffix which may not be overridden in the configuration.)
Example:
olcSuffix: "dc=example,dc=com"

Queries with a DN ending in "dc=example,dc=com" will be passed to this backend.
Note: When the backend to pass a query to is selected, slapd looks at the suffix value(s) in each database
definition in the order in which they were configured. Thus, if one database suffix is a prefix of another, it
must appear after it in the configuration.

OpenLDAP Software 2.4 Administrator's Guide
5.2.5.8. olcSyncrepl
olcSyncrepl: rid=
provider=ldap[s]://[:port]
[type=refreshOnly|refreshAndPersist]
[interval=dd:hh:mm:ss]
[retry=[ <# of retries>]+]
searchbase=
[filter=]
[scope=sub|one|base]
[attrs=]
[attrsonly]
[sizelimit=]
[timelimit=]
[schemachecking=on|off]
[bindmethod=simple|sasl]
[binddn=]
[saslmech=]
[authcid=]
[authzid=]
[credentials=]
[realm=]
[secprops=]
[starttls=yes|critical]
[tls_cert=]
[tls_key=]
[tls_cacert=]
[tls_cacertdir=]
[tls_reqcert=never|allow|try|demand]
[tls_ciphersuite=]
[tls_crlcheck=none|peer|all]
[logbase=]
[logfilter=]
[syncdata=default|accesslog|changelog]

This directive specifies the current database as a replica of the master content by establishing the current
slapd(8) as a replication consumer site running a syncrepl replication engine. The master database is located at
the replication provider site specified by the provider parameter. The replica database is kept up-to-date
with the master content using the LDAP Content Synchronization protocol. See RFC4533 for more
information on the protocol.
The rid parameter is used for identification of the current syncrepl directive within the replication
consumer server, where uniquely identifies the syncrepl specification described by the
current syncrepl directive. is non-negative and is no more than three decimal digits in
length.
The provider parameter specifies the replication provider site containing the master content as an LDAP
URI. The provider parameter specifies a scheme, a host and optionally a port where the provider slapd
instance can be found. Either a domain name or IP address may be used for . Examples are
ldap://provider.example.com:389 or ldaps://192.168.1.1:636. If is not given,
the standard LDAP port number (389 or 636) is used. Note that the syncrepl uses a consumer-initiated
protocol, and hence its specification is located at the consumer site, whereas the replica specification is
located at the provider site. syncrepl and replica directives define two independent replication
mechanisms. They do not represent the replication peers of each other.

OpenLDAP Software 2.4 Administrator's Guide
The content of the syncrepl replica is defined using a search specification as its result set. The consumer slapd
will send search requests to the provider slapd according to the search specification. The search specification
includes searchbase, scope, filter, attrs, attrsonly, sizelimit, and timelimit
parameters as in the normal search specification. The searchbase parameter has no default value and must
always be specified. The scope defaults to sub, the filter defaults to (objectclass=*), attrs
defaults to "*,+" to replicate all user and operational attributes, and attrsonly is unset by default. Both
sizelimit and timelimit default to "unlimited", and only positive integers or "unlimited" may be
specified.
The LDAP Content Synchronization protocol has two operation types: refreshOnly and
refreshAndPersist. The operation type is specified by the type parameter. In the refreshOnly
operation, the next synchronization search operation is periodically rescheduled at an interval time after each
synchronization operation finishes. The interval is specified by the interval parameter. It is set to one day
by default. In the refreshAndPersist operation, a synchronization search remains persistent in the
provider slapd instance. Further updates to the master replica will generate searchResultEntry to the
consumer slapd as the search responses to the persistent synchronization search.
If an error occurs during replication, the consumer will attempt to reconnect according to the retry parameter
which is a list of the and <# of retries> pairs. For example, retry="60 10 300 3" lets the
consumer retry every 60 seconds for the first 10 times and then retry every 300 seconds for the next three
times before stop retrying. + in <# of retries> means indefinite number of retries until success.
The schema checking can be enforced at the LDAP Sync consumer site by turning on the
schemachecking parameter. If it is turned on, every replicated entry will be checked for its schema as the
entry is stored into the replica content. Every entry in the replica should contain those attributes required by
the schema definition. If it is turned off, entries will be stored without checking schema conformance. The
default is off.
The binddn parameter gives the DN to bind as for the syncrepl searches to the provider slapd. It should be a
DN which has read access to the replication content in the master database.
The bindmethod is simple or sasl, depending on whether simple password-based authentication or
SASL authentication is to be used when connecting to the provider slapd instance.
Simple authentication should not be used unless adequate data integrity and confidentiality protections are in
place (e.g. TLS or IPsec). Simple authentication requires specification of binddn and credentials
parameters.
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.
The realm parameter specifies a realm which a certain mechanisms authenticate the identity within. The
secprops parameter specifies Cyrus SASL security properties.
The starttls parameter specifies use of the StartTLS extended operation to establish a TLS session before
authenticating to the provider. If the critical argument is supplied, the session will be aborted if the
StartTLS request fails. Otherwise the syncrepl session continues without TLS. The tls_reqcert setting defaults
to "demand" and the other TLS settings default to the same as the main slapd TLS settings.

OpenLDAP Software 2.4 Administrator's Guide
Rather than replicating whole entries, the consumer can query logs of data modifications. 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. The syncdata parameter must be set to
either "accesslog" if the log conforms to the slapo-accesslog(5) log format, or "changelog" if the log
conforms to the obsolete changelog format. If the syncdata parameter is omitted or set to "default"
then the log parameters are ignored.
The syncrepl replication mechanism is supported by the bdb and hdb backends.
See the LDAP Sync Replication chapter of this guide for more information on how to use this directive.
5.2.5.9. olcTimeLimit:
This directive specifies the maximum number of seconds (in real time) 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.
Default:
olcTimeLimit: 3600

See the Limits section of this guide and slapd-config(5) for more details.
5.2.5.10. olcUpdateref:
This directive is only applicable in a slave slapd. It specifies the URL to return to clients which submit update
requests upon the replica. If specified multiple times, each URL is provided.
Example:
olcUpdateref:

ldap://master.example.net

5.2.5.11. Sample Entries
dn: olcDatabase=frontend,cn=config
objectClass: olcDatabaseConfig
objectClass: olcFrontendConfig
olcDatabase: frontend
olcReadOnly: FALSE
dn: olcDatabase=config,cn=config
objectClass: olcDatabaseConfig
olcDatabase: config
olcRootDN: cn=Manager,dc=example,dc=com

5.2.6. BDB and HDB Database Directives
Directives in this category apply to both the BDB and the HDB database. They are used in an olcDatabase
entry in addition to the generic database directives defined above. For a complete reference of BDB/HDB
configuration directives, see slapd-bdb(5). In addition to the olcDatabaseConfig objectClass, BDB and
HDB database entries must have the olcBdbConfig and olcHdbConfig objectClass, respectively.

OpenLDAP Software 2.4 Administrator's Guide
5.2.6.1. olcDbDirectory:
This directive specifies the directory where the BDB files containing the database and associated indices live.
Default:
olcDbDirectory: /usr/local/var/openldap-data

5.2.6.2. olcDbCachesize:
This directive specifies the size in entries of the in-memory cache maintained by the BDB backend database
instance.
Default:
olcDbCachesize: 1000

5.2.6.3. olcDbCheckpoint:
This directive specifies how often to checkpoint the BDB transaction log. A checkpoint operation flushes the
database buffers to disk and writes a checkpoint record in the log. The checkpoint will occur if either
data has been written or minutes have passed since the last checkpoint. Both arguments default to zero,
in which case they are ignored. When the argument is non-zero, an internal task will run every
minutes to perform the checkpoint. See the Berkeley DB reference guide for more details.
Example:
olcDbCheckpoint: 1024 10

5.2.6.4. olcDbConfig:
This attribute specifies a configuration directive to be placed in the DB_CONFIG file of the database
directory. At server startup time, if no such file exists yet, the DB_CONFIG file will be created and the
settings in this attribute will be written to it. If the file exists, its contents will be read and displayed in this
attribute. The attribute is multi-valued, to accommodate multiple configuration directives. No default is
provided, but it is essential to use proper settings here to get the best server performance.
Any changes made to this attribute will be written to the DB_CONFIG file and will cause the database
environment to be reset so the changes can take immediate effect. If the environment cache is large and has
not been recently checkpointed, this reset operation may take a long time. It may be advisable to manually
perform a single checkpoint using the Berkeley DB db_checkpoint utility before using LDAP Modify to
change this attribute.
Example:
olcDbConfig:
olcDbConfig:
olcDbConfig:
olcDbConfig:

set_cachesize 0 10485760 0
set_lg_bsize 2097512
set_lg_dir /var/tmp/bdb-log
set_flags DB_LOG_AUTOREMOVE

In this example, the BDB cache is set to 10MB, the BDB transaction log buffer size is set to 2MB, and the
transaction log files are to be stored in the /var/tmp/bdb-log directory. Also a flag is set to tell BDB to delete
35

OpenLDAP Software 2.4 Administrator's Guide
transaction log files as soon as their contents have been checkpointed and they are no longer needed. Without
this setting the transaction log files will continue to accumulate until some other cleanup procedure removes
them. See the Berkeley DB documentation for the db_archive command for details. For a complete list of
Berkeley DB flags please see http://www.oracle.com/technology/documentation/berkeley-db/db/api_c/env_set_flags.html
Ideally the BDB cache must be at least as large as the working set of the database, the log buffer size should
be large enough to accommodate most transactions without overflowing, and the log directory must be on a
separate physical disk from the main database files. And both the database directory and the log directory
should be separate from disks used for regular system activities such as the root, boot, or swap filesystems.
See the FAQ-o-Matic and the Berkeley DB documentation for more details.
5.2.6.5. olcDbNosync: { TRUE | FALSE }
This option causes on-disk database contents to not be immediately synchronized with in memory changes
upon change. Setting this option to TRUE may improve performance at the expense of data integrity. This
directive has the same effect as using
olcDbConfig: set_flags DB_TXN_NOSYNC

5.2.6.6. olcDbIDLcacheSize:
Specify the size of the in-memory index cache, in index slots. The default is zero. A larger value will speed up
frequent searches of indexed entries. The optimal size will depend on the data and search characteristics of the
database, but using a number three times the entry cache size is a good starting point.
Example:
olcDbIDLcacheSize: 3000

5.2.6.7. olcDbIndex: { | default} [pres,eq,approx,sub,none]
This directive specifies the indices to maintain for the given attribute. If only an is given, the
default indices are maintained. The index keywords correspond to the common types of matches that may be
used in an LDAP search filter.
Example:
olcDbIndex:
olcDbIndex:
olcDbIndex:
olcDbIndex:

default pres,eq
uid
cn,sn pres,eq,sub
objectClass eq

The first line sets the default set of indices to maintain to present and equality. The second line causes the
default (pres,eq) set of indices to be maintained for the uid attribute type. The third line causes present,
equality, and substring indices to be maintained for cn and sn attribute types. The fourth line causes an
equality index for the objectClass attribute type.
There is no index keyword for inequality matches. Generally these matches do not use an index. However,
some attributes do support indexing for inequality matches, based on the equality index.

OpenLDAP Software 2.4 Administrator's Guide
A substring index can be more explicitly specified as subinitial, subany, or subfinal, corresponding
to the three possible components of a substring match filter. A subinitial index only indexes substrings that
appear at the beginning of an attribute value. A subfinal index only indexes substrings that appear at the end
of an attribute value, while subany indexes substrings that occur anywhere in a value.
Note that by default, setting an index for an attribute also affects every subtype of that attribute. E.g., setting
an equality index on the name attribute causes cn, sn, and every other attribute that inherits from name to be
indexed.
By default, no indices are maintained. It is generally advised that minimally an equality index upon
objectClass be maintained.
olcDbindex: objectClass eq

Additional indices should be configured corresponding to the most common searches that are used on the
database. Presence indexing should not be configured for an attribute unless the attribute occurs very rarely in
the database, and presence searches on the attribute occur very frequently during normal use of the directory.
Most applications don't use presence searches, so usually presence indexing is not very useful.
If this setting is changed while slapd is running, an internal task will be run to generate the changed index
data. All server operations can continue as normal while the indexer does its work. If slapd is stopped before
the index task completes, indexing will have to be manually completed using the slapindex tool.
5.2.6.8. olcDbLinearIndex: { TRUE | FALSE }
If this setting is TRUE slapindex will index one attribute at a time. The default settings is FALSE in which
case all indexed attributes of an entry are processed at the same time. When enabled, each indexed attribute is
processed individually, using multiple passes through the entire database. This option improves slapindex
performance when the database size exceeds the BDB cache size. When the BDB cache is large enough, this
option is not needed and will decrease performance. Also by default, slapadd performs full indexing and so a
separate slapindex run is not needed. With this option, slapadd does no indexing and slapindex must be used.
5.2.6.9. olcDbMode: { | }
This directive specifies the file protection mode that newly created database index files should have. This can
be in the form 0600 or -rw------Default:
olcDbMode: 0600

5.2.6.10. olcDbSearchStack:
Specify the depth of the stack used for search filter evaluation. Search filters are evaluated on a stack to
accommodate nested AND / OR clauses. An individual stack is allocated for each server thread. The depth of
the stack determines how complex a filter can be evaluated without requiring any additional memory
allocation. Filters that are nested deeper than the search stack depth will cause a separate stack to be allocated
for that particular search operation. These separate allocations can have a major negative impact on server
performance, but specifying too much stack will also consume a great deal of memory. Each search uses
512K bytes per level on a 32-bit machine, or 1024K bytes per level on a 64-bit machine. The default stack
depth is 16, thus 8MB or 16MB per thread is used on 32 and 64 bit machines, respectively. Also the 512KB
37

OpenLDAP Software 2.4 Administrator's Guide
size of a single stack slot is set by a compile-time constant which may be changed if needed; the code must be
recompiled for the change to take effect.
Default:
olcDbSearchStack: 16

5.2.6.11. olcDbShmKey:
Specify a key for a shared memory BDB environment. By default the BDB environment uses memory
mapped files. If a non-zero value is specified, it will be used as the key to identify a shared memory region
that will house the environment.
Example:
olcDbShmKey: 42

5.2.6.12. Sample Entry
dn: olcDatabase=hdb,cn=config
objectClass: olcDatabaseConfig
objectClass: olcHdbConfig
olcDatabase: hdb
olcSuffix: "dc=example,dc=com"
olcDbDirectory: /usr/local/var/openldap-data
olcDbCacheSize: 1000
olcDbCheckpoint: 1024 10
olcDbConfig: set_cachesize 0 10485760 0
olcDbConfig: set_lg_bsize 2097152
olcDbConfig: set_lg_dir /var/tmp/bdb-log
olcDbConfig: set_flags DB_LOG_AUTOREMOVE
olcDbIDLcacheSize: 3000
olcDbIndex: objectClass eq

5.3. Configuration Example
The following is an example configuration, interspersed with explanatory text. It defines two databases to
handle different parts of the X.500 tree; both are BDB database instances. The line numbers shown are
provided for reference only and are not included in the actual file. First, the global configuration section:
1.
2.
3.
4.
5.
6.

# example config file - global configuration entry
dn: cn=config
objectClass: olcGlobal
cn: config
olcReferral: ldap://root.openldap.org

Line 1 is a comment. Lines 2-4 identify this as the global configuration entry. The olcReferral: directive
on line 5 means that queries not local to one of the databases defined below will be referred to the LDAP
server running on the standard port (389) at the host root.openldap.org. Line 6 is a blank line,
indicating the end of this entry.
7.
8.
9.

# internal schema
dn: cn=schema,cn=config
objectClass: olcSchemaConfig

OpenLDAP Software 2.4 Administrator's Guide
10.
11.

cn: schema

Line 7 is a comment. Lines 8-10 identify this as the root of the schema subtree. The actual schema definitions
in this entry are hardcoded into slapd so no additional attributes are specified here. Line 11 is a blank line,
indicating the end of this entry.
12.
13.
14.

# include the core schema
include: file:///usr/local/etc/openldap/schema/core.ldif

Line 12 is a comment. Line 13 is an LDIF include directive which accesses the core schema definitions in
LDIF format. Line 14 is a blank line.
Next comes the database definitions. The first database is the special frontend database whose settings are
applied globally to all the other databases.
15.
16.
17.
18.
19.
20.

# global database parameters
dn: olcDatabase=frontend,cn=config
objectClass: olcDatabaseConfig
olcDatabase: frontend
olcAccess: to * by * read

Line 15 is a comment. Lines 16-18 identify this entry as the global database entry. Line 19 is a global access
control. It applies to all entries (after any applicable database-specific access controls). Line 20 is a blank line.
The next entry defines the config backend.
21.
22.
23.
24.
25.
26.
27.
28.

# set a rootpw for the config database so we can bind.
# deny access to everyone else.
dn: olcDatabase=config,cn=config
objectClass: olcDatabaseConfig
olcDatabase: config
olcRootPW: {SSHA}XKYnrjvGT3wZFQrDD5040US592LxsdLy
olcAccess: to * by * none

Lines 21-22 are comments. Lines 23-25 identify this entry as the config database entry. Line 26 defines the
super-user password for this database. (The DN defaults to "cn=config".) Line 27 denies all access to this
database, so only the super-user will be able to access it. (This is already the default access on the config
database. It is just listed here for illustration, and to reiterate that unless a means to authenticate as the
super-user is explicitly configured, the config database will be inaccessible.)
Line 28 is a blank line.
The next entry defines a BDB backend that will handle queries for things in the "dc=example,dc=com"
portion of the tree. Indices are to be maintained for several attributes, and the userPassword attribute is to
be protected from unauthorized access.
29.
30.
31.
32.
33.

# BDB definition for example.com
dn: olcDatabase=bdb,cn=config
objectClass: olcDatabaseConfig
objectClass: olcBdbConfig
olcDatabase: bdb

OpenLDAP Software 2.4 Administrator's Guide
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.

olcSuffix: dc=example,dc=com
olcDbDirectory: /usr/local/var/openldap-data
olcRootDN: cn=Manager,dc=example,dc=com
olcRootPW: secret
olcDbIndex: uid pres,eq
olcDbIndex: cn,sn pres,eq,approx,sub
olcDbIndex: objectClass eq
olcAccess: to attrs=userPassword
by self write
by anonymous auth
by dn.base="cn=Admin,dc=example,dc=com" write
by * none
olcAccess: to *
by self write
by dn.base="cn=Admin,dc=example,dc=com" write
by * read

Line 29 is a comment. Lines 30-33 identify this entry as a BDB database configuration entry. Line 34
specifies the DN suffix for queries to pass to this database. Line 35 specifies the directory in which the
database files will live.
Lines 36 and 37 identify the database super-user entry and associated password. This entry is not subject to
access control or size or time limit restrictions.
Lines 38 through 40 indicate the indices to maintain for various attributes.
Lines 41 through 49 specify access control for entries in this database. For all applicable entries, the
userPassword attribute is writable by the entry itself and by the "admin" entry. It may be used for
authentication/authorization purposes, but is otherwise not readable. All other attributes are writable by the
entry and the "admin" entry, but may be read by all users (authenticated or not).
Line 50 is a blank line, indicating the end of this entry.
The next entry defines another BDB database. This one handles queries involving the
dc=example,dc=net subtree but is managed by the same entity as the first database. Note that without
line 60, the read access would be allowed due to the global access rule at line 19.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.

# BDB definition for example.net
dn: olcDatabase=bdb,cn=config
objectClass: olcDatabaseConfig
objectClass: olcBdbConfig
olcDatabase: bdb
olcSuffix: "dc=example,dc=net"
olcDbDirectory: /usr/local/var/openldap-data-net
olcRootDN: "cn=Manager,dc=example,dc=com"
olcDbIndex: objectClass eq
olcAccess: to * by users read

5.4. Converting old style slapd.conf(5) file to cn=config format
Before converting to the cn=config format you should make sure that the config backend is properly
configured in your existing config file. While the config backend is always present inside slapd, by default it
is only accessible by its rootDN, and there are no default credentials assigned so unless you explicitly
configure a means to authenticate to it, it will be unusable.
40

OpenLDAP Software 2.4 Administrator's Guide
If you do not already have a database config section, add something like this to the end of
slapd.conf
database config
rootpw VerySecret

Note: Since the config backend can be used to load arbitrary code into the slapd process, it is extremely
important to carefully guard whatever credentials are used to access it. Since simple passwords are vulnerable
to password guessing attacks, it is usually better to omit the rootpw and only use SASL authentication for the
config rootDN.
An existing slapd.conf(5) file can be converted to the new format using slaptest(8) or any of the slap tools:
slaptest -f /usr/local/etc/openldap/slapd.conf -F /usr/local/etc/openldap/slapd.d

Test that you can access entries under cn=config using the default rootdn and the rootpw configured
above:
ldapsearch -x -D cn=config -w VerySecret -b cn=config

You can then discard the old slapd.conf(5) file. Make sure to launch slapd(8) with the -F option to specify the
configuration directory if you are not using the default directory path.
Note: When converting from the slapd.conf format to slapd.d format, any included files will also be integrated
into the resulting configuration database.

OpenLDAP Software 2.4 Administrator's Guide

6. The slapd Configuration File
This chapter describes configuring slapd(8) via the slapd.conf(5) configuration file. slapd.conf(5) has been
deprecated and should only be used if your site requires one of the backends that hasn't yet been updated to
work with the newer slapd-config(5) system. Configuring slapd(8) via slapd-config(5) is described in the
previous chapter.
The slapd.conf(5) file is normally installed in the /usr/local/etc/openldap directory. An alternate
configuration file location can be specified via a command-line option to slapd(8).

6.1. Configuration File Format
The slapd.conf(5) file consists of three types of configuration information: global, backend specific, and
database specific. Global information is specified first, followed by information associated with a particular
backend type, which is then followed by information associated with a particular database instance. Global
directives can be overridden in backend and/or database directives, and backend directives can be overridden
by database directives.
Blank lines and comment lines beginning with a '#' character are ignored. If a line begins with whitespace, it
is considered a continuation of the previous line (even if the previous line is a comment).
The general format of slapd.conf is as follows:
# global configuration directives

# backend definition
backend

# first database definition & config directives
database

# second database definition & config directives
database

# subsequent backend & database definitions & config directives
...

A configuration directive may take arguments. If so, they are separated by whitespace. If an argument
contains whitespace, the argument should be enclosed in double quotes "like this". If an argument
contains a double quote or a backslash character `\', the character should be preceded by a backslash character
`\'.
The distribution contains an example configuration file that will be installed in the
/usr/local/etc/openldap directory. A number of files containing schema definitions (attribute types
and object classes) are also provided in the /usr/local/etc/openldap/schema directory.
43

OpenLDAP Software 2.4 Administrator's Guide

6.2. Configuration File Directives
This section details commonly used configuration directives. For a complete list, see the slapd.conf(5) manual
page. This section separates the configuration file directives into global, backend-specific and data-specific
categories, describing each directive and its default value (if any), and giving an example of its use.

6.2.1. Global Directives
Directives described in this section apply to all backends and databases unless specifically overridden in a
backend or database definition. Arguments that should be replaced by actual text are shown in brackets <>.
6.2.1.1. access to [ by [] [] ]+
This directive grants access (specified by ) to a set of entries and/or attributes (specified by
) by one or more requestors (specified by ). See the Access Control section of this guide for
basic usage.
Note: If no access directives are specified, the default access control policy, access to * by *
read, allows all both authenticated and anonymous users read access.
6.2.1.2. attributetype
This directive defines an attribute type. Please see the Schema Specification chapter for information regarding
how to use this directive.
6.2.1.3. idletimeout
Specify the number of seconds to wait before forcibly closing an idle client connection. An idletimeout of 0,
the default, disables this feature.
6.2.1.4. include
This directive specifies that slapd should read additional configuration information from the given file before
continuing with the next line of the current file. The included file should follow the normal slapd config file
format. The file is commonly used to include files containing schema specifications.
Note: You should be careful when using this directive - there is no small limit on the number of nested
include directives, and no loop detection is done.
6.2.1.5. loglevel
This directive specifies the level at which debugging statements and operation statistics should be syslogged
(currently logged to the syslogd(8) LOG_LOCAL4 facility). You must have configured OpenLDAP
--enable-debug (the default) for this to work (except for the two statistics levels, which are always
enabled). Log levels may be specified as integers or by keyword. Multiple log levels may be used and the
levels are additive. To display what numbers correspond to what kind of debugging, invoke slapd with -d? or
consult the table below. The possible values for are:
Table 6.1: Debugging Levels
44

OpenLDAP Software 2.4 Administrator's Guide
Level Keyword
Description
-1 any
enable all debugging
0
no debugging
1 (0x1 trace)
trace function calls
2 (0x2 packets) debug packet handling
4 (0x4 args)
heavy trace debugging
8 (0x8 conns)
connection management
16 (0x10 BER)
print out packets sent and received
32 (0x20 filter)
search filter processing
64 (0x40 config) configuration processing
128 (0x80 ACL)
access control list processing
256 (0x100 stats) stats log connections/operations/results
512 (0x200 stats2) stats log entries sent
1024 (0x400 shell) print communication with shell backends
2048 (0x800 parse) print entry parsing debugging
16384 (0x4000 sync) syncrepl consumer processing
32768 (0x8000 none) only messages that get logged whatever log level is set
The desired log level can be input as a single integer that combines the (ORed) desired levels, both in decimal
or in hexadecimal notation, as a list of integers (that are ORed internally), or as a list of the names that are
shown between brackets, such that
loglevel
loglevel
loglevel
loglevel
loglevel

129
0x81
128 1
0x80 0x1
acl trace

are equivalent.
Examples:
loglevel -1

This will cause lots and lots of debugging information to be logged.
loglevel conns filter

Just log the connection and search filter processing.
loglevel none

OpenLDAP Software 2.4 Administrator's Guide
Basic stats logging is configured by default. However, if no loglevel is defined, no logging occurs (equivalent
to a 0 level).
6.2.1.6. objectclass
This directive defines an object class. Please see the Schema Specification chapter for information regarding
how to use this directive.
6.2.1.7. referral
This directive specifies the referral to pass back when slapd cannot find a local database to handle a request.
Example:
referral ldap://root.openldap.org

This will refer non-local queries to the global root LDAP server at the OpenLDAP Project. Smart LDAP
clients can re-ask their query at that server, but note that most of these clients are only going to know how to
handle simple LDAP URLs that contain a host part and optionally a distinguished name part.
6.2.1.8. sizelimit
This directive specifies the maximum number of entries to return from a search operation.
Default:
sizelimit 500

See the Limits section of this guide and slapd.conf(5) for more details.
6.2.1.9. timelimit
This directive specifies the maximum number of seconds (in real time) 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.
Default:
timelimit 3600

See the Limits section of this guide and slapd.conf(5) for more details.

6.2.2. General Backend Directives
Directives in this section apply only to the backend in which they are defined. They are supported by every
type of backend. Backend directives apply to all databases instances of the same type and, depending on the
directive, may be overridden by database directives.
6.2.2.1. backend
This directive marks the beginning of a backend declaration. should be one of the supported backend
types listed in Table 6.2.
46

OpenLDAP Software 2.4 Administrator's Guide
Table 6.2: Database Backends
Types
bdb
dnssrv
hdb
ldap
meta
monitor
passwd
perl
shell
sql

Description
Berkeley DB transactional backend
DNS SRV backend
Hierarchical variant of bdb backend
Lightweight Directory Access Protocol (Proxy) backend
Meta Directory backend
Monitor backend
Provides read-only access to passwd(5)
Perl Programmable backend
Shell (extern program) backend
SQL Programmable backend

Example:
backend bdb

This marks the beginning of a new BDB backend definition.

6.2.3. General Database Directives
Directives in this section apply only to the database in which they are defined. They are supported by every
type of database.
6.2.3.1. database
This directive marks the beginning of a database instance declaration. should be one of the
supported backend types listed in Table 6.2.
Example:
database bdb

This marks the beginning of a new BDB database instance declaration.
6.2.3.2. limits [ [...]]
Specify time and size limits based on who initiated an operation.
See the Limits section of this guide and slapd.conf(5) for more details.
6.2.3.3. readonly { on | off }
This directive puts the database into "read-only" mode. Any attempts to modify the database will return an
"unwilling to perform" error.
Default:
readonly off

OpenLDAP Software 2.4 Administrator's Guide
6.2.3.4. rootdn
This directive specifies the DN that is not subject to access control or administrative limit restrictions for
operations on this database. The DN need not refer to an entry in this database or even in the directory. The
DN may refer to a SASL identity.
Entry-based Example:
rootdn "cn=Manager,dc=example,dc=com"

SASL-based Example:
rootdn "uid=root,cn=example.com,cn=digest-md5,cn=auth"

See the SASL Authentication section for information on SASL authentication identities.
6.2.3.5. rootpw
This directive can be used to specifies a password for the DN for the rootdn (when the rootdn is set to a DN
within the database).
Example:
rootpw secret

It is also permissible to provide hash of the password in RFC2307 form. slappasswd(8) may be used to
generate the password hash.
Example:
rootpw {SSHA}ZKKuqbEKJfKSXhUbHG3fG8MDn9j1v4QN

The hash was generated using the command slappasswd -s secret.
6.2.3.6. suffix
This directive specifies the DN suffix of queries that will be passed to this backend database. Multiple suffix
lines can be given, and at least one is required for each database definition.
Example:
suffix "dc=example,dc=com"

Queries with a DN ending in "dc=example,dc=com" will be passed to this backend.
Note: When the backend to pass a query to is selected, slapd looks at the suffix line(s) in each database
definition in the order they appear in the file. Thus, if one database suffix is a prefix of another, it must appear
after it in the config file.

OpenLDAP Software 2.4 Administrator's Guide
6.2.3.7. syncrepl
syncrepl rid=
provider=ldap[s]://[:port]
[type=refreshOnly|refreshAndPersist]
[interval=dd:hh:mm:ss]
[retry=[ <# of retries>]+]
searchbase=
[filter=]
[scope=sub|one|base]
[attrs=]
[attrsonly]
[sizelimit=]
[timelimit=]
[schemachecking=on|off]
[bindmethod=simple|sasl]
[binddn=]
[saslmech=]
[authcid=]
[authzid=]
[credentials=]
[realm=]
[secprops=]
[starttls=yes|critical]
[tls_cert=]
[tls_key=]
[tls_cacert=]
[tls_cacertdir=]
[tls_reqcert=never|allow|try|demand]
[tls_ciphersuite=]
[tls_crlcheck=none|peer|all]
[logbase=]
[logfilter=]
[syncdata=default|accesslog|changelog]

OpenLDAP Software 2.4 Administrator's Guide
Rather than replicating whole entries, the consumer can query logs of data modifications. 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. The syncdata parameter must be set to
either "accesslog" if the log conforms to the slapo-accesslog(5) log format, or "changelog" if the log
conforms to the obsolete changelog format. If the syncdata parameter is omitted or set to "default"
then the log parameters are ignored.
The syncrepl replication mechanism is supported by the bdb, hdb, and mdb backends.
See the LDAP Sync Replication chapter of this guide for more information on how to use this directive.
6.2.3.8. updateref
This directive is only applicable in a slave (or shadow) slapd(8) instance. It specifies the URL to return to
clients which submit update requests upon the replica. If specified multiple times, each URL is provided.
Example:
updateref

ldap://master.example.net

6.2.4. BDB and HDB Database Directives
Directives in this category only apply to both the BDB and the HDB database. That is, they must follow a
"database bdb" or "database hdb" line and come before any subsequent "backend" or "database" line. For a
complete reference of BDB/HDB configuration directives, see slapd-bdb(5).
6.2.4.1. directory
This directive specifies the directory where the BDB files containing the database and associated indices live.
Default:
directory /usr/local/var/openldap-data

6.3. Configuration File Example
The following is an example configuration file, interspersed with explanatory text. It defines two databases to
handle different parts of the X.500 tree; both are BDB database instances. The line numbers shown are
provided for reference only and are not included in the actual file. First, the global configuration section:
1.
2.
3.
4.

# example config file - global configuration section
include /usr/local/etc/schema/core.schema
referral ldap://root.openldap.org
access to * by * read

Line 1 is a comment. Line 2 includes another config file which contains core schema definitions. The
referral directive on line 3 means that queries not local to one of the databases defined below will be
referred to the LDAP server running on the standard port (389) at the host root.openldap.org.
Line 4 is a global access control. It applies to all entries (after any applicable database-specific access
controls).
51

OpenLDAP Software 2.4 Administrator's Guide
The next section of the configuration file defines a BDB backend that will handle queries for things in the
"dc=example,dc=com" portion of the tree. The database is to be replicated to two slave slapds, one on truelies,
the other on judgmentday. Indices are to be maintained for several attributes, and the userPassword
attribute is to be protected from unauthorized access.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.

# BDB definition for the example.com
database bdb
suffix "dc=example,dc=com"
directory /usr/local/var/openldap-data
rootdn "cn=Manager,dc=example,dc=com"
rootpw secret
# indexed attribute definitions
index uid pres,eq
index cn,sn pres,eq,approx,sub
index objectClass eq
# database access control definitions
access to attrs=userPassword
by self write
by anonymous auth
by dn.base="cn=Admin,dc=example,dc=com" write
by * none
access to *
by self write
by dn.base="cn=Admin,dc=example,dc=com" write
by * read

Line 5 is a comment. The start of the database definition is marked by the database keyword on line 6. Line 7
specifies the DN suffix for queries to pass to this database. Line 8 specifies the directory in which the database
files will live.
Lines 9 and 10 identify the database super-user entry and associated password. This entry is not subject to
access control or size or time limit restrictions.
Lines 12 through 14 indicate the indices to maintain for various attributes.
Lines 16 through 24 specify access control for entries in this database. For all applicable entries, the
userPassword attribute is writable by the entry itself and by the "admin" entry. It may be used for
authentication/authorization purposes, but is otherwise not readable. All other attributes are writable by the
entry and the "admin" entry, but may be read by all users (authenticated or not).
The next section of the example configuration file defines another BDB database. This one handles queries
involving the dc=example,dc=net subtree but is managed by the same entity as the first database. Note
that without line 39, the read access would be allowed due to the global access rule at line 4.
33.
34.
35.
36.
37.
38.
39.

# BDB definition for example.net
database bdb
suffix "dc=example,dc=net"
directory /usr/local/var/openldap-data-net
rootdn "cn=Manager,dc=example,dc=com"
index objectClass eq
access to * by users read

7. Running slapd
slapd(8) is designed to be run as a standalone service. This allows the server to take advantage of caching,
manage concurrency issues with underlying databases, and conserve system resources. Running from inetd(8)
is NOT an option.

7.1. Command-Line Options
slapd(8) supports a number of command-line options as detailed in the manual page. This section details a few
commonly used options.
-f

This option specifies an alternate configuration file for slapd. The default is normally
/usr/local/etc/openldap/slapd.conf.
-F

Specifies the slapd configuration directory. The default is /usr/local/etc/openldap/slapd.d.
If both -f and -F are specified, the config file will be read and converted to config directory format and
written to the specified directory. If neither option is specified, slapd will attempt to read the default config
directory before trying to use the default config file. If a valid config directory exists then the default config
file is ignored. All of the slap tools that use the config options observe this same behavior.
-h

This option specifies alternative listener configurations. The default is ldap:/// which implies LDAP over
TCP on all interfaces on the default LDAP port 389. You can specify specific host-port pairs or other protocol
schemes (such as ldaps:// or ldapi://).
URL
Protocol
Transport
ldap:/// LDAP
TCP port 389
ldaps:/// LDAP over SSL TCP port 636
ldapi:/// LDAP
IPC (Unix-domain socket)
For example, -h "ldaps:// ldap://127.0.0.1:666" will create two listeners: one for the
(non-standard) ldaps:// scheme on all interfaces on the default ldaps:// port 636, and one for the
standard ldap:// scheme on the localhost (loopback) interface on port 666. Hosts may be specified
using using hostnames or IPv4 or IPv6 addresses. Port values must be numeric.
For LDAP over IPC, the pathname of the Unix-domain socket can be encoded in the URL. Note that directory
separators must be URL-encoded, like any other characters that are special to URLs. Thus the socket
/usr/local/var/ldapi must be encoded as
ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi

ldapi: is described in detail in Using LDAP Over IPC Mechanisms [Chu-LDAPI]
Note that the ldapi:/// transport is not widely implemented: non-OpenLDAP clients may not be able to use it.
53

OpenLDAP Software 2.4 Administrator's Guide
-n

This option specifies the service name used for logging and other purposes. The default service name is
slapd.
-l

This option specifies the local user for the syslog(8) facility. Values can be LOCAL0, LOCAL1, LOCAL2, ...,
and LOCAL7. The default is LOCAL4. This option may not be supported on all systems.
-u user -g group

These options specify the user and group, respectively, to run as. user can be either a user name or uid.
group can be either a group name or gid.
-r directory

This option specifies a run-time directory. slapd will chroot(2) to this directory after opening listeners but
before reading any configuration files or initializing any backends.
-d | ?

This option sets the slapd debug level to . When level is a `?' character, the various debugging levels
are printed and slapd exits, regardless of any other options you give it. Current debugging levels are
Table 7.1: Debugging Levels
Level Keyword
Description
-1 any
enable all debugging
0
no debugging
1 (0x1 trace)
trace function calls
2 (0x2 packets) debug packet handling
4 (0x4 args)
heavy trace debugging
8 (0x8 conns)
connection management
16 (0x10 BER)
print out packets sent and received
32 (0x20 filter)
search filter processing
64 (0x40 config) configuration processing
128 (0x80 ACL)
access control list processing
256 (0x100 stats) stats log connections/operations/results
512 (0x200 stats2) stats log entries sent
1024 (0x400 shell) print communication with shell backends
2048 (0x800 parse) print entry parsing debugging
16384 (0x4000 sync) syncrepl consumer processing
32768 (0x8000 none) only messages that get logged whatever log level is set
You may enable multiple levels by specifying the debug option once for each desired level. Or, since
debugging levels are additive, you can do the math yourself. That is, if you want to trace function calls and
watch the config file being processed, you could set level to the sum of those two levels (in this case, -d 65).
Or, you can let slapd do the math, (e.g. -d 1 -d 64). Consult for more details.
54

OpenLDAP Software 2.4 Administrator's Guide
Note: slapd must have been compiled with --enable-debug defined for any debugging information
beyond the two stats levels to be available (the default).

7.2. Starting slapd
In general, slapd is run like this:
/usr/local/libexec/slapd [