Administration Guide

Red Hat Directory Server 11

Basic and advanced administration of Directory Server

Abstract

This guide covers both GUI and command-line procedures for managing Directory Server instances and databases.

Making Open Source More Inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see “our CTO Chris Wright's message”.

Chapter 1. General Directory Server Management Tasks

This chapter describes the general tasks of managing Directory Server instances.

1.1. System Requirements

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

1.2. File Locations

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

1.3. Supported Methods to Configure Directory Server

You can configure Directory Server using:

the command-line utilities provided by Directory Server
the web console

Important

The web console does not automatically display the latest settings if a user changes the configuration outside of the console's window. For example, if you change the configuration using the command line while the web console is open, the new settings are not automatically updated in the web console. This applies also if you change the configuration using the web console on a different computer. To work around the problem, manually refresh the web console in the browser if the configuration has been changed outside the console's window.

1.4. Logging Into Directory Server Using the Web Console

The web console is a browser-based graphical user interface (GUI) that enables users to perform administrative tasks. The Directory Server package automatically installs the Directory Server user interface for the web console.

To open Directory Server in the web console:

Use a browser and connect to the web console running on port 9090 on the Directory Server host. For example:
```
https://server.example.com:9090
```
Log in as the root user or as a user with sudo privileges.
Select the Red Hat Directory Server entry.

1.5. Starting and Stopping a Directory Server Instance

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

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

To start the instance:
```
# dsctl instance_name start
```
To stop the instance:
```
# dsctl instance_name stop
```
To restart the instance:
```
# dsctl instance_name restart
```

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.5.2. Starting and Stopping a Directory Server Instance Using the Web Console

As an alternative to command line, you can use the web console to start, stop, or restart instances.

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

Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
Select the instance.
Click the Actions button and select the action to execute:
- Start Instance
- Stop Instance
- Restart Instance

1.6. Creating a New Directory Server Instance

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

1.7. Removing a Directory Server Instance

If you run multiple instances on a server, you can remove individual instances of them.

When you remove an instance, the content of the /var/lib/dirsrv/slapd-instance_name/ and /etc/dirsrv/slapd-instance_name/ directories are removed.

Important

The /var/lib/dirsrv/slapd-instance_name/ directory contains the database, as well as the backup and export directory. The /etc/dirsrv/slapd-instance_name/ directory contains the instance configuration and the network security services (NSS) database. Before you remove an instance, backup this data.

1.7.1. Removing an Instance Using the Command Line

To remove an instance using the command line:

# dsctl instance_name remove --do-it
Removing instance ...
Completed instance removal

1.7.2. Removing an Instance Using the Web Console

To remove an instance using the web console:

Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
Select the instance.
Click the Actions button, and select Remove instance.

1.8. Setting Directory Server Configuration Parameters

Directory Server stores its configuration in the cn=config directory entry. Each configuration parameter is an LDAP attribute and the parameter's value is the value set in this attribute.

1.8.1. Managing Configuration Parameters

You can set, update, and delete configuration parameters by:

Using the dsconf utility:
Note
Red Hat recommends using the dsconf utility to manage the Directory Server configuration.
Example 1.1. Setting a Configuration Parameter Using dsconf
For example, to set the error log level to 16384, update the nsslapd-errorlog-level parameter using the dsconf utility:
```
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-errorlog-level=16384
```
For further details about using dsconf, see the dsconf(8) man page.
Using the LDAP interface:
Example 1.2. Setting a Configuration Parameter using the LDAP Interface
For example, to set the error log level to 16384, update the nsslapd-errorlog-level parameter using the LDAP interface:
```
# ldapmodify -D "cn=Directory Manager" -W -x -H ldap://server.example.com:389

dn: cn=config
replace: nsslapd-errorlog-level
nsslapd-errorlog-level: 16384
```
Editing the /etc/dirsrv/slapd-instance_name/dse.ldif file.
Warning
As long as an instance starts successfully, do not manually edit this file because this can cause Directory Server to not work as expected, or the instance can fail to start.

1.8.2. Where Directory Server Stores its Configuration

Directory Server stores the configuration from the cn=config entry in the /etc/dirsrv/slapd-instance_name/dse.ldif file. The server stores only parameters you modified in this file. Attributes that are not listed, use their default value. This enables you to identify all configuration parameters you set in this instance by displaying the /etc/dirsrv/slapd-instance_name/dse.ldif file.

