Red Hat Training

A Red Hat training course is available for Red Hat Directory Server

Administration Guide

Red Hat Directory Server 10

Updated for Directory Server 10.6

Marc Muehlfeld

Red Hat Customer Content Services

mmuehlfeld@redhat.com

Petr Bokoč

Red Hat Customer Content Services

Tomáš Čapek

Red Hat Customer Content Services

Petr Kovář

Red Hat Customer Content Services

Ella Deon Ballard

Red Hat Customer Content Services

Legal Notice

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 November 30, 2020, the support for Red Hat Directory Server 10 has ended. For details, see “Red Hat Directory Server Life Cycle policy”. Red Hat recommends users of Directory Server 10 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!

Chapter 1. Basic Red Hat Directory Server Settings

The Red Hat Directory Server 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). The server manages the directory databases and responds to client requests.

Directory Server 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 management of users, groups, and other LDAP data. The Console is used for all aspects of the server management, including backups; security, replication, or databases configuration; server monitoring; and viewing statistics.
The Administration Server is the management agent which administers Directory Server instances. It communicates with the Directory Server Console and performs operations on the Directory Server instances. It also provides a simple HTML interface and online help pages.

You can administer Directory Server by using command-line utilities, but it is also possible to use the Directory Server Console.

1.1. System Requirements

See the corresponding section in the Red Hat Directory Server 10 Release Notes.

1.2. File Locations

See the corresponding section in the Red Hat Directory Server Configuration, Command, and File Reference.

1.3. Starting the Directory Server Management Console

The Management Console provides a graphical user interface that enables you to perform administrative tasks, such as:

Managing Directory Server instances
Managing the Administration Server
Managing users and groups

Note

The Management Console uses Java. For details about the supported Java runtime environments and versions, see the Red Hat Directory Server Release Notes.

To open the Management Console, enter:

# redhat-idm-console

For supported command-line options, see the corresponding section in the Red Hat Directory Server Configuration, Command, and File Reference.

1.3.1. Opening the Directory Server Console

Start the Directory Server Management Console:
```
# redhat-idm-console
```
Log in as the cn=Directory Manager user:
On the Servers and Applications tab, navigate to administration_domain_name → host_name → Server Group → Directory Server (instance_name), and click Open.

1.3.2. Opening the Administration Server Console

Start the Directory Server Management Console:
```
# redhat-idm-console
```
Log in as the cn=Directory Manager user:
On the Servers and Applications tab, navigate to administration_domain_name → host_name → Server Group → Administration Server, and click Open.

1.4. Starting and Stopping a Directory Server Instance

1.4.1. Starting and Stopping a Directory Server Instance Using the Command Line

Use the systemctl utility to start, stop, or restart an instance:

To start an instance:
```
# systemctl start dirsrv@instance_name
```
To stop an instance:
```
# systemctl stop dirsrv@instance_name
```

To restart an instance:

# systemctl restart dirsrv@instance_name

Optionally, you can enable Directory Server instances to automatically start when the system boots:

for a single instance:
```
# systemctl enable dirsrv@instance_name
```
for all instances on a server:
```
# systemctl enable dirsrv.target
```

For further details, see the Managing System Services section in the Red Hat System Administrator's Guide.

1.4.2. Starting and Stopping a Directory Server Instance Using the Console

Besides the command line, you can use the Directory Server Console to start, stop, or restart instances.

Important

If you run SELinux in enforcing mode, you cannot use the Console to start or stop an instance. To work around the problem, use the command line to manage the services. See Section 1.4, “Starting and Stopping a Directory Server Instance”.

Important

If you enabled TLS encryption for an instance, Directory Server prompts for the TLS certificate password when the instance starts. The Directory Server Console does not support displaying this password prompt in the GUI. To work around the problem:

use the command line to manage the service. See Section 1.4.1, “Starting and Stopping a Directory Server Instance Using the Command Line”.
create a password file. See Section 9.4.1.5, “Creating a Password File for Directory Server”.

To start, stop, or restart a Directory Server instance:

Start the Directory Server Console and log in using the cn=Directory Manager user name.
For details, see Section E.2.2, “Opening the Administration Server Console”.
On the Servers and Applications tab, navigate to administration_domain_name → host_name → Server Group → Directory Server (instance_name), and click Open.
On the Tasks tab, click the task you want to execute:
Click Yes to confirm.

After the task finished, the console displays a message if the operation was successful or failed.

1.5. Starting and Stopping the Directory Server Administration Server Service

The Administration Server provides the Directory Server Console — a GUI to manage Directory Server.

1.5.1. Starting and Stopping the Administration Server Service Using the Command Line

Use the systemctl utility to start, stop, or restart the Administration Server service:

To start the service:
```
# systemctl start dirsrv-admin
```
To stop the service:
```
# systemctl stop dirsrv-admin
```
To restart the service:
```
# systemctl restart dirsrv-admin
```

Optionally, enable the Administration Server to automatically start when the system boots:

# systemctl enable dirsrv-admin

For further details, see the Managing System Services section in the Red Hat System Administrator's Guide.

1.5.2. Restarting and Stopping the Administration Server Service Using the Console

To restart or stop the Administration Server service:

Start the Directory Server Console and log in using the cn=Directory Manager user name.
For details, see Section E.2.2, “Opening the Administration Server Console”.
On the Servers and Applications tab, navigate to administration_domain_name → host_name → Server Group → Administration Server, and click Open.
On the Tasks tab, click the task you want to execute:
Click Yes to confirm.

After the task finished, the console displays a message if the operation was successful or failed.

1.6. Enabling LDAPI

Inter-process communication (IPC) is a way for separate processes on a Unix machine or a network to communicate directly with each other. LDAPI allows LDAP connections to run over IPC connections, meaning that LDAP operations can run over Unix sockets. These connections are much faster and more secure than regular LDAP connections.

