Red Hat Directory Server 8.2

Administration Guide

for managing Directory Server instances

Edition 8.2.8

Legal Notice

Copyright © 2010 Red Hat, Inc..
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
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.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
August 2, 2010, updated on April 2, 2012

Abstract

This book is for LDAP administrators.
Preface
1. Directory Server Overview
2. Examples and Formatting
2.1. Command and File Examples
2.2. Tool Locations
2.3. LDAP Locations
2.4. Text Formatting and Styles
3. Additional Reading
4. Giving Feedback
5. Documentation History
1. Basic Red Hat Directory Server Settings
1.1. System Requirements
1.1.1. Required JDK
1.1.2. Directory Server Supported Platforms
1.1.3. Directory Server Console Supported Platforms
1.1.4. Password Sync Service Platforms
1.1.5. Web Application Browser Support
1.2. Directory Server File Locations
1.3. LDAP Tool Locations
1.4. Starting and Stopping Servers
1.4.1. Starting and Stopping Directory Server from the Console
1.4.2. Starting and Stopping Directory Server from the Command Line
1.4.3. Starting and Stopping Admin Server
1.5. Starting the Console
1.5.1. Starting the Directory Server Console
1.5.2. Logging into Directory Server
1.5.3. Changing Login Identity
1.5.4. Viewing the Current Console Bind DN
1.6. Enabling LDAPI
1.7. Changing Directory Server Port Numbers
1.8. Creating a New Directory Server Instance
1.9. Setting the Directory Manager Information
1.10. Using Directory Server Plug-ins
1.10.1. Enabling Plug-ins
1.10.2. Setting the Plug-in Precedence
2. Configuring Directory Databases
2.1. Creating and Maintaining Suffixes
2.1.1. Creating Suffixes
2.1.2. Maintaining Suffixes
2.2. Creating and Maintaining Databases
2.2.1. Creating Databases
2.2.2. Maintaining Directory Databases
2.2.3. Configuring Attribute Encryption
2.3. Creating and Maintaining Database Links
2.3.1. Creating a New Database Link
2.3.2. Configuring the Chaining Policy
2.3.3. Maintaining Database Links
2.3.4. Configuring Database Link Defaults
2.3.5. Deleting Database Links
2.3.6. Database Links and Access Control Evaluation
2.4. Configuring Cascading Chaining
2.4.1. Overview of Cascading Chaining
2.4.2. Configuring Cascading Chaining Using the Console
2.4.3. Configuring Cascading Chaining from the Command Line
2.4.4. Detecting Loops
2.4.5. Summary of Cascading Chaining Configuration Attributes
2.4.6. Cascading Chaining Configuration Example
2.5. Using Referrals
2.5.1. Starting the Server in Referral Mode
2.5.2. Setting Default Referrals
2.5.3. Creating Smart Referrals
2.5.4. Creating Suffix Referrals
3. Creating Directory Entries
3.1. Managing Entries from the Directory Console
3.1.1. Creating a Root Entry
3.1.2. Creating Directory Entries
3.1.3. Modifying Directory Entries
3.1.4. Deleting Directory Entries
3.2. Managing Entries from the Command Line
3.2.1. Providing Input from the Command Line
3.2.2. Creating a Root Entry from the Command Line
3.2.3. Adding Entries Using LDIF
3.2.4. Adding and Modifying Entries Using ldapmodify
3.2.5. Deleting Entries Using ldapdelete
3.2.6. Using Special Characters
3.3. Using LDIF Update Statements to Create or Modify Entries
3.3.1. Adding an Entry Using LDIF
3.3.2. Renaming an Entry Using LDIF
3.3.3. Modifying an Entry Using LDIF
3.3.4. Deleting an Entry Using LDIF
3.3.5. Modifying an Entry in an Internationalized Directory
3.4. Tracking Modifications to Directory Entries
3.4.1. Tracking Modifications to the Database through Update Sequence Numbers
3.4.2. Tracking Entry Modifications through Operational Attributes
3.5. Maintaining Referential Integrity
3.5.1. How Referential Integrity Works
3.5.2. Using Referential Integrity with Replication
3.5.3. Enabling and Disabling Referential Integrity
3.5.4. Modifying the Update Interval
3.5.5. Modifying the Attribute List
4. Populating Directory Databases
4.1. Importing Data
4.1.1. Importing Entries with Large Attributes
4.1.2. Importing a Database from the Console
4.1.3. Initializing a Database from the Console
4.1.4. Importing from the Command Line
4.2. Exporting Data
4.2.1. Exporting Directory Data to LDIF Using the Console
4.2.2. Exporting a Single Database to LDIF Using the Console
4.2.3. Exporting to LDIF from the Command Line
4.3. Backing up and Restoring Data
4.3.1. Backing up All Databases
4.3.2. Backing up the dse.ldif Configuration File
4.3.3. Restoring All Databases
4.3.4. Restoring a Single Database
4.3.5. Restoring Databases That Include Replicated Entries
4.3.6. Restoring the dse.ldif Configuration File
5. Managing Attributes and Values
5.1. Enforcing Attribute Uniqueness
5.1.1. Attribute Uniqueness Plug-in Syntax
5.1.2. Creating an Instance of the Attribute Uniqueness Plug-in
5.1.3. Configuring Attribute Uniqueness
5.1.4. Attribute Uniqueness Plug-in Syntax Examples
5.2. Assigning Class of Service
5.2.1. About the CoS Definition Entry
5.2.2. About the CoS Template Entry
5.2.3. How a Pointer CoS Works
5.2.4. How an Indirect CoS Works
5.2.5. How a Classic CoS Works
5.2.6. Handling Physical Attribute Values
5.2.7. Handling Multi-valued Attributes with CoS
5.2.8. Searches for CoS-Specified Attributes
5.2.9. Access Control and CoS
5.2.10. Managing CoS Using the Console
5.2.11. Managing CoS from the Command Line
5.2.12. Creating Role-Based Attributes
5.3. Linking Attributes to Manage Attribute Values
5.3.1. About Linking Attributes
5.3.2. Looking at the Linking Attributes Plug-in Syntax
5.3.3. Configuring Attribute Links
5.3.4. Cleaning up Attribute Links
5.4. Assigning and Managing Unique Numeric Attribute Values
5.4.1. Looking at the DNA Plug-in Syntax
5.4.2. Configuring Unique Number Assignments
6. Managing the Directory Schema
6.1. Overview of Schema
6.1.1. Default Schema Files
6.1.2. Object Classes
6.1.3. Attributes
6.1.4. Extending the Schema
6.1.5. Schema Replication
6.2. Managing Object Identifiers
6.3. Directory Server Attribute Syntaxes
6.4. Managing Custom Schema in the Console
6.4.1. Viewing Attributes and Object Classes
6.4.2. Creating Attributes
6.4.3. Creating Object Classes
6.4.4. Editing Custom Schema Elements
6.4.5. Deleting Schema
6.5. Managing Schema Using ldapmodify
6.5.1. Creating Attributes
6.5.2. Creating Object Classes
6.5.3. Deleting Schema
6.6. Creating Custom Schema Files
6.7. Dynamically Reloading Schema
6.7.1. Reloading Schema Using schema-reload.pl
6.7.2. Reloading Schema Using ldapmodify
6.7.3. Reloading Schema with Replication
6.7.4. Schema Reload Errors
6.8. Turning Schema Checking On and Off
6.9. Using Syntax Validation
6.9.1. About Syntax Validation
6.9.2. Syntax Validation and Other Directory Server Operations
6.9.3. Enabling or Disabling Syntax Validation
6.9.4. Enabling Strict Syntax Validation for DNs
6.9.5. Enabling Syntax Validation Warnings (Logging)
6.9.6. Validating the Syntax of Existing Attribute Values
7. Managing Indexes
7.1. About Indexes
7.1.1. About Index Types
7.1.2. About Default, System, and Standard Indexes
7.1.3. Overview of the Searching Algorithm
7.1.4. Approximate Searches
7.1.5. Indexing Performance
7.1.6. Balancing the Benefits of Indexing
7.2. Creating Standard Indexes
7.2.1. Creating Indexes from the Server Console
7.2.2. Creating Indexes from the Command Line
7.3. Applying New Indexes to Existing Databases
7.3.1. Running the db2index.pl Script
7.3.2. Using a cn=tasks Entry to Create an Index
7.4. Creating Browsing (VLV) Indexes
7.4.1. Creating Browsing Indexes from the Server Console
7.4.2. Creating Browsing Indexes from the Command Line
7.4.3. Setting Access Control for VLV Information
7.5. Changing the Index Sort Order
7.5.1. Changing the Sort Order in the Console
7.5.2. Changing the Sort Order in the Command Line
7.6. Changing the Width for Indexed Substring Searches
7.7. Deleting Indexes
7.7.1. Deleting Indexes from the Server Console
7.7.2. Deleting Indexes from the Command Line
7.7.3. Deleting Browsing Indexes from the Server Console
7.7.4. Deleting Browsing Indexes from the Command Line
8. Finding Directory Entries
8.1. Finding Entries Using the Directory Server Console
8.2. Using ldapsearch
8.2.1. ldapsearch Command-Line Format
8.2.2. Commonly Used ldapsearch Options
8.2.3. Using Special Characters
8.3. LDAP Search Filters
8.3.1. Using Attributes in Search Filters
8.3.2. Using Operators in Search Filters
8.3.3. Using Compound Search Filters
8.3.4. Using Matching Rules
8.4. Examples of Common ldapsearches
8.4.1. Returning All Entries
8.4.2. Specifying Search Filters on the Command Line
8.4.3. Searching the Root DSE Entry
8.4.4. Searching the Schema Entry
8.4.5. Using LDAP_BASEDN
8.4.6. Displaying Subsets of Attributes
8.4.7. Searching for Operational Attributes
8.4.8. Specifying Search Filters Using a File
8.4.9. Specifying DNs That Contain Commas in Search Filters
8.4.10. Using Client Authentication When Searching
8.4.11. Searching with Specified Controls
8.4.12. Searching with Language Matching Rules
8.4.13. Searching for Attributes with Bit Field Values
8.5. Using Persistent Search
8.5.1. An Overview of Persistent Searches
8.5.2. Running a Persistent Search
8.6. Performing Dereferencing Searches
8.7. Using Simple Paged Results
9. Managing Replication
9.1. Replication Overview
9.1.1. What Directory Units Are Replicated
9.1.2. Read-Write and Read-Only Replicas
9.1.3. Suppliers and Consumers
9.1.4. Changelog
9.1.5. Replication Identity
9.1.6. Replication Agreement
9.1.7. Replicating a Subset of Attributes with Fractional Replication
9.1.8. Compatibility with Earlier Versions of Directory Server
9.2. Replication Scenarios
9.2.1. Single-Master Replication
9.2.2. Multi-Master Replication
9.2.3. Cascading Replication
9.3. Creating the Supplier Bind DN Entry
9.4. Configuring Single-Master Replication
9.4.1. Configuring the Read-Write Replica on the Supplier Server
9.4.2. Configuring the Read-Only Replica on the Consumer
9.4.3. Creating the Replication Agreement
9.5. Configuring Multi-Master Replication
9.5.1. Configuring the Read-Write Replicas on the Supplier Servers
9.5.2. Configuring the Read-Only Replicas on the Consumer Servers
9.5.3. Setting up the Replication Agreements
9.5.4. Preventing Monopolization of the Consumer in Multi-Master Replication
9.6. Configuring Cascading Replication
9.6.1. Configuring the Read-Write Replica on the Supplier Server
9.6.2. Configuring the Read-Only Replica on the Consumer Server
9.6.3. Configuring the Read-Only Replica on the Hub
9.6.4. Setting up the Replication Agreements
9.7. Configuring Replication from the Command Line
9.7.1. Configuring Suppliers from the Command Line
9.7.2. Configuring Consumers from the Command Line
9.7.3. Configuring Hubs from the Command Line
9.7.4. Configuring Replication Agreements from the Command Line
9.7.5. Initializing Consumers Online from the Command Line
9.8. Making a Replica Updatable
9.9. Deleting the Changelog
9.9.1. Removing the Changelog
9.9.2. Moving the Changelog to a New Location
9.10. Initializing Consumers
9.10.1. When to Initialize a Consumer
9.10.2. Online Consumer Initialization Using the Console
9.10.3. Initializing Consumers Online Using the Command Line
9.10.4. Manual Consumer Initialization Using the Command Line
9.10.5. Filesystem Replica Initialization
9.11. Forcing Replication Updates
9.11.1. Forcing Replication Updates from the Console
9.11.2. Forcing Replication Updates from the Command Line
9.12. Replication over SSL
9.13. Setting Replication Timeout Periods
9.14. Replicating o=NetscapeRoot for Admin Server Failover
9.15. Replication with Earlier Releases
9.15.1. Using Legacy Replication
9.15.2. Legacy Replication and Parent Object Classes
9.15.3. Configuring Legacy Replication
9.16. Using the Retro Changelog Plug-in
9.16.1. Enabling the Retro Changelog Plug-in
9.16.2. Trimming the Retro Changelog
9.16.3. Searching and Modifying the Retro Changelog
9.16.4. Retro Changelog and the Access Control Policy
9.17. Monitoring Replication Status
9.17.1. Monitoring Replication Status from the Directory Server Console
9.17.2. Monitoring Replication Status from Administration Express
9.18. Solving Common Replication Conflicts
9.18.1. Solving Naming Conflicts
9.18.2. Solving Orphan Entry Conflicts
9.18.3. Solving Potential Interoperability Problems
9.19. Troubleshooting Replication-Related Problems
10. Synchronizing Red Hat Directory Server with Microsoft Active Directory
10.1. About Windows Sync
10.2. Configuring Windows Sync
10.2.1. Step 1: Configure SSL on Directory Server
10.2.2. Step 2: Configure the Active Directory Domain
10.2.3. Step 3: Select or Create the Sync Identity
10.2.4. Step 4: Install the Password Sync Service
10.2.5. Step 5: Configure the Password Sync Service
10.2.6. Step 6: Configure the Directory Server Database for Synchronization
10.2.7. Step 7: Create the Synchronization Agreement
10.2.8. Step 8: Configure Directory Server User and Group Entries for Synchronization
10.2.9. Step 9: Begin Synchronization
10.3. Synchronizing Users
10.3.1. User Attributes Synchronized between Directory Server and Active Directory
10.3.2. User Schema Differences between Red Hat Directory Server and Active Directory
10.3.3. Configuring User Sync for Directory Server Users
10.3.4. Configuring User Sync for Active Directory Users
10.4. Synchronizing Groups
10.4.1. About Windows Group Types
10.4.2. Group Attributes Synchronized between Directory Server and Active Directory
10.4.3. Group Schema Differences between Red Hat Directory Server and Active Directory
10.4.4. Configuring Group Sync for Directory Server Groups
10.4.5. Configuring Group Sync for Active Directory Groups
10.5. Deleting and Resurrecting Entries
10.5.1. Deleting Entries
10.5.2. Resurrecting Entries
10.6. Sending Synchronization Updates
10.6.1. Performing a Manual Sync Update
10.6.2. Sending a Total Update (Full Synchronization)
10.6.3. Sending Sync Updates in the Command Line
10.6.4. Checking Synchronization Status
10.7. Modifying the Sync Agreement
10.7.1. Editing the Sync Agreement in the Console
10.7.2. Adding and Editing the Sync Agreement in the Command Line
10.8. Configuring Unidirectional Synchronization
10.9. Managing the Password Sync Service
10.9.1. Modifying Password Sync
10.9.2. Starting and Stopping the Password Sync Service
10.9.3. Uninstalling Password Sync Service
10.9.4. Upgrading Password Sync
10.10. Troubleshooting
11. Organizing Entries with Groups, Roles, and Views
11.1. Using Groups
11.1.1. Creating Static Groups in the Console
11.1.2. Creating Dynamic Groups in the Console
11.1.3. Creating Groups in the Command Line
11.1.4. Using the memberOf Attribute to Manage Group Membership Information
11.2. Using Roles
11.2.1. About Roles
11.2.2. Creating a Managed Role
11.2.3. Creating a Filtered Role
11.2.4. Creating a Nested Role
11.2.5. Editing and Assigning Roles to an Entry
11.2.6. Viewing Roles for an Entry through the Command Line
11.2.7. Making a Role Inactive or Active
11.2.8. Viewing the Activation Status for Entries
11.2.9. About Deleting Roles
11.2.10. Using Roles Securely
11.3. Using Views
11.3.1. Creating Views in the Console
11.3.2. Creating Views from the Command Line
12. Managing Access Control
12.1. Access Control Principles
12.1.1. ACI Structure
12.1.2. ACI Placement
12.1.3. ACI Evaluation
12.1.4. ACI Limitations
12.2. Default ACIs
12.3. Creating ACIs Manually
12.3.1. The ACI Syntax
12.3.2. Defining Targets
12.3.3. Defining Permissions
12.4. Bind Rules
12.4.1. Bind Rule Syntax
12.4.2. Defining User Access - userdn Keyword
12.4.3. Defining Group Access - groupdn Keyword
12.4.4. Defining Role Access - roledn Keyword
12.4.5. Defining Access Based on Value Matching
12.4.6. Defining Access from a Specific IP Address
12.4.7. Defining Access from a Specific Domain
12.4.8. Requiring a Certain Level of Security in Connections
12.4.9. Defining Access at a Specific Time of Day or Day of Week
12.4.10. Defining Access Based on Authentication Method
12.4.11. Using Boolean Bind Rules
12.5. Creating ACIs from the Console
12.5.1. Displaying the Access Control Editor
12.5.2. Creating a New ACI
12.5.3. Editing an ACI
12.5.4. Deleting an ACI
12.6. Viewing ACIs
12.7. Checking Access Rights on Entries (Get Effective Rights)
12.7.1. Rights Shown with a Get Effective Rights Search
12.7.2. The Format of a Get Effective Rights Search
12.7.3. Using Get Effective Rights from the Console
12.7.4. Get Effective Rights Return Codes
12.8. Logging Access Control Information
12.9. Access Control Usage Examples
12.9.1. Granting Anonymous Access
12.9.2. Granting Write Access to Personal Entries
12.9.3. Restricting Access to Key Roles
12.9.4. Granting a Group Full Access to a Suffix
12.9.5. Granting Rights to Add and Delete Group Entries
12.9.6. Granting Conditional Access to a Group or Role
12.9.7. Denying Access
12.9.8. Setting a Target Using Filtering
12.9.9. Allowing Users to Add or Remove Themselves from a Group
12.9.10. Setting an ACI to Require a Certain Security Strength Factor for Some Operations
12.9.11. Defining Permissions for DNs That Contain a Comma
12.9.12. Proxied Authorization ACI Example
12.10. Advanced Access Control: Using Macro ACIs
12.10.1. Macro ACI Example
12.10.2. Macro ACI Syntax
12.11. Access Control and Replication
12.12. Compatibility with Earlier Releases
13. Managing User Authentication
13.1. Managing the Password Policy
13.1.1. Configuring the Password Policy
13.1.2. Setting User Passwords
13.1.3. Password Change Extended Operation
13.2. Configuring the Account Lockout Policy
13.2.1. Configuring the Account Lockout Policy Using the Console
13.2.2. Configuring the Account Lockout Policy Using the Command Line
13.2.3. Replicating Account Lockout Attributes
13.3. Synchronizing Passwords
13.4. Setting Resource Limits Based on the Bind DN
13.4.1. Setting Resource Limits Using the Console
13.4.2. Setting Resource Limits Using the Command Line
13.4.3. Setting Resource Limits on Anonymous Binds
13.5. Enabling Different Types of Binds
13.5.1. Requiring Secure Binds
13.5.2. Disabling Anonymous Binds
13.5.3. Allowing Unauthenticated Binds
13.5.4. Configuring Autobind
13.6. Using Pass-through Authentication
13.6.1. PTA Plug-in Syntax
13.6.2. Configuring the PTA Plug-in
13.6.3. PTA Plug-in Syntax Examples
13.7. Using PAM for Pass-through Authentication
13.7.1. PAM Pass-through Authentication Configuration Options
13.7.2. Configuring PAM Pass-through Authentication
13.8. Inactivating Users and Roles
13.8.1. Activating and Inactivating Users and Roles Using the Console
13.8.2. Viewing Inactive Users and Roles
13.8.3. Inactivating and Activating Users and Roles Using the Command Line
14. Configuring Secure Connections
14.1. Requiring Secure Connections
14.2. Using TLS/SSL
14.2.1. Enabling TLS/SSL: Summary of Steps
14.2.2. Obtaining and Installing Server Certificates
14.2.3. Configuring the Directory Server to Run in SSL/TLS
14.2.4. Command-Line Functions for Start TLS
14.2.5. Using certutil
14.2.6. Managing Certificates Used by the Directory Server Console
14.2.7. Updating Attribute Encryption for New SSL/TLS Certificates
14.2.8. Using External Security Devices
14.2.9. Setting Security Preferences
14.2.10. Using Certificate-Based Authentication
14.2.11. Managing Certificates for the Directory Server
14.3. Using SASL
14.3.1. About SASL Identity Mapping
14.3.2. Default SASL Mappings for Directory Server
14.3.3. Authentication Mechanisms for SASL in Directory Server
14.3.4. About Kerberos with Directory Server
14.3.5. Configuring SASL Identity Mapping
14.3.6. Configuring SASL Authentication at Directory Server Startup
14.3.7. Using an External Keytab
15. Monitoring Server and Database Activity
15.1. Types of Directory Server Log Files
15.2. Viewing Log Files
15.3. Configuring Logs
15.3.1. Enabling or Disabling Logs
15.3.2. Defining a Log File Rotation Policy
15.3.3. Defining a Log File Deletion Policy
15.3.4. Manual Log File Rotation
15.3.5. Configuring Log Levels
15.4. Replacing Log Files with a Named Pipe
15.4.1. Using the Named Pipe for Logging
15.4.2. Starting the Named Pipe with the Server
15.4.3. Using Plug-ins with the Named Pipe Log
15.5. Monitoring Server Activity
15.5.1. Monitoring the Server from the Directory Server Console
15.5.2. Monitoring the Directory Server from the Command Line
15.6. Monitoring Database Activity
15.6.1. Monitoring Database Activity from the Directory Server Console
15.6.2. Monitoring Databases from the Command Line
15.7. Monitoring Database Link Activity
15.8. Enabling and Disabling Counters
16. Monitoring Directory Server Using SNMP
16.1. About SNMP
16.2. Configuring the Master Agent
16.3. Configuring the Subagent
16.3.1. Creating the Subagent Configuration File
16.3.2. Starting the Subagent
16.3.3. Testing the Subagent
16.4. Configuring SNMP Traps
16.5. Configuring the Directory Server for SNMP
16.6. Using the Management Information Base
16.6.1. Operations Table
16.6.2. Entries Table
16.6.3. Entity Table
16.6.4. Interaction Table
17. Planning for Disaster
17.1. Identifying Potential Scenarios
17.2. Defining the Type of Rollover
17.3. Identifying Useful Directory Server Features for Disaster Recovery
17.3.1. Multi-Master Replication for Disaster Recovery
17.3.2. Chaining Databases for Disaster Recovery
17.3.3. Backing up Directory Data for Disaster Recovery
17.3.4. Using a Named Pipe Script for Disaster Recovery
17.4. Defining the Recovery Process
17.5. Basic Example: Performing a Recovery
A. LDAP Data Interchange Format
A.1. About the LDIF File Format
A.2. Continuing Lines in LDIF
A.3. Representing Binary Data
A.3.1. Standard LDIF Notation
A.3.2. Base-64 Encoding
A.4. Specifying Directory Entries Using LDIF
A.4.1. Specifying Domain Entries
A.4.2. Specifying Organizational Unit Entries
A.4.3. Specifying Organizational Person Entries
A.5. Defining Directories Using LDIF
A.5.1. LDIF File Example
A.6. Storing Information in Multiple Languages
B. LDAP URLs
B.1. Components of an LDAP URL
B.2. Escaping Unsafe Characters
B.3. Examples of LDAP URLs
C. Internationalization
C.1. About Locales
C.2. Supported Locales
C.3. Supported Language Subtypes
C.4. Searching an Internationalized Directory
C.4.1. Matching Rule Formats
C.4.2. Supported Search Types
C.4.3. International Search Examples
C.5. Troubleshooting Matching Rules
Glossary
Index

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

2. Examples and Formatting

Each of the examples used in this guide, such as file locations and commands, have certain defined conventions.

2.1. Command and File Examples

All of the examples for Red Hat Directory Server commands, file locations, and other usage are given for Red Hat Enterprise Linux 5 (64-bit) systems. Be certain to use the appropriate commands and files for your platform.

Example 1. Example Command

To start the Red Hat Directory Server:
service dirsrv start

2.2. Tool Locations

The tools for Red Hat Directory Server are located in the /usr/bin and the /usr/sbin directories. These tools can be run from any location without specifying the tool location.

2.3. LDAP Locations

There is an 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/lib64/mozldap directory on Red Hat Enterprise Linux 5 (64-bit) (or /usr/lib/mozldap for Red Hat Enterprise Linux 5 (32-bit) systems).
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.

2.4. Text Formatting and Styles

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.

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. this manual does not describe many of the basic directory and architectural concepts that you need to deploy, install, and administer a directory service successfully. Those concepts are contained in the Red Hat Directory Server Deployment Guide. You should read that book before continuing with this manual.
When you are familiar with Directory Server concepts and have done some preliminary planning for your directory service, install the Directory Server. 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 and Command-Line Tool Reference.
Also, Managing Servers with Red Hat Console contains general background information on how to use the Red Hat Console. You should read and understand the concepts in that book before you attempt to administer Directory Server.
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 Deployment Guide provides an overview for planning a deployment of the 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 and Command-Line Tool 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.
  • Red Hat Directory Server Schema Reference provides reference information about the Directory Server schema.
  • Red Hat Directory Server Plug-in Programmer's Guide describes how to write server plug-ins in order to customize and extend the capabilities of Directory Server.
  • Using Red Hat Console gives an overview of the primary user interface and how it interacts with the Directory Server and Admin Server, as well as how to perform basic management tasks through the main Console window.
  • Using the Admin Server describes the different tasks and tools associated with the Admin Server and how to use the Admin Server with the Configuration and User Directory Server instances.
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:
  1. Select the Red Hat Directory Server product.
  2. Set the component to Doc - administration-guide.
  3. Set the version number to 8.2.
  4. 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.
  5. Give a clear title for the bug. For example, "Incorrect command example for setup script options" is better than "Bad example".
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 docs@redhat.com.

5. Documentation History

Revision History
Revision 8.2.8-3.4002013-10-31Rüdiger Landmann
Rebuild with publican 4.0.0
Revision 8.2.8-32012-07-18Anthony Towns
Rebuild for Publican 3.0
Revision 8.2-15April 2, 2012Ella Deon Lackey
Removing reference to IPv6 suport for ACIs.
Revision 8.2-14January 31, 2012Ella Deon Lackey
Adding an example for the new nested DN validation attribute, Errata RHBA-2012:0064.
Revision 8.2-13July 1, 2011Ella Deon Lackey
Backing out some attribute syntax changes, Bugzilla 524991.
Revision 8.2-12June 3, 2011Ella Deon Lackey
Adding a note about nsrolefilter not supporting virtual attributes, Bugzilla 329751.
Revision 8.2-11June 3, 2011Ella Deon Lackey
Fixing ldapmodify proxy account example, Bugzilla 707585.
Revision 8.2-10May 23, 2011Ella Deon Lackey
Fixing a log setting example, Bugzilla 703711.
Revision 8.2-9April 4, 2011Ella Deon Lackey
Persistent search review, Bugzilla 367741.
Replication chapter typos, Bugzilla 690637 and Bugzilla 690823.
Revision 8.2-8February 24, 2011Ella Deon Lackey
Fixing typos, Bugzilla 680150.
Revision 8.2-7January 6, 2011Ella Deon Lackey
Fixing typos, Bugzilla 662860.
Revision 8.2-6November 19, 2010Ella Deon Lackey
Added warning note for configuring SSL in the Console, per Bugzilla #488951.
Added information on loading certificates in the Console security databases, per Bugzilla #632420.
Revision 8.2-5November 15, 2010Lee Carlon
Added information regarding replication of memberOf attribute in multi-master and single suppier, per Bugzilla #536865.
Added information regarding requirement for inetUser and memberOf attribute for MemberOf plug-in, per Bugzilla #642776.
Updated screen short for connection properties for windows sync, per Bugzilla #577400/
Updated the name of a reference guide, per Bugzilla #578642.
Revision 8.2-4November 1, 2010Ella Deon Lackey
Corrected example for using the markerobjectclass keywork with Attribute Uniqueness, per Bugzilla #646651.
Revision 8.2-3October 12, 2010Ella Deon Lackey
Corrected example for enabling the Referential Integriry plug-in, per Bugzilla #640876.
Revision 8.2-2September 17, 2010Ella Deon Lackey
Clarified some comments in the account lockout section from a customer request, per Bugzilla #621646.
Adding section on using modutil to load PKCS#11 modules, per Bugzilla #629411.
Clarifying the backup procedures with db2bak and db2bak.pl, per Bugzilla #632014.
Revision 8.2-1August 10, 2010Ella Deon Lackey
Fixing user account management example, per Bugzilla #622525.
Adding note to DNA section that the DNA plug-in cannot check multiple backends to allocate numbers, per Bugzilla #621727.
Revision 8.2-0August 3, 2010Ella Deon Lackey
Initial draft for Red Hat Directory Server version 8.2.

Chapter 1. Basic Red Hat Directory Server Settings

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.2 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 Admin 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. System Requirements

This section contains information related to installing and upgrading Red Hat Directory Server 8.2, including prerequisites and hardware or platform requirements.

1.1.1. Required JDK

Red Hat Directory Server 8.2 requires Sun JRE 1.6.0 or OpenJDK 1.6.0 for Red Hat Enterprise Linux 4 and 5.

IMPORTANT

When the new JDK is installed for Directory Server 8.2, it is no longer possible to manage older instances of Directory Server using the Directory Server Console because the required JDKs for the different Directory Server versions are different. You must migrate any older instance to Directory Server 8.2 if you need to manage that instance with the Directory Server Console.

1.1.2. Directory Server Supported Platforms

Directory Server 8.2 is supported on the following platforms:
  • Red Hat Enterprise Linux 4 i386 (32-bit)
  • Red Hat Enterprise Linux 4 x86_64 (64-bit)
  • Red Hat Enterprise Linux 5 i386 (32-bit)
  • Red Hat Enterprise Linux 5 x86_64 (64-bit)

    NOTE

    Red Hat Directory Server 8.2 is supported running on a virtual guest on a Red Hat Enterprise Linux virtual server.
  • Solaris 9 SPARC (64-bit)

1.1.3. Directory Server Console Supported Platforms

The Directory Server Console is supported on the following platforms:
  • Red Hat Enterprise Linux 4 i386 (32-bit)
  • Red Hat Enterprise Linux 4 x86_64 (64-bit)
  • Red Hat Enterprise Linux 5 i386 (32-bit)
  • Red Hat Enterprise Linux 5 x86_64 (64-bit)
  • Solaris 9 SPARC (64-bit)
  • Windows XP Professional
  • Windows Server 2003
  • Windows Server 2008 (32-bit)
  • Windows Server 2008 (64-bit)

1.1.4. Password Sync Service Platforms

The Password Sync Service runs on these Windows platforms:
  • Windows 2003 Active Directory (32-bit)
  • Windows 2003 Active Directory (64-bit)
  • Windows 2008 Active Directory (32-bit)
  • Windows 2008 Active Directory (64-bit)

1.1.5. Web Application Browser Support

Directory Server 8.2 supports the following browsers to access web-based interfaces, such as Admin Express and online help tools:
  • Firefox 3.x
  • Microsoft Internet Explorer 6.0 and higher

1.2. Directory Server File Locations

Red Hat Directory Server 8.2 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 Admin Server directories are named the same as the Directory Server directories, only instead of the instance as a directory name, the Admin 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.

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/lib/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/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/

1.3. 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 and 5 i386 /usr/lib/mozldap
Red Hat Enterprise Linux 4 and 5 x86_64 /usr/lib64/mozldap
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.

1.4. 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 14.2.3.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. Use the chkconfig command to enable the Directory Server and Admin Server to start on boot.

1.4.1. Starting and Stopping Directory Server from the Console

  1. Start the Directory Server Console.
    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.

1.4.2. Starting and Stopping Directory Server from the Command Line

The most common way to start and stop the Directory Server service is using system tools on Red Hat Enterprise Linux. For example, Linux uses the service tool:
service dirsrv {start|stop|restart} instance
Passing the instance name stops or starts only that instance; not giving any name starts or stops all instances.

NOTE

The service name for the Directory Server service on Red Hat Enterprise Linux is dirsrv.
The start/stop scripts are in the /usr/sbin directory and are run similar to the service start/stop command:
/usr/sbin/{start|stop|restart}-dirsrv instance
If the instance name is not given, then the all instances are started or stopped.
Alternatively each instance has its own start and stop scripts that apply only to that instance.
/etc/dirsrv/slapd-instance_name/{start|stop|restart}-slapd

1.4.3. Starting and Stopping Admin Server

There are two ways to start, stop, or restart the Admin Server:
  • There are scripts in the /usr/sbin directory.
    /usr/sbin/{start|stop|restart}-ds-admin
  • The Admin Server service can also be stopped and started using system tools on Red Hat Enterprise Linux. For example, on Red Hat Enterprise Linux 5 (64-bit), the command is service:
    service dirsrv-admin {start|stop|restart}

    NOTE

    The service name for the Admin Server process on Red Hat Enterprise Linux is dirsrv-admin.

1.5. Starting the Console

1.5.1. Starting the Directory Server Console

There is a simple script to launch the Directory Server Console. The script is in the standard /usr/bin directory, so it can be run as follows:
redhat-idm-console

NOTE

Make sure that the correct Sun JDK or OpenJDK version 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
The login screen prompts for the username, password, and Admin Server location. It is possible to pass other information along with the Console command to supply the Admin Server URL, password, and username. For example:
redhat-idm-console -a http://localhost:9830 -u "cn=Directory Manager" -w secret

Table 1.3. redhat-idm-console Options

Option Description
-a adminURL Specifies a base URL for the instance of Admin Server to log into.
-f fileName Writes errors and system messages to fileName.
-h Prints out the help message for redhat-idm-console.
-s Specifies the directory instance to access, either by specifying the DN of the server instance entry (SIE) or the instance name, such as slapd-example.
-u Gives the user DN to use to log into the Console.
-w Gives the password to use to log into the Console.
-w - Reads the password from the standard output.
-x options Specifies extra options. There are three values for extraOptions:
nowinpos, which puts the Console window in the upper left corner of the screen
nologo, which keeps the splash screen from being displayed and only opens the login dialog
javalaf, which uses the Java look and feel for the Console interface rather than the platform-specific styles
To use multiple options, separate them with a comma.
-y file Reads the password from the specified input file.

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

1.5.3. 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:
  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.
    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.5.4. 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.
Viewing the Bind DN

Figure 1.1. Viewing the Bind DN


1.6. Enabling LDAPI

Inter-process communication (IPC) is a way for separate processes on a Unix machine or a network to communicate directly with each other. LDAPI allows LDAP connections to run over IPC connections, meaning that LDAP operations can run over Unix sockets. These connections are much faster and more secure than regular LDAP connections.
LDAPI is enabled through two configuration attributes:
  • nsslapd-ldapilisten to enable LDAPI for Directory Server
  • nsslapd-ldapifilepath to point to the Unix socket file
To enable LDAPI:
  1. Modify the nsslapd-ldapilisten to turn LDAPI on and add the socket file attribute.
    /usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com
    
    dn: cn=config
    changetype: modify
    replace: nsslapd-ldapilisten
    nsslapd-ldapilisten: on
    -
    add: nsslapd-ldapifilepath
    nsslapd-ldapifilepath: /var/run/slapd-example.socket
  2. Restart the server to apply the new configuration.
    service dirsrv restart example

1.7. 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 Admin 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:
  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. Change the port numbers. The port number for the server to use for non-SSL communications in the Port field, with a default value of 389. The port number for the server to use for SSL communications is in the Encrypted Port field, with a default value of 636.
  4. Click Save.
  5. 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.
  6. 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 Admin Server through the Console.
  7. Open the Admin Server Console.
  8. In the Configuration tab, select the Configuration DS tab.
  9. In the LDAP Port field, type in the new LDAP port number for your Directory Server instance.
  10. 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.
  11. 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.
  12. Open the Configuration DS tab of the Admin Server Console and select Save.
    A dialog will appear, reading The Directory Server setting has been modified. You must shutdown and restart your Admin Server and all the servers in the Server Group for the changes to take effect. Click OK.
  13. In the Tasks tab of the Admin Server Console, click Restart Admin Server. A dialog opens reading that the Admin 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.8. 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:
  1. In the Red Hat Console window, select Server Group in the navigation tree, and then right-click.
  2. From the pop-up menu, select Create Instance and then Directory Server.
  3. Fill in the instance information.
    • A unique name for the server. This name must only have alphanumeric characters, a dash (-), or an underscore (_).
    • A port number for LDAP communications.
    • The root suffix for the new Directory Server instance.
    • A DN for the Directory Manager. This user has total access to every entry in the directory, without normal usage constraints (such as search timeouts); this is described in Section 1.9, “Setting the Directory Manager Information”.
    • The password for the Directory Manager.
    • The user ID as which to run the Directory Server daemon.
  4. Click OK.
A status box appears to confirm that the operation was successful. To dismiss it, click OK.

1.9. Setting the Directory Manager Information

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:
  1. Log in to the Directory Server Console as Directory Manager. For information on changing the bind DN, see Section 1.5.3, “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. Change the Directory Manager settings:
    • Change the distinguished name for the Directory Manager in the Root DN field. The default value is cn=Directory Manager.
    • Set the storage scheme for the server to use to store the password for Directory Manager in the Manager Password Encryption pull-down menu.
    • Enter a new password, and confirm it.

1.10. Using Directory Server Plug-ins