Important

Do not manually edit the /etc/dirsrv/slapd-instance_name/dse.ldif file as long as the instance starts successfully.

For details about how you can edit configuration parameters, see Section 1.8.1, “Managing Configuration Parameters”.

1.8.3. Benefits of Using Default Values

If a parameter is not set, Directory Server uses the default value of this parameter. Using the default value has the benefit that 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 sets a password.

1.8.3.1. Removing a Parameter to Use the Default Value

If a parameter is set and you want to use the default value instead, delete the parameter:

# dsconf -D "cn=Directory Manager" ldap://server.example.com config delete parameter_name

Important

You cannot delete certain parameters, such as nsslapd-secureport to reset them to default. If you try to delete them, the server rejects the request with a Server is unwilling to perform (53) error.

1.8.4. The `dsconf config backend` command limitations

The dsconf config backend command retrieves and sets backends configuration. The command has the following arguments:

The dsconf config backend get command retrieves all server backend configuration attributes with set values, for example:

# dsconf -D "cn=Directory Manager" ldap://server.example.com:389 backend config get

nsslapd-lookthroughlimit: 5000
nsslapd-mode: 600
nsslapd-idlistscanlimit: 2147483646
…

Note

You can get only the full set of attribute values by using the dsconf config backend get command, not a value for a specified attribute.

The dsconf config backend set command sets backends configuration attributes individually. To set a value, specify an option that matches the LDAP attribute name, for example:

# dsconf -D "cn=Directory Manager"  ldap://server.example.com:389 backend config set --lookthroughlimit 4000  --cache-autosize-split 24

The following is the dsconf backend config set command options and LDAP attribute names mapping:

Table 1.1. Mapping of the dsconf backend config set command options and LDAP attribute names
The `dsconf backend config set` command options	LDAP attribute names
--lookthroughlimit	nsslapd-lookthroughlimit
--mode	nsslapd-mode
--idlistscanlimit	nsslapd-idlistscanlimit
--directory	nsslapd-directory
--dbcachesize	nsslapd-dbcachesize
--logdirectory	nsslapd-db-logdirectory
--txn-wait	nsslapd-db-transaction-wait
--checkpoint-interval	nsslapd-db-checkpoint-interval
--compactdb-interval	nsslapd-db-compactdb-interval
--compactdb-time	nsslapd-db-compactdb-time
--txn-batch-val	nsslapd-db-transaction-batch-val
--txn-batch-min	nsslapd-db-transaction-batch-min-wait
--txn-batch-max	nsslapd-db-transaction-batch-max-wait
--logbufsize	nsslapd-db-logbuf-size
--locks	nsslapd-db-locks
--locks-monitoring-enabled	nsslapd-db-locks-monitoring-enabled
--locks-monitoring-threshold	nsslapd-db-locks-monitoring-threshold
--locks-monitoring-pause	nsslapd-db-locks-monitoring-pause
--import-cache-autosize	nsslapd-import-cache-autosize
--import-cachesize	nsslapd-import-cachesize
--cache-autosize	nsslapd-cache-autosize
--cache-autosize-split	nsslapd-cache-autosize-split
--exclude-from-export	nsslapd-exclude-from-export
--pagedlookthroughlimit	nsslapd-pagedlookthroughlimit
--pagedidlistscanlimit	nsslapd-pagedidlistscanlimit
--rangelookthroughlimit	nsslapd-rangelookthroughlimit
--backend-opt-level	nsslapd-backend-opt-level
--deadlock-policy	nsslapd-db-deadlock-policy
--db-home-directory	nsslapd-db-home-directory
--db-lib	nsslapd-backend-implement

1.9. Changing the LDAP and LDAPS Port Numbers

By default, Directory Server uses port 389 for the LDAP and, if enabled, port 636 for the LDAPS protocol. You can change these port numbers, for example, to run multiple Directory Server instances on one host.

Important

The new ports you assign to the protocols for an instance must not be in use by any other service.

1.9.1. Changing the Port Numbers Using the Command Line

To change the port numbers using the command line, update the following parameters:

nsslapd-port: Stores the port number the instance uses for the LDAP protocol.
nsslapd-secureport: Stores the port number the instance uses for the LDAPS protocol.