LDAPI is enabled through two configuration attributes:

nsslapd-ldapilisten to enable LDAPI for Directory Server
nsslapd-ldapifilepath to point to the Unix socket file

To enable LDAPI:

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

Restart the server to apply the new configuration.
```
# systemctl restart dirsrv@instance
```

1.7. Changing Directory Server Port Numbers

The standard and secure LDAP port numbers used by Directory Server can be changed through the Directory Server Console or by changing the value of the nsslapd-port or nsslapd-secureport attribute under the cn=config entry in the dse.ldif.

Note

Modifying the standard or secure port numbers for a Configuration Directory Server, which maintains the o=NetscapeRoot subtree, should be done through the Directory Server Console.

1.7.1. Changing Standard Port Numbers

In the Directory Server Console, select the Configuration tab, and then select the top entry in the navigation tree in the left pane.
Select the Settings tab in the right pane.
Change the port numbers. The port number for the server to use for non-TLS communications in the Port field, with a default value of 389.
Click Save.
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.
Then a dialog appears, reading that the changes will not take effect until the server is restarted. Click OK.
Note
Do not restart the Directory Server at this point. If you do, you will not be able to make the necessary changes to the Administration Server through the Console.
Open the Administration Server Console.
In the Configuration tab, select the Configuration DS tab.
In the LDAP Port field, type in the new LDAP port number for your Directory Server instance.
Change the SELinux labels for the Directory Server ports so that the new port number is used in the Directory Server policies. For example:
```
# 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.
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.
Open the Configuration DS tab of the Administration Server Console and select Save.
A dialog will appear, reading The Directory Server setting has been modified. You must shutdown and restart your Administration Server and all the servers in the Server Group for the changes to take effect. Click OK.
In the Tasks tab of the Administration Server Console, click Restart Admin Server. A dialog opens reading that the Administration Server has been successfully restarted. Click Close.
Note
You must close and reopen the Console before you can do anything else in the Console. Refresh may not update the Console, and, if you try to do anything, you will get a warning that reads Unable to contact LDAP server.

1.7.2. Changing the LDAPS 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 Administration Server configuration.
If there are other Directory Server instances that point to the configuration or user directory, update those servers to point to the new port number.

To modify the LDAPS port:

Make sure that the CA certificate used to issue the Directory Server instance's certificate is in the Administration Server certificate database. Importing CA certificates for the Administration Server is the same as the Directory Server process described in Section 9.3.3, “Installing a CA Certificate”.
The secure port can be configured using the Directory Server Console, much like the process in Section 1.7.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:
```
# ldapmodify -x -h server.example.com -p 1389 -D "cn=Directory Manager" -W
dn: cn=config
replace: nsslapd-securePort
nsslapd-securePort: 1636
```

Edit the corresponding port configuration for the Directory Server instance in th Administration Server configuration (o=netscaperoot).

First, search for the current configuration:

# 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:

# ldapmodify -x -h config-ds.example.com -p 389 -D "cn=Directory Manager" -W

dn: cn=slapd-ID,cn=389 Directory Server,cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot
replace: nsSecureServerPort
nsSecureServerPort: 1636

Start the Directory Server Console for the instance and confirm that the new LDAPS port number is listed in the Configuration tab.
Optionally, select the Use SSL in Console check box.
Change the SELinux labels for the Directory Server ports so that the new port number is used in the Directory Server policies. For example:
```
# 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.
Restart the Directory Server instance.

1.8. Managing Directory Server Instances

1.8.1. Creating a New Directory Server Instance

For details, see the corresponding sections in the Red Hat Directory Server Installation Guide:

1.8.2. Removing a Directory Server Instance

1.8.2.1. Removing a Directory Server Instance Using the Command Line

It is possible to remove a single instance of Directory Server without uninstalling all other instances, removing an Administration Server instance, or removing the packages.

# remove-ds.pl -i slapd-instance_name -a

The remove-ds.pl script removes any related files and directories if the -a (all) option is specified. But the Directory Server instance is not unregistered from the Configuration Directory Server.

By default, the key and cert files are left in the instance configuration directory, and the configuration directory is renamed slapd-instance-name.removed. Using the -a option (as shown) removes the security databases, as well.

Note

If there is a problem with the Directory Server, like the installation failed or the server cannot be restarted, then running remove-ds.pl script fails. In this case, try the -f option to force the removal process.

1.8.2.1.1. Removing a Directory Server Instance and Administration Server

It is possible to remove both the Directory Server and the Administration Server (if configured on the same system).

The -y option is required for the script to perform the removal operation. Otherwise, the remove-ds-admin.pl script performs a dry-run but does not remove any servers.

The -a option is not required, but it is recommended if a Directory Server or Administration Server instance may be re-configured on the system later. By default, all of the security databases are preserved by the removal script. The -a option removes the security databases, as well.

Note

The Directory Server instance must be running for the script to bind to the server.

Note

If there is a problem with the Directory Server, like the installation failed or the server cannot be restarted, then running remove-ds-admin.pl script fails. In this case, try the -f option to force the removal process.

1.8.3. Removing a Directory Server Instance Using the Console

Open the Directory Server Console. For details, see Section 1.3.1, “Opening the Directory Server Console”.
Right-click the server instance, and select Remove Server.
Click Yes to confirm.

1.9. 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 all are 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.

For further details, see:

Section 1.9, “Using Directory Server Plug-ins”
The Plug-in Implemented Server Functionality Reference section in the Red Hat Directory Server Configuration, Command, and File Reference
Red Hat Directory Server Plug-in Guide

1.9.1. Enabling Plug-ins Dynamically