Directory Server has a number of default plug-ins which configure core Directory Server functions, such as replication, classes of service, and even attribute syntaxes. Core plug-ins are enabled and completely configured by default.
Other default plug-ins extend the functionality of the Directory Server by providing consistent, but user-defined, behaviors, as with DNA, attribute uniqueness, and attribute linking. These plug-ins are available, but not enabled or configured by default.
Using plug-ins also allows the Directory Server to be easily extended, so customers can write and deploy their own server plug-ins to perform whatever directory operations they need for their specific deployment.
The details of configuring and deploying plug-ins are covered in other guides (primarily the Plug-in Programmer's Guide and to some extent in the plug-in attribute reference in the Configuration and Command-Line Tool Reference). This section covers common adminsitrative tasks for all plug-ins.

1.10.1. Enabling Plug-ins

To enable and disable plug-ins over LDAP using the Directory Server Console:
  1. In the Directory Server Console, select the Configuration tab.
  2. Double-click the Plugins folder in the navigation tree.
  3. Select the plug-in from the Plugins list.
  4. To disable the plug-in, clear the Enabled checkbox. To enable the plug-in, check this checkbox.
  5. Click Save.
  6. Restart the Directory Server.
    service dirsrv restart instance_name
To disable or enable a plug-in through the command line, use the ldapmodify utility to edit the value of the nsslapd-pluginEnabled attribute. For example: [1]
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=ACL Plugin,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginEnabled
nsslapd-pluginEnabled: on

1.10.2. Setting the Plug-in Precedence

The plug-in precedence is the priority it has in the execution order of plug-ins. For pre- and post-operation plug-ins, this allows one plug-in to be executed and complete before the next plug-in is initiated, which lets the second plug-in take advantage of the first plug-in's results.
Plug-in precedence is configured in the nsslapd-pluginPrecedence attribute on the plug-in's configuration entry. This attribute has a value of 1 (highest priority) to 99 (lowest priority). If the attribute is not set, it has a default value of 50.
The nsslapd-pluginPrecedence attribute is set using the ldapmodify command. For example:
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=My Example Plugin,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginPrecedence
nsslapd-pluginPrecedence: 1

IMPORTANT

Don't set the plug-in precedence for the default Directory Server plug-ins unless told to do so by Red Hat support. The plug-in precedence attribute is primarily to govern the behavior of custom plug-ins, not to change the behavior of the core Directory Server plug-ins.


[1] The LDAP tools referenced in this guide are Mozilla LDAP, installed with Directory Server in the /usr/lib64/mozldap directory on Red Hat Enterprise Linux 5 (64-bit); directories for other platforms are listed in Section 1.3, “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.

Chapter 2. 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.
For a discussion of concepts about distributing directory data, see the Directory Server Deployment Guide.

2.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 2.1, “A Directory Tree with One Root Suffix”.
A Directory Tree with One Root Suffix

Figure 2.1. A 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.

2.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, 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 2.2, “A Directory Tree with Two Root Suffixes”.
A Directory Tree with Two Root Suffixes

Figure 2.2. A 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 2.3, “A Directory Tree with a Root Suffix Off Limits to Search Operations”.
A Directory Tree with a Root Suffix Off Limits to Search Operations

Figure 2.3. A 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 2.4, “A Directory Tree with a Sub Suffix”.
A Directory Tree with a Sub Suffix

Figure 2.4. A 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.

2.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.
  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, 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 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.
The new root suffix is listed under the Data folder.

2.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.
    If the checkbox is not selected, than the database for the new sub suffix must be created later. The new sub suffix is disabled until a database is created.
The suffix appears automatically under its root suffix in the Data tree in the left navigation pane.

2.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. [2]
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
    ldapmodify binds to the server and prepares it to add an entry to the configuration file.
  2. Create the root suffix entry.

    Example 2.1. Example 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
    cn: dc=example,dc=com

  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:

Table 2.1. Suffix Attributes

Attribute Name Value
dn Defines the DN for the suffix. The DN is contained in quotes. The value entered takes the form cn=dc=example\,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.
The default value is disabled.
nsslapd-referral Defines the LDAP URL of the referral to be returned by the suffix. This attribute can be multi-valued, 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 2.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 2.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 2.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.

2.1.2. Maintaining Suffixes

This section describes the following procedures:

2.1.2.1. Disabling a Suffix

Sometimes, a database may need taken down for maintenance, but the data the database contains are 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:
  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.

2.1.2.2. 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. Right-click the suffix, and select Delete from the menu.
  4. Select either Delete this suffix and all of its sub suffixes or Delete this suffix only.

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

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

2.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.
  4. Enter a unique name for the database, such as example2. The database name can be a combination of alphanumeric characters, dashes (-), and underscores (_).
    The Create database in field is automatically filled with the default database directory (/var/lib/dirsrv/slapd-instance_name/db) and the name of the new database. It is also possible to enter or browse for a different directory location.

2.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:[2]
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
    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 2.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.

2.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.
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.
2.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. The databases associated with the suffix are already listed in the Databases tab. Click Add to associate additional databases with the suffix.
  5. Enter the path to the distribution library.
  6. Enter the name of the distribution function in the Function name field.
2.2.1.3.2. Adding the Custom Distribution Function to a Suffix Using the Command Line
  1. Run ldapmodify.[2]
    /usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com
  2. Add the following attributes to the suffix entry itself, supplying the information about the custom distribution logic:
    changetype: modify
    add: nsslapd-backend
    nsslapd-backend: Database1 
    -
    add: nsslapd-backend
    nsslapd-backend: Database2 
    -
    add: nsslapd-backend
    nsslapd-backend: Database3 
    -
    add: nsslapd-distribution-plugin
    nsslapd-distribution-plugin: /full/name/of/a/shared/library 
    -
    add: nsslapd-distribution-funct
    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 3.2.4, “Adding and Modifying Entries Using ldapmodify”.

2.2.2. Maintaining Directory Databases

2.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.
2.2.2.1.1. Making a Database Read-Only Using the Console
  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.
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.
2.2.2.1.2. Making a Database Read-Only from the Command Line
To manually place a database into read-only mode:
  1. Run ldapmodify.[2]
    /usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com
  2. Change the read-only attribute to on
    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.
2.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:
  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.

2.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. Expand the Data folder, and then select the suffix.
  3. Select the database to delete.
  4. Right-click the database and select Delete from the pop-up menu.
  5. Confirm that the database should be deleted in the Delete Database dialog box.

2.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.
    service 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.
    service dirsrv start example

2.2.3. Configuring Attribute 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 attribute 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 attribute 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.

2.2.3.1. Encryption Keys

In order to use attribute encryption, the server must be configured for SSL and have SSL enabled because attribute 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 attribute 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.

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.

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

2.2.3.3. Configuring Attribute Encryption from the Console

  1. In the Configuration tab, select the Data node.
  2. Expand the suffix, and select the database to edit.
  3. Select the Attribute Encryption tab.
  4. Click the Add Attribute button to open the list of attributes. Select the attribute to encrypt.

    NOTE

    For existing attribute values to be encrypted, the information must be exported from the database, then re-imported. See Section 2.2.3.5, “Exporting and Importing an Encrypted Database”.
  5. Select which encryption cipher to use.

NOTE

The encryption cipher to use is set separately for each attribute, so attribute encryption is applied to each attribute one at a time.
To remove encryption from attributes, select them from the list of encrypted attributes in the Attribute Encryption table, click the Delete button, and then click Save to apply the changes. Any deleted attributes have to be manually re-added after saving.

2.2.3.4. Configuring Attribute Encryption Using the Command Line

  1. Run the ldapmodify command[2]:
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.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 re-imported. See Section 2.2.3.5, “Exporting and Importing an Encrypted Database”.
For more information on attribute 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 and Command-Line Tool Reference.

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

NOTE

When enabling encryption for data that is already present in the database, several additional security concerns arise:
  • 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.

2.2.3.6. Updating Attribute Encryption Keys for New SSL/TLS Certificates

When SSL is first configured, there is no problem with attribute encryption. However, if the SSL certificate is changed, then attribute encryption fails, with messages like these:
Apr  4 13:00:35 smtp1 logger: [04/Apr/2010:13:00:34 -0700] - attrcrypt_unwrap_key: failed to unwrap key for cipher AES
Apr  4 13:00:35 smtp1 logger: [04/Apr/2010:13:00:34 -0700] - Failed to retrieve key for cipher AES in attrcrypt_cipher_init
Apr  4 13:00:35 smtp1 logger: [04/Apr/2010:13:00:34 -0700] - Failed to initialize cipher AES in attrcrypt_init
Apr  4 13:00:35 smtp1 logger: [04/Apr/2010:13:00:34 -0700] - attrcrypt_unwrap_key: failed to unwrap key for cipher AES
Apr  4 13:00:35 smtp1 logger: [04/Apr/2010:13:00:34 -0700] - Failed to retrieve key for cipher AES in attrcrypt_cipher_init
Apr  4 13:00:35 smtp1 logger: [04/Apr/2010:13:00:34 -0700] - Failed to initialize cipher AES in attrcrypt_init
This is because the previously-generated keys do not work with the new server certificate. To correct these errors, force the server to generate new keys for attribute encryption:
  1. Stop the server.
    service dirsrv stop
  2. Open the dse.ldif file.
    vim /etc/dirsrv/dse.ldif
  3. There are special encryption key entries for the encryption ciphers used for attribute encryption under the database configuration. For example:
    dn: cn=AES,cn=encrypted attribute keys,cn=userRoot,cn=ldbm database,cn=plugins,cn=config
    objectClass: top
    objectClass: extensibleObject
    cn: AES
    nssymmetrickey:: mSLm/RlCLvPZrSdARHPowedF9zKx+kjVTww5ARE4w0lbl2YlYvrI3bNg=
    Delete these entries.
  4. Start the server again.
    service dirsrv start

2.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.
For more general information about chaining, refer to the chapter "Designing the Directory Topology," in the Directory Server Deployment Guide. Section 15.7, “Monitoring Database Link Activity” covers how to monitor database link activity.

2.3.1. Creating a New Database Link

The basic database link configuration requires four piece of 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.

NOTE

If secure binds are required for simple password authentication (Section 13.5.1, “Requiring Secure Binds”), then any chaining operations will fail unless they occur over a secure connection. Using a secure connection (SSL/TLS and Start TLS connections or SASL authentication) is recommended, anyway.

2.3.1.1. Creating a New Database Link Using the Console

  1. In the Directory Server Console, select the Configuration tab.
  2. Create a new suffix as described in Section 2.1.1, “Creating Suffixes”.
    Deselect the Create associated database automatically checkbox. It is simpler to configure a database link on a suffix without a database associated with it because having both a database and database link requires custom distribution functions to distribute directory data.
  3. In the left pane, right-click the new suffix, and select New Database Link from the pop-up menu.
  4. Fill in the database link name. The name can be a combination of alphanumeric characters, dashes (-), and underscores (_). No other characters, like spaces, are allowed.
  5. Set the radio button for the appropriate method for authentication.
    There are four authentication methods:
    • Simple means that the server connects over the standard port with no encryption. The only required information is the bind DN and password for the user as whom the server connects to the remote server.
    • Server TLS/SSL Certificate uses the local server's SSL certificate to authenticate to the remote server. A certificate must be installed on the local server for certificate-based authentication, and the remote server must have certificate mapping configured so that it can map the subject DN in the local server's certificate to the corresponding user entry.
      Configuring SSL and certificate mapping is described in Section 14.2, “Using TLS/SSL”.

      NOTE

      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.
    • SASL/DIGEST-MD5 requires only the bind DN and password to authenticate.
    • SASL/GSSAPI requires the local server to have a Kerberos keytab (as in Section 14.3.4.2, “About the KDC Server and Keytabs”), and the remote server to have a SASL mapping to map the local server's principal to the real user entry (as in Section 14.3.5.1, “Configuring SASL Identity Mapping from the Console”).
  6. In the Remote Server Information section, select the connection type for the local server to use to connect to the remote server. There are three options:
    • Use LDAP. This sets a standard, unencrypted connection.
    • Use TLS/SSL. This uses a secure connection over the server's secure LDAPS port, such as 636. This setting is required to use TLS/SSL.
      When using SSL/TLS, make sure that the remote server's port number is set to its secure port.
    • Use Start TLS. This uses Start TLS to establish a secure connection over the server's standard port.

    NOTE

    If secure binds are required for simple password authentication (Section 13.5.1, “Requiring Secure Binds”), then any chaining operations will fail unless they occur over a secure connection. Using a secure connection (SSL/TLS and Start TLS connections or SASL authentication) is recommended, anyway.
  7. In the Remote Server Information section, fill in the name and port number for the remote server.
    For any failover servers, fill in the hostname and port number, and click the Add button. A failover server is a backup server, so that if the primary remote server fails, the database link contacts the first server in the failover servers list and cycles through the list until a server is accessed.
The new database link is listed under the suffix, in place of the database.

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 is in the Remote server checklist box.

2.3.1.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.
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.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

NOTE

If secure binds are required for simple password authentication (Section 13.5.1, “Requiring Secure Binds”), then any chaining operations will fail unless they occur over a secure connection. Using a secure connection (SSL/TLS and Start TLS connections or SASL authentication) is recommended, anyway.
Default configuration attributes are contained in the cn=default instance 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 and Command-Line Tool Reference.
2.3.1.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.

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.
2.3.1.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:
  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.
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.
For more information on ACIs, see Chapter 12, 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.
2.3.1.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/

NOTE

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 and points to the secure port of the server. For example:
nsFarmServerURL: ldaps://africa.example.com:636/

NOTE

SSL has to be enabled on the local Directory Server and the remote Directory Server to be chained over SSL. For more information on enabling SSL, see Section 14.2.1, “Enabling TLS/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.
2.3.1.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.
2.3.1.2.5. Using Different Bind Mechanisms
The local server can connect to the remote server using several different connection types and authentication mechanisms.
There are three ways that the local server can connect to the remote server:
  • Over the standard LDAP port
  • Over a dedicated TLS/SSL port
  • Using Start TLS, which is a secure connection over a standard port

NOTE

If secure binds are required for simple password authentication (Section 13.5.1, “Requiring Secure Binds”), then any chaining operations will fail unless they occur over a secure connection. Using a secure connection (SSL/TLS and Start TLS connections or SASL authentication) is recommended, anyway.
Ultimately, there are two connection settings. The TLS/SSL option signifies that both of the servers are configured to run and accept connections over TLS/SSL, but there is no separate configuration attribute for enforcing TLS/SSL.
The connection type is identified in the nsUseStartTLS attribute. When this is on, then the server initiates a Start TLS connect over the standard port. If this is off, then the server either uses the LDAP port or the TLS/SSL port, depending on what is configured for the remote server in the nsFarmServerURL attribute.
For example, to use Start TLS:
nsUseStartTLS: on
For example, to use a standard connection or TLS/SSL connection:
nsUseStartTLS: off
There are four different methods which the local server can use to authenticate to the farm server.
  • empty. If there is no bind mechanism set, then the server performs simple authentication and requires the nsMultiplexorBindDN and nsMultiplexorCredentials attributes to give the bind information.
  • EXTERNAL. This uses an SSL certificate to authenticate the farm server to the remote server. Either the farm server URL must be set to the secure URL (ldaps) or the nsUseStartTLS attribute must be set to on.
    Additionally, the remote server must be configured to map the farm server's certificate to its bind identity, as described in Section 14.2.10.2, “Mapping DNs to Certificates”.
  • DIGEST-MD5. This uses SASL authentication with DIGEST-MD5 encryption. As with simple authentication, this requires the nsMultiplexorBindDN and nsMultiplexorCredentials attributes to give the bind information.
  • GSSAPI. This uses Kerberos-based authentication over SASL.
    The farm server must be configured with a Kerberos keytab, and the remote server must have a defined SASL mapping for the farm server's bind identity. Setting up Kerberos keytabs and SASL mappings is described in Section 14.3, “Using SASL”.

NOTE

SASL connections can be established over standard connections or SSL/TLS connections.
For example:
nsBindMechanism: EXTERNAL

NOTE

If SASL is used, then the local server must also be configured to chain the SASL and password policy components. Add the components for the database link configuration, as described in Section 2.3.2, “Configuring the Chaining Policy”. For example:
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=config,cn=chaining database,cn=plugins,cn=config
changetype: modify
add: nsActiveChainingComponents
nsActiveChainingComponents: cn=password policy,cn=components,cn=config
-
add: nsActiveChainingComponents
nsActiveChainingComponents: cn=sasl,cn=components,cn=config
^D
2.3.1.2.6. 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.

Table 2.2. Database Link Configuration Attributes

Attributes Value
nsTransmittedControls [†] Gives the OID of LDAP controls forwarded by the database link to the remote data server.
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.
nsUseStartTLS Sets whether to use Start TLS to establish a secure connection over a standard port. The default is off, which is used for both simple (standard) connections and TLS/SSL connections.
nsBindMethod Sets the authentication method to use to authenticate (bind) to the remote server. The default, if this attribute is not given, is to authenticate using a simple bind, requiring the nsMultiplexorBindDN and nsMultiplexorCredentials attributes for the bind information.
null; this is a simple bind.
EXTERNAL (certificate-based); certificate mapping must be enabled for this.
DIGEST-MD5 (SASL); this, like a simple bind, requires the bind DN and password.
GSSAPI (SASL); this requires the keytab to be configured on the local server and SASL identity mapping on the remote server.
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 2.3.2.1, “Chaining Component Operations”.
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.

2.3.1.2.7. 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.
  1. Run ldapmodify[2] to add a database link to Server A:
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.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
         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 2.3.6, “Database Links and Access Control Evaluation”.

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

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

Table 2.3. Components Allowed to Chain

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 external bind method is used. It retrieves the user certificate from the database on the remote server. Allowing 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. Read, search, and compare
Password policy component This component is used to allow SASL binds to the remote server. Some forms of SASL authentication require authenticating with a username and password. Enabling the password policy allows the server to verify and implement the specific authentication method requested and to apply the appropriate password policies. To chain this component's operations, add the chaining component attribute, nsActiveChainingComponents: cn=password policy,cn=components,cn=config. Read, search, and compare
SASL component This component is used to allow SASL binds to the remote server. To chain this component's operations, add the chaining component attribute, nsActiveChainingComponents: cn=password policy,cn=components,cn=config. Read, search, and compare
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 attribute are unique (no duplicates). If this plug-in is chained, it confirms that 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
Roles component This component chains the roles and roles assignments for the entries in a database. Chaining this component maintains the roles even on chained databases. To chain this component's operations, add the chaining component attribute, nsActiveChainingComponents: cn=roles,cn=components,cn=config. Read, write, search, and compare

NOTE

The following components cannot be chained:
  • 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 12.1.4, “ACI Limitations”.
2.3.2.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.
  4. Click the Add button in the Components allowed to chain section.
  5. Select the component to chain from the list, and click OK.
  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";)
2.3.2.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
    See Table 2.3, “Components Allowed to Chain” for a list of the components which can be chained.
  2. Restart the server for the change to take effect.
    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";)

2.3.2.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, usually using a specific matching rule.
  • Simple paged results. This control breaks entry results into smaller pages, where the user specifies the page size. This is similar to VLV indexes for results, only without maintaining an index.
  • Dereferencing. This control tracks back over references in entry attributes in a search and pulls specified attribute information from the referenced entry and returns it with the rest of the search results.
  • 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 2.4.4, “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.
2.3.2.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.
  4. Click the Add button in the LDAP Controls forwarded by the database link section to add an LDAP control to the list.
  5. Select the OID of a control to add to the list, and click OK.
2.3.2.2.2. Chaining LDAP Controls from the Command Line
To chain controls, 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 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:

Table 2.4. LDAP Controls and Their OIDs

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
Simple paged results 1.2.840.113556.1.4.319
Managed DSA 2.16.840.1.113730.3.4.2
Loop detection 1.3.6.1.4.1.1466.29539.12
Dereferencing searches 1.3.6.1.4.1.4203.666.5.16

For more information about LDAP controls, refer to the LDAP C-SDK documentation at http://www.mozilla.org/directory.

2.3.3. Maintaining Database Links

All of the information for the database link for the connection to the remote server.
  1. In the Directory Server Console, select the Configuration tab.
  2. In the left pane, expand the Data folder, and select the database link under the suffix.
  3. In the right navigation pane, click the Authentication tab.
  4. Change the connection information.
    • The LDAP URL for the remote server.[2]
    • The bind DN and password used by the database link to bind to the remote server.

2.3.4. Configuring Database Link Defaults

Configuring the default settings for database links defines the settings used for cascading chaining (the number of hops allowed for a client request), the connection rules for the remote server, and how the server responds to client requests.
  1. Select the Configuration tab.
  2. Expand the Data folder in the left pane, and click Database Link Settings. Open the Default Creation Parameters tab.
  3. Fill in the new configuration parameters.

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.

2.3.5. Deleting Database Links

To delete a database link, right-click the database link, and select Delete from the pop-up menu. Confirm the delete when prompted.
  1. In the Directory Server Console, select the Configuration tab.
  2. Under Data in the left navigation pane, open the suffix and select the database link to delete.
  3. Right-click the database link, and select Delete from the menu.

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

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

2.4.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.
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 ACIs applying to the client are evaluated only after the request has been chained to the destination server, in the above example Server 2.
For example, on Server A, a directory tree is split:
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:
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.

2.4.2. Configuring Cascading Chaining Using the Console

  1. Select the Configuration tab. Expand the Data folder in the left pane, and select the suffix, then the database link.
  2. 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.

2.4.3. Configuring Cascading Chaining from the Command Line

To configure a cascade of database links through the command line:
  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/
  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 2.3.2.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.
    1. 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 2.2.1, “Creating Databases”.
    2. Create an entry that corresponds to the administrative user in the database.
    3. 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:
    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.

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

2.4.5. Summary of Cascading Chaining Configuration Attributes

The following table describes the attributes used to configure intermediate database links in a cascading chain:

Table 2.5. Cascading Chaining Configuration Attributes

Attribute Description
nsFarmServerURL URL of the server containing the next database link in the cascading chain.
nsTransmittedControls Enter the following OIDs to the database links involved in the cascading chain:
nsTransmittedControls: 2.16.840.1.113730.3.4.12 
nsTransmittedControls: 1.3.6.1.4.1.1466.29539.12
The first OID corresponds to the Proxy Authorization Control. The second OID corresponds to the Loop Detection Control.
aci This attribute must contain the following ACI:
aci: (targetattr = "*")(version 3.0; acl "Proxied 
     authorization for database links";
     allow (proxy) userdn = "ldap:///cn=proxy admin,cn=config";)
nsCheckLocalACI To enable evaluation of local ACIs on all database links involved in chaining, turn local ACI evaluation on, as follows:
nsCheckLocalACI: on

2.4.6. Cascading Chaining Configuration Example

To create a cascading chain involving three servers as in the diagram below, the chaining components must be configured on all three servers.

2.4.6.1. Configuring Server One

  1. Run ldapmodify[2]:
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
  2. Then specify the configuration information for the database link, DBLink1, on Server 1, as follows:
    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=server1 proxy admin,cn=config 
    nsmultiplexorcredentials: secret 
    cn: DBLink1 
    nsCheckLocalACI:off
    
    dn: cn=c=africa\,ou=people\,dc=example\,dc=com,cn=mapping tree,cn=config
    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
    The first section creates the entry associated with DBLink1. The second section creates a new suffix, allowing the server to direct requests made to the database link to the correct server. The nsCheckLocalACI attribute does not need to be configured to check local ACIs, as this is only required on the database link, DBLink2, on Server 2.
  3. To implement loop detection, to specify the OID of the loop detection control in the nsTransmittedControl attribute stored in cn=config,cn=chaining database,cn=plugins,cn=config entry on Server 1.
    dn: cn=config,cn=chaining database,cn=plugins,cn=config 
    changetype: modify 
    add: nsTransmittedControl 
    nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12
    As the nsTransmittedControl attribute is usually configured by default with the loop detection control OID 1.3.6.1.4.1.1466.29539.12 value, it is wise to check beforehand whether it already exists. If it does exist, this step is not necessary.

2.4.6.2. Configuring Server Two

  1. Create a proxy administrative user on Server 2. This administrative user will be used to allow Server 1 to bind and authenticate to Server 2. It is useful to choose a proxy administrative user name which is specific to Server 1, as it is the proxy administrative user which will allow server one to bind to Server 2. Create the proxy administrative user, as follows:
    dn: cn=server1 proxy admin,cn=config
    objectclass: person
    objectclass: organizationalPerson
    objectclass: inetOrgPerson
    cn: server1 proxy admin
    sn: server1 proxy admin
    userPassword: secret
    description: Entry for use by database links

    WARNING

    Do not use the Directory Manager or Administrator ID user as the proxy administrative user on the remote server. This creates a security hole.
  2. Configure the database link, DBLink2, on Server 2, using ldapmodify:
    dn: cn=DBLink2,cn=chaining database,cn=plugins,cn=config 
    objectclass: top 
    objectclass: extensibleObject 
    objectclass: nsBackendInstance 
    nsslapd-suffix: l=Zanzibar,c=africa,ou=people,dc=example,dc=com
    nsfarmserverurl: ldap://zanz.africa.example.com:389/ 
    nsmultiplexorbinddn: cn=server2 proxy admin,cn=config 
    nsmultiplexorcredentials: secret 
    cn: DBLink2 
    nsCheckLocalACI:on
    
    dn: cn=l=Zanzibar\,c=africa\,ou=people\,dc=example\,dc=com,cn=mapping tree,cn=config 
    objectclass: top 
    objectclass: extensibleObject 
    objectclass: nsMappingTree 
    nsslapd-state: backend 
    nsslapd-backend: DBLink2 
    nsslapd-parent-suffix: c=africa,ou=people,dc=example,dc=com
    cn: l=Zanzibar\,c=africa\,ou=people\,dc=example\,dc=com
    Since database link DBLink2 is the intermediate database link in the cascading chaining configuration, set the nsCheckLocalACI attribute to on to allow the server to check whether it should allow the client and proxy administrative user access to the database link.
  3. The database link on Server 2 must be configured to transmit the proxy authorization control and the loop detection control. To implement the proxy authorization control and the loop detection control, specify both corresponding OIDs. Add the following information to the cn=config,cn=chaining database,cn=plugins,cn=config entry on Server 2:
    dn: cn=config,cn=chaining database,cn=plugins,cn=config 
    changetype: modify 
    add: nsTransmittedControl 
    nsTransmittedControl: 2.16.840.1.113730.3.4.12 
    nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12
    nsTransmittedControl: 2.16.840.1.113730.3.4.12 is the OID for the proxy authorization control. nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12 is the or the loop detection control.
    Check beforehand whether the loop detection control is already configured, and adapt the above command accordingly.
  4. Configure the ACIs. On Server 2, ensure that a suffix exists above the l=Zanzibar,c=africa,ou=people,dc=example,dc=com suffix, so that the following actions are possible:
    • Add the database link suffix
    • Add a local proxy authorization ACI to allow Server 1 to connect using the proxy authorization administrative user created on Server 2
    • Add a local client ACI so the client operation succeeds on Server 2, and it can be forwarded to server three. This local ACI is needed because local ACI checking is turned on for the DBLink2 database link.
    Both ACIs will be placed on the database that contains the c=africa,ou=people,dc=example,dc=com suffix.

    NOTE

    To create these ACIs, the database corresponding to the c=africa,ou=people,dc=example,dc=com suffix must already exist to hold the entry. This database needs to be associated with a suffix above the suffix specified in the nsslapd-suffix attribute of each database link. That is, the suffix on the final destination server should be a sub suffix of the suffix specified on the intermediate server.
    1. Add the local proxy authorization ACI to the c=africa,ou=people,dc=example,dc=com entry:
      aci:(targetattr="*")(target="l=Zanzibar,c=africa,ou=people,dc=example,dc=com")
           (version 3.0; acl "Proxied authorization for database links"; allow (proxy) 
           userdn = "ldap:///cn=server1 proxy admin,cn=config";)
    2. Then add the local client ACI that will allow the client operation to succeed on Server 2, given that ACI checking is turned on. This ACI is the same as the ACI created on the destination server to provide access to the l=Zanzibar,c=africa,ou=people,dc=example,dc=com branch. All users within c=us,ou=people,dc=example,dc=com may need to have update access to the entries in l=Zanzibar,c=africa,ou=people,dc=example,dc=com on server three. Create the following ACI on Server 2 on the c=africa,ou=people,dc=example,dc=com suffix to allow this:
      aci:(targetattr="*")(target="l=Zanzibar,c=africa,ou=people,dc=example,dc=com")
           (version 3.0; acl "Client authorization for database links"; allow (all) 
           userdn = "ldap:///uid=*,c=us,ou=people,dc=example,dc=com";)
      This ACI allows clients that have a UID in c=us,ou=people,dc=example,dc=com on Server 1 to perform any type of operation on the l=Zanzibar,c=africa,ou=people,dc=example,dc=com suffix tree on server three. If there are users on Server 2 under a different suffix that will require additional rights on server three, it may be necessary to add additional client ACIs on Server 2.

2.4.6.3. Configuring Server Three

  1. Create an administrative user on server three for Server 2 to use for proxy authorization:
    dn: cn=server2 proxy admin,cn=config
    objectclass: person
    objectclass: organizationalPerson
    objectclass: inetOrgPerson
    cn: server2 proxy admin
    sn: server2 proxy admin
    userPassword: secret
    description: Entry for use by database links
  2. Then add the same local proxy authorization ACI to server three as on Server 2. Add the following proxy authorization ACI to the l=Zanzibar,ou=people,dc=example,dc=com entry:
    aci: (targetattr = "*")(version 3.0; acl "Proxied authorization
         for database links"; allow (proxy) userdn = "ldap:///cn=server2
         proxy admin,cn=config";)
    This ACI gives the Server 2 proxy admin read-only access to the data contained on the remote server, server three, within the l=Zanzibar,ou=people,dc=example,dc=com subtree only.
  3. Create a local client ACI on the l=Zanzibar,ou=people,dc=example,dc=com subtree that corresponds to the original client application. Use the same ACI as the one created for the client on Server 2:
    aci: (targetattr ="*")(target="l=Zanzibar,c=africa,ou=people,dc=example,dc=com")
         (version 3.0; acl "Client authentication for database link users"; allow (all) 
         userdn = "ldap:///uid=*,c=us,ou=people,dc=example,dc=com";)
The cascading chaining configuration is now set up. This cascading configuration allows a user to bind to Server 1 and modify information in the l=Zanzibar,c=africa,ou=people,dc=example,dc=com branch on server three. Depending on your security needs, it may be necessary to provide more detailed access control.

2.5. Using Referrals

Referrals tell client applications which server to contact for a specific piece of information. This redirection occurs when a client application requests a directory entry that does not exist on the local server or when a database has been taken off-line for maintenance. This section contains the following information about referrals:
For conceptual information on how to use referrals in the directory, see the Directory Server Deployment Guide.

2.5.1. Starting the Server in Referral Mode

Referrals are used to redirect client applications to another server while the current server is unavailable or when the client requests information that is not held on the current server. For example, starting Directory Server in referral mode while there are configuration changes being made to the Directory Server will refer all clients to another supplier while that server is unavailable. Starting the Directory Server in referral mode is done with the refer command.
Run nsslapd with the refer option.
/usr/sbin/ns-slapd refer -D /etc/dirsrv/slapd-instance_name [-p port] -r referral_url
  • /etc/dirsrv/slapd-instance_name is the directory where the Directory Server configuration files are. This is the default location on Red Hat Enterprise Linux 5 (64-bit).
  • port is the optional port number of the Directory Server to start in referral mode.
  • referral_url is the referral returned to clients. The format of an LDAP URL is covered in Appendix B, LDAP URLs.

2.5.2. Setting Default Referrals

Default referrals are returned to client applications that submit operations on a DN not contained within any of the suffixes maintained by the directory. The following procedures describes setting a default referral for the directory using the console and the command-line utilities.

2.5.2.1. Setting a Default Referral Using the Console

  1. In the Directory Server Console, select the Configuration tab.
  2. Select the top entry in the navigation tree in the left pane.
  3. Select the Settings tab in the right pane.
  4. Enter an LDAP URL for the referral.
    Enter multiple referral URLs separated by spaces and in quotes:
    "ldap://dir1.example.com:389/dc=example,dc=com" "ldap://dir2.example.com/"
    For more information about LDAP URLs, see Appendix B, LDAP URLs.

2.5.2.2. Setting a Default Referral from the Command Line

ldapmodify can add a default referral to the cn=config entry in the directory's configuration file. For example, to add a new default referral from one Directory Server, dir1.example.com, to a server named dir2.example.com, add a new line to the cn=config entry.
  1. Run the ldapmodify utility:[2]
    /usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com
    ldapmodify binds to the server and prepares it to change an entry in the configuration file.
  2. Add the default referral to the dir2.example.com server:
    dn: cn=config
    changetype: modify
    replace: nsslapd-referral
    nsslapd-referral: ldap://dir2.example.com/
After adding the default referral to the cn=config entry of the directory, the directory will return the default referral in response to requests made by client applications. The Directory Server does not need to be restarted.

2.5.3. Creating Smart Referrals

Smart referrals map a directory entry or directory tree to a specific LDAP URL. Using smart referrals, client applications can be referred to a specific server or a specific entry on a specific server.
For example, a client application requests the directory entry uid=jdoe,ou=people,dc=example,dc=com. A smart referral is returned to the client that points to the entry cn=john doe,o=people,l=europe,dc=example,dc=com on the server directory.europe.example.com.
The way the directory uses smart referrals conforms to the standard specified in RFC 2251 section 4.1.11. The RFC can be downloaded at http://www.ietf.org/rfc/rfc2251.txt.

2.5.3.1. Creating Smart Referrals Using the Directory Server Console

  1. In the Directory Server Console, select the Directory tab.
  2. Browse through the tree in the left navigation pane, and select the entry for which to add the referral.
  3. Right-click the entry, and select Set Smart Referrals.
  4. Select the Enable Smart Referral checkbox. (Unchecking the option removes all smart referrals from the entry and deletes the referral object class from the entry.)
  5. In the Enter a new Smart Referral field, enter a referral in the LDAP URL format, and then click Add. The LDAP URL must be in the following format:
    ldap://hostname:portnumber/[optional_dn]
    optional_dn is the explicit DN for the server to return to the requesting client application.
    Construct opens a wizard to direct the process of adding a referral.
    The Smart Referral List lists the referrals currently in place for the selected entry. The entire list of referrals is returned to client applications in response to a request with the Return Referrals for All Operations or Return Referrals for Update Operations options in the Suffix Settings tab, which is available under the Configuration tab.
    To modify the list, click Edit to edit the selected referral or Delete to delete the selected referral.
  6. To set the referral to use different authentication credentials, click Authentication, and specify the appropriate DN and password. This authentication remains valid only until the Console is closed; then it's reset to the same authentication used to log into the Console.

2.5.3.2. Creating Smart Referrals from the Command Line

Use the ldapmodify command-line utility[2] to create smart referrals from the command line.
To create a smart referral, create the relevant directory entry, and add the referral object class. This object class allows a single attribute, ref. The ref attribute must contain an LDAP URL.
For example, add the following to return a smart referral for an existing entry, uid=jdoe:
dn: uid=jdoe,ou=people,dc=example,dc=com 
objectclass: referral
ref: ldap://directory.europe.example.com/cn=john%20doe,ou=people,l=europe,dc=example,dc=com

NOTE

Any information after a space in an LDAP URL is ignored by the server. For this reason, use %20 instead of spaces in any LDAP URL used as a referral.
To add the entry uid=jdoe,ou=people,dc=example,dc=com with a referral to directory.europe.example.com, include the following in the LDIF file before importing:
dn: uid=jdoe,ou=people,dc=example,dc=com 
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
objectclass: referral
cn: john doe
sn: doe
uid: jdoe
ref: ldap://directory.europe.example.com/cn=john%20doe,ou=people,l=europe,dc=example,dc=com
Use the -M option with ldapmodify when there is already a referral in the DN path. For information about the ldapmodify utility, see the Directory Server Configuration and Command-Line Tool Reference.

2.5.4. Creating Suffix Referrals

The following procedure describes creating a referral in a suffix. This means that the suffix processes operations using a referral rather than a database or database link.

WARNING

When a suffix is configured to return referrals, the ACIs contained by the database associated with the suffix are ignored.

2.5.4.1. Creating Suffix Referrals Using the Console

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:
  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 ... Operations radio button.
    Selecting Return Referrals for Update Operations means that the directory redirects only update and write requests to a read-only database. For example, there may be a local copy of directory data, and that data should be available for searches but not for updates, so it's replicated across several servers. Enabling referrals for that Directory Server only for update requests means that when a client asks to update an entry, the client is referred to the server that owns the data, where the modification request can proceed.
  4. Click the Referrals tab. Enter an LDAP URL in the[3] in the Enter a new referral field, or click Construct to create an LDAP URL.
  5. Click Add to add the referral to the list.
    You can enter multiple referrals. The directory returns the entire list of referrals in response to requests from client applications.

2.5.4.2. Creating Suffix Referrals from the Command Line

Add a suffix referral to the root or sub suffix entry in the directory configuration file under the cn=mapping tree,cn=config branch.
  1. Run ldapmodify.[2] For example:
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
    The ldapmodify utility binds to the server and prepares it to add information to the configuration file.
  2. Add a suffix referral to the ou=people,dc=example,dc=com root suffix, as follows:
    dn: cn=ou=people,dc=example,dc=com,cn=mapping tree,cn=config
    objectclass: extensibleObject
    objectclass: nsMappingTree
    nsslapd-state: referral
    nsslapd-referral: ldap://zanzibar.com/
    The nsslapd-state attribute is set to referral, meaning that a referral is returned for requests made to this suffix. The nsslapd-referral attribute contains the LDAP URL of the referral returned by the suffix, in this case a referral to the zanzibar.com server.
    The nsslapd-state attribute can also be set to referral on update. This means that the database is used for all operations except update requests. When a client application makes an update request to a suffix set to referral on update, the client receives a referral.
For more information about the suffix configuration attributes, refer to Table 2.1, “Suffix Attributes”.


[2] The LDAP tools referenced in this guide are Mozilla LDAP, installed with Directory Server in the /usr/lib64/mozldap directory on Red Hat Enterprise Linux 5 (64-bit); directories for other platforms are listed in Section 1.3, “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.
[2] Unlike the standard LDAP URL format, the URL of the remote server does not specify a suffix. It has the form ldap://hostname:port/.
[3] Appendix B, LDAP URLs has more information about the structure of LDAP URLs.

Chapter 3. 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 10, Synchronizing Red Hat Directory Server with Microsoft Active Directory for more information on adding or modifying synchronized entries through Windows User Sync.

3.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 3.2, “Managing Entries from the Command Line”.

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 12, Managing Access Control.

3.1.1. Creating a Root Entry

Each time a new database is created, it is associated 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:
  1. In the Directory Server Console, select the Configuration tab.
  2. Right-click on the Data entry in the left menu, and select New Root Suffix from the menu.
  3. Fill in the new suffix and database information.
  4. 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 the new suffixes without a corresponding directory entry. Choose the suffix corresponding to the entry to create.
  5. In the New Object window, select the object class corresponding to the new entry.
    The object class must contain the attribute used to name the suffix. For example, if the entry corresponds to the suffix ou=people,dc=example,dc=com, then 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 3.1.3, “Modifying Directory Entries”.

3.1.2. Creating Directory Entries

Directory Server Console offers predefined templates, with preset forms, for new directory entries. Table 3.1, “Entry Templates and Corresponding Object Classes” shows what type of object class is used for each template.

Table 3.1. Entry Templates and Corresponding Object Classes

Template Object Class
User inetOrgPerson
Group groupOfUniqueNames
Organizational Unit organizationalUnit
Role nsRoleDefinition
Class of Service cosSuperDefinition

Another type, Other allows any kind of entry to be created by allowing users to select the specific object classes and attributes to apply.
  1. In the Directory Server Console, select the Directory tab.
  2. In the left pane, right-click the main entry to add the new entry, and select the type of entry: User, Group, Organizational Unit, Role, Class of Service, or Other.
  3. If the new entry type was Other, then a list of object classes opens. Select an object class from the list to define the new entry.
  4. Supply a value for all the listed attributes. Required attributes are marked with an asterisk (*).
  5. To display the full list of attributes available for the object class (entry type), click the Advanced button.
    In the Property Editor, select any additional attributes, and fill in the attribute values.
  6. Click OK to save the entry. The new entry is listed in the right pane.

3.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 classes and attributes belonging to that entry by adding and removing object classes, attributes and attribute values, and attribute subtypes.
The Property Editor can be opened in several ways:
  • From the Directory tab, by right-clicking an entry, and selecting Advanced Properties from the pop-up menu.
  • From the Directory tab, by double-clicking an entry and clicking the Advanced button
  • From the Create... new entry forms, by clicking the Advanced button
  • From the New Object window, by clicking OK

3.1.3.1. Adding or Removing an Object Class to an Entry

To add an object class to an entry:
  1. In the Directory tab of the Directory Server Console, right-click the entry to modify, and select Advanced from the pop-up menu.
  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.
To remove an object class from an entry, click the text box for the object class to remove, and then click Delete Value.

3.1.3.2. 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. See Section 3.1.3.1, “Adding or Removing an Object Class to an Entry” and Chapter 6, Managing the Directory Schema for more information.
To add an attribute to an entry:
  1. In the Directory tab of the Directory Server Console, right-click the entry to modify, and select Advanced from the pop-up menu.
  2. Click Add Attribute.
  3. Select the attribute to add from the list, and click OK.

    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 3.1.3.1, “Adding or Removing an Object Class to an Entry” for instructions on adding an object class. If you do not know which object class contains the attribute you need, look up the attribute in the Directory Server Schema Reference, which lists the object classes which use that attribute.
  4. Type in the value for the new attribute in the field to the right of the attribute name.
To remove the attribute and all its values from the entry, select Delete Attribute from the Edit menu.

3.1.3.3. 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.
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 consider, 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
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 Directory Server Configuration and Command-Line Tool Reference.

3.1.3.4. Adding Attribute Values

Multi-valued attributes allow multiple value for one attribute to be added to an entry.
  1. In the Directory tab of the Directory Server Console, right-click the entry to modify, and select Advanced from the pop-up menu.
  2. Select the attribute to which to add a value, and then click Add Value.
  3. Type in the new attribute value.
To remove an attribute value from an entry, click the text box of the attribute value to remove, and click Delete Value.

3.1.3.5. Adding an Attribute Subtype

A subtype allows the same entry value to be represented in different ways, such as providing a foreign-characterset version. There three different kinds of subtypes to attributes which can be added to an entry: language, binary, and pronunciation.
To add a subtype to an entry:
  1. In the Directory tab of the Directory Server Console, right-click the entry to modify, and select Properties from the pop-up menu.
  2. Click Add Attribute, and select the attribute to add from the list.
  3. Add a language subtype by selecting a value from the Language drop-down list. Add either a binary or pronunciation subtypeby selecting a value from the Subtype drop-down list.
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 C.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
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.
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.

3.1.4. Deleting Directory Entries

  1. In the Directory Server Console, select the Directory tab.
  2. Right-click the entry to delete, and select Delete from the right-click menu.

WARNING

The server deletes the entry or entries immediately. There is no way to undo the delete operation.

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

NOTE

You cannot modify your directory unless the appropriate access control rules have been set. For information on creating access control rules for the directory, see Chapter 12, Managing Access Control.

3.2.1. Providing Input from the Command Line

When you provide input to the ldapmodify and ldapdelete [4] utilities directly from the command line, you must use LDIF statements. For detailed information on LDIF statements, see Section 3.3, “Using LDIF Update Statements to Create or Modify Entries”.
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:
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com
  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. ...

3.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:
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
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”.

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

3.2.4. Adding and Modifying Entries Using ldapmodify

The ldapmodify[4] 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:
  • 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.

3.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:
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com -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 secret.
  • The hostname is example.com.
  • The server uses port number 389.
Table 3.2, “ldapmodify Parameters Used for Adding Entries” describes the ldapmodify parameters used in the example.

Table 3.2. ldapmodify Parameters Used for Adding Entries

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.
-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, see Section 3.2.1, “Providing Input from the Command Line”.

For full information on ldapmodify parameters, see the Directory Server Configuration and Command-Line Tool Reference.

3.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:
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com -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 3.3, “Using LDIF Update Statements to Create or Modify Entries”.
  • The bind DN is cn=Directory Manager, which has permissions to edit any entry in the database, and the password is secret.
  • The hostname is example.com.
  • The server uses port number 389.
Table 3.3, “ldapmodify Parameters Used for Modifying Entries” describes the ldapmodify parameters used in the example.

Table 3.3. ldapmodify Parameters Used for Modifying Entries

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.
-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, see Section 3.2.1, “Providing Input from the Command Line”.

For full information on ldapmodify parameters, see the Directory Server Configuration and Command-Line Tool Reference.

3.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 secret -h example.com -p 389 "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 to 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 secret.
  • The hostname is example.com.
  • The server uses port number 389.
Table 3.4, “ldapdelete Parameters Used for Deleting Entries” describes the ldapdelete parameters used in the example:

Table 3.4. ldapdelete Parameters Used for Deleting Entries

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.

For full information on ldapdelete parameters, see the Directory Server Configuration and Command-Line Tool Reference.

3.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 secret -h example.com -p 389 "cn=Patricia Fuentes,ou=People,o=example.com Bolivia\,S.A."

3.3. Using LDIF Update Statements to Create or Modify Entries

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

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

3.3.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.
The modrdn change type only changes the 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=com, 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

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

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

3.3.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. In order 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
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:
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com
  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.

3.3.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 numbers:
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
-
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

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

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

3.3.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 Admin Server uses this suffix to store information about installed Directory Servers. Deleting this suffix could force you to reinstall the Directory Server.

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

3.4. Tracking Modifications to Directory Entries

It can be useful to track when changes are made to entries. There are two aspects of entry modifications that the Directory Server tracks:
  • Using change sequence numbers to track changes to the database. This is similar to change sequence numbers used to in replication and synchronization. Every normal directory operation triggers a sequence number.
  • Assigning creation and modification information. These attributes record the names of the user who created and most recently modified an entry, as well as the timestamps of when it was created and modified.

NOTE

The entry USN, modify time and name, and create time and name are all operational attributes and are not returned in a regular ldapsearch. For details on running a search for operational attributes, see Section 8.4.7, “Searching for Operational Attributes”.

3.4.1. Tracking Modifications to the Database through Update Sequence Numbers

The Entry USN Plug-in provides a way for LDAP clients to know that something — anything — in the database has changed.
When the plug-in is enabled, an update sequence number (USN) is assigned to an entry every time a write operation occurs. (Write operations include add, modify, modrdn, and delete operations. Internal database operations, like export operations, are not counted in the update sequence.) The USN is evaluated globally, for the entire database, not for the single entry.

NOTE

The USN counter is local to each backend and there is only a single counter per instance. This means that there is only a single local instance of the Entry USN plug-in.
The entry shows the change number for the last modification to that entry in the entryUSN attribute. The root DSE contains another attribute which contains the most recent USN assigned to any entry in the database, in the lastusn attribute.

Example 3.1. Example Entry USN

 dn: uid=jsmith,ou=People,dc=example,dc=com
 mail: jsmith@example.com
 uid: jsmith
 givenName: John
 objectClass: top
 objectClass: person
 objectClass: organizationalPerson
 objectClass: inetorgperson
 sn: Smith
 cn: John Smith
 userPassword: {SSHA}EfhKCI4iKl/ipZMsWlITQatz7v2lUnptxwZ/pw==
 entryusn: 1122

The USN is similar to the change sequence number for replication and synchronization, in that it simply ticks upward to track changes. The entry USN is maintained separately from the CSNs, however.
The Entry USN Plug-in does have some implications for replication.
Replication operations are treated by the Entry USN Plug-in as regular modify operations. This means that the replication process itself triggers the entryUSN to increment.
For single-master replication, if the entryUSN attribute is replicated, the consumer has the same entryUSNs as the supplier. There is no conflict, because the consumer server must be read-only, so there is no point in having a local entry USN counter. When the consumer is initialized, it is initialized with all of the entry USN numbers from the supplier (unless entryUSN is excluded using fractional replication) and continues from there.
For multi-master replication, however, it is possible for there to be different USNs on entries across both suppliers and consumers. If the entry USN is replicated, it is simply overwritten by the local Entry USN Plug-in or locally ignored, if the plug-in is not enabled.
The simplest solution is to exclude the entryUSN attribute using fractional replication (see Section 9.1.7, “Replicating a Subset of Attributes with Fractional Replication”), so that all entryUSN numbers are local. When the entryUSN attribute is excluded in the replication agreement, then when the consumers are initialized, they have entryUSNs that start at zero (0) locally instead of using the supplier's entryUSNs.

3.4.1.1. Configuring the USN Plug-in

The Entry USN Plug-in must be enabled for USNs to be recorded on entries, as described in Section 1.10.1, “Enabling Plug-ins”. The plug-in can be enabled through the Directory Server Console or through the command line. For example:
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389

dn: cn=USN,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginEnabled
nsslapd-pluginEnabled: on
Then restart the server to apply the changes.

3.4.1.2. Cleaning up USN Tombstone Entries

The Entry USN Plug-in moves entries to tombstone entries when the entry is deleted. If replication is enabled, then separate tombstone entries are kept by both the Entry USN and Replication Plug-ins. Both tombstone entries are deleted by the replication process, but for server performance, it can be beneficial to delete the entry USN tombstones before converting a server to a replica or to free memory for the server.
The usn-tombstone-cleanup.pl command deletes USN tombstone entries for a specific database backend or specific suffix. Optionally, it can delete all of tombstone entries up to a certain USN. For example:
/usr/lib64/dirsrv/instance_name/usn-tombstone-cleanup.pl -D "cn=directory manager" -w secret -s "ou=people,dc=example,dc=com" -m 1100
Either the backend must be specified using the -n option or the suffix, using the -s option. If both are given, then the suffix in the -s option is used.
The options for usn-tombstone-cleanup.pl command are listed in Table 3.5, “usn-tombstone-cleanup.pl Options”. More details for this tool are in the Configuration and Command-Line Tool Reference.

Table 3.5. usn-tombstone-cleanup.pl Options

Option Description
-D rootdn Gives the user DN with root permissions, such as Directory Manager. The default is the DN of the Directory Manager, which is read from the nsslapd-root attribute under cn=config.
-m maximum_USN Sets the upper bound for entries to delete. All tombstone entries with an entryUSN value up to the specified maximum (inclusive) are deleted, but not past that USN value. If no maximum USN value is set, then all backend tombstone entries are deleted.
-n backendInstance Gives the name of the database containing the entries to clean (delete).
-s suffix Gives the name of the suffix containing the entries to clean (delete).
-w password The password associated with the user DN.

3.4.2. Tracking Entry Modifications through Operational Attributes

The Directory Server can maintain some special operational attributes for every directory entry, showing basic creation and modification information:
  • 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.
  • 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.
Operational attributes are not returned in default directory searches and must be explicitly requested, as described in Section 8.4.7, “Searching for Operational Attributes”.

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 2.3.1.2.2, “Providing Bind Credentials”.
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. Open the Tasks tab, and click Restart Directory Server.

    NOTE

    The Directory Server must be restarted for the changes to take effect.

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

3.5.1. How Referential Integrity Works

When the Referential Integrity 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 multi-master replication environment to avoid conflict resolution loops. When enabling the plug-in 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 7.2, “Creating Standard Indexes” for more information about checking and creating indexes.

3.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.
  • 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 3.5.3, “Enabling and 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.

3.5.3. Enabling and Disabling Referential Integrity

3.5.3.1. Enabling and Disabling Referential Integrity in the Console

  1. Select the Configuration tab, and expand the Plugins folder.
  2. Select Referential Integrity Postoperation Plug-in from the list.
  3. Check the Enable plugin checkbox to enable the plug-in; clear it to disable it.
  4. Fill in the correct path to the plug-in by default; plug-ins are located in /usr/lib64/dirsrv/plugins.
  5. Restart the Directory Server to apply the changes. In the Tasks tab, select Restart the Directory Server.

3.5.3.2. Enabling and Disabling Referential Integrity from the Command Line

To disable or enable the Referential Integrity Plug-in:
  1. Use ldapmodify to edit the value of the nsslapd-pluginEnabled attribute. For example: [5]
    /usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com
    
    dn: cn=referential integrity postoperation,cn=plugins,cn=config
    changetype: modify
    replace: nsslapd-pluginEnabled
    nsslapd-pluginEnabled: on
  2. Then restart the server.
    service dirsrv restart

3.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)
  • 86,400 seconds (updates occur once a day)
  • 604,800 seconds (updates occur once a week)

3.5.4.1. Modifying the Update Interval from the Console

  1. Select the Configuration tab, and expand the Plugins folder. Select the Referential Integrity Postoperation Plug-in.
  2. In the arguments list, replace the value in the first text box with the appropriate time interval.
  3. Restart the Directory Server to apply the changes. In the Tasks tab, select Restart the Directory Server.

3.5.4.2. Modifying the Update Interval from the Command Line

  1. Use ldapmodify[5] to edit the value of the nsslapd-pluginarg attribute. For example:
    The first argument listed sets the update intervale for referntial integrity checks. To change the interval, replace the nsslapd-pluginarg0 attribute.
    /usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389
    
    dn: cn=referential integrity postoperation,cn=plugins,cn=config
    changetype: modify
    replace: nsslapd-pluginarg0
    nsslapd-pluginarg0: 600
  2. Then restart the server.
    service dirsrv restart

3.5.5. Modifying the Attribute List

3.5.5.1. Modifying the Attribute List from the Console

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.

NOTE

Improve the performance by removing any unused attributes from the list.
  1. Select the Configuration tab, and expand the Plugins folder. Select the Referential Integrity Postoperation Plug-in.
  2. In the Arguments section, use the Add and Delete buttons to modify the attributes in the list.
  3. Restart the Directory Server to apply the changes. In the Tasks tab, select Restart the Directory Server.

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 7.2, “Creating Standard Indexes” for more information about checking and creating indexes.

3.5.5.2. Modifying the Attribute List from the Command Line

By default, the Referential Integrity Plug-in is set up to check for and update the member, uniquemember, owner, and seeAlso attributes.
nsslapd-pluginarg3: member
nsslapd-pluginarg4: uniquemember
nsslapd-pluginarg5: owner
nsslapd-pluginarg6: seeAlso
To add another attribute to the list:
  1. Use ldapmodify[5] to add another attribute to the list by adding another nsslapd-pluginarg attribute.
    /usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389
    
    dn: cn=referential integrity postoperation,cn=plugins,cn=config
    changetype: modify
    add: nsslapd-pluginarg7
    nsslapd-pluginarg7: nsroledn
  2. Then restart the server.
    service dirsrv restart

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.


[4] The LDAP tools referenced in this guide are Mozilla LDAP, installed with Directory Server in the /usr/lib64/mozldap directory on Red Hat Enterprise Linux 5 (64-bit); directories for other platforms are listed in Section 1.3, “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.
[5] The LDAP tools referenced in this guide are Mozilla LDAP, installed with Directory Server in the /usr/lib64/mozldap directory on Red Hat Enterprise Linux 5 (64-bit); directories for other platforms are listed in Section 1.3, “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.

Chapter 4. Populating Directory Databases

Databases contain the directory data managed by the Red Hat Directory Server.

4.1. Importing Data

Directory Server can populate a database with data in one of two ways: by importing data (either through the Directory Server Console or using the import tools) or by initializing a database for replication.
Table 4.1, “Import Method Comparison” describes the differences between an import and initializing databases.

Table 4.1. Import Method Comparison

Action Import Initialize Database
Overwrites database No Yes
LDAP operations Add, modify, delete Add only
Performance More time-consuming Fast
Partition specialty Works on all partitions Local partitions only
Response to server failure Best effort (all changes made up to the point of the failure remain) Atomic (all changes are lost after a failure)
LDIF file location Local to Console Local to Console or local to server
Imports configuration information (cn=config) Yes No

4.1.1. Importing Entries with Large Attributes

The nsslapd-cachememsize attribute defines the size allowed for the entry cache.
The import buffer is automatically set to 80% of the cache memory size setting. If the memory cache is 1GB, for example, then the import buffer is 800MB.
When importing a very large database or entries with large attributes (often with values like binary data like certificate chains, CRLs, or images), then set the nsslapd-cachememsize attribute high enough so that the import buffer has enough memory to process the entries.

4.1.2. Importing a Database from the Console

When performing an import operation from the Directory Server Console, an ldapmodify operation is executed to append data, as well as to modify and delete entries. The operation is performed on all of the databases managed by the Directory Server and on remote databases to which the Directory Server has a configured database link.
Import operations can be run on a server instance that is local to the Directory Server Console or on a different host machine (a remote import operation).
You must be logged in as the Directory Manager in order to perform an import.

NOTE

The LDIF files used for import operations must use UTF-8 character set encoding. Import operations do not convert data from local character set encoding to UTF-8 characterset encoding.

WARNING

All imported LDIF files must also contain the root suffix.
To import data from the Directory Server Console:
  1. Select the Tasks tab. Scroll to the bottom of the screen, and select Import Database.
    Alternatively, open the Configuration tab and select Import from the Console menu.
  2. In the Import Database dialog box, enter the full path to the LDIF file to import in the LDIF file field, or click Browse to select the file to import.
    If the Console is running on a machine remote to the directory, the field name appears as LDIF file (on the machine running the Console). When browsing for a file, you are not browsing the current directory for the Directory Server host, but the filesystem of the machine running the Console.
    When importing a database through a remote Console, do not use a relative path to the database. For remote imports, the operation fails with the error Cannot write to file... if a relative path is given for the file. Always use an absolute path for remote import operations.
  3. In the Options box, select one or both of the following options:
    • Add Only. The LDIF file may contain modify and delete instructions in addition to the default add instructions. For the server to ignore operations other than add, select the Add only checkbox.
    • Continue on Error. Select the Continue on error checkbox for the server to continue with the import even if errors occur. For example, use this option to import an LDIF file that contains some entries that already exist in the database in addition to new ones. The server notes existing entries in the rejects file while adding all new entries.
  4. In the File for Rejects field, enter the full path to the file in which the server is to record all entries it cannot import, or click Browse to select the file which will contain the rejects.
    A reject is an entry which cannot be imported into the database; for example, the server cannot import an entry that already exists in the database or an entry that has no parent object. The Console will write the error message sent by the server to the rejects file.
    Leaving this field blank means the server will not record rejected entries.
The server performs the import and also creates indexes.

NOTE

Trailing spaces are dropped during a remote Console import but are preserved during both local Console or ldif2db import operations.

4.1.3. Initializing a Database from the Console

The existing data in a database can be overwritten by initializing databases.
You must be logged in as the Directory Manager in order to initialize a database because an LDIF file that contains a root entry cannot be imported into a database except as the Directory Manager (root DN). Only the Directory Manager has access to the root entry, such as dc=example,dc=com.

WARNING

When initializing databases from an LDIF file, be careful not to overwrite the o=NetscapeRoot suffix unless you are restoring data. Otherwise, initializing the database deletes information and may require re-installing the Directory Server.
To initialize a database using the Directory Server Console:
  1. Select the Configuration tab.
  2. Expand the Data tree in the left navigation pane. Expand the suffix of the database to initialize, then click the database itself.
  3. Right-click the database, and select Initialize Database.
    Alternatively, select Initialize Database from the Object menu.
  4. In the LDIF file field, enter the full path to the LDIF file to import, or click Browse.
  5. If the Console is running from a machine local to the file being imported, click OK and proceed with the import immediately. If the Console is running from a machine remote to the server containing the LDIF file, select one of the following options, then click OK:
    • From local machine. Indicates that the LDIF file is located on the local machine.
    • From server machine. Indicates that the LDIF file is located on a remote server.
    The default LDIF directory is /var/lib/dirsrv/slapd-instance_name/ldif.

4.1.4. Importing from the Command Line

There are four methods for importing data through the command line:

NOTE

The LDIF files used for import operations must use UTF-8 character set encoding. Import operations do not convert data from local character set encoding to UTF-8 characterset encoding.

WARNING

All imported LDIF files must also contain the root suffix.

NOTE

To import a database that has been encrypted, use the -E option with the script. See Section 2.2.3.5, “Exporting and Importing an Encrypted Database” for more information.

4.1.4.1. Importing Using the ldif2db Command-Line Script

The ldif2db script overwrites the data in the specified database. Also, the script requires that the Directory Server be stopped when the import begins.
By default, the script first saves and then merges any existing o=NetscapeRoot configuration information with the o=NetscapeRoot configuration information in the files being imported.

WARNING

This script overwrites the data in the database.
To import LDIF:
  1. Stop the server.
    service dirsrv stop instance
  2. Open the Directory Server instance directory.
    cd /etc/dirsrv/slapd-instance_name
  3. Run the ldif2db command-line script.
    ldif2db -n Database1 -i /var/lib/dirsrv/slapd-instance_name/ldif/demo.ldif
     -i /var/lib/dirsrv/slapd-instance_name/ldif/demo2.ldif
    For more information about using this script, see the Directory Server Configuration and Command-Line Tool Reference.

    WARNING

    If the database specified in the -n option does not correspond with the suffix contained by the LDIF file, all of the data contained by the database is deleted, and the import fails. Make sure that the database name is not misspelled.

Table 4.2. ldif2db Parameters

Option Description
-i Specifies the full path name of the LDIF files to be imported. This option is required. To import more than one LDIF file at a time, use multiple -i arguments. When multiple files are imported, the server imports the LDIF files in the order which they are specified from the command line.
-n Specifies the name of the database to which to import the data.

For more information about using this script, see the Directory Server Configuration and Command-Line Tool Reference.

4.1.4.2. Importing Using the ldif2db.pl Perl Script

As with the ldif2db script, the ldif2db.pl script overwrites the data in the specified database. This script requires the server to be running in order to perform the import.

WARNING

This script overwrites the data in the database.
  1. Open the Directory Server instance directory.
    cd /etc/dirsrv/slapd-instance_name
  2. Run the ldif2db script.
    ldif2db -D "cn=Directory Manager" -w secret -i /var/lib/dirsrv/slapd-instance_name/ldif/demo.ldif -n Database1
    For more information about using this script, see the Directory Server Configuration and Command-Line Tool Reference.

    NOTE

    You do not need root privileges to run the script, but you must authenticate as the Directory Manager.

Table 4.3. ldif2db Options

Option Description
-D Specifies the DN of the administrative user.
-w Specifies the password of the administrative user.
-i Specifies the LDIF files to be imported. This option is required. To important multiple LDIF files at a time, use multiple -i arguments. When multiple files are imported, the server imports the LDIF files in the order they are specified in the command line.
-n Specifies the name of the database to which to import the data.

4.1.4.3. Importing Using the ldif2ldap Command-Line Script

The ldif2ldap script appends the LDIF file through LDAP. Using this script, data are imported to all directory databases at the same time. The server must be running in order to import using ldif2ldap.
To import LDIF using ldif2ldap:
  1. Open the Directory Server instance directory:
    cd /etc/dirsrv/slapd-instance_name
  2. Run the ldif2ldap command-line script.
    ldif2ldap "cn=Directory Manager" secretpwd /var/lib/dirsrv/slapd-instance_name/ldif/demo.ldif
    The ldif2ldap script requires the DN of the administrative user, the password of the administrative user, and the absolute path and filename of the LDIF files to be imported.
    For more information about using this script, see the Directory Server Configuration and Command-Line Tool Reference.

4.1.4.4. Importing through the cn=tasks Entry

The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries that the server uses to manage tasks. Several common directory tasks have container entries under cn=tasks,cn=config. Temporary task entries can be created under cn=import,cn=tasks,cn=config to initiate an import operation.
As with the ldif2db and ldif2db.pl scripts, an import operation in cn=tasks overwrites all of the information in the database.
This task entry requires three attributes:
  • A unique name (cn)
  • The filename of the LDIF file to import (nsFilename)
  • The name of the database into which to import the file (nsInstance)
It is also possible to supply the DNs of suffixes to include or exclude from the import, analogous to the -s and -x options, respectively, for the ldif2db and ldif2db.pl scripts.
The entry is simply added using ldapmodify, as described in Section 3.2.4, “Adding and Modifying Entries Using ldapmodify”. For example:
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=example import,cn=import,cn=tasks,cn=config
objectclass: extensibleObject
cn: example import
nsFilename: /home/files/example.ldif
nsInstance: userRoot
nsIncludeSuffix: ou=People,dc=example,dc=com
nsExcludeSuffix: ou=Groups,dc=example,dc=com
As soon as the task is completed, the entry is removed from the directory configuration.
The Directory Server Configuration and Command-Line Tool Reference has more information on the available attributes for running Directory Server import tasks under the cn=tasks entries.

4.2. Exporting Data

LDAP Data Interchange Format (LDIF) files are used to export database entries from the Directory Server databases. LDIF is a standard format described in RFC 2849, The LDAP Data Interchange Format (LDIF) - Technical Specification.
Exporting data can be useful for the following:
  • Backing up the data in the database.
  • Copying data to another Directory Server.
  • Exporting data to another application.
  • Repopulating databases after a change to the directory topology.
For example, if a directory contains one database, and its contents are split into two databases, then the two new databases receive their data by exporting the contents of the old databases and importing it into the two new databases, as illustrated in Figure 4.1, “Splitting a Database Contents into Two Databases”.

NOTE

The export operations do not export the configuration information (cn=config), schema information (cn=schema), or monitoring information (cn=monitor).
Splitting a Database Contents into Two Databases

Figure 4.1. Splitting a Database Contents into Two Databases


The Directory Server Console or command-line utilities can be used to export data.

WARNING

Do not stop the server during an export operation.

4.2.1. Exporting Directory Data to LDIF Using the Console

Some or all of directory data can be exported to LDIF, depending upon the location of the final exported file. When the LDIF file is on the server, only the data contained by the databases local to the server can be exported. If the LDIF file is remote to the server, all of the databases and database links can be exported.
Export operations can be run to get data from a server instance that is local to the Directory Server Console or from a different host machine (a remote export operation).
Export directory data to LDIF from the Directory Server Console while the server is running:
  1. Select the Tasks tab. Scroll to the bottom of the screen, and click Export Database(s).
    Alternatively, select the Configuration tab and click the Export from the Console menu.
  2. Enter the full path and filename of the LDIF file in the LDIF File field, or click Browse to locate the file.
    Browse is not enabled if the Console is running on a remote server. When the Browse button is not enabled, the file is stored in the default directory, /var/lib/dirsrv/slapd-instance_name/ldif.
  3. If the Console is running on a machine remote to the server, two radio buttons are displayed beneath the LDIF File field.
    • Select To local machine to export the data to an LDIF file on the machine from which the Console is running.
    • Select To server machine to export to an LDIF file located on the server's machine.
  4. To export the whole directory, select the Entire database radio button.
    To export only a single subtree of the suffix contained by the database, select the Subtree radio button, and then enter the name of the suffix in the Subtree text box. This option exports a subtree that is contained by more than one database.
    Alternatively, click Browse to select a suffix or subtree.

4.2.2. Exporting a Single Database to LDIF Using the Console

It is also possible to export a single database to LDIF. Do the following while the server is running:
  1. Select the Configuration tab.
  2. Expand the Data tree in the left navigation pane. Expand the suffix, and select the database under the suffix.
  3. Right-click the database, and select Export Database.
    Alternatively, select Export Database from the Object menu.
  4. In the LDIF file field, enter the full path to the LDIF file, or click Browse.
    When the Browse button is not enabled, the file is stored in the default directory, /var/lib/dirsrv/slapd-instance_name/ldif.

4.2.3. Exporting to LDIF from the Command Line

There are three methods for exporting data through the command line:
  • Using db2ldif. This method runs the command-line utility; unlike the import script, ldif2db, this utility can be run while the server is running.
  • Using db2ldif.pl. This Perl script behaves the same as the db2ldif command-line utility and takes the same options.
  • Creating a cn=tasks entry. This method creates a temporary task entry which automatically launches an export operation. This is functionally like running db2ldif, with one exception: when running db2ldif or db2ldif.pl for a replica (with a -r option, the server must be stopped first. The cn=tasks entry can be added and export replica information while the server is still running. See Section 4.2.3.2, “Exporting through the cn=tasks Entry”.

4.2.3.1. Exporting a Database Using db2ldif or db2ldif.pl

Databases can be exported to LDIF using the db2ldif command-line script or the db2ldif.pl Perl script. Both of these tools export all of the database contents or a part of their contents to LDIF when the server is running or stopped.
These script take the same options.

NOTE

The -E option is required to export a database that has been encrypted. See Section 2.2.3.5, “Exporting and Importing an Encrypted Database” for more information.

NOTE

If the database being exported is a replica, then the server must be stopped before the export script is run and the export script must have the -r.
To export to LDIF from the command line:
  1. Open the Directory Server instance directory:
    cd /etc/dirsrv/slapd-instance_name
  2. Run either the db2ldif command-line script or the db2ldif.pl Perl script. For example:
    db2ldif -n database1 -a /export/output.ldif
    This exports the database contents to /export/output.ldif. If the -a option is not specified, then the database information is exported to /var/lib/dirsrv/slapd-instance_name/ldif/instance_name-database1-date.ldif. For example:
    db2ldif -n database1
    It is also possible to specify which suffixes to export, using the -s option. For example:
    db2ldif -s "dc=example,dc=com"
    The LDIF file in this case would be /var/lib/dirsrv/slapd-instance_name/ldif/instance_name-example-2010_04_30_112718.ldif, using the name of the suffix rather than the database.
    If the suffix specified is a root suffix, such as dc=example,dc=com, then it is not necessary to specify the database or to use the -n option.
For more information about using these scripts, see the Directory Server Configuration and Command-Line Tool Reference.

Table 4.4. db2ldif Options

Option Description
-n Specifies the name of the database from which the file is being exported.
-s Specifies the suffix or suffixes to include in the export. If the suffix is a root suffix, such as dc=example,dc=com, then the -n option is not required. There can be multiple -s arguments.
-a Defines the output file to which Directory Server exports the LDIF. This file must be an absolute path. If the -a option is not given, the output ldif is stored in the /var/lib/dirsrv/slapd-instance_name/ldif directory and is automatically named serverID-database-YYYY_MM_DD_hhmmxx.ldif with the -n option or serverID-firstsuffixvalue-YYYY_MM_DD_hhmmxx.ldif with the -s option.
-r Specifies that the exported database is a consumer replica. In this case, the appropriate settings and entries are included with the LDIF to initialize the replica when the LDIF is imported.
-E Decrypts an encrypted database so it can be exported.

4.2.3.2. Exporting through the cn=tasks Entry

The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries that the server uses to manage tasks. Several common directory tasks have container entries under cn=tasks,cn=config. Temporary task entries can be created under cn=export,cn=tasks,cn=config to initiate an export operation.
The export task entry requires three attributes:
  • A unique name (cn)
  • The filename of the LDIF file to which to export the database (nsFilename)
  • The name of the database to export (nsInstance)
It is also possible to supply the DNs of suffixes to include or exclude from the export operation, analogous to the -s and -x options, respectively, for the db2ldif and db2ldif.pl scripts. Additionally, if the database is a replica, then the appropriate replica information can be included to initialize the new consumer when the LDIF is imported; this is set in the nsExportReplica, corresponding to the -r option.
The entry is simply added using ldapmodify, as described in Section 3.2.4, “Adding and Modifying Entries Using ldapmodify”. For example:
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=example export,cn=export,cn=tasks,cn=config
objectclass: extensibleObject
cn: example export
nsInstance: userRoot
nsFilename: /home/files/example.ldif
nsExportReplica: true
nsIncludeSuffix: ou=People,dc=example,dc=com
nsExcludeSuffix: ou=Groups,dc=example,dc=com
As soon as the task is completed, the entry is removed from the directory configuration.
The Directory Server Configuration and Command-Line Tool Reference has more information on the available attributes for running Directory Server export tasks under the cn=tasks entries.

4.3. Backing up and Restoring Data

Databases can be backed up and restored using the Directory Server Console or a command-line script.

WARNING

Do not stop the server during a backup or restore operation.

4.3.1. Backing up All Databases

The following procedures describe backing up all of the databases in the directory using the Directory Server Console and from the command line.

NOTE

These backup methods cannot be used to back up the data contained by databases on a remote server that are chained using database links.

4.3.1.1. Backing up All Databases from the Console

When backing up databases from the Directory Server Console, the server copies all of the database contents and associated index files to a backup location. A backup can be performed while the server is running.
To back up databases from the Directory Server Console:
  1. Select the Tasks tab.
  2. Click Back Up Directory Server.
  3. Enter the full path of the directory to store the backup file in the Directory text box, or click Use default, and the server provides a name for the backup directory.
    If the Console is running on the same machine as the directory, click Browse to select a local directory.
    With the default location, the backup files are placed in /var/lib/dirsrv/slapd-instance_name/bak. By default, the backup directory name contains the name of the server instance and the time and date the backup was created (instance_name-YYYY_MM_DD_hhmmss).

4.3.1.2. Backing up All Databases from the Command Line

Databases can be backed up from the command line using either the db2bak command-line script or the db2bak Perl script. The Perl script works when the server is running or when the server is stopped; the command-line script can only be run when the server is stopped.
Configuration information cannot be backed up using this backup method. For information on backing up the configuration information, see Section 4.3.2, “Backing up the dse.ldif Configuration File”.
To back up the directory from the command line using the db2bak script:
  1. Stop the server instance.
    cd service dirsrv stop slapd-example

    TIP

    To avoid shutting down the server when running a backup, use the db2bak.pl Perl script instead of the bd2bak tool. These are both located in the /usr/lib[64]/dirsrv/slapd-example directory.
  2. Open the instance's tools directory. For example, on Red Hat Enterprise Linux 5 (64-bit):
    cd /usr/lib64/dirsrv/slapd-instance
  3. Run the db2bak command-line script, specifying the backup file name and directory.
    ./db2bak /var/lib/dirsrv/slapd-instance_name/bak/instance_name-2010_04_30_16_27_56
    The backup directory where the server saves the backed up databases can be specified with the script. If a directory is not specified, the backup file is stored in /var/lib/dirsrv/slapd-instance_name/bak. By default, the backup directory is named with the Directory Server instance name and the date of the backup (serverID-YYYY_MM_DD_hhmmss).
  4. Start the server instance again.
    cd service dirsrv start slapd-example
For more information about using these scripts, see the Directory Server Configuration and Command-Line Tool Reference.

4.3.1.3. Backing up the Database through the cn=tasks Entry

The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries that the server uses to manage tasks. Several common directory tasks have container entries under cn=tasks,cn=config. Temporary task entries can be created under cn=backup,cn=tasks,cn=config to initiate a backup operation.
The backup task entry requires three attributes:
  • A unique name (cn).
  • The directory to write the backup file to (nsArchiveDir). The backup file is named with the Directory Server instance name and the date of the backup (serverID-YYYY_MM_DD_hhmmss).
  • The type of database (nsDatabaseType); the only option is ldbm database.
The entry is simply added using ldapmodify, as described in Section 3.2.4, “Adding and Modifying Entries Using ldapmodify”. For example:
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=example backup,cn=backup,cn=tasks,cn=config
objectclass: extensibleObject
cn: example backup
nsArchiveDir: /export/backups/
nsDatabaseType: ldbm database
As soon as the task is completed, the entry is removed from the directory configuration.
The Directory Server Configuration and Command-Line Tool Reference has more information on the available attributes for running tasks to back up databases under the cn=tasks entries.

4.3.2. Backing up the dse.ldif Configuration File

Directory Server automatically backs up the dse.ldif configuration file. When the Directory Server is started, the directory creates a backup of the dse.ldif file automatically in a file named dse.ldif.startOK in the /etc/dirsrv/slapd-instance_name directory.
When the dse.ldif file is modified, the file is first backed up to a file called dse.ldif.bak in the /etc/dirsrv/slapd-instance_name directory before the directory writes the modifications to the dse.ldif file.

4.3.3. Restoring All Databases

The following procedures describe restoring all of the databases in the directory using the Directory Server Console and from the command line.

IMPORTANT

While restoring databases, the server must be running. However, the databases will be unavailable for processing operations during the restore.
Therefore, stop all replication processes before attempting to restore a database. After the database is restored, any consumers, hubs, or multi-master peers must be reinitialized.

4.3.3.1. Restoring All Databases from the Console

If the databases become corrupted, restore data from a previously generated backup using the Directory Server Console. This process consists of stopping the server and then copying the databases and associated index files from the backup location to the database directory.

WARNING

Restoring databases overwrites any existing database files.

IMPORTANT

While restoring databases, the server must be running. However, the databases will be unavailable for processing operations during the restore.
Therefore, stop all replication processes before attempting to restore a database. After the database is restored, any consumers, hubs, or multi-master peers must be reinitialized.
To restore databases from a previously created backup:
  1. In the Directory Server Console, select the Tasks tab.
  2. Click Restore Directory Server.
  3. Select the backup from the Available Backups list, or enter the full path to a valid backup in the Directory text box.
    The Available Backups list shows all backups located in the default directory, /var/lib/dirsrv/slapd-instance_name/bak/backup_directory. backup_directory is the directory of the most recent backup, in the form serverID-YYYY_MM_DD_hhmmss.

4.3.3.2. Restoring Databases from the Command Line

There are three ways to restore databases from the command line:
  • Using the bak2db command-line script. This script requires the server to be shut down.
  • Using the bak2db.pl Perl script. This script works while the server is running.
  • Creating a temporary entry under cn=restore,cn=tasks,cn=config. This method can also be run while the server is running.

IMPORTANT

While restoring databases, the server must be running (with the exception of running the bak2db command-line script). However, the databases will be unavailable for processing operations during the restore.
Therefore, stop all replication processes before attempting to restore a database. After the database is restored, any consumers, hubs, or multi-master peers must be reinitialized.
4.3.3.2.1. Using the bak2db Command-Line Script
  1. If the Directory Server is running, stop it:
    service dirsrv stop instance
  2. Open the Directory Server instance directory:
    cd /etc/dirsrv/slapd-instance_name
  3. Run the bak2db command-line script. The bak2db script requires the full path and name of the input file.
    bak2db /var/lib/dirsrv/slapd-instance_name/bak/instance_name-2010_04_30_11_48_30
    For more information about using this script, see the Directory Server Configuration and Command-Line Tool Reference.
4.3.3.2.2. Using bak2db.pl Perl Script
  1. Open the Directory Server instance directory. For example:
    cd /usr/lib[64]/dirsrv/slapd-example
  2. Run the bak2db.pl Perl script.
    ./bak2db.pl -D "cn=Directory Manager" -w secret -a /var/lib/dirsrv/slapd-instance_name/bak/instance_name-2010_04_30_11_48_30
    For more information on using this Perl script, see the Directory Server Configuration and Command-Line Tool Reference.

IMPORTANT

While restoring databases, the server must be running. However, the databases will be unavailable for processing operations during the restore.
Therefore, stop all replication processes before attempting to restore a database. After the database is restored, any consumers, hubs, or multi-master peers must be reinitialized.
Option Description
-a Defines the full path and name of the input file.
-D Specifies the DN of the administrative user.
-w Specifies the password of the administrative user.
4.3.3.2.3. Restoring the Database through the cn=tasks Entry
The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries that the server uses to manage tasks. Several common directory tasks have container entries under cn=tasks,cn=config. Temporary task entries can be created under cn=restore,cn=tasks,cn=config to initiate a restore operation.

IMPORTANT

While restoring databases, the server must be running. However, the databases will be unavailable for processing operations during the restore.
Therefore, stop all replication processes before attempting to restore a database. After the database is restored, any consumers, hubs, or multi-master peers must be reinitialized.
The restore task entry requires three attributes, the same as the backup task:
  • A unique name (cn).
  • The directory from which to retrieve the backup file (nsArchiveDir).
  • The type of database (nsDatabaseType); the only option is ldbm database.
The entry is simply added using ldapmodify, as described in Section 3.2.4, “Adding and Modifying Entries Using ldapmodify”. For example:
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=example restore,cn=restore,cn=tasks,cn=config
objectclass: extensibleObject
cn: example restore
nsArchiveDir: /export/backups/
nsDatabaseType: ldbm database
As soon as the task is completed, the entry is removed from the directory configuration.
The Directory Server Configuration and Command-Line Tool Reference has more information on the available attributes for running database restore tasks under the cn=tasks entries.

4.3.4. Restoring a Single Database

It is possible to restore a single database through the command line, but not in the Directory Server Console. To restore a single database:
  1. Stop the Directory Server if it is running.
    service dirsrv stop instance
  2. Restore the backend from the /var/lib/dirsrv/slapd-instance_name/bak archives with the bak2db script, using the -n parameter to specify the database name. For example:
    bak2db /var/lib/dirsrv/slapd-instance_name/bak/backup_file -n userRoot
  3. Restart the Directory Server.
    service dirsrv start instance

    NOTE

    If the Directory Server fails to start, remove the database transaction log files in /var/lib/dirsrv/slapd-instance_name/db/log.###, then retry starting the server.

4.3.5. Restoring Databases That Include Replicated Entries

If a database that supplies entries to other servers is restored, then you must reinitialize all of the servers that receive updates from the restored database (for example, consumer servers, hub servers, and, in multi-master replication environments, other supplier servers). The changelog associated with the restored database will be erased during the restore operation. A message will be logged to the supplier servers' log files indicating that reinitialization is required. If a database containing data received from a supplier server is restored, then one of two situations can occur:
  • Changelog entries have not yet expired on the supplier server.
    If the supplier's changelog has not expired since the database backup was taken, then restore the local consumer and continue with normal operations. This situation occurs only if the backup was taken within a period of time that is shorter than the value set for the maximum changelog age attribute, nsslapd-changelogmaxage, in the cn=changelog5,cn=config entry. For more information about this option, see the Directory Server Configuration and Command-Line Tool Reference.
    Directory Server automatically detects the compatibility between the replica and its changelog. If a mismatch is detected, the server removes the old changelog file and creates a new, empty one.
  • Changelog entries have expired on the supplier server since the time of the local backup.
    If changelog entries have expired, reinitialize the consumer. For more information on reinitializing consumers, refer to Section 9.10, “Initializing Consumers”.
For information on managing replication, see Chapter 9, Managing Replication.

4.3.6. Restoring the dse.ldif Configuration File

The directory creates two backup copies of the dse.ldif file in the /etc/dirsrv/slapd-instance_name directory. The dse.ldif.startOK file records a copy of the dse.ldif file at server start up. The dse.ldif.bak file contains a backup of the most recent changes to the dse.ldif file. Use the version with the most recent changes to restore the directory.
To restore the dse.ldif configuration file:
  1. Stop the server.
    service dirsrv stop instance
  2. Restore the database as outlined in Section 4.3.4, “Restoring a Single Database” to copy the backup copy of the dse.ldif file into the directory.
  3. Restart the server.
    service dirsrv restart instance

Chapter 5. Managing Attributes and Values

Red Hat Directory Server provides several different mechanisms for dynamically and automatically maintaining some types of attributes on directory entries. These plug-ins and configuration options simplify managing directory data and expressing relationships between entries.
Part of the characteristic of entries are their relationships to each other. Obviously, a manager has an employee, so those two entries are related. Groups are associated with their members. There are less apparent relationships, too, like between entries which share a common physical location.
Red Hat Directory Server provides several different ways that these relationshipts between entries can be maintained smoothly and consistently. There are several plug-ins can apply or generate attributes automatically as part of the data within the directory, including classes of service, linking attributes, and generating unique numeric attribute values.

5.1. Enforcing Attribute Uniqueness

Attribute uniqueness means that the Directory Server requires that all new or edited attributes always have unique values. Attribute uniqueness is enforced through a plug-in. A new instance of the Attribute Uniqueness Plug-in must be created for every attribute for which values must be unique.

5.1.1. Attribute Uniqueness Plug-in Syntax

Configuration information for the Attribute Uniqueness Plug-in is specified in an entry under cn=plugins,cn=config entry. There are two possible syntaxes for nsslapd-pluginarg attributes.

NOTE

To enforce uniqueness of another attribute than the ones in these example, copy and paste the default Attribute Uniqueness Plug-in entry, and being care to change only the attributes described here.
Use the following syntax to perform the uniqueness check under a suffix or subtree:
 dn: cn=descriptive_plugin_name,cn=plugins,cn=config
 ...
 nsslapd-pluginEnabled: state    
 nsslapd-pluginarg0: attribute_name    
 nsslapd-pluginarg1: dn1    
 nsslapd-pluginarg2: dn2   
 ...
  • Any value can be given to the cn attribute to name the plug-in. The name should be descriptive.
  • The cn attribute does not contain the name of the attribute which is checked for uniqueness.
  • Only one attribute can be specified on which the uniqueness check will be performed.
  • It is possible to specify several DNs of suffixes or subtrees in which to perform the uniqueness check by incrementing the nsslapd-pluginarg attribute suffix by one each time.
The variable components of the Attribute Uniqueness Plug-in syntax are described in Table 5.1, “Attribute Uniqueness Plug-in Variables”.
Use the following syntax to specify to perform the uniqueness check below an entry containing a specified object class:
 dn: cn=descriptive_plugin_name,cn=plugins,cn=config
 ...
 nsslapd-pluginEnabled: state      
 nsslapd-pluginarg0: attribute=attribute_name      
 nsslapd-pluginarg1: markerObjectClass=objectclass1      
 nsslapd-pluginarg2: requiredObjectClass=objectclass2     
 ...
  • Any value can be given to the cn attribute to name the plug-in. The name should be descriptive.
  • The cn attribute does not contain the name of the attribute which is checked for uniqueness.
  • Only one attribute can be specified on which the uniqueness check will be performed.
  • If the nsslapd-pluginarg0 attribute begins with attribute=attribute_name, then the server expects the nsslapd-pluginarg1 attribute to include a markerObjectClass value.
The variable components of the attribute uniqueness plug-in syntax are described in Table 5.1, “Attribute Uniqueness Plug-in Variables”.

Table 5.1. Attribute Uniqueness Plug-in Variables

Variable Definition
descriptive_plugin_name Specifies the name of this instance of the Attribute Uniqueness Plug-in. It is not required that the name of the attribute for which to ensure uniqueness be included, but it is advisable. For example, cn=mail uniqueness,cn=plugins,cn=config.
state Defines whether the plug-in is enabled or disabled. Acceptable values are on or off.
attribute_name The name of the attribute for which to ensure unique values. Only one attribute can be named.
dn The DN of the suffix or subtree in which to ensure attribute uniqueness. To specify several suffixes or subtrees, increment the suffix of the nsslapd-pluginarg attribute by one for each additional suffix or subtree.
attribute= attribute_name The name of the attribute for which to ensure unique values. Only one attribute can be named.
markerObjectClass= objectclass1 Attribute uniqueness will be checked under the entry belonging to the DN of the updated entry that has the object class specified in the markerObjectClass keyword. Do not include a space before or after the equals sign.
requiredObjectClass= objectclass2 Optional. When using the markerObjectClass keyword to specify the scope of the uniqueness check instead of a DN, it is also possible to specify to perform the check only if the updated entry contains the objectclass specified in the requiredObjectClass keyword. Do not include a space before or after the equals sign.

5.1.2. Creating an Instance of the Attribute Uniqueness Plug-in

To ensure that a particular attribute in the directory always has unique values, create an instance of the Attribute Uniqueness Plug-in for the attribute to check. For example, to ensure that every entry in the directory that includes a mail attribute has a unique value for that attribute, create a mail uniqueness plug-in.
To create an instance of the Attribute Uniqueness Plug-in, modify the Directory Server configuration to add an entry for the new plug-in under the cn=plugins,cn=config entry. The format of the new entry must conform to the syntax described in Section 5.1.1, “Attribute Uniqueness Plug-in Syntax”.

NOTE

Red Hat strongly encourages you to copy and paste an existing Attribute Uniqueness Plug-in entry and only modify the attributes listed below.
For example, to create an instance the Attribute Uniqueness Plug-in for the mail attribute:
  1. Stop the Directory Server. Changes to the dse.ldif file are not saved if it is edited while the server is running.
    service dirsrv stop instance_name
  2. In the dse.ldif file, locate the entry for the Attribute Uniqueness Plug-in, cn=attribute uniqueness,cn=plugins,cn=config.
  3. Copy the entire entry. The entry ends in an empty line; copy the empty line, too.
  4. Paste the copied Attribute Uniqueness Plug-in entry at the end of the file.
  5. Modify the Attribute Uniqueness Plug-in entry attributes for the new attribute information:
    dn: cn=mail uniqueness,cn=plugins,cn=config
    ...
    nsslapd-pluginEnabled: on
    nsslapd-pluginarg0: mail
    nsslapd-pluginarg1: dc=example,dc=com
    ...
  6. Restart the Directory Server.
    service dirsrv start instance_name
In this example, the uniqueness check will be performed on every entry in the dc=example,dc=com entry that includes the mail attribute.

5.1.3. Configuring Attribute Uniqueness

This section explains how to use Directory Server Console to view the plug-ins configured for the directory and how to modify the configuration of the Attribute Uniqueness Plug-ins.

5.1.3.1. Configuring Attribute Uniqueness Plug-ins from the Directory Server Console

  1. In the Directory Server Console, select the Configuration tab; then, in the navigation tree, expand the Plug-ins folder, and select the Attribute Uniqueness Plug-in to modify.
    The configuration parameters for the plug-in are displayed in the right pane.
  2. To add a suffix or subtree, click Add, and type a DN in the blank text field.
    To delete a suffix from the list, place the cursor in the text field to delete, and click Delete.
    To avoid using a DN, enter the markerObjectClass keyword. With this syntax, it is possible to click Add again to specify a requiredObjectClass, as described in Section 5.1.1, “Attribute Uniqueness Plug-in Syntax”.

    NOTE

    Do not add an attribute name to the list. To check the uniqueness of other attributes, create a new instance of the Attribute Uniqueness Plug-in for the attribute to check. For information, see Section 5.1.2, “Creating an Instance of the Attribute Uniqueness Plug-in”.
  3. Click Save.

5.1.3.2. Configuring Attribute Uniqueness Plug-ins from the Command Line

This section provides information about configuring the plug-in from the command line.
5.1.3.2.1. Specifying a Suffix or Subtree
The suffix or subtrees which the plug-in checks to ensure attribute uniqueness are defined using the nsslapd-pluginarg attribute in the entry defining the plug-in.
To specify the subtree or subtrees, use ldapmodify to send LDIF update statements, similar to this example:
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=mail uniqueness,cn=plugins,cn=config
changetype: modify
add: nsslapd-pluginarg2 nsslapd-pluginarg3
nsslapd-pluginarg2: ou=Engineering,dc=example,dc=com
nsslapd-pluginarg3: ou=Sales,dc=example,dc=com
This example LDIF statement modified the Attribute Uniqueness Plug-in to check the uniqueness of the mail attribute under the subtrees dc=example,dc=com, ou=Engineering,dc=example,dc=com, and ou=Sales,dc=example,dc=com.
Use the ldapmodify command to import the LDIF file into the directory. For detailed information on the ldapmodify command, see the Directory Server Configuration and Command-Line Tool Reference.
Whenever this type of configuration change is made, restart the server.
service dirsrv restart instance_name
For information on restarting the server, see Section 1.4, “Starting and Stopping Servers”.
5.1.3.2.2. Using the markerObjectClass and requiredObjectClass Keywords
Instead of specifying a suffix or subtree in the configuration of an Attribute Uniqueness Plug-in, perform the check under the entry belonging to the DN of the updated entry that has the object class given in the markerObjectClass keyword.
To specify to perform the uniqueness check under the entry in the DN of the updated entry that contains the organizational unit (ou) object class, copy and paste an existing Attribute Uniqueness Plug-in entry, and change the following attributes:
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=mail uniqueness,cn=plugins,cn=config
...
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: attribute=mail
nsslapd-pluginarg1: markerObjectClass=organizationalUnit
...
If the server should not check every entry in the organization unit, limit the scope by setting the check to be performed only if the updated entry contains a specified object class.
For example, if the uniqueness of the mail attribute is checked, it is probably only necessary to perform the check when adding or modifying entries with the person or inetorgperson object class.
Restrict the scope of the check by using the requiredObjectClass keyword, as shown in the following example:
dn: cn=mail uniqueness,cn=plugins,cn=config
...
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: attribute=mail
nsslapd-pluginarg1: markerObjectClass=organizationalUnit
nsslapd-pluginarg2: requiredObjectClass=person
...
The markerObjectClass or requiredObjectClass keywords cannot be repeated by incrementing the counter in the nsslapd-pluginarg attribute suffix. These keywords can only be used once per Attribute Uniqueness Plug-in instance.

NOTE

The nsslapd-pluginarg0 attribute always contains the name of the attribute for which to ensure uniqueness.

5.1.4. Attribute Uniqueness Plug-in Syntax Examples

This section contains examples of Attribute Uniqueness Plug-in syntax in the dse.ldif file.

5.1.4.1. Specifying One Attribute and One Subtree

This example configures the plug-in to ensure the uniqueness of the mail attribute under the dc=example,dc=com subtree.
dn: cn=mail uniqueness,cn=plugins,cn=config
...
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: mail
nsslapd-pluginarg1: dc=example,dc=com
...

5.1.4.2. Specifying One Attribute and Multiple Subtrees

It is possible use a single plug-in instance to check for the uniqueness of an attribute within multiple subtrees, which means that the attribute value must be unique within each subtree but not unique across all subtrees. This example configures the Attribute Uniqueness Plug-in to ensure the uniqueness of the mail attribute for separate subtrees, l=Chicago,dc=example,dc=com and l=Boston,dc=example,dc=com.
dn: cn=mail uniqueness,cn=plugins,cn=config
...
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: mail
nsslapd-pluginarg1: l=Chicago,dc=example,dc=com
nsslapd-pluginarg2: l=Boston,dc=example,dc=com 
...

NOTE

The nsslapd-pluginarg0 attribute always contains the name of the attribute for which to ensure uniqueness. All other occurrences of the nsslapd-pluginarg, such as nsslapd-pluginarg1, contain DNs.
With this configuration, the plug-in allows an instance of a value for the mail attribute to exist once under the l=Chicago,dc=example,dc=com subtree and once under the l=Boston,dc=example,dc=com subtree. For example, the following two attribute-value settings are allowed:
mail=bjensen,l=Chicago,dc=example,dc=com
mail=bjensen,l=Boston,dc=example,dc=com
To ensure that only one instance of a value exists under both subtrees, configure the plug-in to ensure uniqueness for the entire dc=example,dc=com subtree.

5.2. Assigning Class of Service

A class of service definition (CoS) shares attributes between entries in a way that is transparent to applications. CoS simplifies entry management and reduces storage requirements.
Clients of the Directory Server read the attributes in a user's entry. With CoS, some attribute values may not be stored within the entry itself. Instead, these attribute values are generated by class of service logic as the entry is sent to the client application.
Each CoS is comprised of two types of entry in the directory:
  • CoS definition entry. The CoS definition entry identifies the type of CoS used. Like the role definition entry, it inherits from the LDAPsubentry object class. The CoS definition entry is below the branch at which it is effective.
  • Template entry. The CoS template entry contains a list of the shared attribute values. Changes to the template entry attribute values are automatically applied to all the entries within the scope of the CoS. A single CoS might have more than one template entry associated with it.
The CoS definition entry and template entry interact to provide attribute information to their target entries, any entry within the scope of the CoS.

5.2.1. About the CoS Definition Entry

The CoS definition entry is an instance of the cosSuperDefinition object class. The CoS definition entry also contains one of three object class that specifies the type of template entry it uses to generate the entry. The target entries which interact with the CoS share the same parent as the CoS definition entry.
There are three types of CoS, defined using three types of CoS definition entries:
  • Pointer CoS. A pointer CoS identifies the template entry using the template DN only.
  • Indirect CoS. An indirect CoS identifies the template entry using the value of one of the target entry's attributes. For example, an indirect CoS might specify the manager attribute of a target entry. The value of the manager attribute is then used to identify the template entry.
    The target entry's attribute must be single-valued and contain a DN.
  • Classic CoS. A classic CoS identifies the template entry using a combination of the template entry's base DN and the value of one of the target entry's attributes.
For more information about the object classes and attributes associated with each type of CoS, refer to Section 5.2.11, “Managing CoS from the Command Line”.
If the CoS logic detects that an entry contains an attribute for which the CoS is generating values, the CoS, by default, supplies the client application with the attribute value in the entry itself. However, the CoS definition entry can control this behavior.

5.2.2. About the CoS Template Entry

The CoS template entry contains the value or values of the attributes generated by the CoS logic. The CoS template entry contains a general object class of cosTemplate. The CoS template entries for a given CoS are stored in the directory tree along with the CoS definition.
The relative distinguished name (RDN) of the template entry is determined by one of the following:
  • The DN of the template entry alone. This type of template is associated with a pointer CoS definition.
  • The value of one of the target entry's attributes. The attribute used to provide the relative DN to the template entry is specified in the CoS definition entry using the cosIndirectSpecifier attribute. This type of template is associated with an indirect CoS definition.
  • By a combination of the DN of the subtree where the CoS performs a one level search for templates and the value of one of the target entry's attributes. This type of template is associated with a classic CoS definition.

5.2.3. How a Pointer CoS Works

An administrator creates a pointer CoS that shares a common postal code with all of the entries stored under dc=example,dc=com. The three entries for this CoS appear as illustrated in Figure 5.1, “Sample Pointer CoS”.
Sample Pointer CoS

Figure 5.1. Sample Pointer CoS


In this example, the template entry is identified by its DN, cn=exampleUS,cn=data, in the CoS definition entry. Each time the postalCode attribute is queried on the entry cn=wholiday,ou=people,dc=example,dc=com, the Directory Server returns the value available in the template entry cn=exampleUS,cn=data.

5.2.4. How an Indirect CoS Works

An administrator creates an indirect CoS that uses the manager attribute of the target entry to identify the template entry. The three CoS entries appear as illustrated in Figure 5.2, “Sample Indirect CoS”.
Sample Indirect CoS

Figure 5.2. Sample Indirect CoS


In this example, the target entry for William Holiday contains the indirect specifier, the manager attribute. William's manager is Carla Fuentes, so the manager attribute contains a pointer to the DN of the template entry, cn=Carla Fuentes,ou=people,dc=example,dc=com. The template entry in turn provides the departmentNumber attribute value of 318842.

5.2.5. How a Classic CoS Works

An administrator creates a classic CoS that uses a combination of the template DN and a CoS specifier to identify the template entry containing the postal code. The three CoS entries appear as illustrated in Figure 5.3, “Sample Classic CoS”:
Sample Classic CoS

Figure 5.3. Sample Classic CoS


In this example, the CoS definition entry's cosSpecifier attribute specifies the employeeType attribute. This attribute, in combination with the template DN, identify the template entry as cn=sales,cn=exampleUS,cn=data. The template entry then provides the value of the postalCode attribute to the target entry.

5.2.6. Handling Physical Attribute Values

The cosAttribute attribute contains the name of another attribute which is governed by the class of service. This attribute allows an override qualifier (after the attribute value) which sets how the CoS handles existing attribute values on entries when it generates attribute values.
cosAttribute: attribute_name override
There are four override qualifiers.
Override Qualifier Description
default Only returns a generated value if there is no corresponding attribute value stored with the entry.
override Always returns the value generated by the CoS, even when there is a value stored with the entry.
operational Returns a generated attribute only if it is explicitly requested in the search. Operational attributes do not need to pass a schema check in order to be returned. When operational is used, it also overrides any existing attribute values.

NOTE

An attribute can only be made operational if it is defined as operational in the schema. For example, if the CoS generates a value for the description attribute, it is not possible to use the operational qualifier because this attribute is not marked operational in the schema.
operational-default Only returns a generated value if there is no corresponding attribute value stored with the entry and if it is explicitly requested in the search.
If no qualifier is set, default is assumed.
For example, this pointer CoS definition entry indicates that it is associated with a template entry, cn=exampleUS,ou=data,dc=example,dc=com, that generates the value of the postalCode attribute. The override qualifier indicates that this value will take precedence over the value stored by the entries for the postalCode attribute:
dn: cn=pointerCoS,dc=example,dc=com
objectclass: top
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDn: cn=exampleUS,ou=data,dc=example,dc=com
cosAttribute: postalCode override

NOTE

If an entry contains an attribute value generated by a CoS, the value of the attribute cannot be manually updated if it is defined with the operational or override qualifiers.
For more information about the CoS attributes, see the Directory Server Configuration and Command-Line Tool Reference.

5.2.7. Handling Multi-valued Attributes with CoS

Any attribute can be generated using a class of service — including multi-valued attributes. That introduces the potential for confusion. Which CoS supplies a value? Any of them or all of them? How is the value selected from competing CoS templates? Does the generated attribute use a single value or multiple values?
There way to resolve this is to set a priority to select one CoS value out of competing CoS definitions. This generates one single value for the target entry.

NOTE

Indirect CoS don't support the cosPriority attribute.
If there are multiple CoS definitions available for an attribute, then the value is chosen arbitrarily. This is an unpredictable and unwieldy option. The way to control which CoS template to use is to set a ranking on the template — a priority — and the highest prioritized CoS always "wins" and provides the value.
It is fairly common for there to be multiple templates completing to provide a value. For example, there can be a multi-valued cosSpecifier attribute in the CoS definition entry. The template priority is set using the cosPriority attribute. This attribute represents the global priority of a particular template. A priority of zero is the highest priority.
For example, a CoS template entry for generating a department number appears as follows:
dn: cn=data,dc=example,dc=com
objectclass: top
objectclass: extensibleObject
objectclass: cosTemplate
departmentNumber: 71776
cosPriority: 0
This template entry contains the value for the departmentNumber attribute. It has a priority of zero, meaning this template takes precedence over any other conflicting templates that define a different departmentNumber value.
Templates that contain no cosPriority attribute are considered the lowest priority. Where two or more templates are considered to supply an attribute value and they have the same (or no) priority, a value is chosen arbitrarily.

NOTE

The behavior for negative cosPriority values is not defined in Directory Server; do not enter negative values.

5.2.8. Searches for CoS-Specified Attributes

CoS definitions provide values for attributes in entries. For example, a CoS can set the postalCode attribute for every entry in a subtree. Searches against those CoS-defined attributes, however, do not behave like searches against regular entries.
If the CoS-defined attribute is indexed with any kind of index (including presence), then any attribute with a value set by the CoS is not returned with a search. For example:
  • The postalCode attribute for Ted Morris is defined by a CoS.
  • The postalCode attribute for Barbara Jensen is set in her entry.
  • The postalCode attribute is indexed.
If an ldapsearch command uses the filter (postalCode=*), then Barbara Jensen's entry is returned, while Ted Morris's is not.
If the CoS-defined attribute is not indexed, then every matching entry is returned in a search, regardless of whether the attribute value is set locally or with CoS. For example:
  • The postalCode attribute for Ted Morris is defined by a CoS.
  • The postalCode attribute for Barbara Jensen is set in her entry.
  • The postalCode attribute is not indexed.
If an ldapsearch command uses the filter (postalCode=*), then both Barbara Jensen's and Ted Morris's entries are returned.
CoS allows for an override, an identifier given to the cosAttribute attribute in the CoS entry, which means that local values for an attribute can override the CoS value. If an override is set on the CoS, then an ldapsearch operation will return a value for an entry even if the attribute is indexed, as long as there is a local value for the entry. Other entries which possess the CoS but do not have a local value will still not be returned in the ldapsearch operation.
Because of the potential issues with running LDAP search requests on CoS-defined attributes, take care when deciding which attributes to generate using a CoS.

5.2.9. Access Control and CoS

The server controls access to attributes generated by a CoS in exactly the same way as regular stored attributes. However, access control rules depending upon the value of attributes generated by CoS will not work. This is the same restriction that applies to using CoS-generated attributes in search filters.

5.2.10. Managing CoS Using the Console

This section describes creating and editing CoS through the Directory Server Console:

5.2.10.1. Creating a New CoS

  1. In the Directory Server Console, select the Directory tab.
  2. Browse the tree in the left navigation pane, and select the parent entry for the new class of service.
  3. Go to the Object menu, and select New > Class of Service.
    Alternatively, right-click the entry and select New > Class of Service.
  4. Select General in the left pane. In the right pane, enter the name of the new class of service in the Class Name field. Enter a description of the class in the Description field.
  5. Click Attributes in the left pane. The right pane displays a list of attributes generated on the target entries.
    Click Add to browse the list of possible attributes and add them to the list.
  6. After an attribute is added to the list, a drop-down list appears in the Class of Service Behavior column.
    • Select Does not override target entry attribute to tell the directory to only return a generated value if there is no corresponding attribute value stored with the entry.
    • Select Overrides target entry attribute to make the value of the attribute generated by the CoS override the local value.
    • Select Overrides target entry attribute and is operational to make the attribute override the local value and to make the attribute operational, so that it is not visible to client applications unless explicitly requested.
    • Select Does not override target entry attribute and is operational to tell the directory to return a generated value only if there is no corresponding attribute value stored with the entry and to make the attribute operational (so that it is not visible to client applications unless explicitly requested).

    NOTE

    An attribute can only be made operational if it is also defined as operational in the schema. For example, if a CoS generates a value for the description attribute, you cannot select Overrides target entry attribute and is operational because this attribute is not marked operational in the schema.
  7. Click Template in the left pane. In the right pane, select how the template entry is identified.
    • By its DN. To have the template entry identified by only its DN (a pointer CoS), enter the DN of the template in the Template DN field. Click Browse to locate the DN on the local server. This will be an exact DN, such as cn=CoS template,ou=People,dc=example,dc=com.
    • Using the value of one of the target entry's attribute. To have the template entry identified by the value of one of the target entry's attributes (an indirect CoS), enter the attribute name in the Attribute Name field. Click Change to select a different attribute from the list of available attributes.
    • Using both its DN and the value of one of the target entry's attributes. To have the template entry identified by both its DN and the value of one of the target entry's attributes (a classic CoS), enter both a template DN and an attribute name. The template DN in a classic CoS is more general than for a pointer CoS; it references the suffix or subsuffix where the template entries will be. There can be more than one template for a classic CoS.
  8. Click OK.

5.2.10.2. Creating the CoS Template Entry

For a pointer CoS or a classic CoS, there must be a template entry, according to the template DN set when the class of service was created. Although the template entries can be placed anywhere in the directory as long as the cosTemplateDn attribute reflects that DN, it is best to place the template entries under the CoS itself.
  • For a pointer CoS, make sure that this entry reflects the exact DN given when the CoS was created.
  • For a classic CoS, the template DN should be recursive, pointing back to the CoS entry itself as the base suffix for the template.
  1. In the Directory Server Console, select the Directory tab.
  2. Browse the tree in the left navigation pane, and select the parent entry that contains the class of service.
    The CoS appears in the right pane with other entries.
  3. Right-click the CoS, and select New > Other.
    Alternatively, select the CoS in the right pane, click Object in the menu at the top, and select New > Other.
  4. Select cosTemplate from the list of object classes.

    NOTE

    The LDAPsubentry object class can be added to a new template entry. Making the CoS template entry an instance of the LDAPsubentry object class allows ordinary searches to be performed unhindered by the configuration entries. However, if the template entry already exists and is used for something else (for example, if it is a user entry), the LDAPsubentry object class does not need to be added to the template entry.
  5. Select the object classes attribute, and click Add Value.
  6. Add the extensibleObject object class. This makes it possible to add any attribute available in the directory.
  7. Click the Add Attribute button.
  8. Add the cn attribute, and give it a value that corresponds to the attribute value in the target entry. For example, if the manager attribute is used to set the value for a classic CoS, give the cn a value of a manager's DN, such as uid=bparker,ou=people,dc=example,dc=com. Alternatively, set it to a role, such as cn=QA Role,dc=example,dc=com or a regular attribute value. For example, if the employeeType attribute is selected, it can be full time or temporary.
  9. Click the Change button in the lower right corner to change the naming attribute.
  10. Use the cn of the entry as the naming attribute instead of cosPriority.
  11. Click the Add Attribute button, and add the attributes listed in the CoS. The values used here will be used throughout the directory in the targeted entries.
  12. Set the cosPriority. There may be more than one CoS that applies to a given attribute in an entry; the cosPriority attribute ranks the importance of that particular CoS. The higher cosPriority will take precedence in a conflict. The highest priority is 0.
    Templates that contain no cosPriority attribute are considered the lowest priority. In the case where two or more templates could supply an attribute value and they have the same (or no) priority, a value is chosen arbitrarily.

    NOTE

    The behavior for negative cosPriority values is not defined in Directory Server; do not enter negative values.

    NOTE

    The cosPriority attribute is not supported by indirect CoS.
The CoS is visible in the left navigation pane once there are entries beneath it. For classic CoS, there can be multiple entries, according to the different potential values of the attribute specifier.
To edit the description or attributes generated on the target entry of an existing CoS, simply double-click the CoS entry listed in the Directory tab, and make the appropriate changes in the editor window.

5.2.11. Managing CoS from the Command Line

Because all configuration information and template data is stored as entries in the directory, standard LDAP tools can be used for CoS configuration and management.

5.2.11.1. Creating the CoS Definition Entry from the Command Line

Each type of CoS requires a particular object class to be specified in the definition entry. All CoS definition object classes inherit from the LDAPsubentry object class and the cosSuperDefinition object class.
A pointer CoS uses the cosPointerDefinition object class. This object class identifies the template entry using an entry DN value specified in the cosTemplateDn attribute, as shown in Example 5.1, “An Example Pointer CoS Entry”.

Example 5.1. An Example Pointer CoS Entry

 dn: cn=pointerCoS,dc=example,dc=com
 objectclass: top 
 objectclass: cosSuperDefinition 
 objectclass: cosPointerDefinition   
 cosTemplateDn:DN_string  
 cosAttribute:list_of_attributes qualifier  
 cn: pointerCoS

An indirect CoS uses the cosIndirectDefinition object class. This type of CoS identifies the template entry based on the value of one of the target entry's attributes, as specified in the cosIndirectSpecifier attribute. This is illustrated in Example 5.2, “An Example Indirect CoS Entry”.

Example 5.2. An Example Indirect CoS Entry

 dn: cn=indirectCoS,dc=example,dc=com
 objectclass: top 
 objectclass: cosSuperDefinition 
 objectclass: cosIndirectDefinition   
 cosIndirectSpecifier:attribute_name  
 cosAttribute:list_of_attributes qualifier  
 cn: indirectCoS

A classic CoS uses the cosClassicDefinition object class. This identifies the template entry using both the template entry's DN (set in the cosTemplateDn attribute) and the value of one of the target entry's attributes (set in the cosSpecifier attribute). This is illustrated in Example 5.3, “An Example Classic CoS Entry”.

Example 5.3. An Example Classic CoS Entry

 dn: cn=classicCoS,dc=example,dc=com
 objectclass: top 
 objectclass: cosSuperDefinition 
 objectclass: cosClassicDefinition   
 cosTemplateDn:DN_string  
 cosSpecifier:attribute_name  
 cosAttribute:list_of_attributes qualifier  
 cn: classicCoS

For a class of service, the object class defines the type of CoS, and the supporting attributes identify which directory entries are affected by defining the CoS template. Every CoS has one additional attribute which can be defined for it: cosAttribute. The purpose of a CoS is to supply attribute values across multiple entries; the cosAttribute attribute defines which attribute the CoS generates values for.

5.2.11.2. Creating the CoS Template Entry from the Command Line

Each template entry is an instance of the cosTemplate object class.

NOTE

Consider adding the LDAPsubentry object class to a new template entry. Making the CoS template entry an instance of the LDAPsubentry object classes allows ordinary searches to be performed unhindered by the configuration entries. However, if the template entry already exists and is used for something else, such as a user entry, the LDAPsubentry object class does not need to be added to the template entry.
The CoS template entry also contains the attribute generated by the CoS (as specified in the cosAttribute attribute of the CoS definition entry) and the value for that attribute.
For example, a CoS template entry that provides a value for the postalCode attribute follows:
dn:cn=exampleUS,ou=data,dc=example,dc=com
objectclass: top
objectclass: extensibleObject
objectclass: cosTemplate
postalCode: 44438
The following sections provide examples of template entries along with examples of each type of CoS definition entry.

5.2.11.3. Example of a Pointer CoS

Example Corporation's administrator is creating a pointer CoS that shares a common postal code with all entries in the dc=example,dc=com tree.
  1. Add a new pointer CoS definition entry to the dc=example,dc=com suffix using ldapmodify:
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
    The ldapmodify utility binds to the server and prepares it to add information to the configuration file.
  2. Next, add the pointer CoS definition to the dc=example,dc=com root suffix.
    dn: cn=pointerCoS,dc=example,dc=com
    objectclass: top
    objectclass: cosSuperDefinition
    objectclass: cosPointerDefinition
    cosTemplateDn: cn=exampleUS,ou=data,dc=example,dc=com
    cosAttribute: postalCode
  3. Create the template entry.
    dn: cn=exampleUS,ou=data,dc=example,dc=com
    objectclass: top
    objectclass: extensibleObject
    objectclass: cosTemplate
    postalCode: 44438
The CoS template entry (cn=exampleUS,ou=data,dc=example,dc=com) supplies the value stored in its postalCode attribute to any entries located under the dc=example,dc=com suffix. These entries are the target entries.

5.2.11.4. Example of an Indirect CoS

This indirect CoS uses the manager attribute of the target entry to identify the CoS template entry, which varies depending on the different values of the attribute.
  1. Add a new indirect CoS definition entry to the dc=example,dc=com suffix, using ldapmodify as follows:
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
    The ldapmodify utility binds to the server and prepares it to add information to the configuration file.
  2. Add the indirect CoS definition to the dc=example,dc=com root suffix as follows:
    dn: cn=indirectCoS,dc=example,dc=com
    objectclass: top
    objectclass: cosSuperDefinition
    objectclass: cosIndirectDefinition
    cosIndirectSpecifier: manager
    cosAttribute: departmentNumber
If the directory or modify the manager entries already contain the departmentNumber attribute, then no other attribute needs to be added to the manager entries. The definition entry looks in the target suffix (the entries under dc=example,dc=com) for entries containing the manager attribute because this attribute is specified in the cosIndirectSpecifier attribute of the definition entry). It then checks the departmentNumber value in the manager entry that is listed. The value of the departmentNumber attribute will automatically be relayed to all of the manager's subordinates that have the manager attribute. The value of departmentNumber will vary depending on the department number listed in the different manager's entries.

5.2.11.5. Example of a Classic CoS

The Example Corporation administrator is creating a classic CoS that automatically generates postal codes using a combination of the template DN and the attribute specified in the cosSpecifier attribute.
  1. Add a new classic CoS definition entry to the dc=example,dc=com suffix, using ldapmodify.
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
    The ldapmodify utility binds to the server and prepares it to add information to the configuration file.
  2. Add the indirect CoS definition to the dc=example,dc=com root suffix.
    dn: cn=classicCoS,dc=example,dc=com
    objectclass: top
    objectclass: cosSuperDefinition
    objectclass: cosClassicDefinition
    cosTemplateDn: cn=classicCoS,dc=example,dc=com
    cosSpecifier: businessCategory
    cosAttribute: postalCode override
  3. Create the template entries for the sales and marketing departments. Add the CoS attributes to the template entry. The cn of the template sets the value of the businessCategory attribute in the target entry, and then the attributes are added or overwritten according to the value in the template:
    dn: cn=sales,cn=classicCoS,dc=example,dc=com
    objectclass: top
    objectclass: extensibleObject
    objectclass: cosTemplate
    postalCode: 44438
    
    dn: cn=marketing,cn=classicCoS,dc=example,dc=com
    objectclass: top
    objectclass: extensibleObject
    objectclass: cosTemplate
    postalCode: 99111
The classic CoS definition entry applies to all entries under the dc=example,dc=com suffix. Depending upon the combination of the businessCategory attribute found in the entry and the cosTemplateDn, it can arrive at one of two templates. One, the sales template, provides a postal code specific to employees in the sales department. The marketing template provides a postal code specific to employees in the marketing department.

5.2.11.6. Searching for CoS Entries

CoS definition entries are operational entries and are not returned by default with regular searches. This means that if a CoS is defined under ou=People,dc=example,dc=com, for example, the following ldapsearch command will not return them:
ldapsearch -s sub -b ou=People,dc=example,dc=com “(objectclass=*)”
To return the CoS definition entries, add the ldapSubEntry object class to the CoS definition entries. For example:
dn: cn=pointerCoS,ou=People,dc=example,dc=com
objectclass: top 
objectclass: cosSuperDefinition 
objectclass: cosPointerDefinition 
objectclass: ldapSubEntry 
cosTemplateDn: cn=exampleUS,ou=data,dc=example,dc=com
cosAttribute: postalCode override
Then use a special search filter, (objectclass=ldapSubEntry), with the search. This filter can be added to any other search filter using OR (|):
ldapsearch -s sub -b ou=People,dc=example,dc=com “(|(objectclass=*)(objectclass=ldapSubEntry))”
This search returns all regular entries in addition to CoS definition entries in the ou=People,dc=example,dc=com subtree.

NOTE

The Console automatically shows CoS entries.

5.2.12. Creating Role-Based Attributes

Classic CoS schemes generate attribute values for an entry based on the role possessed by the entry. For example, role-based attributes can be used to set the server look-through limit on an entry-by-entry basis.
To create a role-based attribute, use the nsRole attribute as the cosSpecifier in the CoS definition entry of a classic CoS. Because the nsRole attribute can be multi-valued, CoS schemes can be defined that have more than one possible template entry. To resolve the ambiguity of which template entry to use, include the cosPriority attribute in the CoS template entry.
For example, this CoS allows members of the manager role to exceed the standard mailbox quota. The manager role entry is:
dn: cn=ManagerRole,ou=people,dc=example,dc=com
objectclass: top
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsFilteredRoleDefinition
cn: ManagerRole
nsRoleFilter: ou=managers
Description: filtered role for managers

IMPORTANT

The nsRoleFilter attribute cannot accept virtual attribute values.
The classic CoS definition entry looks like:
dn: cn=managerCOS,dc=example,dc=com
objectclass: top
objectclass: cosSuperDefinition
objectclass: cosClassicDefinition
cosTemplateDn: cn=managerCOS,dc=example,dc=com
cosSpecifier: nsRole
cosAttribute: mailboxquota override
The cosTemplateDn attribute provides a value that, in combination with the attribute specified in the cosSpecifier attribute (in the example, the nsRole attribute of the target entry), identifies the CoS template entry. The CoS template entry provides the value for the mailboxquota attribute. An additional qualifier of override tells the CoS to override any existing mailboxquota attributes values in the target entry.
The corresponding CoS template entry looks as follows:
dn:cn=cn=ManagerRole\,ou=people\,dc=example\,dc=com,cn=managerCOS,dc=example,dc=com
objectclass: top
objectclass: extensibleObject
objectclass: cosTemplate
mailboxquota: 1000000
The template provides the value for the mailboxquota attribute, 1000000.

NOTE

The role entry and the CoS definition and template entries should be located at the same level in the directory tree.

5.3. Linking Attributes to Manage Attribute Values

A class of service dynamically supplies attribute values for entries which all have attributes with the same value, like building addresses, postal codes, or main office numbers. These are shared attribute values, which are updated in a single template entry.
Frequently, though, there are relationships between entries where there needs to be a way to express linkage between them, but the values (and possibly even the attributes) that express that relationship are different. Red Hat Directory Server provides a way to link specified attributes together, so that when one attribute in one entry is altered, a corresponding attribute on a related entry is automatically updated. (The link and managed attributes both have DN values. The value of the link attribute contains the DN of the entry for the plug-in to update; the managed attribute in the second entry has a DN value which points back to the original link entry.)

5.3.1. About Linking Attributes

The Linked Attributes Plug-in, allows multiple instances of the plug-in. Each instance configures one attribute which is manually maintained by the administrator (linkType) and one attribute which is automatically maintained by the plug-in (managedType).
Basic Linked Attribute Configuration

Figure 5.4. Basic Linked Attribute Configuration


NOTE

To preserve data consistency, only the plug-in process should maintain the managed attribute. Consider creating an ACI that will restrict all write access to any managed attribute. See Section 12.5.2, “Creating a New ACI” To preserve data consistency, only the plug-in process should maintain the managed attribute. Consider creating an ACI that will restrict all write access to any managed attribute. See Section 12.5.2, “Creating a New ACI” for information on setting ACIs.
A Linked Attribute Plug-in instance can be restricted to a single subtree within the directory. This can allow more flexible customization of attribute combinations and affected entries. If no scope is set, then the plug-in operates in the entire directory.
Restricting the Linked Attribute Plug-in to a Specific Subtree

Figure 5.5. Restricting the Linked Attribute Plug-in to a Specific Subtree


When configuring the Linked Attribute Plug-in instance, certain configurations are required:
  • Both the managed attribute and linked attribute must require the Distinguished Name syntax in their attribute definitions. The linked attributes are essentially managed cross-references, and the way that the plug-in handles these cross-references is by pulling the DN of the entry from the attribute value.
    For information on planning custom schema elements, see Chapter 6, Managing the Directory Schema.
  • Each Linked Attribute Plug-in instance must be local and any managed attributes must be blocked from replication using fractional replication.
    Any changes that are made on one supplier will automatically trigger the plug-in to manage the values on the corresponding directory entries, so the data stay consistent across servers. However, the managed attributes must be maintained by the plug-in instance for the data to be consistent between the linked entries. This means that managed attribute values should be maintained solely by the plug-in processes, not the replication process, even in a multi-master replication environment.
    For information on using fractional replication, see Section 9.1.7, “Replicating a Subset of Attributes with Fractional Replication”.

5.3.2. Looking at the Linking Attributes Plug-in Syntax

The default Linked Attributes Plug-in entry is a container entry for each plug-in instance, similar to the password syntax plug-ins or the DNA Plug-in in the next section. Each entry beneath this container entry defines a different link-managed attribute pair.
To create a new linking attribute pair, then, create a new plug-in instance beneath the container entry. A basic linking attribute plug-in instance required defining two things:
  • The attribute that is managed manually by administrators, in the linkType attribute
  • The attribute that is created dynamically by the plug-in, in the managedType attribute
  • Optionally, a scope that restricts the plug-in to a specific part of the directory tree, in the linkScope attribute

Example 5.4. Example Linked Attributes Plug-in Instance Entry

dn: cn=Manager Link,cn=Linked Attributes,cn=plugins,cn=config
objectClass: top
objectClass: extensibleObject
cn: Manager Link1
cn: Manager Link
linkType: directReport
managedType: manager
linkScope: ou=people,dc=example,dc=com

All of the attributes available for an instance of the Linked Attributes Plug-in instance are listed in Table 5.2, “Linked Attributes Plug-in Instance Attributes”.

Table 5.2. Linked Attributes Plug-in Instance Attributes

Plug-in Attribute Description
cn Gives a unique name for the plug-in instance.
linkScope Contains the DN of a suffix to which to restrict the function of the plug-in instance.
linkType Gives the attribute which is maintained by an administrator. This attribute is manually maintained and is used as the reference for the plug-in. This attribute must have a DN value format. When the attribute is added, modified, or deleted, then its value contains the DN of the target entry for the plug-in to update.
managedType Gives the attribute which is maintained by the plug-in. This attribute is created and updated on target entries. This attribute must have a DN value format. When the attribute is added to the entry, its value will point back as a cross-reference to the managed entry.

5.3.3. Configuring Attribute Links

NOTE

The Linked Attribute Plug-in instance can be created in the Directory Server Console, but only through the Advanced Property Editor for the directory entry, by manually adding all of the required attributes, the same as creating the entry manually through the command line.
  1. If it is not already enabled, enable the Linked Attributes Plug-in, as described in Section 1.10.1, “Enabling Plug-ins”. For example:
    /usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389
    
    dn: cn=Linked Attributes,cn=plugins,cn=config
    changetype: modify
    replace: nsslapd-pluginEnabled
    nsslapd-pluginEnabled: on
  2. Create the plug-in instance. Both the managedType and linkType attributes are required. The plug-in syntax is covered in Section 5.3.2, “Looking at the Linking Attributes Plug-in Syntax”. For example:
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
    
    dn: cn=Manager Link,cn=Linked Attributes,cn=plugins,cn=config
    objectClass: top
    objectClass: extensibleObject
    cn: Manager Link
    linkType: directReport
    managedType: manager
  3. Restart the server to apply the new plug-in instance.
    service dirsrv restart

5.3.4. Cleaning up Attribute Links

The managed-linked attributes can get out of sync. For instance, a linked attribute could be imported or replicated over to a server, but the corresponding managed attribute was not because the link attribute wasn't properly configured. The managed-linked attribute pairs can be fixed by running a script (fixup-linkedattrs.pl) or by launching a fix-up task.
The fixup task removes any managed attributes (attributes managed by the plug-in) that do not have a corresponding link attribute (attributes managed by the administrator) on the referenced entry. Conversely, the task adds any missing managed attributes if the link attribute exists in an entry.

5.3.4.1. Regenerating Linked Attributes Using fixup-linkedattrs.pl

The fixup-linkedattrs.pl script launches a special task to regenerate all of the managed-link attribute pairs on directory entries. One or the other may be lost in certain situations. If the link attribute exists in an entry, the task traces the cross-referenced DN in the available attribute and creates the corresponding configured managed attribute on the referenced entry. If a managed attribute exists with no corresponding link attribute, then the managed attribute value is removed.
To repair all configured link attribute pairs for the entire scope of the plug-in, then simply run the command as the Directory Manager:
/usr/lib64/dirsrv/instance_name/fixup-linkedattrs.pl -D "cn=Directory Manager" -w password
It is also possible to limit the fixup task to a single link-managed attribute pair, using the -l option to specify the target plug-in instance DN:
/usr/lib64/dirsrv/instance_name/fixup-linkedattrs.pl -D "cn=Directory Manager" -w password -l "cn=Manager Link,cn=Linked Attributes,cn=plugins,cn=config"
The fixup-linkedattrs.pl tool is described in more detail in the Configuration and Command-Line Tool Reference.

5.3.4.2. Regenerating Linked Attributes Using ldapmodify

Repairing linked attributes is one of the tasks which can be managed through a special task configuration entry. Task entries occur under the cn=tasks configuration entry in the dse.ldif file, so it is also possible to initiate a task by adding the entry using ldapmodify. When the task is complete, the entry is removed from the directory.
This task is the same one created automatically by the fixup-linkedattrs.pl script when it is run.
To initiate a linked attributes fixup task, add an entry under the cn=fixup linked attributes,cn=tasks,cn=config entry. The only required attribute is the cn for the specific task, though it also allows the ttl attribute to set a timeout period.
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=example,cn=fixup linked attributes,cn=tasks,cn=config
cn:example
ttl: 5
Once the task is completed, the entry is deleted from the dse.ldif configuration, so it is possible to reuse the same task entry continually.
The cn=fixup linked attributes task configuration is described in more detail in the Configuration and Command-Line Tool Reference.

5.4. Assigning and Managing Unique Numeric Attribute Values

Some entry attributes require having a unique number, such as uidNumber and gidNumber. The Directory Server can automatically generate and supply unique numbers for specified attributes using the Distributed Numeric Assignment (DNA) Plug-in.

NOTE

Attribute uniqueness is not necessarily preserved with the DNA Plug-in. The plug-in only assigns non-overlapping ranges, but it does allow manually-assigned numbers for its managed attributes, and it does not verify or require that the manually-assigned numbers are unique.
The issue with assigning unique numbers is not with generating the numbers but in effectively managing numbers so that there are not any conflicts with other assigned numbers when entries are replicated and that every server has a sufficient range of numbers to assign.
The DNA Plug-in for a server assigns a range of available numbers that that instance can issue. The range definition is very simple and is set by two attributes: the server's next available number (the low end of the range) and its maximum value (the top end of the range). The initial bottom range is set when the plug-in instance is configured. After that, the bottom value is updated by the plug-in. By breaking the available numbers into ranges, the servers can all continually assign numbers without overlapping with each other.
The server performs a sorted search, internally, to see if the next specified range is already taken, requiring the managed attribute to have an equality index with the proper ordering matching rule (as described in Section 7.2, “Creating Standard Indexes”).
For multi-master replication, each supplier can be configured with a threshold, so that when it begins running out of numbers in its range, it can request additional ranges from other suppliers. Each supplier keeps a track of its current range in a separate configuration entry. The configuration entry is replicated to all of the other suppliers, so each supplier can check that configuration to find a server to contact for a new range. For example:
dn: dnaHostname=ldap1.example.com+dnaPortNum=389,cn=Account UIDs,ou=Ranges,dc=example,dc=com
objectClass: extensibleObject
objectClass: top
dnahostname: ldap1.example.com
dnaPortNum: 389
dnaSecurePortNum: 636
dnaRemainingValues: 1000
The DNA Plug-in is applied, always, to a specific area of the directory tree (the scope) and to specific entry types within that subtree (the filter).
There are several different ways that the Directory Server can handle generating attribute values.
In the simplest case, a user entry is added to the directory with an object class which requires the unique-number attribute, but without the attribute. Adding (or requiring) the managed attribute without a value triggers the DNA Plug-in to assign a value.
A similar and more manageable option is to use a magic number. This magic number is a template value for the managed attribute, something outside the server's range, a number or even a word, that the plug-in recognizes it needs to replace with a new assigned value. When an entry is added with that number, and the entry is within the scope and filter of the configured DNA Plug-in, then using the magic number automatically triggers the plug-in to generate a new value. For example:
 /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com

 dn: uid=jsmith,ou=people,dc=example,dc=com
 objectClass: top
 objectClass: person
 objectClass: posixAccount
 uid: jsmith
 cn: John Smith
 uidNumber: magic    
 ....
The DNA Plug-in only generates new, unique values. If an entry is added or modified to use a specific value for an attribute controlled by the DNA Plug-in, the specified number is used; the DNA Plug-in will not overwrite it.

IMPORTANT

The DNA Plug-in only works on a single backend; it cannot manage number assignments for multiple databases. The DNA plug-in uses the sort control when checking whether a value has already been manually allocated outside of the DNA Plug-in. This validation, using the sort control, only works on a single backend.

5.4.1. Looking at the DNA Plug-in Syntax

The DNA Plug-in itself is a container entry, similar to the Password Storage Schemes Plug-in. Each DNA entry underneath the DNA Plug-in entry defines a new managed range for the DNA Plug-in.
To set new managed ranges for the DNA Plug-in, create entries beneath the container entry.
The most basic configuration is to set up distributed numeric assignments on a single server, meaning the ranges will not be shared or transferred between servers. A basic DNA configuration entry defines four things:
  • The attribute that's value is being managed, set in the dnaType attribute
  • The entry DN to use as the base to search for entries, set in the dnaScope attribute
  • The search filter to use to identify entries to manage, set in the dnaFilter attribute
  • The next available value to assign, set in the dnaNextValue attribute (after the entry is created, this is handled by the plug-in)
For example:
dn: cn=Account UIDs,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config
objectClass: top
objectClass: extensibleObject
cn: Account UIDs
dnatype: uidNumber
dnafilter: (objectclass=posixAccount)
dnascope: ou=people,dc=example,dc=com
dnaNextValue: 1
If multiple suppliers are configured for distributed numeric assignments, then the entry must contain the required information to transfer ranges:
  • The maximum number that the server can assign; this sets the upward bound for the range, which is logically required when multiple servers are assigning numbers. This is set in the dnaMaxValue attribute.
  • The threshold where the range is low enough to trigger a range transfer, set in the dnaThreshold attribute. If this is not set, the default value is 1.
  • A timeout period so that the server does not hang waiting for a transfer, set in the dnaRangeRequestTimeout attribute. If this is not set, the default value is 10, meaning 10 seconds.
  • A configuration entry DN which is shared among all supplier servers, which stores the range information for each supplier, set in the dnaSharedCfgDN attribute.
The specific number range which could be assigned by the server is defined in the dnaNextRange attribute. This shows the next available range for transfer and is managed automatically by the plug-in, as ranges are assigned or used by the server. This range is just "on deck." It has not yet been assigned to another server and is still available for its local Directory Server to use.
dn: cn=Account UIDs,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config
objectClass: top
objectClass: extensibleObject
cn: Account UIDs
dnatype: uidNumber
dnafilter: (objectclass=posixAccount)
dnascope: ou=People,dc=example,dc=com
dnanextvalue: 1
dnaMaxValue: 1300
dnasharedcfgdn: cn=Account UIDs,ou=Ranges,dc=example,dc=com
dnathreshold: 100
dnaRangeRequestTimeout: 60
dnaNextRange: 1301-2301
The dnaNextRange attribute should be set explicitly only if a separate, specific range has to be assigned to other servers. Any range set in the dnaNextRange attribute must be unique from the available range for the other servers to avoid duplication. If there is no request from the other servers and the server where dnaNextRange is set explicitly has reached its set dnaMaxValue, the next set of values (part of the dnaNextRange) is allocated from this deck.
The dnaNextRange allocation is also limited by the dnaThreshold attribute that is set in the DNA configuration. Any range allocated to another server for dnaNextRange cannot violate the threshold for the server, even if the range is available on the deck of dnaNextRange.

NOTE

If the dnaNextRange attribute is handled internally if it is not set explicitly. When it is handled automatically, the dnaMaxValue attribute serves as upper limit for the next range.
All of the attributes available for a DNA Plug-in instance are listed in Table 5.3, “DNA Entry Attributes”.

Table 5.3. DNA Entry Attributes

Plug-in Attribute Description
cn Gives a unique name for the plug-in instance.
dnaType
Contains the name of the attribute for which unique numbers are assigned.
If a prefix will be prepended to the generated value, then be sure to use an attribute which allows the syntax of the combined attribute value, such as a custom attribute which allows alphanumeric strings. Otherwise, syntax validation will enforce the defined syntax for the value, such as integer for uidNumber and gidNumber, and the DNA operations will fail with syntax violations.
dnaScope Sets the base DN to use to search for entries to which to apply the managed ranges.
dnaFilter Gives an LDAP filter to use to specify the kinds of entries for the plug-in to manage.
dnaNextValue Gives the next available number to assign. This is initially set manually when the entry is created; afterward, it is managed by the plug-in.
dnaMaxValue Optionally, the upper limit of the range that the server can assign. Defining the range is required when there are multiple servers assigning numbers to entries. The default value is -1, which is the same as the highest 64-bit integer.
dnaThreshold Sets a limit on the amount of remaining available numbers before the server requests a new range.
dnaSharedCfgDN Specifies the DN of a container entry that each supplier server shares. The plug-in automatically creates an entry for the individual instances underneath this entry which contains their available ranges. The plug-in can use this information to request and transfer ranges as servers consume their available range.
dnaNextRange Shows the next range of numbers which are available to be transferred. This attribute can be set automatically by the plug-in according to the threshold and shared configuration information; this can also be set manually for an administrator to specifically assign an additional range of values to a server. This attribute is always limited by the dnaThreshold settings.
dnaRangeRequestTimeout Sets a timeout period for a range request so that a server does not hang indefinitely waiting for a transfer.
dnaMagicRegen Sets a word or number (outside of the assigned range) which automatically triggers the plug-in to assign a number to an attribute. This is a useful default to use for importing entries.
dnaPrefix
Sets a string to insert in front of whatever number is assigned. For example, if the prefix is user and the assigned number for the attribute is 1001, then the final assigned value is user1001.
dnaPrefix can hold any kind of string. However, some possible values for dnaType (such as uidNumber and gidNumber) require integer syntax for attribute values. To use a prefix string, consider using a custom attribute for dnaType which allows the syntax of the prefix plus the generated number assignment.

5.4.2. Configuring Unique Number Assignments

The unique number distribution is configured by creating different instances of the DNA Plug-in. These DNA Plug-in instances can only be created through the command line, but they can be edited through the Directory Server Console.

5.4.2.1. Configuring Unique Number Assignments

NOTE

Any attribute which has a unique number assigned to it must have an equality index set for it. The server must perform a sorted search, internally, to see if the dnaNextvalue is already taken, which requires an equality index on an integer attribute, with the proper ordering matching rule.
Creating indexes is described in Section 7.2, “Creating Standard Indexes”.

NOTE

Set up the DNA Plug-in on every supplier server, and be careful not to overlap the number range values.
  1. Create the shared container entry in the replicated subtree. For example:
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
    
    dn: ou=Ranges,dc=example,dc=coma
    objectclass: top
    objectclass: extensibleObject
    objectclass: organizationalUnit
    ou: Ranges
    
    
    dn: cn=Account UIDs,ou=Ranges,dc=example,dc=coma
    objectclass: top
    objectclass: extensibleObject
    cn: Account UIDs
  2. Enable the DNA Plug-in. By default, the plug-in entry (which is the container entry) is disabled.
    /usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com
    
    dn: cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config
    changetype: modify
    replace: nsslapd-pluginEnabled
    nsslapd-pluginEnabled: on
  3. Create the new DNA Plug-in instance beneath the container entry.
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
    
    dn: cn=Account UIDs,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config
    objectClass: top
    dnanextvalue: 1
    dnaMaxValue: 1300
    dnasharedcfgdn: cn=Account UIDs,ou=Ranges,dc=example,dc=com
    dnathreshold: 100
    dnaRangeRequestTimeout: 60
    dnaMagicRegen: magic
  4. Restart the server to load the new plug-in instance.
    service dirsrv restart instance_name

5.4.2.2. Editing the DNA Plug-in in the Console

NOTE

Any attribute which has a unique number assigned to it must have an equality index set for it. The server must perform a sorted search, internally, to see if the dnaNextvalue is already taken, which requires an equality index on an integer attribute, with the proper ordering matching rule.
Creating indexes is described in Section 7.2, “Creating Standard Indexes”.
The Directory Server Console can be used to edit the DNA Plug-in instances.
  1. Click the Directory tab.
  2. Open the config folder, and then expand the plugins folder.
  3. Click the Distributed Numeric Assignment plug-in folder. All of the DNA Plug-in instances are listed in the main window.
  4. Highlight the DNA instance entry, and right-click on the Advanced link to open the property editor.
  5. Edit the DNA-related attributes.

Chapter 6. Managing the Directory Schema

Red Hat Directory Server comes with a standard schema that includes hundreds of object classes and attributes. While the standard object classes and attributes should meet most deployments' requirements, it can be necessary to extend the schema for specific directory data. Extending the schema is done by creating new object classes and attributes.
The Directory Server Schema Reference is a references for most the standard Directory Server attributes and object classes, with information on allowed and required attributes, which object classes take which attribute, and OID and value information. This is a good resource for identifying useful schema elements for a directory and determining what custom schema needs to be created.

6.1. Overview of Schema

The directory schema is a set of rules that defines how data can be stored in the directory. Directory information is stored discrete entries, and each entry is comprised of a set of attributes and their values. The kind of identity being described in the entry is defined in the entry's object classes. An object class specifies the kind of object the entry describes through the defined set of attributes for the object class.
In LDAP, an object class defines the set of attributes that can be used to define an entry. The LDAP standard provides object classes for many common types of entries, including people, groups, locations, organizations and divisions, and equipment. The identity is described in a directory entries with attributes and their values, pairs are called attribute-value assertions or AVAs. Any piece of information in the directory is associated with a descriptive attribute. Other aspects of the Directory Server configuration, including matching rules and LDAP controls, are also defined in the schema. All of these together are schema elements.
Every schema element is identified by a unique, dot-separated number. This is called the object identifier or OID.

6.1.1. Default Schema Files

The schema for Directory Server is defined in several different schema files (LDIF files which define schema elements). The Directory Server schema files are instance-specific and are located in the /etc/dirsrv/slapd-instance_name/schema directory. There is also a common /etc/dirsrv/schema directory; the files in this directory are used as templates for new Directory Server instances. Putting custom schema in the /etc/dirsrv/schema directory means that it is automatically included with any new instances.
The default schema files are listed and described in the Schema Reference, which also describes the common standard attributes and object classes. The attributes used by the Directory Server to perform operations and manage entries is described with other configuration settings in the Configuration and Command-Line Tool Reference.

6.1.2. Object Classes

In LDAP, an object class defines the set of attributes that can be used to define an entry. The LDAP standard provides object classes for many common types of entries, such as people (person and inetOrgPerson), groups (groupOfUniqueNames), locations (locality), organizations and divisions (organization and organizationalUnit), and equipment (device).
In a schema file, an object class is identified by the objectclasses line, then followed by its OID, name, a description, its direct superior object class (an object class which is required to be used in conjunction with the object class and which shares its attributes with this object class), and the list of required (MUST) and allowed (MAY) attributes.

Example 6.1. person Object Class Schema Entry

objectClasses: ( 2.5.6.6 NAME 'person' DESC 'Standard LDAP objectclass' SUP top MUST ( sn $ cn ) MAY ( description $ seeAlso $ telephoneNumber $ userPassword ) X-ORIGIN 'RFC 2256' )

Every object class defines a number of required attributes and of allowed attributes. Required attributes must be present in entries using the specified object class, while allowed attributes are permissible and available for the entry to use, but are not required for the entry to be valid.
As in Example 6.1, “person Object Class Schema Entry”, the person object class requires the cn, sn, and objectClass attributes and allows the description, seeAlso, telephoneNumber, and userPassword attributes.
An object class can inherit attributes from another class, in addition to its own required and allowed attributes. The second object class is the superior or parent object class of the first.
For example, a user's entry has to have the inetOrgPerson object class. In that case, the entry must also include the superior object class for inetOrgPerson, organizationalPerson, and the superior object class for organizationalPerson, which is person:
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson

6.1.3. Attributes

Directory entries are composed of attributes and their values. These pairs are called attribute-value assertions or AVAs. Any piece of information in the directory is associated with a descriptive attribute. For instance, the cn attribute is used to store a person's full name, such as cn: John Smith.
Additional attributes can supply additional information about John Smith:
givenname: John
surname: Smith
mail: jsmith@example.com
In a schema file, an attribute is identified by the attributetypes line, then followed by its OID, name, a description, syntax (allowed format for its value), optionally whether the attribute is single- or multi-valued, and where the attribute is defined.

Example 6.2. description Attribute Schema Entry

attributetypes: ( 2.5.4.13 NAME 'description' DESC 'Standard LDAP attribute type' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'RFC 2256' )

6.1.4. Extending the Schema

New, custom attributes and object classes can be added to a Directory Server instance to extend the schema, and there are several ways to add schema elements. Using the Directory Server Console or LDAP tools adds schema elements to the default custom schema file for an instance, 99user.ldif. It is also possible to create a new, separate schema file and include it with the default schema files.
Adding new schema elements requires three things:
  1. Planning and defining OIDs for the new schema. Schema elements are recognized by the server by their OID, so it is important for the OIDs to be unique and organized. Directory Server itself does not manage OIDs, but there are some best practices described in Section 6.2, “Managing Object Identifiers”.
  2. Create the new attributes. Attribute definitions require a name, a syntax (the allowed format of the values), an OID, and a description of whether the attribute can only be used once per entry or multiple times.
  3. Create an object class to contain the new attributes. An object class lists the required attributes for that entry type and the allowed (permissible) attributes. Because the default schema should never be altered, if any new attributes are created, then they should be added to a custom object class.
The schema elements should be planned in advance; do not use multiple attributes for the same information. Whenever possible, use the standard Directory Server schema. Directory Server has hundreds of attributes and dozens of object classes defined in the default schema files. The Directory Server Schema Reference lists and describes the standard attributes and object classes; all of the schema can be viewed in the Directory Server Console or read in the schema files in /etc/dirsrv/slapd-instance_name/schema. Become familiar with the available schema; then plan what information attributes are missing and how best to fill those gaps with custom attributes. Planning the schema is covered in the Deployment Guide.

CAUTION

The default object classes and attributes in Directory Server are based on LDAP and X.500 standards and RFCs. Using standard schema makes the Directory Server more easily integrated with other applications and servers and allows interoperability with LDAP clients, legacy Directory Server instances, and future release. It is inadvisable for you to edit the standard attributes or change the object classes.
Keep the following rules in mind when customizing the Directory Server schema:
  • Keep the schema as simple as possible.
  • Reuse existing schema elements whenever possible.
  • Minimize the number of mandatory attributes defined for each object class.
  • Do not define more than one object class or attribute for the same purpose.
  • Do not modify any existing definitions of attributes or object classes.

NOTE

Never delete or replace the standard schema. Doing so can lead to compatibility problems with other directories or other LDAP client applications.
The schema is loaded into the Directory Server instance when the instance is started; any new schema files are not loaded until the Directory Server is restarted or unless a reload task is initiated. Always, any custom schema is loaded before the standard schema.

6.1.5. Schema Replication

Schema elements are replicated by default whenever the schema is changed in the Directory Server Console or through ldapmodify because the changes are logged in the server change log. However, replicated schema elements are all copied to 99user.ldif regardless of what schema file held the schema on the supplier server, so replication can lead to multiple files defining the same schema.
To keep from having duplicate schema definitions in multiple files, and for the easiest maintenance of the schema, keep all custom schema in the default custom schema file, 99user.ldif in /etc/dirsrv/slapd-instance_name/schema.
When new schema files are added to the server and loaded dynamically into the Directory Server, the schema is only loaded locally because the schema reload operation is a local task. Since the changes do not show up in the changelog, these newly-loaded schema files are not replicated. In order to load those schema files on any other servers, the schema has to be copied over, and then a local reload task has to be run.

6.2. Managing Object Identifiers

Each LDAP object class or attribute must be assigned a unique name and object identifier (OID). An OID is a dot-separated number which identifies the schema element to the server. OIDs can be hierarchical, with a base OID that can be expanded to accommodate different branches. For example, the base OID could be 1, and there can be a branch for attributes at 1.1 and for object classes at 1.2.

NOTE

It is not required to have a numeric OID for creating custom schema, but Red Hat strongly recommends it for better forward compatibility and performance.
OIDs are assigned to an organization through the Internet Assigned Numbers Authority (IANA), and Directory Server does not provide a mechanism to obtain OIDs. To get information about obtaining OIDs, visit the IANA website at http://www.iana.org/cgi-bin/enterprise.pl.
After obtaining a base OID from IANA, plan how the OIDs are going to be assigned to custom schema elements. Define a branch for both attributes and object classes; there can also be branches for matching rules and LDAP controls.
Once the OID branches are defined, create an OID registry to track OID assignments. An OID registry is a list that gives the OIDs and descriptions of the OIDs used in the directory schema. This ensures that no OID is ever used for more than one purpose. Publish the OID registry with the custom schema.

6.3. Directory Server Attribute Syntaxes

The attribute's syntax defines the format of the values which the attribute allows; as with other schema elements, the syntax is defined for an attribute using the syntax's OID in the schema file entry. In the Directory Server Console, the syntax is referenced by its friendly name.
The Directory Server uses the attribute's syntax to perform sorting and pattern matching on entries.
For more information about LDAP attribute syntaxes, see RFC 4517.

Table 6.1. Supported LDAP Attribute Syntaxes

Name OID Definition
Binary 1.3.6.1.4.1.1466.115.121.1.5 For values which are binary.
Bitstring 1.3.6.1.4.1.1466.115.121.1.6 For values which are bitstings. This is supported for searches which require accessing attributes using bitstring flags.
Boolean 1.3.6.1.4.1.1466.115.121.1.7 For attributes with only two allowed values, true or false.
Country String 1.3.6.1.4.1.1466.115.121.1.11 For values which are limited to exactly two printable string characters; for example, US for the United States.
DN 1.3.6.1.4.1.1466.115.121.1.12 For values which are DNs.
Delivery Method 1.3.6.1.4.1.1466.115.121.1.14 For values which are contained a preferred method of delivering information or contacting an entity. The different values are separated by a dollar sign ($). For example:
telephone $ physical
DirectoryString (Case-Insensitive String) 1.3.6.1.4.1.1466.115.121.1.15 For values which are case-insensitive strings.
Enhanced Guide 1.3.6.1.4.1.1466.115.121.1.21 For values which contain complex search parameters based on attributes and filters.
Facsimile 1.3.6.1.4.1.1466.115.121.1.22 For values which contain fax numbers.
Fax 1.3.6.1.4.1.1466.115.121.1.23 For values which contain the images of transmitted faxes.
GeneralizedTime 1.3.6.1.4.1.1466.115.121.1.24 For values which are encoded as printable strings. The time zone must be specified. It is strongly recommended to use GMT time.
Guide 1.3.6.1.4.1.1466.115.121.1.25 Obsolete. For values which contain complex search parameters based on attributes and filters.
IA5String (Case-Exact String) 1.3.6.1.4.1.1466.115.121.1.26 For values which are case-exact strings.
Integer 1.3.6.1.4.1.1466.115.121.1.27 For values which are whole numbers.
JPEG 1.3.6.1.4.1.1466.115.121.1.28 For values which contain image data.
Name and Optional UID 1.3.6.1.4.1.1466.115.121.1.34 For values which contain a combination value of a DN and (optional) unique ID.
Numeric String 1.3.6.1.4.1.1466.115.121.1.36 For values which contain a string of both numerals and spaces.
OctetString 1.3.6.1.4.1.1466.115.121.1.40 For values which are binary; this is the same as using the binary syntax.
OID 1.3.6.1.4.1.1466.115.121.1.37 For values which contain an object identifier (OID).
Postal Address 1.3.6.1.4.1.1466.115.121.1.41 For values which are encoded in the format postal-address = dstring * ("$" dstring). For example:
1234 Main St.$Raleigh, NC 12345$USA
Each dstring component is encoded as a DirectoryString value. Backslashes and dollar characters, if they occur, are quoted, so that they will not be mistaken for line delimiters. Many servers limit the postal address to 6 lines of up to thirty characters.
PrintableString 1.3.6.1.4.1.1466.115.121.1.58 For values which contain strings containing alphabetic, numeral, and select punctuation characters (as defined in RFC 4517).
Space-Insensitive String 2.16.840.1.113730.3.7.1 For values which contain space-insensitive strings.
TelephoneNumber 1.3.6.1.4.1.1466.115.121.1.50 For values which are in the form of telephone numbers. It is recommended to use telephone numbers in international form.
Teletex Terminal Identifier 1.3.6.1.4.1.1466.115.121.1.51 For values which contain an international telephone number.
Telex Number 1.3.6.1.4.1.1466.115.121.1.52 For values which contain a telex number, country code, and answerback code of a telex terminal.
URI For values in the form of a URL, introduced by a string such as http://, https://, ftp://, ldap://, and ldaps://. The URI has the same behavior as IA5String. See RFC 4517 for more information on this syntax.

6.4. Managing Custom Schema in the Console

The Directory Server Console shows all attributes in the schema, and custom attributes can be created, edited, and deleted from the schema.

6.4.1. Viewing Attributes and Object Classes

All of the information about the attributes and object classes which are currently loaded in the server instance are visible with the other server configuration.
  1. In the Directory Server Console, select the Configuration tab.
  2. In the left navigation tree, select the Schema folder.
  3. There are three tabs which display the schema elements loaded in Directory Server: Object Class, Attributes, and Matching Rules.
The Attributes tab is broken into two sections for default and custom attributes. Both sections show the attribute name, OID, syntax, and whether the attribute is multi-valued.
The Object Classes tab shows the list of object classes on the left. When an object class is highlighted, its OID and superior object class are listed in the fields at the top and its required and allowed attributes are listed in the boxes on the right.

6.4.2. Creating Attributes

NOTE

After adding new attributes to the schema, create a new object class to contain them, as described in Section 6.4.3, “Creating Object Classes”.
  1. Select the Configuration tab.
  2. In the left navigation tree, select the Schema folder, and then select the Attributes tab in the right pane.
  3. Click Create.
  4. Fill in the information for the new attribute.
    • The attribute name; this must be unique.
    • The OID; this is not required, but for compatibility and server performance, assigning a unique numeric OID is strongly recommended.
    • The syntax; this is the allowed format for the attributes values.
    • Whether the attribute is multi-valued; by default, all attributes can be used more than once in an entry, but deselecting the checkbox means the attribute can be used only once.
  5. Click OK.

6.4.3. Creating Object Classes

A new object class must be created with a unique name, a parent object, and required and optional attributes. To create an object class:
  1. In the Directory Server Console, select the Configuration tab.
  2. In the navigation tree, select the Schema folder, and then select the Object Classes tab in the right pane.
  3. Click the Create button in the Object Classes tab.
  4. Fill in the information about the new object class.
    • The name; this must be unique.
    • The OID; this is not required, but for compatibility and server performance, assigning a unique numeric OID is strongly recommended.
    • The superior object class for the entry. The default is top; selecting another object class means that the new object class inherits all of the required and allowed attributes from the parent, in addition to its own defined attributes.
    • Required and allowed attributes. Select the attributes on the left and used the Add buttons by the Available Attributes and Required Attributes boxes to add the attributes as appropriate.

    NOTE

    Attributes that are inherited from the parent object classes cannot be removed, regardless of whether they are allowed or required.
  5. Click OK to save the new object class.

6.4.4. Editing Custom Schema Elements

Only user-created attributes or object classes can be edited; standard schema elements cannot be edited.
  1. In the Directory Server Console, select the Configuration tab.
  2. In the left navigation tree, select the Schema folder.
  3. Open the Object Classes or Attributes tab.
  4. Select the schema element to edit from the list. Only custom (user-defined) schema can be edited in the Directory Server Console.
  5. Click the Edit button at the bottom of the window.
  6. Edit any of the schema information.

6.4.5. Deleting Schema

Only user-created attributes or object classes can be deleted; standard schema elements cannot be deleted.
  1. In the Directory Server Console, select the Configuration tab.
  2. In the left navigation tree, select the Schema folder.
  3. Open the Object Classes or Attributes tab.
  4. Select the schema element to delete from the list. Only custom (user-defined) schema can be deleted in the Directory Server Console.
  5. Click the Delete button at the bottom of the window.
  6. Confirm the deletion.

WARNING

The server immediately deletes the schema element. There is no undo.

6.5. Managing Schema Using ldapmodify

As with the Directory Server Console, ldapmodify can be used to add, edit, and delete custom schema elements. ldapmodify also modifies the default custom schema file for a Directory Server instance, 99user.ldif.

6.5.1. Creating Attributes

A custom attribute entry is itself an attributetypes entry for the cn=schema entry. The attributetypes attribute has the format:
attributetypes: ( definition )
The definition contains five components:
  • An OID, usually a dot-separated number
  • A unique name, in the form NAME name
  • A description, in the form DESC description
  • The OID for the syntax of the attribute values, listed in Table 6.1, “Supported LDAP Attribute Syntaxes”, in the form SYNTAX OID
  • Optionally, the source where the attribute is defined
The attribute definition is added to the custom schema file, 99user.ldif, by by running an LDAP command and modifying the cn=schema entry. For example:
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -v

dn: cn=schema
changetype: modify
add: attributetypes
attributetypes: ( 1.2.3.4.5.6.1 NAME 'dateofbirth' DESC 'For employee birthdays' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUED X-ORIGIN 'Example defined')

6.5.2. Creating Object Classes

An object class definition is an objectclasses attribute for the cn=schema entry. The objectclasses attribute has the format:
objectclasses: ( definition )
The object class definition contains several components:
  • An OID, usually a dot-separated number
  • A unique name, in the form NAME name
  • A description, in the form DESC description
  • The superior, or parent, object class for this object class, in the form SUP object_class; if there is no related parent, use SUP top
  • The word AUXILIARY, which gives the type of entry to which the object class applies; AUXILIARY means it can apply to any entry
  • A list of required attributes, preceded by the word MUST; to include multiple attributes, enclose the group in parentheses and separate with attributes with dollar signs ($)
  • A list of allowed attributes, preceded by the word MAY; to include multiple attributes, enclose the group in parentheses and separate with attributes with dollar signs ($)
The object class definition is added to the custom schema file, 99user.ldif, by by running an LDAP command and modifying the cn=schema entry. For example:
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com -v

dn: cn=schema
changetype: modify
add: objectclasses
objectclasses: ( 2.16.840.1133730.2.123 NAME 'examplePerson' DESC 'Example Person Object Class' SUP inetOrgPerson AUXILIARY  MUST cn MAY (exampleDateOfBirth $ examplePreferredOS) )

6.5.3. Deleting Schema

WARNING

Never delete default schema elements. Those are required by the Directory Server to run.
  1. Remove the unwanted attributes from any entries which use them, then from any object classes in the schema file which accept that attribute. Likewise, to remove an object class, remove it from any entries.
  2. Run ldapmodify to remove the attribute. For example:
    /usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com
    
    dn: cn=schema 
    changetype: modify 
    delete: objectclasses
    objectclasses: ( 2.16.840.1133730.2.123 NAME 'examplePerson' DESC 'Example Person Object Class' SUP inetOrgPerson AUXILIARY MUST cn MAY (exampleDateOfBirth $ examplePreferredOS) )

    CAUTION

    Be sure to specify the exact object class or attribute to remove; using only the attributetypes or objectclasses attribute without the value will delete every user-defined attribute or object class in the file.
If the custom attribute or object class is in a custom schema file other than 99user.ldif, edit the file directly. Neither the Directory Server Console nor LDAP tools can edit a schema file other than 99user.ldif.

6.6. Creating Custom Schema Files

Schema files are simple LDIF files which define the cn=schema entry. Each attribute and object class is added as an attribute to that entry. Here are the requirements for creating a schema file:
  • The first line must be dn: cn=schema.
  • The schema file can include both attributes and object classes, but it can also include only one or the other.
  • If both attributes and object classes are defined in the style, all of the attributes must be listed in the file first, then all of the attributes must be listed first, then the object classes.
  • The object classes can use attributes defined in other schema files.
  • The file must be named in the format [1-9][0-9]text.ldif.
    The file must always begin with two numbers. Numerically, the schema file cannot be loaded after the core configuration schema (which begin with 00 and 01).
    Also, the Directory Server always writes its custom schema to the numerically and alphabetically highest named schema file in the schema directory. It expects this file to be 99user.ldif. If this file is not 99user.ldif, the server can experience problems. So, always make sure custom schema files are at least alphabetically lower than 99user.ldif. The name 99alpha.ldif is okay; the name 99zzz.ldif is not.
Practices for creating schema files are described in more detail in the Deployment Guide.
Attributes are defined in the schema file as attributetypes attributes to the schema, with five components:
  • An OID, usually a dot-separated number
  • A unique name, in the form NAME name
  • A description, in the form DESC description
  • The OID for the syntax of the attribute values, listed in Table 6.1, “Supported LDAP Attribute Syntaxes”, in the form SYNTAX OID
  • Optionally, the source where the attribute is defined
For example:
attributetypes: ( 1.2.3.4.5.6.1 NAME 'dateofbirth' DESC 'For employee birthdays' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUED X-ORIGIN 'Example defined')
Likewise, object classes are defined as objectclasses attributes, although there is slightly more flexibility in how the object class is defined. The only required configurations are the name and OID for the object class; all other configuration depends on the needs for the object class:
  • An OID, usually a dot-separated number
  • A unique name, in the form NAME name
  • A description, in the form DESC description
  • The superior, or parent, object class for this object class, in the form SUP object_class; if there is no related parent, use SUP top
  • The word AUXILIARY, which gives the type of entry to which the object class applies; AUXILIARY means it can apply to any entry
  • A list of required attributes, preceded by the word MUST; to include multiple attributes, enclose the group in parentheses and separate with attributes with dollar signs ($)
  • A list of allowed attributes, preceded by the word MAY; to include multiple attributes, enclose the group in parentheses and separate with attributes with dollar signs ($)
For example:
objectclasses: ( 2.16.840.1133730.2.123 NAME 'examplePerson' DESC 'Example Person Object Class' SUP inetOrgPerson AUXILIARY  MUST cn MAY (exampleDateOfBirth $ examplePreferredOS) )
Example 6.3, “Example Schema File” shows a simplified schema file.

Example 6.3. Example Schema File

dn: cn=schema
attributetypes: ( 2.16.840.1133730.1.123 NAME 'dateofbirth' DESC 'For employee birthdays' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'Example defined')
objectclasses: ( 2.16.840.1133730.2.123 NAME 'examplePerson' DESC 'Example Person Object Class' SUP inetOrgPerson AUXILIARY MAY (dateofbirth) )

Custom schema files should be added to the Directory Server instance's schema directory, /etc/dirsrv/slapd-instance_name/schema. The schema in these files are not loaded and available to the server unless the server is restarted or a dynamic reload task is run.

6.7. Dynamically Reloading Schema

By default, the schema files used by the Directory Server instance are loaded into the directory when it is started. This means that any new schema files added to the schema directory are not available for use unless the server is restarted. The Directory Server has a task which manually reloads the full schema for the Directory Server instance, including custom files, without requiring a server restart.
The schema reload task can be initiated in two ways:
  • Using the schema-reload.pl script
  • Adding a cn=schema reload task entry using ldapmodify

6.7.1. Reloading Schema Using schema-reload.pl

The schema-reload.pl script launches a special task to reload all of the schema files used by a specific Directory Server instance. This allows custom schema files to be loaded dynamically without having to add schema elements to 99user.ldif.
  1. Open the tool directory for the Directory Server instance, /usr/lib/dirsrv/slapd-instance_name/.
  2. Run the script, binding as the Directory Manager.
    ./schema-reload.pl -D "cn=Directory Manager" -w secret
    The Directory Server responds that it has added the new reload task entry.
    adding new entry cn=schema_reload_2009_1_6_17_52_4,cn=schema reload task,cn=tasks,cn=config
    This reloads the schema from the default schema directory, /etc/dirsrv/slapd-instance_name/schema, which is recommended. It is also possible to specify a different directory using the -d option.
    ./schema-reload.pl -D "cn=Directory Manager" -w password -d /export/custom-schema

    IMPORTANT

    All of the schema is reloaded with the schema reload task, not just the newest schema or modified schema. This means that whatever directory is specified should contain the full schema for the Directory Server, or the Directory Server instance may have serious performance problems.
The schema-reload.pl is described in more detail in the Configuration and Command-Line Tool Reference.

6.7.2. Reloading Schema Using ldapmodify

The schema-reload.pl script creates a special task entry in a Directory Server instance which reloads schema files; it is also possible to reload schema by creating the task entry directly. Task entries occur under the cn=tasks configuration entry in the dse.ldif file, so it is also possible to initiate a task by adding the entry using ldapmodify. As soon as the task is complete, the entry is removed from the directory.
To initiate a schema reload task, add an entry under the cn=schema reload task,cn=tasks,cn=config entry. The only required attribute is the cn for the specific task.
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=example schema reload,cn=schema reload task,cn=tasks,cn=config
objectclass: extensibleObject
cn:example schema reload
The default schema directory from which the Directory Server instance reloads the schema is in /etc/dirsrv/slapd-instance_name/schema; it is possible to specify a different schema directory using the schemadir attribute, which is analogous to the -d option with schema-reload.pl.
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=example schema reload,cn=schema reload task,cn=tasks,cn=config
objectclass: extensibleObject
cn:example schema reload
schemadir: /export/schema

IMPORTANT

All of the schema is reloaded with the schema reload task, not just the newest schema or modified schema. This means that whatever directory is specified should contain the full schema for the Directory Server, or the Directory Server instance may have serious performance problems.
As soon as the task is completed, the entry is deleted from the dse.ldif configuration, so it is possible to reuse the same task entry continually.
The cn=schema reload task configuration is described in more detail in the Configuration and Command-Line Tool Reference.

6.7.3. Reloading Schema with Replication

The schema reload task is a local operation, so schema changes are not replicated in a multi-master environment if the schema is added to one supplier but not to the others. To load the new schema files on all of the supplier servers:
  1. Stop replication.
  2. Copy the new schema file over and run the schema reload task for every supplier and replica server.
  3. Restart replication.

6.7.4. Schema Reload Errors

When the schema reload task runs, the command prompt only shows that the task is initiated.
adding new entry cn=schema reload task 1, cn=schema reload task, cn=tasks, cn=config
However, the task does not return whether it completed successfully. To verify the schema reload operation was successful, check the error logs. The schema reload has two tasks, first validating the schema file and then loading it.
A success message shows that the validation passed and the task finished.
[06/Jan/2009:17:52:04 -0500] schemareload - Schema reload task starts (schema dir: default) ...
[06/Jan/2009:17:52:04 -0500] schemareload - Schema validation passed.
[06/Jan/2009:17:52:04 -0500] schemareload - Schema reload task finished.
If there is a failure, then the logs show which step failed and why.
[..] schemareload - Schema reload task starts (schema dir: /bogus) ...
[..] schema - No schema files were found in the directory /bogus
[..] schema_reload - schema file validation failed
[..] schemareload - Schema validation failed.

6.8. Turning Schema Checking On and Off

When schema checking is on, the Directory Server ensures three things:
  • The object classes and attributes using are defined in the directory schema.
  • The attributes required for an object class are contained in the entry.
  • Only attributes allowed by the object class are contained in the entry.
Schema checking is turned on by default in the Directory Server, and the Directory Server should always run with schema checking turned on. The only situation where is may be beneficial to turn schema checking off is to accelerate LDAP import operations. However, there is a risk of importing entries that do not conform to the schema. Consequently, it is impossible to search for these entries.
  1. In the Directory Server Console, select the Configuration tab.
  2. Highlight the server icon at the top of the navigation tree, then select the Settings tab in the right pane.
  3. To enable schema checking, check the Enable Schema Checking checkbox; clear it to turn off schema checking.
  4. Click Save.
To turn schema checking on and off using LDAP commands, edit the value of the nsslapd-schemacheck attribute. For example:
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=config 
changetype: modify 
replace: nsslapd-schemacheck: on 
nsslapd-schemacheck: off
For information, see the Directory Server Configuration and Command-Line Tool Reference.

6.9. Using Syntax Validation

With syntax validation, the Directory Server checks that the value of an attribute follows the rules of the syntax given in the definition for that attribute. For example, syntax validation will confirm that a new telephoneNumber attribute actually has a valid telephone number for its value.

6.9.1. About Syntax Validation

As with schema checking, validation reviews any directory modification and rejects changes that violate the syntax. Additional settings can be optionally configured so that syntax validation can log warning messages about syntax violations and then either reject the modification or allow the modification process to succeed.
This feature validates all attribute syntaxes, with the exception of binary syntaxes (which cannot be verified) and non-standard syntaxes, which do not have a defined required format. The syntaxes are validated against RFC 4514.

6.9.2. Syntax Validation and Other Directory Server Operations

Syntax validation is mainly relevant for standard LDAP operations like creating entries (add) or editing attributes (modify). Validating attribute syntax can impact other Directory Server operations, however.
Database Encryption
For normal LDAP operations, an attribute is encrypted just before the value is written to the database. This means That encryption occurs after the attribute syntax is validated.
Encrypted databases (as described in Section 2.2.3, “Configuring Attribute Encryption”) can be exported and imported. Normally, it is strongly recommended that these export and import operations are done with the -E flag with db2ldif and ldif2db, which allows syntax validation to occur just fine for the import operation. However, if the encrypted database is exported without using the -E flag (which is not supported), then an LDIF with encrypted values is created. When this LDIF is then imported, the encrypted attributes cannot be validated, a warning is logged, and attribute validation is skipped in the imported entry.
Synchronization
There may be differences in the allowed or enforced syntaxes for attributes in Windows Active Directory entries and Red Hat Directory Server entries. In that case, the Active Directory values could not be properly synced over because syntax validation enforces the RFC standards in the Directory Server entries.
Replication
If the Directory Server 8.2 instance is a supplier which replicates its changes to a consumer, then there is no issue with using syntax validation. However, if the supplier in replication is an older version of Directory Server or has syntax validation disabled, then syntax validation should not be used on the 8.2 consumer because the Directory Server 8.2 consumer may reject attribute values that the master allows.

6.9.3. Enabling or Disabling Syntax Validation

Syntax validation is configured by the nsslapd-syntaxcheck attribute. The value of this attribute is either on or off (by default, this is on). To change the syntax validation, modify this attribute using ldapmodify or by editing the dse.ldif file directly.
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389

dn: cn=config
changetype: modify
replace: nsslapd-syntaxcheck
nsslapd-syntaxcheck: off

TIP

If syntax validation is disabled, then run the syntax-validate.pl script to audit existing attribute values before re-enabling syntax validation. See Section 6.9.6, “Validating the Syntax of Existing Attribute Values”.

6.9.4. Enabling Strict Syntax Validation for DNs

When syntax validation is enabled, DNs are validated against RFC 4514, as are other attribte syntaxes. However, DN syntax validation is enabled separately because the strictness of later standards can invalidate old-style DNs, and therefore directory trees.
Syntax validation checks DNs against section 3 in RFC 4514.
The value of this attribute is either on or off (by default, this is off). To change the syntax validation, modify this attribute using ldapmodify or by editing the dse.ldif file directly.
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389
 	  	 
dn: cn=config
changetype: modify
replace: nsslapd-dn-validate-strict
nsslapd-dn-validate-strict: on
If strict DN validation is enabled and a DN value does not conform to the required syntax, then the operation fails with LDAP result code 34, INVALID_DN_SYNTAX.

TIP

If a DN contains a nested DN, then the syntax validation checks not only the DN, but it looks up and normalizes the nested DN as well. This can affect performance in some situations, because a single validation can result in multiple lookup and normalization operations.
To disable checking on the nested DNs, turn off the nsslapd-normalize-nested-dn attribute. The primary DN will be validated and normalized as expected.

6.9.5. Enabling Syntax Validation Warnings (Logging)

By default, syntax validation rejects any add or modify operations where an attribute value violates the required syntax. However, the violation itself is not recorded to the errors log by default. The nsslapd-syntaxlogging attribute enables error logging for any syntax violations.

NOTE

Syntax violations discovered by the syntax validation script and task are logged in the Directory Server error log.
If nsslapd-syntaxlogging and nsslapd-syntaxcheck are both enabled, then any invalid attribute modification is rejected and the message written to the log. If nsslapd-syntaxlogging is enabled but nsslapd-syntaxcheck is disabled, then the operation is allowed to succeed, but the warning message is still written to the error log.
The value of this attribute is either on or off (by default, this is off). To enable syntax validation logging, edit the attribute using ldapmodify or by editing the dse.ldif file directly.
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389

dn: cn=config
changetype: modify
replace: nsslapd-syntaxlogging
nsslapd-syntaxlogging: on

6.9.6. Validating the Syntax of Existing Attribute Values

Syntax validation checks every modification to attributes to make sure that the new value has the required syntax for that attribute type. However, syntax validation only audits changes to attribute values, such as when an attribute is added or modified. It does not validate the syntax of existing attribute values.
Validation of existing attribute values can be done with the syntax validation script. This script checks entries under a specified subtree (in the -b option) and, optionally, only entries which match a specified filter (in the -f option). For example:
/usr/lib64/dirsrv/instance_name/syntax-validate.pl -D "cn=directory manager" -w secret -b "ou=people,dc=example,dc=com" -f "objectclass=inetorgperson)"
Any syntax violations in existing attribute values can be identified and corrected through this script.

TIP

If syntax validation is disabled or if a server is migrated, then there may be data in the server which does not conform to attribute syntax requirements. The syntax validation script can be run to evaluate those existing attribute values before enabling syntax validation.
Alternately, a task can be launched to initiate syntax validation, specifying the required base DN and, optionally, LDAP search filter.
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=example, cn=syntax validation,cn=tasks,cn=config
objectclass: extensibleObject
cn:example
basedn: ou=people,dc=example,dc=com
filter: "(objectclass=inetorgperson)"

Chapter 7. Managing Indexes

Indexing makes searching for and retrieving information easier by classifying and organizing attributes or values. This chapter describes the searching algorithm itself, placing indexing mechanisms in context, and then describes how to create, delete, and manage indexes.

7.1. About Indexes

This section provides an overview of indexing in Directory Server. It contains the following topics:

7.1.1. About Index Types

Indexes are stored in files in the directory's databases. The names of the files are based on the indexed attribute, not the type of index contained in the file. Each index file may contain multiple types of indexes if multiple indexes are maintained for the specific attribute. For example, all indexes maintained for the common name attribute are contained in the cn.db4 file.
Directory Server supports the following types of index:
  • Presence index (pres) contains a list of the entries that contain a particular attribute, which is very useful for searched. For example, it makes it easy to examine any entries that contain access control information. Generating an aci.db4 file that includes a presence index efficiently performs the search for ACI=* to generate the access control list for the server.
    The presence index is not used for base object searches.
  • Equality index (eq) improves searches for entries containing a specific attribute value. For example, an equality index on the cn attribute allows a user to perform the search for cn=Babs Jensen far more efficiently.
  • Approximate index (approx) is used for efficient approximate or sounds-like searches. For example, an entry may include the attribute value cn=Robert E Lee. An approximate search would return this value for searches against cn~=Robert Lee, cn~=Robert, or cn~=Lee. Similarly, a search against l~=San Fransisco (note the misspelling) would return entries including l=San Francisco.
  • Substring index (sub) is a costly index to maintain, but it allows efficient searching against substrings within entries. Substring indexes are limited to a minimum of three characters for each entry.
    For example, searches of the form cn=*derson , match the common names containing strings such as Bill Anderson, Jill Henderson, or Steve Sanderson. Similarly, the search for telephoneNumber= *555* returns all the entries in the directory with telephone numbers that contain 555.
  • International index speeds up searches for information in international directories. The process for creating an international index is similar to the process for creating regular indexes, except that it applies a matching rule by associating an object identifier (OID) with the attributes to be indexed.
    The supported locales and their associated OIDs are listed in Appendix C, Internationalization. If there is a need to configure the Directory Server to accept additional matching rules, contact Red Hat Professional Services.
  • Browsing index, or virtual list view (VLV) index, speeds up the display of entries in the Directory Server Console. This index is particularly useful if a branch of your directory contains hundreds of entries; for example, the ou=people branch. You can create a browsing index on any branch point in the directory tree to improve display performance through the Directory Server Console or by using the vlvindex command-line tool, which is explained in the Directory Server Configuration and Command-Line Tool Reference.

7.1.2. About Default, System, and Standard Indexes

When you install Directory Server, a set of default and system indexes is created per database instance. To maintain these indexes, the directory uses standard indexes.

7.1.2.1. Overview of Default Indexes

The default indexes can be modified depending on the directory indexing needs. Always ensure that no server plug-ins or other servers depend on a default index before removing it.
Table 7.1, “Default Indexes” lists the default indexes installed with the directory.

Table 7.1. Default Indexes

Attribute Eq Pres Sub Purpose
cn Improves the performance of the most common types of user directory searches.
givenname Improves the performance of the most common types of user directory searches.
mail Improves the performance of the most common types of user directory searches.
mailHost Used by a messaging server.
member Improves Directory Server performance. This index is also used by the Referential Integrity Plug-in. See Section 3.5, “Maintaining Referential Integrity” for more information.
owner Improves Directory Server performance. This index is also used by the Referential Integrity Plug-in. See Section 3.5, “Maintaining Referential Integrity” for more information.
see Also Improves Directory Server performance. This index is also used by the Referential Integrity Plug-in. See Section 3.5, “Maintaining Referential Integrity” for more information.
sn Improves the performance of the most common types of user directory searches.
telephoneNumber Improves the performance of the most common types of user directory searches.
uid Improves Directory Server performance.
unique member Improves Directory Server performance. This index is also used by the Referential Integrity Plug-in. See Section 3.5, “Maintaining Referential Integrity” for more information.

7.1.2.2. Overview of System Indexes

System indexes cannot be deleted or modified. They are required by the directory to function properly. Table 7.2, “System Indexes” lists the system indexes included with the directory.

Table 7.2. System Indexes

Attribute Eq Pres Purpose
aci Allows the Directory Server to quickly obtain the access control information maintained in the database.
objectClass Used to help accelerate subtree searches in the directory.
entryDN Speeds up entry retrieval based on DN searches.
parentID Enhances directory performance during one-level searches.
numSubordinates Used by the Directory Server Console to enhance display performance on the Directory tab.
nsUniqueID Used to search for specific entries.

7.1.2.3. Overview of Standard Indexes

Because of the need to maintain default indexes and other internal indexing mechanisms, the Directory Server also maintains certain standard index files. The standard index, id2entry.db4, exists by default in Directory Server; you do not need to generate it.
The id2entry.db4 contains the actual directory database entries. All other database files can be recreated from this one.

7.1.3. Overview of the Searching Algorithm

Indexes are used to speed up searches. To understand how the directory uses indexes, it helps to understand the searching algorithm. Each index contains a list of attributes (such as the cn, common name, attribute) and a pointer to the entries corresponding to each value. Directory Serverprocesses a search request as follows:
  1. An LDAP client application sends a search request to the directory.
  2. The directory examines the incoming request to make sure that the specified base DN matches a suffix contained by one or more of its databases or database links.
    • If they do match, the directory processes the request.
    • If they do not match, the directory returns an error to the client indicating that the suffix does not match. If a referral has been specified in the nsslapd-referral attribute under cn=config, the directory also returns the LDAP URL where the client can attempt to pursue the request.
    • If the search request for each database attribute can be satisfied by a single index, then the server reads that index to generate a list of potential matches.
    • If there is no index for the attribute, the directory generates a candidate list that includes all entries in the database, which makes the search considerably slower.
    • If a search request contains multiple attributes, the directory consults multiple indexes and then combines the resulting lists of candidate entries.
    • If there is an index for the attribute, the directory takes the candidate matches from the index files in the form of a series of entry ID numbers.
  3. The directory uses the returned entry ID numbers to read the corresponding entries from the id2entry.db4 file. The Directory Server then examines each of the candidate entries to see if any match the search criteria. The directory returns matching entries to the client as each is found.
    The directory continues until either it has examined all candidate entries or it reaches the limit set in one of the following attributes:
    • nsslapd-sizelimit which specifies the maximum number of entries to return from a search operation. If this limit is reached, the directory returns any entries it has located that match the search request, as well as an exceeded size limit error.
    • nsslapd-timelimit which specifies the maximum number of seconds allocated for a search request. If this limit is reached, the directory returns any entries it has located that match the search request, as well as an exceeded time limit error.
    • nsslapd-lookthroughlimit, which specifies the maximum number of entries that the directory will check when examining candidate entries in response to a search request.
    • nsslapd-idlistscanlimit which specifies the maximum number of entries in an ID list before the list is considered to equal the entire database.
    See Directory Server Configuration and Command-Line Tool Reference for further information about these attributes.

7.1.4. Approximate Searches

In addition, the directory uses a variation of the metaphone phonetic algorithm to perform searches on an approximate index. Each value is treated as a sequence of words, and a phonetic code is generated for each word.

NOTE

The metaphone phonetic algorithm in Directory Server supports only US-ASCII letters. Therefore, use approximate indexing only with English values.
Values entered on an approximate search are similarly translated into a sequence of phonetic codes. An entry is considered to match a query if both of the following are true:
  • All of the query string codes match the codes generated in the entry string.
  • All of the query string codes are in the same order as the entry string codes.
Name in the Directory (Phonetic Code) Query String (Phonetic code) Match Comments
Alice B Sarette (ALS B SRT) Alice Sarette (ALS SRT) Matches. Codes are specified in the correct order.
Alice Sarrette (ALS SRT) Matches. Codes are specified in the correct order, despite the misspelling of Sarette.
Surette (SRT) Matches. The generated code exists in the original name, despite the misspelling of Sarette.
Bertha Sarette (BR0 SRT) No match. The code BR0 does not exist in the original name.
Sarette, Alice (SRT ALS) No match. The codes are not specified in the correct order.

7.1.5. Indexing Performance

Each index that the directory uses is composed of a table of index keys and matching entry ID lists. This entry ID list is used by the directory to build a list of candidate entries that may match a client application's search request; Section 7.1, “About Indexes” describes each kind of Directory Server index. The Directory Server secondary index structure greatly improves write and search operations.

7.1.5.1. Indexing Performance

While achieving extremely high read performance, in previous versions of Directory Server, write performance was limited by the number of bytes per second that could be written into the storage manager's transaction log file. Large log files were generated for each LDAP write operation; in fact, log file verbosity could easily be 100 times the corresponding number of bytes changed in the Directory Server. The majority of the contents in the log files are related to index changes (ID insert and delete operations).
The secondary index structure was separated into two levels in the old design:
  • The ID list structures, which were the province of the Directory Server backend and opaque to the storage manager.
  • The storage manager structures (Btrees), which were opaque to the Directory Server backend code.
Because it had no insight into the internal structure of the ID lists, the storage manager had to treat ID lists as opaque byte arrays. From the storage manager's perspective, when the content of an ID list changed, the entire list had changed. For a single ID that was inserted or deleted from an ID list, the corresponding number of bytes written to the transaction log was the maximum configured size for that ID list, about 8 kilobytes. Also, every database page on which the list was stored was marked as dirty, since the entire list had changed.
In the redesigned index, the storage manager has visibility into the fine-grain index structure, which optimizes transaction logging so that only the number of bytes actually changed need to be logged for any given index modification. The Berkeley DB provides ID list semantics, which are implemented by the storage manager. The Berkeley API was enhanced to support the insertion and deletion of individual IDs stored against a common key, with support for duplicate keys, and an optimized mechanism for the retrieval of the complete ID list for a given key.
The storage manager has direct knowledge of the application's intent when changes are made to ID lists, resulting in several improvements to ID list handling:
  • For long ID lists, the number of bytes written to the transaction log for any update to the list is significantly reduced, from the maximum ID list size (8 kilobytes) to twice the size of one ID (4 bytes).
  • For short ID lists, storage efficiency, and in most cases performance, is improved because only the storage manager meditate need to be stored, not the ID list metadata.
  • The average number of database pages marked as dirty per ID insert or delete operation is very small because a large number of duplicate keys will fit into each database page.

7.1.5.2. Search Performance

For each entry ID list, there is a size limit that is globally applied to all index keys managed by the server. In previous versions of Directory Server, this limit was called the All IDs Threshold. Because maintaining large ID lists in memory can affect performance, the All IDs Threshold set a limit on how large a single entry ID list could get. When a list hit a certain pre-determined size, the search would treat it as if the index contained the entire directory.
The difficulty in setting the All IDs Threshold hurt performance. If the threshold was too low, too many searches examined every entry in the directory. If it was too high, too many large ID lists had to be maintained in memory.
The problems addressed by the All IDs Threshold are no longer present because of the efficiency of entry insertion, modification, and deletion in the Berkeley DB design. The All IDs Threshold is removed for database write operations, and every ID list is now maintained accurately.
Since loading a long ID list from the database can significantly reduce search performance, the configuration parameter, nsslapd-idlistscanlimit, sets a limit on the number of IDs that are read before a key is considered to match the entire primary index. nsslapd-idlistscanlimit is analogous to the All IDs Threshold, but it only applies to the behavior of the server's search code, not the content of the database.
When the server uses indexes in the processing of a search operation, it is possible that one index key matches a large number of entries. For example, consider a search for objectclass=inetorgperson in a directory that contained one million inetorgperson entries. When the server reads the inetorgperson index key in the objectclass index, it finds one million matching entries. In cases like this, it is more efficient simply to conclude in the index lookup phase of the search operation processing that all the entries in the database match the query. This causes subsequent search processing to scan the entire database content, checking each entry as to whether it matches the search filter. The time required to fetch the index keys is not worthwhile; the search operation is likely to be processed more efficiently by omitting the index lookup.
In Directory Server, when examining an index, if more than a certain number of entries are found, the server stops reading the index and marks the search as unindexed for that particular index.
The threshold number of entries is called the idlistscanlimit and is configured with the nsslapd-idlistscanlimit configuration attribute. The default value is 4000, which is designed to give good performance for a common range of database sizes and access patterns. Typically, it is not necessary to change this value. However, in rare circumstances it may be possible to improve search performance with a different value. For example, lowering the value will improve performance for searches that will otherwise eventually hit the default limit of 4000. This might reduce performance for other searches that benefit from indexing. Conversely, increasing the limit could improve performance for searches that were previously hitting the limit. With a higher limit, these searches could benefit from indexing where previously they did not.
For more information on search limits for the server, refer to Section 7.1.3, “Overview of the Searching Algorithm”.

7.1.5.3. Backwards Compatibility and Migration

While current versions of Directory Server can support the old database design, only the new design is supported for this and later releases of Directory Server.
Upon startup, the server will read the database version from the DBVERSION file, which contains the text Netscape-ldbm/6.2 (old database version), Netscape-ldbm/7.1 (new database format), or bdb/4.2/libback-ldbm (new database format). If the file indicates that the old format is used, then the old code is selected for the database. Because the DBVERSION file stores everything per-backend, it is possible to have different database formats for different individual backends, but the old database format is not recommended.
All databases must be migrated to Directory Server 8.2 when the system is upgraded. Migration is supported for Directory Server 6.x versions, and for releases earlier than version 6.x, dump the databases be dumped, and install Directory Server fresh. Migrating databases is covered in the Directory Server Installation Guide.
Also, the index sizes can be larger than in older releases, so you may want to increase your database cache size. To reconfigure your cache size, look up the nsslapd-dbcachesize entry in the Directory Server Configuration and Command-Line Tool Reference.

7.1.6. Balancing the Benefits of Indexing

Before creating new indexes, balance the benefits of maintaining indexes against the costs.
  • Approximate indexes are not efficient for attributes commonly containing numbers, such as telephone numbers.
  • Substring indexes do not work for binary attributes.
  • Equality indexes should be avoided if the value is big (such as attributes intended to contain photographs or passwords containing encrypted data).
  • Maintaining indexes for attributes not commonly used in a search increases overhead without improving global searching performance.
  • Attributes that are not indexed can still be specified in search requests, although the search performance may be degraded significantly, depending on the type of search.
  • The more indexes you maintain, the more disk space you require.
Indexes can become very time-consuming. For example:
  1. The Directory Server receives an add or modify operation.
  2. The Directory Server examines the indexing attributes to determine whether an index is maintained for the attribute values.
  3. If the created attribute values are indexed, then the Directory Server generates the new index entries.
  4. Once the server completes the indexing, the actual attribute values are created according to the client request.
For example, the Directory Server adds the entry:
dn: cn=John Doe,ou=People,dc=example,dc=com
objectclass: top
objectClass: person
objectClass: orgperson
objectClass: inetorgperson
cn: John Doe
cn: John
sn: Doe
ou: Manufacturing
ou: people
telephoneNumber: 408 555 8834
description: Manufacturing lead for the Z238 line of widgets.
The Directory Server is maintaining the following indexes:
  • Equality, approximate, and substring indexes for cn (common name) and sn (surname) attributes.
  • Equality and substring indexes for the telephone number attribute.
  • Substring indexes for the description attribute.
When adding that entry to the directory, the Directory Server must perform these steps:
  1. Create the cn equality index entry for John and John Doe.
  2. Create the appropriate cn approximate index entries for John and John Doe.
  3. Create the appropriate cn substring index entries for John and John Doe.
  4. Create the sn equality index entry for Doe.
  5. Create the appropriate sn approximate index entry for Doe.
  6. Create the appropriate sn substring index entries for Doe.
  7. Create the telephone number equality index entry for 408 555 8834.
  8. Create the appropriate telephone number substring index entries for 408 555 8834.
  9. Create the appropriate description substring index entries for Manufacturing lead for the Z238 line of widgets. A large number of substring entries are generated for this string.
As this example shows, the number of actions required to create and maintain databases for a large directory can be resource-intensive.

7.2. Creating Standard Indexes

This section describes how to create presence, equality, approximate, substring, and international indexes for specific attributes using the Directory Server Console and the command line.
When a new index type is created, that index is used as a template for any additional databases as they are added. The Directory Server uses the current set of default indexes defined for the instance as the basis for additional databases.
However, new indexes are not added to existing databases automatically, though they can be added manually. This means that if you add a default index to your second database instance, it will not be maintained in your first database instance but will be maintained in any subsequent instances. To apply a new index to an existing database, run the db2index.pl script or run a cn=index,cn=tasks task, as described in Section 7.3, “Applying New Indexes to Existing Databases”.

7.2.1. Creating Indexes from the Server Console

To create presence, equality, approximate, substring, or international indexes:
  1. Select the Configuration tab.
  2. Expand the Data node, expand the suffix of the database to index, and select the database.
  3. Select the Indexes tab in the right pane.

    NOTE

    Do not click the Database Settings node because this opens the Default Index Settings window, not the window for configuring indexes per database.
  4. If the attribute to be indexed is listed in the Additional Indexes table, go to step 6. Otherwise, click Add Attribute to open a dialog box with a list of all of the available attributes in the server schema.
  5. Select the attribute to index, and click OK.
    The server adds the attribute to the Additional Indexes table.
  6. Select the checkbox for each type of index to maintain for each attribute.
  7. To create an index for a language other than English, enter the OID of the collation order to use in the Matching Rules field.
    To index the attribute using multiple languages, list multiple OIDs separated by commas, but no whitespace. For a list of languages, their associated OIDs, and further information regarding collation orders, see Appendix C, Internationalization.
  8. Click Save.
The new index is immediately active for any new data that you add and any existing data in your directory. You do not have to restart your server.

7.2.2. Creating Indexes from the Command Line

NOTE

You cannot create new system indexes because system indexes are hard-coded in Directory Server.
Use ldapmodify [6] to add the new index attributes to your directory.
  • To create a new index that will become one of the default indexes, add the new index attributes to the cn=default indexes,cn=config,cn=ldbm database,cn=plugins,cn=config entry.
  • To create a new index for a particular database, add it to the cn=index,cn=database_name,cn=ldbm database,cn=plugins,cn=config entry, where cn=database_name corresponds to the name of the database.

NOTE

Avoid creating entries under cn=config 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 probably suffer. Although we recommend you do not store simple user entries under cn=config for performance reasons, it can be useful to store special user entries such as the Directory Manager entry or replication manager (supplier bind DN) entry under cn=config since this centralizes configuration information.
For information on the LDIF update statements required to add entries, see Section 3.3, “Using LDIF Update Statements to Create or Modify Entries”.
For example, to create presence, equality, and substring indexes for the sn (surname) attribute in the Example1 database:
  1. Open the Directory Server LDAP tool directory.
    cd /usr/lib64/mozldap
  2. Run ldapmodify.
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
    The ldapmodify utility binds to the server and prepares it to add an entry to the configuration file.
  3. Add the LDIF entry for the new indexes:
    dn: cn=sn,cn=index,cn=Example1,cn=ldbm database,cn=plugins,cn=config
    objectClass:top
    objectClass:nsIndex
    cn:sn
    nsSystemIndex:false
    nsIndexType:pres
    nsIndexType:eq
    nsIndexType:sub
    nsMatchingRule:2.16.840.1.113730.3.3.2.3.1
    The cn attribute contains the name of the attribute to index, in this example the sn attribute. The entry is a member of the nsIndex object class. The nsSystemIndex attribute is false, indicating that the index is not essential to Directory Server operations. The multi-valued nsIndexType attribute specifies the presence (pres), equality (eq) and substring (sub) indexes. Each keyword has to be entered on a separate line. The nsMatchingRule attribute in the example specifies the OID of the Bulgarian collation order; the matching rule can indicate any possible value match, such as languages or other formats like date or integer.
    You can use the keyword none in the nsIndexType attribute to specify that no indexes are to be maintained for the attribute. This example temporarily disables the sn indexes on the Example1 database by changing the nsIndexType to none:
    dn: cn=sn,cn=index,cn=Example1,cn=ldbm database,cn=plugins,cn=config
    objectClass:top 
    objectClass:nsIndex 
    cn:sn 
    nsSystemIndex:false 
    nsIndexType:none
For a complete list of matching rules and their OIDs, see Section 8.3.4, “Using Matching Rules”, and for the index configuration attributes or the ldapmodify command-line utility, see the Directory Server Configuration and Command-Line Tool Reference.

NOTE

Always use the attribute's primary name (not the attribute's alias) when creating indexes. The primary name of the attribute is the first name listed for the attribute in the schema; for example, uid for the user ID attribute.

