OpenLDAP Software 2.4 Administrator's Guide OpenLDAP Software 2.4 Administrator's Guide Table of Contents Table of Contents Preface Copyright .1 Scope of this Document Acknowledgments Amendments About this document Introduction to OpenLDAP Directory Services 1.1 What is a directory service? 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? 1.6 What about X.500? 1.7 What is the difference between LDAPv2 and LDAPv3? .7 1.8 LDAP vs RDBMS 1.9 What is slapd and what can it do? 11 A Quick-Start Guide 15 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 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 .18 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 21 Configuring slapd 21 5.1 Configuration Layout 23 5.2 Configuration Directives .23 5.2.1 cn=config .25 5.2.2 cn=module 25 5.2.3 cn=schema 26 i OpenLDAP Software 2.4 Administrator's Guide Table of Contents Configuring slapd 5.2.4 Backend-specific Directives 27 5.2.5 Database-specific Directives .31 5.2.6 BDB and HDB Database Directives 37 The slapd Configuration File .37 6.1 Configuration File Format 38 6.2 Configuration File Directives .38 6.2.1 Global Directives 40 6.2.2 General Backend Directives 40 6.2.3 General Database Directives .44 6.2.4 BDB and HDB Database Directives 47 Access Control .47 7.1 Introduction 47 7.2 Access Control via Static Configuration .48 7.2.1 What to control access to .49 7.2.2 Who to grant access to 50 7.2.3 The access to grant 50 7.2.4 Access Control Evaluation 50 7.2.5 Access Control Examples 52 7.2.6 Configuration File Example 53 7.3 Access Control via Dynamic Configuration 54 7.3.1 What to control access to .55 7.3.2 Who to grant access to 56 7.3.3 The access to grant 56 7.3.4 Access Control Evaluation 57 7.3.5 Access Control Examples 58 7.3.6 Access Control Ordering .59 7.3.7 Configuration Example .61 7.3.8 Converting from slapd.conf(5) to a cn=config directory format 61 7.4 Access Control Common Examples .61 7.4.1 Basic ACLs 62 7.4.2 Matching Anonymous and Authenticated users 62 7.4.3 Controlling rootdn access 63 7.4.4 Managing access with Groups .64 7.4.5 Granting access to a subset of attributes .64 7.4.6 Allowing a user write to all entries below theirs 64 7.4.7 Allowing entry creation .66 7.4.8 Tips for using regular expressions in Access Control 67 7.4.9 Granting and Denying access based on security strength factors (ssf) .67 7.4.10 When things aren't working as expected 68 7.5 Sets - Granting rights based on relationships 68 7.5.1 Groups of Groups 69 7.5.2 Group ACLs without DN syntax 70 7.5.3 Following references 73 ii OpenLDAP Software 2.4 Administrator's Guide Table of Contents Running slapd 73 8.1 Command-Line Options .74 8.2 Starting slapd 74 8.3 Stopping slapd .77 Database Creation and Maintenance Tools 77 9.1 Creating a database over LDAP 78 9.2 Creating a database off-line 79 9.2.1 The slapadd program 80 9.2.2 The slapindex program 80 9.2.3 The slapcat program 80 9.3 The LDIF text entry format 83 10 Backends 83 10.1 Berkeley DB Backends .83 10.1.1 Overview 83 10.1.2 back-bdb/back-hdb Configuration .83 10.1.3 Further Information 83 10.2 LDAP 83 10.2.1 Overview 83 10.2.2 back-ldap Configuration 84 10.2.3 Further Information 84 10.3 LDIF 84 10.3.1 Overview 85 10.3.2 back-ldif Configuration .86 10.3.3 Further Information 86 10.4 Metadirectory 86 10.4.1 Overview 86 10.4.2 back-meta Configuration 86 10.4.3 Further Information 86 10.5 Monitor .86 10.5.1 Overview 86 10.5.2 back-monitor Configuration 87 10.5.3 Further Information 87 10.6 Null .87 10.6.1 Overview 88 10.6.2 back-null Configuration 88 10.6.3 Further Information 88 10.7 Passwd 88 10.7.1 Overview 89 10.7.2 back-passwd Configuration .89 10.7.3 Further Information 89 10.8 Perl/Shell .89 10.8.1 Overview 90 10.8.2 back-perl/back-shell Configuration 90 10.8.3 Further Information 90 10.9 Relay 90 10.9.1 Overview 90 iii OpenLDAP Software 2.4 Administrator's Guide Table of Contents 10 Backends 10.9.2 back-relay Configuration 90 10.9.3 Further Information 90 10.10 SQL 90 10.10.1 Overview 91 10.10.2 back-sql Configuration 92 10.10.3 Further Information 93 11 Overlays .94 11.1 Access Logging 94 11.1.1 Overview 94 11.1.2 Access Logging Configuration 95 11.1.3 Further Information 95 11.2 Audit Logging .95 11.2.1 Overview 96 11.2.2 Audit Logging Configuration 96 11.2.3 Further Information 96 11.3 Chaining 97 11.3.1 Overview 97 11.3.2 Chaining Configuration .98 11.3.3 Handling Chaining Errors 98 11.3.4 Read-Back of Chained Modifications .98 11.3.5 Further Information 98 11.4 Constraints 98 11.4.1 Overview 98 11.4.2 Constraint Configuration 99 11.4.3 Further Information 99 11.5 Dynamic Directory Services .99 11.5.1 Overview 99 11.5.2 Dynamic Directory Service Configuration 100 11.5.3 Further Information 101 11.6 Dynamic Groups .101 11.6.1 Overview 101 11.6.2 Dynamic Group Configuration 101 11.7 Dynamic Lists 101 11.7.1 Overview 101 11.7.2 Dynamic List Configuration 103 11.7.3 Further Information 103 11.8 Reverse Group Membership Maintenance 103 11.8.1 Overview 103 11.8.2 Member Of Configuration .104 11.8.3 Further Information 104 11.9 The Proxy Cache Engine 104 11.9.1 Overview 105 11.9.2 Proxy Cache Configuration .106 11.9.3 Further Information 106 11.10 Password Policies 106 11.10.1 Overview .107 iv OpenLDAP Software 2.4 Administrator's Guide Table of Contents 11 Overlays 11.10.2 Password Policy Configuration .109 11.10.3 Further Information .109 11.11 Referential Integrity 109 11.11.1 Overview .109 11.11.2 Referential Integrity Configuration .110 11.11.3 Further Information .110 11.12 Return Code 110 11.12.1 Overview .110 11.12.2 Return Code Configuration 111 11.12.3 Further Information .111 11.13 Rewrite/Remap .111 11.13.1 Overview .111 11.13.2 Rewrite/Remap Configuration 112 11.13.3 Further Information .112 11.14 Sync Provider 112 11.14.1 Overview .112 11.14.2 Sync Provider Configuration 112 11.14.3 Further Information .112 11.15 Translucent Proxy 112 11.15.1 Overview .112 11.15.2 Translucent Proxy Configuration 114 11.15.3 Further Information .114 11.16 Attribute Uniqueness 114 11.16.1 Overview .114 11.16.2 Attribute Uniqueness Configuration .114 11.16.3 Further Information .114 11.17 Value Sorting 115 11.17.1 Overview .115 11.17.2 Value Sorting Configuration 116 11.17.3 Further Information .116 11.18 Overlay Stacking .116 11.18.1 Overview .116 11.18.2 Example Scenarios 117 12 Schema Specification 117 12.1 Distributed Schema Files 117 12.2 Extending Schema 118 12.2.1 Object Identifiers .119 12.2.2 Naming Elements 119 12.2.3 Local schema file .119 12.2.4 Attribute Type Specification 122 12.2.5 Object Class Specification .123 12.2.6 OID Macros .125 13 Security Considerations 125 13.1 Network Security 125 13.1.1 Selective Listening 125 v OpenLDAP Software 2.4 Administrator's Guide Table of Contents 13 Security Considerations 13.1.2 IP Firewall .125 13.1.3 TCP Wrappers 126 13.2 Data Integrity and Confidentiality Protection 126 13.2.1 Security Strength Factors 126 13.3 Authentication Methods 126 13.3.1 "simple" method 127 13.3.2 SASL method 127 13.4 Password Storage 128 13.4.1 SSHA password storage scheme .128 13.4.2 CRYPT password storage scheme 128 13.4.3 MD5 password storage scheme .128 13.4.4 SMD5 password storage scheme .129 13.4.5 SHA password storage scheme .129 13.4.6 SASL password storage scheme 129 13.4.7 KERBEROS password storage scheme 129 13.5 Pass-Through authentication .130 13.5.1 Configuring slapd to use an authentication provider .130 13.5.2 Configuring saslauthd 130 13.5.3 Testing pass-through authentication 133 14 Using SASL 133 14.1 SASL Security Considerations 134 14.2 SASL Authentication 134 14.2.1 GSSAPI 135 14.2.2 KERBEROS_V4 .136 14.2.3 DIGEST-MD5 137 14.2.4 Mapping Authentication Identities 138 14.2.5 Direct Mapping 138 14.2.6 Search-based mappings 140 14.3 SASL Proxy Authorization .140 14.3.1 Uses of Proxy Authorization 141 14.3.2 SASL Authorization Identities 141 14.3.3 Proxy Authorization Rules 145 15 Using TLS 145 15.1 TLS Certificates 145 15.1.1 Server Certificates 145 15.1.2 Client Certificates 145 15.2 TLS Configuration 145 15.2.1 Server Configuration .147 15.2.2 Client Configuration 149 16 Constructing a Distributed Directory Service 149 16.1 Subordinate Knowledge Information 149 16.2 Superior Knowledge Information .150 16.3 The ManageDsaIT Control .151 vi OpenLDAP Software 2.4 Administrator's Guide Table of Contents 17 Replication .151 17.1 Push Based 151 17.1.1 Replacing Slurpd .156 17.2 Pull Based 156 17.2.1 LDAP Sync Replication 160 17.2.2 Delta-syncrepl replication .160 17.3 Mixture of both Pull and Push based 160 17.3.1 N-Way Multi-Master replication .161 17.3.2 MirrorMode replication 162 17.4 Configuring the different replication types .162 17.4.1 Syncrepl 164 17.4.2 Delta-syncrepl 165 17.4.3 N-Way Multi-Master .167 17.4.4 MirrorMode .171 18 Maintenance 171 18.1 Directory Backups 171 18.2 Berkeley DB Logs .173 18.3 Checkpointing 173 18.4 Migration 175 19 Monitoring .175 19.1 Monitor configuration via cn=config(5) 175 19.2 Monitor configuration via slapd.conf(5) 176 19.3 Accessing Monitoring Information 177 19.4 Monitor Information 178 19.4.1 Backends 179 19.4.2 Connections .179 19.4.3 Databases 180 19.4.4 Listener 180 19.4.5 Log 180 19.4.6 Operations .181 19.4.7 Overlays 181 19.4.8 SASL .181 19.4.9 Statistics 181 19.4.10 Threads 182 19.4.11 Time .182 19.4.12 TLS 182 19.4.13 Waiters 183 20 Tuning 183 20.1 Performance Factors 183 20.1.1 Memory 183 20.1.2 Disks 183 20.1.3 Network Topology 183 20.1.4 Directory Layout Design 183 20.1.5 Expected Usage .184 20.2 Indexes 184 vii OpenLDAP Software 2.4 Administrator's Guide Table of Contents 20 Tuning 20.2.1 Understanding how a search works 184 20.2.2 What to index 184 20.2.3 Presence indexing 184 20.3 Logging .184 20.3.1 What log level to use .185 20.3.2 What to watch out for 185 20.3.3 Improving throughput 185 20.4 Caching .185 20.4.1 Berkeley DB Cache 187 20.4.2 slapd(8) Entry Cache (cachesize) 188 20.4.3 IDL Cache (idlcachesize) 188 20.4.4 slapd(8) Threads 189 21 Troubleshooting 189 21.1 User or Software errors? 189 21.2 Checklist 189 21.3 OpenLDAP Bugs 190 21.4 3rd party software error 190 21.5 How to contact the OpenLDAP Project 190 21.6 How to present your problem 190 21.7 Debugging slapd(8) 190 21.8 Commercial Support 191 A Changes Since Previous Release .191 A.1 New Guide Sections 191 A.2 New Features and Enhancements in 2.4 191 A.2.1 Better cn=config functionality 192 A.2.2 Better cn=schema functionality 192 A.2.3 More sophisticated Syncrepl configurations 192 A.2.4 N-Way Multimaster Replication 192 A.2.5 Replicating slapd Configuration (syncrepl and cn=config) .192 A.2.6 Push-Mode Replication 193 A.2.7 More extensive TLS configuration control 193 A.2.8 Performance enhancements 193 A.2.9 New overlays 193 A.2.10 New features in existing Overlays 194 A.2.11 New features in slapd .194 A.2.12 New features in libldap 194 A.2.13 New clients, tools and tool enhancements 194 A.2.14 New build options 194 A.3 Obsolete Features Removed From 2.4 .194 A.3.1 Slurpd .194 A.3.2 back-ldbm 195 B Upgrading from 2.3.x .195 B.1 Monitor Backend 195 B.2 cn=config olc* attributes 195 viii ... indexing system allows OpenLDAP to provide greater performance and scalability without loss of reliability OpenLDAP uses Berkeley DB OpenLDAP Software 2.4 Administrator's Guide concurrent / transactional... http://www .OpenLDAP. org/doc/ http://www .OpenLDAP. org/faq/ http://www .OpenLDAP. org/its/ http://www .OpenLDAP. org/lists/ http://www .OpenLDAP. org/software/man.cgi http://www .OpenLDAP. org/software/ http://www .OpenLDAP. org/support/... SLAPD and SLURPD Administrators Guide OpenLDAP Software 2.4 Administrator's Guide Amendments Suggested enhancements and corrections to this document should be submitted using the OpenLDAP Issue