Directory Server supports dynamic plug-ins that can be enabled without restarting the Directory Server. Allowing for dynamically enabled plug-ins makes server administration significantly easier. By using dynamic plug-ins, you can avoid restarting the server multiple times to install and configure the plug-ins. This makes deploying software applications for the Directory Server much faster.

Each plug-in can be enabled or disabled by switching the value of the nsslapd-pluginEnabled attribute. For example:

# ldapmodify -x -D 'cn=Directory Manager' -W
dn: cn=Plug-in_name,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginEnabled
nsslapd-pluginEnabled: on

Restarting the Directory Server when plug-ins are reconfigured is not required if you specify the nsslapd-dynamic-plugins switch under the cn=config entry. To enable the dynamic plug-in feature, set the nsslapd-dynamic-plugins attribute to on:

dn: cn=config
nsslapd-dynamic-plugins: on

To disable the dynamic plug-in feature, set the nsslapd-dynamic-plugins attribute to off:

dn: cn=config
nsslapd-dynamic-plugins: off

By default, nsslapd-dynamic-plugins is set to off.

1.9.2. Enabling Plug-ins

1.9.2.1. 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.9.2.2. Enabling Plug-ins in the Directory Server Console

To enable and disable plug-ins using the Directory Server Console:

In the Directory Server Console, select the Configuration tab.
Double-click the Plugins folder in the navigation tree.
Select the plug-in from the Plugins list.
To disable the plug-in, clear the Enabled check box. To enable the plug-in, check this check box.
Click Save.
Restart the Directory Server.
```
# systemctl restart dirsrv@instance
```

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.9.3. Configuring Plug-ins

In Directory Server 9 and earlier, you configured plug-ins using the nsslapd-pluginarg* attributes. Directory Server 10 added support for specific configuration attributes for certain plug-ins.

Important

If both the plug-in-specific configuration attributes and the deprecated nsslapd-pluginarg* attributes are set in a plug-in's configuration, Directory Server only uses settings in plug-in-specific attributes.

The following two examples use the same settings for the Referential Integrity plug-in but using the different configuration options:

Example 1.1. Plug-in Configuration using Configuration Attributes

referint-update-delay: 0
referint-logfile: /var/log/dirsrv/slapd-localhost/referint
referint-logchanges: 0
referint-membership-attr: member
referint-membership-attr: uniquemember
referint-membership-attr: owner
referint-membership-attr: seeAlso

Note

Red Hat recommends using only the configuration plug-in-specific attributes. For plug-in-specific attributes, see the corresponding section in the Red Hat Directory Server Configuration, Command, and File Reference.

Example 1.2. Plug-in Configuration using Plug-in Argument Attributes (Deprecated)

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

1.9.3.1. Configuring Plug-ins using the Command Line

To use the ldapmodify utility to configure settings of a plug-in:

Identify the distinguished name (DN) of the plug-in's configuration. For details, see the corresponding section in the Red Hat Directory Server Configuration, Command, and File Reference.

Set the new value. For example, to set the update delay of the Referential Integrity plug-in to 0:

# 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: referint-update-delay
referint-update-delay: 0

Restart the Directory Server instance:

# systemctl restart dirsrv@instance_name

1.9.3.2. Configuring Plug-ins using the Console

To use the Directory Server Console to configure settings of a plug-in:

Start the Directory Server Console and log in using the cn=Directory Manager user name.
For details, see Section E.2.2, “Opening the Administration Server Console”.
On the Servers and Applications tab, navigate to administration_domain_name → host_name → Server Group → Directory Server (instance_name), and click Open.
Navigate to Plug-ins and select the plug-in to configure.
Click the Advanced button in the right panel.
Note
Red Hat recommends to configure the plug-in using the Property Editor, which uses the plug-in-specific attributes.
Set the plug-in-specific attributes.
Click OK to close the Property Editor.
Restart Directory Server. For details, see Section 1.5.2, “Restarting and Stopping the Administration Server Service Using the Console”.

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

Important

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

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

1.10. Server Configuration Attributes

Directory Server stores the configuration maintained in the cn=config entry in the /etc/dirsrv/slapd-instance_name/dse.ldif file. If you set up a new instance, Directory Server only stores configuration attributes that have been modified in this file. Attributes that are not listed, use their default value.

This enables you to:

Identify all configuration parameters set in this instance by displaying the /etc/dirsrv/slapd-instance_name/dse.ldif file.
Restore a default value by deleting the parameter.
If you delete a configuration parameter, the parameter is no longer listed in the /etc/dirsrv/slapd-instance_name/dse.ldif file. However, the parameter and its default value is displayed when you search the parameter in the cn=config entry using the LDAP protocol.
Note that you cannot delete the parameters listed in Table 1.1, “Configuration Attributes That Cannot Be Deleted” to reset them to their default. If you try to delete them, the server will reject the request with a Server is unwilling to perform (53) error.
Use the latest default values provided by a new Directory Server version.
New versions often provide optimized settings and increased security. For example, if you do not set the passwordStorageScheme attribute, Directory Server automatically uses the strongest supported password storage scheme available. If a future update changes the default value to increase security, passwords will be automatically encrypted using the new storage scheme when a user set a passwords.
Note
If you manually set a parameter to the same value as its default, the value is not updated. This happens, when a newer version uses a different default value.

Table 1.1. Configuration Attributes That Cannot Be Deleted

`nsslapd-accesslog`	`nsslapd-auditlog`	`nsslapd-bakdir`
`nsslapd-certdir`	`nsslapd-certmap-basedn`	`nsslapd-conntablesize`
`nsslapd-errorlog`	`nsslapd-instancedir`	`nsslapd-ldifdir`
`nsslapd-localhost`	`nsslapd-localuser`	`nsslapd-lockdir`
`nsslapd-rootpw`	`nsslapd-referral`	`nsslapd-referralmode`
`nsslapd-rundir`	`nsslapd-saslpath`	`nsslapd-schemadir`
`nsslapd-tmpdir`	`nsslapd-workingdir`

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.

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

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 in another database, and the ou=contractors suffix in yet another database.