7.3. Applying New Indexes to Existing Databases

New indexes are not added to existing databases automatically. They must be added manually, and Directory Server has two methods for applying new indexes to an existing database: running the db2index.pl script or running a cn=index,cn=tasks task.

7.3.1. Running the db2index.pl Script

After creating an indexing entry or adding additional index types to an existing indexing entry, run the db2index.pl script to generate the new set of indexes to be maintained by the Directory Server. After the script is run, the new set of indexes is active for any new data added to the directory and any existing data in the directory.
  1. Open the Directory Server instance directory.
    cd /etc/dirsrv/slapd-instance_name
  2. Run the db2index.pl Perl script.
    db2index.pl-D "cn=Directory Manager" -w secret -n ExampleServer -t sn
    For more information about using this Perl script, see the Directory Server Configuration and Command-Line Tool Reference.
Table 7.6, “db2index Options” describes the db2index.pl options.

Table 7.3. db2index.pl Options

Option Description
-D Specifies the DN of the administrative user.
-w Specifies the password of the administrative user.
-n Specifies the name of the database being indexed.
-t Specifies the name of the attribute contained by the index.

7.3.2. Using a cn=tasks Entry to Create an Index

The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries that the server uses to manage tasks. Several common directory tasks have container entries under cn=tasks,cn=config. Temporary task entries can be created under cn=index,cn=tasks,cn=config to initiate an indexing operation.
This task entry requires a unique name (cn) and a definition for the attribute and type of index, set in nsIndexAttribute in the format attribute:index_type.
For example:
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=example presence index,cn=index,cn=tasks,cn=config
objectclass: extensibleObject
cn: example presence index
nsIndexAttribute: "cn:pres"
There are three possible index_types:
  • pres for presence indexes
  • eq for equality indexes
  • sub for substring indexes
