Page 1
Directory Server 8.0
Administration Guide
A Guide for Using and Maintaining Red Hat Directory Server
Ella Deon Lackey
Publication date: January 15, 2008, updated on February 11, 2010
Page 2
Administration Guide
Directory Server 8.0 Administration Guide
A Guide for Using and Maintaining Red Hat Directory Server
Edition 8.0.19
Author Ella Deon Lackey
Copyright © 2008, 2009 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons
Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available
at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this
document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,
Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity
Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
All other trademarks are the property of their respective owners.
1801 Varsity Drive
Raleigh, NC 27606-2072 USA
Phone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588
Research Triangle Park, NC 27709 USA
Page 3
iii
Preface xiii
1. Directory Server Overview ............................................................................................. xiii
2. Examples and Formatting .............................................................................................. xiv
3. Additional Reading ........................................................................................................ xv
4. Giving Feedback ........................................................................................................... xv
5. Document History ......................................................................................................... xvi
1. General Red Hat Directory Server Usage 1
1.1. Directory Server File Locations ..................................................................................... 1
1.2. LDAP Tool Locations .................................................................................................... 3
1.3. Starting and Stopping Servers ...................................................................................... 4
1.3.1. Starting and Stopping Directory Server from the Console ..................................... 4
1.3.2. Starting and Stopping Directory Server from the Command Line ........................... 5
1.3.3. Starting and Stopping Administration Server ........................................................ 5
1.4. Starting the Directory Server Console ............................................................................ 6
1.4.1. Logging into Directory Server ............................................................................. 6
1.4.2. Changing Login Identity ..................................................................................... 7
1.4.3. Viewing the Current Console Bind DN ................................................................ 8
1.5. Changing Directory Server Port Numbers ...................................................................... 8
1.6. Creating a New Directory Server Instance ..................................................................... 9
1.7. Configuring the Directory Manager .............................................................................. 10
2. Creating Directory Entries 13
2.1. Managing Entries from the Directory Console ............................................................... 13
2.1.1. Creating a Root Entry ...................................................................................... 13
2.1.2. Creating Directory Entries ................................................................................ 14
2.1.3. Modifying Directory Entries ............................................................................... 16
2.1.4. Deleting Directory Entries ................................................................................. 20
2.2. Managing Entries from the Command-Line .................................................................. 20
2.2.1. Providing Input from the Command-Line ........................................................... 21
2.2.2. Creating a Root Entry from the Command-Line ................................................. 22
2.2.3. Adding Entries Using LDIF ............................................................................... 22
2.2.4. Adding and Modifying Entries Using ldapmodify ................................................. 22
2.2.5. Deleting Entries Using ldapdelete ..................................................................... 25
2.2.6. Using Special Characters ................................................................................. 26
2.3. Tracking Modifications to Directory Entries ................................................................... 26
2.4. LDIF Update Statements ............................................................................................ 27
2.4.1. Adding an Entry Using LDIF ............................................................................. 28
2.4.2. Renaming an Entry Using LDIF ........................................................................ 29
2.4.3. Modifying an Entry Using LDIF ......................................................................... 30
2.4.4. Deleting an Entry Using LDIF ........................................................................... 34
2.4.5. Modifying an Entry in an Internationalized Directory ........................................... 34
2.5. Maintaining Referential Integrity .................................................................................. 34
2.5.1. How Referential Integrity Works ........................................................................ 35
2.5.2. Using Referential Integrity with Replication ........................................................ 35
2.5.3. Enabling/Disabling Referential Integrity ............................................................. 36
2.5.4. Modifying the Update Interval ........................................................................... 36
2.5.5. Modifying the Attribute List ............................................................................... 37
3. Configuring Directory Databases 39
3.1. Creating and Maintaining Suffixes ............................................................................... 39
3.1.1. Creating Suffixes ............................................................................................. 39
3.1.2. Maintaining Suffixes ......................................................................................... 44
Page 4
Administration Guide
iv
3.2. Creating and Maintaining Databases ........................................................................... 46
3.2.1. Creating Databases ......................................................................................... 46
3.2.2. Maintaining Directory Databases ...................................................................... 50
3.2.3. Database Encryption ........................................................................................ 54
3.3. Creating and Maintaining Database Links .................................................................... 57
3.3.1. Configuring the Chaining Policy ........................................................................ 57
3.3.2. Creating a New Database Link ......................................................................... 62
3.3.3. Chaining Using SSL ........................................................................................ 71
3.3.4. Maintaining Database Links .............................................................................. 71
3.3.5. Database Links and Access Control Evaluation ................................................. 72
3.3.6. Advanced Feature: Tuning Database Link Performance ...................................... 73
3.3.7. Advanced Feature: Configuring Cascading Chaining .......................................... 77
3.4. Using Referrals .......................................................................................................... 88
3.4.1. Starting the Server in Referral Mode ................................................................. 88
3.4.2. Setting Default Referrals .................................................................................. 89
3.4.3. Creating Smart Referrals .................................................................................. 90
3.4.4. Creating Suffix Referrals .................................................................................. 91
4. Populating Directory Databases 95
4.1. Importing Data ........................................................................................................... 95
4.1.1. Importing Entries with Large Attributes .............................................................. 95
4.1.2. Importing a Database from the Console ............................................................ 95
4.1.3. Initializing a Database from the Console ........................................................... 97
4.1.4. Importing from the Command-Line .................................................................... 97
4.2. Exporting Data ......................................................................................................... 100
4.2.1. Exporting Directory Data to LDIF Using the Console ........................................ 102
4.2.2. Exporting a Single Database to LDIF Using the Console ................................... 102
4.2.3. Exporting to LDIF from the Command-Line ...................................................... 103
4.3. Backing up and Restoring Data ................................................................................. 104
4.3.1. Backing up All Databases .............................................................................. 105
4.3.2. Backing up the dse.ldif Configuration File ........................................................ 106
4.3.3. Restoring All Databases ................................................................................. 106
4.3.4. Restoring a Single Database .......................................................................... 108
4.3.5. Restoring Databases That Include Replicated Entries ....................................... 108
4.3.6. Restoring the dse.ldif Configuration File .......................................................... 109
5. Managing Entries with Roles, Classes of Service, and Views 111
5.1. Using Roles ............................................................................................................. 111
5.1.1. About Roles .................................................................................................. 111
5.1.2. Managing Roles Using the Console ................................................................ 113
5.1.3. Managing Roles Using the Command-Line ...................................................... 117
5.1.4. Using Roles Securely ..................................................................................... 120
5.2. Assigning Classes of Service .................................................................................... 121
5.2.1. About CoS .................................................................................................... 121
5.2.2. Managing CoS Using the Console .................................................................. 126
5.2.3. Managing CoS from the Command-Line .......................................................... 129
5.2.4. Creating Role-Based Attributes ....................................................................... 136
5.2.5. Access Control and CoS ................................................................................ 137
5.3. Using Views ............................................................................................................. 137
5.3.1. Creating Views in the Console ........................................................................ 138
5.3.2. Deleting Views from the Directory Server Console ........................................... 139
5.3.3. Creating Views from the Command Line ......................................................... 139
Page 5
v
5.3.4. Deleting Views from the Command Line .......................................................... 139
5.4. Using Groups ........................................................................................................... 140
5.4.1. Managing Static Groups ................................................................................. 140
5.4.2. Managing Dynamic Groups ............................................................................ 141
6. Managing Access Control 143
6.1. Access Control Principles .......................................................................................... 143
6.1.1. ACI Structure ................................................................................................. 143
6.1.2. ACI Placement .............................................................................................. 143
6.1.3. ACI Evaluation ............................................................................................... 144
6.1.4. ACI Limitations .............................................................................................. 144
6.2. Default ACIs ............................................................................................................. 145
6.3. Creating ACIs Manually ............................................................................................ 146
6.3.1. The ACI Syntax ............................................................................................. 146
6.3.2. Defining Targets ............................................................................................. 147
6.3.3. Defining Permissions ..................................................................................... 152
6.4. Bind Rules ............................................................................................................... 156
6.4.1. Bind Rule Syntax ........................................................................................... 156
6.4.2. Defining User Access - userdn Keyword .......................................................... 157
6.4.3. Defining Group Access - groupdn Keyword ..................................................... 160
6.4.4. Defining Role Access - roledn Keyword ........................................................... 161
6.4.5. Defining Access Based on Value Matching ...................................................... 161
6.4.6. Defining Access from a Specific IP Address .................................................... 166
6.4.7. Defining Access from a Specific Domain ......................................................... 167
6.4.8. Defining Access at a Specific Time of Day or Day of Week ............................... 167
6.4.9. Defining Access Based on Authentication Method ............................................ 169
6.4.10. Using Boolean Bind Rules ............................................................................ 170
6.5. Creating ACIs from the Console ................................................................................ 170
6.5.1. Displaying the Access Control Editor ............................................................... 171
6.5.2. Creating a New ACI ....................................................................................... 173
6.5.3. Editing an ACI ............................................................................................... 178
6.5.4. Deleting an ACI ............................................................................................. 179
6.6. Viewing ACIs ............................................................................................................ 179
6.7. Get Effective Rights Control ...................................................................................... 179
6.7.1. Using Get Effective Rights from the Command-Line ......................................... 181
6.7.2. Using Get Effective Rights from the Console ................................................... 183
6.7.3. Get Effective Rights Return Codes .................................................................. 183
6.8. Logging Access Control Information ........................................................................... 184
6.9. Access Control Usage Examples ............................................................................... 184
6.9.1. Granting Anonymous Access .......................................................................... 185
6.9.2. Granting Write Access to Personal Entries ...................................................... 187
6.9.3. Restricting Access to Key Roles ..................................................................... 189
6.9.4. Granting a Group Full Access to a Suffix ......................................................... 191
6.9.5. Granting Rights to Add and Delete Group Entries ............................................ 192
6.9.6. Granting Conditional Access to a Group or Role .............................................. 194
6.9.7. Denying Access ............................................................................................. 195
6.9.8. Setting a Target Using Filtering ....................................................................... 197
6.9.9. Allowing Users to Add or Remove Themselves from a Group ............................ 198
6.9.10. Defining Permissions for DNs That Contain a Comma .................................... 199
6.9.11. Proxied Authorization ACI Example ............................................................... 199
6.10. Advanced Access Control: Using Macro ACIs ........................................................... 200
6.10.1. Macro ACI Example ..................................................................................... 200
Page 6
Administration Guide
vi
6.10.2. Macro ACI Syntax ........................................................................................ 202
6.11. Access Control and Replication ............................................................................... 205
6.12. Compatibility with Earlier Releases .......................................................................... 205
7. Managing User Accounts and Passwords 207
7.1. Managing the Password Policy .................................................................................. 207
7.1.1. Configuring the Password Policy ..................................................................... 207
7.1.2. Setting User Passwords ................................................................................. 217
7.1.3. Password Change Extended Operation ........................................................... 217
7.1.4. Configuring the Account Lockout Policy ........................................................... 219
7.1.5. Managing the Password Policy in a Replicated Environment ............................. 221
7.1.6. Synchronizing Passwords ............................................................................... 222
7.2. Inactivating Users and Roles ..................................................................................... 222
7.2.1. Inactivating User and Roles Using the Console ................................................ 223
7.2.2. Inactivating User and Roles Using the Command-Line ..................................... 223
7.2.3. Activating User and Roles Using the Console .................................................. 224
7.2.4. Activating User and Roles Using the Command-Line ........................................ 224
7.3. Setting Resource Limits Based on the Bind DN .......................................................... 224
7.3.1. Setting Resource Limits Using the Console ..................................................... 225
7.3.2. Setting Resource Limits Using the Command-Line ........................................... 225
8. Managing Replication 227
8.1. Replication Overview ................................................................................................ 227
8.1.1. What Directory Units Are Replicated ............................................................... 227
8.1.2. Read-Write and Read-Only Replicas ............................................................... 227
8.1.3. Suppliers and Consumers .............................................................................. 227
8.1.4. Changelog ..................................................................................................... 228
8.1.5. Replication Identity ......................................................................................... 228
8.1.6. Replication Agreement ................................................................................... 229
8.1.7. Replicating Attributes with Fractional Replication .............................................. 229
8.1.8. Compatibility with Earlier Versions of Directory Server ...................................... 229
8.2. Replication Scenarios ............................................................................................... 230
8.2.1. Single-Master Replication ............................................................................... 230
8.2.2. Multi-Master Replication ................................................................................. 231
8.2.3. Cascading Replication .................................................................................... 233
8.3. Creating the Supplier Bind DN Entry .......................................................................... 235
8.4. Configuring Single-Master Replication ........................................................................ 236
8.4.1. Configuring the Read-Write Replica on the Supplier Server ............................... 236
8.4.2. Configuring the Read-Only Replica on the Consumer ....................................... 238
8.4.3. Create the Replication Agreement .................................................................. 240
8.5. Configuring Multi-Master Replication .......................................................................... 246
8.5.1. Configuring the Read-Write Replicas on the Supplier Servers ........................... 246
8.5.2. Configuring the Read-Only Replicas on the Consumer Servers ......................... 249
8.5.3. Setting up the Replication Agreements ............................................................ 251
8.5.4. Preventing Monopolization of the Consumer in Multi-Master Replication ............. 257
8.6. Configuring Cascading Replication ............................................................................ 258
8.6.1. Configuring the Read-Write Replica on the Supplier Server ............................... 258
8.6.2. Configuring the Read-Only Replica on the Consumer Server ............................ 260
8.6.3. Configuring the Read-Only Replica on the Hub ................................................ 262
8.6.4. Setting up the Replication Agreements ............................................................ 265
8.7. Configuring Replication from the Command Line ........................................................ 271
8.7.1. Configuring Suppliers from the Command Line ................................................ 271
Page 7
vii
8.7.2. Configuring Consumers from the Command Line ............................................. 274
8.7.3. Configuring Hubs from the Command Line ...................................................... 275
8.7.4. Configuring Replication Agreements from the Command Line ........................... 276
8.7.5. Initializing Consumers Online from the Command Line ..................................... 279
8.8. Making a Replica Updatable ..................................................................................... 280
8.9. Deleting the Changelog ............................................................................................ 280
8.9.1. Removing the Changelog ............................................................................... 280
8.9.2. Moving the Changelog to a New Location ....................................................... 281
8.10. Initializing Consumers ............................................................................................. 281
8.10.1. When to Initialize a Consumer ...................................................................... 282
8.10.2. Online Consumer Initialization Using the Console ........................................... 282
8.10.3. Initializing Consumers Online Using the Command Line ................................. 283
8.10.4. Manual Consumer Initialization Using the Command Line ............................... 283
8.10.5. Filesystem Replica Initialization ..................................................................... 284
8.11. Forcing Replication Updates .................................................................................... 286
8.11.1. Forcing Replication Updates from the Console ............................................... 286
8.11.2. Forcing Replication Updates from the Command-Line ..................................... 287
8.12. Replicating Account Lockout Attributes ..................................................................... 288
8.12.1. Configuring Directory Server to Replicate Password Policy Attributes ............... 288
8.12.2. Configuring Fractional Replication for Password Policy Attributes .................... 289
8.13. Replication over SSL .............................................................................................. 289
8.14. Replicating o=NetscapeRoot for Administration Server Failover ................................. 290
8.15. Replication with Earlier Releases ............................................................................. 291
8.16. Using the Retro Changelog Plug-in .......................................................................... 292
8.16.1. Enabling the Retro Changelog Plug-in ........................................................... 293
8.16.2. Trimming the Retro Changelog ..................................................................... 294
8.16.3. Searching and Modifying the Retro Changelog ............................................... 294
8.16.4. Retro Changelog and the Access Control Policy ............................................ 294
8.17. Monitoring Replication Status .................................................................................. 295
8.17.1. Monitoring Replication Status from the Directory Server Console ..................... 295
8.17.2. Monitoring Replication Status from Administration Express ............................. 296
8.18. Solving Common Replication Conflicts ..................................................................... 298
8.18.1. Solving Naming Conflicts .............................................................................. 298
8.18.2. Solving Orphan Entry Conflicts ..................................................................... 300
8.18.3. Solving Potential Interoperability Problems .................................................... 301
8.19. Troubleshooting Replication-Related Problems ......................................................... 301
9. Extending the Directory Schema 307
9.1. Overview of Extending Schema ................................................................................. 307
9.2. Managing Attributes .................................................................................................. 307
9.2.1. Viewing Attributes .......................................................................................... 307
9.2.2. Creating Attributes ......................................................................................... 309
9.2.3. Editing Attributes ............................................................................................ 309
9.2.4. Deleting Attributes .......................................................................................... 310
9.3. Managing Object Classes ......................................................................................... 310
9.3.1. Viewing Object Classes .................................................................................. 310
9.3.2. Creating Object Classes ................................................................................. 312
9.3.3. Editing Object Classes ................................................................................... 313
9.3.4. Deleting Object Classes ................................................................................. 314
9.4. Turning Schema Checking On and Off ....................................................................... 314
10. Managing Indexes 317
Page 8
Administration Guide
viii
10.1. About Indexes ........................................................................................................ 317
10.1.1. About Index Types ....................................................................................... 317
10.1.2. About Default, System, and Standard Indexes ............................................... 318
10.1.3. Overview of the Searching Algorithm ............................................................. 321
10.1.4. Approximate Searches ................................................................................. 322
10.1.5. Balancing the Benefits of Indexing ................................................................ 322
10.2. Creating Indexes .................................................................................................... 324
10.2.1. Creating Indexes from the Server Console .................................................... 324
10.2.2. Creating Indexes from the Command-Line ..................................................... 325
10.2.3. Creating Browsing Indexes from the Server Console ...................................... 328
10.2.4. Creating Browsing Indexes from the Command-Line ...................................... 328
10.3. Deleting Indexes ..................................................................................................... 331
10.3.1. Deleting Indexes from the Server Console ..................................................... 332
10.3.2. Deleting Indexes from the Command-Line ..................................................... 332
10.3.3. Deleting Browsing Indexes from the Server Console ....................................... 334
10.3.4. Deleting Browsing Indexes from the Command-Line ....................................... 334
10.4. Managing Indexes .................................................................................................. 336
10.4.1. Indexing Performance .................................................................................. 337
10.4.2. Search Performance .................................................................................... 337
10.4.3. Backwards Compatibility and Migration .......................................................... 338
10.5. Attribute Name Quick Reference Table ..................................................................... 339
11. Managing SSL 341
11.1. Introduction to TLS/SSL in the Directory Server ........................................................ 341
11.1.1. Enabling SSL: Summary of Steps ................................................................. 341
11.1.2. Command-Line Functions for Start TLS ......................................................... 342
11.2. Obtaining and Installing Server Certificates ............................................................... 343
11.2.1. Step 1: Generate a Certificate Request ......................................................... 344
11.2.2. Step 2: Send the Certificate Request ............................................................. 347
11.2.3. Step 3: Install the Certificate ......................................................................... 348
11.2.4. Step 4: Trust the Certificate Authority ............................................................ 349
11.2.5. Step 5: Confirm That The New Certificates Are Installed ................................. 349
11.3. Using certutil .......................................................................................................... 350
11.3.1. Creating Directory Server Certificates through the Command Line ................... 350
11.3.2. certutil Usage ............................................................................................... 352
11.4. Starting the Server with TLS/SSL Enabled ............................................................... 353
11.4.1. Enabling TLS/SSL Only in the Directory Server .............................................. 353
11.4.2. Enabling TLS/SSL in the Directory Server, Administration Server, and Console
................................................................................................................................ 355
11.4.3. Creating a Password File for the Directory Server .......................................... 357
11.4.4. Creating a Password File for the Administration Server ................................... 357
11.5. Setting Security Preferences .................................................................................... 358
11.5.1. Available Ciphers ......................................................................................... 358
11.5.2. Selecting the Encryption Cipher .................................................................... 360
11.6. Using Certificate-Based Authentication ..................................................................... 360
11.6.1. Setting up Certificate-Based Authentication .................................................... 361
11.6.2. Allowing/Requiring Client Authentication ........................................................ 362
11.7. Configuring LDAP Clients to Use SSL ...................................................................... 362
12. Managing SASL 365
12.1. Authentication Mechanisms ..................................................................................... 365
12.2. SASL Identity Mapping ............................................................................................ 366
Page 9
ix
12.3. Configuring SASL Identity Mapping from the Console ............................................... 367
12.4. Configuring SASL Identity Mapping from the Command-Line ..................................... 369
12.5. Configuring Kerberos .............................................................................................. 369
12.5.1. Realms ........................................................................................................ 369
12.5.2. Configuring the KDC Server ......................................................................... 370
12.5.3. Example: Configuring an Example KDC Server .............................................. 371
12.5.4. Configuring SASL Authentication at Directory Server Startup ........................... 371
13. Monitoring Server and Database Activity 373
13.1. Viewing and Configuring Log Files ........................................................................... 373
13.1.1. Defining a Log File Rotation Policy ............................................................... 373
13.1.2. Defining a Log File Deletion Policy ................................................................ 374
13.1.3. Access Log .................................................................................................. 375
13.1.4. Error Log ..................................................................................................... 376
13.1.5. Audit Log ..................................................................................................... 378
13.2. Manual Log File Rotation ........................................................................................ 379
13.3. Monitoring Server Activity ........................................................................................ 379
13.3.1. Monitoring the Server from the Directory Server Console ................................ 379
13.3.2. Monitoring the Directory Server from the Command Line ................................ 383
13.4. Monitoring Database Activity ................................................................................... 385
13.4.1. Monitoring Database Activity from the Directory Server Console ...................... 385
13.4.2. Monitoring Databases from the Command Line .............................................. 388
13.5. Monitoring Database Link Activity ............................................................................ 390
14. Monitoring Directory Server Using SNMP 393
14.1. About SNMP .......................................................................................................... 393
14.2. Configuring the Master Agent .................................................................................. 394
14.3. Configuring the Subagent ........................................................................................ 394
14.3.1. Subagent Configuration File .......................................................................... 394
14.3.2. Starting the Subagent .................................................................................. 395
14.3.3. Testing the Subagent ................................................................................... 395
14.4. Configuring SNMP Traps ......................................................................................... 396
14.5. Configuring the Directory Server for SNMP .............................................................. 396
14.6. Using the Management Information Base ................................................................. 397
14.6.1. Operations Table .......................................................................................... 397
14.6.2. Entries Table ................................................................................................ 399
14.6.3. Entity Table .................................................................................................. 399
14.6.4. Interaction Table .......................................................................................... 400
15. Tuning Directory Server Performance 403
15.1. Tuning Server Performance ..................................................................................... 403
15.2. Tuning Database Performance ................................................................................ 404
15.2.1. Optimizing Search Performance .................................................................... 404
15.2.2. Tuning Transaction Logging .......................................................................... 405
15.2.3. Changing the Location of the Database Transaction Log ................................. 406
15.2.4. Changing the Database Checkpoint Interval .................................................. 406
15.2.5. Disabling Durable Transactions ..................................................................... 407
15.2.6. Specifying Transaction Batching .................................................................... 407
15.3. Miscellaneous Tuning Tips ...................................................................................... 408
15.3.1. Avoid Creating Entries Under the cn=config Entry in the dse.ldif File ................ 408
16. Administering Directory Server Plug-ins 409
16.1. Server Plug-in Functionality Reference ..................................................................... 409
Page 10
Administration Guide
x
16.1.1. 7-Bit Check Plug-in ...................................................................................... 409
16.1.2. ACL Plug-in ................................................................................................. 409
16.1.3. ACL Preoperation Plug-in ............................................................................. 410
16.1.4. Binary Syntax Plug-in ................................................................................... 410
16.1.5. Boolean Syntax Plug-in ................................................................................ 410
16.1.6. Case Exact String Syntax Plug-in ................................................................. 411
16.1.7. Case Ignore String Syntax Plug-in ................................................................ 411
16.1.8. Chaining Database Plug-in ........................................................................... 412
16.1.9. Class of Service Plug-in ............................................................................... 412
16.1.10. Country String Syntax Plug-in ..................................................................... 412
16.1.11. Distinguished Name Syntax Plug-in ............................................................. 413
16.1.12. Generalized Time Syntax Plug-in ................................................................ 413
16.1.13. Integer Syntax Plug-in ................................................................................ 414
16.1.14. Internationalization Plug-in .......................................................................... 414
16.1.15. ldbm Database Plug-in ............................................................................... 415
16.1.16. Legacy Replication Plug-in .......................................................................... 415
16.1.17. Multi-Master Replication Plug-in .................................................................. 416
16.1.18. Octet String Syntax Plug-in ......................................................................... 416
16.1.19. CLEAR Password Storage Plug-in .............................................................. 416
16.1.20. CRYPT Password Storage Plug-in .............................................................. 417
16.1.21. NS-MTA-MD5 Password Storage Plug-in ..................................................... 417
16.1.22. SHA Password Storage Plug-in ................................................................... 418
16.1.23. SSHA Password Storage Plug-in ................................................................ 419
16.1.24. Postal Address String Syntax Plug-in .......................................................... 419
16.1.25. PTA Plug-in ............................................................................................... 419
16.1.26. Referential Integrity Postoperation Plug-in .................................................... 420
16.1.27. Retro Changelog Plug-in ............................................................................ 421
16.1.28. Roles Plug-in ............................................................................................. 422
16.1.29. Space Insensitive String Syntax Plug-in ....................................................... 422
16.1.30. State Change Plug-in ................................................................................. 423
16.1.31. Telephone Syntax Plug-in ........................................................................... 423
16.1.32. UID Uniqueness Plug-in ............................................................................. 423
16.1.33. URI Plug-in ................................................................................................ 424
16.2. Enabling and Disabling Plug-ins .............................................................................. 425
17. Using the Pass-through Authentication Plug-in 427
17.1. How Directory Server Uses PTA .............................................................................. 427
17.2. PTA Plug-in Syntax ................................................................................................. 428
17.3. Configuring the PTA Plug-in .................................................................................... 430
17.3.1. Turning the Plug-in On or Off ........................................................................ 431
17.3.2. Configuring the Servers to Use a Secure Connection ..................................... 431
17.3.3. Specifying the Authenticating Directory Server ............................................... 431
17.3.4. Specifying the Pass-through Subtree ............................................................. 432
17.3.5. Configuring the Optional Parameters ............................................................. 433
17.4. PTA Plug-in Syntax Examples ................................................................................. 433
17.4.1. Specifying One Authenticating Directory Server and One Subtree .................... 434
17.4.2. Specifying Multiple Authenticating Directory Servers ....................................... 434
17.4.3. Specifying One Authenticating Directory Server and Multiple Subtrees ............. 434
17.4.4. Using Non-Default Parameter Values ............................................................ 435
17.4.5. Specifying Different Optional Parameters and Subtrees for Different
Authenticating Directory Servers .............................................................................. 435
Page 11
xi
18. Using the Attribute Uniqueness Plug-in 437
18.1. Overview of the Attribute Uniqueness Plug-in ........................................................... 437
18.2. Attribute Uniqueness Plug-in Syntax ........................................................................ 438
18.3. Creating an Instance of the Attribute Uniqueness Plug-in .......................................... 439
18.4. Configuring Attribute Uniqueness Plug-ins ................................................................ 440
18.4.1. Viewing Plug-in Configuration Information ...................................................... 440
18.4.2. Configuring Attribute Uniqueness Plug-ins from the Directory Server Console ... 441
18.4.3. Configuring Attribute Uniqueness Plug-ins from the Command-Line ................. 441
18.5. Attribute Uniqueness Plug-in Syntax Examples ......................................................... 443
18.5.1. Specifying One Attribute and One Subtree .................................................... 444
18.5.2. Specifying One Attribute and Multiple Subtrees .............................................. 444
18.6. Replication and the Attribute Uniqueness Plug-in ...................................................... 444
18.6.1. Simple Replication Scenario ......................................................................... 445
18.6.2. Multi-Master Replication Scenario ................................................................. 445
19. Synchronizing Red Hat Directory Server with Microsoft Active Directory 447
19.1. About Windows Sync .............................................................................................. 447
19.2. Configuring Windows Sync ...................................................................................... 449
19.2.1. Step 1: Configure SSL on Directory Server .................................................... 449
19.2.2. Step 2: Configure the Active Directory Domain ............................................... 450
19.2.3. Step 3: Select or Create the Sync Identity ..................................................... 451
19.2.4. Step 4: Install and Configure the Password Sync Service ................................ 451
19.2.5. Step 5: Configure the Password Sync Service ............................................... 453
19.2.6. Step 6: Configure the Directory Server Database for Synchronization ............... 454
19.2.7. Step 7: Create the Synchronization Agreement .............................................. 455
19.2.8. Step 7: Begin Synchronization ...................................................................... 457
19.3. Using Windows Sync .............................................................................................. 457
19.3.1. Synchronizing Users .................................................................................... 457
19.3.2. Synchronizing Groups .................................................................................. 460
19.3.3. Deleting Entries ........................................................................................... 461
19.3.4. Resurrecting Entries ..................................................................................... 461
19.3.5. Manually Updating and Resynchronizing Entries ............................................ 462
19.3.6. Checking Synchronization Status .................................................................. 462
19.3.7. Modifying the Sync Agreement ..................................................................... 462
19.4. Schema Differences ................................................................................................ 463
19.4.1. Password Policies ........................................................................................ 463
19.4.2. Groups ........................................................................................................ 463
19.4.3. Values for street and streetAddress ............................................................... 463
19.4.4. Contraints on the initials Attribute .................................................................. 464
19.5. Password Sync Service .......................................................................................... 464
19.5.1. Modifying Password Sync ............................................................................. 464
19.5.2. Starting and Stopping the Password Sync Service ......................................... 464
19.5.3. Uninstalling Password Sync Service .............................................................. 464
19.6. Troubleshooting ...................................................................................................... 465
A. LDAP Data Interchange Format 467
A.1. About the LDIF File Format ...................................................................................... 467
A.2. Continuing Lines in LDIF .......................................................................................... 468
A.3. Representing Binary Data ......................................................................................... 468
A.3.1. Standard LDIF Notation ................................................................................. 469
A.3.2. Base-64 Encoding ......................................................................................... 469
A.4. Specifying Directory Entries Using LDIF .................................................................... 470
Page 12
Administration Guide
xii
A.4.1. Specifying Domain Entries ............................................................................. 470
A.4.2. Specifying Organizational Unit Entries ............................................................ 471
A.4.3. Specifying Organizational Person Entries ........................................................ 472
A.5. Defining Directories Using LDIF ................................................................................ 473
A.5.1. LDIF File Example ......................................................................................... 474
A.6. Storing Information in Multiple Languages ................................................................. 475
B. Finding Directory Entries 477
B.1. Finding Entries Using the Directory Server Console .................................................... 477
B.2. Using ldapsearch ..................................................................................................... 478
B.2.1. Using Special Characters ............................................................................... 479
B.2.2. ldapsearch Command-Line Format ................................................................. 479
B.2.3. Commonly Used ldapsearch Options .............................................................. 480
B.2.4. ldapsearch Examples ..................................................................................... 481
B.3. LDAP Search Filters ................................................................................................. 484
B.3.1. Search Filter Syntax ...................................................................................... 484
B.4. Searching an Internationalized Directory .................................................................... 487
B.4.1. Matching Rule Filter Syntax ........................................................................... 488
B.4.2. Supported Search Types ................................................................................ 490
B.4.3. International Search Examples ....................................................................... 491
C. LDAP URLs 495
C.1. Components of an LDAP URL .................................................................................. 495
C.2. Escaping Unsafe Characters .................................................................................... 496
C.3. Examples of LDAP URLs ......................................................................................... 497
D. Internationalization 499
D.1. About Locales .......................................................................................................... 499
D.2. Identifying Supported Locales ................................................................................... 500
D.3. Supported Language Subtypes ................................................................................. 501
D.4. Troubleshooting Matching Rules ............................................................................... 502
Glossary 505
Index 519
Page 13
xiii
Preface
Red Hat Directory Server (Directory Server) is a powerful and scalable distributed directory server
based on the industry-standard Lightweight Directory Access Protocol (LDAP). Directory Server is the
cornerstone for building a centralized and distributed data repository that can be used in your intranet,
over your extranet with your trading partners, or over the public Internet to reach your customers.
This Administrator's Guide describes all of the administration tasks you need to perform to maintain
Directory Server.
1. Directory Server Overview
Directory Server provides the following key features:
• Multi-master replication — Provides a highly available directory service for both read and write
operations. Multi-master replication can be combined with simple and cascading replication
scenarios to provide a highly flexible and scalable replication environment.
• Chaining and referrals — Increases the power of your directory by storing a complete logical view
of your directory on a single server while maintaining data on a large number of Directory Servers
transparently for clients.
• Roles and classes of service — Provides a flexible mechanism for grouping and sharing attributes
between entries in a dynamic fashion.
• Improved access control mechanisms — Provides support for macros that dramatically reduce the
number of access control statements used in the directory and increase the scalability of access
control evaluation.
• Resource-limits by bind DN — Grants the power to control the amount of server resources allocated
to search operations based on the bind DN of the client.
• Multiple databases — Provides a simple way of breaking down your directory data to simplify the
implementation of replication and chaining in your directory service.
• Password policy and account lockout — Defines a set of rules that govern how passwords and user
accounts are managed in the Directory Server.
• TLS and SSL — Provides secure authentication and communication over the network, using the
Mozilla Network Security Services (NSS) libraries for cryptography.
The major components of Directory Server include the following:
• An LDAP server — The LDAP v3-compliant network daemon.
• Directory Server Console — A graphical management console that dramatically reduces the effort of
setting up and maintaining your directory service.
• SNMP agent — Can monitor the Directory Server using the Simple Network Management Protocol
(SNMP).
Page 14
Preface
xiv
2. Examples and Formatting
All of the examples for Red Hat Directory Server commands, file locations, and other usage are given
for Red Hat Enterprise Linux 5 (32-bit) systems. Be certain to use the appropriate commands and files
for your platform.
To start the Red Hat Directory Server:
/etc/init.d/dirsv start
Example 1. Example Command
All of the tools for Red Hat Directory Server are located in the /usr/bin directory. These tools can be
run from any location without specifying the tool location.
There is another important consideration with the Red Hat Directory Server tools. The LDAP tools
referenced in this guide are Mozilla LDAP, installed with Red Hat Directory Server in the /usr/lib/
mozldap directory on Red Hat Enterprise Linux 5 (32-bit).
However, Red Hat Enterprise Linux systems also include LDAP tools from OpenLDAP in the /usr/
bin directory. It is possible to use the OpenLDAP commands as shown in the examples, but you must
use the -x argument to disable SASL, which OpenLDAP tools use by default.
Certain words are represented in different fonts, styles, and weights. Different character formatting is
used to indicate the function or purpose of the phrase being highlighted.
Formatting Style Purpose
Monospace font Monospace is used for commands, package names, files and
directory paths, and any text displayed in a prompt.
Monospace
with a
background
This type of formatting is used for anything entered or returned
in a command prompt.
Italicized text Any text which is italicized is a variable, such as
instance_name or hostname. Occasionally, this is also used to
emphasize a new term or other phrase.
Bolded text Most phrases which are in bold are application names, such as
Cygwin, or are fields or options in a user interface, such as a
User Name Here: field or Save button.
Other formatting styles draw attention to important text.
NOTE
A note provides additional information that can help illustrate the behavior of the system or
provide more detail for a specific issue.
IMPORTANT
Important information is necessary, but possibly unexpected, such as a configuration
change that will not persist after a reboot.
Page 15
Additional Reading
xv
WARNING
A warning indicates potential data loss, as may happen when tuning hardware for
maximum performance.
3. Additional Reading
The Directory Server Administrator's Guide describes how to set up, configure, and administer Red
Hat Directory Server and its contents. The instructions for installing the various Directory Server
components are contained in the Red Hat Directory Server Installation Guide. Many of the scripts and
commands used to install and administer the Directory Server are explained in detail in the Red Hat
Directory Server Configuration, Command, and File Reference.
The document set for Directory Server contains the following guides:
• Red Hat Directory Server Release Notes contain important information on new features, fixed bugs,
known issues and workarounds, and other important deployment information for this specific version
of Directory Server.
• Red Hat Directory Server Administrator's Guide contains procedures for the day-to-day maintenance
of the directory service. Includes information on configuring server-side plug-ins.
• Red Hat Directory Server Configuration, Command, and File Reference provides reference
information on the command-line scripts, configuration attributes, and log files shipped with
Directory Server.
• Red Hat Directory Server Installation Guide contains procedures for installing your Directory Server
as well as procedures for migrating from a previous installation of Directory Server.
For the latest information about Directory Server, including current release notes, complete product
documentation, technical notes, and deployment information, see the Red Hat Directory Server
documentation site at http://www.redhat.com/docs/manuals/dir-server/.
4. Giving Feedback
If there is any error in this Administrator's Guide or there is any way to improve the documentation,
please let us know. Bugs can be filed against the documentation for Red Hat Directory Server through
Bugzilla, http://bugzilla.redhat.com/bugzilla. Make the bug report as specific as possible, so we can be
more effective in correcting any issues:
• Select the Red Hat Directory Server product.
• Set the component to Doc - administration-guide.
• Set the version number to 8.0.
• For errors, give the page number (for the PDF) or URL (for the HTML), and give a succinct
description of the problem, such as incorrect procedure or typo.
For enhancements, put in what information needs to be added and why.
• Give a clear title for the bug. For example, "Incorrect command example for setup
script options" is better than "Bad example".
Page 16
Preface
xvi
We appreciate receiving any feedback — requests for new sections, corrections, improvements,
enhancements, even new ways of delivering the documentation or new styles of docs. You are
welcome to contact Red Hat Content Services directly at mailto:docs@redhat.com.
5. Document History
Revision
8.0.19
February 11, 2010 Ella Deon Lackey
Clarifying how passwordUnlock works, per Bugzilla #552377.
Correcting the nsds5replicacredentials example in the replication agreements command-line
example, per Bugzilla #560032.
Revision
8.0.18
January 11, 2010 Ella Deon Lackey
Adding section on nsslapd-cachememsize and the import buffer size, per Bugzilla #531043.
Revision
8.0.17
November 30, 2009 Ella Deon Lackey
Fixing a self-referential cross-link.
Revision
8.0.16
October 13, 2009 Ella Deon Lackey
Correcting passwordIsGlobalPolicy configuration, per Bugzilla #526449.
Revision
8.0.15
September 9, 2009 Ella Deon Lackey
Removing any references to the Directory Server Gateway or Org Chart.
Revision
8.0.14
September 5, 2009 Ella Deon Lackey
Fixing the ldapmodify examples for adding new role entries to include the -a option, which is requred;
related to Bug #521336.
Revision
8.0.13
August 6, 2009 Ella Deon Lackey
Fixing links in configuration for o=Netscape replication, per Bug #514020.
Revision
8.0.12
May 4, 2009 Ella Deon Lackey
Clarifying how to export a replica with db2ldif, per Bug #452576.
Corrected the authmethod bind rule example, per Bug #437007.
Corrected inconsistent use of quotation marks in examples for chaining, per Bug #488818.
Clarified the max cache size file description, per Bug #490038.
Corrected the server certificate name in the pk12util example, per Bug #490499.
Fixed the CNs used in the examples in the certutil procedure, per Bug #492135 and Bug #488152.
Updated the defaults for log deletion attributes, per Bug #475331.
Revision
8.0.11
April 9, 2009 Ella Deon Lackey
Removed paragraph about empty value for nsIndexType, per Bug #464651.
Revision
8.0.10
April 7, 2009 Ella Deon Lackey
Corrected description of nsds5ReplicaPurgeDelay, per Bug #489754.
Page 17
Document History
xvii
Revision 8.0.9 February 24, 2009 Ella Deon Lackey
Edited pin.txt information, per Bug #487149.
Revision 8.0.8 February 7, 2009 Ella Deon Lackey
Add -2 option to the example for generating a CA certificate, per Bug #481174.
Revision 8.0.7 January 16, 2009 Ella Deon Lackey
Correcting the Administration Server password file token example, per Bugzilla #476910.
Revision 8.0.6 January 10, 2009 Ella Deon Lackey
Changing the ECC key to RSA key in the certutil example per the email from SEG engineer Marc
Sauton.
Revision 8.0.5 September 5, 2008 Ella Deon Lackey
Fixing minor typos in the database chapter, per Bugzilla 159786.
Revision 8.0.4 August 28, 2008 Ella Deon Lackey
Editing the procedure for configuring transaction logs for frequent updates, adding missing and
necessary steps per Bugzilla 459839.
Removing an incorrect note about server startup time in the common usage chapter.
Correcting the procedure for using a password file for running the Administration Server with SSL.
Minor changes to the fractional replication and password policy replication sections, per Bugzilla
450973.
Edits to certutil sections, per Bugzilla 441889.
Revision 8.0.3 April 30, 2008 Ella Deon Lackey
Correcting the labels in the graphic dirtree3.png, per Bugzilla 443809.
Correcting password expiration description, per Bugzilla 239642.
Revision 8.0.2 April 7, 2008 Ella Deon Lackey
Correcting bad cross-reference links in the performance tuning chapter.
Minor edits to the SSL cipher list, per Bugzilla 234966.
Changing the name and location of template-cl-dump.pl and template-repl-monitor.pl, per Bugzilla
239337.
Revision 8.0.1 April 7, 2008 Ella Deon Lackey
Correcting bad cross-reference links in the performance tuning chapter.
Minor edits to the SSL cipher list, per Bugzilla 234966.
Changing the name and location of template-cl-dump.pl and template-repl-monitor.pl, per Bugzilla
239337.
Revision 8.0.1 February 12, 2008 Ella Deon Lackey
Clarifying the location of Mozilla LDAP tools, per Bugzilla 430539.
Removing references to 7.1 manuals, per Bugzilla 430562.
Removing a misleading note box in the synchronization chapter.
Correcting the schema directory path.
Revision 8.0.0 January 15, 2008 Ella Deon Lackey
Initial draft for version 8.0.
Page 18
xviii
Page 19
Chapter 1.
1
General Red Hat Directory Server
Usage
Red Hat Directory Server product includes a directory service, an administration server to manage
multiple server instances, and a Java-based console to manage server instances through a graphical
interface. This chapter provides an overview of the basic tasks for administering a directory service.
The Directory Server is a robust, scalable server designed to manage an enterprise-wide directory of
users and resources. It is based on an open-systems server protocol called the Lightweight Directory
Access Protocol (LDAP). Directory Server runs the ns-slapd daemon on the host machine. The
server manages the directory databases and responds to client requests.
Directory Server 8.0 is comprised of several components, which work in tandem:
• The Directory Server is the core LDAP server daemon. It is compliant with LDAP v3 standards. This
component includes command-line server management and administration programs and scripts for
common operations like export and backing up databases.
• The Directory Server Console is the user interface that simplifies managing users, groups, and other
LDAP data for your enterprise. The Console is used for all aspects of server management, including
making backups; configuring security, replication, and databases; adding entries; and monitoring
servers and viewing statistics.
• The Administration Server is the management agent which administers Directory Server instances.
It communicates with the Directory Server Console and performs operations on the Directory Server
instances. It also provides a simple HTML interface and online help pages.
Most Directory Server administrative tasks are available through the Directory Server Console, but it is
also possible to administer the Directory Server by manually editing the configuration files or by using
command-line utilities.
1.1. Directory Server File Locations
Red Hat Directory Server 8.0 conforms to the Filesystem Hierarchy Standards. For more information
on FHS, see the FHS homepage, http://www.pathname.com/fhs/. The files and directories installed
with Directory Server are listed in the tables below for each supported platform.
In the file locations listed in the following tables, instance is the server instance name that was given
during setup. By default, this is the leftmost component of the fully-qualified host and domain name.
For example, if the hostname is ldap.example.com, the instance name is ldap by default.
The Administration Server directories are named the same as the Directory Server directories, only
instead of the instance as a directory name, the Administration Server directories are named admin-
serv. For any directory or folder named slapd-instance, substitute admin-serv, such as /etc/
dirsrv/slapd-example and /etc/dirsrv/admin-serv.
File or Directory Location
Log files /var/log/dirsrv/slapd-instance
Configuration files /etc/dirsrv/slapd-instance
Instance directory /usr/lib/dirsrv/slapd-instance
Page 20
Chapter 1. General Red Hat Directory Server Usage
2
File or Directory Location
Database files /var/lib/dirsrv/slapd-instance
Runtime files /var/lock/dirsrv/slapd-instance
/var/run/dirsrv/slapd-instance
Initscripts /etc/rc.d/init.d/dirsrv and /etc/
sysconfig/dirsrv
/etc/rc.d/init.d/dirsrv-admin and /
etc/sysconfig/dirsrv-admin
Tools /usr/bin/
/usr/sbin/
Table 1.1. Red Hat Enterprise Linux 4 and 5 (x86)
File or Directory Location
Log files /var/log/dirsrv/slapd-instance
Configuration files /etc/dirsrv/slapd-instance
Instance directory /usr/lib64/dirsrv/slapd-instance
Database files /var/lib/dirsrv/slapd-instance
Runtime files /var/lock/dirsrv/slapd-instance
/var/run/dirsrv/slapd-instance
Initscripts /etc/rc.d/init.d/dirsrv and /etc/
sysconfig/dirsrv
/etc/rc.d/init.d/dirsrv-admin and /
etc/sysconfig/dirsrv-admin
Tools /usr/bin/
/usr/sbin/
Table 1.2. Red Hat Enterprise Linux 4 and 5 (x86_64)
File or Directory Location
Log files /var/log/dirsrv/slapd-instance
Configuration files /etc/dirsrv/slapd-instance
Instance directory /usr/lib/sparc9/dirsrv/slapd-instance
Database files /var/lib/dirsrv/slapd-instance
Runtime files /var/lock/dirsrv/slapd-instance
/var/run/dirsrv/slapd-instance
Initscripts /etc/rc.d/init.d/dirsrv and /etc/
default/dirsrv
/etc/rc.d/init.d/dirsrv-admin and /
etc/default/dirsrv-admin
Tools /usr/bin/
Page 21
LDAP Tool Locations
3
File or Directory Location
/usr/sbin/
Table 1.3. Sun Solaris 9 (sparc)
File or Directory Location
Log files /var/opt/log/dirsrv/slapd-instance
Configuration files /etc/opt/dirsrv/slapd-instance
Instance directory /opt/dirsrv/slapd-instance
Database files /var/opt/dirsrv/slapd-instance
Runtime files /var/opt/dirsrv/instance
Binaries /opt/dirsrv/bin/
/opt/dirsrv/sbin/
Libraries /opt/dirsrv/lib/
Table 1.4. HP-UX 11i (IA64)
1.2. LDAP Tool Locations
Red Hat Directory Server uses Mozilla LDAP tools — such as ldapsearch, ldapmodify, and
ldapdelete — for command-line operations. The MozLDAP tools are installed with Directory Server.
Platform Directory Location
Red Hat Enterprise Linux 4 i386 /usr/lib/mozldap6
Red Hat Enterprise Linux 4 x86_64 /usr/lib64/mozldap6
Red Hat Enterprise Linux 5 i386 /usr/lib/mozldap
Red Hat Enterprise Linux 5 x86_64 /usr/lib64/mozldap
Sun Solaris /usr/lib/sparcv9/mozldap
HP-UX /opt/dirsrv/bin
For all Red Hat Directory Server guides and documentation, the LDAP tools used in the examples,
such as ldapsearch and ldapmodify, are the Mozilla LDAP tools. For most Linux systems,
OpenLDAP tools are already installed in the /usr/bin/ directory. These OpenLDAP tools are not
supported for Directory Server operations. For the best results with the Directory Server, make sure
the path to the Mozilla LDAP tools comes first in the PATH or use the full path and file name for every
LDAP operation.
However, these OpenLDAP tools can be used for Directory Server operations with certain cautions:
• The output of the other tools may be different, so it may not look like the examples in the
documentation.
• The OpenLDAP tools require a -x argument to disable SASL so that it can be used for a simple
bind, meaning the -D and -w arguments or an anonymous bind.
• The OpenLDAP tools' arguments for using TLS/SSL and SASL are quite different than the Mozilla
LDAP arguments. See the OpenLDAP documentation for instructions on those arguments.
Page 22
Chapter 1. General Red Hat Directory Server Usage
4
1.3. Starting and Stopping Servers
The Directory Server is running when the setup-ds-admin.pl script completes. Avoid stopping and
starting the server to prevent interrupting replication, searches, and other server operations.
• If the Directory Server has SSL enabled, you cannot restart the server from the Console; you
must use the command-line. It is possible to restart without being prompted for a password; see
Section 11.4.3, “Creating a Password File for the Directory Server” for more information.
• Rebooting the host system can automatically start the ns-slapd process. The directory provides
startup or run command (rc) scripts. On Red Hat Enterprise Linux, use the chkconfig command
to enable the Directory Server and Administration Server to start on boot. On Solaris, the commands
are already set up in the /etc/rc.d directories to start up the servers at boot time. For HP-UX,
check the operating system documentation for details on adding these scripts.
1.3.1. Starting and Stopping Directory Server from the Console
1. Start the Directory Server Console.
/usr/bin/redhat-idm-console -a http://localhost:9830
2. In the Tasks tab, click Start the Directory Server, Stop the Directory Server, or Restart the
Directory Server.
When the Directory Server is successfully started or stopped from the Directory Server Console, the
server displays a message box stating that the server has either started or shut down.
Page 23
Starting and Stopping Directory Server from the Command Line
5
1.3.2. Starting and Stopping Directory Server from the Command
Line
There are two ways to start, stop, or restart the Directory Server:
• There are scripts in the instance directories. For example:
/usr/lib/dirsrv/slapd-instance/start-slapd
/usr/lib/dirsrv/slapd-instance/restart-slapd
/usr/lib/dirsrv/slapd-instance/stop-slapd
• The Directory Server service can also be stopped and started using system tools on Red Hat
Enterprise Linux and Solaris. For example, Linux uses the service tool:
service dirsrv {start|stop|restart} instance
NOTE
The service name for the Directory Server process on Red Hat Enterprise Linux is
dirsrv.
Solaris uses /etc/init.d:
/etc/init.d/dirsrv {start|stop|restart} instance
The Directory Server instance name can be specific in both the start|stop|restart-slapd and
system scripts. If an instance name is not given, the start or stop operation applies to all instances on
the machine.
1.3.3. Starting and Stopping Administration Server
There are two ways to start, stop, or restart the Administration Server:
• There are scripts in the /usr/sbin directory.
/usr/sbin/start|stop|restart-ds-admin
• The Administration Server service can also be stopped and started using system tools on Red Hat
Enterprise Linux and Solaris. For example, on Red Hat Enterprise Linux, the command is service:
service dirsrv-admin {start|stop|restart}
NOTE
The service name for the Administration Server process on Red Hat Enterprise Linux is
dirsrv-admin.
On Solaris, the service is init.d:
Page 24
Chapter 1. General Red Hat Directory Server Usage
6
/etc/init.d/dirsrv-admin {start|stop|restart}
1.4. Starting the Directory Server Console
There is a simple script to launch the Directory Server Console. On Red Hat Enterprise Linux and
Solaris, run the following:
/usr/bin/redhat-idm-console
HP-UX has a different location for the script:
/opt/dirsrv/bin/redhat-idm-console
NOTE
Make sure that the correct JRE — the program called java — is set in the PATH before
launching the Console. Run the following to see if the Java program is in the PATH and to
get the version and vendor information:
java -version
When the login screen opens, you are prompted for the username, password, and Administration
Server location. It is possible to send the Administration Server URL and port with the start script. For
example:
/usr/bin/redhat-idm-console -a http://localhost:9830
The a option is a convenience, particularly if you are logging into a Directory Server for the first time.
On subsequent logins, the URL is saved. If you do not pass the Administration Server port number
with the redhat-idm-console command, then you are prompted for it at the Console login screen.
1.4.1. Logging into Directory Server
After starting the Directory Server Console, a login screen opens, requiring the username and
password for the user logging in and the URL for the Administration Server instance being access.
The user logged in at the Console is the user who is binding to Directory Server. This determines
the access permissions granted and allowed operations while access the directory tree. The user
account used to log into the Directory Server Console can make significant differences in the access;
for example, the Directory Manager has access to every user and configuration entry in Directory
Server, while the admin entry created during installation has access to only configuration entries, not
user entries. Regular user accounts are more limited.
To bind to, or log into, the Directory Server, supply a username and password at the login box.
Page 25
Changing Login Identity
7
1.4.2. Changing Login Identity
At any time during a session, you can log in as a different user, without having to restart the Console.
To change the login identity, do the following:
1. In the Directory Server Console, select the Tasks tab.
2. Click Log on to the Directory Server as a New User.
3. A login dialog box appears.
Page 26
Chapter 1. General Red Hat Directory Server Usage
8
Enter the full distinguished name of the entry with which to bind to the server. For example, to bind
as user Barbara Jensen, enter her full DN in the login box:
cn=Barbara Jensen, ou=People,dc=example,dc=com
1.4.3. Viewing the Current Console Bind DN
To see the bind DN that is currently logged into the Directory Server Console, click the login icon in the
lower-left corner of the window. The current bind DN appears next to the login icon.
Figure 1.1. Viewing the Bind DN
1.5. Changing Directory Server Port Numbers
The standard and secure LDAP port numbers used by Directory Server can be changed through the
Directory Server Console or by changing the value of the nsslapd-port or nsslapd-secureport
attribute under the cn=config entry in the dse.ldif.
NOTE
Modifying the standard or secure port numbers for a Configuration Directory Server, which
maintains the o=NetscapeRoot subtree should be done through the Directory Server
Console.
Changing the configuration directory or user directory port or secure port numbers has the following
repercussions:
• The Directory Server port number must also be updated in the Administration Server configuration.
• If there are other Directory Server instances that point to the configuration or user directory, update
those servers to point to the new port number.
To modify a Directory Server LDAP or LDAPS port for either a user or a configuration directory, do the
following:
1. In the Directory Server Console, select the Configuration tab, and then select the top entry in the
navigation tree in the left pane.
2. Select the Settings tab in the right pane.
3. Enter the port number for the server to use for non-SSL communications in the Port field. The
default value is 389.
4. Enter the port number for the server to use for SSL communications in the Encrypted Port field.
The encrypted port number must not be the same port number used for normal LDAP
communications. The default value is 636.
5. Click Save.
Page 27
Creating a New Directory Server Instance
9
6. The Console returns a warning, You are about to change the port number for the Configuration
Directory. This will affect all Administration Servers that use this directory and you'll need to update
them with the new port number. Are you sure you want to change the port number? Click Yes.
7. Then a dialog appears, reading that the changes will not take effect until the server is restarted.
Click OK.
NOTE
Do not restart the Directory Server at this point. If you do, you will not be able to make
the necessary changes to the Administration Server through the Console.
8. Open the Administration Server Console.
9. In the Configuration tab, select the Configuration DS tab.
10. In the LDAP Port field, type in the new LDAP port number for your Directory Server instance.
11. Check the Secure Connection box if this is a secure port.
NOTE
If you try to save these changes at this step, you will get a warning box that reads,
Invalid LDAP Host/LDAP Port, can not connect. Click OK, and ignore this warning.
12. In the Tasks tab of the Directory Server Console, click Restart Directory Server. A dialog to
confirm that you want to restart the server. Click Yes.
13. Open the Configuration DS tab of the Administration Server Console and select Save.
A dialog will appear, reading The Directory Server setting has been modified. You must shutdown
and restart your Administration Server and all the servers in the Server Group for the changes to
take effect. Click OK.
14. In the Tasks tab of the Administration Server Console, click Restart Admin Server. A dialog
opens reading that the Administration Server has been successfully restarted. Click Close.
NOTE
You must close and reopen the Console before you can do anything else in the
Console. Refresh may not update the Console, and, if you try to do anything, you will
get a warning that reads Unable to contact LDAP server.
1.6. Creating a New Directory Server Instance
Additional instances can be created through the Directory Server Console or using the setup-ds.pl
script. For information on using the setup-ds.pl script, see the Directory Server Installation Guide.
To create an instance using the Directory Server Console, do the following:
1. In the Red Hat Console window, select Server Group in the navigation tree, and then right-click.
Page 28
Chapter 1. General Red Hat Directory Server Usage
10
2. From the pop-up menu, select Create Instance and then Directory Server.
The Create New Instance dialog box is displayed.
3. Enter a unique identifier for the server in the Server Identifier field.
NOTE
This name must only have alphanumeric characters, a dash (-), or an underscore (_).
4. Enter the a port number for LDAP communications in the Network port field.
5. Enter the suffix managed by this new instance of the directory in the Base Suffix field.
6. Enter a DN for the Directory Manager in the Root DN field.
For information on the role and privileges of the Directory Manager entry, refer to Section 1.7,
“Configuring the Directory Manager”.
7. Enter the password for this user in the Password for Root DN field, and confirm it.
8. Enter the user ID for the Directory Server daemon in the Server Runtime User ID field.
9. Click OK.
A status box appears to confirm that the operation was successful. To dismiss it, click OK.
1.7. Configuring the Directory Manager
The Directory Manager is the privileged database administrator, comparable to the root user in UNIX.
Access control does not apply to the Directory Manager entry; likewise, limits on searches and other
operations do not apply. The Directory Manager entry is created during installation; the default DN is
cn=Directory Manager.
The password for this user is defined in the nsslapd-rootdn attribute.
To change the Directory Manager DN and password and the encryption scheme used for this
password, do the following:
1. Log in to the Directory Server Console as Directory Manager.
If you are already logged in to the Console, change the bind DN, as described in Section 1.4.2,
“Changing Login Identity”.
2. In the Directory Server Console, select the Configuration tab, and then select the top entry in the
navigation tree in the left pane.
3. Select the Manager tab in the right pane.
4. Enter the new distinguished name for the Directory Manager in the Root DN field.
The default value is cn=Directory Manager.
5. From the Manager Password Encryption pull-down menu, select the storage scheme you want
the server to use to store the password for Directory Manager.
Page 29
Configuring the Directory Manager
11
6. Enter the new password, and confirm it.
7. Click Save.
Page 30
12
Page 31
Chapter 2.
13
Creating Directory Entries
This chapter discusses how to use the Directory Server Console and the ldapmodify and
ldapdelete command-line utilities to modify the contents of your directory.
Entries stored in Active Directory can be added to the Directory Server through Windows Sync;
see Chapter 19, Synchronizing Red Hat Directory Server with Microsoft Active Directory for more
information on adding or modifying synchronized entries through Windows User Sync.
2.1. Managing Entries from the Directory Console
You can use the Directory tab and the Property Editor on the Directory Server Console to add,
modify, or delete entries individually.
To add several entries simultaneously, use the command-line utilities described in Section 2.1,
“Managing Entries from the Directory Console”.
• Section 2.1.1, “Creating a Root Entry”
• Section 2.1.2, “Creating Directory Entries”
• Section 2.1.3, “Modifying Directory Entries”
• Section 2.1.4, “Deleting Directory Entries”
NOTE
You cannot modify your directory unless the appropriate access control rules have been
set. For information on creating access control rules for your directory, see Chapter 6,
Managing Access Control.
2.1.1. Creating a Root Entry
Each time you create a new database, you associate it with the suffix that will be stored in the
database. The directory entry representing that suffix is not automatically created.
To create a root entry for a database, do the following:
NOTE
For information on starting the Directory Server Console, see Section 1.4, “Starting the
Directory Server Console”.
1. In the Directory Server Console, select the Configuration tab.
2. Create a new database, as explained in Section 3.2, “Creating and Maintaining Databases”.
3. In the Directory tab, right-click the top object representing the Directory Server, and choose New
Root Object.
The secondary menu under New Root Object displays a list of suffixes that do not have a
corresponding entry.
Page 32
Chapter 2. Creating Directory Entries
14
4. Choose the suffix corresponding to the entry to create.
The New Object window opens.
5. In the New Object window, select the object class corresponding to the new entry.
The object class you select must contain the attribute you used to name the suffix. For example,
if you are creating the entry corresponding to the suffix ou=people,dc=example,dc=com, then
you can choose the organizationalUnit object class or another object class that allows the
ou attribute.
6. Click OK in the New Object window.
The Property Editor for the new entry opens. You can either accept the current values by clicking OK
or modify the entry, as explained in Section 2.1.3, “Modifying Directory Entries”.
2.1.2. Creating Directory Entries
Directory Server Console offers several predefined templates for creating directory entries. Templates
are available for the following types of entries:
• User
• Group
• Organizational Unit
• Role
• Class of Service
Table 2.1, “Entry Templates and Corresponding Object Classes” shows what type of object class is
used for each template.
Template Object Class
User inetOrgPerson
Group groupOfUniqueNames
Organizational Unit organizationalUnit
Role nsRoleDefinition
Class of Service cosSuperDefinition
Table 2.1. Entry Templates and Corresponding Object Classes
These templates contain fields representing all the mandatory attributes and some of the commonly
used optional attributes. To create an entry using one of these templates, refer to Section 2.1.2.1,
“Creating an Entry Using a Predefined Template”. To create any other type of entry, refer to
Section 2.1.2.2, “Creating Other Types of Entries”.
2.1.2.1. Creating an Entry Using a Predefined Template
1. In the Directory Server Console, select the Directory tab.
For information on starting the Directory Server Console, see Section 1.4, “Starting the Directory
Server Console”.
Page 33
Creating Directory Entries
15
2. In the left pane, right-click the main entry to to add the new entry, and select the type of entry:
User, Group, Organizational Unit, Role, Class of Service, or Other.
The corresponding Create window opens.
3. Supply values for all of the mandatory attributes (identified by an asterisk) and, if you want, for any
of the optional attributes.
4. The Create window does not provide fields for all optional attributes. To display the full list of
attributes, click the Advanced button.
In the Property Editor (described in Section 2.1.3, “Modifying Directory Entries”), select any
additional attributes, and fill in the attribute values.
5. Click OK to save the entry. The new entry opens in the right pane.
2.1.2.2. Creating Other Types of Entries
1. In the Directory Server Console, select the Directory tab.
For information on starting the Directory Server Console, see Section 1.4, “Starting the Directory
Server Console”.
2. In the left pane, right-click the main entry under which to add the new entry, and select Other.
The New Object window opens.
3. In the object class list, select an object class to define the new entry.
4. Click OK.
If you selected an object class related to a type of entry for which a predefined template is
available, the corresponding Create window opens, as described in Section 2.1.2.1, “Creating an
Entry Using a Predefined Template”.
In all other cases, the Property Editor opens. It contains a list of mandatory attributes for the
selected object class.
5. Supply a value for all the listed attributes.
• Some fields are empty, but some might have a placeholder value such as New. Fill in all
attributes with a meaningful value for the entry.
• Some object classes can have several naming attributes. Select the naming attribute to use to
name the new entry.
• Open the Property Editor to add optional attributes, as described in Section 2.1.3, “Modifying
Directory Entries”.
6. Click OK to save the new entry. The new entry opens in the right pane.
Page 34
Chapter 2. Creating Directory Entries
16
2.1.3. Modifying Directory Entries
Modifying directory entries in Directory Server Console uses a dialog window called the Property
Editor. The Property Editor contains the list of object classes and attributes belonging to an entry
and can be used to edit the object classess and attributes belonging to that entry:
• Add and remove object classes
• Add and remove an attribute
• Add and remove an attribute value
• Add an attribute subtype
This section describes how to start the Property Editor and use it to modify an entry's attributes and
attribute values.
2.1.3.1. Displaying the Property Editor
The Property Editor can be opened in several ways:
• From the Directory tab, by right-clicking an entry, and selecting Properties from the pop-up menu.
• From the Directory tab, by double-clicking an entry
• From the Create... entry templates, by clicking the Advanced button (as in Section 2.1.2.1,
“Creating an Entry Using a Predefined Template”)
• From the New Object window, by clicking OK (as in Section 2.1.2.2, “Creating Other Types of
Entries”)
2.1.3.2. Adding an Object Class to an Entry
To add an object class to an entry, do the following:
1. In the Directory tab of the Directory Server Console, right-click the entry to modify, and select
Advanced from the pop-up menu.
Alternatively, double-click the entry to open the Property Editor, and click the Advanced button.
2. Select the object class field, and click Add Value.
The Add Object Class window opens. It shows a list of object classes that can be added to the
entry.
3. Select the object class to add, and click OK.
The selected object class appears in the list of object classes in the Advanced Property Editor.
To dismiss the Add Object Class window, click Cancel.
4. Click OK in the Advanced Property Editor when you have finished editing the entry, then click
OK to close the Property Editor.
2.1.3.3. Removing an Object Class
To remove an object class from an entry, do the following:
Page 35
Modifying Directory Entries
17
1. In the Directory tab of the Directory Server Console, right-click the entry to modify, and select
Advanced from the pop-up menu.
Alternatively, double-click the entry to open the Property Editor opens, and click the Advanced
button.
2. Click the text box that shows the object class to remove, and then click Delete Value.
3. Click OK in the Advanced Property Editor, then click OK to save the changes and close the
Property Editor.
2.1.3.4. Adding an Attribute to an Entry
Before you can add an attribute to an entry, the entry must contain an object class that either requires
or allows the attribute. refer to Section 2.1.3.2, “Adding an Object Class to an Entry” and Chapter 9,
Extending the Directory Schema for more information.
Add an attribute to an entry as follows:
1. In the Directory tab of the Directory Server Console, right-click the entry to modify, and select
Advanced from the pop-up menu.
Alternatively, double-click the entry to open the Property Editor, and then click the Advanced
button.
2. Click Add Attribute. The Add Attribute dialog box opens.
3. Select the attribute to add from the list, and click OK.
The Add Attribute window is dismissed, and the selected attribute appears in the list of attributes
in the Advanced Property Editor.
4. Type in the value for the new attribute in the field to the right of the attribute name.
5. Click OK in the Advanced Property Editor to save the attribute to the entry and close the
Advanced Property Editor.
Click OK to close the Property Editor.
NOTE
If the attribute you want to add is not listed, add the object class containing the attribute
first, then add the attribute. See Section 2.1.3.2, “Adding an Object Class to an Entry” for
instructions on adding an object class.
2.1.3.5. Adding Very Large Attributes
The configuration attribute nsslapd-maxbersize sets the maximum size limit for LDAP requests.
The default configuration of Directory Server sets this attribute at 2 megabytes. LDAP add or modify
operations will fail when attempting to add very large attributes that result in a request that is larger
than 2 megabytes.
To add very large attributes, first change the setting for the nsslapd-maxbersize configuration
attribute to a value larger than the largest LDAP request you will make.
Page 36
Chapter 2. Creating Directory Entries
18
When determining the value to set, consider all elements of the LDAP add and modify operations used
to add the attributes, not just the single attribute. There are a number of different factors to considerin,
including the following:
• The size of each attribute name in the request
• The size of the values of each of the attributes in the request
• The size of the DN in the request
• Some overhead; usually 10 kilobytes is sufficient
One common issue that requires increasing the nsslapd-maxbersize setting is using attributes
which hold CRL values, such as certificateRevocationList, authorityRevocationList,
and deltaRevocationList.
For further information about the nsslapd-maxbersize attribute and for information about setting
this attribute, see the section "nsslapd-maxbersize (MaximumMessage Size)" in chapter 2, "Core
Server Configuration Reference," in Red Hat Directory Server Configuration, Command, and File
Reference.
2.1.3.6. Adding Attribute Values
Multi-valued attributes allow multiple value for one attribute to be added to an entry. To add an attribute
value to a multi-valued attribute:
1. In the Directory tab of the Directory Server Console, right-click the entry to modify, and select
Advanced from the pop-up menu.
Alternatively, double-click the entry to open the Property Editor, and click the Advanced button.
2. Select the attribute to which to add a value, and then click Add Value. A new blank text field
opens in the right column.
3. Type in the new attribute value.
4. Click OK in the Advanced Property Editor to close the Advanced Property Editor, then click
OK again to close the Property Editor.
2.1.3.7. Removing an Attribute Value
To remove an attribute value from an entry, do the following:
1. In the Directory tab of the Directory Server Console, right-click the entry to modify, and select
Advanced from the pop-up menu.
Alternatively, double-click the entry to open the Property Editor, and click the Advanced button.
2. Click the text box of the attribute value to remove, and click Delete Value.
To remove the entire attribute and all its values from the entry, select Delete Attribute from the
Edit menu.
3. Click OK to close the Advanced Property Editor, then click OK to close the Property Editor.
Page 37
Modifying Directory Entries
19
2.1.3.8. Adding an Attribute Subtype
There are three different kinds of subtypes to attributes which can be added to an entry: language,
binary, and pronunciation.
2.1.3.8.1. Language Subtype
Sometimes a user's name can be more accurately represented in characters of a language other
than the default language. For example, a user, Noriko, has a name in Japanese and prefers that her
name be represented by Japanese characters when possible. You can select Japanese as a language
subtype for the givenname attribute so that other users can search for her name in Japanese as well
as English. For example:
givenname;lang-ja
To specify a language subtype for an attribute, add the subtype to the attribute name as follows:
attribute;lang-subtype:attribute value
attribute is the attribute being added to the entry and subtype is the two character abbreviation for the
language. The supported language subtypes are listed in Table D.2, “Supported Language Subtypes”.
Only one language subtype can be added per attribute instance in an entry. To assign multiple
language subtypes, add another attribute instance to the entry, and then assign the new language
subtype. For example, the following is illegal:
cn;lang-ja;lang-en-GB:value
Instead, use:
cn;lang-ja:ja-value
cn;lang-en-GB:value
2.1.3.8.2. Binary Subtype
Assigning the binary subtype to an attribute indicates that the attribute value is binary, such as user
certificates (usercertificate;binary).
Although you can store binary data within an attribute that does not contain the binary subtype (for
example, jpegphoto), the binary subtype indicates to clients that multiple variants of the attribute
type may exist.
2.1.3.8.3. Pronunciation Subtype
Assigning the pronunciation subtype to an attribute indicates that the attribute value is a phonetic
representation. The subtype is added to the attribute name as attribute;phonetic. This subtype
is commonly used in combination with a language subtype for languages that have more than one
alphabet, where one is a phonetic representation.
This subtype is useful with attributes that are expected to contain user names, such as cn or
givenname. For example, givenname;lang-ja;phonetic indicates that the attribute value is the
phonetic version of the user's Japanese name.
Page 38
Chapter 2. Creating Directory Entries
20
2.1.3.8.4. Adding a Subtype to an Attribute
To add a subtype to an entry, do the following:
1.
In the Directory tab of the Directory Server Console, right-click the entry to modify, and select
Properties from the pop-up menu.
Alternatively, double-click the entry to open the Property Editor.
2. Click Add Attribute. The Add Attribute dialog box opens.
3. Select the attribute to add from the list.
4. To assign a language subtype to the attribute, select the subtype from the Language drop-down
list.
Assign one of the other two subtypes, binary or pronunciation, from the Subtype drop-down list.
5. Click OK to close the Add Attribute window, then click OK again to close the Property Editor.
2.1.4. Deleting Directory Entries
To delete entries using the Directory Server Console, do the following:
1. In the Directory Server Console, select the Directory tab.
For information on starting the Directory Server Console, see Section 1.4, “Starting the Directory
Server Console”.
2. Right-click the entry to delete in the navigation tree or in the right pane. To select multiple entries,
use Ctrl or Shift.
3. Select Delete from the Edit menu.
WARNING
The server deletes the entry or entries immediately. There is no way to undo the delete
operation.
2.2. Managing Entries from the Command-Line
The command-line utilities allow you to manipulate the contents of your directory. They can be useful
to write scripts to perform bulk management of the directory or to test the Directory Server. For
example, you might want to ensure that it returns the expected information after you have made
changes to access control information.
With command-line utilities, information can be provided directly from the command-line or through an
LDIF input file.
• Section 2.2.1, “Providing Input from the Command-Line”
• Section 2.2.2, “Creating a Root Entry from the Command-Line”
• Section 2.2.3, “Adding Entries Using LDIF”
Page 39
Providing Input from the Command-Line
21
• Section 2.2.4, “Adding and Modifying Entries Using ldapmodify”
• Section 2.2.5, “Deleting Entries Using ldapdelete”
• Section 2.2.6, “Using Special Characters”
NOTE
You cannot modify your directory unless the appropriate access control rules have been
set. For information on creating access control rules for your directory, see Chapter 6,
Managing Access Control.
2.2.1. Providing Input from the Command-Line
When you provide input to the ldapmodify and ldapdelete1 utilities directly from the commandline, you must use LDIF statements. For detailed information on LDIF statements, see Section 2.4,
“LDIF Update Statements”.
The ldapmodify and ldapdelete utilities read the statements that you enter in exactly the same
way as if they were read from a file. When all of the input has been entered, enter the character that
the shell recognizes as the end of file (EOF) escape sequence. The utility then begins operations
based on the supplied inputs.
While the EOF escape sequence depends on the type of machine, the EOF escape sequence almost
always control-D (^D).
For example, to input some LDIF update statements to ldapmodify, you would do the following:
ldapmodify -D bindDN -w password -h hostname
dn: cn=Barry Nixon, ou=people, dc=example,dc=com
changetype: modify
delete: telephonenumber
add: manager
manager: cn=Harry Cruise, ou=people, dc=example,dc=com
^D
When adding an entry from the command line or from LDIF, make sure that an entry representing a
subtree is created before new entries are created under that branch. For example, to place an entry in
a People subtree, create an entry representing that subtree before creating entries within the subtree.
For example:
dn: dc=example,dc=com
dn: ou=People, dc=example,dc=com
...People subtree entries. ...
dn: ou=Group, dc=example,dc=com
...Group subtree entries. ...
The LDAP tools referenced in this guide are Mozilla LDAP, installed with Directory Server in the /usr/lib/mozldap directory
on Red Hat Enterprise Linux 5 (32-bit); directories for other platforms are listed in Section 1.2, “LDAP Tool Locations”. However,
Red Hat Enterprise Linux systems also include LDAP tools from OpenLDAP. It is possible to use the OpenLDAP commands as
shown in the examples, but you must use the -x argument to disable SASL and allow simple authentication.
Page 40
Chapter 2. Creating Directory Entries
22
2.2.2. Creating a Root Entry from the Command-Line
The ldapmodify command-line utility can be used to create a new root entry in a database. For
example:
ldapmodify -a -D bindDN -w password
The ldapmodify utility binds to the server and prepares it to add an entry. The new root object can
then be added, as follows:
dn: Suffix_Name
objectclass: newobjectclass
The DN corresponds to the DN of the root or sub-suffix contained by the database. The
newobjectclass value depends upon the type of object class you are adding to the database. You may
need to specify additional required attributes depending on the type of root object being added.
NOTE
You can use ldapmodify to add root objects only if you have one database per suffix. If
you create a suffix that is stored in several databases, you must use the ldif2db utility
with the -noption parameter to specify the database that will hold the new entries. For
information, see Section 4.1.4, “Importing from the Command-Line”.
2.2.3. Adding Entries Using LDIF
You can use an LDIF file to add multiple entries or to import an entire database. To add entries using
an LDIF file and the Directory Server Console:
1. Define the entries in an LDIF file.
LDIF files are described in Appendix A, LDAP Data Interchange Format.
2. Import the LDIF file from the Directory Server Console.
See Section 4.1.2, “Importing a Database from the Console” for information about LDIF file
formats. When you import the LDIF file, select Append to database in the Import dialog box so
that the server will only import entries that do not currently exist in the directory.
You can also add entries described in an LDIF file from the command-line using the ldapmodify
command with the -f option.
2.2.4. Adding and Modifying Entries Using ldapmodify
The ldapmodify1 command can add and modify entries in an existing Directory Server database.
The ldapmodify command opens a connection to the specified server using the supplied
distinguished name and password and modifies the entries based on LDIF update statements
contained in a specified file. Because ldapmodify uses LDIF update statements, ldapmodify can
do everything that ldapdelete can do.
Consider the following when using ldapmodify:
Page 41
Adding and Modifying Entries Using ldapmodify
23
• If the server detects an attribute or object class in the entry that is not known to the server, then
the modify operation will fail when it reaches the erroneous entry. All entries that were processed
before the error was encountered will be successfully added or modified. If you run ldapmodify
with the -c option (do not stop on errors), all correct entries processed after the erroneous entry will
be successfully added or modified.
•
If a required attribute is not present, the modify operation fails. This happens even if the offending
object class or attribute is not being modified.
NOTE
To create the root entry a database suffix (such as dc=example,dc=com) using
ldapmodify, you must bind to the directory as the Directory Manager.
2.2.4.1. Adding Entries Using ldapmodify
Typically, to add the entries using ldapmodify, specify the DN and password to bind to the Directory
Server, the port and host of the Directory Server, and the LDIF file to use. For example:
ldapmodify -a -D "cn=Directory Manager" -w King-Pin -h cyclops -p 845 -f new.ldif
This ldapmodify example has the following values:
• The entries to be created are specified in the file new.ldif. (In this example, the LDIF statements
in the new.ldif file do not specify a change type. They follow the format defined in Section A.1,
“About the LDIF File Format”.)
• The Directory Manager is a database administrator who has the authority to modify the entries, and
its password is King-Pin.
• The hostname is cyclops.
• The server uses port number 845.
Table 2.2, “ldapmodify Parameters Used for Adding Entries” describes the ldapmodify parameters
used in the example.
Parameter Name Description
-a Specifies that the modify operation will add new
entries to the directory.
-D Specifies the distinguished name with which to
authenticate to the server. The value must be
a DN recognized by the Directory Server, and
it must also have the authority to modify the
entries.
-w Specifies the password associated with
the distinguished name specified in the -D
parameter.
-h Specifies the name of the host on which the
server is running.
Page 42
Chapter 2. Creating Directory Entries
24
Parameter Name Description
-p Specifies the port number that the server uses.
-f Optional parameter that specifies the file
containing the LDIF update statements used to
define the modifications. If you do not supply
this parameter, the update statements are read
from stdin. For information on supplying LDIF
update statements from the command-line,
refer to Section 2.2.1, “Providing Input from the
Command-Line”.
Table 2.2. ldapmodify Parameters Used for Adding Entries
For full information on ldapmodify parameters, see the Directory Server Configuration, Command,
and File Reference.
2.2.4.2. Modifying Entries Using ldapmodify
Typically, to edit entries using ldapmodify, specify the DN and password to bind to the Directory
Server, the port and host of the Directory Server, and the LDIF file to use, as when adding entries with
ldapmodify. For example:
ldapmodify -D "cn=Directory Manager" -w King-Pin -h cyclops -p 845 -f modify_statements
This ldapmodify example has the following values:
• The entries to modify are specified in the file modify_statements. Before the entries can be
modified, you must first create the modify_statements file with the appropriate LDIF update
statements; LDIF update statements are described in Section 2.4, “LDIF Update Statements”.
• The bind DN is cn=Directory Manager, which has permissions to edit any entry in the database,
and the password is King-Pin.
• The hostname is cyclops.
• The server uses port number 845.
Table 2.3, “ldapmodify Parameters Used for Modifying Entries” describes the ldapmodify
parameters used in the example.
Parameter Name Description
-D Specifies the distinguished name with which to
authenticate to the server. The value must be
a DN recognized by the Directory Server, and
it must also have the authority to modify the
entries.
-w Specifies the password associated with
the distinguished name specified in the -D
parameter.
-h Specifies the name of the host on which the
server is running.
-p Specifies the port number that the server uses.
Page 43
Deleting Entries Using ldapdelete
25
Parameter Name Description
-f Optional parameter that specifies the file
containing the LDIF update statements used to
define the modifications. If you do not supply
this parameter, the update statements are read
from stdin. For information on supplying LDIF
update statements from the command-line,
refer to Section 2.2.1, “Providing Input from the
Command-Line”.
Table 2.3. ldapmodify Parameters Used for Modifying Entries
For full information on ldapmodify parameters, see the Directory Server Configuration, Command,
and File Reference.
2.2.5. Deleting Entries Using ldapdelete
The ldapdelete command-line utility opens a connection to the specified server using the provided
distinguished name and password and deletes the specified entry or entries.
NOTE
You can only delete entries at the end of a branch. You cannot delete entries that are
branch points in the directory tree.
For example, of the following three entries, only the last two entries can be deleted.
ou=People,dc=example,dc=com
cn=Paula Simon,ou=People,dc=example,dc=com
cn=Jerry O'Connor,ou=People,dc=example,dc=com
The entry that identifies the People subtree can be deleted only if there are not any entries below
it. To delete ou=People,dc=example,dc=com, you must first delete Paula Simon and Jerry
O'Connor's entries and all other entries in that subtree.
Like ldapmodify, running ldapdelete requires the DN and password to bind to the Directory
Server, the port and host of the Directory Server, and the DNs of the entries to delete. For example:
ldapdelete -D "cn=Directory Manager" -w King-Pin -h cyclops -p 845 "cn=Robert
Jenkins,ou=People,dc=example,dc=com" "cn=Lisa
Jangles,ou=People,dc=example,dc=com"
This ldapdelete example has the following values:
• The entries tp delete have the DNs cn=Robert Jenkins,ou=People,dc=example,dc=com
and cn=Lisa Jangles, ou=People,dc=example,dc=com.
• The bind DN is the Directory Manager, which has permission to delete every entry in the database,
and a password of King-Pin.
• The hostname is cyclops.
• The server uses port number 845.
Page 44
Chapter 2. Creating Directory Entries
26
Table 2.4, “ldapdelete Parameters Used for Deleting Entries” describes the ldapdelete parameters
used in the example:
Parameter Name Description
-D Specifies the distinguished name with which to
authenticate to the server. The value must be
a DN recognized by the Directory Server, and
it must also have the authority to modify the
entries.
-w Specifies the password associated with
the distinguished name specified in the -D
parameter.
-h Specifies the name of the host on which the
server is running.
-p Specifies the port number that the server uses.
Table 2.4. ldapdelete Parameters Used for Deleting Entries
For full information on ldapdelete parameters, see the Directory Server Configuration, Command,
and File Reference.
2.2.6. Using Special Characters
When using the Directory Server command-line client tools, you may need to specify values that
contain characters that have special meaning to the command-line interpreter, such as space ( ),
asterisk (*), or backslash (\). When this situation occurs, enclose the value in quotation marks ("").
For example:
-D "cn=Barbara Jensen,ou=Product Development,dc=example,dc=com"
Depending on the command-line utility, use either single or double quotation marks; see your
operating system documentation for more information.
Additionally, if a DN contains commas, you must escape the commas with a backslash (\). For
example:
-D "cn=Patricia Fuentes,ou=people,o=example.com Bolivia\,S.A."
To delete user Patricia Fuentes from the example.com Bolivia, S.A. tree, use the following
command:
ldapdelete -D "cn=Directory Manager" -w King-Pin -h cyclops -p 845 "cn=Patricia
Fuentes,ou=People,o=example.com Bolivia\,S.A."
2.3. Tracking Modifications to Directory Entries
You can configure the server to maintain special attributes for newly created or modified entries:
• creatorsName. The distinguished name of the person who initially created the entry.
• createTimestamp. The timestamp for when the entry was created in GMT (Greenwich Mean Time)
format.
Page 45
LDIF Update Statements
27
• modifiersName. The distinguished name of the person who last modified the entry.
• modifyTimestamp. The timestamp for when the entry was last modified in GMT format.
NOTE
When a database link is used by a client application to create or modify entries, the
creatorsName and modifiersName attributes do not reflect the real creator or modifier
of the entries. These attributes contain the name of the administrator who is granted proxy
authorization rights on the remote server. For information on proxy authorization, see
Section 3.3.2.2.2, “Providing Bind Credentials”.
Do the following to enable the Directory Server to track when entries are created or modified:
1. In the Directory Server Console, select the Configuration tab, and then select the top entry in the
navigation tree in the left pane.
2. Select the Settings tab in the right pane.
3. Select the Track Entry Modification Times checkbox.
The server adds the creatorsName, createTimestamp, modifiersName, and
modifyTimestamp attributes to every newly created or modified entry.
4. Click Save.
5. Open the Tasks tab, and click Restart Directory Server.
NOTE
The Directory Server must be restarted for the changes to take effect.
2.4. LDIF Update Statements
LDIF update statements define how ldapmodify changes the directory entry. In general, LDIF
update statements contain the following information:
• The DN of the entry to be modified.
•
A changetype that defines how a specific entry is to be modified (add, delete, modify, modrdn).
• A series of attributes and their changed values.
A change type is required unless ldapmodify is run with the -a parameter. If you specify the -a
parameter, then an add operation (changetype: add) is assumed. However, any other change type
overrides the -a parameter.
If you specify a modify operation (changetype: modify), a change operation is required that
indicates how the entry should be changed.
If you specify changetype: modrdn, change operations are required that specify how the relative
distinguished name (RDN) is to be modified. A distinguished name's RDN is the left-most value in the
Page 46
Chapter 2. Creating Directory Entries
28
DN. For example, the distinguished name uid=ssarette,dc=example,dc=com has an RDN of
uid=ssarette.
The general format of LDIF update statements is as follows:
dn: distinguished_name
changetype: changetype_identifier
change_operation_identifier: list_of_attributes
-
change_operation_identifier: list_of_attributes
-
A dash (-) must be used to denote the end of a change operation if subsequent change operations are
specified. For example, the following statement adds the telephone number and manager attributes to
the entry:
dn: cn=Lisa Jangles,ou=People,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: (408) 555-2468
-
add: manager
manager: cn=Harry Cruise,ou=People,dc=example,dc=com
In addition, the line continuation operator is a single space. Therefore, the following two statements
are identical:
dn: cn=Lisa Jangles,ou=People,dc=example,dc=com
dn: cn=Lisa Jangles,
ou=People,
dc=example,dc=com
The following sections describe the change types in detail.
2.4.1. Adding an Entry Using LDIF
changetype: add adds an entry to the directory. When you add an entry, make sure to create an
entry representing a branch point before you try to create new entries under that branch. That is, to
place an entry in a People and a Groups subtree, then create the branch point for those subtrees
before creating entries within the subtrees. For example:
dn: dc=example,dc=com
changetype: add
objectclass: top
objectclass: organization
o: example.com
dn: ou=People, dc=example,dc=com
changetype: add
objectclass: top
objectclass: organizationalUnit
ou: People
ou: Marketing
dn: cn=Pete Minsky,ou=People,dc=example,dc=com
changetype: add
objectclass: top
Page 47
Renaming an Entry Using LDIF
29
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Pete Minsky
givenName: Pete
sn: Minsky
ou: People
ou: Marketing
uid: pminsky
dn: cn=Sue Jacobs,ou=People,dc=example,dc=com
changetype: add
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Sue Jacobs
givenName: Sue
sn: Jacobs
ou: People
ou: Marketing
uid: sjacobs
dn: ou=Groups,dc=example,dc=com
changetype: add
objectclass: top
objectclass: organizationalUnit
ou: Groups
dn: cn=Administrators,ou=Groups,dc=example,dc=com
changetype: add
objectclass: top
objectclass: groupOfNames
member: cn=Sue Jacobs,ou=People,dc=example,dc=com
member: cn=Pete Minsky,ou=People,dc=example,dc=com
cn: Administrators
dn: ou=example.com Bolivia\, S.A.,dc=example,dc=com
changetype: add
objectclass: top
objectclass: organizationalUnit
ou: example.com Bolivia\, S.A.
dn: cn=Carla Flores,ou=example.com Bolivia\,S.A.,dc=example,dc=com
changetype: add
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Carla Flores
givenName: Carla
sn: Flores
ou: example.com Bolivia\, S.A.
uid: cflores
2.4.2. Renaming an Entry Using LDIF
changetype: modrdn changes an entry's relative distinguished name (RDN). An
entry's RDN is the left-most element in the distinguished name. The RDN for cn=Barry
Nixon,ou=People,dc=example,dc=com is cn=Barry Nixon, and the RDN for
ou=People,dc=example,dc=com is ou=People. A changetype: modrdn operation changes
that left-most value in an entry's DN.
Page 48
Chapter 2. Creating Directory Entries
30
The modrdn change type only changes teh RDN; it cannot change other parts of a DN. For
example, the entry cn=Sue Jacobs,ou=People,dc=example,dc=com can be changed to
cn=Susan Jacobs,ou=People,dc=example,dc=coma, but it cannot be modified to be cn=Sue
Jacobs,ou=old employees,dc=example,dc=com.
The following command renames Sue Jacobs to Susan Jacobs:
dn: cn=Sue Jacobs,ou=Marketing,dc=example,dc=com
changetype: modrdn
newrdn: cn=Susan Jacobs
deleteoldrdn: 0
Because deleteoldrdn is 0, this example retains the existing RDN as a value in the new entry. The
resulting entry would therefore have a common name (cn) attribute set to both Sue Jacobs and Susan
Jacobs, in addition to all the other attributes included in the original entry. However, using the following
command causes the server to delete cn=Sue Jacobs, so that only cn=Susan Jacobs remains in
the entry:
dn: cn=Sue Jacobs,ou=Marketing,dc=example,dc=com
changetype: modrdn
newrdn: cn=Susan Jacobs
deleteoldrdn: 1
2.4.2.1. A Note on Renaming Entries
The modrdn change type cannot move an entry to a completely different subtree. To move an entry
to a completely different branch, you must create a new entry in the alternative subtree using the old
entry's attributes, and then delete the old entry.
Also, for the same reasons that you cannot delete an entry if it is a branch point, you cannot rename
an entry if it has any children. Doing so would orphan the children in the tree, which is not allowed
by the LDAP protocol. For example, of the following three entries, only the last two entries can be
renamed:
ou=People,dc=example,dc=com
cn=Paula Simon,ou=People,dc=example,dc=com
cn=Jerry O'Connor,ou=People,dc=example,dc=com
The entry that identifies the People subtree can be renamed only if no other entries exist below it.
2.4.3. Modifying an Entry Using LDIF
changetype: modify can add, replace, or remove attributes or attribute values in an entry. When
you specify changetype: modify, you must also provide a change operation to indicate how the
entry is to be modified. Change operations can be as follows:
•
add: attribute
Adds the specified attribute or attribute value. If the attribute type does not currently exist for
the entry, then the attribute and its corresponding value are created. If the attribute type already
exists for the entry, then the specified attribute value is added to the existing value. If the particular
attribute value already exists for the entry, then the operation fails, and the server returns an error.
•
replace: attribute
Page 49
Modifying an Entry Using LDIF
31
The specified values are used to entirely replace the attribute's values. If the attribute does not
already exist, it is created. If no replacement value is specified for the attribute, the attribute is
deleted.
•
delete: attribute
The specified attribute is deleted. If more than one value of an attribute exists for the entry, then all
values of the attribute are deleted in the entry. To delete just one of many attribute values, specify
the attribute and associated value on the line following the delete change operation.
This section contains the following topics:
• Section 2.4.3.1, “Adding Attributes to Existing Entries Using LDIF”
• Section 2.4.3.2, “Changing an Attribute Value Using LDIF”
• Section 2.4.3.3, “Deleting All Values of an Attribute Using LDIF”
• Section 2.4.3.4, “Deleting a Specific Attribute Value Using LDIF”
2.4.3.1. Adding Attributes to Existing Entries Using LDIF
Using changetype: modify with the add operation cam add an attribute and an attribute value to
an entry. For example, the following LDIF update statement adds a telephone number to the entry:
dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: 555-1212
The following example adds two telephone numbers to the entry:
dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: 555-1212
telephonenumber: 555-6789
The following example adds two telephonenumber attributes and a manager attribute to the entry:
dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: 555-1212
telephonenumber: 555-6789
add: manager
manager: cn=Sally Nixon,ou=People,dc=example,dc=com
The following example adds a jpeg photograph to the directory. To add this attribute to the directory,
use the -b parameter, which indicates that ldapmodify should read the referenced file for binary
values if the attribute value begins with a slash:
dn: cn=Barney Fife,ou=People,dc=example,dc=com
Page 50
Chapter 2. Creating Directory Entries
32
changetype: modify
add: jpegphoto
jpegphoto: /path/to/photo
You can also add a jpeg photograph to the directory using the following standard LDIF notation:
jpegphoto: < file:/path/to/photo
Using the standard notation means that the -b parameter does not need to be used withldapmodify.
However, you must add version:1 to the beginning of the LDIF file or with LDIF update statements.
For example:
ldapmodify -D userDN -w user_password
version: 1
dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
add: userCertificate
userCertificate;binary:< file: BarneysCert
NOTE
Standard LDIF notation can only be used with the ldapmodify command, not with other
command-line utilities.
2.4.3.2. Changing an Attribute Value Using LDIF
changetype: modify with the replace operation changes all values of an attribute in an entry. For
example, the following LDIF update statement changes Barney's manager from Sally Nixon to Wally
Hensford:
dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
replace: manager
manager: cn=Wally Hensford, ou=People, dc=example,dc=com
If the entry has multiple instances of the attribute, then to change one of the attribute values, you must
delete the attribute value first and then add the replacement value. For example, this entry has two
telephone nubmers:
cn=Barney Fife,ou=People,dc=example,dc=com
objectClass: inetOrgPerson
cn: Barney Fife
sn: Fife
telephonenumber: 555-1212
telephonenumber: 555-6789
To change the telephone number 555-1212 to 555-4321, use the following LDIF update statement:
dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
delete: telephonenumber
telephonenumber: 555-1212
-
Page 51
Modifying an Entry Using LDIF
33
add: telephonenumber
telephonenumber: 555-4321
The entry is now as follows:
cn=Barney Fife,ou=People,dc=example,dc=com
objectClass: inetOrgPerson
cn: Barney Fife
sn: Fife
telephonenumber: 555-6789
telephonenumber: 555-4321
2.4.3.3. Deleting All Values of an Attribute Using LDIF
changetype: modify with the delete operation deletes an attribute from an entry. If the entry has
more than one instance of the attribute, you must indicate which of the attributes to delete.
For example, the following LDIF update statement deletes all instances of the telephonenumber
attribute from the entry, regardless of how many times it appears in the entry:
dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
delete: telephonenumber
To delete just a specific instance of the telephonenumber attribute, simply delete that specific
attribute value, as described in the next section.
2.4.3.4. Deleting a Specific Attribute Value Using LDIF
Running changetype: modify with the delete operation can delete a single value for an attribute
value from an entry, as well as deleting all instances of the attribute. For example, consider the
following entry:
cn=Barney Fife,ou=People,dc=example,dc=com
objectClass: inetOrgPerson
cn: Barney Fife
sn: Fife
telephonenumber: 555-1212
telephonenumber: 555-6789
To delete the 555-1212 telephone number from this entry, use the following LDIF update statement:
dn: cn=Barney Fife,ou=People,dc=example,dc=com
changetype: modify
delete: telephonenumber
telephonenumber: 555-1212
Barney's entry then becomes:
cn=Barney Fife,ou=People,dc=example,dc=com
objectClass: inetOrgPerson
cn: Barney Fife
sn: Fife
telephonenumber: 555-6789
Page 52
Chapter 2. Creating Directory Entries
34
2.4.4. Deleting an Entry Using LDIF
changetype: delete is the change type which deletes an entire entry from the directory.
NOTE
You can only delete leaf entries. Therefore, when you delete an entry, make sure that
no other entries exist under that entry in the directory tree. That is, you cannot delete an
organizational unit entry unless you have first deleted all the entries that belong to the
organizational unit.
For example, of the following three entries, only the last two entries can be deleted:
ou=People,dc=example,dc=com
cn=Paula Simon,ou=People,dc=example,dc=com
cn=Jerry O'Connor,ou=People,dc=example,dc=com
The entry that identifies the People subtree can be deleted only if no other entries exist below it.
The following LDIF update statements can be used to delete person entries:
dn: cn=Pete Minsky,ou=People,dc=example,dc=com
changetype: delete
dn: cn=Sue Jacobs,ou=People,dc=example,dc=com
changetype: delete
WARNING
Do not delete the suffix o=NetscapeRoot. The Administration Server uses this suffix to
store information about installed Directory Servers. Deleting this suffix could force you to
reinstall the Directory Server.
2.4.5. Modifying an Entry in an Internationalized Directory
If the attribute values in the directory are associated with languages other than English, the attribute
values are associated with language tags. When using the ldapmodify command-line utility to
modify an attribute that has an associated language tag, you must match the value and language tag
exactly or the modify operation will fail.
For example, to modify an attribute value that has a language tag of lang-fr, include lang-fr in the
modify operation, as follows:
dn: bjensen,dc=example,dc=com
changetype: modify
replace: homePostalAddress;lang-fr
homePostalAddress;lang-fr: 34 rue de Seine
2.5. Maintaining Referential Integrity
Referential integrity is a database mechanism that ensures relationships between related entries are
maintained. In the Directory Server, the referential integrity can be used to ensure that an update to
one entry in the directory is correctly reflected in any other entries that may refer to the updated entry.
Page 53
How Referential Integrity Works
35
For example, if a user's entry is removed from the directory and referential integrity is enabled, the
server also removes the user from any groups of which the user is a member. If referential integrity
is not enabled, the user remains a member of the group until manually removed by the administrator.
This is an important feature if you are integrating the Directory Server with other products that rely on
the directory for user and group management.
2.5.1. How Referential Integrity Works
When the Referential Integrity Plug-in (see Section 16.1.26, “Referential Integrity Postoperation Plug-
in”) is enabled, it performs integrity updates on specified attributes immediately after a delete or
rename operation. By default, the Referential Integrity Plug-in is disabled.
NOTE
The Referential Integrity Plug-in should only be enabled on one supplier replica in a multimaster replication environment to avoid conflict resolution loops. When enabling the plugin on servers issuing chaining requests, be sure to analyze performance resource and
time needs, as well as your integrity needs. Integrity checks can be time-consuming and
draining on memory and CPU.
Whenever a user or group entry is deleted or renamed in the directory, the operation is logged to
the referential integrity log file (/var/log/dirsrv/slapd-instance_name). After a specified
time, known as the update interval, the server performs a search on all attributes for which referential
integrity is enabled and matches the entries resulting from that search with the DNs of deleted
or modified entries present in the log file. If the log file shows that the entry was deleted, the
corresponding attribute is deleted. If the log file shows that the entry was changed, the corresponding
attribute value is modified accordingly.
By default, when the Referential Integrity Plug-in is enabled, it performs integrity updates on the
member, uniquemember, owner, and seeAlso attributes immediately after a delete or rename
operation. However, the behavior of the Referential Integrity Plug-in can be configured to suit the
needs of the directory in several different ways:
• Record referential integrity updates in the replication changelog.
• Modify the update interval.
• Select the attributes to which to apply referential integrity.
• Disable referential integrity.
All attributes used in referential integrity must be indexed for presence and equality; not indexing
those attributes results poor server performance for modify and delete operations. See Section 10.2,
“Creating Indexes” for more information about checking and creating indexes.
2.5.2. Using Referential Integrity with Replication
There are certain limitations when using the Referential Integrity Plug-in in a replication environment:
• Never enable it on a dedicated consumer server (a server that contains only read-only replicas).
• Never enable it on a server that contains a combination of read-write and read-only replicas.
Page 54
Chapter 2. Creating Directory Entries
36
• It is possible to enable it on a supplier server that contains only read-write replicas.
• With multi-master replication, enable the plug-in on just one supplier.
If the replication environment satisfies the all of those condition, you can enable the Referential
Integrity Plug-in.
1. Enable the Referential Integrity Plug-in as described in Section 2.5.3, “Enabling/Disabling
Referential Integrity”.
2. Configure the plug-in to record any integrity updates in the changelog.
3. Ensure that the Referential Integrity Plug-in is disabled on all consumer servers.
NOTE
Because the supplier server sends any changes made by the Referential Integrity
Plug-in to consumer servers, it is unnecessary to run the Referential Integrity Plug-in
on consumer servers.
2.5.3. Enabling/Disabling Referential Integrity
You can enable or disable referential integrity as follows:
1. Start the Directory Server Console. See Section 1.4, “Starting the Directory Server Console”.
2. Select the Configuration tab.
3. Expand the Plugins folder in the navigation tree, and select Referential Integrity Postoperation
Plug-in from the list.
The settings for the plug-in are displayed in the right pane.
4. Check the Enable plugin checkbox to enable the plug-in; clear it to disable it.
5. Click Save.
6. For your changes to be applied, go to the Tasks tab, and select Restart the Directory Server.
2.5.4. Modifying the Update Interval
By default, the server makes referential integrity updates immediately after a delete or a modrdn
operation. To reduce the impact this operation has on your system, increase the amount of time
between updates. Although there is no maximum update interval, the following intervals are commonly
used:
• Update immediately
• 90 seconds
• 3600 seconds (updates occur every hour)
• 10,800 seconds (updates occur every 3 hours)
• 28,800 seconds (updates occur every 8 hours)
Page 55
Modifying the Attribute List
37
• 86,400 seconds (updates occur once a day)
• 604,800 seconds (updates occur once a week)
To modify the update interval, do the following:
1. Start the Directory Server Console. See Section 1.4, “Starting the Directory Server Console”.
2. Select the Configuration tab.
3. Expand the Plugins folder in the navigation tree, and select the Referential Integrity
Postoperation Plug-in.
The settings for the plug-in are displayed in the right pane.
4. In the arguments list, replace the value in the first text box with the appropriate time interval.
5. Click Save.
6. For your changes to be applied, go to the Tasks tab, and click Restart the Directory Server.
2.5.5. Modifying the Attribute List
By default, the Referential Integrity Plug-in is set up to check for and update the member,
uniquemember, owner, and seeAlso attributes. You can add or delete attributes to be updated
through the Directory Server Console, such as adding the nsroledn attribute if roles are being used.
NOTE
Keep in mind that any attribute specified in the Referential Integrity Plug-in parameter list
must have equality indexing on all databases. Otherwise, the plug-in scans every entry of
the databases for matching the deleted or modified DN, degrading performance severely.
If you add an attribute, ensure that it is indexed in all the backends.
TIP
Improve the performance by removing any unused attributes from the list.
1. Start the Directory Server Console. See Section 1.4, “Starting the Directory Server Console”.
2. Select the Configuration tab.
3. Expand the Plugins folder in the navigation tree, and select the Referential Integrity
Postoperation Plug-in.
The settings for the plug-in are displayed in the right pane.
4. In the Arguments section, use the Add and Delete buttons to modify the attributes in the list.
5. Click Save.
6. For your changes to be applied, go to the Tasks tab, and select Restart the Directory Server.
Page 56
Chapter 2. Creating Directory Entries
38
NOTE
All attributes used in referential integrity must be indexed for presence and equality;
not indexing those attributes results poor server performance for modify and delete
operations. See Section 10.2, “Creating Indexes” for more information about checking and
creating indexes.
Page 57
Chapter 3.
39
Configuring Directory Databases
The directory is made up of databases, and the directory tree is distributed across the databases. This
chapter describes how to create suffixes, the branch points for the directory tree, and how to create
the databases associated with each suffix. This chapter also describes how to create database links to
reference databases on remote servers and how to use referrals to point clients to external sources of
directory data.
3.1. Creating and Maintaining Suffixes
Different pieces of the directory tree can be stored in different databases, and then these databases
can be distributed across multiple servers. The directory tree contains branch points called nodes.
These nodes may be associated with databases. A suffix is a node of the directory tree associated
with a particular database. For example, a simple directory tree might appear as illustrated in
Figure 3.1, “A Sample Directory Tree with One Root Suffix”.
Figure 3.1. A Sample Directory Tree with One Root Suffix
The ou=people suffix and all the entries and nodes below it might be stored in one database, the
ou=groups suffix on another database, and the ou=contractors suffix on yet another database.
This section describes creating suffixes on Directory Server and associating them with databases.
• Section 3.1.1, “Creating Suffixes”
• Section 3.1.2.1, “Using Referrals in a Suffix”
3.1.1. Creating Suffixes
Both root and sub suffixes can be created to organize the contents of the directory tree. A root suffix is
the parent of a sub suffix. It can be part of a larger tree designed for the Directory Server. A sub suffix
is a branch underneath a root suffix. The data for root and sub suffixes are contained by databases.
A directory might contain more than one root suffix. For example, an ISP might host several
websites, one for example.com and one for redhat.com. The ISP would create two root suffixes,
Page 58
Chapter 3. Configuring Directory Databases
40
one corresponding to the dc=example,dc=com naming context and one corresponding to the
dc=redhat,dc=com naming context, as shown in Figure 3.2, “A Sample Directory Tree with Two
Root Suffixes”.
Figure 3.2. A Sample Directory Tree with Two Root Suffixes
It is also possible to create root suffixes to exclude portions of the directory tree from search
operations. For example, Example Corporation wants to exclude their European office from a search
on the general Example Corporation directory. To do this, they create two root suffixes. One root suffix
corresponds to the general Example Corporation directory tree, dc=example,dc=com, and one root
suffix corresponds to the European branch of their directory tree, l=europe,dc=example,dc=com.
From a client application's perspective, the directory tree looks as illustrated in Figure 3.3, “A Sample
Directory Tree with a Root Suffix Off Limits to Search Operations”.
Figure 3.3. A Sample Directory Tree with a Root Suffix Off Limits to Search Operations
Searches performed by client applications on the dc=example,dc=com branch of Example
Corporation's directory will not return entries from the l=europe,dc=example,dc=com branch of
the directory, as it is a separate root suffix.
If Example Corporation decides to include the entries in the European branch of their directory tree
in general searches, they make the European branch a sub suffix of the general branch. To do this,
they create a root suffix for Example Corporation, dc=example,dc=com, and then create a sub suffix
beneath it for their European directory entries, l=europe,dc=example,dc=com. From a client
application's perspective, the directory tree appears as illustrated in Figure 3.4, “A Sample Directory
Tree with a Sub Suffix”.
Page 59
Creating Suffixes
41
Figure 3.4. A Sample Directory Tree with a Sub Suffix
This section describes creating root and sub suffixes for the directory using either the Directory Server
Console or the command line.
• Section 3.1.1.1, “Creating a New Root Suffix Using the Console”
• Section 3.1.1.2, “Creating a New Sub Suffix Using the Console”
• Section 3.1.1.3, “Creating Root and Sub Suffixes from the Command Line”
3.1.1.1. Creating a New Root Suffix Using the Console
1. In the Directory Server Console, select the Configuration tab.
2. Right-click Data in the left navigation pane, and select New Root Suffix from the pop-up menu.
The Create new root suffix dialog box is displayed.
3. Enter a unique suffix in the New suffix field.
The suffix must be named with dc naming conventions, such as dc=example,dc=com.
4. Select the Create associated database automatically to create a database at the same time
as the new root suffix, an enter a unique name for the new database in the Database name field,
such as example2. The name can be a combination of alphanumeric characters, dashes (-), and
underscores (_). No other characters are allowed.
Deselect the checkbox to create a database for the new root suffix later. This option specifies a
directory where the database will be created. The new root suffix will be disabled until a database
is created.
5. Click OK.
The suffix appears automatically under the Data tree in the left navigation pane.
Page 60
Chapter 3. Configuring Directory Databases
42
3.1.1.2. Creating a New Sub Suffix Using the Console
1. In the Directory Server Console, select the Configuration tab.
2. Under the Data in the left navigation pane, select the suffix under which to add a new sub suffix.
Right-click the suffix, and select New Sub Suffix from the pop-up menu.
The Create new sub suffix dialog box is displayed.
3. Enter a unique suffix name in the New suffix field. The suffix must be named in line with dc
naming conventions, such as ou=groups.
The root suffix is automatically added to the name. For example, it the sub suffix ou=groups
is created under the dc=example,dc=com suffix, the Console automatically names it
ou=groups,dc=example,dc=com.
4. Select the Create associated database automatically checkbox to create a database at the
same time as the new sub suffix, and enter a unique name for the new database in the Database
name field, such as example2. The name can be a combination of alphanumeric characters,
dashes (-), and underscores (_). No other characters are allowed.
Deselect the checkbox to create a database for the new sub suffix later. The new sub suffix will be
disabled until a database is created.
5. Click OK.
The suffix appears automatically under its root suffix in the Data tree in the left navigation pane.
3.1.1.3. Creating Root and Sub Suffixes from the Command Line
Use the ldapmodify command-line utility to add new suffixes to the directory configuration file. The
suffix configuration information is stored in the cn=mapping tree,cn=config entry.
NOTE
Avoid creating entries under the cn=config entry in the dse.ldif file. The cn=config
entry in the simple, flat dse.ldif configuration file is not stored in the same highly
scalable database as regular entries. As a result, if many entries, particularly entries that
are likely to be updated frequently, are stored under cn=config, performance will suffer.
1. Add a new root suffix to the configuration file using the ldapmodify utility.
1
ldapmodify -a -h example1 -p 389 -D "cn=directory manager" -w secret
ldapmodify binds to the server and prepares it to add an entry to the configuration file.
2. Create the root suffix entry.
dn: cn="dc=example,dc=com",cn=mapping tree,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: UserData
Page 61
Creating Suffixes
43
cn: dc=example,dc=com
Example 3.1. Example Root Suffix Entry
3. Create a sub suffix for groups under this root suffix using ldapmodify to add the sub suffix entry:
dn: cn="ou=groups,dc=example,dc=com",cn=mapping tree,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: GroupData
nsslapd-parent-suffix: "dc=example,dc=com"
cn: "ou=groups,dc=example,dc=com"
NOTE
To maintain suffixes using the Directory Server Console, respect the same spacing used
to name the root and sub suffixes in the command line. For example, if a root suffix is
named ou=groups ,dc=example,dc=com, with two spaces after groups, any sub
suffixes created under this root will need to specify two spaces after ou=groups, as well.
The following table describes the attributes used to configure a suffix entry:
Attribute Name Value
dn Defines the DN for the suffix. The DN is
contained in quotes. The value entered takes the
form cn="dc=domain,dc=com",cn=mapping
tree, cn=config. This attribute is required.
cn Defines the relative DN (RDN) of the entry. This
attribute is required.
objectclass Tells the server that the entry is root or
sub suffix entry. It always takes the value
nsMappingTree. This attribute is required.
nsslapd-state Determines how the suffix handles operations.
This attribute takes the following values:
• backend: The backend (database) is used to
process all operations.
• disabled: The database is not available for
processing operations. The server returns a
No such search object error in response to
requests made by client applications.
• referral: A referral is returned for requests
made to this suffix.
• referral on update: The database is
used for all operations except update requests,
which receive a referral.
Page 62
Chapter 3. Configuring Directory Databases
44
Attribute Name Value
The default value is disabled.
nsslapd-referral Defines the LDAP URL of the referral to be
returned by the suffix. This attribute can be multivalued, with one referral per value. This attribute
is required when the value of the nsslapd-
state attribute is referral or referral on
update.
nsslapd-backend Gives the name of the database or database
link used to process requests. This attribute can
be multi-valued, with one database or database
link per value. See Section 3.3, “Creating and
Maintaining Database Links” for more information
about database links. This attribute is required
when the value of the nsslapd-state attribute
is set to backend or referral on update.
nsslapd-distribution-plugin Specifies the shared library to be used with the
custom distribution function. This attribute is
required only when more than one database is
specified in the nsslapd-backend attribute.
See Section 3.2, “Creating and Maintaining
Databases” for more information about the
custom distribution function.
nsslapd-distribution-funct Specifies the name of the custom distribution
function. This attribute is required only when
more than one database is specified in the
nsslapd-backend attribute. See Section 3.2,
“Creating and Maintaining Databases” for
more information about the custom distribution
function.
nsslapd-parent-suffix Provides the DN of the parent entry for a sub
suffix. By default, this attribute is not present,
which means that the suffix is regarded as a root
suffix. For example, to create a sub suffix names
o=sales,dc=example,dc=com under the root
suffix dc=example,dc=com, add nsslapd-
parent-suffix: "dc=example,dc=com" to
the sub suffix.
Table 3.1. Suffix Attributes
3.1.2. Maintaining Suffixes
This section describes the following procedures:
• Section 3.1.2.1, “Using Referrals in a Suffix”
• Section 3.1.2.2, “Enabling Referrals Only During Update Operations”
• Section 3.1.2.3, “Disabling a Suffix”
Page 63
Maintaining Suffixes
45
• Section 3.1.2.4, “Deleting a Suffix”
3.1.2.1. Using Referrals in a Suffix
Referrals can be used to point a client application temporarily to a different server. For example,
adding a referral to a suffix so that the suffix points to a different server allows the database associated
with the suffix is taken off-line for maintenance without affecting the users of the Directory Server
database.
To set referrals in a suffix, do the following:
1. In the Directory Server Console, select the Configuration tab.
2. Under Data in the left pane, select the suffix for which to add a referral.
3. Click the Suffix Settings tab, and select the Return Referrals for all Operations radio button.
4. Click the Referrals tab. Enter an LDAP URL in the Enter a new referral field, or click Construct
to be guided through the creation of an LDAP URL. Appendix C, LDAP URLs has more
information about the structure of LDAP URLs.
5. Click Add to add the referral to the list.
You can enter multiple referrals. The directory will return the entire list of referrals in response to
requests from client applications.
6. Click Save.
3.1.2.2. Enabling Referrals Only During Update Operations
It is possible to configure the directory to redirect update and write requests made by client
applications to a read-only database. For example, there may be a local copy of directory data, and
that data should be available company-wide for searches but not for updates. Enabling referrals for
that Directory Server only for update requests means that when a client application asks to update
an entry, the client is referred to the server that owns the data, where the modification request can
proceed.
To enable referrals only during update operations, do the following:
1. In the Directory Server Console, select the Configuration tab.
2. Under Data in the left pane, click the suffix to which to add a referral.
3. Click the Suffix Settings tab, and select the Return Referrals for Update Operations radio
button.
4. Click the Referrals tab. Enter an LDAP URL in the Enter a new referral field, or click Construct
to be guided through the creation of an LDAP URL.
For more information about the structure of LDAP URLs, refer to the Appendix.
5. Click Add to add the referral to the list.
You can enter multiple referrals. The directory will return the entire list of referrals in response to
requests from client applications.
Page 64
Chapter 3. Configuring Directory Databases
46
6. Click Save.
3.1.2.3. Disabling a Suffix
Sometimes, a database may need taken down for maintenance, but the data the database contains is
not replicated. Rather than returning a referral, disable the suffix responsible for the database.
Once a suffix is disabled, the contents of the database related to the suffix are invisible to client
applications when they perform LDAP operations such as search, add, and modify.
To disable a suffix, do the following:
1. In the Directory Server Console, select the Configuration tab.
2. Under Data in the left navigation pane, click the suffix to disable.
3. Click the Suffix Setting tab, and deselect the Enable this suffix checkbox.
4. Click Save.
The suffix is no longer enabled.
3.1.2.4. Deleting a Suffix
WARNING
Deleting a suffix also deletes all database entries and replication information associated
with that suffix.
1. In the Directory Server Console, select the Configuration tab.
2. Under Data in the left navigation pane, select the suffix to delete.
3. Select Delete from the Object menu.
Alternatively, right-click the suffix and select Delete from the pop-up menu.
4. Select Delete this suffix and all of its sub suffixes to remove all the suffix and every suffix
below it.
Select Delete this suffix only to remove only this particular suffix, not its sub suffixes.
5. Click OK.
3.2. Creating and Maintaining Databases
After creating suffixes to organizing the directory data, create databases to contain that directory data.
Databases are used to store directory data.
3.2.1. Creating Databases
The directory tree can be distributed over multiple Directory Server databases. There are two ways to
distribute data across multiple databases:
Page 65
Creating Databases
47
• One database per suffix. The data for each suffix is contained in a separate database.
Three databases are added to store the data contained in separate suffixes.
This division of the tree corresponds to three databases.
Database one contains the data for ou=people plus the data for dc=example,dc=com, so that
clients can conduct searches based at dc=example,dc=com. Database two contains the data for
ou=groups, and database three contains the data for ou=contractors.
• Multiple databases for one suffix.
Page 66
Chapter 3. Configuring Directory Databases
48
Suppose the number of entries in the ou=people branch of the directory tree is so large that two
databases are needed to store them. In this case, the data contained by ou=people could be
distributed across two databases.
DB1 contains people with names from A-K, and DB2 contains people with names from L-Z. DB3
contains the ou=groups data, and DB4 contains the ou=contractors data.
Custom distribution plug-in distributes data from a single suffix across multiple databases. Contact
Red Hat Professional Services for information on how to create distribution logic for Directory
Server.
3.2.1.1. Creating a New Database for an Existing Suffix Using the Console
1. In the Directory Server Console, select the Configuration tab.
2. In the left pane, expand Data, then click the suffix to which to add the new database.
3. Right-click the suffix, and select New Database from the pop-up menu.
The Create New Database dialog box is displayed.
4. In the Create New Database dialog box, enter a unique name for the database, such as
example2. The database name can be a combination of alphanumeric characters, dashes (-),
and underscores (_). No other characters are allowed.
5. In the Create database in field, enter the path to the directory to store the new database.
Alternatively, click Browse to locate a directory on the local machine.
By default, the directory stores the new database in the /var/lib/dirsrv/
slapd-instance_name/db directory.
6. Click OK. Click Yes in the confirmation dialog to create the new database.
Page 67
Creating Databases
49
3.2.1.2. Creating a New Database for a Single Suffix from the Command
Line
Use the ldapmodify command-line utility to add a new database to the directory
configuration file. The database configuration information is stored in the cn=ldbm
database,cn=plugins,cn=config entry.
For example, add a new database to the server example1:
1. Run ldapmodify:
1
ldapmodify -a -h example1 -p 389 -D "cn=directory manager" -w secret
The ldapmodify utility binds to the server and prepares it to add an entry to the configuration file.
2. Create the entry for the new database.
dn: cn=UserData,cn=ldbm database,cn=plugins,cn=config
objectclass: extensibleObject
objectclass: nsBackendInstance
nsslapd-suffix: ou=people,dc=example,dc=com
The entry added corresponds to a database named UserData that contains the data for the root
or sub suffix ou=people,dc=example,dc=com.
3. Create a root or sub suffix, as described in Section 3.1.1.3, “Creating Root and Sub Suffixes from
the Command Line”. The database name, given in the DN attribute, must correspond with the
value in the nsslapd-backend attribute of the suffix entry.
3.2.1.3. Adding Multiple Databases for a Single Suffix
A single suffix can be distributed across multiple databases. However, to distribute the suffix, a custom
distribution function has to be created to extend the directory. For more information on creating a
custom distribution function, contact Red Hat Professional Services.
NOTE
Once entries have been distributed, they cannot be redistributed. The following restrictions
apply:
• The distribution function cannot be changed once entry distribution has been deployed.
• The LDAP modrdn operation cannot be used to rename entries if that would cause
them to be distributed into a different database.
• Distributed local databases cannot be replicated.
• The ldapmodify operation cannot be used to change entries if that would cause them
to be distributed into a different database.
Violating these restrictions prevents Directory Server from correctly locating and returning
entries.
After creating a custom distribution logic plug-in, add it to the directory.
Page 68
Chapter 3. Configuring Directory Databases
50
The distribution logic is a function declared in a suffix. This function is called for every operation
reaching this suffix, including subtree search operations that start above the suffix. A distribution
function can be inserted into a suffix using both the Console and the command line.
3.2.1.3.1. Adding the Custom Distribution Function to a Suffix Using the
Directory Server Console
1. In the Directory Server Console, select the Configuration tab.
2. Expand Data in the left navigation pane. Select the suffix to which to apply the distribution
function.
3. Select the Databases tab in the right window.
4. Click Add to associate additional databases with the suffix.
The Database List dialog box is displayed. Select a database from the list, and click OK.
5. Enter the path to the distribution library in the Distribution library field, or click Browse to locate
a distribution library on the local machine.
6. Enter the name of the distribution function in the Function name field.
7. Click Save.
3.2.1.3.2. Adding the Custom Distribution Function to a Suffix Using the
Command Line
1. Run ldapmodify.
1
ldapmodify -p 389 -D "cn=directory manager" -w secret -h us.example.com
2. Add the following attributes to the suffix entry itself, supplying the information about the custom
distribution logic:
nsslapd-backend: Database1
nsslapd-backend: Database2
nsslapd-backend: Database3
nsslapd-distribution-plugin: /full/name/of/a/shared/library
nsslapd-distribution-funct:distribution-function-name
The nsslapd-backend attribute specifies all of the databases associated with this suffix. The
nsslapd-distribution-plugin attribute specifies the name of the library that the plug-
in uses. The nsslapd-distribution-funct attribute provides the name of the distribution
function itself.
For more information about using the ldapmodify command-line utility, see Section 2.2.4, “Adding
and Modifying Entries Using ldapmodify”.
3.2.2. Maintaining Directory Databases
This section describes jobs associated with maintaining directory databases. It includes the following
procedures:
Page 69
Maintaining Directory Databases
51
• Section 3.2.2.1, “Placing a Database in Read-Only Mode”
• Section 3.2.2.2, “Deleting a Database”
• Section 3.2.2.3, “Configuring Transaction Logs for Frequent Database Updates”
3.2.2.1. Placing a Database in Read-Only Mode
When a database is in read-only mode, you cannot create, modify, or delete any entries. One of the
situations when read-only mode is useful is for manually initializing a consumer or before backing up
or exporting data from the Directory Server. Read-only mode ensures a faithful image of the state of
these databases at a given time.
The Directory Server Console and the command-line utilities do not automatically put the directory
in read-only mode before export or backup operations because this would make your directory
unavailable for updates. However, with multi-master replication, this might not be a problem.
• Section 3.2.2.1.1, “Making a Database Read-Only Using the Console”
• Section 3.2.2.1.2, “Making a Database Read-Only from the Command Line”
• Section 3.2.2.1.3, “Placing the Entire Directory Server in Read-Only Mode”
3.2.2.1.1. Making a Database Read-Only Using the Console
To place a database in read-only mode from the Directory Server Console, do the following:
1. In the Directory Server Console, select the Configuration tab.
2. Expand Data in the left pane. Expand the suffix containing the database to put in read-only mode.
3. Select the database to put into read-only mode.
4. Select the Database Settings tab in the right pane.
5. Select the database is read-only checkbox.
6. Click Save.
The change takes effect immediately.
Before importing or restoring the database, ensure that the databases affected by the operation are
not in read-only mode.
To disable read-only mode, open the database up in the Directory Server Console again and uncheck
the database is read-only checkbox.
3.2.2.1.2. Making a Database Read-Only from the Command Line
To manually place a database into read-only mode, do the following:
1. Run ldapmodify.
1
ldapmodify -p 389 -D "cn=directory manager" -w secret -h us.example.com
2. Change the read-only attribute to on
Page 70
Chapter 3. Configuring Directory Databases
52
dn: cn=database_name,cn=ldbm database,cn=plugins,cn=config
changetype: modify
replace: nsslapd-readonly
nsslapd-readonly: on
NOTE
By default, the name of the database created at installation time is userRoot.
3.2.2.1.3. Placing the Entire Directory Server in Read-Only Mode
If the Directory Server maintains more than one database and all databases need to be placed in
read-only mode, this can be done in a single operation.
WARNING
This operation also makes the Directory Server configuration read-only; therefore, you
cannot update the server configuration, enable or disable plug-ins, or even restart the
Directory Server while it is in read-only mode. Once read-only mode is enabled, it cannot
cannot be undone from the Console; you must modify the configuration files.
NOTE
If Directory Server contains replicas, do not use read-only mode because it will disable
replication.
To put the Directory Server in read-only mode, do the following:
1. In the Directory Server Console, select the Configuration tab, and then select the top entry in the
navigation tree in the left pane.
2. Select the Settings tab in the right pane.
3. Select the Make Entire Server Read-Only checkbox.
4. Click Save, and then restart the server.
3.2.2.2. Deleting a Database
Deleting a database deletes the configuration information and entries for that database only, not the
physical database itself.
1. In the Directory Server Console, select the Configuration tab.
2. In the left navigation pane, locate the database to delete, and select it.
3. From the Object menu, select Delete.
Alternatively, right-click the database and select Delete from the pop-up menu.
Page 71
Maintaining Directory Databases
53
The Deleting Database confirmation dialog box is displayed.
4. Click Yes to confirm the deletion.
Once deleted, the database no longer appears in the right pane.
3.2.2.3. Configuring Transaction Logs for Frequent Database Updates
When the server is going to be asked to perform frequent database updates (LDAP adds, modifies,
replication), the database transaction log files should be configured to be on a different disk than the
primary database files.
Storing the transaction log files on a separate physical disk improves performance because the disk
heads do not thrash moving between the log files and the data files.
1. Stop the Directory Server instance.
/etc/init.d/dirsrv stop example
2. Create the new directory, if necessary, where the transaction logs will be located.
mkdir /home/exampledb-txnlogs
3. Set the appropriate file permissions on the directory so that the Directory Server user can access
it; the default Directory Server user and group are nobody:nobody.
chown nobody:nobody /home/exampledb-txnlogs
4. Open the Directory Server instance's configuration directory.
cd /etc/dirsrv/slapd-instance_name
5. Edit the dse.ldif file, and change the nsslapd-db-logdirectory directive for the new log
file path:
nsslapd-db-logdirectory: /home/exampledb-txnlogs
This attribute goes on the same entry that has the nsslapd-dbcachesize attribute.
6. Open the database directory.
cd /var/lib/dirsrv/slapd-instance_name/db
7. Remove all of the __db.* files.
8. Move the log.* files to the new location.
9. Start the Directory Server instance again.
/etc/init.d/dirsrv start example
Page 72
Chapter 3. Configuring Directory Databases
54
3.2.3. Database Encryption
The Directory Server offers a number of mechanisms to secure access to sensitive data, such as
access control rules to prevent unauthorized users from reading certain entries or attributes within
entries and SSL to protect data from eavesdropping and tampering on untrusted networks. However,
if a copy of the server's database files should fall into the hands of an unauthorized person, they could
potentially extract sensitive information from those files. Because information in a database is stored in
plain text, some sensitive information, such as government identification numbers or passwords, may
not be protected enough by standard access control measures.
For highly sensitive information, this potential for information loss could present a significant security
risk. In order to remove that security risk, Directory Server allows portions of its database to be
encrypted. Once encrypted, the data are safe even in the event that an attacker has a copy of the
server's database files.
Database encryption allows attributes to be encrypted in the database. Both encryption and the
encryption cipher are configurable per attribute per backend. When configured, every instance of a
particular attribute, even index data, is encrypted for every entry stored in that database.
NOTE
To enable database encryption on an attribute with existing stored data, export the
database to LDIF first, then make the configuration change, then re-import the data to
the database. The server does not enforce consistency between encryption configuration
and stored data; therefore, pay careful attention that all existing data are exported before
enabling or disabling encryption.
Indexed attributes may be encrypted, and database encryption is fully compatible with indexing. The
contents of the index files that are normally derived from attribute values are also encrypted to prevent
an attacker from recovering part or all of the encrypted data from an analysis of the indexes.
Since the server pre-encrypts all index keys before looking up an index for an encrypted attribute,
there is some effect on server performance for searches that make use of an encrypted index, but the
effect is not serious enough that it is no longer worthwhile to use an index.
3.2.3.1. Encryption Keys
In order to use database encryption, the server must be configured for SSL and have SSL enabled
because database encryption uses the server's SSL encryption key and the same PIN input methods
as SSL. The PIN must either be entered manually upon server startup or a PIN file must be used.
Randomly generated symmetric cipher keys are used to encrypt and decrypt attribute data. A separate
key is used for each configured cipher. These keys are wrapped using the public key from the server's
SSL certificate, and the resulting wrapped key is stored within the server's configuration files. The
effective strength of the database encryption is never higher than the strength of the server's SSL
key used for wrapping. Without access to the server's private key, it is not possible to recover the
symmetric keys from the wrapped copies.
Page 73
Database Encryption
55
WARNING
There is no mechanism for recovering a lost key. Therefore, it is especially important
to back up the server's certificate database safely. If the server's certificate were lost, it
would not be possible to decrypt any encrypted data stored in its database.
WARNING
If the SSL certificate is expiring and needs to be renewed, export the encrypted backend
instance before the renewal. Update the certificate, then re-import the exported LDIF file.
3.2.3.2. Encryption Ciphers
The encryption cipher is configurable on a per-attribute basis and must be selected by the
administrator at the time encryption is enabled for an attribute. Configuration can be done through the
Console or through the command line.
The following ciphers are supported:
• Advanced Encryption Standard (AES)
• Triple Data Encryption Standard (3DES)
All ciphers are used in Cipher Block Chaining mode.
Once the encryption cipher is set, it should not be changed without exporting and re-importing the
data.
3.2.3.3. Configuring Database Encryption from the Console
1. In the Console, open the Directory Server.
2. Open the Configuration tab, and select the Data node.
3. In the Data node, select the backend to edit, such as dc=example,dc=com.
4. Next, select the root to edit, such as o=userRoot.
5. Select the Attribute Encryption tab.
6. Hit the Add Attribute button, and a list of attributes will appear. Select the attribute to encrypt.
NOTE
For existing attribute entries to be encrypted, the information must be exported, then
re-imported. See Section 3.2.3.5, “Exporting and Importing an Encrypted Database”.
7. Select which encryption cipher to use.
8. Repeat steps 6 and 7 for every attribute to encrypt. Then hit Save.
Page 74
Chapter 3. Configuring Directory Databases
56
To remove encryption from attributes, select them from the list of encrypted attributes in the Attribute
Encryption table, and hit the Delete button, then hit Save to apply the changes. Any deleted
attributes have to be manually re-added after saving.
3.2.3.4. Configuring Database Encryption Using the Command Line
1. Run the ldapmodify command1:
ldapmodify -a -p 389 -D "cn=directory manager" -w secret -h us.example.com
2. Add an encryption entry for the attribute being encrypted. For example, this entry encrypts the
telephoneNumber attribute with the AES cipher:
dn: cn=telephoneNumber,cn=encrypted attributes,cn=Database1,cn=ldbm
database,cn=plugins,cn=config
objectclass: top
objectclass: nsAttributeEncryption
cn: telephoneNumber
nsEncryptionAlgorithm: AES
3. For existing attributes in entries to be encrypted, the information must be exported, then reimported. See Section 3.2.3.5, “Exporting and Importing an Encrypted Database”.
For more information on database encryption configuration schema, refer to "Database
Attributes under cn=attributeName,cn=encrypted attributes,cn=database_name,cn=ldbm
database,cn=plugins,cn=config" in the Directory Server Configuration, Command, and File Reference.
3.2.3.5. Exporting and Importing an Encrypted Database
Exporting and importing encrypted databases is similar to exporting and importing regular databases.
However, the encrypted information must be decrypted when it is exported to LDIF, then re-encrypted
when it is imported to the database. Using the -E option when running the db2ldif and ldif2db
scripts will decrypt the data on export and re-encrypt it on import.
1. Export the data using the db2ldif script, as follows:
db2ldif -n Database1 -E -a /path/to/output.ldif -s "dc=example,dc=com" -s "o=userRoot"
See Section 4.2.3, “Exporting to LDIF from the Command-Line” for more information.
2. Make any configuration changes.
3. Re-import the data using the ldif2db script, as follows:
ldif2db -n Database1 -E -i /path/to/output.ldif
See Section 4.1.4, “Importing from the Command-Line” for more information.
NOTE
When enabling encryption for data that is already present in the the database, several
additional security concerns arise:
Page 75
Creating and Maintaining Database Links
57
• It is possible for old, unencrypted data to persist in the server's database page pool
backing file, even after a successful re-import with encryption. To remove this data, stop
the server and delete the db/guardian file, then re-start the server. This will force
recovery, a side-effect of which is deleting the backing file. However, it is possible that
the data from the deleted file could still be recovered from the hard drive unless steps
are taken to overwrite the disk blocks that it occupied.
• After enabling encryption and importing data, be sure to delete the LDIF file because it
contains plain text values for the now-encrypted data. Ensure that the disk blocks that it
occupied are overwritten.
• The unencrypted data previously stored in the server's database may persist on disk
after a successful re-import with encryption. This is because the old database files
are deleted as part of the import process. Ensure that the disk blocks that those files
occupied are overwritten.
• Data stored in the server's replication log database is never encrypted; therefore, care
should be taken to protect those files if replication is used.
• The server does not attempt to protect unencrypted data stored in memory. This data
may be copied into a system page file by the operating system. For this reason, ensure
that any page or swap files are adequately protected.
3.3. Creating and Maintaining Database Links
Chaining means that a server contacts other servers on behalf of a client application and then returns
the combined results. Chaining is implemented through a database link, which points to data stored
remotely. When a client application requests data from a database link, the database link retrieves the
data from the remote database and returns it to the client.
Section 13.5, “Monitoring Database Link Activity” covers how to monitor database link activity.
• Section 3.3.1, “Configuring the Chaining Policy”
• Section 3.3.2, “Creating a New Database Link”
• Section 3.3.3, “Chaining Using SSL”
• Section 3.3.4, “Maintaining Database Links”
• Section 3.3.5, “Database Links and Access Control Evaluation”
• Section 3.3.6, “Advanced Feature: Tuning Database Link Performance”
• Section 3.3.7, “Advanced Feature: Configuring Cascading Chaining”
3.3.1. Configuring the Chaining Policy
These procedures describe configuring how Directory Server chains requests made by client
applications to Directory Servers that contain database links. This chaining policy applies to all
database links created on Directory Server.
Page 76
Chapter 3. Configuring Directory Databases
58
3.3.1.1. Chaining Component Operations
A component is any functional unit in the server that uses internal operations. For example, plug-ins
are considered to be components, as are functions in the front-end. However, a plug-in may actually
be comprised of multiple components (for example, the ACI plug-in).
Some components send internal LDAP requests to the server, expecting to access local data only. For
such components, control the chaining policy so that the components can complete their operations
successfully. One example is the certificate verification function. Chaining the LDAP request made by
the function to check certificates implies that the remote server is trusted. If the remote server is not
trusted, then there is a security problem.
By default, all internal operations are not chained and no components are allowed to chain, although
this can be overridden.
Additionally, an ACI must be created on the remote server to allow the specified plug-in to perform its
operations on the remote server. The ACI must exist in the suffix assigned to the database link.
The following table lists component names, the potential side-effects of allowing them to chain internal
operations, and the permissions they need in the ACI on the remote server:
Component Name Description Permissions
ACI plug-in This plug-in implements access
control. Operations used
to retrieve and update ACI
attributes are not chained
because it is not safe to mix
local and remote ACI attributes.
However, requests used to
retrieve user entries may
be chained by setting the
chaining components attribute,
nsActiveChainingComponents:
cn=ACI
Plugin,cn=plugins,cn=config.
Read, search, and compare
Resource limit component This component sets server
limits depending on the user
bind DN. Resource limits
can be applied on remote
users if the resource limitation
component is allowed to
chain. To chain resource limit
component operations, add the
chaining component attribute,
nsActiveChainingComponents:
cn=resource
limits,cn=components,cn=config.
Read, search, and compare
Certificate-based authentication
checking component
This component is used when
the SASL-external bind method
is used. It retrieves the user
certificate from the database
on the remote server. Allowing
Read, search, and compare
Page 77
Configuring the Chaining Policy
59
Component Name Description Permissions
this component to chain means
certificate-based authentication
can work with a database link.
To chain this component's
operations, add the chaining
component attribute,
nsActiveChainingComponents:
cn=certificate-based
authentication,cn=components,cn=config.
Referential Integrity plug-in This plug-in ensures that
updates made to attributes
containing DNs are propagated
to all entries that contain
pointers to the attribute. For
example, when an entry that is
a member of a group is deleted,
the entry is automatically
removed from the group. Using
this plug-in with chaining helps
simplify the management
of static groups when the
group members are remote
to the static group definition.
To chain this component's
operations, add the chaining
component attribute,
nsActiveChainingComponents:
cn=referential integrity
postoperation,cn=plugins,cn=config.
Read, write, search, and
compare
Attribute Uniqueness plug-in This plug-in checks that all
the values for a specified
uid attribute are unique (no
duplicates). If this plug-in
is chained, it confirms that
the uid attribute values are
unique even on attributes
changed through a database
link. To chain this component's
operations, add the chaining
component attribute,
nsActiveChainingComponents:
cn=attribute
uniqueness,cn=plugins,cn=config
Read, search, and compare
Table 3.2. Components Allowed to Chain
NOTE
The following components cannot be chained:
Page 78
Chapter 3. Configuring Directory Databases
60
• Roles plug-in
• Password policy component
• Replication plug-ins
• Referential Integrity plug-in
When enabling the Referential Integrity plug-in on servers issuing chaining requests,
be sure to analyze performance, resource, and time needs as well as integrity needs.
Integrity checks can be time-consuming and draining on memory and CPU. For further
information on the limitations surrounding ACIs and chaining, see Section 6.1.4, “ACI
Limitations”.
After modifying the components allowed to chain, restart the server in order for the modification to take
effect.
3.3.1.1.1. Chaining Component Operations Using the Console
1.
In the Directory Server Console, select the Configuration tab.
2. Expand Data in the left pane, and click Database Link Settings.
3. Select the Settings tab in the right window. To add a component to the Components allowed to
chain list, click Add.
The Select Components to Add dialog box displays. Select a component from the list, and click
OK.
4. To delete a component from the list, select it, and click Delete.
5. Click Save.
6. Restart the server in order for the change to take effect.
After allowing the component to chain, create an ACI in the suffix on the remote server to which the
operation will be chained. For example, this creates an ACI for the Referential Integrity plug-in:
aci: (targetattr "*")(target="ldap:///ou=customers,l=us,dc=example,dc=com")
(version 3.0; acl "RefInt Access for chaining"; allow
(read,write,search,compare) userdn = "ldap:///cn=referential integrity
postoperation,cn=plugins,cn=config";)
3.3.1.1.2. Chaining Component Operations from the Command Line
1. Specify components to include in chaining using the nsActiveChainingComponents
attribute in the cn=config,cn=chaining database,cn=plugins,cn=config entry of the
configuration file.
For example, to allow the referential integrity component to chain operations, add the following to
the database link configuration file:
nsActiveChainingComponents: cn=referential integrity postoperation,cn=components,cn=config
Page 79
Configuring the Chaining Policy
61
See Table 3.2, “Components Allowed to Chain” for a list of the components which can be chained.
2. Restart the server for the change to take effect.
2
service dirsrv restart instance
3. Create an ACI in the suffix on the remote server to which the operation will be chained. For
example, this creates an ACI for the Referential Integrity plug-in:
aci: (targetattr "*")(target="ldap:///ou=customers,l=us,dc=example,dc=com")
(version 3.0; acl "RefInt Access for chaining"; allow
(read,write,search,compare) userdn = "ldap:///cn=referential
integrity postoperation,cn=plugins,cn=config";)
3.3.1.2. Chaining LDAP Controls
It is possible to not chain operation requests made by LDAP controls. By default, requests made by
the following controls are forwarded to the remote server by the database link:
• Virtual List View (VLV). This control provides lists of parts of entries rather than returning all entry
information.
• Server-side sorting. This control sorts entries according to their attribute values.
• Managed DSA. This controls returns smart referrals as entries, rather than following the referral, so
the smart referral itself can be changed or deleted.
• Loop detection. This control keeps track of the number of times the server chains with another
server. When the count reaches the configured number, a loop is detected, and the client application
is notified. For more information about using this control, see Section 3.3.7.5, “Detecting Loops”.
NOTE
Server-side sorting and VLV controls are supported only when a client application request
is made to a single database. Database links cannot support these controls when a client
application makes a request to multiple databases.
3.3.1.2.1. Chaining LDAP Controls Using the Console
1. In the Directory Server Console, select the Configuration tab.
2. Expand the Data folder in the left pane, and click Database Link Settings.
3. Select the Settings tab in the right window. To add an LDAP control to the list, click Add.
The Select control OIDs to add dialog box displays. Select the OID of a control to add to the list,
and click OK.
4. To delete a control from the list, select it from the LDAP controls forwarded to the remote
server list, and click Delete.
5. Click Save.
Page 80
Chapter 3. Configuring Directory Databases
62
3.3.1.2.2. Chaining LDAP Controls from the Command Line
Alter the controls that the database link forwards by changing the nsTransmittedControls
attribute of the cn=config,cn=chaining database, cn=plugins,cn=config entry. For
example, to forward the virtual list view control, add the following to the database link entry in the
configuration file:
nsTransmittedControls: 2.16.840.1.113730.3.4.9
In addition, if clients of the Directory Server create their own controls and their operations should to
be chained to remote servers, add the OID of the custom control to the nsTransmittedControls
attribute.
The LDAP controls which can be chained and their OIDs are listed in the following table:
Control Name OID
Virtual list view (VLV) 2.16.840.1.113730.3.4.9
Server-side sorting 1.2.840.113556.1.4.473
Managed DSA 2.16.840.1.113730.3.4.2
Loop detection 1.3.6.1.4.1.1466.29539.12
Table 3.3. LDAP Controls and Their OIDs
For more information about LDAP controls, refer to the LDAP C-SDK documentation at http://
www.mozilla.org/directory.
3.3.2. Creating a New Database Link
The basic configuration of the database link involves the following information:
• Suffix information. A suffix is created in the directory tree that is managed by the database link, not a
regular database. This suffix corresponds to the suffix on the remote server that contains the data.
• Bind credentials. When the database link binds to a remote server, it impersonates a user, and this
specifies the DN and the credentials for each database link to use to bind with remote servers.
• LDAP URL. This supplies the LDAP URL of the remote server to which the database link connects.
• List of failover servers. This supplies a list of alternative servers for the database link to contact in
the event of a failure. This configuration item is optional.
3.3.2.1. Creating a New Database Link Using the Console
To create a new database link using the Directory Server Console:
1. In the Directory Server Console, select the Configuration tab.
2. Right-click Data in the left navigation pane, and select New Root Suffix or New Sub Suffix from
the pop-up menu.
A Create New Suffix dialog box is displayed.
3. Enter the name of the suffix on the remote server to which to chain the suffix in the New suffix
field.
Page 81
Creating a New Database Link
63
The suffix must be named in line with dc naming conventions, such as dc=example,dc=com.
4. Deselect the Create associated database automatically checkbox.
The checkbox must not be selected because a database link cannot be added to a suffix that is
associated with a database. This suffix is used only by the database link.
5. Click OK.
The suffix appears automatically under Data in the left navigation pane.
6. In the left pane, right-click the new suffix, and select New Database Link from the pop-up menu.
The Create New Database Link dialog box is displayed.
7. Enter the name of the new database link in the Database link name field, such as
examplelink1. The name can be a combination of alphanumeric characters, dashes (-), and
underscores (_). No other characters are allowed.
8. Enter the DN used by the database link to bind to the remote server in the Bind DN field, such as
cn=dblink.
9. Enter the password used by the database link to bind to the remote server in the Password field.
10. Select the Use a secure LDAP connection between servers checkbox for the database link to
use SSL to communicate to the remote server.
11. Enter the name of the remote server in the Remote server field. Enter the server port number
used for the bind in the Remote server port field. The default port number is 389. The default
SSL port number is 636.
12. Enter the name of a failover server in the Failover Server(s) field, and specify a port number in
the Port field. The default port number is 389. The default SSL port number is 636. Click Add to
add the failover server to the list.
There can be multiple failover servers specified. If the primary remote server fails, the database
link contacts the first server in the Failover Servers list. If it fails, it contacts the next in the list, and
so on.
13. Click OK to create the new database link. Click OK to dismiss the success dialog box that appears
after the database link has been created.
The new database link appears under the suffix in the left navigation pane.
NOTE
The Console provides a checklist of information that needs to be present on the remote
server for the database link to bind successfully. To view this checklist, click the new
database link, and click the Authentication tab. The checklist appears in the Remote
server checklist box.
Page 82
Chapter 3. Configuring Directory Databases
64
3.3.2.2. Creating a Database Link from the Command Line
1. Use the ldapmodify command-line utility to create a new database link from the command line.
The new instance must be located in the cn=chaining database,cn=plugins,cn=config
entry.
ldapmodify -a -p 389 -D "cn=directory manager" -w secret -h us.example.com
2. Specify the configuration information for the database link:
dn: cn=examplelink,cn=chaining database,cn=plugins,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsBackendInstance
nsslapd-suffix: ou=people,dc=example,dc=com suffix being chained
nsfarmserverurl: ldap://people.example.com:389/ LDAP URL to remote server
nsmultiplexorbinddn: cn=proxy admin,cn=config bind DN
nsmultiplexorcredentials: secret bind password
cn: examplelink
Default configuration attributes are contained in the cn=default config, cn=chaining
database,cn=plugins,cn=config entry. These configuration attributes apply to all database
links at creation time. Changes to the default configuration only affect new database links. The default
configuration attributes on existing database links cannot be changed.
Each database link contains its own specific configuration information, which is stored with the
database link entry itself, cn=database_link, cn=chaining database,cn=plugins,cn=config.
For more information about configuration attributes, refer to the Directory Server Configuration,
Command, and File Reference.
• Section 3.3.2.2.1, “Providing Suffix Information”
• Section 3.3.2.2.2, “Providing Bind Credentials”
• Section 3.3.2.2.3, “Providing an LDAP URL”
• Section 3.3.2.2.4, “Providing a List of Failover Servers”
• Section 3.3.7.6, “Summary of Cascading Chaining Configuration Attributes”
• Section 3.3.2.2.6, “Database Link Configuration Example”
3.3.2.2.1. Providing Suffix Information
Use the nsslapd-suffix attribute to define the suffix managed by the database link. For example,
for the database link to point to the people information for a remote site of the company, enter the
following suffix information:
nsslapd-suffix: l=Zanzibar,ou=people,dc=example,dc=com
The suffix information is stored in the cn=database_link, cn=chaining
database,cn=plugins,cn=config entry.
Page 83
Creating a New Database Link
65
NOTE
After creating the database link, any alterations to the nsslapd-nsslapd-suffix
attribute are applied only after the server containing the database link is restarted.
3.3.2.2.2. Providing Bind Credentials
For a request from a client application to be chained to a remote server, special bind credentials can
be supplied for the client application. This gives the remote server the proxied authorization rights
needed to chain operations. Without bind credentials, the database link binds to the remote server as
anonymous.
Providing bind credentials involves the following steps:
1. On the remote server, do the following:
• Create an administrative user for the database link.
For information on adding entries, see Chapter 2, Creating Directory Entries.
• Provide proxy access rights for the administrative user created in step 1 on the subtree chained
to by the database link.
For more information on configuring ACIs, see Chapter 6, Managing Access Control
2. On the server containing the database link, use ldapmodify to provide a user DN for the
database link in the nsMultiplexorBindDN attribute of the cn=database_link, cn=chaining
database,cn=plugins,cn=config entry.
WARNING
The nsMultiplexorBindDN cannot be that of the Directory Manager.
Use ldapmodify to provide a user password for the database link in the
nsMultiplexorCredentials attribute of the cn=database_link, cn=chaining
database,cn=plugins,cn=config entry.
For example, a client application sends a request to Server A. Server A contains a database link that
chains the request to a database on Server B.
Page 84
Chapter 3. Configuring Directory Databases
66
The database link on Server A binds to Server B using a special user as defined
in the nsMultiplexorBindDN attribute and a user password as defined in the
nsMultiplexorCredentials attribute. In this example, Server A uses the following bind
credentials:
nsMultiplexorBindDN: cn=proxy admin,cn=config
nsMultiplexorCredentials: secret
Server B must contain a user entry corresponding to the nsMultiplexorBindDN, and set the proxy
authentication rights for this user. To set the proxy authorization correctly, set the proxy ACI as any
other ACI.
WARNING
Carefully examine access controls when enabling chaining to avoid giving access to
restricted areas of the directory. For example, if a default proxy ACI is created on a
branch, the users that connect via the database link will be able to see all entries below
the branch. There may be cases when not all of the subtrees should be viewed by a user.
To avoid a security hole, create an additional ACI to restrict access to the subtree.
Page 85
Creating a New Database Link
67
For more information on ACIs, see Chapter 6, Managing Access Control. For more information about
the proxy authentication control, refer to the LDAP C-SDK documentation at http://www.mozilla.org/
directory.
NOTE
When a database link is used by a client application to create or modify entries, the
attributes creatorsName and modifiersName do not reflect the real creator or modifier
of the entries. These attributes contain the name of the administrative user granted
proxied authorization rights on the remote data server.
3.3.2.2.3. Providing an LDAP URL
On the server containing the database link, identify the remote server that the database link connects
with using an LDAP URL. Unlike the standard LDAP URL format, the URL of the remote server does
not specify a suffix. It takes the form ldap://hostname:port.
The URL of the remote server using the nsFarmServerURL attribute is set in the cn=database_link,
cn=chaining database,cn=plugins,cn=config entry of the configuration file.
nsFarmServerURL: ldap://example.com:389/
Do not forget to use the trailing slash (/) at the end of the URL.
For the database link to connect to the remote server using LDAP over SSL, the LDAP URL of
the remote server uses the protocol LDAPS instead of LDAP in the URL, such as ldaps://
example.com:636.
For more information about chaining and SSL, see Section 3.3.3, “Chaining Using SSL”.
3.3.2.2.4. Providing a List of Failover Servers
There can be additional LDAP URLs for servers included to use in the case of failure. Add alternate
servers to the nsFarmServerURL attribute, separated by spaces.
nsFarmServerURL: ldap://example.com us.example.com:389 africa.example.com:1000/
In this sample LDAP URL, the database link first contacts the server example.com on the standard
port to service an operation. If it does not respond, the database link then contacts the server
us.example.com on port 389. If this server fails, it then contacts africa.example.com on port
1000.
3.3.2.2.5. Summary of Database Link Configuration Attributes
The following table lists the attributes available for configuring a database link. Some of these
attributes were discussed in the earlier sections. All instance attributes are defined in the
cn=database_link, cn=chaining database,cn=plugins,cn=config entry.
Values defined for a specific database link take precedence over the global attribute value.
Attributes Value
nsTransmittedControls
†
Gives the OID of LDAP controls forwarded by the
database link to the remote data server.
Page 86
Chapter 3. Configuring Directory Databases
68
Attributes Value
nsslapd-suffix The suffix managed by the database link. Any
changes to this attribute after the entry has
been created take effect only after the server
containing the database link is restarted.
nsslapd-timelimit Default search time limit for the database link,
given in seconds. The default value is 3600
seconds.
nsslapd-sizelimit Default size limit for the database link, given in
number of entries. The default value is 2000
entries.
nsFarmServerURL Gives the LDAP URL of the remote server
(or farm server) that contains the data. This
attribute can contain optional servers for failover,
separated by spaces. If using cascading
chaining, this URL can point to another database
link.
nsMultiplexorBindDN DN of the administrative entry used to
communicate with the remote server. The term
multiplexor in the name of the attribute
means the server which contains the database
link and communicates with the remote server.
This bind DN cannot be the Directory Manager.
If this attribute is not specified, the database link
binds as anonymous.
nsMultiplexorCredentials Password for the administrative user, given
in plain text. If no password is provided, it
means that users can bind as anonymous. The
password is encrypted in the configuration file.
nsCheckLocalACI Reserved for advanced use only. Controls
whether ACIs are evaluated on the database
link as well as the remote data server. Takes the
values on or off. Changes to this attribute occur
only after the server has been restarted. The
default value is off.
nsProxiedAuthorization Reserved for advanced use only. Disables
proxied authorization. A value of off means
proxied authorization is disabled. The default
value is on.
nsActiveChainingComponents
†
Lists the components using chaining. A
component is any functional unit in the server.
The value of this attribute in the database
link instance overrides the value in the global
configuration attribute. To disable chaining on
a particular database instance, use the value
none. The default policy is not to allow chaining.
For more information, see Section 3.3.1.1,
“Chaining Component Operations”.
Page 87
Creating a New Database Link
69
Attributes Value
nsReferralOnScopedSearch Controls whether referrals are returned by
scoped searches. This attribute is for optimizing
the directory because returning referrals in
response to scoped searches is more efficient.
Takes the values on or off. The default value is
off.
nsHopLimit Maximum number of times a request can be
forwarded from one database link to another. The
default value is 10.
Can be both a global and instance attribute. This global configuration attribute is located in the cn=config, cn=chaining
database,cn=plugins,cn=config entry. The global attributes are dynamic, meaning any changes made to them
automatically take effect on all instances of the database link within the directory.
Table 3.4. Database Link Configuration Attributes
3.3.2.2.6. Database Link Configuration Example
Suppose a server within the us.example.com domain contains the subtree l=Walla
Walla,ou=people,dc=example,dc=com on a database and that operation requests for the
l=Zanzibar,ou=people,dc=example,dc=com subtree should be chained to a different server in
the africa.example.com domain.
Page 88
Chapter 3. Configuring Directory Databases
70
1. Run ldapmodify1 to add a database link to Server A:
ldapmodify -a -p 389 -D "cn=directory manager" -w secret -h us.example.com
2. Specify the configuration information for the database link:
dn: cn=DBLink1,cn=chaining database,cn=plugins,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsBackendInstance
nsslapd-suffix: c=africa,ou=people,dc=example,dc=com
nsfarmserverurl: ldap://africa.example.com:389/
nsmultiplexorbinddn: cn=proxy admin,cn=config
nsmultiplexorcredentials: secret
cn: DBLink1
dn: cn="c=africa,ou=people,dc=example,dc=com",cn=mapping tree,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: DBLink1
nsslapd-parent-suffix: "ou=people,dc=example,dc=com"
cn: "c=africa,ou=people,dc=example,dc=com"
In the first entry, the nsslapd-suffix attribute contains the suffix on Server B to which to chain
from Server A. The nsFarmServerURL attribute contains the LDAP URL of Server B.
The second entry creates a new suffix, allowing the server to route requests made to the new
database link. The cn attribute contains the same suffix specified in the nsslapd-suffix
attribute of the database link. The nsslapd-backend attribute contains the name of the
database link. The nsslapd-parent-suffix attribute specifies the parent of this new suffix,
ou=people,dc=example,dc=com.
3. Create an administrative user on Server B, as follows:
dn: cn=proxy admin,cn=config
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: proxy admin
sn: proxy admin
userPassword: secret
description: Entry for use by database links
WARNING
Do not use the Directory Manager user as the proxy administrative user on the remote
server. This creates a security hole.
4. Add the following proxy authorization ACI to the
l=Zanzibar,ou=people,dc=example,dc=com entry on Server B:
aci: (targetattr = "*")(version 3.0; acl "Proxied authorization
for database links"; allow (proxy) userdn = "ldap:///cn=proxy
Page 89
Chaining Using SSL
71
admin,cn=config";)
This ACI gives the proxy admin user read-only access to the data contained on the remote server
within the l=Zanzibar,ou=people,dc=example,dc=com subtree only.
NOTE
When a user binds to a database link, the user's identity is sent to the remote server.
Access controls are always evaluated on the remote server. For the user to modify or
write data successfully to the remote server, set up the correct access controls on the
remote server. For more information about how access controls are evaluated in the
context of chained operations, see Section 3.3.5, “Database Links and Access Control
Evaluation”.
3.3.3. Chaining Using SSL
Database links can be configured to communicate with the remote server using SSL. Using SSL to
chain involves the following steps:
1. Enable SSL on the remote server.
2. Specify the LDAP URL of the remote server in SSL format in the nsFarmServerURL attribute.
For more information about this attribute, see Section 3.3.2.2.3, “Providing an LDAP URL”. For
example:
nsFarmServerURL: ldaps://africa.example.com:636/
3. Enable SSL on the server that contains the database link.
For more information on enabling SSL, see Section 11.1.1, “Enabling SSL: Summary of Steps”.
When the database link and remote server are configured to communicate using SSL, this does not
mean that the client application making the operation request must also communicate using SSL. The
client can bind using a normal port.
3.3.4. Maintaining Database Links
This section describe how to update and delete existing database links. It contains the following
procedures:
• Section 3.3.4.1, “Updating Remote Server Authentication Information”
• Section 3.3.4.2, “Deleting Database Links”
3.3.4.1. Updating Remote Server Authentication Information
To update the bind DN and password used by the database link to connect to the remote server, do
the following:
1. In the Directory Server Console, select the Configuration tab.
2. In the left pane, expand the Data folder, and locate the database link to update under one of the
suffixes. Select the database link.
Page 90
Chapter 3. Configuring Directory Databases
72
3. In the right navigation pane, click the Authentication tab.
4. To update the remote server information, enter a new LDAP URL in the Remote Server URL field.
Unlike the standard LDAP URL format, the URL of the remote server does not specify a suffix. It
takes the form ldap://hostname:port/.
5. Update the bind DN used by the database link to bind with the remote server by entering a new
DN in the Database link bind DN field.
6. Update the password used by the database link to bind with the remote server by entering a
new password in the Database link password field. Confirm the password by retyping it in the
Confirm database link password field.
The remote server checklist box lists the administrative user entry, suffix, and ACI that need to
exist on the remote server for the database link to bind successfully.
7. Click Save.
3.3.4.2. Deleting Database Links
To delete a database link, do the following:
1. In the Directory Server Console, select the Configuration tab.
2. In the left navigation pane, locate the database link to delete, and select it.
3. From the Object menu, select Delete.
Alternatively, right-click the database link, and select Delete from the pop-up menu.
The Deleting Database Link confirmation dialog box is displayed.
4. Click Yes to confirm the deletion of the database link.
Once deleted, the database link no longer appears in the right pane.
3.3.5. Database Links and Access Control Evaluation
When a user binds to a server containing a database link, the database link sends the user's identity to
the remote server. Access controls are always evaluated on the remote server. Every LDAP operation
evaluated on the remote server uses the original identity of the client application passed via the
proxied authorization control. Operations succeed on the remote server only if the user has the correct
access controls on the subtree contained on the remote server. This requires adding the usual access
controls to the remote server with a few restrictions:
• Not all types of access control can be used.
For example, role-based or filter-based ACIs need access to the user entry. Because the data
are accessed through database links, only the data in the proxy control can be verified. Consider
designing the directory in a way that ensures the user entry is located in the same database as the
user's data.
Page 91
Advanced Feature: Tuning Database Link Performance
73
• All access controls based on the IP address or DNS domain of the client may not work since the
original domain of the client is lost during chaining. The remote server views the client application as
being at the same IP address and in the same DNS domain as the database link.
The following restrictions apply to the ACIs used with database links:
• ACIs must be located with any groups they use. If the groups are dynamic, all users in the group
must be located with the ACI and the group. If the group is static, it may refer to remote users.
• ACIs must be located with any role definitions they use and with any users intended to have those
roles.
• ACIs that refer to values of a user's entry (for example, userattr subject rules) will work if the user
is remote.
Though access controls are always evaluated on the remote server, they can also be evaluated on
both the server containing the database link and the remote server. This poses several limitations:
• During access control evaluation, contents of user entries are not necessarily available (for
example, if the access control is evaluated on the server containing the database link and the entry
is located on a remote server).
For performance reasons, clients cannot do remote inquiries and evaluate access controls.
• The database link does not necessarily have access to the entries being modified by the client
application.
When performing a modify operation, the database link does not have access to the full entry stored
on the remote server. If performing a delete operation, the database link is only aware of the entry's
DN. If an access control specifies a particular attribute, then a delete operation will fail when being
conducted through a database link.
NOTE
By default, access controls set on the server containing the database link are not
evaluated. To override this default, use the nsCheckLocalACI attribute in the
cn=database_link, cn=chaining database,cn=plugins,cn=config entry.
However, evaluating access controls on the server containing the database link is not
recommended except with cascading chaining.
3.3.6. Advanced Feature: Tuning Database Link Performance
The following sections provide information on tuning the performance of database links through
connection and thread management.
• Section 3.3.6.1, “Managing Connections to the Remote Server”
• Section 3.3.6.2, “Detecting Errors During Normal Processing”
• Section 3.3.6.3, “Managing Threaded Operations”
Page 92
Chapter 3. Configuring Directory Databases
74
3.3.6.1. Managing Connections to the Remote Server
Each database link maintains a pool of connections to a remote server. The connections to optimize
resources can be configured for the directory.
3.3.6.1.1. Managing Connections to the Remote Server Using the Console
1. In the Directory Server Console, select the Configuration tab.
2. Expand the Data folder in the left pane and locate the database link to change. Click the database
link, then click the Limits and Controls tab in the right navigation pane.
3. In the Connection Management section, make changes to any of the following fields:
• Maximum TCP connection(s). The maximum number of TCP connections that the database link
establishes with the remote server. The default value is 3 connections.
• Bind timeout. Amount of time, in seconds, before the database link's bind attempt times out. The
default value is 15 seconds.
• Maximum binds per connection. Maximum number of outstanding bind operations per TCP
connection. The default value is 10 outstanding bind operations per connection.
• Time out before abandon (sec). Number of seconds before the server checks to see if a timed-
out connection should be abandoned. The default value is 1 second.
• Maximum LDAP connection(s). Maximum number of LDAP connections that the database link
establishes with the remote server. The default value is 10 connections.
• Maximum bind retries. Number of times a database link attempts to bind to the remote server.
A value of 0 indicates that the database link will try to bind only once. The default value is 3
attempts.
• Maximum operations per connection. Maximum number of outstanding operations per LDAP
connection. The default value is 2 operations per connection.
• Connection lifetime (sec). How long a connection made between the database link and remote
server remains open. Connections between the database link and the remote server can be
kept open for an unspecified time or closed after a specific period of time. It is faster to keep the
connections open, but it uses more resources. For slow connections, it may be desirable to limit
the connection time. A value of 0 indicates there is no limit. By default, the value is set to 0.
4. Click Save.
3.3.6.1.2. Managing Connections to the Remote Server from the Command Line
Use ldapmodify to add connection attributes to the database link entry.
The default connection management attributes are stored in the following entry:
cn=default instance config,cn=chaining database,cn=plugins,cn=config
The connection management attributes for a specific database link are stored in the following entry:
cn=database_link,cn=chaining database,cn=plugins,cn=config
Page 93
Advanced Feature: Tuning Database Link Performance
75
The connection management attributes specified in this entry take precedence over the attributes
specified in the cn=default instance config entry.
Attribute Name Description
nsOperationConnectionsLimit Maximum number of LDAP connections that
the database link establishes with the remote
server. The default value is 20 connections per
database link instance.
nsBindConnectionsLimit Maximum number of TCP connections that the
database link establishes with the remote server.
The default value is 3 connections.
nsConcurrentOperationsLimit Maximum number of outstanding operations
per LDAP connection. The default value is 2
operations per connection.
nsConcurrentBindLimit Maximum number of outstanding bind operations
per TCP connection. The default value is 10
outstanding bind operations.
nsBindRetryLimit Number of times a database link attempts to
bind to the remote server. A value of zero (0)
indicates that the database link will try to bind
only once. The default value is 3 attempts.
nsConnectionLife Connection lifetime, in seconds. Connections
between the database link and the remote
server can be kept open for an unspecified
time or closed after a specific period of time.
It is faster to keep the connections open, but
it uses more resources. For example, it may
be wise to limit the connection time for a slow
connection. A value of 0 indicates there is no
limit. By default, the value is set to 0. When the
value is 0 and there is a list of failover servers in
the nsFarmServerURL attribute, the first server
is never contacted after failover to the alternate
server. The default value is 0 seconds.
nsBindTimeout Amount of time, in seconds, before the bind
attempt times out. The default value is 15
seconds.
nsAbandonedSearchCheckInterval Number of seconds that pass before the server
checks for abandoned operations. The default
value is 1 second.
Table 3.5. Database Link Connection Management Attributes
For the list of database link configuration attributes, see Table 3.4, “Database Link Configuration
Attributes”.
3.3.6.2. Detecting Errors During Normal Processing
Protect server performance by detecting errors during the normal chaining operation between the
database link and the remote server. The database link has two attributes — nsMaxResponseDelay
Page 94
Chapter 3. Configuring Directory Databases
76
and nsMaxTestResponseDelay — which work together to determine if the remote server is no
longer responding.
The first attribute, nsMaxResponseDelay, sets a maximum duration for an LDAP operation to
complete. If the operation takes more than the amount of time specified in this attribute, the database
link's server suspects that the remote server is no longer online.
Once the nsMaxResponseDelay period has been met, the database link pings the remote
server. During the ping, the database link issues another LDAP request, a simple search request
for an object that does not exist in the remote server. The duration of the ping is set using the
nsMaxTestResponseDelay.
If the remote server does not respond before the nsMaxTestResponseDelay period has passed,
then an error is returned, and the connection is flagged as down. All connections between the
database link and remote server will be blocked for 30 seconds, protecting the server from a
performance degradation. After 30 seconds, operation requests made by the database link to the
remote server continue as normal.
Both attributes are stored in the cn=config,cn=chaining database,cn=plugins,cn=config
entry. The following table describes the attributes in more detail:
Attribute Name Description
nsMaxResponseDelay Maximum amount of time it can take a remote
server to respond to an LDAP operation request
made by a database link before an error is
suspected. This period is given in seconds. The
default delay period is 60 seconds. Once this
delay period has been met, the database link
tests the connection with the remote server.
nsMaxTestResponseDelay Duration of the test issued by the database
link to check whether the remote server is
responding. If a response from the remote server
is not returned before this period has passed,
the database link assumes the remote server
is down, and the connection is not used for
subsequent operations. This period is given in
seconds. The default test response delay period
is 15 seconds.
Table 3.6. Database Link Processing Error Detection Parameters
3.3.6.3. Managing Threaded Operations
Generally, Directory Server performs best using a limited number of threads for processing operations.
A limited number of threads can generally process operations very quickly, preventing the queue of
operations waiting for a free thread from growing too long.
However, the database link forwards operations to remote servers for processing. The database link
contacts the remote server, forwards the operation, waits for the result, and then sends the result back
to the client application. The entire operation can take much longer than a local operation.
While the database link waits for results from the remote server, it can process additional operations.
By default, the number of threads used by the server is 30. However, when using database links,
Page 95
Advanced Feature: Configuring Cascading Chaining
77
performance can be improved by increasing the number of threads available for processing
operations. While the local CPU waits for a response from a remote server, it can process other
operations rather than stand idle.
To change the number of threads used for processing operations, change the nsslapd-
threadnumber global configuration attribute in the cn=config entry. Increasing the thread number
can improve performance; the default thread number is 30. Restart the server after changing the
thread count to apply the changes.
3.3.7. Advanced Feature: Configuring Cascading Chaining
The database link can be configured to point to another database link, creating a cascading chaining
operation. A cascading chain occurs any time more than one hop is required to access all of the data
in a directory tree.
• Section 3.3.7.1, “Overview of Cascading Chaining”
• Section 3.3.7.2, “Configuring Cascading Chaining Defaults Using the Console”
• Section 3.3.7.3, “Configuring Cascading Chaining Using the Console”
• Section 3.3.7.4, “Configuring Cascading Chaining from the Command Line”
• Section 3.3.7.5, “Detecting Loops”
• Section 3.3.7.6, “Summary of Cascading Chaining Configuration Attributes”
• Section 3.3.7.7, “Cascading Chaining Configuration Example”
3.3.7.1. Overview of Cascading Chaining
Cascading chaining occurs when more than one hop is required for the directory to process a client
application's request. For example:
The client application sends a modify request to Server 1. Server one contains a database link that
forwards the operation to Server 2, which contains another database link. The database link on Server
2 forwards the operations to server three, which contains the data the clients wants to modify in a
database. Two hops are required to access the piece of data the client want to modify.
During a normal operation request, a client binds to the server, and then any ACIs applying to that
client are evaluated. With cascading chaining, the client bind request is evaluated on Server 1, but the
Page 96
Chapter 3. Configuring Directory Databases
78
ACIs applying to the client are evaluated only after the request has been chained to the destination
server, in the above example Server 2.
Consider the following example scenario. On Server A, a directory tree is split as follows:
The root suffix dc=example,dc=comand the ou=people and ou=groups sub suffixes are stored on
Server A. The l=europe,dc=example,dc=com and ou=groups suffixes are stored in on Server B,
and the ou=people branch of the l=europe,dc=example,dc=com suffix is stored on Server C.
With cascading configured on servers A, B, and C, a client request targeted at the
ou=people,l=europe,dc=example,dc=com entry would be routed by the directory as follows:
Page 97
Advanced Feature: Configuring Cascading Chaining
79
First, the client binds to Server A and chains to Server B using Database Link 1. Then Server
B chains to the target database on Server C using Database Link 2 to access the data in the
ou=people,l=europe,dc=example,dc=com branch. Because at least two hops are required for
the directory to service the client request, this is considered a cascading chain.
3.3.7.2. Configuring Cascading Chaining Defaults Using the Console
To set cascading chaining defaults for all database links in Directory Server, do the following:
1. In the Directory Server Console, select the Configuration tab.
2. Expand the Data folder in the left pane, and click Database Link Settings. Click the Default
Creation Parameters tab.
Page 98
Chapter 3. Configuring Directory Databases
80
3. Select the Check local ACI checkbox to enable the evaluation of local ACIs on the intermediate
database links involved in cascading chaining. Selecting this checkbox may require adding the
appropriate local ACIs to a database on the servers that contain intermediate database links.
4. Enter the maximum number of times a database link can point to another database link in the
Maximum hops field.
By default, the maximum is 10 hops. After 10 hops, a loop is detected by the server, and an error
is returned to the client application.
5. Click Save.
NOTE
Changes made to the default settings of a database link are not applied retroactively. Only
the database links created after changes are made to the default settings will reflect the
changes.
3.3.7.3. Configuring Cascading Chaining Using the Console
To configure cascading chaining for a particular set of database links, do the following:
1. In the Directory Server Console, select the Configuration tab.
2. Expand the Data folder in the left pane, and locate the database link to include in a cascading
chain. Click the database link, then click the Limits and Controls tab in the right navigation pane.
3. Select the Check local ACI checkbox to enable the evaluation of local ACIs on the intermediate
database links involved in the cascading chain. Selecting this checkbox may require adding the
appropriate local ACIs to the database link.
4. Enter the maximum number of times a database link can point to another database link in the
Maximum hops field.
By default, the maximum is ten hops. After ten hops, a loop is detected by the server, and an error
is returned to the client application.
5. Click Save.
3.3.7.4. Configuring Cascading Chaining from the Command Line
To configure a cascade of database links through the command line, do the following:
1. Point one database link to the URL of the server containing the intermediate database link.
To create a cascading chain, the nsFarmServerURL attribute of one database link must contain
the URL of the server containing another database link. Suppose the database link on the server
called example1.com points to a database link on the server called africa.example.com. For
example, the cn=database_link, cn=chaining database, cn=plugins,cn=config entry of
the database link on Server 1 would contain the following:
nsFarmServerURL: ldap://africa.example.com:389/
Page 99
Advanced Feature: Configuring Cascading Chaining
81
2. Configure the intermediate database link or links (in the example, Server 2) to transmit the Proxy
Authorization Control.
By default, a database link does not transmit the Proxy Authorization Control. However, when
one database link contacts another, this control is used to transmit information needed by
the final destination server. The intermediate database link needs to transmit this control. To
configure the database link to transmit the proxy authorization control, add the following to the
cn=config,cn=chaining database,cn=plugins,cn=config entry of the intermediate
database link:
nsTransmittedControls: 2.16.840.1.113730.3.4.12
The OID value represents the Proxy Authorization Control. For more information about chaining
LDAP controls, see Section 3.3.1.2, “Chaining LDAP Controls”.
3. Create a proxy administrative user ACI on all intermediate database links.
The ACI must exist on the server that contains the intermediate database link that checks the
rights of the first database link before translating the request to another server. For example, if
Server 2 does not check the credentials of Server 1, then anyone could bind as anonymous and
pass a proxy authorization control allowing them more administrative privileges than appropriate.
The proxy ACI prevents this security breach.
a. Create a database, if one does not already exist, on the server containing the intermediate
database link. This database will contain the admin user entry and the ACI. For information
about creating a database, see Section 3.2.1, “Creating Databases”.
b. Create an entry that corresponds to the administrative user in the database.
c. Create an ACI for the administrative user that targets the appropriate suffix. This ensures the
administrator has access only to the suffix of the database link. For example:
aci: (targetattr = "*")(version 3.0; acl "Proxied authorization for database links";
allow (proxy) userdn = "ldap:///cn=proxy admin,cn=config";)
This ACI is like the ACI created on the remote server when configuring simple chaining.
WARNING
Carefully examine access controls when enabling chaining to avoid giving access to
restricted areas of the directory. For example, if a default proxy ACI is created on a
branch, the users that connect through the database link will be able to see all entries
below the branch. There may be cases when not all of the subtrees should be viewed
by a user. To avoid a security hole, create an additional ACI to restrict access to the
subtree.
4. Enable local ACI evaluation on all intermediate database links.
To confirm that the proxy administrative ACI is used, enable evaluation of local ACIs on
all intermediate database links involved in chaining. Add the following attribute to the
cn=database_link, cn=chaining database,cn=plugins,cn=config entry of each
intermediate database link:
Page 100
Chapter 3. Configuring Directory Databases
82
nsCheckLocalACI: on
Setting this attribute to on in the cn=default instance config,cn=chaining
database,cn=plugins,cn=config entry means that all new database link instances will
have the nsCheckLocalACI attribute set to on in their cn=database_link, cn=chaining
database,cn=plugins,cn=config entry.
5. Create client ACIs on all intermediate database links and the final destination database.
Because local ACI evaluation is enabled, the appropriate client application ACIs must be created
on all intermediate database links, as well as the final destination database. To do this on the
intermediate database links, first create a database that contains a suffix that represents a root
suffix of the final destination suffix.
For example, if a client request made to the c=africa,ou=people,dc=example,dc=com
suffix is chained to a remote server, all intermediate database links need to contain a database
associated with the dc=example,dc=com suffix.
Add any client ACIs to this superior suffix entry. For example:
aci: (targetattr = "*")(version 3.0; acl "Client authentication for database link users";
allow (all) userdn = "ldap:///uid=* ,cn=config";)
This ACI allows client applications that have a uid in the cn=config entry of Server 1 to perform
any type of operation on the data below the ou=people,dc=example,dc=com suffix on server
three.
3.3.7.5. Detecting Loops
An LDAP control included with Directory Server prevents loops. When first attempting to chain, the
server sets this control to be the maximum number of hops, or chaining connections, allowed. Each
subsequent server decrements the count. If a server receives a count of 0, it determines that a loop
has been detected and notifies the client application.
The number of hops allowed is defined using the nsHopLimit attribute. If not specified, the default
value is 10.
To use the control, add the following OID to the nsTransmittedControl attribute in the
cn=config,cn=chaining database,cn=plugins,cn=config entry:
nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12
If the control is not present in the configuration file of each database link, loop detection will not be
implemented.
3.3.7.6. Summary of Cascading Chaining Configuration Attributes
The following table describes the attributes used to configure intermediate database links in a
cascading chain:
Loading...