2.1.1. Creating Suffixes

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. Both root and sub suffixes are used to organize the contents of the directory tree. The data for root and sub suffixes are contained in 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. Here, two root suffixes are required, 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”.

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

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 the 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 you wanted to include entries in the European branch of the directory tree in general searches, you could make the European branch a sub suffix of the general branch. To do this, create a root suffix for Example Corporation, dc=example,dc=com, and then create a sub suffix beneath it for the European directory entries, l=europe,dc=example,dc=com. From a client application's perspective, the directory tree would appear as illustrated in Figure 2.4, “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

In the Directory Server Console, select the Configuration tab.
Right-click Data in the left navigation pane, and select New Root Suffix from the pop-up menu.
Enter a unique suffix in the New suffix field.
The suffix must be named in line with dc naming conventions, such as dc=example,dc=com.
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

In the Directory Server Console, select the Configuration tab.
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.
Enter a unique suffix name in the New suffix field. The suffix must be named in line with dc naming conventions, for example ou=groups.
The root suffix is automatically added to the name. For example, if 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.
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 using the Command Line

The suffix configuration information is stored in the cn=mapping tree,cn=config entry. Use the ldapmodify utility to add new suffixes to the directory.

For a list of all parameters you can set when creating a suffix, see the corresponding section in the Red Hat Directory Server Configuration, Command, and File Reference.

Creating a Root Suffix

For example, to add the dc=example,dc=com root suffix:

# ldapmodify -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
cn: dc=example,dc=com
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: UserData

Creating a Sub Suffix

Creating a sub suffix is similar to creating a root suffix. The difference is that you additionally set the parent suffix in the nsslapd-parent-suffix.

For example, to create the ou=groups sub suffix under the dc=example,dc=com root suffix:

# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn="ou=groups,dc=example,dc=com",cn=mapping tree,cn=config
changetype: add
cn: ou=groups,dc=example,dc=com
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: GroupData
nsslapd-parent-suffix: dc=example,dc=com

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 (Directory Server Agent Service Entry) and can be queried by clients anonymously by checking the defaultnamingcontext attribute in the root DSE:

# 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

To maintain configuration consistency, do not remove the nsslapd-defaultnamingcontext attribute from the nsslapd-allowed-to-delete-attrs list.

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

2.1.2.2. Disabling a Suffix

In certain situations, a suffix in the directory needs to be disabled. If a suffix is disabled, the content of the database related to the suffix are no longer accessible by clients.

2.1.2.2.1. Disabling a Suffix Using the Command Line

To disable a suffix using the command line, set the nsslapd-state attribute of the corresponding suffix entry to disabled:

# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=suffix_DN,cn=mapping tree,cn=config
changetype: modify
replace: nsslapd-state
nsslapd-state: disabled

2.1.2.2.2. Disabling a Suffix Using the Console

To disable a suffix using the Console:

In the Directory Server Console, select the Configuration tab.
Under Data in the left navigation pane, click the suffix to disable.
Click the Suffix Setting tab, and deselect the Enable this suffix check box.

2.1.2.3. Deleting a Suffix

If a suffix is no longer required, delete it from the database.

Warning

Deleting a suffix also deletes all database entries and replication information associated with that suffix.

2.1.2.3.1. Deleting a Suffix Using the Command Line

To delete a suffix using the command line:

Delete the suffix from the mapping tree:

# ldapdelete -D "cn=Directory Manager" -W -p 389 -h server.example.com -x "cn="suffix_DN",cn=mapping tree,cn=config"

If the suffix uses a separate database, delete the database:

# ldapdelete -D "cn=Directory Manager" -W -p 389 -h server.example.com -x "cn=database_name,cn=ldbm database,cn=plugins,cn=config"

2.1.2.3.2. Deleting a Suffix Using the Console

To delete a suffix using the Console:

In the Directory Server Console, select the Configuration tab.
Under Data in the left navigation pane, select the suffix to delete.
Right-click the suffix, and select Delete from the menu.
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 data of that directory.

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 units corresponds to three databases, for example:
In this example, DB1 contains the data for ou=people and the data for dc=example,dc=com, so that clients can conduct searches based at dc=example,dc=com. However, DB2 only contains the data for ou=groups, and DB3 only 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.
A custom plug-in distributes data from a single suffix across multiple databases. Contact Red Hat Consulting 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

In the Directory Server Console, select the Configuration tab.
In the left pane, expand Data, then click the suffix to which to add the new database.
Right-click the suffix, and select New Database from the pop-up menu.
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/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:

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 added entry corresponds to a database named UserData that contains the data for the root or sub suffix ou=people,dc=example,dc=com.

Create a root or a sub-suffix, as described in Section 2.1.1.3, “Creating Root and Sub Suffixes using 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 Consulting.

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

2.2.1.3.1. Adding the Custom Distribution Function to a Suffix Using the Directory Server Console

In the Directory Server Console, select the Configuration tab.
Expand Data in the left navigation pane. Select the suffix to which to apply the distribution function.
Select the Databases tab in the right window.
The databases associated with the suffix are already listed in the Databases tab. Click Add to associate additional databases with the suffix.
Enter the path to the distribution library.
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

Run ldapmodify.

# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

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 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.1, “Managing Entries Using the Command Line”.

2.2.2. Maintaining Directory Databases

Section 2.2.2.1, “Placing a Database in Read-Only Mode”
Section 2.2.2.2, “Deleting a Database”
Section 2.2.2.3, “Changing the Transaction Log Directory”

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.