To change the port numbers of the LDAP and LDAPS protocol using the command line:

Optionally, display the currently configured port numbers for the instance:

# dsconf -D "cn=Directory Manager" ldap://server.example.com config get nsslapd-port nsslapd-secureport
nsslapd-port: 389
nsslapd-secureport: 636

To change the LDAP port:

Set the port for the LDAP protocol. For example, to set it to 1389:

# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-port=1389
Successfully replaced "nsslapd-port"

Set the ldap_port_t type for the LDAP port you assigned in the previous step:
```
# semanage port -a -t ldap_port_t -p tcp 1389
```

To change the LDAPS port:

Set the port for the LDAPS protocol. For example, to set it to 1636:

# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-secureport=1636
Successfully replaced "nsslapd-secureport"

Set the ldap_port_t type for the LDAPS port you assigned in the previous step:
```
# semanage port -a -t ldap_port_t -p tcp 1636
```

Restart the instance:
```
# dsctl instance_name restart
```

1.9.2. Changing the Port Numbers Using the Web Console

To change the port numbers of the LDAP and LDAPS protocol using the web console:

Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
Select the instance.
To change the LDAP port:
1. Open the Server Settings menu.
2. On the Server Settings tab, fill the new port number into the LDAP Port field.
3. Click Save.
To change the LDAPS port:
1. Open the Server Settings menu.
2. On the General Settings tab, fill the new port number into the LDAPS Port field.
3. Click Save.
Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.

1.10. Using Directory Server Plug-ins

Directory Server provides several core plug-ins, such as for replication, class of service, and attribute syntax validation. Core plug-ins are enabled by default.

Additionally, the Directory Server packages contain further plug-ins to enhance the functionality, such as for attribute uniqueness and attribute linking. However, not all of these plug-ins are enabled by default.

For further details, see the Plug-in Implemented Server Functionality Reference chapter in the Red Hat Directory Server Configuration, Command, and File Reference.

1.10.1. Listing Available Plug-ins

1.10.1.1. Listing Available Plug-ins Using the Command Line

To list all available plug-ins using the command line:

# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin list
7-bit check
Account Policy Plugin
...

You require the exact name of the plug-in, for example, to enable or disable it using the command line.

1.10.1.2. Listing Available Plug-ins Using the Web Console

To display all available plug-ins using the web console:

Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
Select the instance.
Select the Plugins menu.

Optionally, you can filter the plug-ins by entering a name into the Filter Plugins field.

1.10.2. Enabling and Disabling Plug-ins

1.10.2.1. Enabling and Disabling Plug-ins Using the Command Line

To enable or disable a plug-in using the command line, use the dsconf utility.

Note

The dsconf command requires that you provide the name of the plug-in. For details about displaying the names of all plug-ins, see Section 1.10.1.1, “Listing Available Plug-ins Using the Command Line”.

For example, to enable the Automember plug-in:

Enable the plug-in:

# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin automember enable

Restart the instance:
```
# dsctl instance_name restart
```

1.10.2.2. Enabling and Disabling Plug-ins Using the Web Console

To enable or disable a plug-in using the web console:

Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
Select the instance.
Select the Plugins menu.
Select the All Plugins tab.
Click the Edit Plugin button to the right of the plug-in you want to enable or disable.
Change the status to ON to enable or to OFF to disable the plug-in.
Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.

1.10.3. Configuring Plug-ins

1.10.3.1. Configuring Plug-ins Using the Command Line

To configure plug-in settings, use the dsconf plugin command:

# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin \
     plug-in-specific_subcommand ...

For a list of plug-ins you can configure, enter:

# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin --help

1.10.3.2. Configuring Plug-ins Using the Web Console

To configure a plug-in using the web console:

Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
Select the instance.
Select the Plugins menu.
Select the All Plugins tab.
Select the plug-in and click Show Advanced Settings.
Open the plug-in-specific tab.
Set the appropriate settings.
Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.

1.10.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 enables a plug-in to be executed and complete before the next plug-in is initiated, to let the next plug-in take advantage of the previous plug-in's results.

The precedence can be set to a value from 1 (highest priority) to 99 (lowest priority). If no precedence is set, the default is 50.

Warning

Set a precedence value only in custom plug-ins. Updating the value of core plug-ins can cause Directory Server to not work as expected and is not supported by Red Hat.