As soon as the task is completed, the entry is removed from the directory configuration.
The Directory Server Configuration and Command-Line Tool Reference has more information on running Directory Server tasks under the cn=tasks entries.

7.4. Creating Browsing (VLV) Indexes

A virtual list view (VLV) index is a way of creating a truncated list for faster searching while enhancing server performance. The VLV index itself can be resource-intensive to maintain, but it can be beneficial in large directories (over 1000 entries).
A browsing index is a type of VLV index that organizes the entries listed into alphabetical order, making it easier to find entries.
VLV indexes are not applied to attributes, like standard indexes are, but they are dynamically generated based on attributes set in entries and the location of those entries in the directory tree. VLV indexes, unlike standard indexes, are special entries in the database rather than configuration settings for the database.

NOTE

VLV indexes are similar to simple paged results, which can be returned with some external LDAP clients. Simple paged results are calculated per search, while VLV indexes are a permanent list, so VLV indexes are overall faster for searches, but do require some overhead for the server to maintain.
Simple paged results and VLV indexes cannot be used on the same search.

7.4.1. Creating Browsing Indexes from the Server Console

  1. Select the Directory tab.
  2. In the left navigation tree, select the entry, such as People, for which to create the index.
  3. From the Object menu, select Create Browsing Index.
    The Create Browsing Index dialog box appears displaying the status of the index creation. Click the Status Logs box to view the status of the indexes created.
  4. Click Close.