Section 2.2.2.1.1, “Making a Database Read-Only Using the Console”
Section 2.2.2.1.2, “Making a Database Read-Only from the Command Line”
Section 2.2.2.1.3, “Placing the Entire Directory Server in Read-Only Mode”

2.2.2.1.1. Making a Database Read-Only Using the Console

In the Directory Server Console, select the Configuration tab.
Expand Data in the left pane. Expand the suffix containing the database to put in read-only mode.
Select the database to put into read-only mode.
Select the Database Settings tab in the right pane.
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:

Run ldapmodify.

# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

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:

In the Directory Server Console, select the Configuration tab, and then select the top entry in the navigation tree in the left pane.
Select the Settings tab in the right pane.
Select the Make Entire Server Read-Only check box.
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.

In the Directory Server Console, select the Configuration tab.
Expand the Data folder, and then select the suffix.
Select the database to delete.
Right-click the database and select Delete from the pop-up menu.
Confirm that the database should be deleted in the Delete Database dialog box.

2.2.2.3. Changing the Transaction Log Directory

The transaction log enables Directory Server to recover the database, after an instance shut down unexpectedly. In certain situations, administrators want to change the path to the transaction logs. For example, to store them on a different physical disk than the Directory Server database.

Note

To achieve higher performance, mount a faster disk to the directory that contains the transaction logs, instead of changing the location. For details, see the corresponding section in the Red Hat Directory Server Performance Tuning Guide.

To change the location of the transaction log directory:

Stop the Directory Server instance:
```
# systemctl stop dirsrv@instance_name
```
Create a new location for the transaction logs. For example:
```
# mkdir -p /srv/dirsrv/instance_name/db/
```

Set permissions to enable only Directory Server to access the directory:

# chown dirsrv:dirsrv /srv/dirsrv/instance_name/db/
# chmod 770 /srv/dirsrv/instance_name/db/

Remove all __db.* files from the previous transaction log directory. For example:
```
# rm /var/lib/dirsrv/slapd-instance_name/db/__db.*
```
Move all log.* files from the previous to the new transaction log directory. For example:
```
# mv /var/lib/dirsrv/slapd-instance_name/db/log.* \
     /srv/dirsrv/instance_name/db/
```

If SELinux is running in enforcing mode, set the dirsrv_var_lib_t context on the directory:

# semanage fcontext -a -t dirsrv_var_lib_t /srv/dirsrv/instance_name/db/
# restorecon -Rv /srv/dirsrv/instance_name/db/

Edit the /etc/dirsrv/slapd-instance_name/dse.ldif file, and update the nsslapd-db-logdirectory parameter under the cn=config,cn=ldbm database,cn=plugins,cn=config entry. For example:
```
dn: cn=config,cn=ldbm database,cn=plugins,cn=config
...
nsslapd-db-logdirectory: /srv/dirsrv/instance_name/db/
```
Start the instance:
```
# systemctl start dirsrv@instance_name
```

2.3. Creating and Maintaining Database Links

Chaining means that a server contacts other servers on behalf of a client application and then returns the combined results. Chaining is implemented through a database link, which points to data stored remotely. When a client application requests data from a database link, the database link retrieves the data from the remote database and returns it to the client.

Section 2.3.1, “Creating a New Database Link”
Section 2.3.2, “Configuring the Chaining Policy”
Section 2.3.3, “Maintaining Database Links”
Section 2.3.4, “Configuring Database Link Defaults”
Section 2.3.5, “Deleting Database Links”
Section 2.3.6, “Database Links and Access Control Evaluation”

For more general information about chaining, see the chapter "Designing the Directory Topology," in the Red Hat Directory Server Deployment Guide. Section 20.8, “Monitoring Database Link Activity” covers how to monitor database link activity.

2.3.1. Creating a New Database Link

The basic database link configuration requires four piece of information:

Suffix information. A suffix is created in the directory tree that is managed by the database link, not a regular database. This suffix corresponds to the suffix on the remote server that contains the data.
Bind credentials. When the database link binds to a remote server, it impersonates a user, and this specifies the DN and the credentials for each database link to use to bind with remote servers.
LDAP URL. This supplies the LDAP URL of the remote server to which the database link connects. The URL consists of the protocol (ldap or ldaps), the host name or IP address (IPv4 or IPv6) for the server, and the port.
List of failover servers. This supplies a list of alternative servers for the database link to contact in the event of a failure. This configuration item is optional.

Note

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

2.3.1.1. Creating a New Database Link Using the Console

In the Directory Server Console, select the Configuration tab.
Create a new suffix as described in Section 2.1.1, “Creating Suffixes”.
Deselect the Create associated database automatically check box. It is simpler to configure a database link on a suffix without a database associated with it because having both a database and database link requires custom distribution functions to distribute directory data.
In the left pane, right-click the new suffix, and select New Database Link from the pop-up menu.
Fill in the database link name. The name can be a combination of alphanumeric characters, dashes (-), and underscores (_). No other characters, like spaces, are allowed.
Set the radio button for the appropriate method for authentication.
There are four authentication methods:
- Simple means that the server connects over the standard port with no encryption. The only required information is the bind DN and password for the user as whom the server connects to the remote server.
- Server TLS/SSL Certificate uses the local server's TLS certificate to authenticate to the remote server. A certificate must be installed on the local server for certificate-based authentication, and the remote server must have certificate mapping configured so that it can map the subject DN in the local server's certificate to the corresponding user entry.
  Configuring TLS and certificate mapping is described in Section 9.4, “Enabling TLS”.
  Note
  When the database link and remote server are configured to communicate using TLS, this does not mean that the client application making the operation request must also communicate using TLS. The client can bind using a normal port.
