Administration Guide

Red Hat Directory Server 9

Updated for Directory Server 9.1.2

Marc Muehlfeld

Red Hat Customer Content Services

Petr Bokoč

Red Hat Customer Content Services

Ella Deon Ballard

Red Hat Customer Content Services

Abstract

This guide covers both GUI and command-line procedures for managing Directory Server instances and databases.
This documentation is no longer maintained. For details, see Deprecated Documentation.

Deprecated Documentation

Important

Note that as of June 10, 2017, the support for Red Hat Directory Server 9 has ended. For details, see Red Hat Directory Server Life Cycle policy. Red Hat recommends users of Directory Server 9 to update to the latest version.
Due to the end of the maintenance phase of this product, this documentation is no longer updated. Use it only as a reference!

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 6 (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. Brackets

Square brackets ([]) are used to indicate an alternative element in a name. For example, if a tool is available in /usr/lib on 32-bit systems and in /usr/lib64 on 64-bit systems, then the tool location may be represented as /usr/lib[64].

2.3. Client Tool Information

The tools for Red Hat Directory Server are located in the /usr/bin and the /usr/sbin directories.

Important

The LDAP tools such as ldapmodify and ldapsearch from OpenLDAP use SASL connections by default. To perform a simple bind using a user name and password, use the -x argument to disable SASL.

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 Red Hat Directory Server Deployment Guide describes many of the basic directory and architectural concepts that you need to deploy, install, and administer a directory service successfully.
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.
The Directory Server Administrator's Guide describes how to set up, configure, and administer Red Hat Directory Server and its contents.
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, schema elements, 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 Plug-in Programmer's Guide describes how to write server plug-ins in order to customize and extend the capabilities of Directory Server.
  • The Red Hat Directory Server Performance Tuning Guide contains features to monitor overall Directory Server and database performance, to tune attributes for specific operations, and to tune the server and database for optimum performance.
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 https://access.redhat.com/site/documentation/Red_Hat_Directory_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 9.0.
  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.

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 9.0 is comprised of several components, which work in tandem:
  • The Directory Server is the core LDAP server daemon. It is compliant with LDAP v3 standards. This component includes command-line server management and administration programs and scripts for common operations like export and backing up databases.
  • The Directory Server Console is the user interface that simplifies managing users, groups, and other LDAP data for your enterprise. The Console is used for all aspects of server management, including making backups; configuring security, replication, and databases; adding entries; and monitoring servers and viewing statistics.
  • The 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 9.0, including prerequisites and hardware or platform requirements.

1.1.1. Required JRE

Red Hat Directory Server 9.0 requires the Oracle Java Runtime Environment (JRE) 1.8.0 or OpenJDK 1.8.0 for Red Hat Enterprise Linux 5 and 6.

Important

It is not possible to manage instances of Directory Server older than 8.1 (which used JRE 1.5) with the 9.0 Directory Server Console because they are using different JRE versions.

1.1.2. Directory Server Supported Platforms

Directory Server 9.0 is supported on the following platforms:
  • Red Hat Enterprise Linux 6 (32-bit)
  • Red Hat Enterprise Linux 6 (64-bit)

Note

Red Hat Directory Server 9.0 is supported running on a virtual guest on a Red Hat Enterprise Linux virtual server.

1.1.3. Directory Server Console Supported Platforms

The Directory Server Console is supported on the following platforms:
  • Red Hat Enterprise Linux 5 (32-bit)
  • Red Hat Enterprise Linux 5 (64-bit)
  • Red Hat Enterprise Linux 6 (32-bit)
  • Red Hat Enterprise Linux 6 (64-bit)
  • Microsoft Windows Server 2008 (32-bit)
  • Microsoft Windows Server 2008 (64-bit)

1.1.4. Password Sync Service Platforms

The Password Sync Service works with these Microsoft Windows services:
  • Active Directory on Microsoft Windows Server 2008 (32-bit)
  • Active Directory on Microsoft Windows Server 2008 (64-bit)

1.1.5. Web Application Browser Support

Directory Server 9.0 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 9.0 conforms to the Filesystem Hierarchy Standards. For more information on FHS, see the FHS homepage, http://www.pathname.com/fhs/. The files and directories installed with Directory Server are listed in the tables below for each supported platform.
In the file locations listed in the following tables, instance is the server instance name that was given during setup. By default, this is the leftmost component of the fully-qualified host and domain name. For example, if the host name 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 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
Certificate and key databases /etc/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 5 and 6 (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
Certificate and key databases /etc/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. 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 7.4.4, “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.3.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.3.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.3.3. Starting and Stopping Admin Server

The Admin Server service is stopped and started using system tools on Red Hat Enterprise Linux. For example, on Red Hat Enterprise Linux 6 (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.4. Starting the Console

1.4.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 Oracle Java Runtime Environment (JRE) or OpenJDK version is set in the PATH variable before launching the Console. To display the version and vendor information about Java on your system, enter:
java -version
The login screen prompts for the user name, 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 user name. 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.4.2. Logging into Directory Server

After starting the Directory Server Console, a login screen opens, requiring the user name 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 user name and password at the login box.

1.4.3. Changing the 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.4.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.5. 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.
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    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.6. 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.

1.6.1. Changing Standard Port Numbers

  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.
  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. Change the SELinux labels for the Directory Server ports so that the new port number is used in the Directory Server policies. By default, only port 389 is labeled. The process for labeling ports is covered in Section 1.10.6, “Labeling SSL/TLS Ports”. For example:
    /usr/sbin/semanage port -a -t ldap_port_t -p tcp 1389

    Warning

    If the SELinux label is not reset, then the Directory Server will not be able to be restarted.
  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.6.2. Changing SSL Port Numbers

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 the LDAPS port:
  1. Make sure that the CA certificate used to issue the Directory Server instance's certificate is in the Admin Server certificate database. Importing CA certificates for the Admin Server is the same as the Directory Server process described in Section 7.3.2, “Trusting the Certificate Authority”.
  2. The secure port can be configured using the Directory Server Console, much like the process in Section 1.6.1, “Changing Standard Port Numbers” (only setting the value in the Encrypted Port field). However, in some circumstances, such as if there are multiple Directory Server instances on the same machine, where changing port numbers may not be possible through the Directory Server Console. It may be be better to use ldapmodify to change the port number.
    For example:
    [root@server ~]# ldapmodify -x -h server.example.com -p 1389 -D "cn=directory manager" -W
    dn: cn=config
    replace: nsslapd-securePort
    nsslapd-securePort: 1636
  3. Edit the corresponding port configuration for the Directory Server instance in th Admin Server configuration (o=netscaperoot).
    First, search for the current configuration:
    [root@server ~]# ldapsearch -x -h config-ds.example.com -p 389 -D "cn=directory manager" -W -b "cn=slapd-ID,cn=389 Directory Server,cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot" -s base "(objectclass=*)"
    nsSecureServerPort
    
    dn: cn=slapd-ID,cn=389 Directory Server,cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot
    nsSecureServerPort: 636
    Then, edit the configuration:
    [root@server ~]# ldapmodify -x -h config-ds.example.com -p 389 -D "cn=directory manager" -WW
    
    dn: cn=slapd-ID,cn=389 Directory Server,cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot
    replace: nsSecureServerPort
    nsSecureServerPort: 1636
  4. Start the Directory Server Console for the instance and confirm that the new SSL port number is listed in the Configuration tab.
  5. Optionally, select the Use SSL in Console check box.
  6. Change the SELinux labels for the Directory Server ports so that the new port number is used in the Directory Server policies. By default, only port 389 is labeled. The process for labeling ports is covered in Section 1.10.6, “Labeling SSL/TLS Ports”. For example:
    /usr/sbin/semanage port -a -t ldap_port_t -p tcp 1636

    Warning

    If the SELinux label is not reset, then the Directory Server will not be able to be restarted.
  7. Restart the Directory Server instance.

1.7. 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).
    • 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.8. 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 administrative tasks for all plug-ins.

1.8.1. Enabling Plug-ins in the Directory Server Console

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 check box. To enable the plug-in, check this check box.
  5. Click Save.
  6. Restart the Directory Server.
    service dirsrv restart instance_name

Note

When a plug-in is disabled, all of the details about the plug-in — such as its version and its vendor — are not displayed in the Directory Server Console; all details fields show NONE.
Once a plug-in is enabled, those details will not be displayed in the Console until the Directory Server is restarted (loading the new plug-in configuration) and the Directory Server Console is refreshed.

1.8.2. Enabling Plug-ins in the Command Line

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:
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

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

1.8.3. 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:
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

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

Important

Don not 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.9. Managing Core Server Attributes

The Directory Server configuration itself is stored in the dse.ldif file, which contains the server configuration entries like cn=config. The server entry itself is defined through a finite and strict set of attributes called core server configuration attributes. Although these attributes can be changed, no attributes can be added to the core server configuration and none can be deleted (except under very limited circumstances, as described in Section 1.9.2, “Configuration Attributes Which Can Be Deleted”).
This is described in more detail in the overview sections of the "Server Instance File Reference" chapter in the Directory Server Configuration and Command-Line Tool Reference.
This section provides details on how to check which core server attributes require that the server be restarted and how to check or change which core server configuration attributes can be deleted.

1.9.1. Configuration Attributes Requiring Server Restart

Some configuration attributes cannot be altered while the server is running. In these cases, for the changes to take effect, the server needs to be shut down and restarted. The modifications should be made either through the Directory Server Console or by manually editing the dse.ldif file when the dirsrv service is stopped.
Some of the attributes that require a server restart for any changes to take effect are listed below. This list is not exhaustive; to see a complete list, run ldapsearch and search for the nsslapd-requiresrestart attribute. For example:
ldapsearch -D "cn=directory manager" -W -p 389 -h server.example.com -b "cn=config" -s sub -x "(objectclass=*)" | grep nsslapd-requiresrestart
nsslapd-cachesize nsslapd-certdir nsslapd-dbcachesize
nsslapd-dbncache nsslapd-plugin nsslapd-changelogdir
nsslapd-changelogmaxage nsslapd-changelogmaxentries nsslapd-port
nsslapd-schemadir nsslapd-saslpath nsslapd-secureport
nsslapd-tmpdir nsSSL2 nsSSL3
nsTLS1 nsSSLclientauth nsSSLSessionTimeout
nsslapd-conntablesize nsslapd-lockdir nsslapd-maxdescriptors
nsslapd-reservedescriptors nsslapd-listenhost nsslapd-schema-ignore-trailing-spaces
nsslapd-securelistenhost nsslapd-workingdir nsslapd-return-exact-case
nsslapd-maxbersize[a] nsslapd-allowed-to-delete-attrs
[a] Although this attribute requires a restart, it is not returned in the search.

1.9.2. Configuration Attributes Which Can Be Deleted

Core server configuration attributes cannot be deleted, by default. All core configuration attributes are present, even if they are not written in the dse.ldif file, because they all have default values used by the server. Deleting any of those attributes is generally not allowed because the server requires that those attributes be present for it to run.
The nsslapd-allowed-to-delete-attrs parameter lists core configuration attributes which are allowed to be deleted from the configuration. Delete operations for those attributes will succeed.
The value of nsslapd-allowed-to-delete-attrs is a space-separated list of attribute names. By default, only two attributes are listed:
nsslapd-allowed-to-delete-attrs: nsslapd-listenhost nsslapd-securelistenhost
This can be changed using ldapmodify to add attributes to the list. Since this is a single-valued attribute, the entire list must be given in the modify statement; the modify operation overwrites the previous value, it does not append new values to it.
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=config
changetype: modify
replace: nsslapd-allowed-to-delete-attrs
nsslapd-allowed-to-delete-attrs: nsslapd-listenhost nsslapd-securelistenhost nsslapd-rewrite-rfc1274

Warning

Be extremely cautious about adding core server configuration attributes to the list of deletable attributes. Some attributes are critical for the server to operate, and deleting those attributes could cause the server not to run.
To return the list of attributes which can be deleted, use grep:
# egrep nsslapd-allowed-to-delete-attrs /etc/dirsrv/slapd-instance_name/dse.ldif

nsslapd-allowed-to-delete-attrs: nsslapd-listenhost nsslapd-securelistenhost nsslapd-rewrite-rfc1274

1.10. Managing SELinux with the Directory Server

SELinux is a security function in Linux that categorizes files, directories, ports, processes, users, and other objects on the server. Each object is placed in an appropriate security context to define how the object is allowed to behave on the server through its role, user, and security level. These roles for objects are grouped in domains, and SELinux rules define how the objects in one domain are allowed to interact with objects in another domain.
SELinux itself is much more complex to manage and implement than what is described here. This section is concerned only with giving the SELinux details for the Directory Server. Both the Fedora project and the National Security Agency have excellent resources for learning about SELinux.

Note

SELinux is a feature of Red Hat Enterprise Linux and, as such, is covered in the Red Hat Enterprise Linux SELinux Guide at https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Security-Enhanced_Linux/index.html.

1.10.1. SELinux Definitions for the Directory Server

SELinux has three different levels of enforcement: disabled (no SELinux), permissive (where the rules are lax), and enforcing (where all rules are strictly enforced). Red Hat Directory Server has defined SELinux policies that allow it to run as normal under strict SELinux enforcing mode, with a caveat. The Directory Server can run in different modes, one for normal operations and one for database operations like importing (ldif2db mode). The SELinux policies for the Directory Server only apply to normal mode.
By default, the Directory Server runs confined by SELinux policies.
The Directory Server processes are contained within the dirsrv_t domain. Ports used by the Directory Server instances are contained within the ldap_port_tdomain.
Table 1.4, “Summary of Directory Server SELinux Policies” lists the security contexts and domains for the major components of the Directory Server.

Table 1.4. Summary of Directory Server SELinux Policies

File Path Security Context Description
dirsrv_t Domain   
/etc/dirsrv/* dirsrv_config_t Configuration files for the different instances.
/usr/sbin/ns-slapd dirsrv_exec_t The main server executable.
/usr/sbin/{start|restart|stop}-dirsrv initrc_exec_t The server start, restart, and stop scripts.
/usr/lib/dirsrv/*
/usr/lib64/dirsrv/*
lib_t The server and plug-in libraries.
/usr/share/dirsrv/* dirsrv_share_t The property files and templates for new instances.
/var/lib/dirsrv/* dirsrv_var_lib_t The default directories for database files, LDIF files, and backup files.
/var/lock/dirsrv/* dirsrv_var_lock_t Lock files.
/var/log/dirsrv/* dirsrv_var_log_t The server instance log files.
/var/run/dirsrv/* dirsrv_var_run_t The instance PID files and the SNMP statistics file.
ldap_t Domain   
Port 389 and 636 and any regular LDAP port configured for a Directory Server instance ldap_port_t The ports used by the Directory Server instances, including the default LDAP and LDAPS ports and whatever the configured LDAP port[a] for the Directory Server is
[a] Only the LDAP port is configured for the Directory Server when it is set up, so only this port is added to the SELinux configuration automatically. The LDAPS port must be added manually, as described in Section 1.10.6, “Labeling SSL/TLS Ports”.
The Directory Server SELinux policies are configured when the server instance is set up (when setup-ds-admin.pl or register-ds-admin.pl are run). Each time a new instance is configured, the policies are updated with the appropriate information. These policies are automatically removed when the server instance is uninstalled.

1.10.2. SELinux Definitions for the SNMP Agent

The Directory Server runs an SNMP agent which can be used to configure traps and send alerts to an SNMP master agent, as described in Chapter 16, Monitoring Directory Server Using SNMP. The SNMP sub-agent is contained within a separate domain, dirsrv_snmp_t.
The SNMP subagent runs as a process, ldap-agent. The process does not listen over any ports (the third-party SNMP master agent does), but the process does need to access some system files, such as PID and log files. The security context definitions for these files and process are listed in Table 1.5, “Summary of Directory Server SELinux Policies”. All of these files are also covered by the Directory Server file contexts listed in Table 1.4, “Summary of Directory Server SELinux Policies”.

Table 1.5. Summary of Directory Server SELinux Policies

File Path Security Context Description
dirsrv_snmp_t Domain   
/usr/sbin/ldap-agent-bin dirsrv_snmp_exec_t The SNMP subagent daemon.
/var/run/ldap-agent.pid dirsrv_snmp_var_run_t The SNMP subagent PID file.
/var/log/dirsrv/ldap-agent.log dirsrv_snmp_var_log_t The SNMP subagent log file.

1.10.3. Viewing and Editing SELinux Policies for the Directory Server

The configured Directory Server and Admin Server policies can be viewed and edited using the SELinux Administration GUI. Much more information about editing SELinux policies and labels is in the Red Hat Enterprise Linux Security-Enhanced Linux Guide.
  1. Open the Systems menu.
  2. Open the Administration menu, and select the SELinux Management item.

    Note

    You can launch the GUI from the command line using system-config-selinux.
  3. Open, add, or edit any file or port label or policy for Directory Server , as necessary.
  4. After making any changes to the SELinux policies, run restorecon to load the changes to the labels or policies.
    # restorecon -r -v [-f filename | directoryName]
    For example, if new policies were created for a custom LDIF directory:
    # restorecon -r -v /myNewLdifDir
To check the version of the Directory Server SELinux policy installed, click the Policy Module link.
To view the policies set on the individual files and processes, click the File Labeling link. To view the policies for the port assignments for the server, click the Network Port link.

1.10.4. Starting the Directory Server Confined by SELinux

Three scripts control how the ns-slapd process transitions to the dirsrv_t domain when starting and stopping. All three of these scripts are in the /usr/sbin/ directory:
  • start-dirsrv
  • stop-dirsrv
  • restart-dirsrv
These scripts are run similar to the service commands used by Directory Server. A single instance can be specified using the instance name or the script can be run with no arguments and apply to all instances, as in Section 1.3, “Starting and Stopping Servers”. For example:
/usr/sbin/start-dirsrv instance_name
Likewise, the SNMP subagent is started or stopped using the service command to run the ldap-agent process confined by SELinux policies. See Section 16.3.2, “Starting the Subagent” for more information.
service dirsrv-snmp start

1.10.5. Managing SELinux Labels for Files Used by the Directory Server

There are a number of different files that the Directory Server has to access in normal operations, such as database, log, and index files. Many of these are configured in settings in cn=config, such as nsslapd-dbdir, nsslapd-rundir, and nsslapd-ldapifilepath. As long as these directory locations are left with their default settings, the confined ns-slapd process can access them just fine. However, if these file locations are moved, then the SELinux labels must be updated for the new locations so that the Directory Server process is allowed to access them.

Note

Do not change the default locations for Directory Server files and directories — such as the databases, run file, or LDAPI configuration file — so that the SELinux policies do not have to be updated.
Most common files used by the Directory Server are covered by the SELinux policies by default. However, for some operations, the Directory Server must access external files, meaning files not directly created from Directory Server templates and maintained by the server. For example:
  • LDIF files for import and export. If the import or export LDIF files are created in the default LDIF directory, /var/lib/dirsrv/slapd-instance_name/ldif, then the files will automatically be covered by the security context. If these are in a non-standard location, then the file labels must be changed for the Directory Server to access them.
    These SELinux labels apply only to the LDIF files used for import/export operations. These contexts do not cover import or export operations, which are database operations and outside the purview of SELinux.

    Important

    If you copy a file into the LDIF directory, then the command automatically relabels the copied files and everything is fine. If, however, a file is moved into the LDIF directory (mv), then it retains its original SELinux labels and will not be recognized by the ns-slapd process.
  • Custom plug-ins. The SELinux file restrictions assume that any plug-in files used by the server are located in the default plug-in directory, /usr/lib[64]/dirsrv/plugins on Red Hat Enterprise Linux 6 (64-bit). Any .so files for custom plug-ins must be in that directory for the server to load and use them.
    If the plug-in files must be stored in a non-default location for some reason, then add appropriate SELinux rules to allow the server to access the files. This is in Section 1.10.3, “Viewing and Editing SELinux Policies for the Directory Server” or using semanage.
  • SASL/GSS-API keytabs. The Directory Server must be able to access the host keytab and krb5.conf configuration file for GSS-API authentication in SASL. (The host keytab is set in the KRB5_KTNAME directive in the /etc/sysconfig/dirsrv file.) For these files to be properly labeled in SELinux in the dirsrv_config_t context, they must be in the /etc/dirsrv/ directory.
    Only the host keytab and krb5.conf file must be in /etc. The user key tabs can still be in any directory.
Although import/export operations and SASL configurations are the most common situations when the Directory Server will access an external file, be sure to consider file labeling any time the Directory Server needs to access a file.
File labels can be added using the SELinux administrative interface (Section 1.10.3, “Viewing and Editing SELinux Policies for the Directory Server”) or using the semanage script. For details, see the semanage(8) man page.

1.10.6. Labeling SSL/TLS Ports

When the Directory Server is first set up, the given LDAP port is labeled for SELinux (the default is port 389). However, SSL/TLS is set up separately, after the Directory Server is already configured, so the LDAPS port for the Directory Server is not automatically labeled.
The default LDAP and LDAPS ports, 389 and 636, respectively, are already labeled as part of the policies in Red Hat Enterprise Linux. Any other LDAP port is added to those policies when the server is set up. If the Directory Server uses a secure port other than the defaults for its SSL/TLS connections, however, then an administrator must label the port manually. This can be done in the SELinux administrative interface shown in Section 1.10.3, “Viewing and Editing SELinux Policies for the Directory Server”. It can also be done easily using the semanage script.
Use the port subcommand, the -t option to identify the security context, and the -p option to identify the port. The -a option adds the port label. For example:
/usr/sbin/semanage port -a -t ldap_port_t -p tcp 1636
To delete a port label, use the -d option. For example:
/usr/sbin/semanage port -d -t ldap_port_t -p tcp 1636

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

    Example 2.1. Example Root Suffix Entry

    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=dc=example\,dc=com,cn=mapping tree,cn=config
    changetype: add
    objectclass: top
    objectclass: extensibleObject
    objectclass: nsMappingTree
    nsslapd-state: backend
    nsslapd-backend: UserData
    cn: dc=example,dc=com
  2. 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
    changetype: add
    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 back end (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

2.1.2.1. Viewing the Default Naming Context

A naming context is analogous to the suffix; it is the root structure for naming directory entries. There can be multiple naming contexts, depending on the directory and data structure; for example, a standard Directory Server configuration has a user suffix such as dc=example,dc=com, a configuration suffix in cn=config, and an administrative configuration suffix in o=netscaperoot.
Many directory trees have multiple naming contexts to be used with different types of entries or with logical data divisions. Clients which access the Directory Server may not know what naming context they need to use. The Directory Server has a server configuration attribute which signals to clients what the default naming context is, if they have no other naming context configuration known to them.
The default naming context is set in the nsslapd-defaultnamingcontext attribute in cn=config. This value is propagated over to the root DSE and can be queried by clients anonymously by checking the defaultnamingcontext attribute in the root DSE.
For example:
[root@server ~]# ldapsearch -p 389 -h server.example.com -x -b "" -s base | egrep namingcontext
namingContexts: dc=example,dc=com
namingContexts: dc=example,dc=net
namingContexts: dc=redhat,dc=com
defaultnamingcontext: dc=example,dc=com

Important

By default, the nsslapd-defaultnamingcontext attribute is included in the list of attributes which can be deleted, in the nsslapd-allowed-to-delete-attrs attribute. This allows the current default suffix to be deleted and then updates the server configuration accordingly.
If for some reason the nsslapd-defaultnamingcontext attribute is removed from the list of configuration attributes which can be deleted, then no changes to that attribute are preserved. If the default suffix is deleted, that change cannot be propagated to the server configuration. This means that the nsslapd-defaultnamingcontext attribute retains the old information instead of being blank (removed), which is the correct and current configuration.
To maintain configuration consistency, do not remove the nsslapd-defaultnamingcontext attribute from the nsslapd-allowed-to-delete-attrs list.

2.1.2.2. 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 check box.

2.1.2.3. 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 and create the entry for the new database.
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=UserData,cn=ldbm database,cn=plugins,cn=config
    changetype: add
    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.
  2. 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.
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
  2. Add the following attributes to the suffix entry itself, supplying the information about the custom distribution logic:
    dn: suffix
    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 check box.
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 check box.
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.
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
  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 check box.
  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 is nobody:nobody. However, Red Hat strongly recommends to use a different user and group name such as dirsrv during the installation.
    chown nobody:nobody /home/exampledb-txnlogs
  4. Open the dse.ldif file in the Directory Server instance's configuration directory.
    [root@server ~]# vim /etc/dirsrv/slapd-instance_name/dse.ldif
  5. 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.
    [root@server ~]# 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.
    [root@server ~]# 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 back end. When configured, every instance of a particular attribute, even index data, is encrypted for every entry stored in that database.

Note

There is one exception to encrypted data: any value which is used as the RDN for an entry is not encrypted within the entry DN. For example, if the uid attribute is encrypted, the value is encrypted in the entry but is displayed in the DN:
# entry-id: 16
dn: uid=jsmith1234,ou=People,dc=example,dc=com
nsUniqueId: ee91ea82-1dd111b2-9f36e9bc-39fb8550
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
givenName: John
sn: Smith
uid:: Sf04P9nJWGU1qiW9JJCGRg==
That would allow someone to discover the encrypted value.
Any attribute used within the entry DN cannot be effectively encrypted, since it will always be displayed in the DN. Be aware of what attributes are used to build the DN and design the attribute encryption model accordingly.
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 back end 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.6, “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:
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
  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
    changetype: add
    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.6, “Exporting and Importing an Encrypted Database”.
For more information on attribute encryption configuration schema, see "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. Enabling Attribute Encryption for Existing Attribute Values

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.

2.2.3.6. 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.7. 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/2017:13:00:34 -0700] - attrcrypt_unwrap_key: failed to unwrap key for cipher AES
Apr  4 13:00:35 smtp1 logger: [04/Apr/2017:13:00:34 -0700] - Failed to retrieve key for cipher AES in attrcrypt_cipher_init
Apr  4 13:00:35 smtp1 logger: [04/Apr/2017:13:00:34 -0700] - Failed to initialize cipher AES in attrcrypt_init
Apr  4 13:00:35 smtp1 logger: [04/Apr/2017:13:00:34 -0700] - attrcrypt_unwrap_key: failed to unwrap key for cipher AES
Apr  4 13:00:35 smtp1 logger: [04/Apr/2017:13:00:34 -0700] - Failed to retrieve key for cipher AES in attrcrypt_cipher_init
Apr  4 13:00:35 smtp1 logger: [04/Apr/2017: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.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 6 (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 C, 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 C, 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 and add the default referral to the dir2.example.com server:
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
    					
    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 check box. (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://server:port/[optional_dn]
    server can be the host name, IPv4 address, or IPv6 address for the server. 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 is 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 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 more information on smart referrals, see the Directory Server Deployment Guide.

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 is 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[1] 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.
Run ldapmodify and add a suffix referral to the ou=people,dc=example,dc=com root suffix:
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
				
dn: cn=ou=people,dc=example,dc=com,cn=mapping tree,cn=config
changetype: add
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, see Table 2.1, “Suffix Attributes”.


[] Unlike the standard LDAP URL format, the URL of the remote server does not specify a suffix. It has the form ldap://server:port/, where server can be the host name, IPv4 address, or IPv6 address.
[1] Appendix C, 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 12, 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 13, 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 8, 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 Red Hat Directory Server 9 Configuration, Command, and File 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.
Note that this limit is additionally applied to replication processes.
For further information about the nsslapd-maxbersize attribute and a workaround in replication scenarios, see the corresponding section in the Red Hat Directory Server Configuration, Command, and File 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 subtype by 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 D.2, “Supported Language Subtypes”.
Only one language subtype can be added per attribute instance in an entry. To assign multiple language subtypes, add another attribute instance to the entry, and then assign the new language subtype. For example, the following is illegal:
cn;lang-ja;lang-en-GB:value
Instead, use:
cn;lang-ja:ja-value
cn;lang-en-GB:value
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 13, Managing Access Control.

3.2.1. Providing Input from the Command Line

When you provide input to the ldapmodify and ldapdelete 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:
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
  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:
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: Suffix_Name
changetype: add
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.6, “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 B, LDAP Data Interchange Format.
  2. Import the LDIF file from the Directory Server Console.
    See Section 4.1.4, “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 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, pass the -a option to indicate an add operation and the LDIF file to use which contains the new entry information (and, optionally, the bind credentials and any connection information). For example:
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x -f new.ldif
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 B.1, “About the LDIF File Format”.)
If the new entry is not passed in a given LDIF file, then the ldapmodify utility waits for the DN of the new entry and then each object class and attribute for the entry, each on a new line in LDIF format. When the last attribute is entered, hit enter twice to submit the new entry.
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”.

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:
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x -f modify_statements
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”.
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”.
-x Disables SASL to allow a simple bind to the server.

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 -p 389 -h server.example.com -x "cn=Robert Jenkins,ou=People,dc=example,dc=com" "cn=Lisa Jangles,ou=People,dc=example,dc=com"
The DNs of the entries to delete (cn=Robert Jenkins,ou=People,dc=example,dc=com and cn=Lisa Jangles,ou=People,dc=example,dc=com) are appended to the end of the delete command.
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.
-x Disables SASL to allow a simple bind to the server.

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 -p 389 -h server.example.com -x "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 distinguished name. Most commonly, it changes the relative DN, or RDN, 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.
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
While it is most common for the modrdn operation to be used in a direct name change operation, it can be used to change other parts of the DN, which is both a rename operation and a move operation. modrdn can update the name of all leaf entries if the name of a subtree entry changes, or a single leaf can be moved to a new parent by changing its DN. This is covered in more detail in Section 3.4, “Renaming and Moving Entries”.

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 with ldapmodify. However, you must add version:1 to the beginning of the LDIF file or with LDIF update statements. For example:
[root@server ~]# ldapmodify -D "cn=directory manager" -W -x
  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. Renaming and Moving Entries

Most rename operations are done on a leaf entry. However, some types of rename operations result in changes to the directory tree itself. These operations — subtree renames and new superior operations — are possible because of the way that entry IDs are stored in Directory Server indexes.

3.4.1. About Renaming Entries

Every DN is comprised of a long chain of elements that build on one another. Every entry has its own name, and then each of its children combine their name (the element on the far left) with the parent name. This pattern orients entries within the directory tree.

Example 3.1. Building Entry DNs

                                                                  dc=example,dc=com  =>  root suffix
                                                        ou=People,dc=example,dc=com  =>  org unit
                                          st=California,ou=People,dc=example,dc=com  =>  state/province
                          l=Mountain View,st=California,ou=People,dc=example,dc=com  =>  city
           ou=Engineering,l=Mountain View,st=California,ou=People,dc=example,dc=com  =>  org unit
uid=jsmith,ou=Engineering,l=Mountain View,st=California,ou=People,dc=example,dc=com  =>  leaf entry
Rename, or modrdn, operations result in changes to this tree.

3.4.1.1. Types of Rename Operations

When the naming attribute of an entry, the leftmost element of the DN, is changed, this is a modrdn operation. That's a special kind of modify operation because, in a sense, it moves the entry within the directory tree. For leaf entries (entries with no children), modrdn operations are lateral moves; the entry has the same parent, just a new name.
modrdn Operations for a Leaf Entry

Figure 3.1. modrdn Operations for a Leaf Entry

For subtree entries, the modrdn operation not only renames the subtree entry itself, but also changes the DN components of all of the children entries beneath the subtree.
modrdn Operations for a Subtree Entry

Figure 3.2. modrdn Operations for a Subtree Entry

Important

Subtree modrdn operations also move and rename all of the child entries beneath the subtree entry. For large subtrees, this can be a time- and resource-intensive process. Plan the naming structure of your directory tree hierarchy so that it will not require frequent subtree rename operations.
A similar action to renaming a subtree is moving an entry from one subtree to another. This is an expanded type of modrdn operation, which simultaneously renames the entry (even if it is the same name) and sets a newSuperior attribute which moves the entry from one parent to another.
modrdn Operations to a New Parent Entry

Figure 3.3. modrdn Operations to a New Parent Entry

3.4.1.2. The Relationships Between Entry Keys in entryrdn.db4

Both new superior and subtree rename operations are possible because of how entries are stored in the entryrdn.db4 index. Each entry is identified by its own key (a self-link) and then a subkey which identifies its parent (the parent link) and any children. This has a format that lays out the directory tree hierarchy by treating parents and children as attribute to an entry, and every entry is describes by a unique ID and its RDN, rather than the full DN.
These relationships are visible in the dbscan output for the entryrdn.db4 index.
numeric_id:RDN => self link
     ID: #; RDN: "rdn"; NRDN: normalized_rdn
P#:RDN => parent link
     ID: #; RDN: "rdn"; NRDN: normalized_rdn
C#:RDN => child link
     ID: #; RDN: "rdn"; NRDN: normalized_rdn
For example, the ou=people subtree has a parent of dc=example,dc=com and a child of uid=jsmith.
4:ou=people
   ID: 4; RDN: "ou=People"; NRDN: "ou=people"
P4:ou=people
   ID: 1; RDN: "dc=example,dc=com"; NRDN: "dc=example,dc=com"
C4:ou=people
   ID: 10; RDN: "uid=jsmith"; NRDN: "uid=jsmith"

Note

Version 8.2 and older of Directory Server used the entrydn.db4 index, which stored entry keys according to their full DN. To upgrade to entryrdn.db4, run the dn2rdn tool.
The defined keys for parent and child entries makes it possible for the Directory Server to perform operations that move entries in the directory tree.
  • Add operations look at the parent given in the modify statement and check for any existing leaf entries; if none exist, the new entry is added.
  • For delete operations, the server first checks the self link (the full entry key), and then deletes both the self link and then the child link in the parent entry. For example, if you deleted ou=people,dc=example,dc=com, the server deletes the ou=people key (the self-link) and then deletes the child subkey from the dc=example,dc=com entry key.
  • For new superior operations, the server changes the parent link in the entry key, removes the child link from the old parent, and adds a new child link to the new superior key.
  • For subtree rename operations, the server changes the self link in the subtree entry key to update its RDN, then tracks any child entry keys (based on the child links) and updates the parent link RDN.

3.4.1.3. Considerations for Renaming Entries

There are some things to keep in mind when performing rename operations:
  • You cannot rename the root suffix.
  • Subtree rename operations have minimal effect on replication. Replication agreements are applied to an entire database, not a subtree within the database, so a subtree rename operation does not require re-configuring a replication agreement. All of the name changes after a subtree rename operation are replicated as normal.
  • Renaming a subtree may require any synchronization agreements to be re-configured. Sync agreements are set at the suffix or subtree level, so renaming a subtree may break synchronization.
  • Renaming a subtree requires that any subtree-level ACIs set for the subtree be re-configured manually, as well as any entry-level ACIs set for child entries of the subtree.
  • You can rename a subtree with children, but you cannot delete a subtree with children.
  • Trying to change the component of a subtree, like moving from ou to dc, may fail with a schema violation. For example, the organizationalUnit object class requires the ou attribute. If that attribute is removed as part of renaming the subtree, then the operation will fail.
  • Any memberOf attributes managed by the MemberOf Plug-in will not be updated after a subtree-level rename operation. The MemberOf Plug-in does not check to see if parent entries change in order to initiate updates. If a subtree is renamed which contains either groups or group members, then launch a cn=memberof task task or use the fixup-memberof.pl command to force the MemberOf Plug-in to make the changes.
    See Section 6.1.4.6, “Synchronizing memberOf Values” to see how to clean up memberOf attribute references.

3.4.2. Renaming an Entry or Subtree

To rename an entry or subtree, use the modrdn changetype LDIF statement and use the newrdn attribute to indicate that the naming attribute is being changed and deleteoldrdn to set whether to retain the old RDN (0) or delete it (any non-zero integer). For example:
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: ou=Engineering,ou=People,dc=example,dc=com
changetype: modrdn
newrdn: ou=Development
deleteoldrdn: 1
If deleteoldrdn is set to any non-zero integer, positive or negative, then the old RDN is removed.
LDIF statements for modrdn operations are described in Section 3.3.2, “Renaming an Entry Using LDIF”.

3.4.3. Moving an Entry to a New Parent

Changing the parent entry requires setting two attributes:
  • newrdn to set the RDN of the moved entry. This is required even if the RDN remains the same.
  • newSuperior to give the DN of the new parent entry.
For example:
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: uid=jsmith,l=Boston,ou=Engineering,ou=People,dc=example,dc=com
changetype: modrdn
newrdn: uid=jsmith
deleteoldrdn: 1
newSuperior: l=Mountain View,ou=Engineering,ou=People,dc=example,dc=com

3.4.4. Disabling Subtree Rename Operations

By default, renaming subtrees is allowed. However, this can be disabled by resetting the nsslapd-subtree-rename-switch parameter to off:

Note

When a new Directory Server 9.0 instance or an upgraded instance has subtree renames enabled, then the RDNs of the entries are mapped in the entryrdn.db4 database. Instances with subtree rename disabled store their entry information in entrydn.db4. When disabling subtree renames, then the server needs to switch from using one database to the other, which is done by exporting and re-importing the directory entries. This is described in Section 3.4.1.2, “The Relationships Between Entry Keys in entryrdn.db4”.
  1. Export the directory to LDIF.
    /etc/dirsrv/slapd-instance_name/db2ldif -n database1 -a /var/lib/dirsrv/slapd-instance_name/ldif/tree.ldif
    More export options are covered in Section 4.2, “Exporting Data”.
  2. Turn off the nsslapd-subtree-rename-switch parameter.
    [root@server ~]# ldapmodify -D "cn=directory manager" -W -x
    dn: cn=config,cn=ldbm database,cn=plugins,cn=config
    changetype: modify
    replace: nsslapd-subtree-rename-switch
    nsslapd-subtree-rename-switch: off
  3. Import the LDIF file. This will populate the new entrydn.db4 file.
    /etc/dirsrv/slapd-instance_name/ldif2db -D "cn=Directory Manager" -w secret -i /var/lib/dirsrv/slapd-instance_name/ldif/tree.ldif -n database1
    More import options are covered in Section 4.1, “Importing Data”.

3.4.5. Setting the DN Cache Size

A separate cache is used specifically to store DN information. As with the entry cache, the DN cache uses memory (RAM) used to store directory entries information in the internal representation. This is configured in the nsslapd-dncachememsize, and setting a large cache memory size improves the performance of rename operations.
The cache itself stores only the entry ID and the entry DN, so the table is relatively small when compared to the entry cache.
For the best move performance, make the entry cache large enough to contain all entries in the database.
This value can be modified from the command line by editing the nsslapd-dncachememsize attribute value for the LDBM plug-in instance for the database. For example:
[root@server ~]# ldapmodify -D "cn=directory manager" -W -x
dn: cn=database_name,cn=ldbm database,cn=plugins,cn=config
changetype: modify
replace: nsslapd-dncachememsize
nsslapd-dncachememsize: 20971520

3.5. 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 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 10.5.7, “Searching for Operational Attributes”.

3.5.1. Tracking Modifications to the Database through Update Sequence Numbers

The USN Plug-in provides a way for LDAP clients to know that something — anything — in the database has changed.

3.5.1.1. An Overview of the Entry Sequence Numbers

When the USN Plug-in is enabled, update sequence numbers (USNs) are sequential numbers that are assigned to an entry whenever a write operation is performed against the entry. (Write operations include add, modify, modrdn, and delete operations. Internal database operations, like export operations, are not counted in the update sequence.) A USN counter keeps track of the most recently assigned USN.
3.5.1.1.1. Local and Global USNs
The USN is evaluated globally, for the entire database, not for the single entry. The USN is similar to the change sequence number for replication and synchronization, in that it simply ticks upward to track any changes in the database or directory. However, the entry USN is maintained separately from the CSNs, and USNs are not replicated.
The entry shows the change number for the last modification to that entry in the entryUSN operational attribute. (For details on running a search for operational attributes, see Section 10.5.7, “Searching for Operational Attributes”.)

Example 3.2. 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 Plug-in has two modes, local mode and global mode:
  • In local mode, each back end database has an instance of the USN Plug-in with a USN counter specific to that back end database. This is the default setting.
  • In global mode, there is a global instance of the USN Plug-in with a global USN counter that applies to changes made to the entire directory.
When the USN Plug-in is set to local mode, results are limited to the local back end database. When the USN Plug-in is set to global mode, the returned results are for the entire directory.
The root DSE shows the most recent USN assigned to any entry in the database in the lastusn attribute. When the USN Plug-in is set to local mode, so each database has its own local USN counter, the lastUSN shows both the database which assigned the USN and the USN:
lastusn;database_name:USN
For example:
lastusn;example1: 2130
lastusn;example2: 2070
In global mode, when the database uses a shared USN counter, the lastUSN attribute shows the latest USN only:
lastusn: 4200
3.5.1.1.2. Importing USN Entries
When entries are imported, the USN Plug-in uses the nsslapd-entryusn-import-initval attribute to check if the entry has an assigned USN. If the value of nsslapd-entryusn-import-initval is numerical, the imported entry will use this numerical value as the entry's USN. If the value of nsslapd-entryusn-import-initval is not numerical, the USN Plug-in will use the value of the lastUSN attribute and increment it by one as the USN for the imported entry.

3.5.1.2. Configuring the USN Plug-in

The USN Plug-in must be enabled for USNs to be recorded on entries, as described in Section 1.8.1, “Enabling Plug-ins in the Directory Server Console”. The plug-in can be enabled through the Directory Server Console or through the command line. For example:
[root@server ~]# ldapmodify -D "cn=directory manager" -W -x
dn: cn=USN,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginEnabled
nsslapd-pluginEnabled: on
Then restart the server to apply the changes.

3.5.1.3. Enabling Global USN

The nsslapd-entryusn-global configuration parameter controls whether the USN Plug-in runs in local mode or global mode. The default is set to use a local USN counter, and the nsslapd-entryusn-global attribute value is off. To change whether the USN counter is in local or global mode, modify the nsslapd-entryusn-global attribute. For example:
[root@server ~]# ldapmodify -D "cn=directory manager" -W -x
dn: cn=USN,cn=plugins,cn=config
changetype: modify
replace: nsslapd-entryusn-global
nsslapd-entryusn-global: on
The USN Plug-in must be enabled before the nsslapd-entryusn-global configuration parameter is turned on.

3.5.1.4. Cleaning up USN Tombstone Entries

The 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 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 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 back end 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 back end 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 back end 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.5.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 10.5.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.
The access logs, however, will show both the proxy user (as dn) and the real user (as the authzid entity). For example:
[23/May/2011:18:13:56 +051800] conn=1175 op=0 BIND dn="cn=proxy admin,ou=people,dc=example,dc=com" method=128 version=3
[23/May/2011:18:13:56 +051800] conn=1175 op=0 RESULT err=0 tag=97 nentries=0 etime=0 dn="cn=proxy admin,ou=people,dc=example,dc=com"
[23/May/2011:18:13:56 +051800] conn=1175 op=1 SRCH base="dc=example,dc=com" scope=2 filter="(objectClass=*)" attrs=ALL authzid="uid=jsmith,ou=people,dc=example,dc=com"
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 check box.
    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.3. Tracking the Bind DN for Plug-in Initiated Updates

One change to an entry can trigger other, automatic changes across the directory tree. When a user is deleted, for example, that user is automatically removed from any groups it belonged to by the Referential Integrity Plug-in.
The initial action is shown in the entry as being performed by whatever user account is bound to the server, but all related updates (by default) are shown as being performed by the plug-in, with no information about which user initiated that update. For example, using the MemberOf Plug-in to update user entries with group membership, the update to the group account is shown as being performed by the bound user, while the edit to the user entry is shown as being performed by the MemberOf Plug-in:
dn: cn=my_group,ou=groups,dc=example,dc=com
modifiersname: uid=jsmith,ou=people,dc=example,dc=com

dn: uid=bjensen,ou=people,dc=example,dc=com
modifiersname: cn=memberOf plugin,cn=plugins,cn=config
The nsslapd-plugin-binddn-tracking attribute allows the server to track which user originated an update operation, as well as the internal plug-in which actually performed it. The bound user is shown in the modifiersname and creatorsname operational attributes, while the plug-in which performed it is shown in the internalModifiersname and internalCreatorsname operational attributes. For example:
dn: uid=bjensen,ou=people,dc=example,dc=com
modifiersname: uid=jsmith,ou=people,dc=example,dc=com
internalModifiersname: cn=memberOf plugin,cn=plugins,cn=config
The nsslapd-plugin-binddn-tracking attribute tracks and maintains the relationship between the bound user and any updates performed for that connection.

Note

The internalModifiersname and internalCreatorsname attributes always show a plug-in as the identity. This plug-in could be an additional plug-in, such as the MemberOf Plug-in. If the change is made by the core Directory Server, then the plug-in is the database plug-in, cn=ldbm database,cn=plugins,cn=config.
The nsslapd-plugin-binddn-tracking attribute is disabled by default. To allow the server to track operations based on bind DN, enable that attribute using ldapmodify:
[jsmith@server ~]$ ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=config
changetype: modify
replace: nsslapd-plugin-binddn-tracking
nsslapd-plugin-binddn-tracking: on

3.5.4. Tracking Password Change Times

Password change operations are normally treated as any other modification to an entry, so the update time is recorded in the lastModified operational attrobite. However, there can be times when the time of the last password change needs to be recorded separately, to make it easier to update passwords in Active Directory synchronization or to connect with other LDAP clients.
The passwordTrackUpdateTime attribute within the password policy tells the server to record a timestamp for the last time that the password was updated for an entry. The password change time itself is stored as an operational attribute on the user entry, pwdUpdateTime (which is separate from the modifyTimestamp or lastModified operational attributes).
The passwordTrackUpdateTime attribute can be set as part of the global password policy or on a subtree or user-level policy, depending on what clients need to access the password change time. Setting password policies is described in Section 14.1, “Managing the Password Policy”.

3.6. 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 reference 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.6.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.
When a user or group entry is deleted, updated, renamed, or moved within the directory, the operation is logged to the Referential Integrity log file. For the distinguished names (DN) in the log file, Directory Server searches and updates in intervals the attributes set in the plug-in configuration:
  • For entries, marked in the log file as deleted, the corresponding attribute in the directory is deleted.
  • For entries, marked in the log file as updated, the corresponding attribute in the directory is updated.
  • For entries, marked in the log file as renamed or moved, the value of the corresponding attribute in the directory is renamed.
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, equality, and subtring; not indexing those attributes results poor server performance for modify and delete operations.
nsIndexType: pres
nsIndexType: eq
nsIndexType: sub
See Section 9.2, “Creating Standard Indexes” for more information about checking and creating indexes.

3.6.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.6.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.6.3. Enabling and Disabling Referential Integrity

3.6.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 check box 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.6.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:
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    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.6.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.6.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.6.4.2. Modifying the Update Interval from the Command Line

  1. Use ldapmodify to edit the value of the nsslapd-pluginarg attribute. For example:
    The first argument listed sets the update interval for referential integrity checks. To change the interval, replace the nsslapd-pluginarg0 attribute.
    [root@server ~]# ldapmodify -D "cn=directory manager" -W -x
    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.6.5. Modifying the Attribute List

3.6.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 back ends.

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

3.6.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.
To enable shared configuration entries, set the nsslapd-pluginConfigArea attribute:
nsslapd-pluginConfigArea:entry_DN
All the configuration attribute settings, for example adding or removing a shared entry, are dynamic and do not require a server restart to take effect.
The following example uses the pluginarg* attributes:
nsslapd-pluginarg0: 0
nsslapd-pluginarg1: /var/log/dirsrv/slapd-localhost/referint
nsslapd-pluginarg2: 0
nsslapd-pluginarg3: member
nsslapd-pluginarg4: uniquemember
nsslapd-pluginarg5: owner
nsslapd-pluginarg6: seeAlso
Referential Integrity plug-in parameter descriptions:
Legacy-style parameter Description
nsslapd-pluginarg0
Sets the update delay:
  • -1: No check for referential integrity is performed.
  • 0: The check for referential integrity is performed immediately.
  • Positive integer value: Represents the interval in seconds for performing the referential integrity check.
nsslapd-pluginarg1 Sets the path to the log file.
nsslapd-pluginarg2
nsslapd-pluginarg[3-10] Sets the attributes on which the plug-in performs integrity updates.

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

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 Large Numbers of Entries

When there are a large number of entries to be imported, the operating system itself may hit performance limits on what it allows the Directory Server to do. This is particularly true on x86 systems. This can cause import operations to fail because of resource constraints.
If necessary, set the system ulimit value to the maximum number of allows processes for the system user.
For example:
[root@server ~]# ulimit -u 4096
Then run the import operation.

4.1.3. Setting EntryUSN Initial Values During Import

Entry update sequence numbers (USNs) are not preserved when entries are exported from one server and imported into another. As Section 3.5.1, “Tracking Modifications to the Database through Update Sequence Numbers” explains, entry USNs are assigned for operations that happen on a local server, so it does not make sense to import those USNs onto another server.
However, it is possible to configure an initial entry USN value for entries when importing a database or initializing a database (such as when a replica is initialized for replication). This is done by setting the nsslapd-entryusn-import-initval attribute, which sets a starting USN for all imported entries.
There are two possible values for nsslapd-entryusn-import-initval:
  • An integer, which is the explicit start number used for every imported entry.
  • next, which means that every imported entry uses whatever the highest entry USN value was on the server before the import operation, incremented by one.
If nsslapd-entryusn-import-initval is not set, then all entry USNs begin at zero.
For example, if the highest value on the server is 1000 before the import or initialization operation, and the nsslapd-entryusn-import-initval value is next, then every imported entry is assigned a USN of 1001:
ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -x "(cn=*)" entryusn
	
dn: dc=example,dc=com
entryusn: 1001
dn: ou=Accounting,dc=example,dc=com
entryusn: 1001
dn: ou=Product Development,dc=example,dc=com
entryusn: 1001
...
dn: uid=jsmith,ou=people,dc=example,dc=com
entryusn: 1001
...
To set an initial value for entry USNs, simply add the nsslapd-entryusn-import-initval attribute to the server into which data are being imported or to the master server which will perform the initialization.
[root@server ~]# ldapmodify -D "cn=directory manager" -W -x -D "cn=directory manager" -w secret -p 389 -h server.example.com -x

dn: cn=config
changetype: modify
add: nsslapd-entryusn-import-initval
nsslapd-entryusn-import-initval: next

Note

In multi-master replication, the nsslapd-entryusn-import-initval attribute is not replicated between servers. This means that the value must be set specifically on whichever supplier server is being used to initialize a replica.
For example, if Supplier1 has nsslapd-entryusn-import-initval set to next and is used to initialize a replica, then the entry USNs for imported entries have the highest value plus one. If Supplier2 does not have nsslapd-entryusn-import-initval set and is used to initialize a replica, then all entry USNs for imported entries begin at zero — even if Supplier1 and Supplier 2 have a multi-master replication agreement between them.

4.1.4. 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 check box.
    • Continue on Error. Select the Continue on error check box 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.5. 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.6. 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.6, “Exporting and Importing an Encrypted Database” for more information.

4.1.6.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 an LDIF:
  1. Stop the server.
    [root@server ~]# service dirsrv stop instance
  2. Run the ldif2db command-line script.
    [root@server ~]# /usr/lib64/dirsrv/slapd-instance_name/ldif2db -n Database1 -i /var/lib/dirsrv/slapd-instance_name/ldif/demo.ldif -i /var/lib/dirsrv/slapd-instance_name/ldif/demo2.ldif
    On 32-bit installations, the ldif2db script is located in the /usr/lib64/dirsrv/slapd-instance_name/ directory.
    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.
  3. Start the server.
    [root@server ~]# service dirsrv start instance

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.6.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.
Run the ldif2db.pl script.
[root@server ~]# ldif2db.pl -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.pl 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.6.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:
[root@server ~]# 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.6.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:
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=example import,cn=import,cn=tasks,cn=config
changetype: add
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.6, “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 linerun either the db2ldif command-line script or the db2ldif.pl Perl script. For example:
[root@server ~]# 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:
[root@server ~]# db2ldif -n database1
It is also possible to specify which suffixes to export, using the -s option. For example:
[root@server ~]# db2ldif -s "dc=example,dc=com"
The LDIF file in this case would be /var/lib/dirsrv/slapd-instance_name/ldif/instance_name-example-2017_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:
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=example export,cn=export,cn=tasks,cn=config
changetype: add
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.

Note

The changelog database is backed up with the regular server database.

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 command-line script works when the server is running or when the server is stopped; the Perl script can only be run when the server is running.

Important

If the database being backed up is a master database, meaning it keeps a changelog, then it must be backed up using the db2bak.pl Perl script or using the Directory Server Console if the server is kept running. The changelog only writes its RUV entries to the database when the server is shut down; while the server is running, the changelog keeps its changes in memory. For the Perl script and the Console, these changelog RUVs are written to the database before the backup process runs. However, that step is not performed by the command-line script.
The db2bak should not be run on a running master server. Either use the Perl script or stop the server before performing the backup.
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.pl script, run the db2bak.pl Perl script, specifying the backup filename and directory.
[root@server ~]# /usr/lib[64]/dirsrv/slapd-example/db2bak.pl /var/lib/dirsrv/slapd-instance_name/bak/instance_name-2017_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).
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:
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=example backup,cn=backup,cn=tasks,cn=config
changetype: add
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.

Note

Restoring a database from backup also restores the changelog.

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.

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.
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.
4.3.3.2.1. Using the bak2db Command-Line Script
  1. If the Directory Server is running, stop it:
    [root@server ~]# service dirsrv stop instance
  2. Run the bak2db command-line script. The bak2db script requires the full path and name of the input file.
    [root@server ~]# /etc/dirsrv/slapd-instance_name/bak2db /var/lib/dirsrv/slapd-instance_name/bak/instance_name-2017_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
Run the bak2db.pl Perl script.
[root@server ~]# /usr/lib[64]/dirsrv/slapd-example/bak2db.pl -D "cn=Directory Manager" -w secret -a /var/lib/dirsrv/slapd-instance_name/bak/instance_name-2017_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.
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.
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:
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=example restore,cn=restore,cn=tasks,cn=config
changetype: add
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 back end 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

Several situations can occur when a supplier server is restored:
  • The consumer servers are also restored.
    If all databases are restored from backups taken at the same time (so that the data are in sync), the consumers remain synchronized with the supplier, and it is not necessary to do anything else. Replication resumes without interruption.
  • Only the supplier is restored.
    If only the supplier is restored or if the consumers are restored from backups taken at a different times, reinitialize the consumers for the supplier to update the data in the database. If only the supplier is restored or if the consumers are restored from backups taken at a different times, reinitialize the consumers for the supplier to update the data in the database.
  • 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, see Section 11.15, “Initializing Consumers”.
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.
For information on managing replication, see Chapter 11, 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 relationships 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. For example:
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

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.
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.3, “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:
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

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, see 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 are two ways to resolve this:
  • Creating a rule to merge multiple CoS-generated attributes into the target entry. This results in multiple values in the target entry.
  • Setting a priority to select one CoS value out of competing CoS definitions. This generates one single value for the target entry.

Note

Indirect CoS do not support the cosPriority attribute.
The way that the CoS handles multiple values for a CoS attribute is defined in whether it uses a merge-schemes qualifier.
cosAttribute: attribute override merge-schemes

Note

The merge-schemes qualifier does not affect how the CoS handles physical attribute values or the override qualifier. If there are multiple competing CoS templates or definitions, then the same merge-schemes and override qualifiers have to be set on every cosAttribute for every competing CoS definition. Otherwise, one combination is chosen arbitrarily from all possible CoS definitions.
Using the merge-schemes qualifier tells the CoS that it will, or can, generate multiple values for the managed attribute. There are two possible scenarios for having a multi-valued CoS attribute:
  • One CoS template entry contains multiple instances of the managed CoS attribute, resulting in multiple values on the target entry. For example:
    dn: cn=server access template,dc=example,dc=com
    objectclass: top
    objectclass: extensibleObject
    objectclass: cosTemplate
    accessTo: mail.example.com
    accessTo: irc.example.com

    Note

    This method only works with classic CoS.
  • Multiple CoS definitions may define a class of service for the same target attribute, so there are multiple template entries. For example:
    dn: cn=mail template,dc=example,dc=com
    objectclass: top
    objectclass: extensibleObject
    objectclass: cosTemplate
    accessTo: mail.example.com
    
    dn: cn=chat template,dc=example,dc=com
    objectclass: top
    objectclass: extensibleObject
    objectclass: cosTemplate
    accessTo: irc.example.com
However, it may be that even if there are multiple CoS definitions, only one value should be generated for the attribute. If there are multiple CoS definitions, 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:
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
  2. Next, add the pointer CoS definition to the dc=example,dc=com root suffix.
    dn: cn=pointerCoS,dc=example,dc=com
    changetype: add
    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
    changetype: add
    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:
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=indirectCoS,dc=example,dc=com
    changetype: add
    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.
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=classicCoS,dc=example,dc=com
    changetype: add
    objectclass: top
    objectclass: cosSuperDefinition
    objectclass: cosClassicDefinition
    cosTemplateDn: cn=classicCoS,dc=example,dc=com
    cosSpecifier: businessCategory
    cosAttribute: postalCode override
  2. 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
    changetype: add
    objectclass: top
    objectclass: extensibleObject
    objectclass: cosTemplate
    postalCode: 44438
    
    dn: cn=marketing,cn=classicCoS,dc=example,dc=com
    changetype: add
    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 -x -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 -x -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 13.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 8, 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.

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.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 avoiding replication conflicts. The DNA Plug-in assigns unique numbers across a single back end. For multi-master replication, when each master is running a local DNA Plug-in instance, there has to be a way to ensure that each instance is using a truly unique set of numbers. This is done by assigning different ranges of numbers to each server to assign.

5.4.1. About Dynamic Number Assignments

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 separate ranges on each replica, the servers can all continually assign numbers without overlapping with each other.

5.4.1.2. Ranges and Assigning Numbers

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 present. Adding an entry with no value for the managed attribute triggers the DNA Plug-in to assign a value. This option only works if the DNA Plug-in has been configured to assign unique values to a single attribute.
  • 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 the magic value 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, this uses 0 as a magic number:
     ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
     dn: uid=jsmith,ou=people,dc=example,dc=com
     changetype: add
     objectClass: top
     objectClass: person
     objectClass: posixAccount
     uid: jsmith
     cn: John Smith
     uidNumber: 0
     gidNumber: 0
     ....
    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.

5.4.1.3. Multiple Attributes in the Same Range

The DNA Plug-in can assign unique numbers to a single attribute type or across multiple attribute types from a single range of unique numbers.
This provides several options for assigning unique numbers to attributes:
  • A single number assigned to a single attribute type from a single range of unique numbers.
  • The same unique number assigned to two attributes for a single entry.
  • Two different attributes assigned two different numbers from the same range of unique numbers.
In many cases, it is sufficient to have a unique number assigned per attribute type. When assigning an employeeID to a new employee entry, it is important each employee entry is assigned a unique employeeID.
However, there are cases where it may be useful to assign unique numbers from the same range of numbers to multiple attributes. For example, when assigning a uidNumber and a gidNumber to a posixAccount entry, the DNA Plug-in will assign the same number to both attributes. To do this, then pass both managed attributes to the modify operation, specifying the magic value.
[root@server ~]# ldapmodify -D "cn=directory manager" -W -x

dn: uid=jsmith,ou=people,dc=example,dc=com
changetype: modify
add: uidNumber
uidNumber: 0
-
add:gidNumber
gidNumber: 0
When multiple attributes are handled by the DNA Plug-in, the plug-in can assign a unique value to only one of those attributes if the object class only allows one of them. For example, the posixGroup object class does not allow a uidNumber attribute but it does allow gidNumber. If the DNA Plug-in manages both uidNumber and gidNumber, then when a posixGroup entry is created, a unique number for gidNumber is assigned from the same range as the uidNumber and gidNumber attributes. Using the same pool for all attributes manged by the plug-in keeps the assignment of unique numbers aligned and prevents situations where a uidNumber and a gidNumber on different entries are assigned from different ranges and result in the same unique number.
If multiple attributes are handled by the DNA Plug-in, then the same value will be assigned to all of the given managed attributes in an entry in a single modify operation. To assign different numbers from the same range, then you must perform separate modify operations. For example:
[root@server ~]# ldapmodify -D "cn=directory manager" -W -x
dn: uid=jsmith,ou=people,dc=example,dc=com
changetype: modify
add: uidNumber
uidNumber: 0
^D

[root@server ~]# ldapmodify -D "cn=directory manager" -W -x
dn: uid=jsmith,ou=people,dc=example,dc=com
changetype: modify
add: employeeId
employeeId: magic

Important

When the DNA Plug-in is configured to assign unique numbers to multiple attributes, it is necessary to specify the magic value for each attribute that requires the unique number. While this is not necessary when the DNA plug-in has been configured to provide unique numbers for a single attribute, it is necessary for multiple attributes. There may be instances where an entry does not allow each type of attribute defined for the range, or, more important, an entry allow all of the attributes types defined, but only a subset of the attributes require the unique value.

Example 5.5. DNA and Unique Bank Account Numbers

Example Bank wants to use the same unique number for a customer's primaryAccount and customerID attributes. The Example Bank administrator configured the DNA Plug-in to assign unique values for both attributes from the same range.
The bank also wants to assign numbers for secondary accounts from the same range as the customer ID and primary account numbers, but these numbers cannot be the same as the primary account numbers. The Example Bank administrator configures the DNA Plug-in to also manage the secondaryAccount attribute, but will only add the secondaryAccount attribute to an entry after the entry is created and the primaryAccount and customerID attributes are assigned. This ensures that primaryAccount and customerID share the same unique number, and any secondaryAccount numbers are entirely unique but still from the same range of numbers.

5.4.2. 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 value is being managed, is 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)
All of the attributes available for a DNA Plug-in instance are listed in Table 5.3, “DNA Entry Attributes”.
To configure distributed numeric assignment on a single server for a single attribute type:
dn: cn=Account UIDs,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config
objectClass: top
objectClass: dnaPluginConfig
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: dnaPluginConfig
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.
Each supplier keeps a track of its current range in a separate configuration entry which contains information about its range and its connection settings. This entry is a child of the location in dnasharedcfgdn. 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: dnaSharedConfig
objectClass: top
dnahostname: ldap1.example.com
dnaPortNum: 389
dnaSecurePortNum: 636
dnaRemainingValues: 1000

Table 5.3. DNA Entry Attributes

Plug-in Attribute Description
dnaPluginConfig (object class) The object class for instances of the DNA Plug-in.
cn Gives a unique name for the plug-in instance.
dnaType
Contains the name of the attributes 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.
dnaInterval Optionally, sets an interval to use to increment through numbers in a range. Essentially, this skips numbers at a predefined rate. If the interval is 3 and the first number in the range is 1, then the next number used in the ragen is 4, then 7, then 10, incrementing by three for every new number assignment.
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.
dnaSharedConfig (object class) The object class for shared configuration entries with host information, for servers in multi-master replication.
dnaHostname Identifies the host name of a server in a shared range, as part of the DNA range configuration for that specific host in multi-master replication.
dnaPortNum Gives the standard port number to use to connect to the host identified in dnaHostname.
dnaSecurePortNum Gives the secure (SSL) port number to use to connect to the host identified in dnaHostname.
dnaRemainingValues Contains the number of values that are remaining and available to a server to assign to entries.

5.4.3. 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.3.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 9.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:
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: ou=Ranges,dc=example,dc=coma
    changetype: add
    objectclass: top
    objectclass: extensibleObject
    objectclass: organizationalUnit
    ou: Ranges
    
    
    dn: cn=Account UIDs,ou=Ranges,dc=example,dc=coma
    changetype: add
    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.
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    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. Table 5.3, “DNA Entry Attributes” lists the possible plug-in attributes.

    Note

    The plug-in attribute which sets which entry attributes have unique number assignments, dnaType, is multi-valued. If multiple attributes are set in the same plug-in instance, then their number assignments are taken from the same range. To use different ranges, configure different plug-in instances.
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=Account UIDs,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config
    changetype: add
    objectClass: top
    objectClass: dnaPluginConfig
    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
    dnaMagicRegen: magic
  4. For servers in multi-master replication, create a configuration entry for the host, which specifies its connection information and range.
    The DN of the entry is a combination of the host name and the port number (dnaHostname+dnaPortNum).
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: dnaHostname=ldap1.example.com+dnaPortNum=389,cn=Account UIDs,ou=Ranges,dc=example,dc=com
    objectClass: dnaSharedConfig
    objectClass: top
    dnahostname: ldap1.example.com
    dnaPortNum: 389
    dnaSecurePortNum: 636
    dnaRemainingValues: 1000
  5. Restart the server to load the new plug-in instance.
    service dirsrv restart instance_name

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

5.4.4. Distributed Number Assignment Plug-in Performance Notes

There can be thread locking issues as DNA configuration is changed dynamically, so that new operations which access the DNS configuration (such as a DNA task or additional changes to the DNA configuration) will access the old configuration because the thread with the new configuration has not yet been released. This can cause operations to use old configuration or simply cause operations to hang.
To avoid this, preserve an interval between dynamic DNA configuration changes of 35 seconds. This means have a sleep or delay between both DNA configuration changes and any directory entry changes which would trigger a DNA plug-in operation.

Chapter 6. Organizing and Grouping Entries

Entries contained within the directory can be grouped in different ways to simplify the management of user accounts. Red Hat Directory Server supports a variety of methods for grouping entries and sharing attributes between entries. To take full advantage of the features offered by roles and class of service, determine the directory topology when planning the directory deployment.

6.1. Using Groups

Groups are a mechanism for associating entries for ease of administration. Groups do not have the flexibility or utility of roles. However, there are certain clients and applications where groups are useful. Groups also offer compatibility with older LDAP clients and directory services.

Note

Managing groups is significantly easier by using the memberOf attribute to identify in user entries to what groups a user belongs. The memberOf attribute is maintained by the Directory Server and updated automatically on entries as group membership changes. See Section 6.1.4, “Listing Group Membership in User Entries” for information on using the memberOf attribute.

6.1.1. Creating Static Groups in the Console

Static groups organize entries by specifying the same group value in the DN attribute of any number of users.

Note

If a user has an entry on a remote Directory Server (for example, in a chained database), different from the Directory Server which has the entry that defines the static group, then use the Referential Integrity plug-in to ensure that deleted user entries are automatically deleted from the static group.
There are some performance and access control considerations with the Referential Integrity plug-in. For more information about using referential integrity with chaining, see Section 2.3.2, “Configuring the Chaining Policy”.
  1. In the Directory Server Console, select the Directory tab.
  2. In the left pane, right-click the entry under which to add a new group, and select New > Group.
    Alternatively, go to the Object menu, and select New > Group.
  3. Click General in the left pane. Type a name for the new group in the Group Name field (the name is required), and enter a description of the new group in the Description field.
  4. Click Members in the left pane. In the right pane, select the Static Group tab. Click Add to add new members to the group.
  5. In the Search drop-down list, select what sort of entries to search for (users, groups, or both) then click Search.
  6. Select the members from the returned entries, and click OK.
  7. Click Languages in the left pane to add language-specific information for the group.
  8. Click OK to create the new group. It appears in the right pane.
To edit a static group, double-click the group entry, and make the changes in the editor window. To view the changes, go to the View menu, and select Refresh.

Note

The Console for managing static groups may not display all possible selections during a search operation if there is no VLV index for users' search. This problem occurs only when the number of users is 1000 or more and there is no VLV index for search. To work around the problem, create a VLV index for the users suffix with the filter (objectclass=person) and scope sub-tree.

6.1.2. Creating Dynamic Groups in the Console

Dynamic groups filter users based on their DN and include them in a single group.
  1. In the Directory Server Console, select the Directory tab.
  2. In the left pane, right-click the entry under which to add a new group, and select New > Group.
    Alternatively, go to the Object menu, and select New > Group.
  3. Click General in the left pane. Type a name for the new group in the Group Name field (the name is required), and enter a description of the new group in the Description field.
  4. Click Members in the left pane. In the right pane, select the Dynamic Group tab. Click Add to create a LDAP URL for querying the database.
  5. Enter an LDAP URL in the text field or select Construct to be guided through the construction of an LDAP URL.
    The results show the current entries (group members) which correspond to the filter.
  6. Click Languages in the left pane to add language-specific information for the group.
  7. Click OK. The new group appears in the right pane.
To edit a dynamic group, double-click the group entry to open the editor window, and make whatever changes to the dynamic group. To view the changes to the group, go to the View menu, and select Refresh.

Note

The Console for managing dynamic groups may not display all possible selections during a search operation if there is no VLV index for users' search. This problem can occur when the number of users is 1000 or more and there is no VLV index for search. To work around the problem, create a VLV index for the users suffix with the filter (objectclass=person) and scope sub-tree.

6.1.3. Creating Groups in the Command Line

Creating both static and dynamic groups from the command line is a similar process. A group entry contains the group name, the type of group, and a members attribute.
There are several different options for the type of group; these are described in more detail in the Red Hat Directory Server 9 Configuration, Command, and File Reference. The type of group in this case refers to the type of defining member attribute it has:
  • groupOfNames is a simple group, that allows any entry to be added. The attribute used to determine members for this is member.
  • groupOfUniqueNames, like groupOfNames, simply lists user DNs as members, but the members must be unique. This prevents users being added more than once as a group member, which is one way of preventing self-referential group memberships. The attribute used to determine members for this is uniqueMember.
  • groupOfURLs uses a list of LDAP URLs to filter and generate its membership list. This object class is required for any dynamic group and can be used in conjunction with groupOfNames and groupOfUniqueNames.
  • groupOfCertificates is similar to groupOfURLs in that it uses an LDAP filter to search for and identify certificates (or, really, certificate names) to identify group members. This is useful for group-based access control, since the group can be given special access permissions. The attribute used to determine members for this is memberCertificate.
Table 6.1, “Dynamic and Static Group Schema” lists the default attributes for groups as they are created from the command line.

Table 6.1. Dynamic and Static Group Schema

Type of Group Group Object Classes Member Attributes
Static groupOfUniqueNames uniqueMember
Dynamic
groupOfUniqueNames
groupOfURLs
memberURL
A static group entry lists the specific members of the group. For example:
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=static group,ou=Groups,dc=example,dc=com
changetype: add
objectClass: top
objectClass: groupOfUniqueNames
cn: static group
description: Example static group.
uniqueMember: uid=mwhite,ou=People,dc=example,dc=com
uniqueMember: uid=awhite,ou=People,dc=example,dc=com
A dynamic group uses at least one LDAP URL to identify entries belonging to the group and can specify multiple LDAP URLs or, if used with another group object class like groupOfUniqueNames, can explicitly list some group members along with the dynamic LDAP URL.
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=dynamic group,ou=Groups,dc=example,dc=com
changetype: add
objectClass: top
objectClass: groupOfUniqueNames
objectClass: groupOfURLs
cn: dynamic group
description: Example dynamic group.
memberURL: ldap:///dc=example,dc=com??sub?(&(objectclass=person)(cn=*sen*))

6.1.4. Listing Group Membership in User Entries

The entries which belong to a group are defined, in some way, in the group entry itself. This makes it very easy to look at a group and see its members and to manage group membership centrally. However, there is no good way to find out what groups a single user belongs to. There is nothing in a user entry which indicates its memberships, as there are with roles.
The MemberOf Plug-in correlates group membership lists to the corresponding user entries.
The MemberOf Plug-in analyzes the member attribute in a group entry and automatically writes a corresponding memberOf attribute in the member's entry. (By default, this checks the member attribute, but mutiple attribute instances can be used to support multiple different group types.)
As membership changes, the plug-in updates the memberOf attributes on the user entries. The MemberOf Plug-in provides a way to view the groups to which a user belongs simply by looking at the entry, including nested group membership. It can be very difficult to backtrack memberships through nested groups, but the MemberOf Plug-in shows memberships for all groups, direct and indirect.
The MemberOf Plug-in manages member attributes for static groups, not dynamic groups or circular groups.

6.1.4.1. Directory Topology Considerations with the MemberOf Plug-in

memberOf and Multi-Master Replication

The memberOf attributes for user entries should not be replicated in multi-master environments. Make sure that the memberOf attribute is excluded from replication in the replication agreement. (Fractional replication is described in Section 11.1.7, “Replicating a Subset of Attributes with Fractional Replication”.)

Each server must maintain its own MemberOf Plug-in independently. To make sure that the memberOf attributes for entries are the same across servers, simply configure the MemberOf Plug-in the same on all servers.
With single-master replication, it is perfectly safe to replicate memberOf attributes. Configure the MemberOf Plug-in for the supplier, then replicate the memberOf attributes to the consumers.
memberOf and Distributed Databases

It is possible, as outlined in Section 2.2.1, “Creating Databases”, to distribute suffixes and directory data across different databases.

By default, the MemberOf Plug-in only looks for potential members for users who are in the same database as the group. If users are stored in a different database than the group, then the user entries will not be updated with memberOf attributes because the plug-in cannot ascertain the relationship between them.
The plug-in can be configured to search across all databases by enabling the memberOfAllBackends in the plug-in configuration.

6.1.4.2. Required Object Classes by the memberOf Plug-In

To enable the memberOf plug-in to add the memberOf attribute, the user entry must contain the inetUser or inetAdmin object class to support this attribute. If you configure the memberOf plug-in to use a different attribute, make sure that the user entry contains an object class that supports this attribute.
To configure nested groups, the group must use the extensibleObject object class.

Note

If directory entries do not contain an object class that supports the required attributes, operations fail with the following error:
LDAP: error code 65 - Object Class Violation

6.1.4.3. The MemberOf Plug-in Syntax

The MemberOf Plug-in instance defines two attributes, one for the group member attribute to poll (memberOfGroupAttr) and the other for the attribute to create and manage in the member's user entry (memberOfAttr).
The memberOfGroupAttr attribute is multi-valued. Because different types of groups use different member attributes, using multiple memberOfGroupAttr attributes allows the plug-in to manage multiple types of groups.
The plug-in instance also gives the plug-in path and function to identify the MemberOf Plug-in and contains a state setting to enable the plug-in, both of which are required for all plug-ins. The default MemberOf Plug-in is shown in Example 6.1, “Default MemberOf Plug-in Entry” and the different parameters are described in Table 6.2, “MemberOf Syntax”.

Example 6.1. Default MemberOf Plug-in Entry

 dn: cn=MemberOf Plugin,cn=plugins,cn=config
 objectClass: top
 objectClass: nsSlapdPlugin
 objectClass: extensibleObject
 cn: MemberOf Plugin  
 nsslapd-pluginPath: libmemberof-plugin  
 nsslapd-pluginInitfunc: memberof_postop_init  
 nsslapd-pluginType: postoperation
 nsslapd-pluginEnabled: on  
 nsslapd-plugin-depends-on-type: database
 memberOfGroupAttr: member  
 memberOfGroupAttr: uniqueMember  
 memberOfAttr: memberOf  
 memberOfAllBackends: on  
 nsslapd-pluginId: memberOf
 nsslapd-pluginVersion: 9.0.4
 nsslapd-pluginVendor: Red Hat, Inc.
 nsslapd-pluginDescription: memberOf plugin

Table 6.2. MemberOf Syntax

Plug-in Attribute Description
cn Gives a unique name for the plug-in instance.
memberOfGroupAttr Gives the attribute in the group entry to poll to identify member DNs. By default, this is the member attribute, but it can be any attribute used to identify group members, such as uniqueMember. This is a multi-valued attribute, so if multiple types of groups will be used with the MemberOf Plug-in, multiple member type attributes can be set.
memberOfAttr Gives the attribute for the plug-in to create and manage on the user entry. By default, this is the memberOf attribute.
memberOfAllBackends Sets whether the plug-in should evaluate user entries only within the local suffix (off) or whether it should evaluate all configured databases (on).
memberOfEntryScope Sets on which suffixes the plug-in works on. If not set, the plug-in works on all suffixes.
memberOfEntryScopeExcludeSubtree Sets what suffixes the plug-in excludes.
nsslapd-pluginEnabled Sets whether the plug-in instance is enabled (active) or disabled. The default MemberOf Plug-in instance is disabled by default.
nsslapd-pluginPath Gives the name of the specific plug-in to load. This must be libmemberof-plugin.
nsslapd-pluginInitfunc Gives the name of the function to call to initialize the plug-in. This must be memberof_postop_init.

Note

To maintain backwards compatibility with older versions of Directory Server, which only allowed a single member attribute (by default, member), it may be necessary to include the member group attribute or whatever previous member attribute was used, in addition any new member attributes used in the plug-in configuration.
 memberOfGroupAttr: member  
 memberOfGroupAttr: uniqueMember  
See Example 6.1, “Default MemberOf Plug-in Entry”.

6.1.4.4. Configuring an Instance of the MemberOf Plug-in

The attributes defined in the MemberOf Plug-in can be changed, depending on the types of groups used in the directory.
6.1.4.4.1. Editing the MemberOf Plug-in from the Console
  1. Select the Configuration tab, and expand to the Plugins folder.
  2. Scroll to the Memberof Plugin entry.
  3. Make sure that the plug-in is enabled. This is disabled by default.
  4. Click the Advanced button to open the Advanced Properties Editor.
  5. The memberOfGroupAttr attribute sets the attribute in the group entry which the server uses to identify member entries; this attribute can be used multiple times for different group/member types. The memberOfAttr attribute sets the attribute which the plug-in creates and manages on user entries.
  6. Save the changes.
  7. Restart the server to update the plug-in. For example, open the Tasks tab and click the Restart server task.
6.1.4.4.2. Editing the MemberOf Plug-in from the Command Line
  1. Enable the MemberOf Plug-in.
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=MemberOf Plugin,cn=plugins,cn=config
    changetype: modify
    replace: nsslapd-pluginEnabled
    nsslapd-pluginEnabled: on
    -
  2. Set the attribute to use for the group member entry attribute. The default attribute is member, which can be changed using the replace command, or, since the memberOfGroupAttr attribute is multi-valued, additional member types can be added to the definition. For example:
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=MemberOf Plugin,cn=plugins,cn=config
    changetype: modify
    add: memberOfGroupAttr
    memberOfGroupAttr: uniqueMember
    
    add: memberOfGroupAttr
    memberOfGroupAttr: customMember-
  3. Set the attribute to set on the user entries to show group membership. For example:
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=MemberOf Plugin,cn=plugins,cn=config
    changetype: modify
    replace: memberOfAttr
    memberOfAttr: memberOf
    -
  4. Optional. If the deployment uses distributed databases, then enable the memberOfAllBackends attribute to search through all databases, not just the local one, for user entries.
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=MemberOf Plugin,cn=plugins,cn=config
    changetype: modify
    replace: memberOfAllBackends
    memberOfAllBackends: on
    -
  5. Restart the Directory Server to load the modified new plug-in instance.
    service dirsrv restart instance_name

6.1.4.5. Setting the Scope of the MemberOf Plug-in

If you configured several back ends or multiple-nested suffixes, you can use the memberOfEntryScope and memberOfEntryScopeExcludeSubtree parameters to set what suffixes the MemberOf plug-in works on.
If you add a user to a group, the MemberOf plug-in only adds the memberOf attribute to the group if both the user and the group are in the plug-in's scope. For example, to configure the MemberOf plug-in to work on all entries in dc=example,dc=com, but to exclude entries in ou=private,dc=example,dc=com, set:
memberOfEntryScope: dc=example,dc=com
memberOfEntryScopeExcludeSubtree: ou=private,dc=example,dc=com
If you moved a user entry out of the scope set in the memberOfEntryScope parameter:
  • The membership attribute, such as member, is updated in the group entry to remove the user DN value.
  • The memberOf attribute is updated in the user entry to remove the group DN value.

Note

The value set in the memberOfEntryScopeExcludeSubtree parameter has a higher priority than values set in memberOfEntryScope. If the scopes set in both parameters overlap, the MemberOf plug-in only works on the non-overlapping directory entries.

6.1.4.6. Synchronizing memberOf Values

The MemberOf Plug-in automatically manages the memberOf attribute on group member entries, based on the configuration in the group entry itself. However, the memberOf attribute can be edited on a user entry directly (which is improper) or new entries can be imported or replicated over to the server that have a memberOf attribute already set. These situations create inconsistencies between the memberOf configuration managed by the server plug-in and the actual memberships defined for an entry.
Directory Server has a memberOf repair task which manually runs the plug-in to make sure the appropriate memberOf attributes are set on entries. There are three ways to trigger this task:
  • In the Directory Server Console
  • Using the fixup-memberof.pl script
  • Running a cn=memberof task,cn=tasks,cn=config tasks entry

Note

The memberOf regeneration tasks are run locally, even if the entries themselves are replicated. This means that the memberOf attributes for the entries on other servers are not updated until the updated entry is replicated.
6.1.4.6.1. Initializing and Regenerating memberOf Attributes Using fixup-memberof.pl
The fixup-memberof.pl script launches a special task to regenerate all of the memberOf attributes on user entries based on the defined member attributes in the group entries. This is a clean-up task which synchronizes the membership defined in group entries and the corresponding user entries and overwrites any accidental or improper edits on the user entries.
  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.
    ./fixup-memberof.pl -D "cn=Directory Manager" -w password
The fixup-memberof.pl command is described in more detail in the Configuration and Command-Line Tool Reference.
6.1.4.6.2. Initializing and Regenerating memberOf Attributes Using ldapmodify
Regenerating memberOf 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. As soon as the task is complete, the entry is removed from the directory.
The fixup-memberof.pl script creates a special task entry in a Directory Server instance which regenerates the memberOf attributes.
To initiate a memberOf fixup task, add an entry under the cn=memberof task, cn=tasks,cn=config entry. The only required attribute is the cn for the specific task.
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=example memberOf,cn=memberof task,cn=tasks,cn=config
changetype: add
cn:example memberOf
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=memberof task configuration is described in more detail in the Configuration and Command-Line Tool Reference.

6.1.5. Automatically Adding Entries to Specified Groups

Group management can be a critical factor for managing directory data, especially for clients which use Directory Server data and organization or which use groups to apply functionality to entries. Groups make it easier to apply policies consistently and reliably across the directory. Password policies, access control lists, and other rules can all be based on group membership.
Being able to assign new entries to groups, automatically, at the time that an account is created ensures that the appropriate policies and functionality are immediately applied to those entries — without requiring administrator intervention.
Dynamic groups are one method of creating groups and assigning members automatically because any matching entry is automatically included in the group. For applying Directory Server policies and settings, this is sufficient. However, LDAP applications and clients commonly need a static and explicit list of group members in order to perform whatever operation is required. And all of the members in static groups have to be manually added to those groups.
The static group itself cannot search for members like a dynamic group, but there is a way to allow a static group to have members added to it automatically — the Auto Membership Plug-in.
Automembership essentially allows a static group to act like a dynamic group, at least for adding new members to the group. Different automembership definitions create searches that are automatically run on all new directory entries. The automembership rules search for and identify matching entries — much like the dynamic search filters — and then explicitly add those entries as members to the static group.

Note

Automembership assignments are only made automatically when an entry is added to the Directory Server.
For existing entries or entries who are edited to match an automember group rule, there is a fix-up task which can be run that updates the group membership.
The Auto Membership Plug-in can target any type of object stored in the directory: users, machines and network devices, customer data, or other assets.

Note

The Auto Membership Plug-in adds a new entry to an existing group based on defined criteria. It does not create a group for the new entry.
To create a corresponding group entry when a new entry of a certain type is created, use the Managed Entries Plug-in. This is covered in Section 6.3, “Automatically Creating Dual Entries”.

6.1.5.1. Looking at the Structure of an Automembership Rule

The Auto Membership Plug-in itself is a container entry in cn=plugins,cn=config. Group assignments are defined through child entries.
6.1.5.1.1. The Automembership Configuration Entry
Automembership assignments are created through a main definition entry, a child of the Auto Membership Plug-in entry. Each definition entry defines three elements:
  • An LDAP search to identify entries, including both a search scope and a search filter (autoMemberScope and autoMemberFilter)
  • A default group to which to add the member entries (autoMemberDefaultGroup)
  • The member entry format, which is the attribute in the group entry, such as member, and the attribute value, such as dn (autoMemberGroupingAttr)
The definition is the basic configuration for an automember rule. It identifies all of the required information: what a matching member entry looks like and a group for that member to belong to.
For example, this definition assigns all Windows users to the cn=windows-users group:
dn: cn=Windows Users,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberDefinition
autoMemberScope: ou=People,dc=example,dc=com
autoMemberFilter: objectclass=ntUser
autoMemberDefaultGroup: cn=windows-group,cn=groups,dc=example,dc=com
autoMemberGroupingAttr: member:dn
The attributes for the definition entry are listed in Table 6.3, “Automember Definition Attributes”.

Table 6.3. Automember Definition Attributes

Attribute Description
autoMemberDefinition (required object class) Identifies the entry as an automember definition. This entry must be a child of the Auto Membership Plug-in, cn=Auto Membership Plugin,cn=plugins,cn=config.
autoMemberScope Sets the subtree DN to search for entries. This is the search base.
autoMemberFilter Sets a standard LDAP search filter to use to search for matching entries. Examples of search filters are in Section 10.4, “LDAP Search Filters”.
autoMemberDefaultGroup Sets a default or fallback group to add the entry to as a member.
If the definition does not use any regular expression conditions, then this is the primary group to which entries are added. If the automember definition does have defined regular expression conditions, then an entry is added to those specified groups first, and the autoMemberDefaultGroup group is used as a fallback for entries which match the autoMemberFilter but do not match a regular expression.
autoMemberGroupingAttr Sets the name of the member attribute in the group entry and the attribute in the object entry that supplies the member attribute value.
This structures how the Auto Membership Plug-in adds a member to the group, depending on the group configuration. For example, for a groupOfUniqueNames user group, each member is added as a uniqueMember attribute. The value of uniqueMember is the DN of the user entry. In essence, each group member is identified by the attribute-value pair of uniqueMember: user_entry_DN. The member entry format, then, is uniqueMember:dn.
6.1.5.1.2. Additional Regular Expression Entries
For something like a users group, where more than likely all matching entries should be added as members, a simple definition is sufficient. However, there can be instances where entries that match the LDAP search filter should be added to different groups, depending on the value of some other attribute. For example, machines may need to be added to different groups depending on their IP address or physical location; users may need to be in different groups depending on their employee ID number.
The automember definition can use regular expressions to provide additional conditions on what entries to include or exclude from a group, and then a new, specific group to add those selected entries to.
For example, an automember definition sets all machines to be added to a generic host group.

Example 6.2. Automember Definition for a Host Group

dn: cn=Hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberDefinition
cn: Hostgroups
autoMemberScope: dc=example,dc=com
autoMemberFilter: objectclass=ipHost
autoMemberDefaultGroup: cn=systems,cn=hostgroups,ou=groups,dc=example,dc=com
autoMemberGroupingAttr: member:dn
A regular expression rule is added so that any machine with a fully-qualified domain name within a given range is added to a web server group.

Example 6.3. Regular Expression Condition for a Web Server Group

dn: cn=webservers,cn=Hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberRegexRule
description: Group for webservers
cn: webservers
autoMemberTargetGroup: cn=webservers,cn=hostgroups,dc=example,dc=com
autoMemberInclusiveRegex: fqdn=^www\.web[0-9]+\.example\.com
So, any host machine added with a fully-qualified domain name that matches the expression ^www\.web[0-9]+\.example\.com, such as www.web1.example.com, is added to the cn=webservers group, defined for that exact regular expression. Any other machine entry, which matches the LDAP filter objectclass=ipHost but with a different type of fully-qualified domain name, is added to the general host group, cn=systems, defined in the main definition entry.
The group in the definition, then, is a fallback for entries which match the general definition, but do not meet the conditions in the regular expression rule.
Regular expression rules are child entries of the automember definition.
Regular Expression Conditions

Figure 6.1. Regular Expression Conditions

Each rule can include multiple inclusion and exclusion expressions. (Exclusions are evaluated first.) If an entry matches any inclusion rule, it is added to the group.
There can be only one target group given for the regular expression rule.

Table 6.4. Regular Expression Condition Attributes

Attribute Description
autoMemberRegexRule (required object class) Identifies the entry as a regular expression rule. This entry must be a child of an automember definition (objectclass: autoMemberDefinition).
autoMemberInclusiveRegex Sets a regular expression to use to identify entries to include. Only matching entries are added to the group. Multiple regular expressions could be used, and if an entry matches any one of those expressions, it is included in the group.
The format of the expression is a Perl-compatible regular expression (PCRE). For more information on PCRE patterns, see the pcresyntax(3) man page.
This is a multi-valued attribute.
autoMemberExclusiveRegex Sets a regular expression to use to identify entries to exclude. If an entry matches the exclusion condition, then it is not included in the group. Multiple regular expressions could be used, and if an entry matches any one of those expressions, it is excluded in the group.
The format of the expression is a Perl-compatible regular expression (PCRE). For more information on PCRE patterns, see the pcresyntax(3) man page.
This is a multi-valued attribute.

Note

Exclude conditions are evaluated first and take precedence over include conditions.
autoMemberTargetGroup Sets which group to add the entry to as a member, if it meets the regular expression conditions.

6.1.5.2. Examples of Automembership Rules

Automembership rules are usually going to applied to users and to machines (although they can be applied to any type of entry). There are a handful of examples that may be useful in planning automembership rules:
  • Different host groups based on IP address
  • Windows user groups
  • Different user groups based on employee ID

Example 6.4. Host Groups by IP Address

The automember rule first defines the scope and target of the rule. The example in Section 6.1.5.1.2, “Additional Regular Expression Entries” uses the configuration group to define the fallback group and a regular expression entry to sort out matching entries.
The scope is used to find all host entries. The plug-in then iterates through the regular expression entries. If an entry matches an inclusive regular expression, then it is added to that host group. If it does not match any group, it is added to the default group.
The actual plug-in configuration entries are configured like this, for the definition entry and two regular expression entries to filter hosts into a web servers group or a mail servers group.
configuration entry
dn: cn=Hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberDefinition
cn: Hostgroups
autoMemberScope: dc=example,dc=com
autoMemberFilter: objectclass=bootableDevice
autoMemberDefaultGroup: cn=orphans,cn=hostgroups,dc=example,dc=com
autoMemberGroupingAttr: member:dn

regex entry #1
dn: cn=webservers,cn=Hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberRegexRule
description: Group placement for webservers
cn: webservers
autoMemberTargetGroup: cn=webservers,cn=hostgroups,dc=example,dc=com
autoMemberInclusiveRegex: fqdn=^www[0-9]+\.example\.com
autoMemberInclusiveRegex: fqdn=^web[0-9]+\.example\.com
autoMemberExclusiveRegex: fqdn=^www13\.example\.com
autoMemberExclusiveRegex: fqdn=^web13\.example\.com

regex entry #2
dn: cn=mailservers,cn=Hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberRegexRule
description: Group placement for mailservers
cn: mailservers
autoMemberTargetGroup: cn=mailservers,cn=hostgroups,dc=example,dc=com
autoMemberInclusiveRegex: fqdn=^mail[0-9]+\.example\.com
autoMemberInclusiveRegex: fqdn=^smtp[0-9]+\.example\.com
autoMemberExclusiveRegex: fqdn=^mail13\.example\.com
autoMemberExclusiveRegex: fqdn=^smtp13\.example\.com

Example 6.5. Windows User Group

The basic users group shown in Section 6.1.5.1.1, “The Automembership Configuration Entry” uses the posixAccount attribute to identify all new users. All new users created within Directory Server are created with the posixAccount attribute, so that is a safe catch-all for new Directory Server users. However, when user accounts are synced over from the Windows domain to the Directory Server, the Windows user accounts are created without the posixAccount attribute.
Windows users are identified by the ntUser attribute. The basic, all-users group rule can be modified to target Windows users specifically, which can then be added to the default all-users group or to a Windows-specific group.
dn: cn=Windows Users,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberDefinition
autoMemberScope: dc=example,dc=com
autoMemberFilter: objectclass=ntUser
autoMemberDefaultGroup: cn=Windows Users,cn=groups,dc=example,dc=com
autoMemberGroupingAttr: member:dn

Example 6.6. User Groups by Employee Type

The Auto Membership Plug-in can work on custom attributes, which can be useful for entries which are managed by other applications. For example, a human resources application may create and then reference users based on the employee type, in a custom employeeType attribute.
Much like Example 6.4, “Host Groups by IP Address”, the user type rule uses two regular expression filters to sort full time and temporary employees, only this example uses an explicit value rather than a true regular expression. For other attributes, it may be more appropriate to use a regular expression, like basing the filter on an employee ID number range.
configuration entry
dn: cn=Employee groups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberDefinition
cn: Hostgroups
autoMemberScope: ou=employees,ou=people,dc=example,dc=com
autoMemberFilter: objectclass=inetorgperson
autoMemberDefaultGroup: cn=general,cn=employee groups,ou=groups,dc=example,dc=com
autoMemberGroupingAttr: member:dn

regex entry #1
dn: cn=full time,cn=Employee groups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberRegexRule
description: Group for full time employees
cn: full time
autoMemberTargetGroup: cn=full time,cn=employee groups,ou=groups,dc=example,dc=com
autoMemberInclusiveRegex: employeeType=full

regex entry #2
dn: cn=temporary,cn=Employee groups,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberRegexRule
description: Group placement for interns, contractors, and seasonal employees
cn: temporary
autoMemberTargetGroup: cn=temporary,cn=employee groups,ou=groups,dc=example,dc=com
autoMemberInclusiveRegex: employeeType=intern
autoMemberInclusiveRegex: employeeType=contractor
autoMemberInclusiveRegex: employeeType=seasonal

6.1.5.3. Creating Automembership Definitions

  1. If necessary, enable the Auto Membership Plug-in.
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=Auto Membership Plugin,cn=plugins,cn=config
    changetype: replace
    replace: nsslapd-pluginEnabled
    nsslapd-pluginEnabled: on
    -
  2. Create the new plug-in instance below the cn=Auto Membership Plugin,cn=plugins,cn=config container entry. This entry must belong to the autoMemberDefinition object class.
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=Example Automember Definition,cn=Auto Membership Plugin,cn=plugins,cn=config
    objectclass: autoMemberDefinition
    The required attributes for the definition are listed in Table 6.3, “Automember Definition Attributes”.
  3. Set the scope and filter for the definition. This is used for the initial search for matching entries.
    For example, for new entries added to the ou=People subtree and containing the ntUser attribute:
    autoMemberScope: ou=People,dc=example,dc=com
    autoMemberFilter: objectclass=ntUser
  4. Set the group to which to add matching entries (as the default or fallback group) and the format of the member entries for that group type.
    autoMemberDefaultGroup: cn=windows-group,cn=groups,dc=example,dc=com
    autoMemberGroupingAttr: member:dn
  5. Optional. Create inclusive or exclusive regular expression filters and set a group to use for entries matching those filters.
    The attributes for the regular expression condition are listed in Table 6.4, “Regular Expression Condition Attributes”.
    Regular expression conditions are added as children of the automember definition. These conditions must belong to the autoMemberRegexRule object class.
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=Example Regex,cn=Example Automember Definition,cn=Auto Membership Plugin,cn=plugins,cn=config
    objectclass: autoMemberRegexRule
    Then add the target group name and any inclusive or exclusive regular expressions. Both include and exclude conditions can be used, and multiple expressions of both types can be used.
    autoMemberTargetGroup: cn=webservers,cn=hostgroups,dc=example,dc=com
    autoMemberInclusiveRegex: fqdn=^www\.web[0-9]+\.example\.com
    If a new entry matches a regular expression condition, it is added to that group instead of the default group set in the automember definition.
  6. Restart the Directory Server to load the modified new plug-in instance.
    service dirsrv restart instance_name

6.1.5.4. Updating Existing Entries for Automembership Definitions

The Auto Member Plug-in only runs when new entries are added to the directory. The plug-in ignores existing entries or entries which are edited to match an automembership rule.
There is a directory task operation which can be run to check existing entries against automembership rules and then update group membership accordingly. This task (cn=automember rebuild membership) requires three elements to run, based on LDAP search parameters to identify which existing entries to process:
  • The search filter
  • The search scope
  • The base DN from which to begin the search
The specific task run also needs a name.
The task entry can be created using ldapmodify; when the task completes, the entry is automatically removed. For example:
[root@server ~]# ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=my rebuild task, cn=automember rebuild membership,cn=tasks,cn=config
objectClass: top
objectClass: extensibleObject
cn: my rebuild task
basedn: dc=example,dc=com
filter: (uid=*)
scope: sub

6.1.5.5. Testing Automembership Definitions

Because each instance of the Auto Member Plug-in is a set of related-but-separate entries for the definition and regular expression, it can be difficult to see exactly how users are going to be mapped to groups. This becomes even more difficult when there are multiple rules which target different subsets of users.
There are two dry-run tasks which can be useful to determine whether all of the different Auto Member Plug-in definitions are assigning groups properly as designed.
Testing with Existing Entries

cn=automember export updates runs against existing entries in the directory and exports the results of what users would have been added to what groups, based on the rules. This is useful for testing existing rules against existing users to see how your real deployment are performing.

This task requires the same information as the cn=automember rebuild membership task — the base DN to search, search filter, and search scope — and has an additional parameter to specify an export LDIF file to record the proposed entry updates.
[root@server ~]# ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=test export, cn=automember export updates,cn=tasks,cn=config
objectClass: top
objectClass: extensibleObject
cn: test export
basedn: dc=example,dc=com
filter: (uid=*)
scope: sub
ldif: /tmp/automember-updates.ldif
Testing with an Import LDIF

cn=automember map updates takes an import LDIF of new users and then runs the new users against the current automembership rules. This can be very useful for testing a new rule, before applying it to (real) new or existing user entries.

This is called a map task because it maps or relates changes for proposed new entries to the existing rules.
This task only requires two attributes: the location of the input LDIF (which must contain at least some user entries) and an output LDIF file to which to write the proposed entry updates. Both the input and output LDIF files are absolute paths on the local machine.
For example:
[root@server ~]# ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=test mapping, cn=automember map updates,cn=tasks,cn=config
objectClass: top
objectClass: extensibleObject
cn: test mapping
ldif_in: /tmp/entries.ldif
ldif_out: /tmp/automember-updates.ldif

6.2. Using Roles

Roles are an entry grouping mechanism that unify the static and dynamic groups described in the previous sections. Roles are designed to be more efficient and easier to use for applications. For example, an application can get the list of roles of which an entry is a member by querying the entry itself, rather than selecting a group and browsing the members list of several groups.

6.2.1. About Roles

Red Hat has two kinds of groups. Static groups have a finite and defined list of members. Dynamic groups used filters to recognize which entries are members of the group, so the group membership is constantly changed as the entries which match the group filter change. (Both kinds of groups are described in Section 6.1, “Using Groups”.)
Roles are a sort of hybrid group, behaving as both a static and a dynamic group. With a group, entries are added to a group entry as members. With a role, the role attribute is added to an entry and then that attribute is used to identify members in the role entry automatically.
Role members are entries that possess the role. Members can be specified either explicitly or dynamically. How role membership is specified depends upon the type of role. Directory Server supports three types of roles:
  • Managed roles have an explicit enumerated list of members.
  • Filtered roles are assigned entries to the role depending upon the attribute contained by each entry, specified in an LDAP filter. Entries that match the filter possess the role.
  • Nested roles are roles that contain other roles.
Managed roles can do everything that can normally be done with static groups. The role members can be filtered using filtered roles, similarly to the filtering with dynamic groups. Roles are easier to use than groups, more flexible in their implementation, and reduce client complexity.
When a role is created, determine whether a user can add themselves or remove themselves from the role. See Section 6.2.10, “Using Roles Securely” for more information about roles and access control.

Note

Evaluating roles is more resource-intensive for the Directory Server than evaluating groups because the server does the work for the client application. With roles, the client application can check role membership by searching for the nsRole attribute. The nsRole attribute is a computed attribute, which identifies to which roles an entry belongs; the nsRole attribute is not stored with the entry itself. From the client application point of view, the method for checking membership is uniform and is performed on the server side.
Considerations for using roles are covered in the Directory Server Deployment Guide.

6.2.2. Creating a Managed Role

Managed roles have an explicit enumerated list of members. Managed roles are added to entries by adding the nsRoleDN attribute to the entry.

6.2.2.1. Creating a Managed Role in the Console

  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 role.
  3. Go to the Object menu, and select New > Role.
    Alternatively, right-click the entry and select New > Role.
  4. Click General in the left pane. Type a name for the new role in the Role Name field. The role name is required.
  5. Enter a description of the new role in the Description field.
  6. Click Members in the left pane.
  7. In the right pane, select Managed Role. Click Add to add new entries to the list of members.
  8. In the Search drop-down list, select Users from the Search drop-down list, then click Search. Select one of the entries returned, and click OK.
  9. After adding all of the entries, click OK.

6.2.2.2. Creating Managed Roles through the Command Line

Roles inherit from the ldapsubentry object class, which is defined in the ITU X.509 standard. In addition, each managed role requires two object classes that inherit from the nsRoleDefinition object class:
  • nsSimpleRoleDefinition
  • nsManagedRoleDefinition
A managed role also allows an optional description attribute.
Members of a managed role have the nsRoleDN attribute in their entry.
This example creates a role which can be assigned to the marketing department.
  1. Use ldapmodify with the -a option to add the managed role entry. The new entry must contain the nsManagedRoleDefinition object class, which in turn inherits from the LdapSubEntry, nsRoleDefinition, and nsSimpleRoleDefinition object classes.
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=Marketing,ou=people,dc=example,dc=com
    objectclass: top
    objectclass: LdapSubEntry
    objectclass: nsRoleDefinition
    objectclass: nsSimpleRoleDefinition
    objectclass: nsManagedRoleDefinition
    cn: Marketing
    description: managed role for marketing staff
  2. Assign the role to the marketing staff members, one by one, using ldapmodify:
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=Bob,ou=people,dc=example,dc=com
    changetype: modify
    add: nsRoleDN
    nsRoleDN: cn=Marketing,ou=people,dc=example,dc=com
    The nsRoleDN attribute in the entry indicates that the entry is a member of a managed role, cn=Marketing,ou=people,dc=example,dc=com.

6.2.3. Creating a Filtered Role

Entries are assigned to a filtered role depending whether the entry possesses a specific attribute defined in the role. The role definition specifies an LDAP filter for the target attributes. Entries that match the filter possess (are members of) the role.

6.2.3.1. Creating a Filtered Role in the Console

  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 role.
  3. Go to the Object menu, and select New > Role.
    Alternatively, right-click the entry and select New > Role.
  4. Click General in the left pane. Type a name for the new role in the Role Name field. The role name is required.
  5. Enter a description of the new role in the Description field.
  6. Click Members in the left pane.
    A search dialog box appears briefly.
  7. In the right pane, select Filtered Role.
  8. Enter an LDAP filter in the text field, or click Construct to be guided through the construction of an LDAP filter.
    The Construct opens the standard LDAP URL construction dialog. Ignore the fields for LDAP Server Host, Port, Base DN, and Search (since the search scope cannot be set filtered role definitions).
    • Select the types of entries to filter from the For drop-down list. The entries can be users, groups, or both.
    • Select an attribute from the Where drop-down list. The two fields following it refine the search by selecting one of the qualifiers from the drop-down list, such as contains, does not contain, is, or is not. Enter an attribute value in the text box. To add additional filters, click More. To remove unnecessary filters, click Fewer.
  9. Click Test to try the filter.
  10. Click OK.

6.2.3.2. Creating a Filtered Role through the Command Line

Roles inherit from the ldapsubentry object class, which is defined in the ITU X.509 standard. In addition, each filtered role requires two object classes that inherit from the nsRoleDefinition object class:
  • nsComplexRoleDefinition
  • nsFilteredRoleDefinition
A filtered role entry also requires the nsRoleFilter attribute to define the LDAP filter to determine role members. Optionally, the role can take a description attribute.
Members of a filtered role are entries that match the filter specified in the nsRoleFilter attribute.
This example creates a filtered role which is applied to all sales managers.
  1. Run ldapmodify with the -a option to add a new entry:
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
  2. Create the filtered role entry.
    The role entry has the nsFilteredRoleDefinition object class, which inherits from the LdapSubEntry, nsRoleDefinition, and nsComplexRoleDefinition object classes.
    The nsRoleFilter attribute sets a filter for o (organization) attributes that contain a value of sales managers.
    dn: cn=SalesManagerFilter,ou=people,dc=example,dc=com
    changetype: add
    objectclass: top
    objectclass: LDAPsubentry
    objectclass: nsRoleDefinition
    objectclass: nsComplexRoleDefinition
    objectclass: nsFilteredRoleDefinition
    cn: SalesManagerFilter
    nsRoleFilter: o=sales managers
    Description: filtered role for sales managers
The following entry matches the filter (possesses the o attribute with the value sales managers), and, therefore, it is a member of this filtered role automatically:
dn: cn=Pat Smith,ou=people,dc=example,dc=com
objectclass: person
cn: Pat
sn: Smith
userPassword: secret
o: sales managers

6.2.4. Creating a Nested Role

Nested roles are roles that contain other roles. Before it is possible to create a nested role, another role must exist. When a nested role is created, the Console displays a list of the roles available for nesting. The roles nested within the nested role are specified using the nsRoleDN attribute.

6.2.4.1. Creating a Nested Role in the Console

  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 role.
  3. Go to the Object menu, and select New > Role.
    Alternatively, right-click the entry and select New > Role.
  4. Click General in the left pane. Type a name for the new role in the Role Name field. The role name is required.
  5. Click Members in the left pane.
  6. In the right pane, select Nested Role.
  7. Click Add to add roles to the list. The members of the nested role are members of other existing roles.
  8. Select a role from the Available roles list, and click OK.

6.2.4.2. Creating Nested Role through the Command Line

Roles inherit from the ldapsubentry object class, which is defined in the ITU X.509 standard. In addition, each nested role requires two object classes that inherit from the nsRoleDefinition object class:
  • nsComplexRoleDefinition
  • nsNestedRoleDefinition
A nested role entry also requires the nsRoleDN attribute to identify the roles to nest within the container role. Optionally, the role can take a description attribute.
Members of a nested role are members of the roles specified in the nsRoleDN attributes of the nested role definition entry.
This example creates a single role out of the managed marketing role and filtered sales manager role.
  1. Run ldapmodify with the -a option to add a new entry:
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
  2. Create the nested role entry. The nested role has four object classes:
    • nsNestedRoleDefinition
    • LDAPsubentry (inherited)
    • nsRoleDefinition (inherited)
    • nsComplexRoleDefinition (inherited)
    The nsRoleDN attributes contain the DNs for both the marketing managed role and the sales managers filtered role.
    dn: cn=MarketingSales,ou=people,dc=example,dc=com
    objectclass: top
    objectclass: LDAPsubentry
    objectclass: nsRoleDefinition
    objectclass: nsComplexRoleDefinition
    objectclass: nsNestedRoleDefinition
    cn: MarketingSales
    nsRoleDN: cn=SalesManagerFilter,ou=people,dc=example,dc=com
    nsRoleDN: cn=Marketing,ou=people,dc=example,dc=com
Both of the users in the previous examples, Bob and Pat, are members of this new nested role.

6.2.5. Editing and Assigning Roles to an Entry

The entries which belong to a role are assigned on the role entry itself. For managed roles, user entries are added explicitly; for filtered roles, they are added through the results of an LDAP filter.
User entries are assigned to the role through the command line by editing the role entry, either by adding the entry as a member or adjusting the filter so it is included. In the Directory Server Console, however, there is a shortcut to add entries to a role by apparently editing the desired user entry (but, functionally, this really edits the role entry).
  1. Select the Directory tab.
  2. In the left navigation pane, browse the tree, and select the entry for which to view or edit a role.
  3. Select Set Roles from the Object menu.
  4. Select the Managed Roles tab to display the managed roles to which this entry belongs.
  5. To add a new managed role, click Add, and select an available role from the Role Selector window.

    Note

    The configuration for a managed role associated with an entry can be edited by clicking the Edit button. The Edit Entry dialog box opens, and the general information or members for the role can be changed.
  6. Select the Other Roles tab to view the filtered or nested roles to which this entry belongs.
    Click Edit to make changes to any filtered or nested roles associated with the entry.

6.2.6. Viewing Roles for an Entry through the Command Line

Role assignments are always visible for an entry when it is displayed in the Directory Server Console. Role assignments are not returned automatically through the command line, however.
The nsRole attribute is an operational attribute. In LDAP, operational attributes must be requested explicitly in the search attributes list; they are not returned by default with the regular attributes in the schema of the entry. For example, this ldapsearch command returns the list of roles of which uid=scarter is a member, in addition to the regular attributes for the entry:
 ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "dc=example,dc=com" -s sub -x “(uid=scarter)” \* nsRole  

 dn: uid=scarter,ou=people,dc=example,dc=com
 objectClass: inetorgperson
 objectClass: top
 objectClass: person
 objectClass: organizationalPerson
 uid: scarter
 cn: Sam Carter
 sn: Carter
 givenName: Sam
 mail: scarter@example.com
 userPassword: {SSHA}6BE31mhTfcYyIQF60kWlnEL8sIvPZ59hvFTRKw==
 manager: uid=lbrown,ou=people,dc=example,dc=com
 nsRole: cn=Role for Managers,dc=example,dc=com  
 nsRole: cn=Role for Accounting,dc=example,dc=com  

Important

Be sure to use the nsRole attribute, not the nsRoleDN attribute, to evaluate role membership.

6.2.7. Making a Role Inactive or Active

The concept of activating/inactivating roles allows entire groups of entries to be activated or inactivated in just one operation. That is, the members of a role can be temporarily disabled by inactivating the role to which they belong.
When a role is inactivated, it does not mean that the user cannot bind to the server using that role entry. The meaning of an inactivated role is that the user cannot bind to the server using any of the entries that belong to that role; the entries that belong to an inactivated role will have the nsAccountLock attribute set to true.
Members of a role can be temporarily disabled by inactivating the role to which they belong. Inactivating a role inactivates the entries possessed by the role, not the role itself.
  1. Select the Directory tab.
  2. Browse the navigation tree in the left pane to locate the base DN for the role. Roles appear in the right pane with other entries.
  3. Double-click the role, open the Account tab, and click the Inactivate button.
    Alternatively, select the role. Right-click the role and select Inactivate from the menu.
The role is inactivated.
To reactivate a disabled role, re-open the role configuration or open the Object menu, and select Activate. All of the members of the role are re-enabled.

6.2.8. Viewing the Activation Status for Entries

When a nested role is inactivated, a user cannot bind to the server if it is a member of any role within the nested role. All the entries that belong to a role that directly or indirectly are members of the nested role have nsAccountLock set to true. There can be several layers of nested roles, and inactivating a nested role at any point in the nesting will inactivate all roles and users beneath it.
The Directory Server Console automatically shows the active or inactive status of entries.
To see the inactivated entries, select Inactivation State from the View menu. Members of an inactivated role have a red slash through them. For example, John Smith is a member of the inactive Example Role.
The nsAccountLock attribute is an operational attribute and must be explicitly requested in the search command in the list of search attributes. For example:
ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "dc=example,dc=com" -s sub -x “(uid=scarter)” nsAccountLock

6.2.9. About Deleting Roles

Deleting a role deletes the role entry but does not delete the nsRoleDN attribute for each role member. To delete the nsRoleDN attribute for each role member, enable the Referential Integrity plug-in, and configure it to manage the nsRoleDN attribute. For more information on the Referential Integrity plug-in, see Section 3.6, “Maintaining Referential Integrity”.

6.2.10. Using Roles Securely

Not every role is suitable for use in a security context. When creating a new role, consider how easily the role can be assigned to and removed from an entry. Sometimes it is appropriate for users to be able to add or remove themselves easily from a role. For example, if there is an interest group role called Mountain Biking, interested users should be able to add themselves or remove themselves easily.
However, it is inappropriate to have such open roles for some security situations. One potential security risk is inactivating user accounts by inactivating roles. Inactive roles have special ACIs defined for their suffix. If an administrator allows users to add and remove themselves from roles freely, then in some circumstance, they may be able to remove themselves from an inactive role to prevent their accounts from being locked.
For example, user A possesses the managed role, MR. The MR role has been locked using account inactivation. This means that user A cannot bind to the server because the nsAccountLock attribute is computed as true for that user. However, if user A was already bound to Directory Server and noticed that he is now locked through the MR role, the user can remove the nsRoleDN attribute from his entry and unlock himself if there are no ACIs preventing him.
To prevent users from removing the nsRoleDN attribute, use the following ACIs depending upon the type of role being used.
  • Managed roles. For entries that are members of a managed role, use the following ACI to prevent users from unlocking themselves by removing the appropriate nsRoleDN:
    aci: (targetattr="nsRoleDN") (targetattrfilters= add=nsRoleDN:(!(nsRoleDN=cn=AdministratorRole,dc=example,dc=com)), del=nsRoleDN:(!(nsRoleDN=cn=nsManagedDisabledRole,dc=example,dc=com))) (version3.0;acl "allow mod of nsRoleDN by self but not to critical values"; allow(write) userdn=ldap:///self;)
  • Filtered roles. The attributes that are part of the filter should be protected so that the user cannot relinquish the filtered role by modifying an attribute. The user should not be allowed to add, delete, or modify the attribute used by the filtered role. If the value of the filter attribute is computed, then all attributes that can modify the value of the filter attribute should be protected in the same way.
  • Nested roles. A nested role is comprised of filtered and managed roles, so both ACIs should be considered for modifying the attributes (nsRoleDN or something else) of the roles that comprise the nested role.
For more information about account inactivation, see Section 14.11, “Manually Inactivating Users and Roles”.

6.3. Automatically Creating Dual Entries

Some clients and integration with Red Hat Directory Server require dual entries. For example, both Posix systems typically have a group for each user. The Directory Server's Managed Entries Plug-in creates a new managed entry, with accurate and specific values for attributes, automatically whenever an appropriate origin entry is created.

6.3.1. About Managed Entries

The basic idea behind the Managed Entries Plug-in is that there are situations when Entry A is created and there should automatically be an Entry B with related attribute values. For example, when a Posix user (posixAccount entry) is created, a corresponding group entry (posixGroup entry) should also be created. An instance of the Managed Entries Plug-in identifies what entry (the origin entry) triggers the plug-in to automatically generate a new entry (the managed entry).
The plug-in works within a defined scope of the directory tree, so only entries within that subtree and that match the given search filter trigger a Managed Entries operation.
Much like configuring a class of service, a managed entry is configured through two entries:
  • A definition entry, that identifies the scope of the plug-in instance and the template to use
  • A template entry, that models what the final managed entry will look like

6.3.1.1. About the Instance Definition Entry

As with the Linked Attributes and DNA Plug-ins, the Managed Entries Plug-in has a container entry in cn=plugins,cn=config, and each unique configuration instance of the plug-in has a definition entry beneath that container.
An instance of the Managed Entries Plug-in defines three things:
  • The search criteria to identify the origin entries (using a search scope and a search filter)
  • The subtree under which to create the managed entries (the new entry location)
  • The template entry to use for the managed entries
Defining Managed Entries

Figure 6.2. Defining Managed Entries

For example:
dn: cn=Posix User-Group,cn=Managed Entries,cn=plugins,cn=config
objectclass: extensibleObject
cn: Posix User-Group
originScope: ou=people,dc=example,dc=com
originFilter: objectclass=posixAccount
managedBase: ou=groups,dc=example,dc=com
managedTemplate: cn=Posix User-Group Template,ou=Templates,dc=example,dc=com
The origin entry does not have to have any special configuration or settings to create a managed entry; it simply has to be created within the scope of the plug-in and match the given search filter.

6.3.1.2. About the Template Entry

Each instance of the plug-in uses a template entry which defines the managed entry configuration. The template effectively lays out the entry, from the object classes to the entry values.

Note

Since the template is referenced in the definition entry, it can be located anywhere in the directory. However, it is recommended that the template entry be under the replicated suffix so that any other masters in multi-master replication all use the same template for their local instances of the Managed Entries Plug-in.
The concept of a template entry is similar to the templates used in CoS, but there are some important differences. The managed entry template is slightly different than the type of template used for a class of service. For a class of service, the template contains a single attribute with a specific value that is fed into all of the entries which belong to that CoS. Any changes to the class of service are immediately reflected in the associated entries, because the CoS attributes in those entries are virtual attributes, not truly attributes set on the entry.
The template entry for the Managed Entries Plug-in, on the other hand, is not a central entry that supplies values to associated entries. It is a true template — it lays out what is in the entry. The template entry can contain both static attributes (ones with pre-defined values, similar to a CoS) and mapped attributes (attributes that pull their values or parts of values from the origin entry). The template is referenced when the managed entry is created and then any changes are applied to the managed entry only when the origin entry is changed and the template is evaluated again by the plug-in to apply those updates.
Templates, Managed Entries, and Origin Entries

Figure 6.3. Templates, Managed Entries, and Origin Entries

The template can provide a specific value for an attribute in the managed entry by using a static attribute in the template. The template can also use a value that is derived from some attribute in the origin entry, so the value may be different from entry to entry; that is a mapped attribute, because it references the attribute type in the origin entry, not a value.
A mapped value use a combination of token (dynamic values) and static values, but it can only use one token in a mapped attribute.
dn: cn=Posix User-Group Template,ou=Templates,dc=example,dc=com
objectclass: mepTemplateEntry
cn: Posix User-Group Template
mepRDNAttr: cn
mepStaticAttr: objectclass: posixGroup
mepMappedAttr: cn: $cn Group Entry
mepMappedAttr: gidNumber: $gidNumber
mepMappedAttr: memberUid: $uid
The mapped attributes in the template use tokens, prepended by a dollar sign ($), to pull in values from the origin entry and use it in the managed entry. (If a dollar sign is actually in the managed attribute value, then the dollar sign can be escaped by using two dollar signs in a row.)
A mapped attribute definition can be quoted with curly braces, such as Attr: ${cn}test. Quoting a token value is not required if the token name is not immediately followed by a character that is valid in an attribute name, such as a space or comma. For example, $cn test is acceptable in an attribute definition because a space character immediately follow the attribute name, but $cntest is not valid because the Managed Entries Plug-in attempts to look for an attribute named cntest in the origin entry. Using curly braces identifies the attribute token name.

Note

Make sure that the values given for static and mapped attributes comply with the required attribute syntax.

6.3.1.3. Entry Attributes Written by the Managed Entries Plug-in

Both the origin entry and the managed entry have special managed entries attributes which indicate that they are being managed by an instance of the Managed Entries Plug-in. For the origin entry, the plug-in adds links to associated managed entries.
dn: uid=jsmith,ou=people,dc=example,dc=com
objectclass: mepOriginEntry
objectclass: posixAccount
...
sn: Smith
mail: jsmith@example.com
mepManagedEntry: cn=jsmith Posix Group,ou=groups,dc=example,dc=com
On the managed entry, the plug-in adds attributes that point back to the origin entry, in addition to the attributes defined in the template.
dn: cn=jsmith Posix Group,ou=groups,dc=example,dc=com
objectclass: mepManagedEntry
objectclass: posixGroup
...
mepManagedBy: uid=jsmith,ou=people,dc=example,dc=com
Using special attributes to indicate managed and origin entries makes it easy to identify the related entries and to assess changes made by the Managed Entries Plug-in.

6.3.1.4. Managed Entries Plug-in and Directory Server Operations

The Managed Entries Plug-in has some impact on how the Directory Server carries out common operations, like add and delete operations.

Table 6.5. Managed Entries Plug-in and Directory Server Operations

Operation Effect by the Managed Entries Plug-in
Add With every add operation, the server checks to see if the new entry is within the scope of any Managed Entries Plug-in instance. If it meets the criteria for an origin entry, then a managed entry is created and managed entry-related attributes are added to both the origin and managed entry.
Modify
If an origin entry is modified, it triggers the plug-in to update the managed entry. Changing a template entry, however, does not update the managed entry automatically. Any changes to the template entry are not reflected in the managed entry until after the next time the origin entry is modified.
The mapped managed attributes within a managed entry cannot be modified manually, only by the Managed Entry Plug-in. Other attributes in the managed entry (including static attributes added by the Managed Entry Plug-in) can be modified manually.
Delete If an origin entry is deleted, then the Managed Entries Plug-in will also delete any managed entry associated with that entry. There are some limits on what entries can be deleted.
  • A template entry cannot be deleted if it is currently referenced by a plug-in instance definition.
  • A managed entry cannot be deleted except by the Managed Entries Plug-in.
Rename If an origin entry is renamed, then plug-in updates the corresponding managed entry. If the entry is moved out of the plug-in scope, then the managed entry is deleted, while if an entry is moved into the plug-in scope, it is treated like an add operation and a new managed entry is created. As with delete operations, there are limits on what entries can be renamed or moved.
  • A configuration definition entry cannot be moved out of the Managed Entries Plug-in container entry. If the entry is removed, that plug-in instance is inactivated.
  • If an entry is moved into the Managed Entries Plug-in container entry, then it is validated and treated as an active configuration definition.
  • A template entry cannot be renamed or moved if it is currently referenced by a plug-in instance definition.
  • A managed entry cannot be renamed or moved except by the Managed Entries Plug-in.
Replication The Managed Entries Plug-in operations are not initiated by replication updates. If an add or modify operation for an entry in the plug-in scope is replicated to another replica, that operation does not trigger the Managed Entries Plug-in instance on the replica to create or update an entry. The only way for updates for managed entries to be replicated is to replicate the final managed entry over to the replica.

6.3.2. Creating the Managed Entries Template Entry

The first entry to create is the template entry. The template entry must contain all of the configuration required for the generated, managed entry. This is done by setting setting the attribute-value assertions in static and mapped attributes in the template:
mepStaticAttr: attribute: specific_value
mepMappedAttr: attribute: $token_value
The static attributes set an explicit value; mapped attributes pull some value from the originating entry is used to supply the given attribute. The values of these attributes will be tokens in the form attribute: $attr. As long as the syntax of the expanded token of the attribute does not violate the required attribute syntax, then other terms and strings can be used in the attribute. For example:
mepMappedAttr: cn: Managed Group for $cn
There are some syntax rules that must be followed for the managed entries:
  • A mapped value use a combination of token (dynamic values) and static values, but it can only use one token per mapped attribute.
  • The mapped attributes in the template use tokens, prepended by a dollar sign ($), to pull in values from the origin entry and use it in the managed entry. (If a dollar sign is actually in the managed attribute value, then the dollar sign can be escaped by using two dollar signs in a row.)
  • A mapped attribute definition can be quoted with curly braces, such as Attr: ${cn}test. Quoting a token value is not required if the token name is not immediately followed by a character that is valid in an attribute name, such as a space or comma. For example, $cn test is acceptable in an attribute definition because a space character immediately follow the attribute name, but $cntest is not valid because the Managed Entries Plug-in attempts to look for an attribute named cntest in the origin entry. Using curly braces identifies the attribute token name.
  • Make sure that the values given for static and mapped attributes comply with the required attribute syntax.

Note

Make sure that the values given for static and mapped attributes comply with the required attribute syntax. For example, if one of the mapped attributes is gidNumber, then the mapped value should be an integer.

Table 6.6. Attributes for the Managed Entry Template

Attribute Description
mepTemplateEntry (object class) Identifies the entry as a template.
cn Gives the common name of the entry.
mepMappedAttr Contains an attribute-token pair that the plug-in uses to create an attribute in the managed entry with a value taken from the originating entry.
mepRDNAttr Specifies which attribute to use as the naming attribute in the managed entry. The attribute used as the RDN must be a mapped attribute for the configuration to be valid.
mepStaticAttr Contains an attribute-value pair that will be used, with that specified value, in the managed entry.
To create a template entry:
  1. Run ldapmodify to add the entry. This entry can be located anywhere in the directory tree.
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=Posix User Template,ou=templates,dc=example,dc=com
    cn: Posix User Template
    You can also use the Directory Server Console to create the entry, as described in Section 3.1.2, “Creating Directory Entries”.
  2. Give it the mepTemplateEntry object class to indicate that it is a template entry.
    objectClass: top
    objectclass: mepTemplateEntry
  3. Set the attributes for the entry; these are described in Table 6.6, “Attributes for the Managed Entry Template”. The RDN attribute (mepRDNAttr) is required. The attribute parameters are optional and the values depend on the type of entry that the plug-in will create. Make sure that whatever attribute you use for the naming attribute is also contained in the template entry as a mapped attribute.

    Note

    Attributes which will be the same for each managed entry — like the object class for the entries — should use the mepStaticAttr attribute to set the values manually.
    mepRDNAttr: cn
    mepStaticAttr: objectclass: posixGroup
    mepMappedAttr: cn: $cn Group Entry
    mepMappedAttr: gidNumber: $gidNumber
    mepMappedAttr: memberUid: $uid

6.3.3. Creating the Managed Entries Instance Definition

Once the template entry is created, then it is possible to create a definition entry that points to that template. The definition entry is an instance of the Managed Entries Plug-in.

Note

When the definition is created, the server checks to see if the specified template entry exists. If the template does not exist, then the server returns a warning that the definition configuration is invalid.
The definition entry must define the parameters to recognize the potential origin entry and the information to create the managed entry. The attributes available for the plug-in instance are listed in Table 6.7, “Attributes for the Managed Entries Definition Entry”.

Table 6.7. Attributes for the Managed Entries Definition Entry

Attribute Name Description
originFilter The search filter to use to search for and identify the entries within the subtree which require a managed entry. The syntax is the same as a regular search filter.
originScope The base subtree which contains the potential origin entries for the plug-in to monitor.
managedTemplate Identifies the template entry to use to create the managed entry. This entry can be located anywhere in the directory tree.
managedBase The subtree under which to create the managed entries.

Note

The Managed Entries Plug-in is enabled by default. If this plug-in is disabled, then re-enable it as described in Section 1.8.1, “Enabling Plug-ins in the Directory Server Console”.
To create an instance:
  1. Create the new plug-in instance below the cn=Managed Entries,cn=plugins,cn=config container entry.
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
    
    dn: cn=instance_name,cn=Managed Entries,cn=plugins,cn=config
  2. Set the scope and filter for the origin entry search, the location of the new managed entries, and the template entry to use. These required attributes are listed in Table 6.7, “Attributes for the Managed Entries Definition Entry”.
    objectClass: top
    objectClass: extensibleObject
    cn: Posix User-Group
    originScope: ou=people,dc=example,dc=com
    originFilter: objectclass=posixAccount
    managedBase: ou=groups,dc=example,dc=com
    managedTemplate: cn=Posix User-Group Template,ou=Templates,dc=example,dc=com
  3. Restart the Directory Server to load the modified new plug-in instance.
    service dirsrv restart instance_name

6.3.4. Putting Managed Entries Plug-in Configuration in a Replicated Database

As Section 6.3.1, “About Managed Entries” highlights, different instances of the Managed Entries Plug-in are created as children beneath the container plug-in entry in cn=plugins,cn=com. (This is common for plug-ins which allow multiple instances.) The drawback to this is that the configuration entries in cn=plugins,cn=com are not replicated, so the configuration has to be re-created on each Directory Server instance.
The Managed Entries Plug-in entry allows the nsslapd-pluginConfigArea attribute. This attribute to another container entry, in the main database area, which contains the plug-in instance entries. This container entry can be in a replicated database, which allows the plug-in configuration to be replicated.
  1. Create a container entry in a subtree that is replicated.
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x -D "cn=directory manager" -w secret -p 389 -h server.example.com -x
    
    dn: cn=managed entries container,ou=containers,dc=example,dc=com
    objectclass: top
    objectClass: extensibleObject
    objectClass: nsContainer
    cn: managed entries container
  2. Add the nsslapd-pluginConfigArea attribute to the Managed Entries Plug-in entry that points back to the container entry.
    [root@server ~]# ldapmodify -D "cn=directory manager" -W -x -D "cn=directory manager" -w secret -p 389 -h server.example.com -x
    
    dn: cn=Managed Entries,cn=plugins,cn=config
    changetype: modify
    add: nsslapd-pluginConfigArea
    nsslapd-pluginConfigArea: cn=managed entries container,ou=containers,dc=example,dc=com

6.4. Using Views

Virtual directory tree views, or views, create a virtual directory hierarchy, so it is easy to navigate entries, without having to make sure those entries physically exist in any particular place. The view uses information about the entries to place them in the view hierarchy, similarly to members of a filtered role or a dynamic group. Views superimpose a DIT hierarchy over a set of entries, and to client applications, views appear as ordinary container hierarchies.

6.4.1. About Views

Views create a directory tree similar to the regular hierarchy, such as using organizational unit entries for subtrees, but views entries have an additional object class (nsview) and a filter attribute (nsviewfilter) that set up a filter for the entries which belong in that view. Once the view container entry is added, all of the entries that match the view filter instantly populate the view. The target entries only appear to exist in the view; their true location never changes. For example, a view may be created as ou=Location Views, and a filter is set for l=Mountain View. Every entry, such as cn=Jane Smith,l=Mountain View,ou=People,dc=example,dc=com, is immediately listed under the ou=Location Views entry, but the real cn=Jane Smith entry remains in the ou=People,dc=example,dc=com subtree.
A Directory Tree with a Virtual DIT View hierarchy

Figure 6.4. A Directory Tree with a Virtual DIT View hierarchy

Virtual DIT views behave like normal DITs in that a subtree or a one-level search can be performed with the expected results being returned.

Note

There is a sample LDIF file with example views entries, Example-views.ldif, installed with Directory Server. This file is in the /usr/share/dirsrv/data directory on Red Hat Enterprise Linux 6 (64-bit).
The Directory Server Deployment Guide has more information on how to integrate views with the directory tree hierarchy.

6.4.2. Creating Views in the Console

  1. Select the Directory tab.
  2. In the left navigation tree, create an organizational unit suffix to hold the views. For instance, for views based on the locality (l) attribute, name this organizational unit Location Views. Creating sub suffixes is described in Section 2.1.1.2, “Creating a New Sub Suffix Using the Console”.
  3. Right-click ou=Location Views, and select New > Other.
  4. Select nsview from the New Object menu, and click OK.
  5. In the Property Editor window, click the Add Value button, and add the organization unit object class.
  6. Name the organization unit according to how to organize the views. For instance, ou=Sunnyvale. Make the ou attribute the naming attribute.
  7. Click the Add Attribute button, and add the nsviewfilter attribute.
  8. Create a filter that reflects the views, such as (l=Sunnyvale).
  9. Click the Change button in the lower right corner to change the naming attribute.
    Use the ou of the entry as the naming attribute instead of description.
  10. Click OK to close the attributes box, and click OK again to save the new view entry.
The new view is immediately populated with any entries matching the search filter, and any new entries added to directory are automatically included in the view.

6.4.3. Creating Views from the Command Line

  1. Use the ldapmodify utility to bind to the server and prepare it to add the new view entry to the configuration file.
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x
  2. Add the new views container entry, in this example, under the dc=example,dc=com root suffix. This entry must have the nsview object class and the nsViewFilter attribute. The nsViewFilter attribute sets the attribute-value which identifies entries that belong in the view.
    dn: ou=Example View,dc=example,dc=com
    changetype: add
    objectClass: top
    objectClass: organizationalUnit
    objectClass: nsview
    ou: Example View
    nsViewFilter: l=Mountain View
    description: Example View

6.4.4. Improving Views Performance

As Section 6.4.1, “About Views” describes, views are derived from search results based on a given filter. Part of the filter is the attribute defined in the nsViewFilter attribute; the rest of the filter is based on the entry hierarchy, looking for the entryid and parentid of the real entries included in the view.
(|(parentid=search_base_id)(entryid=search_base_id)
If any of the searched-for attributes — entryid, parentid, or the attribute set in nsViewFilter — are not indexed, then the views search becomes an unindexed search because the views operation searches the entire tree for matching entries.
To improve views performance, create equality indexes for entryid, parentid, and the attribute set in nsViewFilter.
Creating equality indexes is covered in Section 9.2, “Creating Standard Indexes”, and updating existing indexes to include new attributes is covered in Section 9.3, “Applying New Indexes to Existing Databases”.

Chapter 7. Configuring Secure Connections

By default, clients and users connect to the Red Hat Directory Server over a standard connection. Standard connections do not use any encryption, so information is sent back and forth between the server and client in the clear.
Directory Server supports SSL/TLS connections, Start TLS connection, and SASL authentication, which provide layers of encryption and security that protect directory data from being read even if it is intercepted.

7.1. Requiring Secure Connections

The Directory Server has two different ways of encrypting data: SSL/TLS (either through an initial SSL connection or using Start TLS to establish encryption on a previously unencrypted connection) and SASL. If the server is configured to use it, any client can connect to the server using either encryption method to protect data.
For additional security, the Directory Server can be configured to require a certain level of encryption before it allows a connection. The Directory Server can define and require a specific security strength factor for any connection. The SSF sets a minimum encryption level, defined by its key strength, for any connection or operation.
To require a minimum SSF for any and all directory operations, set the nsslapd-minssf configuration attribute. When enforcing a minimum SSF, the Directory Server looks at each available encryption type for an operation — SSL/TLS or SASL — and determines which has the higher SSF value and then compares the higher value to the minimum SSF. (It is possible for both SASL authentication and SSL/TLS to be configured for some server-to-server connections, such as replication.)

Note

Alternatively, use the nsslapd-minssf-exclude-rootdse configuration attribute. This sets a minimum SSF setting for all connections to the Directory Server except for queries against the root DSE. A client may need to obtain information about the server configuration, like its default naming context, before initiating an operation. The nsslapd-minssf-exclude-rootdse attribute allows the client to get that information without having to establish a secure connection first.
The SSF for a connection is evaluated when the first operation is initiated on a connection. This allows Start TLS and SASL binds to succeed, even though those two connections initially open a regular connection. After the TLS or SASL session is opened, then the SSF is evaluated. Any connection which does not meet the SSF requirements is closed with an LDAP unwilling to perform error.
Setting a minimum SSF can be used to effectively disable all standard or insecure connections to a directory.
The default nsslapd-minssf attribute value is 0, which means there is no minimum SSF for server connections. The value can be set to any reasonable positive integer. The value represents the required key strength for any secure connection.
  1. Add the nsslapd-minssf attribute to the cn=config entry:
    [root@server ~]# ldapmodify -D "cn=directory manager" -W -x
    
    dn: cn=config
    changetype: modify
    replace: nsslapd-minssf
    nsslapd-minssf: 128
  2. Restart the server.
    service dirsrv restart

Note

An ACI can be set to require an SSF for a specific type of operation, as in Section 13.9.10, “Setting an ACI to Require a Certain Security Strength Factor for Some Operations”.
Secure connections can be required for bind operations by turning on the nsslapd-require-secure-binds attribute, as in Section 14.8.1, “Requiring Secure Binds”.

7.2. Disabling SSL and Requiring TLS

TLS is enabled in the nsTLS1 parameter, which is enabled by default.
By default, SSLv3[2] is also enabled. If both TLS and SSLv3 are enabled, then a client can use either protocol to connect to the Directory Server. In some environments, SSLv3 should be disabled so that only TLSv1 connections are allowed.
In the Directory Server configuration, SSLv3 is enabled in the nsSSL3 parameter. There are two ways to change the value of this setting and disable SSLv3:
  • Change the nsSSL3 attribute to off. The SSLv3 attribute must be explicitly set to off; if the parameter is missing or has any other value, SSLv3 is implicitly enabled.
    For example:
    [root@server ~]# ldapmodify -D "cn=directory manager" -W -x -D "cn=directory manager" -w secret -p 636 -h server.example.com -x
    
    dn: cn=encryption,cn=config
    changetype: modify
    replace: nsSSL3
    nsSSL3: off
  • Use modutil to enable FIPS mode, which automatically disables SSLv3. If FIPS mode is enabled, it overrides whatever the nsSSL3 attribute is in order to disable SSLv3. For example:
    modutil -dbdir /etc/dirsrv/slapd-instance_name -chkfips true
    FIPS mode enabled.
    Enabling FIPS mode may have other security and configuration implications, however, so it may be easier to disable the SSLv3 parameter.

7.3. Managing Certificates Used by the Directory Server

7.3.1. Obtaining and Installing Server Certificates

Before the Directory Server can be set to run in TLS/SSL, server and CA certificates must be properly configured in the Directory Server. If a server certificate has already been generated for the Directory Server instance and the issuing certificate authority (CA) is already trusted by the Directory Server, begin setting up TLS/SSL as described in Section 7.4, “Setting up TLS/SSL”.
Obtaining and installing certificates consists of the following steps:
  1. Generate a certificate request.
  2. Send the certificate request to a certificate authority.
  3. Install the server certificate.
  4. Set the Directory Server to trust the certificate authority.
  5. Confirm that the certificates are installed.
Two wizards automate the process of creating a certificate database and of installing the key-pair. The Certificate Request Wizard in the Directory Server Console can generate a certificate request and send it to a certificate authority. The Certificate Install Wizard in the Directory Server Console can then install the server certificate and the CA certificate.

7.3.1.1. Generating a Certificate Request

Generate a certificate request, and send it to a CA. The Directory Server Console has a tool, the Certificate Request Wizard, which generates a valid certificate request to submit to any certificate authority (CA).
  1. Select the Tasks tab, and click Manage Certificates.
  2. Select the Server Certs tab, and click the Request button.
  3. Enter the Requester Information in the blank text fields, then click Next.
    • Server Name. Enter the fully qualified host name of the Directory Server as it is used in DNS and reverse DNS lookups; for example, dir.example.com. The server name is critical for client-side validation to work, which prevents man-in-the-middle attacks.
    • Organization. Enter the legal name of the company or institution. Most CAs require this information to be verified with legal documents such as a copy of a business license.
    • Organizational Unit. Optional. Enter a descriptive name for the organization within the company.
    • Locality. Optional. Enter the company's city name.
    • State or Province. Enter the full name of the company's state or province (no abbreviations).
    • Country. Select the two-character abbreviation for the country's name (ISO format). The country code for the United States is US.
  4. If an external security device is to be used to store the Directory Server certificates, the device is plugged in, and the module has been installed as described in Section 7.8, “Using Hardware Security Modules”, then the module is available in the Active Encryption Token menu. The default is to use the software databases with Directory Server, internal (software).
  5. Enter the password that will be used to protect the private key, and click Next.
    The Next button is grayed out until a password is supplied.
  6. The Request Submission dialog box provides two ways to submit a request: directly to the CA (if there is one internally) or manually. To submit the request manually, select Copy to Clipboard or Save to File to save the certificate request which will be submitted to the CA.
  7. Click Done to dismiss the Certificate Request Wizard.
After generating the certificate request, send it to the CA.

7.3.1.2. Sending a Certificate Request

After the certificate request is generated, send it to a certificate authority (CA); the CA will generate return a server certificate.
  1. Most certificate requests are emailed to the CA, so open a new message.
  2. Copy the certificate request information from the clipboard or the saved file into the body of the message.
    -----BEGIN NEW CERTIFICATE REQUEST-----
    MIIBrjCCARcCAQAwbjELMAkGA1UEBhMCVXMxEzARBgNVBAgTCkNBTElGT1J
    OSUExLDAqBgVBAoTI25ldHNjYXBlIGNvbW11bmljYXRpb25zIGNvcnBvcmF
    0aW9uMRwwGgYDVQQDExNtZWxsb24ubmV0c2NhcGUuY29tMIGfMA0GCSqGSI
    b3DQEBAQUAA4GNADCBiQKBgQCwAbskGh6SKYOgHy+UCSLnm3ok3X3u83Us7
    ug0EfgSLR0f+K41eNqqRftGR83emqPLDOf0ZLTLjVGJaH4Jn4l1gG+JDf/n
    /zMyahxtV7+mT8GOFFigFfuxaxMjr2j7IvELlxQ4IfZgWwqCm4qQecv3G+N
    9YdbjveMVXW0v4XwIDAQABoAAwDQYK
    ------END NEW CERTIFICATE REQUEST-----
  3. Send the email message to the CA.
After emailing the certificate request, wait for the CA to respond with the server certificate. Response time for requests varies. For example, if the CA is internal to the company, it may only take a day or two to respond to the request. If the selected CA is a third-party, it could take several weeks to respond to the request.
After receiving the certificate, install it in the Directory Server's certificate database. When the CA sends a response, be sure to save the information in a text file. The certificate must be available to install in the Directory Server.
Also, keep a backup of the certificate data in a safe location. If the system ever loses the certificate data, the certificate can be reinstalled using the backup file.

7.3.1.3. Installing the Certificate

Note

If an existing certificate has the same name as the new certificate you are attempting to install, you cannot use the Directory Server Console to install the certificate. It fails with the error Internal error: Fail to install certificate -8169.
You can use certutil to install the certificate.
certutil -A -n nickname -t trust-settings -d certDB -f /path/to/certificate_file
For more information on using certutil to manage certificates, see Section 7.6, “Using certutil”.
  1. Select the Tasks tab, and click Manage Certificates.
  2. Select the Server Certs tab, and click Install.
  3. Give the certificate location or paste the certificate text in the text box, then click Next.
    • In this file. Enter the absolute path to the certificate in this field.
    • In the following encoded text block. Copy the text from the CA's email or from the created text file, and paste it in this field.
  4. Check that the certificate information displayed is correct, and click Next.
  5. Give a name to the certificate, and click Next.
  6. Provide the password that protects the private key. This password is the same as the one provided in step 5 in Section 7.3.1.1, “Generating a Certificate Request”.
After installing the server certificate, configure the Directory Server to trust the CA which issued the server's certificate, Section 7.3.2, “Trusting the Certificate Authority”.

7.3.2. Trusting the Certificate Authority

Configuring the Directory Server to trust the certificate authority consists of obtaining the CA's certificate and installing it into the server's certificate database. This process differs depending on the certificate authority. Some commercial CAs provide a web site that allow users to automatically download the certificate. Others will email it back to users.
After receiving the CA certificate, use the Certificate Install Wizard to configure the Directory Server to trust the certificate authority.
  1. Select the Tasks tab, and click Manage Certificates.
  2. Go to the CA Certs tab, and click Install.
  3. If the CA's certificate is saved to a file, enter the path in the field provided. Alternatively, copy and paste the certificate, including the headers, into the text box. Click Next.
  4. Check that the certificate information that opens is correct, and click Next.
  5. Name the certificate, and click Next.
  6. Select the purpose of trusting this certificate authority; it is possible to select both options.
    • Accepting connections from clients (Client Authentication). The server checks that the client's certificate has been issued by a trusted certificate authority.
    • Accepting connections to other servers (Server Authentication). This server checks that the directory to which it is making a connection (for replication updates, for example) has a certificate that has been issued by a trusted certificate authority.
Once both the server and CA certificates are installed, it is possible to configure the Directory Server to run in TLS/SSL. However, Red Hat recommends verifying that the certificates have been installed correctly.

7.3.3. Renewing Certificates

As with any issued identification — drivers' licenses, student IDs — certificates are valid for a predefined period and then expire and must be renewed. To renew a certificate, regenerate a certificate request, using the same information that was used to create the original, submit the request to a CA, and re-install the renewed certificate.

Note

When renewing a certificate using the Certificate Wizard, the text on the introduction screen does not clearly indicate that the process is renewal and not requesting a new certificate. Also, the requester information is not filled in automatically.
  1. Open the Directory Server Console.
  2. In the Tasks tab, click the Manage Certificates button.
  3. Click the Server Certs tab.
  4. Select the certificate to renew from the list of certificates, and click the Renew button.
  5. Go through the request wizard, using the same information used for requesting the original certificate.
  6. Submit the request to a certificate authority.
  7. Once the certificate is issued, reinstall it in the Directory Server.
    1. In the Tasks tab, click the Manage Certificates button.
    2. Click the Server Certs tab.
    3. Click the Install button.
    4. Paste in the renewed certificate, and continue through the installation wizard.

7.3.4. Changing the CA Trust Options

It is sometimes necessary to reject certificates issued by a generally trusted CA. The trust settings on CA certificates installed in the Directory Server can be untrusted, trusted, or change the operations for which it is trusted.
  1. In the Tasks tab, click the Manage Certificates button.
  2. Click the CA Certs tab.
  3. Select the CA certificate to edit.
  4. Click the Edit Trust button.
  5. Set the CA trust options.
    • Accepting connections from clients (Client Authentication). This option sets whether to accept client, or user, certificates issued by the CA.
    • Making connections to other servers (Server Authentication). This option sets whether to accept server certificates issued by the CA.
    • Click OK.

7.3.5. Changing Security Device Passwords

Periodically change the settings for the security databases or devices.
  1. In the Tasks tab, click the Manage Certificates button.
  2. In the top of the window, choose a security device from the drop-down list.
  3. Click the Password button.
  4. In the Change Security Device Password dialog box, enter the old password, and then enter and confirm the new password.
  5. Click OK.

7.3.6. Adding Certificate Revocation Lists

Certificate revocation lists (CRLs) allow CAs to specify certificates that client or server users should no longer trust. If data in a certificate changes, a CA can revoke the certificate and list it in a CRL. CRLs are produced and periodically updated by a CA, so updated CRLs can be added to the Directory Server.
  1. Obtain the CRL from the CA; these can usually be downloaded from the CA's website.
  2. In the Tasks tab, click the Manage Certificates button.
  3. Select the Revoked Certs tab.
  4. To add a CRL, click Add at the bottom of the window, and enter the full path to the CRL file.
  5. Click OK.

7.3.7. Managing Certificates Used by the Directory Server Console

The certificates and keys used by the server are stored in NSS security databases in the /etc/dirsrv/slapd-instance_name directory. The Directory Server Console itself also uses certificates and keys for SSL/TLS connections; these certificates are stored in a separate database in the user's home directory. If the Directory Server Console is used to connect to multiple instances of Directory Server over SSL, then it is necessary to trust every CA which issued the certificates for every Directory Server instance.
When SSL/TLS is enabled for the Directory Server Console (Section 7.4.3, “Enabling TLS/SSL in the Directory Server, Admin Server, and Console”), the Directory Server Console must have a copy of the issuing CA certificate for it to trust the server's SSL client certificates. Otherwise, the Console will return errors about not trusting the CA which issued the certificate.

Note

Only the CA certificates for the CA which issued the server's SSL certificate is required. The Directory Server Console does not require its own SSL client certificate.
The Console's security databases are managed directly using certutil. The certutil tool is described in more detail in Section 7.6, “Using certutil” and in the NSS tool manpages.
To list the certificates in the security database:
certutil -d $HOME/.redhat-idm-console -L
To add a CA certificate to the database:
certutil -d $HOME/.redhat-idm-console -A -t CT,, -a -i /path/to/cacert.asc

Note

If you are running the Directory Server Console on Windows,
  • the security database is located in the C:\Documents and Settings\user_name\.389-console\ directory.
  • change to the C:\Program Files\Red Hat Identity Management Console\ directory to run the certutil.exe command.

7.4. Setting up TLS/SSL

To provide secure communications over the network, Red Hat Directory Server includes the LDAPS communications protocol. LDAPS is the standard LDAP protocol, running over Transport Layer Security (TLS, formerly Secure Sockets Layer or SSL). Directory Server also allows spontaneous secure connections over otherwise-insecure LDAP ports, using the Start TLS LDAP extended operation.

7.4.1. TLS/SSL in Directory Server

The Directory Server supports TLS/SSL to secure communications between LDAP clients and the Directory Server, between Directory Servers that are bound by a replication agreement, or between a database link and a remote database. Directory Server can use TLS/SSL with simple authentication (bind DN and password) or with certificate-based authentication.
Directory Server's cryptographic services are provided by Mozilla Network Security Services (NSS), a library of TLS/SSL and base cryptographic functions. NSS includes a software-based cryptographic token which is FIPS 140-2 certified.
Using TLS/SSL with simple authentication ensures confidentiality and data integrity. There are two major benefits to using a certificate — smart card, token, or software-based — to authenticate to the Directory Server instead of a bind DN and password:
  • Improved efficiency. When using applications that prompt once for the certificate database password and then use that certificate for all subsequent bind or authentication operations, it is more efficient than continuously providing a bind DN and password.
  • Improved security. The use of certificate-based authentication is more secure than non-certificate bind operations because certificate-based authentication uses public-key cryptography. Bind credentials cannot be intercepted across the network. If the certificate or device is lost, it is useless without the PIN, so it is immune from third-party interference like phishing attacks.
The Directory Server is capable of simultaneous TLS/SSL and non-SSL communications. This means that you do not have to choose between TLS/SSL or non-SSL communications for the Directory Server; both can be used at the same time. Directory Server can also utilize the Start TLS extended operation to allow TLS/SSL secure communication over a regular (insecure) LDAP port.
There are four steps to enable TLS/SSL:
  1. Obtain and install a certificate for the Directory Server, and configure the Directory Server to trust the certification authority's (CA's) certificate.
  2. Turn on TLS/SSL in the directory.
  3. Configure the Admin Server connect to a TLS-enabled Directory Server.
  4. Optionally, ensure that each user of the Directory Server obtains and installs a personal certificate for all clients that will authenticate with TLS/SSL.
Most of the time, the server should run with TLS/SSL enabled. If TLS/SSL is temporarily disabled, re-enable it before processing transactions that require confidentiality, authentication, or data integrity.
Before TLS/SSL can be activated, first create a certificate database, obtain and install a server certificate, and trust the CA's certificate, as described in Section 7.3.1, “Obtaining and Installing Server Certificates”.
With TLS/SSL enabled, when the server restarts, it prompts for the PIN or password to unlock the key database. This is the same password used when the server certificate and key were imported into the database. Restarting the Directory Server without the password prompt is possible by using use a hardware crypto device or creating a PIN file (Section 7.4.4, “Creating a Password File for the Directory Server”).

Note

On TLS-enabled servers, be sure to check the file permissions on certificate database files, key database files, and PIN files to protect the sensitive information they contain. Because the server does not enforce read-only permissions on these files, check the file modes to protect the sensitive information contained in these files.
The files must be owned by the Directory Server user, such as the default nobody. If you set a different account during the installation, like Red Hat recommends, use this user and group for a better security instead. The key and cert databases should be owned by the Directory Server user and should typically have read/write access for the owner with no access allowed to any other user (mode 0600). The PIN file should also be owned by the Directory Server user and set to read-only by this user, with no access to anyone other user (mode 0400).

Warning

The Directory Server must already be configured to run in SSL (Section 7.4.2, “Enabling TLS/SSL Only in the Directory Server”) and the server must already have been restarted before the Directory Server Console can be configured to use SSL. Configuring SSL/TLS for the server requires a server restart to load the new configuration, including the new secure port assignment. However, enabling SSL/TLS for the Console takes effect immediately. Therefore, if the Console has SSL/TLS enabled before the server is running in SSL/TLS, then the Console loses the connection to the server and cannot reconnect.
To disable SSL/TLS in the Directory Server Console, use ldapmodify to edit the nsServerSecurity attribute:
nsServerSecurity: off

7.4.2. Enabling TLS/SSL Only in the Directory Server

  1. Obtain and install CA and server certificates.
  2. Set the secure port for the server to use for TLS/SSL communications. In the Configuration area, select the Settings tab, and enter the value in the Encrypted Port field.
    The encrypted port number must not be the same port number used for normal LDAP communications. By default, the standard port number is 389, and the secure port is 636.
  3. Select the Configuration tab, and then select the top entry in the navigation tree in the left pane. Select the Encryption tab in the right pane.
  4. Select the Enable SSL for this Server check box.
  5. Check the Use this Cipher Family check box.
  6. Select the certificate to use from the drop-down menu.
  7. Click Cipher Settings.
    By default, ALL in the TLS tab is selected. When ALL is set, the server selects safe ciphers internally.
  8. Set the preferences for client authentication.
    • Do not allow client authentication. With this option, the server ignores the client's certificate. This does not mean that the bind will fail.
    • Allow client authentication. This is the default setting. With this option, authentication is performed on the client's request. For more information about certificate-based authentication, see Section 7.10, “Using Client (Certificate-Based) Authentication”.