The new index is immediately active for any new data that is added to the directory. You do not have to restart your server.
For more information on how to change the VLV search information or the access control rules that are set by default for VLV searches, see Section 7.4.2.1, “Adding a Browsing Index Entry” and Section 7.4.3, “Setting Access Control for VLV Information”.

7.4.2. Creating Browsing Indexes from the Command Line

Creating a browsing index or virtual list view (VLV) index from the command line has these steps:
  1. Using ldapmodify to add new browsing index entries or edit existing browsing index entries. See Section 7.4.2.1, “Adding a Browsing Index Entry”.
  2. Running the vlvindex script to generate the new set of browsing indexes to be maintained by the server. See Section 7.4.2.2, “Running the vlvindex Script”. Alternatively, launch an appropriate task under cn=tasks,cn=config (Section 7.4.2.3, “Using a cn=tasks Entry to Create a Browsing Index”).
  3. Ensuring that access control on VLV index information is set appropriately. See Section 7.4.3, “Setting Access Control for VLV Information”.

7.4.2.1. Adding a Browsing Index Entry

The type of browsing index entry to create depends on the type of ldapsearch attribute sorting to accelerate. It is important to take the following into account:
  • The scope of the search (base, one, sub)
  • The base of the search (the entry to use as a starting point for the search)
  • The attributes to sort
  • The filter of the search
    For more information on specifying filters for searches, see Chapter 8, Finding Directory Entries.
  • The LDBM database to which the entry that forms the base of the search belongs. You can only create browsing indexes in LDBM databases.