- SASL/DIGEST-MD5 requires only the bind DN and password to authenticate.
- SASL/GSSAPI requires the local server to have a Kerberos keytab (as in Section 9.10.2.2, “About the KDC Server and Keytabs”), and the remote server to have a SASL mapping to map the local server's principal to the real user entry (as in Section 9.9.3.1, “Configuring SASL Identity Mapping from the Console”).
In the Remote Server Information section, select the connection type for the local server to use to connect to the remote server. There are three options:
- Use LDAP. This sets a standard, unencrypted connection.
- Use TLS/SSL. This uses a secure connection over the server's secure LDAPS port, such as 636. This setting is required to use TLS/TLS.
  When using TLS, make sure that the remote server's port number is set to its secure port.
- Use Start TLS. This uses Start TLS to establish a secure connection over the server's standard port.
Note
If secure binds are required for simple password authentication (Section 19.11.1, “Requiring Secure Binds”), then any chaining operations will fail unless they occur over a secure connection. Using a secure connection (TLS and Start TLS connections or SASL authentication) is recommended, anyway.
In the Remote Server Information section, fill in the name (host name, IPv4 address, or IPv6 address) and port number for the remote server.
For any failover servers, fill in the host name and port number, and click the Add button. A failover server is a backup server, so that if the primary remote server fails, the database link contacts the first server in the failover servers list and cycles through the list until a server is accessed.

The new database link is listed under the suffix, in place of the database.

Note

The Console provides a checklist of information that needs to be present on the remote server for the database link to bind successfully. To view this checklist, click the new database link, and click the Authentication tab. The checklist is in the Remote server checklist box.

2.3.1.2. Creating a Database Link from the Command Line

Use the ldapmodify command-line utility to create a new database link. The new instance must be located in the cn=chaining database,cn=plugins,cn=config entry.
```
# ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
```

Specify the configuration information for the database link:

dn: cn=examplelink,cn=chaining database,cn=plugins,cn=config
changetype: add
objectclass: top
objectclass: extensibleObject
objectclass: nsBackendInstance
nsslapd-suffix: ou=people,dc=example,dc=com suffix being chained
nsfarmserverurl: ldap://people.example.com:389/  LDAP URL to remote server  
nsMultiplexorBindDN: cn=proxy admin,cn=config bind DN
nsMultiplexorCredentials: secret bind password
cn: examplelink

Note

Default configuration attributes are contained in the cn=default instance config,cn=chaining database,cn=plugins,cn=config entry. These configuration attributes apply to all database links at creation time. Changes to the default configuration only affect new database links. The default configuration attributes on existing database links cannot be changed.

Each database link contains its own specific configuration information, which is stored with the database link entry itself, cn=database_link, cn=chaining database,cn=plugins,cn=config. For more information about configuration attributes, see the Red Hat Directory Server Configuration, Command, and File Reference.

Section 2.3.1.2.1, “Providing Suffix Information”
Section 2.3.1.2.2, “Providing Bind Credentials”
Section 2.3.1.2.3, “Providing an LDAP URL”
Section 2.3.1.2.4, “Providing a List of Failover Servers”
Section 2.3.1.2.5, “Using Different Bind Mechanisms”
Section 2.3.1.2.6, “Summary of Database Link Configuration Attributes”
Section 2.3.1.2.7, “Database Link Configuration Example”

2.3.1.2.1. Providing Suffix Information

Use the nsslapd-suffix attribute to define the suffix managed by the database link. For example, for the database link to point to the people information for a remote site of the company, enter the following suffix information:

nsslapd-suffix: l=Zanzibar,ou=people,dc=example,dc=com

The suffix information is stored in the cn=database_link, cn=chaining database,cn=plugins,cn=config entry.

Note

After creating the database link, any alterations to the nsslapd-nsslapd-suffix attribute are applied only after the server containing the database link is restarted.

2.3.1.2.2. Providing Bind Credentials

For a request from a client application to be chained to a remote server, special bind credentials can be supplied for the client application. This gives the remote server the proxied authorization rights needed to chain operations. Without bind credentials, the database link binds to the remote server as anonymous.

Providing bind credentials involves the following steps:

On the remote server:
- Create an administrative user for the database link.
  For information on adding entries, see Chapter 3, Managing Directory Entries.
- Provide proxy access rights for the administrative user created in step 1 on the subtree chained to by the database link.
  For more information on configuring ACIs, see Chapter 18, Managing Access Control
On the server containing the database link, use ldapmodify to provide a user DN for the database link in the nsMultiplexorBindDN attribute of the cn=database_link,cn=chaining database,cn=plugins,cn=config entry.
Warning
The nsMultiplexorBindDN cannot be that of the Directory Manager.
Use ldapmodify to provide a user password for the database link in the nsMultiplexorCredentials attribute of the cn=database_link,cn=chaining database,cn=plugins,cn=config entry.

For example, a client application sends a request to Server A. Server A contains a database link that chains the request to a database on Server B.

The database link on Server A binds to Server B using a special user as defined in the nsMultiplexorBindDN attribute and a user password as defined in the nsMultiplexorCredentials attribute. In this example, Server A uses the following bind credentials:

nsMultiplexorBindDN: cn=proxy admin,cn=config
nsMultiplexorCredentials: secret

Server B must contain a user entry corresponding to the nsMultiplexorBindDN, and set the proxy authentication rights for this user. To set the proxy authorization correctly, set the proxy ACI as any other ACI.

Warning

Carefully examine access controls when enabling chaining to avoid giving access to restricted areas of the directory. For example, if a default proxy ACI is created on a branch, the users that connect using the database link will be able to see all entries below the branch. There may be cases when not all of the subtrees should be viewed by a user. To avoid a security hole, create an additional ACI to restrict access to the subtree.

For more information on ACIs, see Chapter 18, Managing Access Control.

Note

