OpenLDAP Software 2.4 Administrator's Guide 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.................................................................................................................................................18 4.2.2.................................................................................................................................................18 4.2.3.................................................................................................................................................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..................................................................................................30 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.....................................................................................52 6.3. Configuration File Example............................................................................................................55 7. Running slapd................................................................................................................................................55 7.1. Command-Line Options.................................................................................................................57 7.2. Starting slapd..................................................................................................................................57 7.3. Stopping slapd.................................................................................................................................59 8. Access Control...............................................................................................................................................59 8.1. Introduction.....................................................................................................................................59 8.2. Access Control via Static Configuration.........................................................................................60 8.2.1. What to control access to.......................................................................................................61 8.2.2. Who to grant access to...........................................................................................................62 8.2.3. The access to grant................................................................................................................62 8.2.4. Access Control Evaluation....................................................................................................63 8.2.5. Access Control Examples......................................................................................................64 8.3. Access Control via Dynamic Configuration...................................................................................65 8.3.1. What to control access to.......................................................................................................66 8.3.2. Who to grant access to...........................................................................................................67 8.3.3. The access to grant................................................................................................................67 8.3.4. Access Control Evaluation....................................................................................................68 8.3.5. Access Control Examples......................................................................................................69 8.3.6. Access Control Ordering.......................................................................................................70 8.4. Access Control Common Examples...............................................................................................70 8.4.1. Basic ACLs............................................................................................................................71 8.4.2. Matching Anonymous and Authenticated users....................................................................71 8.4.3. Controlling rootdn access......................................................................................................72 8.4.4. Managing access with Groups...............................................................................................73 8.4.5. Granting access to a subset of attributes...............................................................................73 8.4.6. Allowing a user write to all entries below theirs...................................................................73 8.4.7. Allowing entry creation.........................................................................................................75 8.4.8. Tips for using regular expressions in Access Control...........................................................76 8.4.9. Granting and Denying access based on security strength factors (ssf).................................76 8.4.10. When things aren't working as expected.............................................................................77 8.5. Sets - Granting rights based on relationships..................................................................................77 ii OpenLDAP Software 2.4 Administrator's Guide Table of Contents 8. Access Control 8.5.1. Groups of Groups..................................................................................................................78 8.5.2. Group ACLs without DN syntax...........................................................................................79 8.5.3. Following references.............................................................................................................81 9. Limits.............................................................................................................................................................81 9.1. Introduction.....................................................................................................................................81 9.2. Soft and Hard limits........................................................................................................................81 9.3. Global Limits..................................................................................................................................82 9.4. Per-Database Limits........................................................................................................................82 9.4.1. Specify who the limits apply to.............................................................................................82 9.4.2. Specify time limits.................................................................................................................83 9.4.3. Specifying size limits............................................................................................................83 9.4.4. Size limits and Paged Results................................................................................................83 9.5. Example Limit Configurations.......................................................................................................84 9.5.1. Simple Global Limits............................................................................................................84 9.5.2. Global Hard and Soft Limits.................................................................................................84 9.5.3. Giving specific users larger limits.........................................................................................84 9.5.4. Limiting who can do paged searches....................................................................................84 9.6. Further Information.........................................................................................................................85 10. Database Creation and Maintenance Tools..............................................................................................85 10.1. Creating a database over LDAP....................................................................................................86 10.2. Creating a database off-line..........................................................................................................87 10.2.1. Theslapadd program...........................................................................................................88 10.2.2. Theslapindex program........................................................................................................88 10.2.3. Theslapcat program............................................................................................................88 10.3. The LDIF text entry format...........................................................................................................91 11. Backends......................................................................................................................................................91 11.1. Berkeley DB Backends.................................................................................................................91 11.1.1. Overview.............................................................................................................................91 11.1.2. back-bdb/back-hdb Configuration.......................................................................................91 11.1.3. Further Information.............................................................................................................91 11.2. LDAP............................................................................................................................................91 11.2.1. Overview.............................................................................................................................92 11.2.2. back-ldap Configuration......................................................................................................93 11.2.3. Further Information.............................................................................................................93 11.3. LDIF..............................................................................................................................................93 11.3.1. Overview.............................................................................................................................93 11.3.2. back-ldif Configuration.......................................................................................................94 11.3.3. Further Information.............................................................................................................94 11.4. LMDB...........................................................................................................................................94 11.4.1. Overview.............................................................................................................................94 11.4.2. back-mdb Configuration......................................................................................................94 11.4.3. Further Information.............................................................................................................94 11.5. Metadirectory................................................................................................................................95 11.5.1. Overview.............................................................................................................................95 iii OpenLDAP Software 2.4 Administrator's Guide Table of Contents 11. Backends 11.5.2. back-meta Configuration.....................................................................................................95 11.5.3. Further Information.............................................................................................................95 11.6. Monitor.........................................................................................................................................95 11.6.1. Overview.............................................................................................................................95 11.6.2. back-monitor Configuration................................................................................................96 11.6.3. Further Information.............................................................................................................96 11.7. Null...............................................................................................................................................96 11.7.1. Overview.............................................................................................................................97 11.7.2. back-null Configuration......................................................................................................97 11.7.3. Further Information.............................................................................................................97 11.8. Passwd..........................................................................................................................................97 11.8.1. Overview.............................................................................................................................97 11.8.2. back-passwd Configuration.................................................................................................98 11.8.3. Further Information.............................................................................................................98 11.9. Perl/Shell.......................................................................................................................................98 11.9.1. Overview.............................................................................................................................98 11.9.2. back-perl/back-shell Configuration.....................................................................................98 11.9.3. Further Information.............................................................................................................98 11.10. Relay...........................................................................................................................................99 11.10.1. Overview...........................................................................................................................99 11.10.2. back-relay Configuration...................................................................................................99 11.10.3. Further Information...........................................................................................................99 11.11. SQL.............................................................................................................................................99 11.11.1. Overview...........................................................................................................................99 11.11.2. back-sql Configuration....................................................................................................101 11.11.3. Further Information.........................................................................................................103 12. Overlays.....................................................................................................................................................104 12.1. Access Logging...........................................................................................................................104 12.1.1. Overview...........................................................................................................................104 12.1.2. Access Logging Configuration..........................................................................................105 12.1.3. Further Information...........................................................................................................105 12.2. Audit Logging.............................................................................................................................106 12.2.1. Overview...........................................................................................................................106 12.2.2. Audit Logging Configuration............................................................................................107 12.2.3. Further Information...........................................................................................................107 12.3. Chaining......................................................................................................................................107 12.3.1. Overview...........................................................................................................................107 12.3.2. Chaining Configuration.....................................................................................................108 12.3.3. Handling Chaining Errors.................................................................................................108 12.3.4. Read-Back of Chained Modifications...............................................................................108 12.3.5. Further Information...........................................................................................................108 12.4. Constraints..................................................................................................................................109 12.4.1. Overview...........................................................................................................................109 12.4.2. Constraint Configuration...................................................................................................109 12.4.3. Further Information...........................................................................................................109 12.5. Dynamic Directory Services.......................................................................................................109 iv OpenLDAP Software 2.4 Administrator's Guide Table of Contents 12. Overlays 12.5.1. Overview...........................................................................................................................110 12.5.2. Dynamic Directory Service Configuration........................................................................111 12.5.3. Further Information...........................................................................................................111 12.6. Dynamic Groups.........................................................................................................................111 12.6.1. Overview...........................................................................................................................111 12.6.2. Dynamic Group Configuration..........................................................................................111 12.7. Dynamic Lists.............................................................................................................................111 12.7.1. Overview...........................................................................................................................111 12.7.2. Dynamic List Configuration..............................................................................................113 12.7.3. Further Information...........................................................................................................113 12.8. Reverse Group Membership Maintenance..................................................................................113 12.8.1. Overview...........................................................................................................................113 12.8.2. Member Of Configuration.................................................................................................114 12.8.3. Further Information...........................................................................................................115 12.9. The Proxy Cache Engine............................................................................................................115 12.9.1. Overview...........................................................................................................................115 12.9.2. Proxy Cache Configuration...............................................................................................117 12.9.3. Further Information...........................................................................................................117 12.10. Password Policies.....................................................................................................................117 12.10.1. Overview.........................................................................................................................118 12.10.2. Password Policy Configuration.......................................................................................120 12.10.3. Further Information.........................................................................................................120 12.11. Referential Integrity..................................................................................................................120 12.11.1. Overview.........................................................................................................................120 12.11.2. Referential Integrity Configuration.................................................................................121 12.11.3. Further Information.........................................................................................................121 12.12. Return Code..............................................................................................................................121 12.12.1. Overview.........................................................................................................................121 12.12.2. Return Code Configuration.............................................................................................122 12.12.3. Further Information.........................................................................................................122 12.13. Rewrite/Remap.........................................................................................................................122 12.13.1. Overview.........................................................................................................................122 12.13.2. Rewrite/Remap Configuration........................................................................................122 12.13.3. Further Information.........................................................................................................123 12.14. Sync Provider............................................................................................................................123 12.14.1. Overview.........................................................................................................................123 12.14.2. Sync Provider Configuration...........................................................................................123 12.14.3. Further Information.........................................................................................................123 12.15. Translucent Proxy.....................................................................................................................123 12.15.1. Overview.........................................................................................................................124 12.15.2. Translucent Proxy Configuration....................................................................................125 12.15.3. Further Information.........................................................................................................125 12.16. Attribute Uniqueness................................................................................................................126 12.16.1. Overview.........................................................................................................................126 12.16.2. Attribute Uniqueness Configuration...............................................................................127 12.16.3. Further Information.........................................................................................................127 12.17. Value Sorting............................................................................................................................127 v OpenLDAP Software 2.4 Administrator's Guide Table of Contents 12. Overlays 12.17.1. Overview.........................................................................................................................127 12.17.2. Value Sorting Configuration...........................................................................................128 12.17.3. Further Information.........................................................................................................128 12.18. Overlay Stacking.......................................................................................................................128 12.18.1. Overview.........................................................................................................................128 12.18.2. Example Scenarios..........................................................................................................129 13. Schema Specification................................................................................................................................129 13.1. Distributed Schema Files............................................................................................................129 13.2. Extending Schema......................................................................................................................130 13.2.1. Object Identifiers...............................................................................................................131 13.2.2. Naming Elements..............................................................................................................131 13.2.3. Local schema file...............................................................................................................131 13.2.4. Attribute Type Specification.............................................................................................134 13.2.5. Object Class Specification.................................................................................................135 13.2.6. OID Macros.......................................................................................................................137 14. Security Considerations............................................................................................................................137 14.1. Network Security........................................................................................................................137 14.1.1. Selective Listening............................................................................................................137 14.1.2. IP Firewall.........................................................................................................................137 14.1.3. TCP Wrappers...................................................................................................................138 14.2. Data Integrity and Confidentiality Protection.............................................................................138 14.2.1. Security Strength Factors..................................................................................................138 14.3. Authentication Methods..............................................................................................................138 14.3.1. "simple" method................................................................................................................139 14.3.2. SASL method....................................................................................................................139 14.4. Password Storage........................................................................................................................140 14.4.1. SSHA password storage scheme.......................................................................................140 14.4.2. CRYPT password storage scheme....................................................................................140 14.4.3. MD5 password storage scheme.........................................................................................140 14.4.4. SMD5 password storage scheme.......................................................................................141 14.4.5. SHA password storage scheme.........................................................................................141 14.4.6. SASL password storage scheme........................................................................................141 14.5. Pass-Through authentication.......................................................................................................141 14.5.1. Configuring slapd to use an authentication provider.........................................................142 14.5.2. Configuring saslauthd........................................................................................................142 14.5.3. Testing pass-through authentication..................................................................................145 15. Using SASL................................................................................................................................................145 15.1. SASL Security Considerations...................................................................................................146 15.2. SASL Authentication..................................................................................................................146 15.2.1. GSSAPI.............................................................................................................................147 15.2.2. KERBEROS_V4...............................................................................................................148 15.2.3. DIGEST-MD5...................................................................................................................149 15.2.4. EXTERNAL......................................................................................................................149 15.2.5. Mapping Authentication Identities....................................................................................150 vi OpenLDAP Software 2.4 Administrator's Guide Table of Contents 15. Using SASL 15.2.6. Direct Mapping..................................................................................................................151 15.2.7. Search-based mappings.....................................................................................................152 15.3. SASL Proxy Authorization.........................................................................................................153 15.3.1. Uses of Proxy Authorization.............................................................................................153 15.3.2. SASL Authorization Identities..........................................................................................154 15.3.3. Proxy Authorization Rules................................................................................................157 16. Using TLS..................................................................................................................................................157 16.1. TLS Certificates..........................................................................................................................157 16.1.1. Server Certificates.............................................................................................................157 16.1.2. Client Certificates..............................................................................................................157 16.2. TLS Configuration......................................................................................................................157 16.2.1. Server Configuration.........................................................................................................160 16.2.2. Client Configuration..........................................................................................................163 17. Constructing a Distributed Directory Service........................................................................................163 17.1. Subordinate Knowledge Information..........................................................................................163 17.2. Superior Knowledge Information...............................................................................................164 17.3. The ManageDsaIT Control.........................................................................................................165 18. Replication.................................................................................................................................................165 18.1. Replication Technology..............................................................................................................165 18.1.1. LDAP Sync Replication....................................................................................................169 18.2. Deployment Alternatives............................................................................................................169 18.2.1. Delta-syncrepl replication.................................................................................................169 18.2.2. N-Way Multi-Provider Replication...................................................................................170 18.2.3. MirrorMode replication.....................................................................................................171 18.2.4. Syncrepl Proxy Mode........................................................................................................172 18.3. Configuring the different replication types.................................................................................172 18.3.1. Syncrepl.............................................................................................................................174 18.3.2. Delta-syncrepl...................................................................................................................176 18.3.3. N-Way Multi-Provider......................................................................................................178 18.3.4. MirrorMode.......................................................................................................................180 18.3.5. Syncrepl Proxy..................................................................................................................187 19. Maintenance..............................................................................................................................................187 19.1. Directory Backups......................................................................................................................187 19.2. Berkeley DB Logs.......................................................................................................................189 19.3. Checkpointing.............................................................................................................................189 19.4. Migration....................................................................................................................................191 20. Monitoring.................................................................................................................................................191 20.1. Monitor configuration via cn=config(5).....................................................................................191 20.2. Monitor configuration via slapd.conf(5).....................................................................................192 20.3. Accessing Monitoring Information.............................................................................................193 20.4. Monitor Information...................................................................................................................194 20.4.1. Backends...........................................................................................................................195 vii OpenLDAP Software 2.4 Administrator's Guide Table of Contents 20. Monitoring 20.4.2. Connections.......................................................................................................................195 20.4.3. Databases...........................................................................................................................196 20.4.4. Listener..............................................................................................................................196 20.4.5. Log.....................................................................................................................................196 20.4.6. Operations.........................................................................................................................197 20.4.7. Overlays.............................................................................................................................197 20.4.8. SASL.................................................................................................................................197 20.4.9. Statistics.............................................................................................................................197 20.4.10. Threads............................................................................................................................198 20.4.11. Time.................................................................................................................................198 20.4.12. TLS..................................................................................................................................198 20.4.13. Waiters.............................................................................................................................199 21. Tuning........................................................................................................................................................199 21.1. Performance Factors...................................................................................................................199 21.1.1. Memory.............................................................................................................................199 21.1.2. Disks..................................................................................................................................199 21.1.3. Network Topology............................................................................................................199 21.1.4. Directory Layout Design...................................................................................................200 21.1.5. Expected Usage.................................................................................................................200 21.2. Indexes........................................................................................................................................200 21.2.1. Understanding how a search works...................................................................................200 21.2.2. What to index....................................................................................................................200 21.2.3. Presence indexing..............................................................................................................200 21.3. Logging.......................................................................................................................................201 21.3.1. What log level to use.........................................................................................................201 21.3.2. What to watch out for........................................................................................................201 21.3.3. Improving throughput........................................................................................................201 21.4. Caching.......................................................................................................................................202 21.4.1. Berkeley DB Cache...........................................................................................................204 21.4.2. slapd(8) Entry Cache (cachesize)......................................................................................204 21.4.3. Cache (idlcachesize)..........................................................................................................204 21.5. slapd(8) Threads..........................................................................................................................205 22. Troubleshooting........................................................................................................................................205 22.1. User or Software errors?.............................................................................................................205 22.2. Checklist.....................................................................................................................................205 22.3. OpenLDAP Bugs........................................................................................................................206 22.4. 3rd party software error..............................................................................................................206 22.5. How to contact the OpenLDAP Project......................................................................................206 22.6. How to present your problem.....................................................................................................206 22.7. Debugging slapd(8).....................................................................................................................206 22.8. Commercial Support...................................................................................................................207 A. Changes Since Previous Release...............................................................................................................207 A.1. New Guide Sections.....................................................................................................................207 A.2. New Features and Enhancements in 2.4......................................................................................207 viii