There is more information on ldapsearch options in the Directory Server Configuration and Command-Line Tool Reference.
For example, create a browsing index to accelerate an ldapsearch on the entry ou=People,dc=example,dc=com held in the Example1 database with the following attributes:
  • The search base is ou=People,dc=example,dc=com
  • The search filter is (|(objectclass=*)(objectclass=ldapsubentry))
  • The scope is one
  • The sorting order for the returned attributes is cn, givenname, o, ou, and sn
  1. Run ldapmodify.
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
    The ldapmodify utility binds to the server and prepares it to add an entry to the configuration file.
  2. Add an entry which specifies the base, scope, and filter of the browsing index:
    dn: cn=MCC ou=People dc=example dc=com,cn=userRoot,cn=ldbm database,cn=plugins,cn=config 
    objectClass: top 
    objectClass: vlvSearch 
    cn: MCC ou=People dc=example dc=com 
    vlvBase: ou=People,dc=example,dc=com 
    vlvScope: 1 
    vlvFilter: (|(objectclass=*)(objectclass=ldapsubentry))
    • The cn contains the browsing index identifier, which specifies the entry on which to create the browsing index; in this example, the ou=People,dc=example,dc=com entry. Red Hat recommends using the dn of the entry for the browsing index identifier, which is the approach adopted by the Directory Server Console, to prevent identical browsing indexes from being created. The entry is a member of the vlvSearch object class.
    • The vlvbase attribute value specifies the entry on which you want to create the browsing index; in this example, the ou=People,dc=example,dc=com entry (the browsing index identifier).
    • The vlvscope attribute is 1, indicating that the scope for the search you want to accelerate is 1. A search scope of 1 means that only the immediate children of the entry specified in the cn attribute, and not the entry itself, will be searched.
    • The vlvfilter specifies the filter to be used for the search; in this example, (|(objectclass=*)(objectclass=ldapsubentry)).
  3. Add the second entry, to specify the sorting order for the returned attributes:
    dn: cn=by MCC ou=People dc=example dc=com,cn=MCC ou=People 
       dc=example dc=com,cn=userRoot,cn=ldbm database,cn=plugins,
       cn= config
    objectClass: top
    objectClass: vlvIndex
    cn: by MCC ou=People dc=example dc=com
    vlvSort: cn givenName o ou sn
    • The cn contains the browsing index sort identifier. The above cn is the type created by the Console by default, which has the sorting order as being set by the browsing index base. The entry is a member of the vlvIndex object class.
    • The vlvsort attribute value specifies the order in which you want your attributes to be sorted; in this example, cn, givenName, o, ou, and then sn.