When a database link is used by a client application to create or modify entries, the attributes creatorsName and modifiersName do not reflect the real creator or modifier of the entries. These attributes contain the name of the administrative user granted proxied authorization rights on the remote data server.

2.3.1.2.3. Providing an LDAP URL

On the server containing the database link, identify the remote server that the database link connects with using an LDAP URL. Unlike the standard LDAP URL format, the URL of the remote server does not specify a suffix. It takes the form ldap://server:port, where the server can be a host name, IPv4 address, or IPv6 address.

The URL of the remote server using the nsFarmServerURL attribute is set in the cn=database_link, cn=chaining database,cn=plugins,cn=config entry of the configuration file.

nsFarmServerURL: ldap://example.com:389/

Note

Do not forget to use the trailing slash (/) at the end of the URL.

For the database link to connect to the remote server using LDAP over TLS, the LDAP URL of the remote server uses the protocol LDAPS instead of LDAP in the URL and points to the secure port of the server. For example:

nsFarmServerURL: ldaps://africa.example.com:636/

Note

TLS has to be enabled on the local Directory Server and the remote Directory Server to be chained over TLS. For more information on enabling TLS, see Section 9.4, “Enabling TLS”.

When the database link and remote server are configured to communicate using TLS, this does not mean that the client application making the operation request must also communicate using TLS. The client can bind using a normal port.

2.3.1.2.4. Providing a List of Failover Servers

There can be additional LDAP URLs for servers included to use in the case of failure. Add alternate servers to the nsFarmServerURL attribute, separated by spaces.

nsFarmServerURL: ldap://example.com us.example.com:389 africa.example.com:1000/

In this sample LDAP URL, the database link first contacts the server example.com on the standard port to service an operation. If it does not respond, the database link then contacts the server us.example.com on port 389. If this server fails, it then contacts africa.example.com on port 1000.

2.3.1.2.5. Using Different Bind Mechanisms

The local server can connect to the remote server using several different connection types and authentication mechanisms.

There are three ways that the local server can connect to the remote server:

Over the standard LDAP port
Over a dedicated LDAPS port
Using Start TLS, which is a secure connection over a standard port

Note

Ultimately, there are two connection settings. The TLS option signifies that both of the servers are configured to run and accept connections over TLS, but there is no separate configuration attribute for enforcing TLS.

The connection type is identified in the nsUseStartTLS attribute. When this is on, then the server initiates a Start TLS connect over the standard port. If this is off, then the server either uses the LDAP port or the LDAPS port, depending on what is configured for the remote server in the nsFarmServerURL attribute.

For example, to use Start TLS:

nsUseStartTLS: on

For example, to use a standard connection or TLS connection:

nsUseStartTLS: off

There are four different methods which the local server can use to authenticate to the farm server.

empty. If there is no bind mechanism set, then the server performs simple authentication and requires the nsMultiplexorBindDN and nsMultiplexorCredentials attributes to give the bind information.
EXTERNAL. This uses an TLS certificate to authenticate the farm server to the remote server. Either the farm server URL must be set to the secure URL (ldaps) or the nsUseStartTLS attribute must be set to on.
Additionally, the remote server must be configured to map the farm server's certificate to its bind identity, as described in the certmap.conf section in the Red Hat Directory Server Configuration, Command, and File Reference.
DIGEST-MD5. This uses SASL authentication with DIGEST-MD5 encryption. As with simple authentication, this requires the nsMultiplexorBindDN and nsMultiplexorCredentials attributes to give the bind information.
GSSAPI. This uses Kerberos-based authentication over SASL.
The farm server must be configured with a Kerberos keytab, and the remote server must have a defined SASL mapping for the farm server's bind identity. Setting up Kerberos keytabs and SASL mappings is described in Section 9.9, “Setting up SASL Identity Mapping”.

Note

SASL connections can be established over standard connections or TLS connections.

For example:

nsBindMechanism: EXTERNAL

Note

If SASL is used, then the local server must also be configured to chain the SASL and password policy components. Add the components for the database link configuration, as described in Section 2.3.2, “Configuring the Chaining Policy”. For example:

ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=config,cn=chaining database,cn=plugins,cn=config
changetype: modify
add: nsActiveChainingComponents
nsActiveChainingComponents: cn=password policy,cn=components,cn=config
-
add: nsActiveChainingComponents
nsActiveChainingComponents: cn=sasl,cn=components,cn=config
^D

2.3.1.2.6. Summary of Database Link Configuration Attributes

The following table lists the attributes available for configuring a database link. Some of these attributes were discussed in the earlier sections. All instance attributes are defined in the cn=database_link, cn=chaining database,cn=plugins,cn=config entry.

Values defined for a specific database link take precedence over the global attribute value.

Table 2.1. Database Link Configuration Attributes