1.10.4.1. Setting the Plug-in Precedence Using the Command Line

To update the precedence value of a plug-in using the command line:

Set precedence of the plug-in. For example, to set the precedence for the example plug-in to 1:

# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin edit example --precedence 1

Restart the instance:
```
# dsctl instance_name restart
```

1.10.4.2. Setting the Plug-in Precedence Using the Web Console

To update the precedence value of a plug-in using the web console:

Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
Select the instance.
Open the Plugins menu.
Select All Plugins.
Press the Edit Plugin button next to the plug-in for which you want to configure the precedence value.
Update the value in the Plugin Precedence field.
Click Save.
Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.

1.11. Creating and Using a .dsrc File to Set Default Options for Directory Server Command-line Utilities

A ~/.dsrc file simplifies commands that use the Directory Server command-line utilities. By default, these utilities require that you pass, for example, an LDAP URL or bind distinguished name (DN) to the command. If you store these settings in a ~/dsrc file, you can use the command-line utilities without specifying these settings each time.

1.11.1. How a .dsrc File Simplifies Commands

The following is an example of a ~/.dsrc file that specifies the LDAP URL of an instance and a bind DN:

[server1]
uri = ldap://server1.example.com
binddn = cn=Directory Manager
basedn = dc=example,dc=com

With these settings, you can use shorter Directory Server commands. For example, to create a user account:

# dsidm server1 user create

Without the ~/.dsrc file, you must specify the bind DN, LDAP URL, and base DN in the command:

# dsidm -D cn=Directory Manager ldap://server1.example.com -b "dc=example,dc=com" user create

1.11.2. Using the dsctl Utility to Create a .dsrc File

Instead of manually creating a ~/.dsrc file, you can use the dsctl utility to create it:

# dsctl instance_name dsrc create ...

You can pass the following options to the command:

--uri: Sets the URL to the instance in the format protocol://host_name_or_IP_address_or_socket.
Examples:
- --uri ldap://server.example.com
- --uri = ldaps://server.example.com
- --uri = ldapi://%%2fvar%%2frun%%2fslapd-instance_name.socket
  If you set the path to an Directory Server socket, use %%02 instead of slashes (/) in the path.
  Important
  If you use an ldapi URL, the server identifies the user ID (UID) and group ID (GID) of the user who runs the Directory Server command-line utility. If you run the command as the root user, both UID and GID are 0 and Directory Server automatically authenticates you as cn=Directory Manager without entering the corresponding password.
--starttls: Sets configures the utilities to connect to an LDAP port and then send the STARTTLS command to switch to an encrypted connection.
--basedn: Sets the base distinguished name (DN). For example: --basedn dc=example,dc=com
--binddn: Sets the bind DN. For example: --binddn cn=Directory Manager
--pwdfile: Sets the path to a file that contains the password of bind DN. For example: --pwdfile /root/rhds.pwd
--tls-cacertdir: When you use an LDAPS connection, the path set in this parameter defines the directory with the certificate authority (CA) certificate that is required to verify the server's certificate. For example: --tls-cacertdir /etc/pki/CA/certs/
Note that you must use the c_rehash /etc/pki/CA/certs/ command after you copied the CA certificate to the specified directory.
--tls-cert: Sets the absolute path to the server's certificate. For example: --tls-cert /etc/dirsrv/slapd-instance_name/Server-Cert.crt
--tls-key: Sets the absolute path to the server's private key. For example: --tls-key /etc/dirsrv/slapd-instance_name/Server-Cert.key
--tls-reqcert: Sets what checks the client utilities perform on server certificates in a TLS session. For example: --tls-reqcert hard
The following parameters are available:
- never: The utilities do not request or check the server certificate.
- allow: The utilities ignore certificate errors and the connection is established anyway.
- hard: The utilities terminate the connection on certificate errors.
--saslmech: Sets the SASL mechanism to use to PLAIN or EXTERNAL. For example: --saslmech PLAIN

1.11.3. Remote and Local Connection Resolution When Using Directory Server Utilities

When securing the Directory Server connection, it is important to distinguish between calling Directory Server commands remotely and locally.

When you run a Directory Server command with an LDAP URL specified, the server considers it as a remote connection and checks the /etc/openldap/ldap.conf configuration file along with system-wide settings to proceed with the command.