NOTE

This first browsing index entry must be added to the cn=database_name,cn=ldbm database,cn=plugins,cn=config directory tree node, and the second entry must be a child of the first entry.

7.4.2.2. Running the vlvindex Script

After creating the two browsing indexing entries or added additional attribute types to an existing indexing browsing entries, run the vlvindex script to generate the new set of browsing indexes to be maintained by the Directory Server. After running the script, the new set of browsing indexes is active for any new data added to the directory and any existing data in the directory.
To run the vlvindex script:
  1. Open the Directory Server instance directory.
    cd /etc/dirsrv/slapd-instance_name
  2. Stop the server.
    service dirsrv stop instance
  3. Run the vlvindex script.
    vlvindex -n Example1 -T "by MCC ou=people dc=example dc=com"
    For more information about using this script, see the Directory Server Configuration and Command-Line Tool Reference.
  4. Restart the server.
    service dirsrv start instance
Table 7.4, “vlvindex Options” describes the vlvindex options used in the examples:

Table 7.4. vlvindex Options

Option Description
-n Name of the database containing the entries to index.
-T Browsing index identifier to use to create browsing indexes.

7.4.2.3. Using a cn=tasks Entry to Create a Browsing Index

As an alternative to running the vlvindex script, it is possible to initiate an indexing task directly.

NOTE

Running the indexing task is the same as running the vlvindex script.
The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries that the server uses to manage tasks. Several common directory tasks have container entries under cn=tasks,cn=config. Temporary task entries can be created under cn=index,cn=tasks,cn=config to initiate an indexing operation.
This task entry requires a unique name (cn) and one other attribute, nsIndexVLVAttribute, which gives the name of the browsing index definition entry to use to generate the VLV index.
For example:
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=example VLV index,cn=index,cn=tasks,cn=config
objectclass: extensibleObject
cn: example VLV index
nsIndexVLVAttribute: "by MCC ou=people,dc=example,dc=com"
As soon as the task is completed, the entry is removed from the directory configuration.
The Directory Server Configuration and Command-Line Tool Reference has more information on running Directory Server tasks under the cn=tasks entries.

7.4.3. Setting Access Control for VLV Information

The default access control for the VLV index information is to allow anyone who has authenticated. If a site requires anonymous users to use the VLV index information, modify the access control set for cn: VLV Request Control in the Directory Server's configuration.
  1. Open the Directory Server configuration directory:
    cd /etc/dirsrv/slapd-instance_name
  2. In a text editor, open the dse.ldif file.
  3. Locate the oid=2.16.840.1.113730.3.4.9 entry.
    dn: oid=2.16.840.1.113730.3.4.9,cn=features,cn=config 
    objectClass: top 
    objectClass: directoryServerFeature 
    oid: 2.16.840.1.113730.3.4.9 
    cn: VLV Request Control 
    aci: (targetattr != "aci")(version 3.0; acl "VLV Request Control"; 
         allow( read, search, compare, proxy ) userdn = "ldap:///all" ;) 
    creatorsName: cn=server,cn=plugins,cn=config modifiersName: cn=server,cn=plugins,cn=config ...
  4. Change "ldap://all" to "ldap://anyone" and save your changes.

7.5. Changing the Index Sort Order

By default, indexes are sorted alphabetically, in descending ASCII order. This is true for every attribute, even attributes which may have numeric attribute values like Integer or TelephoneNumber. It is possible to change the sort method by changing the matching rule set for the attribute.

7.5.1. Changing the Sort Order in the Console

  1. Select the Configuration tab.
  2. Expand the Data node, expand the suffix of the database to index, and select the database.
  3. Select the Indexes tab in the right pane.
  4. Select the index, and, in the Matching Rules field, enter the new sort order to use. For example, to sort by numbers, rather than alphabetically, enter integerOrderingMatch.
  5. Click Save.

7.5.2. Changing the Sort Order in the Command Line

To change the sort order using the command line, change the nsMatchingRule for the attribute index. For example:
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389

dn: cn=sn,cn=index,cn=Example1,cn=ldbm database,cn=plugins,cn=config 
changetype:modify
replace:nsMatchingRule
nsMatchingRule:integerOrderingMatch

7.6. Changing the Width for Indexed Substring Searches

By default, for a search to be indexed, the search string must be at least three characters long, without counting any wildcard characters. For example, the string abc would be an indexed search while ab* would not be. Indexed searches are significantly faster than unindexed searches, so changing the minimum length of the search key is helpful to increase the number of indexed searches.
To improve search performance, particularly for sites with many wildcard searches, the search string length for indexed searches can be changed. Directory Server has three attributes which allow you to change the minimum number of characters required for an indexed search:
  • The nsSubStrBegin attribute sets the required number of characters for an indexed search for the beginning of a search string, before the wildcard.
    abc*
  • The nsSubStrMiddle attribute sets the required number of characters for an indexed search where a wildcard is used in the middle of a search string. For example:
    ab*z
  • The nsSubStrEnd attribute sets the required number of characters for an indexed search for the end of a search string, after the wildcard. For example:
    *xyz
The default substring search length for the string triplet (before, middle, and end) is 3, 3, and 3, meaning every search requires a minimum of three characters, in every wildcard position.
For any attribute index to have alternate string lengths, add the extensibleObject object class to the entry and then set the substring search lengths.
  1. Set the new key length for the specific attribute index. This requires adding the extensibleObject object class and then adding the nsSubStrBegin, nsSubStrEnd, or nsSubStrMiddle attributes as appropriate. For example:
    /usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com
    
    dn: attribute_name,cn=index,cn=database_name,cn=ldbm database,cn=plugins,cn=config
    objectClass: extensibleObject
    nsSubStrBegin: 2
    nsSubStrMiddle: 2
    nsSubStrEnd: 2
  2. Stop the server.
    service dirsrv stop
  3. Recreate the attribute index. If even one of the substring search width options is changed, then the entire index must be recreated.
    db2index -t attribute_name
  4. Start the server again.
    service dirsrv start

7.7. Deleting Indexes

This section describes how to delete presence, equality, approximate, substring, international, and browsing indexes for specific attributes.

NOTE

Because Directory Server 8.2 can operate in either a single or multi-database environment, you have to delete any unwanted indexes from every database instance. Any default indexes you delete will not be deleted from previous sets of indexes on existing database instances.

WARNING

Do not delete system indexes because deleting them can significantly affect Directory Server performance. System indexes are located in the cn=index,cn=instance,cn=ldbm database,cn=plugins,cn=config entry and the cn=default indexes,cn=config,cn=ldbm database,cn=plugins,cn=config entry.
Also, be cautious when deleting default indexes since this can also affect how Directory Server works.

7.7.1. Deleting Indexes from the Server Console

The Directory Server Console can delete any custom indexes, indexes used by other server applications such as a messaging or web server, and default indexes.

NOTE

You cannot delete system indexes.
  1. Select the Configuration tab.
  2. Expand the Data node and expand the suffix associated with the database containing the index.
  3. Select the database from which to delete the index.
  4. Locate the attribute containing the index to delete. Clear the checkbox under the index.
    To delete all indexes maintained for a particular attribute, select the attribute's cell under Attribute Name, and click Delete Attribute.
  5. Click Save.
    A Delete Index warning dialog box opens, requiring a confirmation to delete the index.
  6. Click Yes to delete the index.

7.7.2. Deleting Indexes from the Command Line

Creating browsing indexes, or virtual list view (VLV) indexes, using the ldapdelete command-line utility has two steps:
  1. Delete an entire index entry or delete unwanted index types from an existing index entry using the ldapdelete command-line utility (Section 7.7.2.1, “Deleting an Index Entry”).
  2. Generate the new set of indexes to be maintained by the server using the db2index.pl Perl script (Section 7.7.2.2, “Running the db2index.pl Script”).

7.7.2.1. Deleting an Index Entry

Use the ldapdelete command-line utility to delete either the entire indexing entry or the unwanted index types from an existing entry.
  • To delete the indexes for a particular database, remove the index entry from the cn=index,cn=database_name,cn=ldbm database,cn=plugins,cn=config entry, where cn=database_name corresponds to the name of the database.
  • To delete a default index, remove it from the cn=default indexes,cn=config,cn=ldbm database,cn=plugins,cn=config entry.
  1. Run ldapdelete.[6]
    ldapdelete -D "cn=Directory Manager" -w secret -h ExampleServer
         -p 389 "cn=sn,cn=index,cn=Example1,dn=ldbm database,cn=plugins,dn=config"
    For complete information on ldapdelete, see the Directory Server Configuration and Command-Line Tool Reference.
  2. For example, delete the presence, equality, and substring indexes for the sn attribute on the database named Example1:
    dn: cn=sn,cn=index,cn=Example1,cn=ldbm database,cn=plugins,cn=config 
    objectClass:top 
    objectClass:nsIndex 
    cn:sn 
    nsSystemIndex:false 
    nsIndexType:pres 
    nsIndexType:eq 
    nsIndexType:sub 
    nsMatchingRule:2.16.840.1.113730.3.3.2.3.1
Table 7.5, “ldapdelete Options” describes the ldapdelete options.

Table 7.5. ldapdelete Options

Option 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 option.
-h Specifies the name of the host on which the server is running.
-p Specifies the port number that the server uses.

After deleting the index entry, the presence, equality, and substring indexes for the sn attribute are no longer maintained by the Example1 database.

7.7.2.2. Running the db2index.pl Script

After deleting an indexing entry or some of the index types from an indexing entry, run the db2index.pl script to generate the new set of indexes to be maintained by the Directory Server. Once you run the script, the new set of indexes is active for any new data you add to your directory and any existing data in your directory.
To run the db2index.pl Perl script:
  1. Open the Directory Server instance directory.
    cd /etc/dirsrv/slapd-instance_name
  2. Run the db2index.pl Perl script. For example:
    db2index.pl-D "cn=Directory Manager" -w secret -n Example1
For more information about using the db2index.pl Perl script, refer to Directory Server Configuration and Command-Line Tool Reference. Table 7.6, “db2index Options” describes the db2index.pl options used in the examples:

Table 7.6. db2index Options

Option Description
-D Specifies the DN of the administrative user.
-w Specifies the password of the administrative user.
-n Specifies the name of the database into which you are importing the data.

7.7.3. Deleting Browsing Indexes from the Server Console

  1. Select the Directory tab.
  2. Select the entry from which to delete the index in the navigation tree, and select Delete Browsing Index from the Object menu.
    Alternatively, select and right-click the entry of the index to delete in the navigation tree, and then choose Delete Browsing Index from the pop-up menu.
  3. A Delete Browsing Index dialog box appears asking you to confirm the deletion of the index. Click Yes.
  4. The Delete Browsing Index dialog box appears displaying the status of the index deletion.

7.7.4. Deleting Browsing Indexes from the Command Line

Deleting a browsing index or virtual list view (VLV) index from the command line involves two steps:
  1. Using the ldapdelete to delete browsing index entries or edit existing browsing index entries (Section 7.7.4.1, “Deleting a Browsing Index Entry”).
  2. Running the vlvindex script to generate the new set of browsing indexes to be maintained by the server (Section 7.7.4.2, “Running the vlvindex Script”). Alternatively, launch an appropriate task under cn=tasks,cn=config (Section 7.4.2.3, “Using a cn=tasks Entry to Create a Browsing Index”).
The actual entries for an alphabetical browsing index and virtual list view are the same. The following sections describe the steps involved in deleting browsing indexes.

7.7.4.1. Deleting a Browsing Index Entry

Use the ldapdelete command-line utility to either delete browsing indexing entries or edit existing browsing index entries. To delete browsing indexes for a particular database, remove the browsing index entries from the cn=index,cn=database_name,cn=ldbm database,cn=plugins,cn=config entry, where cn=database_name corresponds to the name of the database.
For example, there is a browsing index for accelerating ldapsearch operations on the entry ou=People,dc=example,dc=com. It held in the Example1 database where the search base is ou=People,dc=example,dc=com, the search filter is (|(objectclass=*)(objectclass=ldapsubentry)), the scope is 1, and the sorting order for the returned attributes is cn, givenname, o, ou, and sn.
  1. Run ldapdelete.[6]
    ldapdelete-D "cn=Directory Manager" -w secret -h ExampleServer
    -p 389 "cn=MCC ou=People dc=example dc=com,cn=userRoot,cn=ldbm database,cn=plugins,cn=config"
    
    "cn=by MCC ou=People dc=example dc=com,cn=MCC ou=People
    dc=example dc=com,cn=userRoot,cn=ldbm database,cn=plugins,cn=config"
    
    For full information on ldapdelete options, see the Directory Server Configuration and Command-Line Tool Reference.
  2. To delete this browsing index, delete the two corresponding browsing index entries:
    dn: cn=MCC ou=People dc=example dc=com,cn=userRoot,cn=ldbm database,cn=plugins,cn=config 
    objectClass: top 
    objectClass: vlvSearch 
    cn: MCC ou=People dc=example dc=com 
    vlvBase: ou=People,dc=example,dc=com 
    vlvScope: 1 vlvFilter: (|(objectclass=*)(objectclass=ldapsubentry))
    
    dn: cn=by MCC ou=People dc=example dc=com,cn=MCC ou=People
    dc=example dc=com,cn=userRoot,cn=ldbm database,cn=plugins,cn=config
    objectClass: top
    objectClass: vlvIndex
    cn: by MCC ou=People dc=example dc=com
    vlvSort: cn givenname o ou sn
The following table describes the ldapdelete options used in the example:
Option 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 option.
-h Specifies the name of the host on which the server is running.
-p Specifies the port number that the server uses.
After deleting the two browsing index entries, the browsing index will no longer be maintained by the Example1 database.

7.7.4.2. Running the vlvindex Script

After deleting browsing indexing entries or unwanted attribute types from existing browsing indexing entries, run the vlvindex script to generate the new set of browsing indexes to be maintained by the Directory Server. After the script is run, the new set of browsing indexes is active for any new data added to the directory and any existing data in the directory.
  1. Open the Directory Server instance directory.
    cd /etc/dirsrv/slapd-instance_name
  2. Stop the server.
    service dirsrv stop instance
  3. Run the vlvindex script.
    vlvindex -n Example1 -T "by MCC ou=people dc=example dc=com"
    For more information about using the vlvindex script, see the Directory Server Configuration and Command-Line Tool Reference.
  4. Restart the server.
    service dirsrv start instance
Table 7.4, “vlvindex Options” describes the vlvindex options.
Alternatively, create a new task entry under cn=index,cn=tasks,cn=config to initiate an indexing operation. This task entry requires a unique name (cn) and one other attribute, nsIndexVLVAttribute, which gives the name of the browsing index definition entry to use to generate the VLV index. This task is the same as running vlvindex.
For example:
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=example VLV index,cn=index,cn=tasks,cn=config
objectclass: extensibleObject
cn: example VLV index
nsIndexVLVAttribute: "by MCC ou=people,dc=example,dc=com"
As soon as the task is completed, the entry is removed from the directory configuration.
The Directory Server Configuration and Command-Line Tool Reference has more information on running Directory Server tasks under the cn=tasks entries.


[6] The LDAP tools referenced in this guide are Mozilla LDAP, installed with Directory Server in the /usr/lib64/mozldap directory on Red Hat Enterprise Linux 5 (64-bit); directories for other platforms are listed in Section 1.3, “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.

Chapter 8. Finding Directory Entries

Entries in the directory can be searched for and found using any LDAP client. Most clients provide some form of search interface so that the directory can be searched easily and entry information can be easily retrieved.

NOTE

Users cannot search the directory unless the appropriate access control has been set in the directory. For information on setting access control in the directory, see Chapter 12, Managing Access Control.

8.1. Finding Entries Using the Directory Server Console

Users can browse the Directory tab of the Directory Server Console to see the contents of the directory tree and search for specific entries in the directory.
Browsing Entries in the Directory Tab

Figure 8.1. Browsing Entries in the Directory Tab


Depending on the DN used to authenticate to the directory, this tab displays the contents of the directory that the user account has access permissions to view. Browse through the contents of the tree, or right-click an entry, and select Search from the pop-up menu.
Searching for Entries

Figure 8.2. Searching for Entries


WARNING

Do not modify the contents of the o=NetscapeRoot suffix using the Directory tab unless instructed to do so by Red Hat technical support.

8.2. Using ldapsearch

The ldapsearch command-line utility can locate and retrieve directory entries. This utility opens a connection to the specified server using the specified distinguished name and password and locates entries based on a specified search filter. The search scope can include a single entry, an entry's immediate subentries, or an entire tree or subtree.
Search results are returned in LDIF format.
Red Hat Directory Server uses Mozilla LDAP tools, including ldapsearch. The MozLDAP tools are installed with Directory Server and are located in the /usr/lib64/mozldap directory for Red Hat Enterprise Linux 5 (64-bit), and in the /usr/lib/mozldap directory on Red Hat Enterprise Linux 5 (32-bit). When running any LDAP command, make sure to use the MozLDAP utilities, otherwise the command will return errors.

NOTE

For most Linux systems, OpenLDAP tools are already installed in the /usr/bin/ directory. These OpenLDAP tools will not work for Directory Server operations.
This section contains information about the following topics:

8.2.1. ldapsearch Command-Line Format

The ldapsearch command must use the following format:
/usr/lib64/mozldap/ldapsearch [optional_options] [optional_search_filter] [optional_list_of_attributes]
  • optional_options is a series of command-line options. These must be specified before the search filter, if any are used.
  • optional_search_filter is an LDAP search filter as described in Section 8.3, “LDAP Search Filters”. Do not specify a separate search filter if search filters are specified in a file using the -f option.
  • optional_list_of_attributes is a list of attributes separated by a space. Specifying a list of attributes reduces the number of attributes returned in the search results. This list of attributes must appear after the search filter. For an example, see Section 8.4.6, “Displaying Subsets of Attributes”. If a list of attributes is not specified, the search returns values for all attributes permitted by the access control set in the directory (with the exception of operational attributes).

    NOTE

    For operational attributes to be returned as a result of a search operation, they must be explicitly specified in the search command. To retrieve regular attributes in addition to explicitly specified operational attributes, use an asterisk (*) in the list of attributes in the ldapsearch command. To retrieve no attributes, just a list of the matching DNs, use the special attribute 1.1. This is useful, for example, to get a list of DNs to pass to the ldapdelete command.

8.2.2. Commonly Used ldapsearch Options

The following table lists the most commonly used ldapsearch command-line options. If a specified value contains a space ( ), the value should be surrounded by single or double quotation marks, such as -b "ou=groups,dc=example,dc=com".
Option Description
-b Specifies the starting point for the search. The value specified here must be a distinguished name that currently exists in the database. This is optional if the LDAP_BASEDN environment variable has been set to a base DN. The value specified in this option should be provided in single or double quotation marks. For example:
-b "cn=Barbara Jensen,ou=Product Development,dc=example,dc=com"
To search the root DSE entry, specify an empty string here, such as -b "" .
-D Specifies the distinguished name with which to authenticate to the server. This is optional if anonymous access is supported by the server. If specified, this value must be a DN recognized by the Directory Server, and it must also have the authority to search for the entries. For example, -D "uid=bjensen,dc=example,dc=com".
-h Specifies the hostname or IP address of the machine on which the Directory Server is installed. For example, -h server.example.com. If a host is not specified, ldapsearch uses the localhost.

NOTE

Directory Server supports both IPv4 and IPv6 IP addresses.
-l Specifies the maximum number of seconds to wait for a search request to complete. For example, -l 300. The default value for the nsslapd-timelimit attribute is 3600 seconds. Regardless of the value specified, ldapsearch will never wait longer than is allowed by the server's nsslapd-timelimit attribute.
-p Specifies the TCP port number that the Directory Server uses. For example, -p 1049. The default is 389. If -Z is used, the default is 636.
-s Specifies the scope of the search. The scope can be one of the following:
base searches only the entry specified in the -b option or defined by the LDAP_BASEDN environment variable.
one searches only the immediate children of the entry specified in the -b option. Only the children are searched; the actual entry specified in the -b option is not searched.
sub searches the entry specified in the -b option and all of its descendants; that is, perform a subtree search starting at the point identified in the -b option. This is the default.
-w Gives the password associated with the distinguished name that is specified in the -D option. If this option is not specified, anonymous access is used. For example, -w diner892.
-x Specifies that the search results are sorted on the server rather than on the client. This is useful for sorting according to a matching rule, as with an international search. In general, it is faster to sort on the server rather than on the client.
-z Sets the maximum number of entries to return in response to a search request. For example, -z 1000. Normally, regardless of the value specified here, ldapsearch never returns more entries than the number allowed by the server's nsslapd-sizelimit attribute. However, this limitation can be overridden by binding as the root DN when using this command-line argument. When binding as the root DN, this option defaults to zero (0). The default value for the nsslapd-sizelimit attribute is 2000 entries.
For detailed information on all ldapsearch utility options, refer to the Directory Server Configuration and Command-Line Tool Reference.

8.2.3. Using Special Characters