Attributes	Value
nsTransmittedControls ^[†]	Gives the OID of LDAP controls forwarded by the database link to the remote data server.
nsslapd-suffix	The suffix managed by the database link. Any changes to this attribute after the entry has been created take effect only after the server containing the database link is restarted.
nsslapd-timelimit	Default search time limit for the database link, given in seconds. The default value is `3600` seconds.
nsslapd-sizelimit	Default size limit for the database link, given in number of entries. The default value is `2000` entries.
nsFarmServerURL	Gives the LDAP URL of the remote server (or farm server) that contains the data. This attribute can contain optional servers for failover, separated by spaces. If using cascading chaining, this URL can point to another database link.
nsUseStartTLS	Sets whether to use Start TLS to establish a secure connection over a standard port. The default is `off`, which is used for both simple (standard) connections and TLS connections.
nsBindMechanism	Sets the authentication method to use to authenticate (bind) to the remote server. If you set an empty value, simple bind is used (LDAP_SASL_SIMPLE).
nsMultiplexorBindDN	DN of the administrative entry used to communicate with the remote server. The term `multiplexor` in the name of the attribute means the server which contains the database link and communicates with the remote server. This bind DN cannot be the Directory Manager. If this attribute is not specified, the database link binds as `anonymous`.
nsMultiplexorCredentials	Password for the administrative user, given in plain text. If no password is provided, it means that users can bind as `anonymous`. The password is encrypted in the configuration file.
nsCheckLocalACI	Reserved for advanced use only. Controls whether ACIs are evaluated on the database link as well as the remote data server. Takes the values `on` or `off`. Changes to this attribute occur only after the server has been restarted. The default value is `off`.
nsProxiedAuthorization	Reserved for advanced use only. Disables proxied authorization. A value of `off` means proxied authorization is disabled. The default value is `on`.
nsActiveChainingComponents^[†]	Lists the components using chaining. A component is any functional unit in the server. The value of this attribute in the database link instance overrides the value in the global configuration attribute. To disable chaining on a particular database instance, use the value `none`. The default policy is not to allow chaining. For more information, see Section 2.3.2.1, “Chaining Component Operations”.
nsReferralOnScopedSearch	Controls whether referrals are returned by scoped searches. This attribute is for optimizing the directory because returning referrals in response to scoped searches is more efficient. Takes the values `on` or `off`. The default value is `off`.
nsHopLimit	Maximum number of times a request can be forwarded from one database link to another. The default value is `10`.
^[†] Can be both a global and instance attribute. This global configuration attribute is located in the `cn=config,cn=chaining database,cn=plugins,cn=config` entry. The global attributes are dynamic, meaning any changes made to them automatically take effect on all instances of the database link within the directory.

For further details, see the parameter descriptions in the Red Hat Directory Server Configuration, Command, and File Reference.

2.3.1.2.7. Database Link Configuration Example

Suppose a server within the us.example.com domain contains the subtree l=Walla Walla,ou=people,dc=example,dc=com on a database and that operation requests for the l=Zanzibar,ou=people,dc=example,dc=com subtree should be chained to a different server in the africa.example.com domain.

Run ldapmodify to add a database link to Server A:

# ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

Specify the configuration information for the database link:

dn: cn=DBLink1,cn=chaining database,cn=plugins,cn=config
changetype: add
objectclass: top
objectclass: extensibleObject
objectclass: nsBackendInstance
nsslapd-suffix: c=africa,ou=people,dc=example,dc=com
nsfarmserverurl: ldap://africa.example.com:389/
nsMultiplexorBindDN: cn=proxy admin,cn=config
nsMultiplexorCredentials: secret
cn: DBLink1

dn: cn="c=africa,ou=people,dc=example,dc=com",cn=mapping tree,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: DBLink1
nsslapd-parent-suffix: ou=people,dc=example,dc=com
cn: c=africa,ou=people,dc=example,dc=com

In the first entry, the nsslapd-suffix attribute contains the suffix on Server B to which to chain from Server A. The nsFarmServerURL attribute contains the LDAP URL of Server B.

The second entry creates a new suffix, allowing the server to route requests made to the new database link. The cn attribute contains the same suffix specified in the nsslapd-suffix attribute of the database link. The nsslapd-backend attribute contains the name of the database link. The nsslapd-parent-suffix attribute specifies the parent of this new suffix, ou=people,dc=example,dc=com.

Create an administrative user on Server B, as follows:

dn: cn=proxy admin,cn=config
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: proxy admin
sn: proxy admin
userPassword: secret
description: Entry for use by database links

Warning

Do not use the Directory Manager user as the proxy administrative user on the remote server. This creates a security hole.

Add the following proxy authorization ACI to the l=Zanzibar,ou=people,dc=example,dc=com entry on Server B:
```
aci: (targetattr = "*")(version 3.0; acl "Proxied authorization
     for database links"; allow (proxy) userdn = "ldap:///cn=proxy
     admin,cn=config";)
```
This ACI gives the proxy admin user read-only access to the data contained on the remote server within the l=Zanzibar,ou=people,dc=example,dc=com subtree only.
Note
When a user binds to a database link, the user's identity is sent to the remote server. Access controls are always evaluated on the remote server. For the user to modify or write data successfully to the remote server, set up the correct access controls on the remote server. For more information about how access controls are evaluated in the context of chained operations, see Section 2.3.6, “Database Links and Access Control Evaluation”.

2.3.2. Configuring the Chaining Policy

These procedures describe configuring how Directory Server chains requests made by client applications to Directory Servers that contain database links. This chaining policy applies to all database links created on Directory Server.

2.3.2.1. Chaining Component Operations

A component is any functional unit in the server that uses internal operations. For example, plug-ins are considered to be components, as are functions in the front-end. However, a plug-in may actually be comprised of multiple components (for example, the ACI plug-in).

Some components send internal LDAP requests to the server, expecting to access local data only. For such components, control the chaining policy so that the components can complete their operations successfully. One example is the certificate verification function. Chaining the LDAP request made by the function to check certificates implies that the remote server is trusted. If the remote server is not trusted, then there is a security problem.

By default, all internal operations are not chained and no components are allowed to chain, although this can be overridden.

Additionally, an ACI must be created on the remote server to allow the specified plug-in to perform its operations on the remote server. The ACI must exist in the suffix assigned to the database link.

The following lists the component names, the potential side-effects of allowing them to chain internal operations, and the permissions they need in the ACI on the remote server:

ACI plug-in

This plug-in implements access control. Operations used to retrieve and update ACI attributes are not chained because it is not safe to mix local and remote ACI attributes. However, requests used to retrieve user entries may be chained by setting the chaining components attribute:

nsActiveChainingComponents: cn=ACI Plugin,cn=plugins,cn=config