When you run a Directory Server command with an instance name specified, the server checks if the ~/.dsrc file is present and applies the following logic to proceed:

If the ~/.dsrc file exists and contains both the instance name and the LDAP URL, Directory Server considers it as a remote connection and checks /etc/openldap/ldap.conf configuration file and system-wide settings.
If the ~/.dsrc file exists and contains only the specified instance name, or if the ~/.dsrc file does not exist, Directory Server considers it as a local connection and uses the nsslapd-certdir setting from the local dse.ldif file to secure the connection. If nsslapd-certdir is not present, the server uses the default path /etc/dirsrv/slapd-instance_name/ to store the Network Security Services (NSS) database of the instance.

For more information about nsslapd-certdir parameter refer to nsslapd-certdir (Certificate and Key Database Directory) section.

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. The following is a simple directory tree:

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 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 stored in databases.

2.1.1.1. Creating a Root Suffix

A directory can contain more than one root suffix. For example, an internet service provider that hosts several websites, one for example.com and one for redhat.com. In this scenario, 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 displayed in the following diagram:

Figure 2.2. A Directory with Two Root Suffixes

It is also possible to create root suffixes to exclude portions of the directory tree from search operations. For example, if the Example Corporation wants to exclude their European office from a search on the general Example Corporation directory. To implement this, the directory requires 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, ou=europe,dc=example,dc=com. From a client application's perspective, the directory tree looks as illustrated the following diagram:

Figure 2.3. A Directory 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 ou=europe,dc=example,dc=com branch of the directory, as it is a separate root suffix.

2.1.1.1.1. Creating a Root Suffix Using the Command Line

Use the dsconf backend create command to create a new root suffix:

Optional: Identify the suffixes and back end databases that are already in use:
```
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list
dc=example,dc=com (userroot)
```
The name in parentheses is the back end database that stores the data of the corresponding suffix. You cannot use existing database names when you create the root suffix in the next step.

Create the dc=example,dc=net root suffix in the example back end database:

# dsconf -D "cn=Directory Manager" ldap://server.example.com backend create \
     --suffix="dc=example,dc=net" --be-name="example"

2.1.1.1.2. Creating a Root Suffix Using the Web Console

To create a new root suffix using the web console:

Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
Select the instance.
Open the Database menu.
Click Create Suffix.
Enter the suffix DN and back end name. For example:
Select Create The Top Suffix Entry.
Click Create Suffix.

2.1.1.2. Creating a Sub-suffix

In certain scenarios, administrators want to store a branch of the directory tree in a separate database. For example, if the administrator creates the ou=europe,dc=example,dc=com entry as a sub-suffix, this suffix is stored in a separate database. At the same time, the dc=example,com root suffix and all its sub-entries - except ou=europe,dc=example,dc=com and subentries - are stored also in a separate database.

Figure 2.4. A Directory Tree with a Sub Suffix

2.1.1.2.1. Creating a Sub-suffix Using the Command Line

Use the dsconf backend create command to create a new sub-suffix. For example, to create the ou=People,dc=example,dc=com sub-suffix in a new database called people under the dc=example,dc=com root suffix:

Optional: Identify the suffixes and back end databases that are already in use:
```
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list
dc=example,dc=com (userroot)
```
The name in parentheses is the back end database that stores the data of the corresponding suffix. You cannot use existing database names when you create the sub-suffix in the next step.

Create the sub-suffix. For example, to create the ou=People,dc=example,dc=com sub-suffix along with the example back end database, enter:

# dsconf -D "cn=Directory Manager" ldap://server.example.com backend create \
     --suffix="ou=People,dc=example,dc=com" --be-name="example" \
     --parent-suffix="dc=example,dc=com"

2.1.1.2.2. Creating a Sub-suffix Using the Web Console

To create a new sub-suffix using the web console:

Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
Select the instance.
Open the Database menu.
Select the suffix, under which you want to create the sub-suffix, click Suffix Tasks, and select Create Sub-Suffix.
Enter the sub-suffix DN and back end name. For example:
Select Create The Top Sub-Suffix Entry.
Click Create 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 and a configuration suffix in cn=config.