When using the ldapsearch command-line utility, it may be necessary to specify values that contain characters that have special meaning to the command-line interpreter, such as space ( ), asterisk (*), or backslash (\). Enclose the value which has the special character in quotation marks (""). For example:
-D "cn=Barbara Jensen,ou=Product Development,dc=example,dc=com"
Depending on the command-line interpreter, use either single or double quotation marks. In general, use single quotation marks (') to enclose values. Use double quotation marks (") to allow variable interpolation if there are shell variables. Refer to the operating system documentation for more information.

8.3. LDAP Search Filters

Search filters select the entries to be returned for a search operation. They are most commonly used with the ldapsearch command-line utility. When using ldapsearch, there can be multiple search filters in a file, with each filter on a separate line in the file, or a search filter can be specified directly on the command line.
The basic syntax of a search filter is:
attribute operator value 
For example:
buildingname>=alpha
In this example, buildingname is the attribute, >= is the operator, and alpha is the value. Filters can also be defined that use different attributes combined together with Boolean operators.

TIP

When performing a substring search using a matching rule filter, use the asterisk (*) character as a wildcard to represent zero or more characters.
For example, to search for an attribute value that starts with the letter l and ends with the letter n, enter a l*n in the value portion of the search filter. Similarly, to search for all attribute values beginning with the letter u, enter a value of u* in the value portion of the search filter.
To search for a value that contains the asterisk (*) character, the asterisk must be escaped with the designated escape sequence, \5c2a. For example, to search for all employees with businessCategory attribute values of Example*Net product line, enter the following value in the search filter:
Example\5c2a*Net product line

8.3.1. Using Attributes in Search Filters

The most basic sort of search looks for the presence of attributes or specific values in entries. There are many variations on how to look for attributes in entries. It is possible to check that the attribute merely exists, to match an exact value, or to list matches against a partial value.
A presence search uses a wild card (an asterisk) to return every entry which has that attribute set, regardless of value. For example, this returns every entry which has a manager attribute:
"(manager=*)"
It is also possible to search for an attribute with a specific value; this is called an equality search. For example:
"(cn=babs jensen)"
This search filter returns all entries that contain the common name Babs Jensen. Most of the time, equality searches are not case sensitive.
When an attribute has values associated with a language tag, all of the values are returned. Thus, the following two attribute values both match the "(cn=babs jensen)" filter:
cn: babs jensen 
cn;lang-fr: babs jensen
It is also possible to search for a partial match on an attribute value, a substring index. For example:
"(description=*X.500*)"
"(sn=*nderson)"
"(givenname=car*)"
The length of the substring searches is configured in the substring index itself, as described in Section 7.6, “Changing the Width for Indexed Substring Searches”.

8.3.2. Using Operators in Search Filters

Operators in search filters set the relationship between the attribute and the given search value. For people searches, operators can be used to set a range, to return a last names within a subset of letters in the alphabet or employee numbers that come after a certain number.
"(employeeNumber>=500)"
"(sn~=suret)"
"(salary<=150000)"
Operators also enable phonetic and approximate searches, which allow more effective searches with imperfect information and are particularly useful in internationalized directories.
The operators that can be used in search filters are listed in Table 8.1, “Search Filter Operators”. In addition to these search filters, special filters can be specified to work with a preferred language collation order. For information on how to search a directory with international charactersets, see Section C.4, “Searching an Internationalized Directory”.

Table 8.1. Search Filter Operators

Search Type Operator Description
Equality = Returns entries containing attribute values that exactly match the specified value. For example, cn=Bob Johnson
Substring =string* string Returns entries containing attributes containing the specified substring. For example, cn=Bob* cn=*Johnson cn=*John* cn=B*John. The asterisk (*) indicates zero (0) or more characters.
Greater than or equal to >= Returns entries containing attributes that are greater than or equal to the specified value. For example, buildingname >= alpha.
Less than or equal to <= Returns entries containing attributes that are less than or equal to the specified value. For example, buildingname <= alpha.
Presence =* Returns entries containing one or more values for the specified attribute. For example, cn=* telephoneNumber=* manager=*.
Approximate ~= Returns entries containing the specified attribute with a value that is approximately equal to the value specified in the search filter. For example, cn~=suret l~=san fransico could return cn=sarette l=san francisco.

8.3.3. Using Compound Search Filters

Multiple search filter components can be combined using Boolean operators expressed in prefix notation as follows:
(Boolean-operator(filter)(filter)(filter)...)
Boolean-operator is any one of the Boolean operators listed in Table 8.2, “Search Filter Boolean Operators”.
FOr example, this filter returns all entries that do not contain the specified value:
(!(cn=Ray Kultgen))
(!(objectClass=person))
Obviously, compound search filters are most useful when they are nested together into completed expressions:
(Boolean-operator(filter)((Boolean-operator(filter)(filter)))
These compound filters can be combined with other types of searches (approximate, substring, other operators) to get very detailed results. For example, this filter returns all entries whose organizational unit is Marketing and whose description field does not contain the substring X.500:
(&(ou=Marketing)(!(description=*X.500*)))
That filter can be expanded to return entries whose organizational unit is Marketing, that do not have the substring X.500, and that have Julie Fulmer or Cindy Zwaska as a manager:
(&(ou=Marketing)(!(description=*X.500*))(|(manager=cn=Julie Fulmer,ou=Marketing,dc=example,dc=com)(manager=cn=Cindy Zwaska,ou=Marketing,dc=example,dc=com)))
This filter returns all entries that do not represent a person and whose common name is similar to printer3b:
(&(!(objectClass=person))(cn~=printer3b))

Table 8.2. Search Filter Boolean Operators

Operator Symbol Description
AND & All specified filters must be true for the statement to be true. For example, (&(filter)(filter)(filter)...).
OR | At least one specified filter must be true for the statement to be true. For example, (|(filter)(filter)(filter)...)
NOT ! The specified statement must not be true for the statement to be true. Only one filter is affected by the NOT operator. For example, (!(filter)).

Boolean expressions are evaluated in the following order:
  • Innermost to outermost parenthetical expressions first.
  • All expressions from left to right.

8.3.4. Using Matching Rules

A matching rule tells the Directory Server how to compare two values (the value stored in the attribute and the value in the search filter). A matching rule also defines how to generate index keys. Matching rules are somewhat related to attribute syntaxes. Syntaxes define the format of an attribute value; matching rules define how that format is compared and indexed.
There are three different types of matching rules:
  • EQUALITY specifies how to compare two values for an equal match. For example, how to handle strings like “Fred” and “FRED”. Search filters that test for equality (e.g. attribute=value) use the EQUALITY rule. Equality (eq) indexes use the EQUALITY rule to generate the index keys. Update operations use the EQUALITY rule to compare values to be updated with values already in an entry.
  • ORDERING specifies how to compare two values to see if one value is greater or less than another value. Search filters that set a range (e.g. attribute<=value or attribute>=value) use the ORDERING rule. An index for an attribute with an ORDERING rule orders the equality values.
  • SUBSTR specifies how to do substring matching. Substring search filters (e.g. attribute=*partial_string* or attribute=*end_string) use the SUBSTR rule. Substring (sub) indexes use the SUBSTR rule to generate the index keys.

IMPORTANT

A matching rule is required in order to support searching or indexing for the corresponding search filter or index type. For example, an attribute must have an EQUALITY matching rule in order to support equality search filters and eq indexes for that attribute. An attribute must have both an ORDERING matching rule and an EQUALITY matching rule in order to support range search filters and indexed range searches.
A search operation will be rejected with PROTOCOL_ERROR or UNWILLING_TO_PERFORM if an attempt is made to use a search filter for an attribute that has no corresponding matching rule.
An extensible matching rule search filter can be used to search for an attribute value with a different matching rule than the one defined for the attribute. The matching rule must be compatible with the syntax of the attribute being searched. For example, to run a case insensitive search for an attribute that has a case-sensitive matching rule defined for it, specify a case insensitive matching rule in the search filter.

NOTE

Matching rules are used for searches in internationalized directories, to specify the language types to use for the results. This is covered in Section C.4, “Searching an Internationalized Directory”.

TIP

An index for an attributes uses whatever matching rules are defined for that attribute in its schema definition. Additional matching rules to use for an index can be configured using the nsMatchingRule attribute, as in Section 7.2.2, “Creating Indexes from the Command Line”.
The syntax of the matching rule filter inserts a matching rule name or OID into the search filter:
attr:matchingRule:=value
  • attr is an attribute belonging to entries being searched, such as cn or mail.
  • matchingRule is a string that contains the name or OID of the rule to use to match attribute values according to the required syntax.
  • value is either the attribute value to search for or a relational operator plus the attribute value to search for. The syntax of the value of the filter depends on the matching rule format used.
A matching rule is actually a schema element, and, as with other schema elements is uniquely identified by an object identifier (OID).
Many of the matching rules defined for Red Hat Directory Server relate to language codes and set internationalized collation orders supported by the Directory Server. For example, the OID 2.16.840.1.113730.3.3.2.17.1 identifies the Finnish collation order.

NOTE

Unlike other schema elements, additional matching rules cannot be added to the Directory Server configuration.
Most of the matching rules list in Table 8.3, “General Syntax Matching Rules” are used for equality indexes. Matching rules with ordering in their name are used for ordering indexes, and those with substring in their name are used for substring (SUBSTR) indexes. (The matching rules used for international matching and collation orders use a different naming scheme.)

Table 8.3. General Syntax Matching Rules

Matching Rule Object Identifiers (OIDs) Definitions Compatible Syntaxes
Bitwise AND Match 1.2.840.113556.1.4.803 Performs bitwise AND matches. Typically used with:[a]
Integer
Numeric String
Bitwise OR Match 1.2.840.113556.1.4.804 Performs bitwise OR matches. Typically used with:[a]
Integer
Numeric String
generalizedTimeMatch 2.5.13.27 Compares values that are in a Generalized Time format. Generalized Time
generalizedTimeOrderingMatch 2.5.13.28 Allows ranged searches (less than and greater than) on values that are in a Generalized Time format. Generalized Time
integerMatch 2.5.13.14 Evaluates integer values. Integer
integerOrderingMatch 2.5.13.15 Allows ranged searches (less than and greater than) on integer values. Integer
numericStringMatch 2.5.13.8 Compares more general numeric values. Numeric String
numericStringOrderingMatch 2.5.13.9 Allows ranged searches (less than and greater than) on more general numeric values. Numeric String
numericStringSubstringMatch 2.5.13.10 Compares more general numeric values. Numeric String
[a] This has a special format; the value is converted to integer before being used by Directory Server.

Table 8.4. Language Ordering Matching Rules

Matching Rule Object Identifiers (OIDs)
English (Case Exact Ordering Match) 2.16.840.1.113730.3.3.2.11.3
Albanian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.44.1
Arabic (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.1.1
Belorussian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.2.1
Bulgarian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.3.1
Catalan (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.4.1
Chinese - Simplified (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.49.1
Chinese - Traditional (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.50.1
Croatian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.22.1
Czechoslovakian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.5.1
Danish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.6.1
Dutch (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.33.1
Dutch - Belgian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.34.1
English - US (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.11.1
English - Canadian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.12.1
English - Irish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.14.1
Estonian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.16.1
Finnish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.17.1
French (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.18.1
French - Belgian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.19.1
French - Canadian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.20.1
French - Swiss (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.21.1
German (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.7.1
German - Austrian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.8.1
German - Swiss (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.9.1
Greek (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.10.1
Hebrew (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.27.1
Hungarian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.23.1
Icelandic (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.24.1
Italian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.25.1
Italian - Swiss (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.26.1
Japanese (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.28.1
Korean (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.29.1
Latvian, Lettish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.31.1
Lithuanian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.30.1
Macedonian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.32.1
Norwegian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.35.1
Norwegian - Bokmul (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.36.1
Norwegian - Nynorsk (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.37.1
Polish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.38.1
Romanian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.39.1
Russian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.40.1
Serbian - Cyrillic (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.45.1
Serbian - Latin (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.41.1
Slovakian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.42.1
Slovenian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.43.1
Spanish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.15.1
Swedish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.46.1
Turkish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.47.1
Ukrainian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.48.1

Table 8.5. Language Substring Matching Rules

Matching Rule Object Identifiers (OIDs)
English (Case Exact Substring Match) 2.16.840.1.113730.3.3.2.11.3.6
Albanian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.44.1.6
Arabic (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.1.1.6
Belorussian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.2.1.6
Bulgarian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.3.1.6
Catalan (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.4.1.6
Chinese - Simplified (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.49.1.6
Chinese - Traditional (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.50.1.6
Croatian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.22.1.6
Czechoslovakian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.5.1.6
Danish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.6.1.6
Dutch (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.33.1.6
Dutch - Belgian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.34.1.6
English - US (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.11.1.6
English - Canadian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.12.1.6
English - Irish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.14.1.6
Estonian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.16.1.6
Finnish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.17.1.6
French (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.18.1.6
French - Belgian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.19.1.6
French - Canadian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.20.1.6
French - Swiss (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.21.1.6
German (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.7.1.6
German - Austrian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.8.1.6
German - Swiss (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.9.1.6
Greek (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.10.1.6
Hebrew (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.27.1.6
Hungarian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.23.1.6
Icelandic (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.24.1.6
Italian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.25.1.6
Italian - Swiss (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.26.1.6
Japanese (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.28.1.6
Korean (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.29.1.6
Latvian, Lettish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.31.1.6
Lithuanian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.30.1.6
Macedonian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.32.1.6
Norwegian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.35.1.6
Norwegian - Bokmul (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.36.1.6
Norwegian - Nynorsk (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.37.1.6
Polish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.38.1.6
Romanian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.39.1.6
Russian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.40.1.6
Serbian - Cyrillic (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.45.1.6
Serbian - Latin (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.41.1.6
Slovakian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.42.1.6
Slovenian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.43.1.6
Spanish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.15.1.6
Swedish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.46.1.6
Turkish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.47.1.6
Ukrainian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.48.1.6

8.4. Examples of Common ldapsearches

The next set of examples assumes the following:
  • The search is for all entries in the directory.
  • The directory is configured to support anonymous access for search and read. This means that no bind information has to be supplied in order to perform the search. For more information on anonymous access, see Section 12.4.2, “Defining User Access - userdn Keyword”.
  • The server is located on a host named server.example.com.
  • The server uses port number 389. Since this is the default port, the port number does not have to be sent in the search request.
  • SSL is enabled for the server on port 636 (the default SSL port number).
  • The suffix under which all data are stored is dc=example,dc=com.

8.4.1. Returning All Entries

Given the previous information, the following call will return all entries in the directory (subject to the configured size and time resource limits):
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "dc=example,dc=com" -s sub "(objectclass=*)"
"objectclass=*" is a search filter that matches any entry in the directory. Since every entry must have an object class, and the objectclass attribute is always indexed, this is a useful search filter to return every entry.

8.4.2. Specifying Search Filters on the Command Line

A search filter can be specified directly on the command line as long as the filter is enclosed in quotation marks ("filter"). If the filter is supplied with the command, do not specify the -f option. For example:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "dc=example,dc=com" -s sub "cn=babs jensen"

8.4.3. Searching the Root DSE Entry

The root DSE is a special entry that contains a list of all the suffixes supported by the local Directory Server. This entry can be searched by supplying a search base of "", a search scope of base, and a filter of "objectclass=*". For example:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "" -s base "objectclass=*"

8.4.4. Searching the Schema Entry

Directory Server stores all directory server schema in the special cn=schema entry. This entry contains information on every object class and attribute defined for the Directory Server. The following command searches the contents of the cn=schema entry:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "cn=schema" -s base "objectclass=*"

8.4.5. Using LDAP_BASEDN

To make searching easier, it is possible to set the search base using the LDAP_BASEDN environment variable. Doing this means that the search base does not have to be set with the -b option. For information on how to set environment variables, see the documentation for the operating system.
Typically, set LDAP_BASEDN to the directory's suffix value. Since the directory suffix is equal to the root, or topmost, entry in the directory, this causes all searches to begin from the directory's root entry.
For example, set LDAP_BASEDN to dc=example,dc=com and search for cn=babs jensen in the directory, use the following command-line call:
export LDAP_BASEDN="dc=example,dc=com"

/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com "cn=babs jensen"
In this example, the default scope of sub is used because the -s option was not used to specify the scope.

8.4.6. Displaying Subsets of Attributes

The ldapsearch command returns all search results in LDIF format. By default, ldapsearch returns the entry's distinguished name and all of the attributes that a user is allowed to read. The directory access control can be set such that users are allowed to read only a subset of the attributes on any given directory entry. Only operational attributes are not returned. For operational attributes to be returned as a result of a search operation, explicitly specify them in the search command.
It may not be necessary to have all of the attributes for an entry returned in the search results. The returned attributes can be limited to just a few specific attributes by specifying the desired ones on the command line immediately after the search filter. For example, to show the cn and sn attributes for every entry in the directory, use the following command-line call:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "dc=example,dc=com" -s sub "(objectclass=*)" sn cn

8.4.7. Searching for Operational Attributes

Operational attributes are special attributes set by the Directory Server itself that are used by the server to perform maintenance tasks, like processing access control instructions. They also show specific information about the entry, like the time it was initially created and the name of the user who created it. Operational attributes are available for use on every entry in the directory, regardless of whether the attribute is specifically defined for the object class of the entry.
Operational attributes are not returned in regular ldapsearches, so to return operational attributes, they have to be explicitly specified in the ldapsearch request.
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "dc=example,dc=com" -s sub "(objectclass=*)" creatorsName createTimestamp modifiersName modifyTimestamp
The complete list of operational attributes is in the "Operational Attributes and Object Classes" chapter in the Schema Reference

8.4.8. Specifying Search Filters Using a File

Search filters can be entered into a file instead of entering them on the command line. In this case, specify each search filter on a separate line in the file. The ldapsearch command runs each search in the order in which it appears in the file.
For example:
sn=Francis
givenname=Richard
ldapsearch first finds all the entries with the surname Francis, then all the entries with the givenname Richard. If an entry is found that matches both search criteria, then the entry is returned twice.
For example, in this search, the filters are specified in a file named searchdb:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -f searchdb
The set of attributes returned here can be limited by specifying the attribute names at the end of the search line. For example, the following ldapsearch command performs both searches but returns only the DN and the givenname and sn attributes of each entry:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -f searchdb sn givenname

8.4.9. Specifying DNs That Contain Commas in Search Filters

When a DN within a search filter contains a comma as part of its value, the comma must be escaped with a backslash (\). For example, to find everyone in the example.com Bolivia, S.A. subtree, use the following command:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -s base -b "l=Bolivia\,S.A.,dc=example,dc=com" "objectclass=*"

8.4.10. Using Client Authentication When Searching

Client authentication uses a stored certificate to bind to the directory rather than simple username-password. This example shows user bjensen searching the directory using client authentication:
/usr/lib64/mozldap/ldapsearch -h server.example.com -p 636 -b "dc=example,dc=com" -N "bjensenscertname" -Z -W certdbpassword -P /home/bjensen/certdb/cert8.db "givenname=Richard"

8.4.11. Searching with Specified Controls

The Directory Server has defined controls in its supportedControls attribute in its DSE. Some of these define server operations like replication; other are allowed extended operations like get effective rights or dereferencing controls which clients can pass through LDAP operations to the server. These controls can be specified using the -J option by giving the control OID, its criticality for the ldapsearch, and any information required for the control operation.
-J control_OID:boolean criticality:control_information
This option is used, for example, for Get effective rights searches:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "dc=example,dc=com" -s sub -J 1.3.6.1.4.1.42.2.27.9.5.2:true:dn:uid=jsmith,ou=people,dc=example,dc=com "(objectclass=*)"
Get effective rights searches are covered in much more detail in the access control chapter, Section 12.7, “Checking Access Rights on Entries (Get Effective Rights)”.

8.4.12. Searching with Language Matching Rules

To explicitly submit a matching rule in a search filter, insert the matching rule after the attribute:
attr:matchingRule:=value
Matching rules are frequently used for searching internationalized directories. For example, this seearches for the department numbers after N4709 in the Swedish (2.16.840.1.113730.3.3.2.46.1) matching rule.
departmentNumber:2.16.840.1.113730.3.3.2.46.1:=>= N4709
More examples of performing internaionalized searches are given in Section C.4, “Searching an Internationalized Directory”.

8.4.13. Searching for Attributes with Bit Field Values

Bitwise searches use the bitwise AND or bitwise OR matching rules to perform bitwise search operaions on attributes with values that are bit fields.

NOTE

Attributes with values for bit fields aren't common in LDAP. (No default Directory Server schema use bit fields as attribute syntax.) However, several LDAP syntaxes support interger-style values. Custom attributes can be defined which use bit field values, and applications can use those custom attributes to perform bitwise operations against bit field values.
The bitwise AND matching rule (1.2.840.113556.1.4.803) checks that the bit given in the assertion value is set in the bit field attribute value. (This is somewhat analogous to an equality search.) In this example, the userAccountControl value must be set to the bit representing 2.
"(UserAccountControl:1.2.840.113556.1.4.803:=2)"
In this example, the userAccountControl value must have all of the bits set that are set in the value 6 (bits 2 and 4).
"(UserAccountControl:1.2.840.113556.1.4.803:=6)”
The bitwise OR matching rule (1.2.840.113556.1.4.804) checks to see if any of the bits in the assertion string are represented in the attribute value. (This is somewhat analogous to a substring search.) In this example, the userAccountControl value must have any of the bits which are set in the bit field of 6, meaning that the attribute value can be 2, 4, or 6.
"(UserAccountControl:1.2.840.113556.1.4.804:=6)"
Bitwise searches can be used with Windows-Red Hat Enterprise Linux integration, such as using Samba file servers.

NOTE

Microsoft has good documentation on bitwise operators at http://msdn.microsoft.com/en-us/library/aa746475.

8.5. Using Persistent Search

A persistent search is an ldapsearch which remains open even after the initial search results are returned.
Persistent searches are especially useful for applications or clients which access the Directory Server and provide two important benefits:
  • Keep a consistent and current local cache.
    Any client will query local cache before trying to connect to and query the directory. Persistent searches provide the local cache necessary to improve performance for these clients.
  • Automatically initiate directory actions.
    The persistent cache can be automatically updated as entries are modified, and the persistent search results can display what kind of modification was performed on the entry. Another application can use that output to update entries automatically, such as automatically creating an email account on a mail server for new users or generating a unique user ID number.
There are some performance considerations when running persistent searches, as well:
  • The ldapsearch does not send a notification when the client disconnects, and the change notifications are not sent for any changes made while the search is disconnected. This means that the client's cache will not be updated if it is ever disconnected and there is no good way to update the cache with any new, modified, or deleted entries that were changed while it was disconnected.
  • An attacker could open a large number of persistent searches to launch a denial of service attack.
  • A persistent search requires leaving open a TCP connection between the Directory Server and client. This should only be done if the server is configured to allow a lot of client connections and has a way to close idle connections.
  • Each persistent search runs as a separate thread inside the Directory Server.

8.5.1. An Overview of Persistent Searches

The purpose of a persistent search is to provide a continuous list of changes to the directory entries as well as the complete entries themselves, something like a hybrid search and changelog. Therefore, the search command must specify what entries to return (the search parameters) and what changes cause an entry to be returned (entry change parameters).
The persistent search command sets the change information in three aspects:
  • Whether to return all of the currently matching entries and then update the cache with changed entries or whether to only send changed entries which match the search parameters. This is the changesOnly setting.
  • What kinds of changes, such as adds or modifies, to entries are returned. This is the changetype setting.
  • Whether to display within the entry what kind of modification was performed. This is the entryChanges setting.
The persistent search command, then, has the following format:
/usr/lib64/mozldap/ldapsearch -r -C PS:changetype:changesOnly:entryChanges -b baseDN -s scope -D bindDN -w password -p port -h host (filter)
A persistent ldapsearch takes the normal ldapsearch options, such as the server connection information and bind credentials.
Additionally, the -C argument and the PS: signal that this is a persistent search. The -r argument is a recommended ldapsearch argument that prints the entries immediately to the screen as soon as they enter the buffer. This prevents the search command from buffering its output, which ultimately makes the search command appear to hang.
The term changetype:changesOnly:entryChanges is what defines the entry change parameters.
  • The only required term is the changetype, which sets what kinds of changes are returned in the persistent search. The possible values are add, modify, modrdn (for modrdn operations), delete, and any.
  • changesOnly is optional. If this value is true (1), then no entries are returned in the initial search, and entries are only returned as they are modified. If it is false (0), then all matching entries are returned in the initial search, as well as sending updated entries. The default is true.
  • entryChanges is also optional. If this value is true (1), then the type of modification is included in a changetype line in the returned entry. For example:
     dn: uid=scarter,ou=People,dc=example,dc=com
     persistentSearch-changetype: modify
    If the value is false (0), then only the entry is returned, without the type of change being noted. The default is true.

8.5.2. Running a Persistent Search

To run a persistent search, simply run an ldapsearch with the -C and -r arguments and the change parameters for the search. If no bind credentials are given, the Directory Server is accessed by the anonymous user.
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -r -C PS:any:1:0 -b dc=example,dc=com objectclass=person
The search, if the changesOnly setting is false (0), will return every matching entry in the directory, as with a normal ldapsearch. Then, as entries are modified, the persistent search returns the newly updated entry with, optionally, the type of operation which updated it (changeType).
version: 1
dn: uid=scarter,ou=People,dc=example,dc=com
persistentSearch-changetype: modify
title: manager
mail: scarter@example.com
description: test
uid: scarter
givenname: scott
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
sn: carter
cn: scott carter
In the access logs, a persistent search is identifies with the tag options=persistent.
[12/Jan/2009:12:51:54 -0500] conn=19636710736396323 op=0 SRCH base="dc=example,dc=com" scope=2 filter="(objectClass=person)" attrs=ALL options=persistent

8.6. Performing Dereferencing Searches

A dereferencing search is a quick way to trackback over cross-references in an entry and return information about the referenced entry. For example, a group entry contains references to its member's user entries. A dereferencing search for the group entry can then return information about the members — such as their locations, email addresses, or managers — along with the search results for the group.
Dereferencing simplifies many client operations. Cross-links show relationships between entries. Some operations may require getting a list of cross-links from one entry and then performing a series of subsequent searches to get information from each entry on the list. Dereferencing allows those sequences of searches to be consolidated into a single search.

IMPORTANT

The dereferencing searches are not done using MozLDAP command-line tools. The server supports dereferencing search operations; however the client tools with Red Hat Directory Server do not. Therefore, dereferencing operations must be done using OpenLDAP command-line tools version 2.4.18 or later or other clients which support dereferencing searches.
To download the appropriate OpenLDAP tools, follow the directions at http://www.openldap.org/faq/data/cache/897.html.
The format of the dereference arguments is:
-E 'deref=deref_attribute:list_of_attributes'
The deref_attribute is the attribute in the search target that contains the reference. This can be any attribute which has a DN for its value, such as member or manager.

NOTE

Not only must the value of the deref_attribute be a DN, but the actual defined syntax for the attribute must be DN syntax (1.3.6.1.4.1.1466.115.121.1.12).
The list_of_attributes is one or more attributes in the referenced entry which will be returned along with the primary search results. Multiple attributes can be separated by commas, like l,mail,cn.
Simple Dereferencing Search Command

Figure 8.3. Simple Dereferencing Search Command


The requested dereferenced information requested in the search argument is returned with the rest of the search results. For example, this dereferencing search tells the server to use the member attribute in the search target entry (the Engineers group) as the deref_attribute. It then returns the locality attribute for each member.
ldapsearch -x -D "cn=Directory Manager" -w secret -b "cn=Example,ou=Groups,dc=example,dc=com" -E 'deref=member:mail,cn' "(objectclass=*)"

# Engineers, Groups, example.com
dn: cn=Engineers,ou=Groups,dc=example,dc=com
control: 1.3.6.1.4.1.4203.666.5.16 false MIQAAADNMIQAAAA1BAZtZW1iZXIEK2NuPURld
 mVsb3BlcnMsIG91PUdyb3VwcywgZGM9ZXhhbXBsZSxkYz1jb20whAAAADIEBm1lbWJlcgQoY249VG
 VzdGVycywgb3U9R3JvdXBzLCBkYz1leGFtcGxlLGRjPWNvbTCEAAAAVAQGbWVtYmVyBCp1aWQ9ZW5
 nLCBvdT1lbmdpbmVlcmluZywgZGM9ZXhhbXBsZSxkYz1jb22ghAAAABowhAAAABQEAWwxhAAAAAsE
 CUNhbWJyaWRnZQ==
# member: <mail=jsmith@example.com><cn=John Smith>;uid=jsmith,ou=people,dc=example,dc=com
 objectClass: top
objectClass: inetuser
objectClass: groupofnames
cn: Engineers
member: uid=jsmith,ou=people,dc=example,dc=com

8.7. Using Simple Paged Results

Search results can be very large, and a part of processing the results is organizing the results. One method of doing this is using a server-side sort, which lists the results according to a sort order for an attribute. Another method is using simple paged results, a control that breaks the results into pages of a certain length.
The simple paged results control sets the number of entries to display at a time. The results can be scrolled through, a page at a time, which makes the results easier to digest. The full behavior of the control is described in RFC 2696.
Simple paged results is implemented as an LDAP control extension for the Directory Server. Its OID is 1.2.840.113556.1.4.319.
The paging itself is done in the server frontend. The search progresses as normal in the backend database, going through resource limits like the look-through and time limits as it pulls candidate entries. The backend database then forwards the list of entry IDs to the server frontend, and the frontend manipulates the results so that the appropriate page sizes are returned.
Simple Paged Results Operation

Figure 8.4. Simple Paged Results Operation


IMPORTANT

Simple paged result searches are not done using MozLDAP command-line tools. The server supports simple paged results; however the client tools with Red Hat Directory Server do not. Therefore, simple paged results operations must be done using OpenLDAP command-line tools version 2.4.18 or later or other clients which support simple paged results, such as Perl Net::LDAP.
To download the appropriate OpenLDAP tools, follow the directions at http://www.openldap.org/faq/data/cache/897.html.
The format of the simple paged result search option with OpenLDAP's ldapsearch is:
-E pg=size
The size value is the page size, or the number of entries to include per page. For example, using OpenLDAP's ldapsearch:
ldapsearch -x -D "cn=Directory Manager" -w secret -b "ou=Engineers,ou=People,dc=example,dc=com" -E pg=3 "(objectclass=*)" cn

dn: uid=jsmith,ou=Engineers,ou=People,dc=example,dc=com
   cn: John Smith

dn: uid=bjensen,ou=Engineers,ou=People,dc=example,dc=com
   cn: Barbara Jensen

dn: uid=hmartin,ou=Engineers,ou=People,dc=example,dc=com
   cn: Henry Martin

Results are sorted.
next page size (3): 5
The tag at the end shows the configured page size (the number in parentheses) from the search. After the colon, one enters the page size for the next page, so entering 5 as shown would open the next page of results with five entries.
Simple paged results can be used together with server-side sorting. Server-side sorting is a control which performs the sort process on the server rather than in a client; this is usually done for a search which uses a particular matching rule. (This behavior is defined in RFC 2891.) The OpenLDAP client tools do not support server-side sort with the simple paged results control, but other LDAP utilities such as Perl Net::LDAP do support both.
VLV indexes are similar to simple paged results in that they also return a usable browsing list of results. The main difference is in how that list is generated. Simple paged results are calculated per search, while VLV indexes are a permanent list. Overall, VLV indexes are faster for searches, but do require some server-side configuration and overhead for the server to maintain.

NOTE

Simple paged results and VLV indexes cannot be used on the same search. Simple paged results would attempt to manipulate the VLV index, which is already a browsin index. If the control is passed for a search using a VLV index, then the server returns an UNWILLING_TO_PERFORM error.
For more information on VLV indexes, see Section 7.4, “Creating Browsing (VLV) Indexes”.

Chapter 9. Managing Replication

9.1. Replication Overview
9.1.1. What Directory Units Are Replicated
9.1.2. Read-Write and Read-Only Replicas
9.1.3. Suppliers and Consumers
9.1.4. Changelog
9.1.5. Replication Identity
9.1.6. Replication Agreement
9.1.7. Replicating a Subset of Attributes with Fractional Replication
9.1.8. Compatibility with Earlier Versions of Directory Server
9.2. Replication Scenarios
9.2.1. Single-Master Replication
9.2.2. Multi-Master Replication
9.2.3. Cascading Replication
9.3. Creating the Supplier Bind DN Entry
9.4. Configuring Single-Master Replication
9.4.1. Configuring the Read-Write Replica on the Supplier Server
9.4.2. Configuring the Read-Only Replica on the Consumer
9.4.3. Creating the Replication Agreement
9.5. Configuring Multi-Master Replication
9.5.1. Configuring the Read-Write Replicas on the Supplier Servers
9.5.2. Configuring the Read-Only Replicas on the Consumer Servers
9.5.3. Setting up the Replication Agreements
9.5.4. Preventing Monopolization of the Consumer in Multi-Master Replication
9.6. Configuring Cascading Replication
9.6.1. Configuring the Read-Write Replica on the Supplier Server
9.6.2. Configuring the Read-Only Replica on the Consumer Server
9.6.3. Configuring the Read-Only Replica on the Hub
9.6.4. Setting up the Replication Agreements
9.7. Configuring Replication from the Command Line
9.7.1. Configuring Suppliers from the Command Line
9.7.2. Configuring Consumers from the Command Line
9.7.3. Configuring Hubs from the Command Line
9.7.4. Configuring Replication Agreements from the Command Line
9.7.5. Initializing Consumers Online from the Command Line
9.8. Making a Replica Updatable
9.9. Deleting the Changelog
9.9.1. Removing the Changelog
9.9.2. Moving the Changelog to a New Location
9.10. Initializing Consumers
9.10.1. When to Initialize a Consumer
9.10.2. Online Consumer Initialization Using the Console
9.10.3. Initializing Consumers Online Using the Command Line
9.10.4. Manual Consumer Initialization Using the Command Line
9.10.5. Filesystem Replica Initialization
9.11. Forcing Replication Updates
9.11.1. Forcing Replication Updates from the Console
9.11.2. Forcing Replication Updates from the Command Line
9.12. Replication over SSL
9.13. Setting Replication Timeout Periods
9.14. Replicating o=NetscapeRoot for Admin Server Failover
9.15. Replication with Earlier Releases
9.15.1. Using Legacy Replication
9.15.2. Legacy Replication and Parent Object Classes
9.15.3. Configuring Legacy Replication
9.16. Using the Retro Changelog Plug-in
9.16.1. Enabling the Retro Changelog Plug-in
9.16.2. Trimming the Retro Changelog
9.16.3. Searching and Modifying the Retro Changelog
9.16.4. Retro Changelog and the Access Control Policy
9.17. Monitoring Replication Status
9.17.1. Monitoring Replication Status from the Directory Server Console
9.17.2. Monitoring Replication Status from Administration Express
9.18. Solving Common Replication Conflicts
9.18.1. Solving Naming Conflicts
9.18.2. Solving Orphan Entry Conflicts
9.18.3. Solving Potential Interoperability Problems
9.19. Troubleshooting Replication-Related Problems
Replication is the mechanism by which directory data is automatically copied from one Red Hat Directory Server instance to another; it is an important mechanism for extending the directory service beyond a single server configuration. This chapter describes the tasks to be performed on the master and consumer servers to set up single-master replication, multi-master replication, and cascading replication.

9.1. Replication Overview

Replication is the mechanism by which directory data is automatically copied from one Directory Server to another. Updates of any kind — entry additions, modifications, or even deletions — are automatically mirrored to other Directory Servers using replication.

9.1.1. What Directory Units Are Replicated

The smallest unit of of the directory which can be replicated is a database. This means that one can replicate an entire database but not a subtree within a database. Therefore, when creating the directory tree, consider any replication plans as part of determining how to distribute information.
Replication also requires that one database correspond to one suffix. This means that a suffix (or namespace) that is distributed over two or more databases using custom distribution logic cannot be replicated. For more information on this topic, see Section 2.2, “Creating and Maintaining Databases”.

9.1.2. Read-Write and Read-Only Replicas

A database that participates in replication is called a replica. There are two kinds of replicas: read-write or read-only. A read-write replica contains master copies of directory information and can be updated. A read-only replica services read, search, and compare requests, but refers all update operations to read-write replicas. A server can hold any number of read-only or read-write replicas.

9.1.3. Suppliers and Consumers

A server that holds a replica that is copied to a replica on a different server is called a supplier for that replica. A server that holds a replica that is copied from a different server is called a consumer for that replica. Generally, the replica on the supplier server is a read-write replica, and the one on the consumer server is a read-only replica, with two exceptions:
Replication is always initiated by the supplier server, never by the consumer (supplier-initiated replication). Supplier-initiated replication allows a supplier server to be configured to push data to multiple consumer servers.

9.1.4. Changelog

Every supplier server maintains a changelog, a record of all changes that a supplier or hub needs to send to its consumers. A changelog is a special kind of database that describes the modifications that have occurred on a replica. The supplier server then replays these modifications to the replicas stored on consumer servers or to other suppliers, in the case of multi-master replication.
When an entry is modified, a change record describing the LDAP operation that was performed is recorded in the changelog.
In Directory Server, the changelog is only intended for internal use by the server. For other applications to read the changelog, use the Retro Changelog Plug-in, as described in Section 9.16, “Using the Retro Changelog Plug-in”.

9.1.5. Replication Identity

When replication occurs between two servers, the replication process uses a special entry, called the replication manager entry, to identify replication protocol exchanges and to control access to the directory data. The replication manager entry, or any entry used during replication, must meet the following criteria:
  • It is created on the consumer server (or hub) and not on the supplier server.
  • Create this entry on every server that receives updates from another server, meaning on every hub or dedicated consumer.
  • When a replica is configured as a consumer or hub (a replica which receives updates from another server), this entry must be specified as the one authorized to perform replication updates.
  • The replication agreement is created on the supplier server, the DN of this entry must be specified in the replication agreement.
  • The supplier bind DN entry must not be part of the replicated database for security reasons.
  • This entry, with its special user profile, bypasses all access control rules defined on the consumer server for the database involved in that replication agreement.

NOTE

In the Directory Server Console, this replication manager entry is referred to as the supplier bind DN, which may be misleading because the entry does not actually exist on the supplier server. It is called the supplier bind DN because it is the entry which the supplier uses to bind to the consumer. This entry actually exists, then, on the consumer.
For more information on creating the replication manager entry, see Section 9.3, “Creating the Supplier Bind DN Entry”.

9.1.6. Replication Agreement

Directory Servers use replication agreements to define their replication configuration. A replication agreement describes replication between one supplier and one consumer only. The agreement is configured on the supplier server and must specify all required replication information:
  • The database to be replicated.
  • The consumer server to which the data is pushed.
  • The days and times during which replication can occur.
  • The DN and credentials that the supplier server must use to bind (the replication manager entry or supplier bind DN).
  • How the connection is secured (SSL, client authentication).
  • Any attributes that will not be replicated (fractional replication).

9.1.7. Replicating a Subset of Attributes with Fractional Replication

Fractional replication sets a specific subset of attributes that will not be transmitted from a supplier to the consumer (or another supplier). Administrators can therefore replicate a database without replicating all the information that it contains or all of the information in every entry.
Fractional replication is enabled and configured per replication agreement. Excluding attributes from replication is applied equally to all entries within the replication agreement's scope.
As far as the consumer server is concerned, the excluded attributes always have no value. Therefore, a client performing a search against the consumer server will never see the excluded attributes. Similarly, should it perform a search that specifies those attributes in its filter, no entries will match.

9.1.8. Compatibility with Earlier Versions of Directory Server

The replication mechanism in Directory Server 8.2 is different from the mechanism used in 4.x of Directory Server. Compatibility is provided through two Directory Server plug-ins:
  • Legacy Replication Plug-in. The Legacy Replication Plug-in makes a Directory Server 8.2 instance behave as a 4.x Directory Server in a consumer role. For information on how to implement legacy replication using this plug-in, see Section 9.15, “Replication with Earlier Releases”.
  • Retro Changelog Plug-in. The Retro Changelog Plug-in can be used for a Directory Server supplier to maintain a 4.x-style changelog. This is sometimes necessary for legacy applications that have a dependency on the Directory Server 4.x changelog format because they read information from the changelog. For more information on the Retro Changelog Plug-in, see Section 9.16, “Using the Retro Changelog Plug-in”.

9.2. Replication Scenarios

These basic strategies can be combined in a variety of ways to create the best replication environment.

NOTE

Whatever replication scenario is implemented, consider schema replication. To avoid conflict resolution loops, the Referential Integrity Plug-in should only be enabled on one supplier replica in a multi-master replication environment. The plug-in is off by default.

9.2.1. Single-Master Replication

In the simplest replication scenario, the master copy of directory data is held in a single read-write replica on one server called the supplier server. The supplier server also maintains changelog for this replica. On another server, called the consumer server, there can be multiple read-only replicas. Such scenarios are called single-master configurations. Figure 9.1, “Single-Master Replication” shows an example of single-master replication.
Single-Master Replication

Figure 9.1. Single-Master Replication


In this particular configuration, the ou=people,dc=example,dc=com suffix receives a large number of search requests. Therefore, to distribute the load, this tree, which is mastered on Server A, is replicated to two read-only replicas located on Server B and Server C.
For information on setting up a single-master replication environment, see Section 9.4, “Configuring Single-Master Replication”.

9.2.2. Multi-Master Replication

Directory Server also supports complex replication scenarios in which the same suffix (database) can be mastered on many servers. This suffix is held in a read-write replica on each server. This means that each server maintains a changelog for the read-write replica.
Multi-master replication in Directory Server supports up to four masters, an unlimited number of hub suppliers, and an unlimited number of consumer servers. Each consumer server holds a read-only replica. The consumers can receive updates from any or all the suppliers. The consumers also have referrals defined for all the suppliers to forward any update requests that the consumers receive. Such scenarios are called multi-master configurations.
Figure 9.2, “Multi-Master Replication (Two Masters)” shows an example of multi-master replication scenario with two supplier servers and two consumer servers.
Multi-Master Replication (Two Masters)

Figure 9.2. Multi-Master Replication (Two Masters)


Figure 9.3, “Multi-Master Replication (Four Masters)” shows a sample of multi-master replication scenario with four supplier servers and eight consumer servers. In this sample setup, each supplier server is configured with ten replication agreements to feed data to two other supplier servers and all eight consumer servers.
Multi-Master Replication (Four Masters)

Figure 9.3. Multi-Master Replication (Four Masters)


Multi-master configurations have the following advantages:
  • Automatic write failover when one supplier is inaccessible.
  • Updates are made on a local supplier in a geographically distributed environment.

NOTE

The speed that replication proceeds depends on the speed of the network. Plan changes and directory configuration accordingly, and realize that changes to one directory may not be quickly replicated to other directories over slow links, such as wide-area networks, in geographically-distributed environments.
For the procedure to set up multi-master replication, see Section 9.5, “Configuring Multi-Master Replication”.

9.2.3. Cascading Replication

In a cascading replication scenario, one server, a hub, acts both as a consumer and a supplier. It holds a read-only replica and maintains a changelog, so it receives updates from the supplier server that holds the master copy of the data and, in turn, supplies those updates to the consumer. Cascading replication is very useful for balancing heavy traffic loads or to keep master servers based locally in geographically-distributed environments.
Figure 9.4, “Cascading Replication” shows an example of a simple cascading replication scenario, though it is possible to create more complex scenarios with several hub servers.
Cascading Replication

Figure 9.4. Cascading Replication


For information on setting up cascading replication, see Section 9.6, “Configuring Cascading Replication”.

NOTE

Multi-master and cascading replication can be combined. For example, in the multi-master scenario illustrated in Figure 9.2, “Multi-Master Replication (Two Masters)”, Server C and Server D could be hub servers that would replicate to any number of consumer servers.

9.3. Creating the Supplier Bind DN Entry

A critical part of setting up replication is to create the entry, called the replication manager or supplier bind DN entry, that the suppliers use to bind to the consumer servers to perform replication updates.
The supplier bind DN must meet the following criteria:
  • It must be unique.
  • It must be created on the consumer server (or hub) and not on the supplier server.
  • It must correspond to an actual entry on the consumer server.
  • It must be created on every server that receives updates from another server.
  • It must not be part of the replicated database for security reasons.
  • It must be defined in the replication agreement on the supplier server.
  • It must have an idle timeout period set to a high enough limit to allow the initialization process for large databases to complete. Using the nsIdleTimeOut operational attribute allows the replication manager entry to override the global nsslapd-idletimeout setting.
For example, the entry cn=Replication Manager,cn=config can be created under the cn=config tree on the consumer server. This would be the supplier bind DN that all supplier servers would use to bind to the consumer to perform replication operations.

NOTE

Avoid creating simple entries under the cn=config entry in the dse.ldif file. The cn=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, and particularly entries that are likely to be updated frequently, are stored under cn=config, performance will suffer. However, although Red Hat recommends not storing simple user entries under cn=config for performance reasons, it can be useful to store special user entries such as the Directory Manager entry or replication manager (supplier bind DN) entry under cn=config since this centralizes configuration information.
On each server that acts as a consumer in replication agreements, create a special entry that the supplier will use to bind to the consumers. Make sure to create the entry with the attributes required by the authentication method specified in the replication agreement.
  1. Stop the Directory Server. If the server is not stopped, the changes to the dse.ldif file will not be saved. See Section 1.4, “Starting and Stopping Servers” for more information on stopping the server.
  2. Create a new entry, such as cn=replication manager,cn=config, in the dse.ldif file.
  3. Specify a userPassword attribute-value pair.
  4. Set an nsIdleTimeout period that gives the replication user a long enough time limit to allow replication initialization on large databases to complete.
  5. If password expiration policy is enabled or ever will be enabled, disable it on the replication manager entry to prevent replication from failing due to passwords expiring. To disable the password expiration policy on the userPassword attribute, add the passwordExpirationTime attribute with a value of 20380119031407Z, which means that the password will never expire.
  6. Restart the Directory Server. See Section 1.4, “Starting and Stopping Servers” for more information on starting the server.
The final entry should resemble Example 9.1, “Example Supplier Bind DN Entry”.

Example 9.1. Example Supplier Bind DN Entry

dn: cn=replication manager,cn=config 
objectClass: inetorgperson 
objectClass: person 
objectClass: top 
cn: replication manager 
sn: RM 
userPassword: password 
passwordExpirationTime: 20380119031407Z
nsIdleTimeout: 0

When configuring a replica as a consumer, use the DN of this entry to define the supplier bind DN.

9.4. Configuring Single-Master Replication

To set up single-master replication such as the configuration shown in Figure 9.1, “Single-Master Replication”, between supplier Server A, which holds a read-write replica, and the two consumers Server B and Server C, which each hold a read-only replica, there are three major steps:

9.4.1. Configuring the Read-Write Replica on the Supplier Server

  1. Specify the supplier settings for the server.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, select the Replication folder.
    3. In the right-hand side of the window, select the Supplier Settings tab.
    4. Check the Enable Changelog checkbox.
      This activates all of the fields in the pane below that were previously grayed out.
    5. Specify a changelog by clicking the Use default button, or click the Browse button to display a file selector.
    6. Set the changelog parameters for the number and age of the log files.
      Clear the unlimited checkboxes to specify different values.
    7. Click Save.
  2. Specify the replication settings required for a read-write replica.
    1. In the navigation tree on the Configuration tab, expand the Replication node, and highlight the database to replicate.
      The Replica Settings tab opens in the right-hand side of the window.
    2. Check the Enable Replica checkbox.
    3. In the Replica Role section, select the Single Master radio button.
    4. In the Common Settings section, specify a Replica ID, which is an integer between 1 and 65534, inclusive.
      The replica ID must be unique for a given suffix, different from any other ID used for read-write replicas on this server and on other servers.
    5. In the Common Settings section, specify a purge delay in the Purge delay field.
      The purge delay is how often the state information stored for the replicated entries is deleted.
    6. Click Save.

9.4.2. Configuring the Read-Only Replica on the Consumer

  1. Create the database for the read-only replica if it does not exist. See Section 2.1.1, “Creating Suffixes” for instructions on creating suffixes.
  2. Create the entry for the supplier bind DN on the consumer server if it does not exist. The supplier bind DN is the special entry that the supplier will use to bind to the consumer. This is described in Section 9.3, “Creating the Supplier Bind DN Entry”.
  3. Specify the replication settings required for a read-only replica.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, expand the Replication folder, and highlight the replica database.
      The Replica Settings tab for that database opens in the right-hand side of the window.
    3. Check the Enable Replica checkbox.
    4. In the Replica Role section, select the Dedicated Consumer radio button.
    5. In the Common Settings section, specify a purge delay in the Purge delay field.
      This option indicates how often the state information stored for the replicated entries is purged.
    6. In the Update Settings section, specify the bind DN that the supplier will use to bind to the replica. Enter the supplier bind DN in the Enter a new Supplier DN field, and click Add. The supplier bind DN appears in the Current Supplier DNs list.
      The supplier bind DN should be the entry created in step 2. The supplier bind DN is a privileged user because it is not subject to access control.

      NOTE

      There can be multiple supplier bind DNs per consumer but only one supplier DN per replication agreement.
    7. Specify the URL for any supplier servers to which to refer updates.
      By default, all updates are first referred to the supplier servers that are specified here. If no suppliers are set here, updates are referred to the supplier servers that have a replication agreement that includes the current replica.
      Automatic referrals assume that clients bind over a regular connection; this has a URL in the form ldap://hostname:port. For clients to bind to the supplier using SSL, use this field to specify a referral of the form ldaps://hostname:port, where the s in ldaps indicates a secure connection.
  4. Click Save.
Repeat these steps for every consumer server in the replication configuration.

9.4.3. Creating the Replication Agreement

Create one replication agreement for each read-only replica. For example, in the scenario illustrated in Figure 9.1, “Single-Master Replication”, Server A has two replication agreements, one for Server B and one for Server C.
  1. In the navigation tree of the Configuration tab, right-click the database to replicate, and select New Replication Agreement.
    Alternatively, highlight the database, and select New Replication Agreement from the Object menu to start the Replication Agreement Wizard.
  2. In the first screen, fill in a name and description for the replication agreement, and hit Next.
  3. In the Source and Destination screen, fill in the URL for the consumer and the supplier bind DN and password on that consumer. If the target server is not available, hit in other to fill in the information manually.
    • Unless there is more than one instance of Directory Server configured, by default, there are no consumers available in the drop-down menu.
    • The port listed is the non-SSL port, even if the Directory Server instance is configured to run over SSL. This port number is used only for identification of the Directory Server instance in the Console; it does not specify the actual port number or protocol that is used for replication.
    • If SSL is enabled on the servers, it is possible to select the Using encrypted SSL connection radio button for SSL client authentication. Otherwise, fill in the supplier bind DN and password.

      NOTE

      If attribute encryption is enabled, a secure connection must be used for the encrypted attributes to be replicated.
  4. Select the connection type. There are three options:
    • Use LDAP. This sets a standard, unencrypted connection.
    • Use TLS/SSL. This uses a secure connection over the server's secure LDAPS port, such as 636. This setting is required to use TLS/SSL.
    • Use Start TLS. This uses Start TLS to establish a secure connection over the server's standard port.

    NOTE

    If secure binds are required for simple password authentication (Section 13.5.1, “Requiring Secure Binds”), then any replication operations will fail unless they occur over a secure connection. Using a secure connection (SSL/TLS and Start TLS connections or SASL authentication) is recommended, anyway.
  5. Select the appropriate authentication method and supply the required information. This gives the information that the supplier uses to authenticate and bind to the consumer server to send updates.
    • Simple means that the server connects over the standard port with no encryption. The only required information is the bind DN and password for the Replication Manager (which must exist on the consumer server).
    • Server TLS/SSL Certificate uses the supplier's SSL certificate to authenticate to the consumer server. A certificate must be installed on the supplier for certificate-based authentication, and the consumer server must have certificate mapping configured so that it can map the subject DN in the supplier's certificate to its Replication Manager entry.
      Configuring SSL and certificate mapping is described in Section 14.2, “Using TLS/SSL”.
    • SASL/DIGEST-MD5, like simple authentication, requires only the bind DN and password to authenticate. This can run over a standard or SSL/TLS connection.
    • SASL/GSSAPI requires the supplier server to have a Kerberos keytab (as in Section 14.3.4.2, “About the KDC Server and Keytabs”), and the consumer server to have a SASL mapping to map the supplier's principal to the real replication manager entry (as in Section 14.3.5.1, “Configuring SASL Identity Mapping from the Console”).
  6. Fractional replication controls which entry attributes are replicated between servers. By default, all attributes are replicated. To select attributes that will not be replicated to the consumer, check the Enable Fractional Replication checkbox. Then, highlight the attribute (or attributes) in the Included column on the right, and click Remove. All attributes that will not be replicated are listed in the Excluded column on the left, as well as in the summary the replication agreement is complete.
  7. Set the schedule for when replication runs. By default, replication runs continually.

    NOTE

    The replication schedule cannot cross midnight (0000). So, it is possible to set a schedule that begins at 0001 and ends at 2359 on the same day, but it is not possible to set one that begins at 2359 on one day and ends at 0001 on the next.
    Hit Next.
  8. Set when the consumer is initialized. Initializing a consumer manually copies all data over from the supplier to the consumer. The default is to create an initialization file (an LDIF of all supplier data) so that the consumer can be initialized later. It is also possible to initialize the consumer as soon as the replication agreement is completed or not at all. For information on initializing consumers, see Section 9.10, “Initializing Consumers”.

    NOTE

    Replication will not begin until the consumer is initialized.
    Hit Next.
  9. The final screen shows the settings for the replication agreement, as it will be included in the dse.ldif file. Hit Done to save the agreement.
The replication agreement is set up.

NOTE

After creating a replication agreement, the connection type (SSL or non-SSL) cannot be changed because LDAP and LDAPS connections use different ports. To change the connection type, re-create the replication agreement.

9.5. Configuring Multi-Master Replication

In a multi-master configuration, many suppliers can accept updates, synchronize with each other, and update all consumers. The consumers can send referrals for updates to all masters.
Directory Server supports four-way multi-master replication, meaning that there can be up to four masters (and an unlimited number of hub suppliers) in a single replication scenario. Directory Server allows an unlimited number of consumers.
To set up multi-master replication, set up all of the consumers first, then set up the suppliers, and last, initialize all of the databases.

NOTE

More than 10 databases running with replication or more than on a supplier can cause performance degradation. To support that many consumers, introduce hub replicas between the suppliers and consumers. See Section 9.6, “Configuring Cascading Replication”.

9.5.1. Configuring the Read-Write Replicas on the Supplier Servers

Set up each supplier server. The first supplier configured should be used to initialize the other suppliers in the multi-master replication environment.
  1. Specify the supplier settings for the server.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, select the Replication folder.
    3. In the right-hand side of the window, select the Supplier Settings tab.
    4. Check the Enable Changelog checkbox.
      This activates all of the fields in the pane below that were previously grayed out.
    5. Specify a changelog by clicking the Use default button, or click the Browse button to display a file selector.
    6. Set the changelog parameters for the number and age of the log files.
      Clear the unlimited checkboxes to specify different values.
    7. Click Save.
  2. Create the entry for the supplier bind DN on the consumer server if it does not exist. This is the special entry that the other suppliers will use to bind to this supplier, as in other supplier-consumer relationships. This is described in Section 9.3, “Creating the Supplier Bind DN Entry”.

    NOTE

    For multi-master replication, it is necessary to create this supplier bind DN on the supplier servers as well as the consumers because the suppliers act as both consumer and supplier to the other supplier servers.
  3. Specify the replication settings for the multi-mastered read-write replica.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, expand the Replication folder, and highlight the replica database.
      The Replica Settings tab for that database opens in the right-hand side of the window.
    3. Check the Enable Replica checkbox.
    4. In the Replica Role section, select the Multiple Master radio button.
    5. In the Common Settings section, specify a Replica ID, which is an integer between 1 and 65534, inclusive.
      The replica ID must be unique for a given suffix, different from any other ID used for read-write replicas on this server and on other servers.
    6. In the Common Settings section, specify a purge delay in the Purge delay field.
      The purge delay is how often the state information stored for the replicated entries is deleted.
    7. In the Update Settings section, specify the bind DN that the supplier will use to bind to the replica. Enter the supplier bind DN in the Enter a new Supplier DN field, and click Add. The supplier bind DN appears in the Current Supplier DNs list.
      The supplier bind DN should be the entry created in step 2. The supplier bind DN is a privileged user because it is not subject to access control in the replicated database.

      NOTE

      There can be multiple supplier bind DNs per consumer but only one supplier DN per replication agreement.
    8. Specify the URL for any supplier servers to which to refer updates, such as the other suppliers in the multi-master replication set. Only specify the URL for the supplier server.
      For clients to bind using SSL, specify a URL beginning with ldaps://.
    9. Click Save.

9.5.2. Configuring the Read-Only Replicas on the Consumer Servers

First, configure every consumer before creating any replication agreements.
  1. Create the database for the read-only replica if it does not exist. See Section 2.1.1, “Creating Suffixes” for instructions on creating suffixes.
  2. Create the entry for the supplier bind DN on the consumer server if it does not exist. The supplier bind DN is the special entry that the supplier will use to bind to the consumer. This is described in Section 9.3, “Creating the Supplier Bind DN Entry”.
  3. Specify the replication settings required for a read-only replica.
    1. In the Directory Server Console, select the Configuration tab.
    2. In the navigation tree, expand the Replication folder, and highlight the replica database.
      The