Many directory trees have multiple naming contexts to be used with different types of entries or with logical data divisions. Clients which access 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 is 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, pass the back end database name to the dsconf backend suffix set --disable command. For example, to disable the o=test suffix:

Display the suffixes and their corresponding back end:
```
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list
dc=example,dc=com (userroot)
o=test (test_database)
```
This command displays the name of the back end database next to each suffix. You require the suffix's database name in the next step.

Disable the suffix:

# dsconf -D "cn=Directory Manager" ldap://server.example.com backend \
     suffix set --disable "test_database"

2.1.2.3. Deleting a Suffix

If a suffix is no longer required, the administrator can 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, use the dsconf backend delete command. For example, to delete the o=test suffix:

Display the suffixes and their corresponding back end:
```
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list
dc=example,dc=com (userroot)
o=test (test_database)
```
This command displays the name of the back end database next to each suffix. You require the suffix's database name in the next step.

Delete the back end database and the corresponding suffix:

# dsconf -D "cn=Directory Manager" ldap://server.example.com backend delete test_database
Deleting Backend cn=test_database,cn=ldbm database,cn=plugins,cn=config :
Type 'Yes I am sure' to continue: Yes I am sure
The database, and any sub-suffixes, were successfully deleted

2.1.2.3.2. Deleting a Suffix Using the Web Console

To delete a suffix using the web console:

Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
Select the instance.
Open the Database menu.
Select the suffix, click Suffix Tasks, and select Delete Suffix.
Click Yes to confirm.

2.2. Creating and Maintaining Databases

After creating suffixes to organizing the directory data, create databases to contain data of that directory.

Note

If you used the dsconf utility or the web console to create the suffix, Directory Server created the database automatically.

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 a Single Suffix Using 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. To add a new database:

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.1.1, “Creating a Root Suffix Using the Command Line” and Section 2.1.1.2.1, “Creating a Sub-suffix 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.2. 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 web console and the command line interface.

To add a custom distribution function to a suffix:

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.

2.2.2. Maintaining Directory Databases

2.2.2.1. Setting 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 Directory Server. Read-only mode ensures a faithful image of the state of these databases at a given time.

The command-line utilities and the web console 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-supplier replication, this might not be a problem.

2.2.2.1.1. Setting a Database in Read-only Mode Using the Command Line

To set a database in read-only mode, use the dsconf backend suffix set command. For example, to set the database of the o=test suffix in read-only mode:

Display the suffixes and their corresponding back end:
```
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list
dc=example,dc=com (userroot)
o=test (test_database)
```
This command displays the name of the back end database next to each suffix. You require the suffix's database name in the next step.

Set the database in read-only mode:

# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix set --enable-readonly "test_database"

2.2.2.1.2. Setting a Database in Read-only Mode Using the Web Console

To set a database in read-only mode:

Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
Select the instance.
Open the Database menu.
Select the suffix entry.
Select Database Read-Only Mode.
Click Save Configuration.

2.2.2.2. Placing the Entire Directory Server in Read-Only Mode

If 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 Directory Server configuration read-only; therefore, you cannot update the server configuration, enable or disable plug-ins, or even restart Directory Server while it is in read-only mode. Once read-only mode is enabled, it cannot cannot be undone unless you manually modify the configuration files.

Note

If Directory Server contains replicas, do not use read-only mode because it will disable replication.

2.2.2.2.1. Placing the Entire Directory Server in Read-Only Mode Using the Command Line

To enable the read-only mode for Directory Server:

Set the nsslapd-readonly parameter to on:

# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-readonly=on

Restart the instance:
```
# dsctl instance_name restart
```

2.2.2.2.2. Placing the Entire Directory Server in Read-Only Mode Using the Web Console

To enable the read-only mode for Directory Server:

Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
Select the instance.
Open the Server Settings menu, and select the Server Settings entry.
On the Advanced Settings tab, select Server Read-Only.
Click Save.

2.2.2.3. Deleting a Database

If a suffix is no longer required, you can delete the database that stores the suffix.

2.2.2.3.1. Deleting a Database Using the Command Line

To delete a database use the dsconf backend delete command. For example, to delete the database of the o=test suffix:

Display the suffixes and their corresponding back end:
```
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list
dc=example,dc=com (userroot)
o=test (test_database)
```
You require the name of the back end database, which is displayed next to the suffix, in the next step.

Delete the database:

# dsconf -D "cn=Directory Manager" ldap://server.example.com backend delete "test_database"

2.2.2.3.2. Deleting a Database Using the Web Console

To delete a database using the web console:

Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
Select the instance.
Open the Database menu.
Select the suffix to delete, click Suffix Tasks, and select Delete Suffix.
Click Yes to confirm.

2.2.2.4. 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 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 Directory Server instance:
```
# dsctl instance_name stop
```
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:
```
# dsctl instance_name start
```

2.3. Creating and Maintaining Database Links

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

For more general information about chaining, see the chapter "Designing Directory Topology," in the Red Hat Directory Server Deployment Guide. Section 21.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 the following information:

Suffix information. A suffix is created in the directory tree that is managed by the database link, not a regular database. This suffix corresponds to the suffix on the remote server that contains the data.
Bind credentials. When the database link binds to a remote server, it impersonates a user, and this specifies the DN and the credentials for each database link to use to bind with remote servers.
LDAP URL. This supplies the LDAP URL of the remote server to which the database link connects. 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 20.12.1, “Requiring Secure Binds”), then any chaining operations will fail unless they occur over a secure connection. Using a secure connection (TLS and STARTTLS connections or SASL authentication) is recommended, anyway.

2.3.1.1. Creating a New Database Link Using the Command Line

To create a new database link, use the dsconf chaining link-create command. For example:

# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining link-create --suffix="ou=Customers,dc=example,dc=com" --server-url="ldap://remote_server.example.com:389" --bind-mech="" --bind-dn="cn=proxy_user,cn=config" --bind-pw="password" "example_chain_name"

This creates a database link named example_chain_name for the ou=Customers,dc=example,dc=com. The link refers to the server ldap://remote_server.example.com:389 and uses the specified bind DN and password to authenticate. Because the --bind-mech is set empty, the link uses simple authentication.

Note

To grant the proxy_user the rights to access data, you must create the proxy ACI entry in the dc=example,dc=com suffix on remote server. How to do so, refer to the section Section 2.3.1.4, “Additional Information on Required Settings When Creating a Database Link”

To display additional settings you can set when you create the database link, see:

# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining link-create --help

For further details, see Section 2.3.1.4, “Additional Information on Required Settings When Creating a Database Link”.

2.3.1.2. Creating a New Database Link Using the Web Console

To create a new database link:

Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
Select the instance.
Open the Database menu.
Create a new suffix as described in Section 2.1.1, “Creating Suffixes”.
Select the suffix, click Suffix Tasks, and select Create Database Link.
Fill the fields with the details about the connection to the remote server. For example:
For further details, see Section 2.3.1.4, “Additional Information on Required Settings When Creating a Database Link”.
Click Create Database Link.

2.3.1.3. Managing the Default Configuration for New Database Links

With the dsconf chaining command you can manage the default configuration of database links.

To display the current default values, see:

# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining config-get-def

To change new database links configuration, use dsconf chaining config-set-def command. For example, to set response-delay parameter to 30, run:

# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining config-set-def --response-delay 30

The example command sets the default response timeout for all chaining connections. You can overwrite the response timeout for a specific chaining link if you use dsconf instance chaining link-set command.

To see the list of all parameters you can set, run:

# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining config-set-def --help

2.3.1.4. Additional Information on Required Settings When Creating a Database Link

Suffix Information

The suffix defines the suffix that is managed by the database link.

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.

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 and password:

Server B must contain a user entry 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.

Providing bind credentials involves the following steps on the remote server:

Create an administrative user, such as cn=proxy_user,cn=config, 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 the previous step on the subtree chained to by the database link. For more information on configuring ACIs, see Chapter 18, Managing Access Control
For example, the following ACI grants read-only access to the cn=proxy_admin,cn=config user to access data contained on the remote server only within the subtree where the ACI is set.
```
aci: (targetattr = "*")(version 3.0; acl "Proxied authorization
     for database links"; allow (proxy) userdn = "ldap:///cn=proxy_admin
     ,cn=config";)
```

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.3, “Database Links and Access Control Evaluation”.

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://host_name:port.

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

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.

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 STARTTLS, which is a secure connection over a standard port

Note

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 a bind DN and password.
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.10, “Setting up SASL Identity Mapping”.

Note

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

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

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