Administration Guide

Red Hat Directory Server 11

Basic and advanced administration of Directory Server

Marc Muehlfeld

Red Hat Customer Content Services

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

Abstract

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

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

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
  • LDAP Data Interchange Format (LDIF) statements sent to the server through an LDAP client

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:
  1. 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
  2. Log in as the root user or as a user with sudo privileges.
  3. Select the 389 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 dirsrv 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

Except the command line, you can use the web console to start, stop, or restart instances.
To start, stop, or restart a Directory Server instance:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. 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/ directory is removed.

    Important

    The /var/lib/dirsrv/slapd-instance_name/ directory contains the database, as well as the backup and export directory. Before you remove an instance, backup this data.
  • The /etc/dirsrv/slapd-instance_name/ directory is renamed to /etc/dirsrv/slapd-instance_name.removed/.

1.7.1. Removing an Instance Using the Command Line

To remove an instance using the command line:
# dsctl instance_name remove --do-it

About to remove instance instance_name!
If this is not what you want, press ctrl-c now ...

4 ...
3 ...
2 ...
1 ...
0 ...
Removing instance ...
Removed /etc/systemd/system/multi-user.target.wants/dirsrv@instance_name.service.
Completed instance removal

1.7.2. Removing an Instance Using the Web Console

To remove an instance using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. 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
Note that you cannot delete certain parameters, such as nsslapd-secureport to reset them to their default. If you try to delete them, the server rejects the request with a Server is unwilling to perform (53) error.

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

Changing the port numbers from the command line requires to update the corresponding parameter of the instance's configuration. The following parameters define the port numbers in Directory Server:
  • 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:
  1. 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
  2. To change the LDAP port:
    1. 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"
    2. 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
  3. To change the LDAPS port:
    1. 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"
    2. 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
  4. 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:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. To change the LDAP port:
    1. Open the Server Settings menu, and select the Server Configuration entry.
    2. Fill the new port number into the Server Port field.
    3. Click Save.
  4. To change the LDAPS port:
    1. Open the Security menu, and select the Security Settings entry.
    2. Fill the new port number into the Server Secure Port field.
    3. Click Save.

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 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:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select the Plugins menu.
Optionally, you can filter the plug-ins by entering a name into the Search Plugins field.

1.10.2. Enabling Plug-ins Dynamically

By default, after enabling or disabling a plug-in, restart the instance to take effect.
If you set the nsslapd-dynamic-plugins parameter to on, you do not have to restart the instance after making the following changes:
  • Enabling a plug-in
  • Disabling a plug-in
  • Changing the configuration of a plug-in
To enable this feature:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-dynamic-plugins=on
Successfully replaced "nsslapd-dynamic-plugins"

1.10.3. Enabling and Disabling Plug-ins

1.10.3.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 Attribute Uniqueness plug-in:
  1. Enable the plug-in:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin set "attribute uniqueness" --enabled=on
    Successfully changed the cn=attribute uniqueness,cn=plugins,cn=config
    ...
  2. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

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

To enable or disable a plug-in using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select the Plugins menu.
  4. Select the All Plugins tab.
  5. Click the Edit Plugin button to the right of the plug-in you want to enable or disable.
  6. Change the status to ON to enable or to OFF to disable the plug-in.
  7. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

1.10.4. Configuring Plug-ins

1.10.4.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.4.2. Configuring Plug-ins Using the Web Console

To configure a plug-in using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select the Plugins menu.
  4. Select the All Plugins tab.
  5. Select the plug-in and click Show Advanced Settings.
  6. Open the plug-in-specific tab.
  7. Set the appropriate settings.
  8. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

1.10.5. 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.5.1. Setting the Plug-in Precedence Using the Command Line

To update the precedence value of a plug-in using the command line:
  1. 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
  2. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

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

To update the precedence value of a plug-in using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select All Plugins.
  5. Press the Edit Plugin button next to the plug-in for which you want to configure the precedence value.
  6. Update the value in the Precedence field.
  7. Click Save.
  8. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

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:
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 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:
A Directory with Two Root Suffixes

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, l=europe,dc=example,dc=com. From a client application's perspective, the directory tree looks as illustrated the following diagram:
A Directory with a Root Suffix Off Limits to Search Operations

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 l=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. For example, to create the dc=example,dc=com suffix in a new database called example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend create \
     --suffix="dc=example,dc=com" --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:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Database menu.
  4. Click Create Suffix.
  5. Enter the suffix DN and back end name. For example:
  6. 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 l=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 l=europe,dc=example,dc=com and subentries - are stored also in a separate database.
A Directory Tree with a Sub Suffix

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:
# 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:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Database menu.
  4. Select the suffix, under which you want to create the sub-suffix, click Suffix Tasks, and select Create Sub-Suffix.
  5. Enter the sub-suffix DN and back end name. For example:
  6. 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:
  1. 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.
  2. 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:
  1. 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.
  2. 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:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Database menu.
  4. Select the suffix, click Suffix Tasks, and select Delete Suffix.
  5. 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. For example, add a new database to the server example1:
  1. Run ldapmodify and create the entry for the new database.
    # ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    
    dn: cn=UserData,cn=ldbm database,cn=plugins,cn=config
    changetype: add
    objectclass: extensibleObject
    objectclass: nsBackendInstance
    nsslapd-suffix: ou=people,dc=example,dc=com
    The added entry corresponds to a database named UserData that contains the data for the root or sub-suffix ou=people,dc=example,dc=com.
  2. Create a root or 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:
  1. Run ldapmodify.
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
  2. Add the following attributes to the suffix entry itself, supplying the information about the custom distribution logic:
    dn: suffix
    changetype: modify
    add: nsslapd-backend
    nsslapd-backend: Database1
    -
    add: nsslapd-backend
    nsslapd-backend: Database2
    -
    add: nsslapd-backend
    nsslapd-backend: Database3
    -
    add: nsslapd-distribution-plugin
    nsslapd-distribution-plugin: /full/name/of/a/shared/library
    -
    add: nsslapd-distribution-funct
    nsslapd-distribution-funct: distribution-function-name
    The nsslapd-backend attribute specifies all 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-master 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:
  1. 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.
  2. 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:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Database menu.
  4. Select the suffix entry.
  5. Select Database Read-Only Mode.
  6. 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:
  1. Set the nsslapd-readonly parameter to off:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-readonly=off
  2. 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:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Server Settings menu.
  4. Click Show Advanced Settings.
  5. Select Server Read-Only.
  6. 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:
  1. 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.
  2. 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:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Database menu.
  4. Select the suffix to delete, click Suffix Tasks, and select Delete Suffix.
  5. 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:
  1. Stop Directory Server instance:
    # dsctl instance_name stop
  2. Create a new location for the transaction logs. For example:
    # mkdir -p /srv/dirsrv/instance_name/db/
  3. 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/
  4. Remove all __db.* files from the previous transaction log directory. For example:
    # rm /var/lib/dirsrv/slapd-instance_name/db/__db.*
  5. 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/
  6. 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/
  7. 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/
  8. Start the instance:
    # dsctl instance_name start

2.5. Using Referrals

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

2.5.1. Starting the Server in Referral Mode

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

2.5.2. Setting Default Referrals

Directory Server returns default referrals to client applications that submit operations on a DN not contained within any of the suffixes maintained by the directory. The following procedures describe setting a default referral for the directory using the command line.

2.5.2.1. Setting a Default Referral Using the Command Line

Use the dsconf config replace command, to set the default referral in the nsslapd-referral parameter. For example, to set ldap://directory.example.com/ as the default referral:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-referral="ldap://directory.example.com/"

2.5.3. Creating Smart Referrals

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

2.5.3.1. Creating Smart Referrals Using the Command Line

To create a smart referral, create the relevant directory entry with the referral object class and set the ref attribute to the referral LDAP URL.
For example, to create a smart referral named uid=user,ou=people,dc=example,dc=com that refers to ldap://directory.europe.example.com/cn=user,ou=people,l=europe,dc=example,dc=com:
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server2.example.com -x
dn: uid=user,ou=people,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
objectclass: referral
sn: user
uid: user
cn: user
ref: ldap://directory.europe.example.com/cn=user,ou=people,l=europe,dc=example,dc=com

Note

Directory Server ignores any information after a space in an LDAP URL. For this reason, use %20 instead of spaces in LDAP URLs used as a referral.
Use the -M option with ldapadd if there is already a referral in the DN path. For more information on smart referrals, see the Directory Server Deployment Guide.

2.5.4. Creating Suffix Referrals

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

Warning

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

2.5.4.1. Creating Suffix Referrals Using the Command Line

To create a suffix referral:
  1. Optionally, create a root or sub-suffix, if it does not already exist. For details, see Section 2.1.1, “Creating Suffixes”.
  2. Add the referral to the suffix. For example:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com suffix set --add-referral="ldap://directory.example.com/"

2.5.4.2. Creating Suffix Referrals Using the Web Console

To create a suffix referral:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Database menu.
  4. Optionally, create a root or sub-suffix, if it does not already exist. For details, see Section 2.1.1, “Creating Suffixes”.
  5. Select the suffix in the list, and open the Referrals tab.
  6. Click Create Referral.
  7. Fill the fields to create the referral URL.
  8. Click Create Referral.

Chapter 3. Managing Directory Entries

This chapter discusses how to use command line utilities, such as ldapmodify, to manage entries in Directory Server.
To perform LDAP operations using the command line, install the openldap-clients package. The utilities installed by this package enable you to:
  • Add new entries
  • Add new attributes to existing entries
  • Update existing entries and attributes
  • Delete entries and attributes from entries
  • Perform bulk operations
To install the openldap-clients package:
# dnf install openldap-clients

Note

To perform LDAP operations, you need the appropriate permissions. For details about access control, see Chapter 18, Managing Access Control.

3.1. Providing Input to the ldapadd, ldapmodify, and ldapdelete Utilities

When you add, update, or delete entries or attributes in your directory, you can either use the interactive mode of the utilities to enter LDAP Data Interchange Format (LDIF) statements or pass an LDIF file to them.
For further details about LDIF, see Section B.1, “About the LDIF File Format”.

3.1.1. Providing Input Using the Interactive Mode

In the interactive mode, the ldapadd, ldapmodify, and ldapdelete utilities read the input from the command line. To exit the interactive mode, press the Ctrl+D (^D) key combination to send the End Of File (EOF) escape sequence.
In interactive mode, the utility sends the statements to the LDAP server when you press Enter twice or when you send the EOF sequence.
Use the interactive mode:
  • To enter LDIF statements without creating a file:

    Example 3.1. Using the ldapmodify Interactive Mode to Enter LDIF Statements

    The following example starts ldapmodify in interactive mode, deletes the telephoneNumber attribute, and adds the manager attribute with the cn=manager_name,ou=people,dc=example,dc=com value to the uid=user,ou=people,dc=example,dc=com entry. Press Ctrl+D after the last statement to exit the interactive mode.
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    
    dn: uid=user,ou=people,dc=example,dc=com
    changetype: modify
    delete: telephoneNumber
    -
    add: manager
    manager: cn=manager_name,ou=people,dc=example,dc=com
    ^D
  • To redirect LDIF statements, outputted by another command, to Directory Server:

    Example 3.2. Using the ldapmodify Interactive Mode with Redirected Content

    The following example redirects the output of the command_that_outputs_LDIF command to ldapmodify. The interactive mode exits automatically after the redirected command exits.
    # command_that_outputs_LDIF | ldapmodify -D "cn=Directory Manager" \
         -W -p 389 -h server.example.com -x

3.1.2. Providing Input Using an LDIF File

In the interactive mode, the ldapadd, ldapmodify, and ldapdelete utilities read the LDIF statements from a file. Use this mode to send a larger number of LDIF statements to Directory Server.

Example 3.3. Passing a File with LDIF Statements to ldapmodify

  1. Create a file with the LDIF statements. For example, create the ~/example.ldif file with the following statements:
    dn: uid=user,ou=people,dc=example,dc=com
    changetype: modify
    delete: telephoneNumber
    -
    add: manager
    manager: cn=manager_name,ou=people,dc=example,dc=com
    This example deletes the telephoneNumber attribute and to adds the manager attribute with the cn=manager_name,ou=people,dc=example,dc=com value to the uid=user,ou=people,dc=example,dc=com entry
  2. Pass the file to the ldapmodify command using the -f file_name option:
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x \
         -f ~/example.ldif

3.2. The Continuous Operation Mode

If you send multiple LDIF statements to Directory Server and one operation fails, the process stops. However, entries processed before the error occurred were successfully added, modified, or deleted.
To ignore errors and continue processing further LDIF statements in a batch, pass the -c option to ldapadd and ldapmodify. For example:
# ldpamodify -c -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

3.3. Adding an Entry

To add a new entry to the directory, use the ldapadd or ldapmodify utility. Note that ldapadd is a symbolic link to /bin/ldapmodify. Therefore, ldapadd performs the same operation as ldapmodify -a.

Note

You can only add a new directory entry, if the parent entry already exists. For example, you cannot add the cn=user,ou=people,dc=example,dc=com entry, if the ou=people,dc=example,dc=com parent entry does not exist.

3.3.1. Adding an Entry Using ldapadd

To use the ldapadd utility to add, for example, the cn=user,ou=people,dc=example,dc=com user entry:
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: uid=user,ou=People,dc=example,dc=com
uid: user
givenName: given_name
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
sn: surname
cn: user

Note

Running ldapadd automatically performs a changetype: add operation. Therefore, you do not need to specify changetype: add in the LDIF statement.
For further details on the parameters used in the command, see the ldapadd(1) man page.

3.3.2. Adding an Entry Using ldapmodify

To use the ldapmodify utility to add, for example, the cn=user,ou=people,dc=example,dc=com user entry:
# ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: uid=user,ou=People,dc=example,dc=com
uid: user
givenName: given_name
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
sn: surname
cn: user

Note

When passing the -a option to the ldapmodify command, the utility automatically performs a changetype: add operation. Therefore, you do not need to specify changetype: add in the LDIF statement.
For further details on the parameters used in the command, see the ldapmodify(1) man page.

3.3.3. Creating a Root Entry

To create the root entry of a database suffix, such as dc=example,dc=com, bind as the cn=Directory Manager user and add the entry.
The DN corresponds to the DN of the root or sub-suffix of the database.
For example, to add the dc=example,dc=com suffix:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: dc=example,dc=com
changetype: add
objectClass: top
objectClass: domain
dc: example

Note

You can add root objects only if you have one database per suffix. If you create a suffix that is stored in several databases, you must use the ldif2db utility with the -n back_end option to set the database that will hold the new entries. For details, see Section 6.1.2, “Importing Using the Command Line”.

3.4. Updating a Directory Entry

When you modify a directory entry, use the changetype: modify statement. Depending on the change operation, you can add, change, or delete attributes from the entry.
Use the ldapmodify utility to send the LDIF statements to Directory Server. For example, in interactive mode:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
For further details on the parameters used in ldapmodify commands, see the ldapmodify(1) man page.

3.4.1. Adding Attributes to an Entry

To add an attribute to an entry, use the add operation.
For example, to add the telephoneNumber attribute with the 555-1234567 value to the uid=user,dc=people,dc=example,dc=com entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: uid=user,dc=people,dc=example,dc=com
changetype: modify
add: telephoneNumber
telephoneNumber: 555-1234567
If an attribute is multi-valued, you can specify the attribute name multiple times to add all the values in a single operation. For example, to add two telephoneNumber attributes at once to the uid=user,dc=people,dc=example,dc=com:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: uid=user,dc=people,dc=example,dc=com
changetype: modify
add: telephoneNumber
telephoneNumber: 555-1234567
telephoneNumber: 555-7654321

3.4.2. Updating an Attribute's Value

The procedure for updating an attribute's value depends on if the attribute is single-valued or multi-valued.

Updating a Single-value Attribute

When updating a single-value attribute, use the replace operation to override the existing value. The following command updates the manager attribute of the uid=user,dc=people,dc=example,dc=com entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: uid=user,dc=people,dc=example,dc=com
changetype: modify
replace: manager
manager: uid=manager_name,dc=people,dc=example,dc=com

Updating a Specific Value of a Multi-value Attribute

To update a specific value of a multi-value attribute, you must first delete the entry you want to replace, and then add the new value. The following command updates only the telephoneNumber attribute that is currently set to 555-1234567 in the uid=user,dc=people,dc=example,dc=com entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: uid=user,dc=people,dc=example,dc=com
changetype: modify
delete: telephoneNumber
telephoneNumber: 555-1234567
-
add: telephoneNumber
telephoneNumber: 555-9876543

3.4.3. Deleting Attributes from an Entry

To delete an attribute from an entry, use the delete operation.

Deleting an Attribute

For example, to delete the manager attribute from the uid=user,dc=people,dc=example,dc=com entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: uid=user,dc=people,dc=example,dc=com
changetype: modify
delete: manager

Note

If the attribute contains multiple values, this operation deletes all of them.

Deleting a Specific Value of a Multi-value Attribute

If you want to delete a specific value from a multi-value attribute, list the attribute and its value in the LDIF statement. For example, to delete only the telephoneNumber attribute that is set to 555-1234567 from the uid=user,dc=people,dc=example,dc=com entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: uid=user,dc=people,dc=example,dc=com
changetype: modify
delete: telephoneNumber
telephoneNumber: 555-1234567

3.5. Deleting an Entry

Deleting an entry removes the entry from the directory.

Note

You can only delete entries that have no child entries. For example, you cannot delete the ou=People,dc=example,dc=com entry, if the uid=user,ou=People,dc=example,dc=com entry still exists.

3.5.1. Deleting an Entry Using ldapdelete

The ldapdelete utility enables you to delete one or multiple entries. For example, to delete the uid=user,ou=People,dc=example,dc=com entry:
# ldapdelete -D "cn=Directory Manager" -W -p 389 -h server.example.com -x "uid=user,ou=People,dc=example,dc=com"
To delete multiple entries in one operation, append them to the command. For example:
# ldapdelete -D "cn=Directory Manager" -W -p 389 -h server.example.com -x \
     "uid=user1,ou=People,dc=example,dc=com" \
     "uid=user2,ou=People,dc=example,dc=com"
For further details on the parameters used, see the ldapdelete(1) man page.

3.5.2. Deleting an Entry Using ldapmodify

To delete an entry using the ldapmodify utility, use the changetype: delete operation. For example, to delete the uid=user,ou=People,dc=example,dc=com entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: uid=user,dc=people,dc=example,dc=com
changetype: delete

3.6. Renaming and Moving an Entry

Use the ldapmodify utility to send the LDIF statements to Directory Server when you rename an entry. For example, in interactive mode:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
For further details on the parameters used in ldapmodify commands, see the ldapmodify(1) man page.

Note

Use the moddn Access Control List (ACL) to grant permissions to move entries. For details, see Section 18.8.2.1, “Targeting Source and Destination DNs”.

3.6.1. Types of Rename Operations

The following rename operations exist:
Renaming an Entry
If you rename a entry, the modrdn operation changes the Relative Distinguished Name (RDN) of the entry:
Renaming a Subentry
For subtree entries, the modrdn operation renames the subtree and also the DN components of child entries:
Note that for large subtrees, this process can take a lot of time and resources.
Moving an Entry to a New Parent
A similar action to renaming a subtree is moving an entry from one subtree to another. This is an expanded type of the modrdn operation, which simultaneously renames the entry and sets a newSuperior attribute which moves the entry from one parent to another:

3.6.2. Considerations for Renaming Entries

Keep the following in mind when performing rename operations:
  • You cannot rename the root suffix.
  • Subtree rename operations have minimal effect on replication. Replication agreements are applied to an entire database, not a subtree within the database. Therefore, a subtree rename operation does not require reconfiguring a replication agreement. All name changes after a subtree rename operation are replicated as normal.
  • Renaming a subtree might require any synchronization agreements to be reconfigured. Synchronization agreements are set at the suffix or subtree level. Therefore, renaming a subtree might break synchronization.
  • Renaming a subtree requires that any subtree-level Access Control Instructions (ACI) set for the subtree be reconfigured manually, as well as any entry-level ACIs set for child entries of the subtree.
  • Trying to change the component of a subtree, such as moving from ou to dc, might fail with a schema violation. For example, the organizationalUnit object class requires the ou attribute. If that attribute is removed as part of renaming the subtree, the operation fails.
  • If you move a group, the MemberOf plug-in automatically updates the memberOf attributes. However, if you move a subtree that contain groups, you must manually create a task in the cn=memberof task entry or use the fixup-memberof.pl to update the related memberOf attributes.
    For details about cleaning up memberOf attribute references, see Section 8.1.4.8, “Regenerating memberOf Values”.

3.6.3. The deleteOldRDN Parameter

When you rename an entry, the deleteOldRDN parameter controls whether the old RDN will be deleted or retained.
deleteOldRDN: 0
The existing RDN is retained as a value in the new entry. The resulting entry contains two cn attributes: one with the old and one with the new common name (CN).
For example, the following attributes belong to a group that was renamed from cn=old_group,dc=example,dc=com to cn=new_group,dc=example,dc=com with the deleteOldRDN: 0 parameter set.
dn: cn=new_group,ou=Groups,dc=example,dc=com
objectClass: top
objectClass: groupOfUniqueNames
cn: old_group
cn: new_group
deleteOldRDN: 1
Directory Server deletes the old entry and creates a new entry using the new RDN. The new entry only contains the cn attribute of the new entry.
For example, the following group was renamed to cn=new_group,dc=example,dc=com with the deleteOldRDN: 1 parameter set:
dn: cn=new_group,ou=Groups,dc=example,dc=com
objectClass: top
objectClass: groupofuniquenames
cn: new_group

3.6.4. Renaming an Entry or Subtree

To rename an entry or subtree, use the changetype: modrdn operation and set the new RDN in the newrdn attribute.
For example, to rename the cn=old_group,ou=Groups,dc=example,dc=com entry to cn=new_group,ou=Groups,dc=example,dc=com:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=old_group,ou=Groups,dc=example,dc=com
changetype: modrdn
newrdn: cn=new_group
deleteOldRDN: 1
For details about the deleteOldRDN, see Section 3.6.3, “The deleteOldRDN Parameter”.

3.6.5. Moving an Entry to a New Parent

To move an entry to a new parent, use the changetype: modrdn operation and set the following to attributes:
newrdn
Sets the RDN of the moved entry. You must set this entry, even if the RDN remains the same.
newSuperior
Sets the DN of the new parent entry.
For example, to move the uid=user entry from ou=Engineering,ou=People,dc=example,dc=com to ou=Marketing,ou=People,dc=example,dc=com:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: uid=user,ou=Engineering,ou=People,dc=example,dc=com
changetype: modrdn
newrdn: uid=user
newSuperior= ou=Marketing,ou=People,dc=example,dc=com
deleteOldRDN: 1
For details about the deleteOldRDN, see Section 3.6.3, “The deleteOldRDN Parameter”.

3.7. Using Special Characters

When using the command line, enclose characters that have a special meaning to the command-line interpreter, such as space ( ), asterisk (*), or backslash (\), with quotation marks. Depending on the command-line interpreter, use single or double quotation marks.
For example, to authenticate as the cn=Directory Manager user, enclose the user's DN in quotation marks:
# ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
Additionally, if a DN contains a comma in a component, escape it using a backslash. For example, to authenticate as the uid=user,ou=People,dc=example.com Chicago, IL user:
# ldapmodify -a -D "cn=uid=user,ou=People,dc=example.com Chicago\, IL" \
     -W -p 389 -h server.example.com -x

3.8. Using Binary Attributes

Certain attributes support binary values, such as the jpegPhoto attribute. When you add or update such an attribute, the utility reads the value for the attribute from a file. To add or update such an attribute, you can use the -b binary option of the ldapadd or ldapmodify utility, or the standard LDIF notation.
For example, to add the jpegPhoto attribute to the uid=user,ou=People,dc=example,dc=com entry, and read the value for the attribute from the ~/photo.jpg file:
  • Using the binary option: Pass the -b option to the command, and set the binary attribute to the path of the file:
    # ldapmodify -b -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    
    dn: uid=user,ou=People,dc=example,dc=com
    changetype: modify
    add: jpegPhoto
    jpegPhoto: ~/photo.jpg
  • Using standard LDIF notation: Set the attribute's value to the path of the file using the < file:path_to_file syntax:
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    
    dn: uid=user,ou=People,dc=example,dc=com
    changetype: modify
    add: jpegPhoto
    jpegPhoto: < ~/photo.jpg

3.9. Updating an Entry in an Internationalized Directory

To use attribute values with languages other than English, associate the attribute's value with a language tag.
When using ldapmodify to update an attribute that has a language tag set, you must match the value and language tag exactly or the operation will fail.
For example, to modify an attribute value that has the lang-fr language tag set, include the tag in the modify operation:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: uid=user,ou=People,dc=example,dc=com
changetype: modify
replace: homePostalAddress;lang-fr
homePostalAddress;lang-fr: 34 rue de Seine

Chapter 4. Tracking Modifications to Directory Entries

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

Note

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

4.1. Tracking Modifications to the Database through Update Sequence Numbers

The USN Plug-in enables LDAP clients and servers to identify if entries have been changed.

4.1.1. An Overview of the Entry Sequence Numbers

When the USN Plug-in is enabled, update sequence numbers (USNs) are sequential numbers that are assigned to an entry whenever a write operation is performed against the entry. (Write operations include add, modify, modrdn, and delete operations. Internal database operations, like export operations, are not counted in the update sequence.) A USN counter keeps track of the most recently assigned USN.

4.1.1.1. Local and Global USNs

The USN is evaluated globally, for the entire database, not for the single entry. The USN is similar to the change sequence number for replication and synchronization, in that it simply ticks upward to track any changes in the database or directory. However, the entry USN is maintained separately from the CSNs, and USNs are not replicated.
The entry shows the change number for the last modification to that entry in the entryUSN operational attribute. For further details about operational attributes, see Section 14.3.7, “Searching for Operational Attributes”.

Example 4.1. Example Entry USN

To display the entryusn attribute of the uid=example,ou=People,dc=example,dc=com user entry:
# ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com:389 -x -b "uid=example,ou=People,dc=example,dc=com" -s base -x entryusn

dn: uid=example,ou=People,dc=example,dc=com
entryusn: 17653
The USN Plug-in has two modes, local mode and global mode:
  • In local mode, each back end database has an instance of the USN Plug-in with a USN counter specific to that back end database. This is the default setting.
  • In global mode, there is a global instance of the USN Plug-in with a global USN counter that applies to changes made to the entire directory.
When the USN Plug-in is set to local mode, results are limited to the local back end database. When the USN Plug-in is set to global mode, the returned results are for the entire directory.
The root DSE shows the most recent USN assigned to any entry in the database in the lastusn attribute. When the USN Plug-in is set to local mode, so each database has its own local USN counter, the lastUSN shows both the database which assigned the USN and the USN:
lastusn;database_name:USN
For example:
lastusn;example1: 2130
lastusn;example2: 2070
In global mode, when the database uses a shared USN counter, the lastUSN attribute shows the latest USN only:
lastusn: 4200

4.1.1.2. Importing USN Entries

When entries are imported, the USN Plug-in uses the nsslapd-entryusn-import-initval attribute to check if the entry has an assigned USN. If the value of nsslapd-entryusn-import-initval is numerical, the imported entry will use this numerical value as the entry's USN. If the value of nsslapd-entryusn-import-initval is not numerical, the USN Plug-in will use the value of the lastUSN attribute and increment it by one as the USN for the imported entry.

4.1.2. Enabling the USN Plug-in

This section describes how to enable the USN plug-in to record USNs on entries.

4.1.2.1. Enabling the USN Plug-in Using the Command Line

To enable the USN plug-in using the command line:
  1. Use the dsconf utility to enable the plug-in:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin usn enable
  2. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

4.1.2.2. Enabling the USN Plug-in Using the Web Console

To enable the USN plug-in using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select the Plugins menu.
  4. Select the USN plug-in.
  5. Change the status to ON to enable the plug-in.
  6. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

4.1.3. Global USNs

With the default settings, Directory Server uses unique update sequence numbers (USN) for each back end database. Alternatively, you can enable unique USNs across all back end databases.

Note

The USN plug-in must be enabled to use this feature. See Section 4.1.2, “Enabling the USN Plug-in”.

4.1.3.1. Identifying Whether Global USNs are Enabled

This section describes how to identify whether USNs are enabled across all back end databases.
4.1.3.1.1. Identifying Whether Global USNs are Enabled Using the Command Line
To display the current status of the global USN feature using the command line:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin usn global
USN global mode is disabled
4.1.3.1.2. Identifying Whether Global USNs are Enabled Using the Web Console
To display the current status of the global USN feature using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Click Show Advanced Settings.
  4. The Enable Unique USNs Across All Backends entry indicates whether this feature is enabled.

4.1.3.2. Enabling Global USNs

4.1.3.2.1. Enabling Global USNs Using the Command Line
To enable global USNs using the command line:
  1. Enable global USNs:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin usn global on
  2. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.
4.1.3.2.2. Enabling Global USNs Using the Web Console
To enable global USNs using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select the USN plug-in.
  5. Change the status of the plug-in to On.
  6. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

4.1.4. Cleaning up USN Tombstone Entries

The USN plug-in moves entries to tombstone entries when the entry is deleted. If replication is enabled, then separate tombstone entries are kept by both the USN and Replication plug-ins. Both tombstone entries are deleted by the replication process, but for server performance, it can be beneficial to delete the USN tombstones:
  • before converting a server to a replica
  • to free memory for the server

4.1.4.1. Cleaning up USN Tombstone Entries Using the Command Line

To remove all USN tombstone entries from the dc=example,dc=com suffix using the command line:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin usn cleanup -s "dc=example,dc=com"
Optionally, pass the -o max_USN option to the command to delete USN tombstone entries up to the specified value.

4.1.4.2. Cleaning up USN Tombstone Entries Using the Web Console

To remove all USN tombstone entries from the dc=example,dc=com suffix using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select the USN plug-in.
  5. Press the Run Fixup Task button.
  6. Fill the fields, and press Run.

4.2. Tracking Entry Modifications through Operational Attributes

Using the default settings, Directory Server tracks the following operational attributes for every entry:
  • creatorsName: The distinguished name (DN) of the user who initially created the entry.
  • createTimestamp: The times stamp in Greenwich Mean Time (GMT) format when the entry was created.
  • modifiersName: The distinguished name of the user who last modified the entry.
  • modifyTimestamp: The time stamp in the GMT format for when the entry was last modified.
Note that operational attributes are not returned in default searches. You must explicitly request these attributes in queries. For details, see Section 14.3.7, “Searching for Operational Attributes”.

Important

Red Hat recommends not disabling tracking these operational attributes. If disabled, entries do not get a unique ID assigned in the nsUniqueID attribute and replication does not work.

4.2.2. Enabling Tracking of Modifications

By default, Directory Server tracks modifications in operational attributes.

Note

Red Hat recommends not disabling this feature.
This section describes how to re-enable tracking of modifications in case that you disabled the feature.

4.2.2.1. Enabling Tracking Of Modifications Using the Command Line

To re-enable tracking of entry modifications using the command line:
  1. Set the nsslapd-lastmod parameter to on:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-lastmod=on
  2. Optionally, to regenerate the missing nsUniqueID attributes:
    1. Export the database into an LDAP Data Interchange Format (LDIF) file. See Section 6.2.1, “Exporting Data into an LDIF File Using the Command Line”.
    2. Import the database from the LDIF file. See Section 6.1.2, “Importing Using the Command Line”.

4.3. Tracking the Bind DN for Plug-in Initiated Updates

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

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

Note

The internalModifiersname and internalCreatorsname attributes always show a plug-in as the identity. This plug-in could be an additional plug-in, such as the MemberOf Plug-in. If the change is made by the core Directory Server, then the plug-in is the database plug-in, cn=ldbm database,cn=plugins,cn=config.

4.3.1. Enabling Tracking the Bind DN for Plug-in Initiated Updates Using the Command Line

To enable tracking the Bind DN for plug-in-initiated updates using the command line:
  1. Set the nsslapd-plugin-binddn-tracking parameter to on:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-plugin-binddn-tracking=on
  2. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

4.3.2. Enabling Tracking the Bind DN for Plug-in Initiated Updates Using the Web Console

To enable tracking the Bind DN for plug-in-initiated updates using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Click Show Advanced Settings.
  4. Select Enable Plugin Bind DN Tracking.
  5. Click Save.
  6. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

4.4. Tracking Password Change Times

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

Chapter 5. Maintaining Referential Integrity

Referential Integrity is a database mechanism that ensures relationships between related entries are maintained. In the Directory Server, the Referential Integrity can be used to ensure that an update to one entry in the directory is correctly reflected in any other entries that reference to the updated entry.
For example, if a user's entry is removed from the directory and Referential Integrity is enabled, the server also removes the user from any groups of which the user is a member. If Referential Integrity is not enabled, the user remains a member of the group until manually removed by the administrator. This is an important feature if you are integrating the Directory Server with other products that rely on the directory for user and group management.

5.1. How Referential Integrity Works

When the Referential Integrity Postoperation plug-in is enabled, it performs integrity updates on specified attributes immediately after a delete or rename operation. By default, the Referential Integrity Postoperation plug-in is disabled.

Note

Enable the Referential Integrity Postoperation plug-in only on one supplier replica in a multi-master replication environment, because the operations generated by the plug-in will be replicated. If you enable the plug-in on multiple masters, the servers have to manage and reapply already performed operations.
When a user or group entry is deleted, updated, renamed, or moved within the directory, the operation is logged to the Referential Integrity log file. For the distinguished names (DN) in the log file, Directory Server searches and updates in intervals the attributes set in the plug-in configuration:
  • For entries, marked in the log file as deleted, the corresponding attribute in the directory is deleted.
  • For entries, marked in the log file as updated, the corresponding attribute in the directory is updated.
  • For entries, marked in the log file as renamed or moved, the value of the corresponding attribute in the directory is renamed.
By default, when the Referential Integrity Postoperationplug-in is enabled, it performs integrity updates on the member, uniquemember, owner, and seeAlso attributes immediately after a delete or rename operation. However, the behavior of the Referential Integrity Postoperation plug-in can be configured to suit the needs of the directory in several different ways:
  • Record Referential Integrity updates in the replication change log.
  • Modify the update interval.
  • Select the attributes to which to apply Referential Integrity.
  • Disable Referential Integrity.
All attributes used in referential integrity must be indexed for presence and equality; not indexing those attributes results poor server performance for modify and delete operations.
nsIndexType: pres
nsIndexType: eq
nsIndexType: sub
See Section 13.2, “Creating Standard Indexes” for more information about checking and creating indexes.

5.2. Using Referential Integrity with Replication

There are certain limitations when using the Referential Integrity Postoperation plug-in in a replication environment:
  • Never enable it on a dedicated consumer server (a server that contains only read-only replicas).
  • Never enable it on a server that contains a combination of read-write and read-only replicas.
  • It is possible to enable it on a supplier server that contains only read-write replicas.
  • With multi-master replication, enable the plug-in on just one supplier.
If the replication environment satisfies the all of those condition, you can enable the Referential Integrity Postoperation plug-in.
  1. Enable the Referential Integrity Postoperation plug-in as described in Section 5.3, “Enabling Referential Integrity”.
  2. Configure the plug-in to record any integrity updates in the changelog.
  3. Ensure that the Referential Integrity Postoperation plug-in is disabled on all consumer servers.

    Note

    Because the supplier server sends any changes made by the Referential Integrity Postoperation plug-in to consumer servers, it is unnecessary to run the Referential Integrity Postoperation plug-in on consumer servers.

5.3. Enabling Referential Integrity

This section describes how to enable the Referential Integrity Postoperation plug-in.

5.3.1. Enabling Referential Integrity Using the Command Line

To enable the Referential Integrity Postoperation plug-in using the command line:
  1. Use the dsconf utility to enable the plug-in:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com referint enable
  2. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

5.3.2. Enabling Referential Integrity Using the Web Console

To enable the Referential Integrity plug-in using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select the Plugins menu.
  4. Select the Referential Integrity plug-in and click Show Advanced Settings.
  5. Change the status to ON to enable the plug-in.
  6. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

5.4. The Referential Integrity Update Interval

By default, the server performs Referential Integrity updates immediately after a delete or a modrdn operation. Depending on the amount of operations, this can cause a performance impact. To reduce the performance impact, you can increase the amount of time between updates.
You can set the update interval in seconds. Alternatively, you can set the following values:
  • 0: The check for referential integrity is performed immediately.
  • -1: No check for referential integrity is performed.

Important

If you set the update interval to 0, you can only enable the plug-in on all masters in a multi-master replication environment if you also set their Referential Integrity Postoperation plug-in's update interval to 0. However, if you configure a positive value on one master, you must not enable the plug-in on any other master to prevent replication loops and directory inconsistencies.
If you want to enable the plug-in in a multi-master replication environment, Red Hat recommends setting the update interval to 0 and to enable the plug-in on all masters.

Note

Referential Integrity can only be enabled on one master. If you set the interval to 0, Directory Server cleans up references replicates these changes to all consumers immediately. If you set the interval to a value greater than 0, and the master who has Referential Integrity enabled is offline, the references are not cleaned up before this master is up again.

5.4.1. Displaying the Update Interval Using the Command Line

To display the update interval using the command line to:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity show
referint-update-delay: 0
...

5.4.2. Displaying the Update Interval Using the Web Console

To display the update interval using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select the Referential Integrity plug-in.
  5. See the Update Delay field for the update interval.

5.4.3. Modifying the Update Interval Using the Command Line

To set the update interval using the command line to, for example, to update immediately:
  1. Set the update interval to 0:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --update-delay=0
  2. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

5.4.4. Modifying the Update Interval Using the Web Console

To set the update interval using the web console, for example, to update immediately:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select the Referential Integrity plug-in.
  5. Set the interval in the Update Delay field.
  6. Press Save Config.
  7. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

5.5. Displaying and Modifying the Attribute List

By default, the Referential Integrity plug-in is set up to check for and update the member, uniquemember, owner, and seeAlso attributes. You can add or delete attributes to be updated using the command line or the web console.

Note

Attributes set in the Referential Integrity plug-in's parameter list, must have equality indexing on all databases. Otherwise, the plug-in scans every entry of the database for matching the deleted or modified DN. This can have a significant performance impact. For details about checking and creating indexes, see Section 13.2, “Creating Standard Indexes”.

5.5.1. Displaying the Attribute List Using the Command Line

To display the attribute list using the command line:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity show

5.5.2. Displaying the Attribute List Using the Web Console

To display the attribute list using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select the Referential Integrity plug-in.
  5. See the Membership Attribute field for the list of attributes.

5.5.3. Configuring the Attribute List Using the Command Line

To update the attribute list using the command line:
  1. Optionally, display the current list of attributes. See Section 5.5.1, “Displaying the Attribute List Using the Command Line”.
  2. Update the attribute list:
    • To set an attribute list that should be checked and updated by the plug-in:
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --membership-attr attribute_name_1 attribute_name_2
    • To delete all attributes that should no longer be checked and updated by the plug-in:
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --membership-attr delete
  3. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

5.5.4. Configuring the Attribute List Using the Web Console

To update the attribute list using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select the Referential Integrity plug-in.
  5. Update the Membership Attribute field to set the attributes.
    • To add an attribute, enter the name into the Membership Attribute field.
    • To remove an attribute, press the X button right next to the attribute's name in the Membership Attribute field.
  6. Press Save Config.
  7. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

5.6. Configuring Scope for the Referential Integrity

If an entry is deleted, the references to it are deleted or modified to reflect the change. When this update is applied to all entries and all groups, it can impact performance and prevents flexibility of restricting the referential integrity to selected subtrees. Defining a scope addresses this problem.
For example, there may be one suffix, dc=example,dc=com, containing two subtrees: ou=active users,dc=example,dc=com and ou=deleted users,dc=example,dc=com. Entries in deleted users should not be handled for purposes of referential integrity.

5.6.1. Parameters That Control the Referential Integrity Scope

The following three parameters can be used to define the scope in the Referential Integrity Postoperation plug-in configuration:
nsslapd-pluginEntryScope
This multi-value parameter controls the scope of the entry that is deleted or renamed. It defines the subtree in which the Referential Integrity Postoperation plug-in looks for the delete or rename operations of a user entry. If a user is deleted or renamed that does not exist under the defined subtree, the plug-in ignores the operation. The parameter allows you to specify to which branches of the database the plug-in should apply the operation.
nsslapd-pluginExcludeEntryScope
This parameter also controls the scope of the entry that is deleted or renamed. It defines the subtree in which the Referential Integrity Postoperation plug-in ignores any operations for deleting or renaming a user.
nsslapd-pluginContainerScope
This parameter controls the scope of groups in which references are updated. After a user is deleted, the Referential Integrity Postoperation plug-in looks for the groups to which the user belongs and updates them accordingly. This parameter specifies which branch the plug-in searches for the groups to which the user belongs. The Referential Integrity Postoperation plug-in only updates groups that are under the specified container branch, and leaves all other groups not updated.

5.6.2. Displaying the Referential Integrity Scope Using the Command Line

The following commands show how to display the scope settings using the command line:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity show
...
nsslapd-pluginEntryScope: DN
nsslapd-pluginExcludeEntryScope: DN
nsslapd-pluginContainerScope: DN

5.6.3. Displaying the Referential Integrity Scope Using the Web Console

The following procedure shows how to display the scope settings using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select the Referential Integrity plug-in.
  5. See the Entry Scope, Exclude Entry Scope, and Container Scope fields for the currently configured scope.

5.6.4. Configuring the Referential Integrity Scope Using the Command Line

To configure the referential integrity scope using the command line:
  1. The following commands show how to configure the individual referential integrity scope settings using the command line:
    • To set a distinguished name (DN):
      • To the nsslapd-pluginEntryScope parameter:
        # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --entry-scope="DN"
      • To the nsslapd-pluginExcludeEntryScope parameter:
        # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --exclude-entry-scope="DN"
      • To the nsslapd-pluginContainerScope parameter:
        # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --container-scope="DN"
    • To remove a DN:
      • From the nsslapd-pluginEntryScope parameter:
        # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --entry-scope=delete
      • From the nsslapd-pluginExcludeEntryScope parameter:
        # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --exclude-entry-scope=delete
      • From the nsslapd-pluginContainerScope parameter:
        # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --container-scope=delete
  2. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

5.6.5. Configuring the Referential Integrity Scope Using the Web Console

To configure the referential integrity scope using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select the Plugins menu.
  4. Select the Referential Integrity plug-in.
  5. Set the scope in the Entry Scope, Exclude Entry Scope, and Container Scope fields.
  6. Click Save Config.
  7. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

Chapter 6. Populating Directory Databases

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

6.1. Importing Data

Directory Server can populate a database with data by:
  • Importing data
  • Initializing a database for replication
Table 6.1, “Import Method Comparison” describes the differences between an import and initializing databases.

Table 6.1. Import Method Comparison

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

6.1.1. Setting EntryUSN Initial Values During Import

Entry update sequence numbers (USNs) are not preserved when entries are exported from one server and imported into another. As Section 4.1, “Tracking Modifications to the Database through Update Sequence Numbers” explains, entry USNs are assigned for operations that happen on a local server, so it does not make sense to import those USNs onto another server.
However, it is possible to configure an initial entry USN value for entries when importing a database or initializing a database (such as when a replica is initialized for replication). This is done by setting the nsslapd-entryusn-import-initval parameter, which sets a starting USN for all imported entries.
There are two possible values for nsslapd-entryusn-import-initval:
  • An integer, which is the explicit start number used for every imported entry.
  • next, which means that every imported entry uses whatever the highest entry USN value was on the server before the import operation, incremented by one.
If nsslapd-entryusn-import-initval is not set, then all entry USNs begin at zero.

Example 6.1. How the nsslapd-entryusn-import-initval Parameter works

For example, if the highest value on the server is 1000 before the import or initialization operation, and the nsslapd-entryusn-import-initval value is next, then every imported entry is assigned a USN of 1001:
# ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com -x "(cn=*)" entryusn

dn: dc=example,dc=com
entryusn: 1001
dn: ou=Accounting,dc=example,dc=com
entryusn: 1001
dn: ou=Product Development,dc=example,dc=com
entryusn: 1001
...
dn: uid=user_name,ou=people,dc=example,dc=com
entryusn: 1001
...
To set an initial value for entry USNs, add the nsslapd-entryusn-import-initval parameter to the server into which data are being imported or to the master server which will perform the initialization. For example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-entryusn-import-initval=next

Note

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

6.1.2. Importing Using the Command Line

Directory Server supports importing data while the instance is running or while the instance is offline:

Warning

When you start an import operation, Directory Server first removes all existing data from the database and subsequently imports the data from the LDIF file. If the import fails, for example, because the LDIF file does not exist, the server has already removed the previous data from the database.
Note that the LDIF files used for import operations must use UTF-8 character set encoding. Import operations do not convert data from the local character set encoding to UTF-8. Additionally, all imported LDIF files must contain the root suffix entry.
Directory Server runs import operations as the dirsrv user. Therefore, the permissions of the LDIF file must allow this user to read the file.

6.1.2.1. Importing Data While the Server is Running

6.1.2.1.1. Importing Using the dsconf backend import Command
Use the dsconf backend import command to automatically create a task that imports data from an LDIF file.
For example, to import the /var/lib/dirsrv/slapd-instance_name/ldif/instance_name-database_name-time_stamp.ldif file into the userRoot database:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend import userRoot /var/lib/dirsrv/slapd-instance_name/ldif/instance_name-database_name-time_stamp.ldif
The import task has finished successfully
The dsconf backend import command supports additional options, for example, to exclude a specific suffix. To display all available options, enter:
# dsconf ldap://server.example.com backend import --help
6.1.2.1.2. Importing Data Using a cn=tasks Entry
The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries the server uses to manage tasks. To initiate an import operation, create a task in the cn=import,cn=tasks,cn=config entry.
An import task entry requires the following attributes:
  • cn: Sets the unique name of the task.
  • nsFilename: Sets the name of the LDIF file to import.
  • nsInstance: Sets the name of the database into which the file should be imported.
Import tasks support additional parameters, for example, to exclude suffixes. For a complete list, see the cn=import section in the Red Hat Directory Server Configuration, Command, and File Reference.
For example, to add a task that imports the content of the /tmp/example.ldif file into the userRoot database:
# ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com -x

dn: cn=example_import,cn=import,cn=tasks,cn=config
changetype: add
objectclass: extensibleObject
cn: example_import
nsFilename: /tmp/example.ldif
nsInstance: userRoot
When the task is completed, the entry is removed from the directory configuration.

6.1.2.2. Importing Data While the Server is Offline

If the server is offline when you import data, use the dsctl ldif2db command:
  1. Stop the instance:
    # dsctl instance_name stop
  2. Import the data from the LDIF file. For example, to import the /tmp/example.ldif file into the userRoot database:
    # dsctl instance_name ldif2db userroot /tmp/example.ldif 
    OK group dirsrv exists
    OK user dirsrv exists
    [17/Jul/2018:13:42:42.015554231 +0200] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
    ...
    [17/Jul/2018:13:42:44.302630629 +0200] - INFO - import_main_offline - import userroot: Import complete.  Processed 160 entries in 2 seconds. (80.00 entries/sec)
    ldif2db successful

    Warning

    If the database specified in the command does not correspond with the suffix contained in the LDIF file, all data contained in the database is deleted, and the import fails.
  3. Start the instance:
    # dsctl instance_name start

6.1.3. Importing Data Using the Web Console

To import data from an LDIF file using the web console:
  1. Store the LDIF file you want to import in the /var/lib/dirsrv/slapd-instance_name/ldif/ directory.
  2. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  3. Select the instance.
  4. Open the Database menu.
  5. Select the suffix entry.
  6. Click Suffix Tasks, and select Initialize Suffix.
  7. Select the LDIF file to import or enter the full path to the file.
  8. Click Import.

6.2. Exporting Data

LDAP Data Interchange Format (LDIF) files are used to export database entries from the Directory Server databases. LDIF is a standard format described in RFC 2849.

Note

The export operations do not export the configuration information (cn=config), schema information (cn=schema), or monitoring information (cn=monitor).
Exporting data can be useful for the following:
  • Backing up the data in the database.
  • Copying data to another Directory Server.
  • Exporting data to another application.
  • Repopulating databases after a change to the directory topology.
    For example, if a directory contains one database, and its contents should be split into two databases, then the two new databases receive their data by exporting the contents of the old databases and importing it into the two new databases, as illustrated in Figure 6.1, “Splitting a Database Contents into Two Databases”.
    Splitting a Database Contents into Two Databases

    Figure 6.1. Splitting a Database Contents into Two Databases

Warning

Do not stop the server during an export operation.
Directory Server runs the export operations as the dirsrv user. Therefore, the permissions of the destination directory must allow this user to write the file.

6.2.1. Exporting Data into an LDIF File Using the Command Line

Directory Server supports exporting data while the instance is running or while the instance is offline:

6.2.1.1. Exporting a Database While the Server is Running

6.2.1.1.1. Exporting a Databases Using the dsconf backend export Command
Use the dsconf backend export command to automatically create a task that exports data to an LDIF file.
For example, to export the userRoot database:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend export userRoot
The export task has finished successfully
By default, dsconf stores the export in a file called instance_name_database_name-time_stamp.ldif in the /var/lib/dirsrv/slapd-instance_name/export/ directory. Alternatively, add the -l file_name option to the command to specify a different location.
The dsconf backend export command supports additional options, for example, to exclude a specific suffix. To display all available options, enter:
# dsconf ldap://server.example.com backend export --help
6.2.1.1.2. Exporting a Database Using a cn=tasks Entry
The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries the server uses to manage tasks. To initiate an export operation, create a task in the cn=export,cn=tasks,cn=config entry.
Using a task entry enables you to export data while the server is running.
An export task entry requires the following attributes:
  • cn: Sets the unique name of the task.
  • nsInstance: Sets the name of the database to export.
  • nsFilename: Sets the name of the file into which the export should be stored.
Export tasks support additional parameters, for example, to exclude suffixes. For a complete list, see the cn=export section in the Red Hat Directory Server Configuration, Command, and File Reference.
For example, to add a task that exports the content of the userRoot database into the /tmp/example.ldif file:
# ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com -x

dn: cn=example_export,cn=export,cn=tasks,cn=config
changetype: add
objectclass: extensibleObject
cn: example_export
nsInstance: userRoot
nsFilename: /tmp/example.ldif
When the task is completed, the entry is removed from the directory configuration.

6.2.1.2. Exporting a Database While the Server is Offline

If the server is offline when you export data, use the dsctl db2ldif command:
  1. Stop the instance:
    # dsctl instance_name stop
  2. Export the database into an LDIF file. For example to export the userRoot database into the /etc/example.ldif file:
    # dsctl instance_name db2ldif userroot /tmp/example.ldif 
    OK group dirsrv exists
    OK user dirsrv exists
    ldiffile: /tmp/example.ldif
    [18/Jul/2018:10:46:03.353656777 +0200] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
    [18/Jul/2018:10:46:03.383101305 +0200] - INFO - ldbm_back_ldbm2ldif - export userroot: Processed 160 entries (100%).
    [18/Jul/2018:10:46:03.391553963 +0200] - INFO - dblayer_pre_close - All database threads now stopped
    db2ldif successful
  3. Start the instance:
    # dsctl instance_name start

6.2.2. Exporting a Suffix to an LDIF File Using the Web Console

To export a suffix using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Database menu.
  4. Select the suffix entry.
  5. Click Suffix Tasks, and select Export Suffix.
  6. Enter the name of the LDIF file in which you want to store the export. Directory Server will store the file in the /var/lib/dirsrv/slapd-instance_name/ldif/ directory using the specified file name.
  7. Click Export Database.

6.3. Backing up Directory Server

A backup in Directory Server contains, for example:
  • All database files including the data stored within these databases

    Note

    Directory Server does not support backing up individual databases.
  • The transaction logs
  • The Indices
In contrast to a backup, you can export data as described in Section 6.2, “Exporting Data”. Use the export feature to export specific data, such as a subtree, from a server in the LDAP Data Interchange Format (LDIF) format.

Warning

Do not stop the server during a backup operation.
Directory Server runs the backup task as the dirsrv user. Therefore, the permissions of the destination directory must allow this user to create files.

6.3.1. Backing up All Databases Using the Command Line

Directory Server supports backing up the databases while the instance is running or while the instance is offline:

Important

These methods only back up the databases. For details about backing up other important files, such as the configuration, see Section 6.3.3, “Backing up Configuration Files, the Certificate Database, and Custom Schema Files”.

6.3.1.1. Backing up All Databases While the Server is Running

6.3.1.1.1. Backing up All Databases Using the dsconf backup create Command
Use the dsconf backup create command to automatically create a task that backs up all databases.
For example, to backup the userRoot database:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backup create
The backup create task has finished successfully
By default, dsconf stores the backup in a subdirectory called instance_name-time_stamp in the /var/lib/dirsrv/slapd-instance_name/bak/ directory. To specify a different location, append a directory name to the command.
6.3.1.1.2. Backing up All Databases Using a cn=tasks entry
The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries the server uses to manage tasks. To initiate a backup operation, create a task in the cn=backup,cn=tasks,cn=config entry.
Using a task entry enables you to backup the databases while the server is running.
A backup task entry requires the following attributes:
  • cn: Sets the unique name of the task.
  • nsDatabaseType: Sets the type of the database to back up. Directory Server supports only the ldbm database value in this attribute.
Backup tasks support additional parameters, for example, to specify a different destination directory as the default, /var/lib/dirsrv/slapd-instance_name/bak/. For a complete list, see the cn=backup section in the Red Hat Directory Server Configuration, Command, and File Reference.
For example, to backup all databases and store the archive in the default backup directory:
# ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com -x

dn: cn=example_backup,cn=export,cn=tasks,cn=config
changetype: add
objectclass: extensibleObject
cn: example_backup
nsDatabaseType: ldbm database
If you not specify the nsArchiveDir attribute, the server stores the backup in a subdirectory called instance_name-time_stamp in the /var/lib/dirsrv/slapd-instance_name/bak/ directory.
When the task is completed, the entry is removed from the directory configuration.

6.3.1.2. Backing up All Databases While the Server is Offline

If the server is offline when you backup databases, use the dsctl db2bak command:
  1. Stop the instance:
    # dsctl instance_name stop
  2. Backup the database:
    # dsctl instance_name db2bak
    OK group dirsrv exists
    OK user dirsrv exists
    [18/Jul/2018:14:02:37.358958713 +0200] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
    ...
    db2bak successful

    Note

    The dsctl db2bak command runs as the backup as the dirsrv user. Therefore, the permissions of the destination directory must allow this user to create files and directories.
    If you not append a destination directory to the command, the server stores the backup in a subdirectory called instance_name-time_stamp in the /var/lib/dirsrv/slapd-instance_name/bak/ directory.
  3. Start the instance:
    # dsctl instance_name start

6.3.2. Backup up all Databases Using the Web Console

To back up all databases of an instance using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Click the Actions button, and select Perform Backup.
  4. Enter a name for the backup, such as a time stamp to indicate the creation date and time of the backup.
  5. Click Do Backup.
The server stores the backup in a subdirectory with the name you entered in the /var/lib/dirsrv/slapd-instance_name/bak/ directory.

6.3.3. Backing up Configuration Files, the Certificate Database, and Custom Schema Files

The backup mechanism integrated into Directory Server backs up only the databases. However, there are additional files stored in the /etc/dirsrv/slapd-instance-name/ directory which are required to, for example, restore a instance on a different server after a hardware failure.

Note

Backing up the configuration directory is not supported in the web console.

Example 6.2. How to Back up the /etc/dirsrv/slapd-instance-name/ Directory

To back up the content of /etc/dirsrv/slapd-instance-name/, you can copy the directory or store it into an archive file. For example, to store the content of the /etc/dirsrv/slapd-instance-name/ directory in the /root/config_slapd-instance_name_time_stamp.tar.gz file:
# cd /etc/dirsrv/
# tar -zcvf /root/config_slapd-instance_name_$(date +%Y-%m-%d_%H-%M-%S).tar.gz slapd-instance_name/

Important

During the backup, do not update the certificate database. Otherwise, this database might not be consistent in the backup.

6.4. Restoring Directory Server

In certain situations, administrators want to restore Directory Server, for example, after a hardware failure. This section describes the supported restore methods.

Note

Directory Server does not support restoring individual databases.
Directory Server runs the restore operation as the dirsrv user. Therefore, the permissions of the directory containing the backup must allow this user to read the files.

6.4.1. Restoring All Databases Using the Command Line

Directory Server supports restoring databases while the instance is running or while the instance is offline:

6.4.1.1. Restoring All Databases While the Server is Running

6.4.1.1.1. Restoring All Databases Using the dsconf backup restore Command
Use the dsconf backup restore command to automatically create a task that restores up all databases from a backup directory.
For example, to restore the backup stored in the /var/lib/dirsrv/slapd-instance_name/bak/instance_name-time_stamp/ directory:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backup restore /var/lib/dirsrv/slapd-instance_name/bak/instance_name-time_stamp/
The backup restore task has finished successfully
6.4.1.1.2. Restoring all Databases Using a cn=tasks entry
The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries the server uses to manage tasks. To initiate a restore operation, create a task in the cn=restore,cn=tasks,cn=config entry.

Warning

Using a restore task overrides all data in the instance.
A restore task entry requires the following attributes:
  • cn: Sets the unique name of the task.
  • nsArchiveDir: Sets the path to the directory that contains the backup.
  • nsDatabaseType: Sets the type of the database to restore. Directory Server supports only the ldbm database value in this attribute.
For example, to add a task that restores all databases from the backup stored in the /var/lib/dirsrv/slapd-instance_name/bak/instance_name-time_stamp/ directory:
# ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com -x

dn: cn=example_restore,cn=import,cn=tasks,cn=config
changetype: add
objectclass: extensibleObject
cn: example_restore
nsArchiveDir: /var/lib/dirsrv/slapd-instance_name/bak/instance_name-time_stamp/
nsDatabaseType: ldbm database
When the task is completed, the entry is removed from the directory configuration.

6.4.1.2. Restoring all Databases While the Server is Offline

If the server is offline when you restore databases, use the dsctl bak2db command:
  1. Stop the instance:
    # dsctl instance_name stop
  2. Restore the databases. For example, to add a task that restores all databases from the backup stored in the /var/lib/dirsrv/slapd-instance_name/bak/instance_name-time_stamp/ directory:
    # dsctl instance_name bak2db /var/lib/dirsrv/slapd-instance_name/bak/instance_name-time_stamp/
    OK group dirsrv exists
    OK user dirsrv exists
    [20/Jul/2018:15:52:24.932598675 +0200] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
    ...
    bak2db successful

    Note

    The dsctl bak2db command runs as the restore as the dirsrv user. Therefore, the permissions of the source directory must allow this user to read files and directories.
    If you not append a destination directory to the command, the server stores the backup in a subdirectory called instance_name-time_stamp in the /var/lib/dirsrv/slapd-instance_name/bak/ directory.
  3. Start the instance:
    # dsctl instance_name start

6.4.2. Restoring All Databases Using the Web Console

To restore all database using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Click the Actions button, and select Manage Backups.
    The displayed window lists the available backups in the /var/lib/dirsrv/slapd-instance_name/bak/ directory.
  4. Click the Restore button next to the backup you want to restore.
  5. Click Yes to confirm.

6.4.3. Restoring Databases That Include Replicated Entries

Several situations can occur when a supplier server is restored:
  • The consumer servers are also restored.
    For the very unlikely situation, that all databases are restored from backups taken at exactly the same time (so that the data are in sync), the consumers remain synchronized with the supplier, and it is not necessary to do anything else. Replication resumes without interruption.
  • Only the supplier is restored.
    If only the supplier is restored or if the consumers are restored from backups taken at a different times, reinitialize the consumers for the supplier to update the data in the database. If only the supplier is restored or if the consumers are restored from backups taken at a different times, reinitialize the consumers for the supplier to update the data in the database.
  • Changelog entries have not yet expired on the supplier server.
    If the supplier's changelog has not expired since the database backup was taken, then restore the local consumer and continue with normal operations. This situation occurs only if the backup was taken within a period of time that is shorter than the value set for the maximum changelog age attribute, nsslapd-changelogmaxage, in the cn=changelog5,cn=config entry. For more information about this option, see the Red Hat Directory Server Configuration, Command, and File Reference.
    Directory Server automatically detects the compatibility between the replica and its changelog. If a mismatch is detected, the server removes the old changelog file and creates a new, empty one.
  • Changelog entries have expired on the supplier server since the time of the local backup.
    If changelog entries have expired, reinitialize the consumer. For more information on reinitializing consumers, see Section 15.7.3, “Initializing a Consumer”.

Example 6.3. Restoring a Directory Server Replication Topology

For example, to restore all servers in a replication environment, consisting of two masters and two consumer server:
  1. Restore the first master. Use the dsconf backend import command to import the data. See Section 6.1.2, “Importing Using the Command Line”.
  2. Online-initialize the remaining servers by using replication:
    1. Initialize the second master from the first one.
    2. Initialize the consumers from the master.
  3. On each server, display the replication status to verify that replication works correctly. For details, see Section 15.18, “Monitoring the Replication Status”.
The changelog associated with the restored database will be erased during the restore operation. A message will be logged to the supplier servers' log files indicating that reinitialization is required.
For information on managing replication, see Chapter 15, Managing Replication.

Chapter 7. Managing Attributes and Values

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

7.1. Enforcing Attribute Uniqueness

To ensure that the value of an attribute is unique across the directory or subtree, use the Attribute Uniqueness plug-in.
If you want multiple attributes to be unique or if you want to use different conditions, create multiple configuration records of the plug-in.

7.1.1. Creating a New Configuration Record of the Attribute Uniqueness Plug-in

For each attribute whose values must be unique, create a new configuration record of the Attribute Uniqueness plug-in.

Note

You can only create a new configuration record of the plug-in from the command line.
To create a new unconfigured and disabled configuration record of the plug-in named Example Attribute Uniqueness:
dsconf -D "cn=Directory Manager" ldap://server.example.com plugin attr-uniq add "Example" --attr-name uid

7.1.2. Configuring Attribute Uniqueness over Suffixes or Subtrees

You can configure the Attribute Uniqueness plug-in to ensure that values of an attribute are unique in certain suffixes, subtrees, or over suffixes and subtrees.

7.1.2.1. Configuring Attribute Uniqueness over Suffixes or Subtrees Using the Command Line

To configure, for example, that values stored in mail attributes are unique:
  1. Create a new configuration record of the Attribute Uniqueness plug-in named, for example, mail Attribute Uniqueness. For details, see Section 7.1.1, “Creating a New Configuration Record of the Attribute Uniqueness Plug-in”.
  2. Enable the plug-in configuration record:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin attr-uniq enable "mail Attribute Uniqueness"
  3. Configure that values stored in mail attributes must be unique inside, for example, the ou=Engineering,dc=example,dc=com and ou=Sales,dc=example,dc=com subtrees:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin attr-uniq set "mail Attribute Uniqueness" --attr-name mail --subtree ou=Engineering,dc=example,dc=com ou=Sales,dc=example,dc=com
  4. Optionally, to configure uniqueness across all subtrees configured in this plug-in configuration record:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin attr-uniq set "mail Attribute Uniqueness" --across--all-subtrees=on
  5. Restart the instance:
    # dsctl instance_name restart

7.1.2.2. Configuring Attribute Uniqueness over Suffixes or Subtrees Using the Web Console

To configure, for example, that values stored in mail attributes are unique:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select the Attribute Uniqueness plug-in.
  5. Click Add Config.
  6. Fill the fields, and enable the config. For example:
    Adding an Attribute Uniqueness Configuration

    Figure 7.1. Adding an Attribute Uniqueness Configuration

  7. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

7.1.3. Configuring Attribute Uniqueness over Object Classes

You can configure the Attribute Uniqueness plug-in to ensure that values of an attribute are unique in subtree entries that contain a specific object class. Directory Server searches for this object class in the parent entry of the updated object. If Directory Server did not find the object class, the search continues at the next higher level entry up to the root of the directory tree. If the object class was found, Directory Server verifies that the value of the attribute set in uniqueness-attribute-name is unique in this subtree.
To configure, for example, that values stored in mail attributes are unique under the entry that contains the nsContainer object class:
  1. Create a new configuration record of the Attribute Uniqueness plug-in named, for example, mail Attribute Uniqueness. For details, see Section 7.1.1, “Creating a New Configuration Record of the Attribute Uniqueness Plug-in”.
  2. Enable the plug-in configuration record:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin attr-uniq enable "mail Attribute Uniqueness"
  3. Configure that values stored in mail attributes must be unique under the entry that contains the nsContainer object class:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin attr-uniq set "mail Attribute Uniqueness" --top-entry-oc=nsContainer
  4. Optionally, you can limit the scope of objects being checked. If you want the server to check only a subset of entries under the entry that contains the nsContainer object class, set an additional object class in the uniqueness-subtree-entries-oc parameter. This additional class will also have to be present.
    For example, the mail attribute must be unique in all entries under the entry that contains the nsContainer object class set. However, you want that the plug-in only searches the mail in entries that contain a object class that provides this attribute, such as inetOrgPerson. In this situation enter:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin attr-uniq set "mail Attribute Uniqueness" --subtree-entries-oc=inetOrgPerson
  5. Restart the instance:
    # dsctl instance_name restart

7.1.4. Attribute Uniqueness Plug-in Configuration Parameters

To configure an Attribute Uniqueness plug-in configuration record, set the plug-in's configuration attributes in the cn=attribute_uniqueness_configuration_record_name,cn=plugins,cn=config entry.

Example 7.1. Attribute Uniqueness Plug-in Configuration Using Plug-in-specific Attributes

dn: cn=Example Attribute Uniqueness,cn=plugins,cn=config
nsslapd-pluginEnabled: on
uniqueness-attribute-name: attribute_name
uniqueness-top-entry-oc: objectclass1 
uniqueness-subtree-entries-oc: objectclass2
For a list of parameters you can set to configure the Attribute Uniqueness plug-in, see the corresponding section in the Red Hat Directory Server Configuration, Command, and File Reference.

7.2. Assigning Class of Service

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

7.2.1. About the CoS Definition Entry

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

7.2.2. About the CoS Template Entry

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

7.2.3. How a Pointer CoS Works

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

Figure 7.2. Sample Pointer CoS

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

7.2.4. How an Indirect CoS Works

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

Figure 7.3. Sample Indirect CoS

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

7.2.5. How a Classic CoS Works

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

Figure 7.4. Sample Classic CoS

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

7.2.6. Handling Physical Attribute Values

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

    Note

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

Note

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

7.2.7. Handling Multi-valued Attributes with CoS

Any attribute can be generated using a class of service — including multi-valued attributes. That introduces the potential for confusion. Which CoS supplies a value? Any of them or all of them? How is the value selected from competing CoS templates? Does the generated attribute use a single value or multiple values?
There are two ways to resolve this:
  • Creating a rule to merge multiple CoS-generated attributes into the target entry. This results in multiple values in the target entry.
  • Setting a priority to select one CoS value out of competing CoS definitions. This generates one single value for the target entry.

Note

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

Note

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

    Note

    This method only works with classic CoS.
  • Multiple CoS definitions may define a class of service for the same target attribute, so there are multiple template entries. For example:
    dn: cn=mail template,dc=example,dc=com
    objectclass: top
    objectclass: extensibleObject
    objectclass: cosTemplate
    accessTo: mail.example.com
    
    dn: cn=chat template,dc=example,dc=com
    objectclass: top                
    objectclass: extensibleObject
    objectclass: cosTemplate
    accessTo: irc.example.com
However, it may be that even if there are multiple CoS definitions, only one value should be generated for the attribute. If there are multiple CoS definitions, then the value is chosen arbitrarily. This is an unpredictable and unwieldy option. The way to control which CoS template to use is to set a ranking on the template — a priority — and the highest prioritized CoS always "wins" and provides the value.
It is fairly common for there to be multiple templates completing to provide a value. For example, there can be a multi-valued cosSpecifier attribute in the CoS definition entry. The template priority is set using the cosPriority attribute. This attribute represents the global priority of a particular template. A priority of zero is the highest priority.
For example, a CoS template entry for generating a department number appears as follows:
dn: cn=data,dc=example,dc=com
objectclass: top
objectclass: extensibleObject
objectclass: cosTemplate
departmentNumber: 71776
cosPriority: 0
This template entry contains the value for the departmentNumber attribute. It has a priority of zero, meaning this template takes precedence over any other conflicting templates that define a different departmentNumber value.
Templates that contain no cosPriority attribute are considered the lowest priority. Where two or more templates are considered to supply an attribute value and they have the same (or no) priority, a value is chosen arbitrarily.

Note

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

7.2.8. Searches for CoS-Specified Attributes

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

7.2.9. Access Control and CoS

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

7.2.10. Managing CoS from the Command Line

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

7.2.10.1. Creating the CoS Definition Entry from the Command Line

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

Example 7.2. An Example Pointer CoS Entry

 dn: cn=pointerCoS,dc=example,dc=com
 objectclass: top 
 objectclass: cosSuperDefinition 
 objectclass: cosPointerDefinition   
 cosTemplateDn:DN_string  
 cosAttribute:list_of_attributes qualifier  
 cn: pointerCoS
An indirect CoS uses the cosIndirectDefinition object class. This type of CoS identifies the template entry based on the value of one of the target entry's attributes, as specified in the cosIndirectSpecifier attribute. This is illustrated in Example 7.3, “An Example Indirect CoS Entry”.

Example 7.3. An Example Indirect CoS Entry

 dn: cn=indirectCoS,dc=example,dc=com
 objectclass: top 
 objectclass: cosSuperDefinition 
 objectclass: cosIndirectDefinition   
 cosIndirectSpecifier:attribute_name  
 cosAttribute:list_of_attributes qualifier  
 cn: indirectCoS
A classic CoS uses the cosClassicDefinition object class. This identifies the template entry using both the template entry's DN (set in the cosTemplateDn attribute) and the value of one of the target entry's attributes (set in the cosSpecifier attribute). This is illustrated in Example 7.4, “An Example Classic CoS Entry”.

Example 7.4. An Example Classic CoS Entry

 dn: cn=classicCoS,dc=example,dc=com
 objectclass: top 
 objectclass: cosSuperDefinition 
 objectclass: cosClassicDefinition   
 cosTemplateDn:DN_string  
 cosSpecifier:attribute_name  
 cosAttribute:list_of_attributes qualifier  
 cn: classicCoS
For a class of service, the object class defines the type of CoS, and the supporting attributes identify which directory entries are affected by defining the CoS template. Every CoS has one additional attribute which can be defined for it: cosAttribute. The purpose of a CoS is to supply attribute values across multiple entries; the cosAttribute attribute defines which attribute the CoS generates values for.

7.2.10.2. Creating the CoS Template Entry from the Command Line

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

Note

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

7.2.10.3. Example of a Pointer CoS

Example Corporation's administrator is creating a pointer CoS that shares a common postal code with all entries in the dc=example,dc=com tree.
  1. Add a new pointer CoS definition entry to the dc=example,dc=com suffix using ldapmodify:
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    dn: cn=pointerCoS,dc=example,dc=com
    changetype: add
    objectclass: top
    objectclass: cosSuperDefinition
    objectclass: cosPointerDefinition
    cosTemplateDn: cn=exampleUS,ou=data,dc=example,dc=com
    cosAttribute: postalCode
  2. Create the template entry:
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    dn: cn=exampleUS,ou=data,dc=example,dc=com
    changetype: add
    objectclass: top
    objectclass: extensibleObject
    objectclass: cosTemplate
    postalCode: 44438
The CoS template entry (cn=exampleUS,ou=data,dc=example,dc=com) supplies the value stored in its postalCode attribute to any entries located under the dc=example,dc=com suffix. These entries are the target entries.

7.2.10.4. Example of an Indirect CoS

This indirect CoS uses the manager attribute of the target entry to identify the CoS template entry, which varies depending on the different values of the attribute.
  1. Add a new indirect CoS definition entry to the dc=example,dc=com suffix using ldapmodify:
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    dn: cn=indirectCoS,dc=example,dc=com
    changetype: add
    objectclass: top
    objectclass: cosSuperDefinition
    objectclass: cosIndirectDefinition
    cosIndirectSpecifier: manager
    cosAttribute: departmentNumber
If the directory or modify the manager entries already contain the departmentNumber attribute, then no other attribute needs to be added to the manager entries. The definition entry looks in the target suffix (the entries under dc=example,dc=com) for entries containing the manager attribute because this attribute is specified in the cosIndirectSpecifier attribute of the definition entry). It then checks the departmentNumber value in the manager entry that is listed. The value of the departmentNumber attribute will automatically be relayed to all of the manager's subordinates that have the manager attribute. The value of departmentNumber will vary depending on the department number listed in the different manager's entries.

7.2.10.5. Example of a Classic CoS

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

7.2.10.6. Searching for CoS Entries

CoS definition entries are operational entries and, by default, not returned in regular searches. To return CoS definition entries in searches, add the ldapSubEntry object class to the CoS definition entries. For example:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=pointerCoS,ou=People,dc=example,dc=com
changetype: add
objectclass: ldapSubEntry
Then use the (objectclass=ldapSubEntry) filter with the ldapsearch utility to search for entries containing the ldapSubEntry object class. For example:
# ldapsearch -x -s sub -b ou=People,dc=example,dc=com "(|(objectclass=*)(objectclass=ldapSubEntry))"
This search returns all regular entries in addition to CoS definition entries in the ou=People,dc=example,dc=com subtree.

7.2.11. Creating Role-Based Attributes

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

Important

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

Note

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

7.3. Linking Attributes to Manage Attribute Values

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

7.3.1. About Linking Attributes

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

Figure 7.5. Basic Linked Attribute Configuration

Note

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

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

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

7.3.2. Looking at the Linking Attributes Plug-in Syntax

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

Example 7.5. Example Linked Attributes Plug-in Instance Entry

dn: cn=Manager Link,cn=Linked Attributes,cn=plugins,cn=config
objectClass: top
objectClass: extensibleObject
cn: Manager Link
linkType: directReport
managedType: manager
linkScope: ou=people,dc=example,dc=com
For a list of attributes available for an instance of the Linked Attributes plug-in, see the corresponding section in the Red Hat Directory Server Configuration, Command, and File Reference.

7.4. Assigning and Managing Unique Numeric Attribute Values

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

Note

Attribute uniqueness is not necessarily preserved with the DNA Plug-in. The plug-in only assigns non-overlapping ranges, but it does allow manually-assigned numbers for its managed attributes, and it does not verify or require that the manually-assigned numbers are unique.
The issue with assigning unique numbers is not with generating the numbers but in effectively avoiding replication conflicts. The DNA Plug-in assigns unique numbers across a single back end. For multi-master replication, when each master is running a local DNA Plug-in instance, there has to be a way to ensure that each instance is using a truly unique set of numbers. This is done by assigning different ranges of numbers to each server to assign.

7.4.1. About Dynamic Number Assignments

The DNA Plug-in for a server assigns a range of available numbers that that instance can issue. The range definition is very simple and is set by two attributes: the server's next available number (the low end of the range) and its maximum value (the top end of the range). The initial bottom range is set when the plug-in instance is configured. After that, the bottom value is updated by the plug-in. By breaking the available numbers into separate ranges on each replica, the servers can all continually assign numbers without overlapping with each other.

7.4.1.2. Ranges and Assigning Numbers

There are several different ways that the Directory Server can handle generating attribute values:
  • In the simplest case, a user entry is added to the directory with an object class which requires the unique-number attribute, but without the attribute present. Adding an entry with no value for the managed attribute triggers the DNA Plug-in to assign a value. This option only works if the DNA Plug-in has been configured to assign unique values to a single attribute.
  • A similar and more manageable option is to use a magic number. This magic number is a template value for the managed attribute, something outside the server's range, a number or even a word, that the plug-in recognizes it needs to replace with a new assigned value. When an entry is added with the magic value and the entry is within the scope and filter of the configured DNA Plug-in, then using the magic number automatically triggers the plug-in to generate a new value. The following example, based on using ldapmodify, adds 0 as a magic number:
    dn: uid=jsmith,ou=people,dc=example,dc=com
     changetype: add
     objectClass: top
     objectClass: person
     objectClass: posixAccount
     uid: jsmith
     cn: John Smith
     uidNumber: 0
     gidNumber: 0
     ....
    The DNA Plug-in only generates new, unique values. If an entry is added or modified to use a specific value for an attribute controlled by the DNA Plug-in, the specified number is used; the DNA Plug-in will not overwrite it.

7.4.1.3. Multiple Attributes in the Same Range

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

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

# ldapmodify -D "cn=Directory Manager" -W -x
dn: uid=jsmith,ou=people,dc=example,dc=com
changetype: modify
add: employeeId
employeeId: magic

Important

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

Example 7.6. DNA and Unique Bank Account Numbers

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

7.4.2. Looking at the DNA Plug-in Syntax

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

Note

If the dnaNextRange attribute is handled internally if it is not set explicitly. When it is handled automatically, the dnaMaxValue attribute serves as upper limit for the next range.
Each supplier keeps a track of its current range in a separate configuration entry which contains information about its range and its connection settings. This entry is a child of the location in dnasharedcfgdn. The configuration entry is replicated to all of the other suppliers, so each supplier can check that configuration to find a server to contact for a new range. For example:
dn: dnaHostname=ldap1.example.com+dnaPortNum=389,cn=Account UIDs,ou=Ranges,dc=example,dc=com
objectClass: dnaSharedConfig
objectClass: top
dnahostname: ldap1.example.com
dnaPortNum: 389
dnaSecurePortNum: 636
dnaRemainingValues: 1000

7.4.3. Configuring Unique Number Assignments

The unique number distribution is configured by creating different instances of the DNA Plug-in.

7.4.3.1. Creating a New Instance of the DNA Plug-in

To use the DNA with multiple configurations, create a new instance of the plug-in for each configuration.

Note

You can create new instances of the plug-in only by using the command line. However, you can edit the settings using both the command line and the web console.
To create and enabling a new instance of the plug-in:
  1. For example, to create a new instance of the plug-in:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin dna config "Account UIDs" add --type uidNumber --filter "(objectclass=posixAccount)" --scope ou=People,dc=example,dc=com --next-value 1 --max-value 1300 --shared-config-entry "cn=Account UIDs,ou=Ranges,dc=example,dc=com" --threshold 100 --range-request-timeout 60 --dnaMagicRegen: magic
  2. Enable the DNA plug-in. For details, see Section 1.10.3, “Enabling and Disabling Plug-ins”.

7.4.3.2. Configuring Unique Number Assignments Using the Command Line

Note

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

Note

Set up the DNA Plug-in on every supplier server, and be careful not to overlap the number range values.
  1. Create a new instance of the plug-in. See Section 7.4.3.1, “Creating a New Instance of the DNA Plug-in”.
  2. Create the shared container entry in the replicated subtree:
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    dn: ou=Ranges,dc=example,dc=com
    changetype: add
    objectclass: top
    objectclass: extensibleObject
    objectclass: organizationalUnit
    ou: Ranges
    -
    dn: cn=Account UIDs,ou=Ranges,dc=example,dc=com
    changetype: add
    objectclass: top
    objectclass: extensibleObject
    cn: Account UIDs
  3. For servers in multi-master replication, create a configuration entry for the host, which specifies its connection information and range:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin dna config "Account UIDs" shared-config-entry add "cn=Account UIDs,ou=Ranges,dc=example,dc=com" --hostname ldap1.example.com --port 389 --secure-port 636 --remaining-values 1000
  4. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

7.4.3.3. Configuring Unique Number Assignments Using the Web Console

To enable and configure the DNA plug-in using the web console:
  1. Create a new instance of the plug-in. See Section 7.4.3.1, “Creating a New Instance of the DNA Plug-in”.
  2. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  3. Select the instance.
  4. Open the Plugins menu.
  5. Select the DNA plug-in.
  6. Change the status to ON to enable the plug-in.
  7. Click Add Config.
  8. Fill the fields, and enable the config.
  9. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

7.4.4. Distributed Number Assignment Plug-in Performance Notes

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

Chapter 8. Organizing and Grouping Entries

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

8.1. Using Groups

Similar to the operating system, you can add users to groups in Directory Server. Groups work the other way around as roles. If you are using roles, the DN of the assigned role is stored in the nsRoleDN attribute in the user object. If you use groups, then the DN of the users who are members of this group are stored in member attributes in the group object. If you enabled the memberOf plug-in, then the groups the user is a member of, are additionally stored in memberOf attribute in the user object. With this plug-in enabled, groups additionally have the benefit of roles, that you can list the group memberships of a user, similar as when using roles. Additionally, groups are faster than roles.
For further details about using the memberOf plug-in, see Section 8.1.4, “Listing Group Membership in User Entries”.

8.1.1. The Different Types of Groups

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

Table 8.1. Dynamic and Static Group Schema

Type of Group Group Object Classes Member Attributes
Static groupOfNames [a] member
groupOfUniqueNames [a] uniqueMember
Dynamic groupOfURLs memberURL
groupOfCertificates memberCertificate
[a] If this object class is used together with one of the dynamic object classes, the group becomes dynamic.
The following two examples show a static and a dynamic group entry:

Example 8.1. A Static Group Entry

A static group entry lists the specific members of the group. For example:
objectClass: top
objectClass: groupOfUniqueNames
cn: static group
description: Example static group.
uniqueMember: uid=mwhite,ou=People,dc=example,dc=com
uniqueMember: uid=awhite,ou=People,dc=example,dc=com

Example 8.2. A Dynamic Group Entry

A dynamic group uses at least one LDAP URL to identify entries belonging to the group and can specify multiple LDAP URLs or, if used with another group object class like groupOfUniqueNames, can explicitly list some group members along with the dynamic LDAP URL. For example:
objectClass: top
objectClass: groupOfUniqueNames
objectClass: groupOfURLs
cn: dynamic group
description: Example dynamic group.
memberURL: ldap:///dc=example,dc=com??sub?(&(objectclass=person)(cn=*sen*))

Note

The memberOf plug-in does not support dynamically generated group memberships. If you set the memberURL attribute instead of listing the group members in an attribute, the memberOf plug-in does not add the memberOf attribute to the user objects that match the filter.

8.1.2. Creating a Static Group

Directory Server only supports creating static groups using the command line.

8.1.2.1. Creating a Static Group Using the Command Line

This section describes how to create the different types of static groups using the command line.
For details about the different static groups, see Section 8.1.1, “The Different Types of Groups”.

Creating a Static Group with the groupOfNames Object Class

The dsidm utility creates static groups in the cn=Groups entry in the specified base DN.
For example, to create the static example_group group with the groupOfNames object class in the cn=Groups,dc=example,dc=com entry
# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" group create --cn "example_group"

Creating a Static Group with the groupOfUniqueNames Object Class

To create a static group with the groupOfUniqueNames object class, use the ldapmodify utility to add the entry.
For example, to create the static example_group group with the groupOfUniqueNames object class in the cn=Groups,dc=example,dc=com entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=example_group,cn=Groups,dc=example,dc=com
changetype: add
objectClass: top
objectClass: groupOfUniqueNames
cn: example_group
description: Example static group with unique members

8.1.3. Creating a Dynamic Group

Directory Server only supports creating dynamic groups using the command line.

8.1.3.1. Creating a Dynamic Group Using the Command Line

This section describes how to create the different types of dynamic groups using the command line.
For details about the different dynamic groups, see Section 8.1.1, “The Different Types of Groups”.

Creating a Dynamic Group with the groupOfURLs Object Class

For example, to create the dynamic example_group group with the groupOfURLs object class in the cn=Groups,dc=example,dc=com entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=example_group,cn=Groups,dc=example,dc=com
changetype: add
objectClass: top
objectClass: groupOfURLs
cn: example_group
description: Example dynamic group for user entries
memberURL: ldap:///dc=example,dc=com??sub?(&(objectclass=person)(cn=*sen*))

Creating a Dynamic Group with the groupOfCertificates Object Class

For example, to create the dynamic example_group group with the groupOfCertificates object class in the cn=Groups,dc=example,dc=com entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=example_group,cn=Groups,dc=example,dc=com
changetype: add
objectClass: top
objectClass: groupOfURLs
cn: example_group
description: Example dynamic group for certificate entries
memberCertificate: ...

8.1.4. Listing Group Membership in User Entries

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

8.1.4.1. Considerations When Using the memberOf Plug-in

This section describes important considerations when you want to use the memberOf plug-in.
Using the memberOf Plug-in in a Replication Topology
There are two approaches to manage the memberOf attribute in a replication topology:
Using the memberOf plug-in With Distributed Databases
As described in Section 2.2.1, “Creating Databases”, you can store sub-trees of your directory in individual databases. By default, the memberOf plug-in only updates user entries which are stored within the same database as the group. To enable the plug-in to also update users in different databases as the group, you must set the memberOfAllBackends parameter to on. See Section 8.1.4.5.2, “Configuring the MemberOf Plug-in on Each Server Using the Web Console”.

8.1.4.2. Required Object Classes by the memberOf Plug-In

The memberOf plug-in By default, the memberOf plug-in will add the MemberOf object class to objects to provide the memberOf attribute. This object class is safe to add to any object for this purpose, and no further action is required to enable this plug-in to operate correctly. Alternatively, you can create user objects that contain the inetUser or inetAdmin, object class. Both object classes support the memberOf attribute as well.
To configure nested groups, the group must use the extensibleObject object class.

Note

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

8.1.4.3. The MemberOf Plug-in Syntax

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

Example 8.3. Default MemberOf Plug-in Entry

 dn: cn=MemberOf Plugin,cn=plugins,cn=config
 objectClass: top
 objectClass: nsSlapdPlugin
 objectClass: extensibleObject
 cn: MemberOf Plugin  
 nsslapd-pluginPath: libmemberof-plugin  
 nsslapd-pluginInitfunc: memberof_postop_init  
 nsslapd-pluginType: postoperation
 nsslapd-pluginEnabled: on  
 nsslapd-plugin-depends-on-type: database
 memberOfGroupAttr: member  
 memberOfGroupAttr: uniqueMember  
 memberOfAttr: memberOf  
 memberOfAllBackends: on  
 nsslapd-pluginId: memberOf
 nsslapd-pluginVersion: X.Y.Z
 nsslapd-pluginVendor: Red Hat, Inc.
 nsslapd-pluginDescription: memberOf plugin
For details about the parameters used in the example and other parameters you can set, see the MemberOf Plug-in Attributes section in the Red Hat Directory Server Command, Configuration, and File Reference.

Note

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

8.1.4.4. Enabling the MemberOf Plug-in

This section describes how to enable the MemberOf plug-in.
8.1.4.4.1. Enabling the MemberOf Plug-in Using the Command Line
Enable the MemberOf plug-in using the command line:
  1. Use the dsconf utility to enable the plug-in:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof enable
  2. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.
8.1.4.4.2. Enabling the MemberOf Plug-in Using the Web Console
Enable the MemberOf plug-in using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select the Plugins menu.
  4. Select the MemberOf plug-in.
  5. Change the status to ON to enable the plug-in.
  6. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

8.1.4.5. Configuring the MemberOf Plug-in on Each Server

If you do not want to replicate the configuration of the MemberOf plug-in, configure the plug-in manually on each server.
8.1.4.5.1. Configuring the MemberOf Plug-in on Each Server Using the Command Line
To configure the MemberOf plug-in using the command line:
  1. To retrieve members of a group from a different attribute than member, which is the default, set the memberOfGroupAttr parameter to the respective attribute name.
    For example, to read group members from uniqueMember attributes, replace the current value of memberOfGroupAttr:
    1. Optionally, display the attribute that is currently configured:
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof show
      ...
      memberofgroupattr: member
      ...
      The command displays that currently only the member attribute is configured to retrieve members of a group.
    2. Remove all attributes from the configuration that currently set:
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof edit --groupattr delete
      Successfully changed the cn=MemberOf Plugin,cn=plugins,cn=config

      Note

      It is not possible to remove a specific group attribute.
    3. Add the uniqueMember attribute to the configuration:
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof edit --groupattr uniqueMember
      successfully added memberOfGroupAttr value "uniqueMember"
      To set multiple attributes, pass them all to the --groupattr parameter. For example:
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof edit --groupattr member uniqueMember ...
  2. By default, the MemberOf plug-in adds the memberOf attribute to user entries. To use a different attribute, set the name of the attribute in the memberOfAttr parameter.
    For example, to add the customMemberOf attribute to user records, replace the current value of memberOfAttr:
    1. Optionally, display the attribute that is currently configured:
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof show
      ...
      memberofattr: memberOf
      ...
    2. Configure the MemberOf plug-in to add the customMemberOf attribute to user entries:
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof edit --attr customMemberOf
      memberOfAttr set to "customMemberOf"

      Note

      You can only set this parameter to an attribute that supports DN syntax.
  3. In an environment that uses distributed databases, you can configure the plug-in to search user entries in all databases instead of only the local database:
    dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof edit --allbackends on
    memberOfAllBackends enabled successfully
  4. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.
8.1.4.5.2. Configuring the MemberOf Plug-in on Each Server Using the Web Console
To configure the MemberOf plug-in using the command line:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select the memberOf plug-in.
  5. Change the status to ON to enable the plug-in.
  6. Fill the fields to configure the plug-in. For example, to configure that the plug-in adds the customMemberOf attribute to user entries if the uniqueMember attribute is added to a group:
  7. Click Save.
  8. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

8.1.4.6. Using the MemberOf Plug-in Shared Configuration

By default, the configuration of the MemberOf plug-in is stored on each server. Using the shared configuration feature of the plug-in, the configuration can be stored outside of the cn=config suffix and replicated. Administrators can use the same settings without configuring the plug-in manually on each server.
  1. Add the shared configuration entry for the MemberOf plug-in. For example:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof config-entry add "cn=shared_MemberOf_config,dc=example,dc=com" --groupattr "member" --attr "memberOf"
    This automatically enables the shared configuration entry on the server on which you ran the command.
  2. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.
  3. On all other servers in the replication topology that should use the shared configuration, enable the shared configuration:
    1. Set the DN that stores the shared configuration. For example:
      # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --config-entry cn=shared_MemberOf_config,dc=example,dc=com
    2. Restart the instance:
      # dsctl instance_name restart
      If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

Important

After enabling the shared configuration, the plug-in ignores all parameters set in the cn=MemberOf Plugin,cn=plugins,cn=config plug-in entry and only uses settings from the shared configuration entry.

8.1.4.7. Setting the Scope of the MemberOf Plug-in

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

Note

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

8.1.4.8. Regenerating memberOf Values

The MemberOf plug-in automatically manages memberOf attributes on group member entries, based on the configuration in the group entry itself. However, the memberOf attribute can be manually edited in a user entry or new entries can be imported or replicated to the server that have a memberOf attribute already set. These situations create inconsistencies between the memberOf configuration managed by the server plug-in and the actual memberships defined in an entry.
For example, to regenerate the memberOf values in dc=example,dc=com entry and subentries:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof fixup -f "dc=example,dc=com"
Attempting to add task entry... This will fail if MemberOf plug-in is not enabled.
Successfully added task entry cn=memberOf_fixup_2018-08-08T17:06:15.663361,cn=memberOf task,cn=tasks,cn=config
Optionally, pass the -f filter option to the command to regenerate the memberOf attributes in user entries matching the filter. If you do not specify a filter, the tasks regenerates the attributes in all entries containing the inetUser, inetAdmin, or nsMemberOf object class.

Note

Regeneration tasks run locally, even if the entries themselves are replicated. This means that memberOf attributes for entries on other servers are not updated until the updated entry is replicated.

8.1.5. Automatically Adding Entries to Specified Groups

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

Note

Members are added or removed according to the auto membership rules on adding and modifying.
For existing entries or entries who are edited to match an automember group rule, there is a fix-up task which can be run that updates the group membership.
The Auto Membership Plug-in can target any type of object stored in the directory: users, machines and network devices, customer data, or other assets.

Note

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

8.1.5.1. Looking at the Structure of an Automembership Rule

The Auto Membership Plug-in itself is a container entry in cn=plugins,cn=config. Group assignments are defined through child entries.
8.1.5.1.1. The Automembership Configuration Entry
Automembership assignments are created through a main definition entry, a child of the Auto Membership Plug-in entry. Each definition entry defines three elements:
  • An LDAP search to identify entries, including both a search scope and a search filter (autoMemberScope and autoMemberFilter)
  • A default group to which to add the member entries (autoMemberDefaultGroup)
  • The member entry format, which is the attribute in the group entry, such as member, and the attribute value, such as dn (autoMemberGroupingAttr)
The definition is the basic configuration for an automember rule. It identifies all of the required information: what a matching member entry looks like and a group for that member to belong to.
For example, this definition assigns all users with the object class set to ntUser to the cn=windows-users group:
dn: cn=Windows Users,cn=Auto Membership Plugin,cn=plugins,cn=config
objectclass: autoMemberDefinition
autoMemberScope: ou=People,dc=example,dc=com
autoMemberFilter: objectclass=ntUser
autoMemberDefaultGroup: cn=windows-group,cn=groups,dc=example,dc=com
autoMemberGroupingAttr: member:dn
For details about the attributes used in the example and other attributes you can set in this entry, see the cn=Auto Membership Plugin,cn=plugins,cn=config entry description in the Red Hat Directory Server Configuration, Command, and File Reference.
8.1.5.1.2. Additional Regular Expression Entries
For something like a users group, where more than likely all matching entries should be added as members, a simple definition is sufficient. However, there can be instances where entries that match the LDAP search filter should be added to different groups, depending on the value of some other attribute. For example, machines may need to be added to different groups depending on their IP address or physical location; users may need to be in different groups depending on their employee ID number.
The automember definition can use regular expressions to provide additional conditions on what entries to include or exclude from a group, and then a new, specific group to add those selected entries to.
For example, an automember definition sets all machines to be added to a generic host group.

Example 8.4. Automember Definition for a Host Group

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

Example 8.5. Regular Expression Condition for a Web Server Group

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

Figure 8.1. Regular Expression Conditions

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

Table 8.2. Regular Expression Condition Attributes

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

Note

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

8.1.5.2. Configuring Auto Membership Definitions

To use the Auto Membership plug-in, create definitions for the plug-in.
8.1.5.2.1. Configuring Auto Membership Definitions Using the Command Line
To create Auto Membership definitions using the command line:
  1. Enable the Auto Membership plug-in:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin automember enable
    Enabled Auto Membership Plugin
  2. Create a Auto Membership definition. For example:
    #  dsconf -D "cn=Directory Manager" ldap://server.example.com plugin automember definition definition_name add --default-group "cn=windows-group,cn=groups,dc=example,dc=com" --scope "ou=People,dc=example,dc=com" --filter "objectclass=ntUser" --grouping-attr "member:dn"
    Automember definition created successfully!
  3. Optionally, you can set further parameters in an Auto Membership definition, for example, to use regular expressions to identify entries to include.Use the ldapmodify utility to add or update these parameters in the cn=definition_name,cn=Auto Membership Plugin,cn=plugins,cn=config entry. For parameters you can set, see cn=Auto Membership Plugin,cn=plugins,cn=config entry description in the Red Hat Directory Server Configuration, Command, and File Reference.
  4. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.
8.1.5.2.2. Configuring Auto Membership Definitions Using the Web Console
To create Auto Membership definitions using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select the Auto Membershipplug-in.
  5. Change the status to ON to enable the plug-in.
  6. Click Add Definition.
  7. Fill the fields. For example:
  8. Optionally, add a regular expression filter.
  9. Click Save.
  10. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

8.1.5.3. Updating Existing Entries to apply Auto Membership Definitions

The Auto Membership plug-in runs when new entries are added to the directory or existing entries are changed.
You can create a directory server task operation to check existing entries against Auto Membership.
To create the task entry:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin automember fixup -f "filter" -s scope
When the task is completed, the entry is removed from the directory configuration.

8.1.5.4. Examples of Automembership Rules

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

Example 8.6. Host Groups by IP Address

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

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

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

Example 8.7. Windows User Group

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

Example 8.8. User Groups by Employee Type

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

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

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

8.1.5.5. Testing Automembership Definitions

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

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

This task requires the same information as the cn=automember rebuild membership task — the base DN to search, search filter, and search scope — and has an additional parameter to specify an export LDIF file to record the proposed entry updates.
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

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

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

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

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

8.2. Using Roles

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

8.2.1. About Roles

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

Note

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

8.2.2. Creating a Managed Role

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

8.2.2.1. Creating Managed Roles through the Command Line

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

8.2.3. Creating a Filtered Role

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

8.2.3.1. Creating a Filtered Role through the Command Line

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

8.2.4. Creating a Nested Role

Nested roles are roles that contain other roles. Before it is possible to create a nested role, another role must exist. The roles nested within the nested role are specified using the nsRoleDN attribute.

8.2.4.1. Creating Nested Role through the Command Line

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

8.2.5. Viewing Roles for an Entry through the Command Line

Role assignments are not returned automatically through the command line.
The nsRole attribute is an operational attribute. In LDAP, operational attributes must be requested explicitly. They are not returned by default with the regular attributes in the schema of the entry. You can either explicitly request single operational attributes by listing them or use + to output all operational attributes for result objects. For example, this ldapsearch command returns the list of roles of which uid=user_name is a member, in addition to the regular attributes for the entry:
# ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com -b "dc=example,dc=com" -s sub -x "(uid=user_name)"” \* nsRole

dn: uid=user_name,ou=people,dc=example,dc=com
...
nsRole: cn=Role for Managers,dc=example,dc=com
nsRole: cn=Role for Accounting,dc=example,dc=com

8.2.6. About Deleting Roles

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

8.2.7. Using Roles Securely

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

8.3. Automatically Creating Dual Entries

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

8.3.1. About Managed Entries

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

8.3.1.1. About the Instance Definition Entry

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

Figure 8.2. Defining Managed Entries

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

8.3.1.2. About the Template Entry

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

Note

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

Figure 8.3. Templates, Managed Entries, and Origin Entries

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

Note

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

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

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

8.3.1.4. Managed Entries Plug-in and Directory Server Operations

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

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

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

8.3.2. Creating the Managed Entries Template Entry

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

Note

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

Table 8.4. Attributes for the Managed Entry Template

Attribute Description
mepTemplateEntry (object class) Identifies the entry as a template.
cn Gives the common name of the entry.
mepMappedAttr Contains an attribute-token pair that the plug-in uses to create an attribute in the managed entry with a value taken from the originating entry.
mepRDNAttr Specifies which attribute to use as the naming attribute in the managed entry. The attribute used as the RDN must be a mapped attribute for the configuration to be valid.
mepStaticAttr Contains an attribute-value pair that will be used, with that specified value, in the managed entry.
To create a template entry:
Use the dsconf plugin managed-entries template add command to add the template entry. For example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin managed-entries template "cn=Posix User Template,ou=templates,dc=example,dc=com" add --rdn-attr "cn" --static-attr "objectclass: posixGroup" --mapped-attr "cn: $cn Group Entry" "gidNumber: $gidNumber" "memberUid: $uid"

8.3.3. Creating the Managed Entries Instance Definition

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

Note

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

Table 8.5. Attributes for the Managed Entries Definition Entry

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

Note

The Managed Entries Plug-in is enabled by default. If this plug-in is disabled, then re-enable it as described in Section 1.10.3, “Enabling and Disabling Plug-ins”.
To create an instance:
  1. Create the new plug-in instance below the cn=Managed Entries,cn=plugins,cn=config container entry. For example:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin managed-entries config "cn=instance,cn=Managed Entries,cn=plugins,cn=config" add --scope="ou=people,dc=example,dc=com" --filter="objectclass=posixAccount" --managed-base="ou=groups,dc=example,dc=com" --managed-template="cn=Posix User-Group Template,ou=Templates,dc=example,dc=com"
    This command sets the scope and filter for the origin entry search, the location of the new managed entries, and the template entry to use.
  2. If the Directory Server is not configured to enable dynamic plug-ins, restart the server to load the modified new plug-in instance:
    # dsctl instance_name restart

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

As Section 8.3.1, “About Managed Entries” highlights, different instances of the Managed Entries Plug-in are created as children beneath the container plug-in entry in cn=plugins,cn=com. (This is common for plug-ins which allow multiple instances.) The drawback to this is that the configuration entries in cn=plugins,cn=com are not replicated, so the configuration has to be re-created on each Directory Server instance.
The Managed Entries Plug-in entry allows the nsslapd-pluginConfigArea attribute. This attribute to another container entry, in the main database area, which contains the plug-in instance entries. This container entry can be in a replicated database, which allows the plug-in configuration to be replicated.
  1. Create a container entry. For example, to create an entry that points back to the container entry, enter:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin managed-entries set --config-area="cn=managed entries container,ou=containers,dc=example,dc=com"

8.4. Using Views

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

8.4.1. About Views

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

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

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

Note

There is a sample LDIF file with example views entries, Example-views.ldif, installed with Directory Server. This file is in the /usr/share/dirsrv/data/ directory on Red Hat Enterprise Linux 7. The sections in this chapter assume Example-views.ldif is imported to the server.
The Red Hat Directory Server Deployment Guide has more information on how to integrate views with the directory tree hierarchy.

8.4.2. Creating Views from the Command Line

  1. Use the ldapmodify utility to bind to the server and prepare it to add the new view entry to the configuration file.
  2. Assuming the view container ou=Location Views,dc=example,dc=com from the Example-views.ldif file is in the Directory Server, add the new views container entry, in this example, under the dc=example,dc=com root suffix. This entry must have the nsview object class and the nsViewFilter attribute. The nsViewFilter attribute sets the attribute-value which identifies entries that belong in the view.
    dn: ou=Mountain View,ou=Location Views,dc=example,dc=com
    changetype: add
    objectClass: top
    objectClass: organizationalUnit
    objectClass: nsview
    ou: Mountain View
    nsViewFilter: l=Mountain View
    description: views categorized by location

8.4.3. Improving Views Performance

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

Chapter 9. Configuring Secure Connections

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

9.1. Requiring Secure Connections

Directory Server provides the following ways of using encrypted connections:
LDAPS
When you use the LDAPS protocol, the connection starts using encryption and either succeeds or fails. However, no unencrypted data is ever send over the network. For this reason, prefer LDAPS instead of using STARTTLS over unencrypted LDAP.
STARTTLS over LDAP
Clients establish an unencrypted connection over the LDAP protocol and then send the STARTTLS command. If the command succeeds, all further communication is encrypted.

Warning

If the STARTTLS command fails and the client does not cancel the connection, all further data, including authentication information, is sent unencrypted over the network.
SASL
Simple Authentication and Security Layer (SASL) enables you to authenticate a user using external authentication methods, such as Kerberos. For details, see Section 9.9, “Setting up SASL Identity Mapping”.

9.2. Setting a Minimum Strength Factor

For additional security, the Directory Server can be configured to require a certain level of encryption before it allows a connection. The Directory Server can define and require a specific Security Strength Factor (SFF) for any connection. The SSF sets a minimum encryption level, defined by its key strength, for any connection or operation.
To require a minimum SSF for any and all directory operations, set the nsslapd-minssf configuration attribute. When enforcing a minimum SSF, Directory Server looks at each available encryption type for an operation — TLS or SASL — and determines which has the higher SSF value and then compares the higher value to the minimum SSF. It is possible for both SASL authentication and TLS to be configured for some server-to-server connections, such as replication.

Note

Alternatively, use the nsslapd-minssf-exclude-rootdse configuration attribute. This sets a minimum SSF setting for all connections to the Directory Server except for queries against the root DSE. A client may need to obtain information about the server configuration, like its default naming context, before initiating an operation. The nsslapd-minssf-exclude-rootdse attribute allows the client to get that information without having to establish a secure connection first.
The SSF for a connection is evaluated when the first operation is initiated on a connection. This allows STARTTLS and SASL binds to succeed, even though those two connections initially open a regular connection. After the TLS or SASL session is opened, then the SSF is evaluated. Any connection which does not meet the SSF requirements is closed with an LDAP unwilling to perform error.
Set a minimum SSF to disable insecure connections to a directory.

Warning

If you connect to the directory using the unencrypted LDAP protocol without SASL, the first LDAP message can contain the bind request. In this case, the credentials are sent unencrypted over the network before the server cancels the connection, because the SSF did not met the minimum value set.
Use the LDAPS protocol or SASL binds to ensure that the credentials are never sent unencrypted.
The default nsslapd-minssf attribute value is 0, which means there is no minimum SSF for server connections. The value can be set to any reasonable positive integer. The value represents the required key strength for any secure connection.
The following example sets the nsslapd-minssf parameter to 128:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-minssf=128
Successfully replaced "nsslapd-minssf"

Note

An ACI can be set to require an SSF for a specific type of operation, as in Section 18.10.2.4, “Requiring a Certain Level of Security in Connections”.
Secure connections can be required for bind operations by turning on the nsslapd-require-secure-binds attribute, as in Section 19.11.1, “Requiring Secure Binds”.

9.3. Managing the NSS Database Used by Directory Server

To use TLS encryption or certificate-based authentication, you must manage the certificates in a Network Security Services (NSS) database. When you created the instance, the dscreate utility automatically created this database in the /etc/dirsrv/slapd-instance_name/ directory and protected it with a strong password. The utility stored the password in the /etc/dirsrv/slapd-instance_name/pwdfile.txt file. Note that Directory Server does not use this file. The dscreate utility only created this file to provide the password to the administrator. For details about changing the password, see Section 9.3.9, “Changing the Password of the NSS Database”.
This section describes the most frequent actions about managing the Directory Server's NSS database.

9.3.1. Creating a Certificate Signing Request

The Certificate Signing Request (CSR) is a request to the Certificate Authority (CA) to sign the key of the server. This section describes how to create the CSR including the private key.

Note

Directory Server supports only creating a private key and CSR directly in the NSS database using the certutil utility.

9.3.1.1. Creating a Certificate Signing Request Using the Command Line

To create the key and a CSR, use the certutil utility:
# certutil -d instance_directory -R -g key_size -a \
     -o output_file -8 FQDN -s "certificate_subject"
For example, to generate a 4096 bit private key for the server.example.com host and to store the CSR in the /root/instance_name.csr file:
# certutil -d /etc/dirsrv/slapd-instance_name/ -R -g 4096 -a \
     -o /root/instance_name.csr -8 server.example.com \
     -s "CN=server.example.com,O=example_organization,OU=IT,ST=North Carolina,C=US"
The string specified in the -s parameter must be a valid subject name according to RFC 1485. The CN field is required, and you must set it to the Fully-qualified Domain Name (FQDN) of the server. The other fields are optional.
For further details about using certutil, see the certutil(1) man page.
After you generated the CSR, submit it to the CA to get a certificate issued. For further details, see your CA's documentation.

9.3.2. Installing a CA Certificate

To enable Directory Server to trust the Certificate Authority (CA) you must install the certificate of the CA into the Network Security Services (NSS) database. During this process, you must set which certificates issued by the CA should be trusted:

Table 9.1. CA Trust Options

Web Console Option dsconf and certutil Option Description
(C) Trusted CA C,, The server verifies that certificates, used to establish an encrypted connection to a replication partner, have been issued by a trusted CA.
(T) Trusted CA Client Auth T,, The server trusts this CA certificate for issuing client certificates suitable for TLS EXTERNAL binds.
You can set both options for a CA. When you use certutil, pass the -T "CT,," parameter to the utility.

9.3.2.1. Installing a CA Certificate Using the Command Line

To install a CA certificate:
  1. Import the CA certificate. For example, to import the CA certificate stored in the /root/ca.crt file and store it in the database with the Example CA nick name:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security ca-certificate add --file /root/server.example.com.crt --name "Example CA"
  2. Set the trust options. For example, to set the CT,, trust flags:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security ca-certificate set-trust-flags "Example CA" --flags "CT,,"

9.3.2.2. Installing a CA Certificate Using the Web Console

To install a CA certificate using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Security menu
  4. Open the Certificate Management tab.
  5. Click Add CA Certificate.
  6. Enter the path to the CA certificate file and a nickname for the certificate.
    Adding a CA Certificate

    Figure 9.1. Adding a CA Certificate

    Note

    The CA certificate must be stored locally on the Directory Server host and must be readable by the dirsrv user.
  7. Click Add Certificate.
  8. Click Actions next to the imported CA certificate, and select Edit Trust Flags.
  9. Select (C) - Trusted CA and (T) - Trusted CA Client Auth in the SSL column.
    Adding Trust Flags of a CA Certificate

    Figure 9.2. Adding Trust Flags of a CA Certificate

9.3.3. Installing a Server Certificate

After the Certificate Authority (CA) issued the requested certificate, you must install it in the Network Security Services (NSS) database.

9.3.3.1. Installing a Server Certificate Using the Command Line

To install a server certificate in the Directory Server's NSS database, use the certutil utility. For example:
  1. Install the CA certificate. See Section 9.3.2, “Installing a CA Certificate”.
  2. Import the server certificate. For example to import the certificate stored in the /root/instance_name.crt file, and set it as the primary certificate the instance uses:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security certificate add --file /root/instance_name.crt --name "server-cert" --primary-cert

9.3.3.2. Installing a Server Certificate Using the Web Console

To install a server certificate using the web console:
  1. Install the CA certificate. See Section 9.3.2, “Installing a CA Certificate”.
  2. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  3. Select the instance.
  4. Open the Security menu
  5. Open the Certificate Management tab.
  6. Open the TLS-Certificates tab.
  7. Click Add Server Certificate.
  8. Enter the path to the server certificate file and a nickname for the certificate.
    Adding a Server Certificate

    Figure 9.3. Adding a Server Certificate

    Note

    The server certificate must be stored locally on the Directory Server host and must be readable by the dirsrv user.
  9. Click Add Certificate.

9.3.4. Generating and Installing a Self-signed Certificate

When you created the instance with TLS enabled using the dscreate utility, dscreate automatically created and installed a self-signed certificate. However, if you did not enable TLS during instance creation, you can manually create and install a self-signed certificate.

Note

You can only perform this operation using the command line.
To create and install a self-signed certificate:
  1. Generate a noise file with random data. For example, to generate a file with a size of 4096 bits:
    # openssl rand -out /tmp/noise.bin 4096
  2. Create the self-signed certificate and add it to the NSS database:
    # certutil -S -x -d /etc/dirsrv/slapd-instance_name/ -z /tmp/noise.bin \
         -n "server-cert" -s "CN=$HOSTNAME" -t "CT,C,C" -m $RANDOM \
         --keyUsage digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment
    Red Hat Enterprise Linux automatically replaces the $HOSTNAME variable with the Fully-qualified Domain Name (FQDN) and $RANDOM with a randomly-generated number. For further details about the parameters used in the previous commands, see the certutil(1) man page.
  3. Optionally, verify that the generated certificate is self-signed:
    # certutil -L -d /etc/dirsrv/slapd-instance_name/ -n "server-cert" | egrep "Issuer|Subject"
            Issuer: "CN=server.example.com"
            Subject: "CN=server.example.com"
    The output of this command must display the FQDN of the Directory Server host for both the issuer and subject of the certificate.

9.3.5. Renewing a Certificate

If a certificate will expire in the near future, you must renew it in time to continue establishing secure connections.

9.3.5.1. Renewing a Certificate Using the Command Line

To renew a certificate:
  1. Create a new Certificate Signing Request (CSR) with the same options, such as key size, host name, and subject. For details about creating a CSR, see Section 9.3.1.1, “Creating a Certificate Signing Request Using the Command Line”
  2. After you received the issued certificate from your CA, install it in the database using the same nickname. See Section 9.3.2.1, “Installing a CA Certificate Using the Command Line”.
Directory Server will automatically use the newer issued certificate.

9.3.6. Removing a Certificate

If a certificate is no longer needed, for example, because it has been exposed, remove it from the database.

9.3.6.1. Removing a Certificate Using the Command Line

To remove a certificate using the command line:
  1. Optionally, display the certificates in the database:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security certificate list
    
    Certificate Name: server-cert
    Subject DN: CN=server.example.com
    Issuer DN: CN=Example CA
    Expires: 2022-07-29 11:10:14
    Trust Flags: ,,
  2. Remove the certificate. For example, to remove the certificate with the server-cert nickname:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security certificate del server-cert

9.3.6.2. Removing a Certificate Using the Web Console

To remove a certificate using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Security menu
  4. Open the Certificate Management tab.
  5. Open the TLS-Certificates tab.
  6. Click Actions next to the certificate, and select Delete Certificate.
  7. Click Yes.

9.3.7. Removing a Private Key

If a private key is no longer needed, for example, because you created a stronger key, remove it from the database.

Warning

If you remove a private key, certificates based on this key are no longer working.

9.3.7.1. Removing a Private Key Using the Command Line

To remove a private key:
  1. Remove all certificates based on the key you want to delete. See Section 9.3.6, “Removing a Certificate”.
  2. Optionally, display the keys in the database:
    # certutil -d /etc/dirsrv/slapd-instance_name/ -K
    certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate Services"
    Enter Password or Pin for "NSS Certificate DB":
    < 0> rsa      7a2fb6c269d83c4036eac7e4edb6aaf2ed08bc4a   server-cert
    < 1> rsa      662b826aa3dd4ca7fd7e6883558cf3866c42f4e2   example-cert
  3. Remove the private key. For example, to remove the private key with the example-cert nickname:
    # certutil -d /etc/dirsrv/slapd-instance_name/ -F -n "example-cert"

9.3.8. Changing the CA Trust Options

In certain situations you need to update the trust option of a Certificate Authority (CA). This section describes this procedure.

9.3.8.1. Changing the CA Trust Options Using the Command Line

To change the trust options of a CA, pass the new options in the --flags parameter to the dsconf security ca-certificate set-trust-flags command.
For example, to set that Directory Server trusts only client authentication certificates issued by the CA named example-CA:
# dsconf -D "cn=Directory Manager" ldap://server.example.com security ca-certificate set-trust-flags "example-CA" --flags "T,,"
The --flags trust_options parameter sets which certificates issued by the CA should be trusted. See Table 9.1, “CA Trust Options”.

9.3.8.2. Changing the CA Trust Options Using the Web Console

To change the trust options of a CA using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Security menu
  4. Open the Certificate Management tab.
  5. On the Trusted Certificate Authorities tab, click Actions next to the imported CA certificate, and select Edit Trust Flags.
  6. Select the trust flags. For example:
    Setting the Trust Flags of a CA Certificate

    Figure 9.4. Setting the Trust Flags of a CA Certificate

9.3.9. Changing the Password of the NSS Database

In certain situations, administrators want to change the password of the Network Security Services (NSS) database. This section describes this process.

Important

If you use a password file to enable Directory Server to automatically open the Network Security Services (NSS) database, you must update the file after you set the new password. See Section 9.4.1.5, “Creating a Password File for Directory Server”.

9.3.9.1. Changing the Password of the NSS Database Using the Command Line

To change the password of the NSS database:
# certutil -d /etc/dirsrv/slapd-instance_name -W
Enter Password or Pin for "NSS Certificate DB":
Enter a password which will be used to encrypt your keys.
The password should be at least 8 characters long,
and should contain at least one non-alphabetic character.

Enter new password: 
Re-enter password: 
Password changed successfully.

9.4. Enabling TLS

Directory Server supports encrypted connections between clients and the server, as well as between servers in a replication environment. For this, Directory Server supports:
  • The LDAPS protocol: TLS encryption is used directly after the connection has been established.
  • The STARTTLS command over the LDAP protocol: The connection is unencrypted until the client sends the STARTTLS command.

Important

For security reasons, Red Hat recommends enabling TLS encryption.
You can use TLS with simple authentication using a bind Distinguished Name (DN) and password, or using certificate-based authentication.
Directory Server's cryptographic services are provided by Mozilla Network Security Services (NSS), a library of TLS and base cryptographic functions. NSS includes a software-based cryptographic token which is Federal Information Processing Standard (FIPS) 140-2 certified.

9.4.1. Enabling TLS in Directory Server

This section describes how to enable TLS in Directory Server.

9.4.1.1. Enabling TLS in Directory Server Using the Command Line

To enable TLS using the command line:
  1. Request and install the certificate:
  2. Enable TLS and set the LDAPS port:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-securePort=636 nsslapd-security=on
    Successfully replaced "nsslapd-securePort"
    Successfully replaced "nsslapd-security"
  3. Display the name of the server certificate in the NSS database:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security certificate list
    
    Certificate Name: server-cert
    Subject DN: CN=server.example.com
    Issuer DN: CN=Example CA
    Expires: 2022-07-29 11:10:14
    Trust Flags: ,,
    You need the nickname in the next step.
  4. To enable the RSA cipher family, setting the NSS database security device, and the server certificate name:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security rsa set -tls-allow-rsa-certificates on --nss-token "internal (software)" --nss-cert-name server-cert

    Note

    By default, the name of the security device in the NSS database is internal (software).
  5. Optionally, update the list of ciphers Directory Server supports. For details, see Section 9.4.1.3.2, “Displaying and Setting the Ciphers Used by Directory Server Using the Command Line”.
  6. Optionally, enable certificate-based authentication. For details, see Section 9.8, “Using Certificate-based Client Authentication”.
  7. Optionally, create a password file to enable Directory Server to start without prompting for the password of the NSS database. For details, see Section 9.4.1.5, “Creating a Password File for Directory Server”.
  8. Restart the Directory Server instance:
    # dsctl instance_name restart
    If you set a password on the NSS database and did not create a password file, Directory Server prompts for the password of the NSS database. For details, see Section 9.4.1.4, “Starting Directory Server Without a Password File”.

9.4.1.2. Enabling TLS in Directory Server Using the Web Console

To enable TLS in Directory Server using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Import the Certificate Authority (CA) certificate. See Section 9.3.2.2, “Installing a CA Certificate Using the Web Console”.
  4. Import the server certificate issued by the CA. See Section 9.3.3.2, “Installing a Server Certificate Using the Web Console”.
  5. Open the Security menu.
  6. On the Security Configuration tab, click Security Enabled.
  7. Optionally, change the server secure port (LDAPS).
  8. Optionally, change the settings for the minimum and maximum TLS version that the server should support.
  9. Optionally, enable users by setting Client Authentication to authenticate using certificates. See Section 9.8, “Using Certificate-based Client Authentication”.
  10. Click Save Configuration.
  11. Optionally, create a password file to enable Directory Server to start without prompting for the password of the NSS database. For details, see Section 9.4.1.5, “Creating a Password File for Directory Server”.
  12. If you set a password on the NSS database and did not create a password file, Directory Server prompts for the password of the NSS database. For details, see Section 9.4.1.4, “Starting Directory Server Without a Password File”.

9.4.1.3. Setting Encryption Ciphers

Directory Server supports different ciphers, and you can enable or disable them. A cipher is the algorithm used in encryption. When a client initiates a TLS connection with a server, the client tells the server what ciphers it prefers to encrypt information. If the server supports at least one of these ciphers, the encrypted connection can be established using this algorithm.
If you enabled encryption according to Section 9.4, “Enabling TLS”, you can display and update the ciphers Directory Server uses.
9.4.1.3.1. Displaying the Default Ciphers
If the nsSSL3Ciphers parameter is not set in the cn=encryption,cn=config entry, Directory Server uses the default ciphers of the Network Security Service (NSS). To display the default ciphers:
# /usr/lib64/nss/unsupported-tools/listsuites | grep -B1 --no-group-separator "Enabled"         
TLS_AES_128_GCM_SHA256:
  0x1301 TLS 1.3 TLS 1.3 AES-GCM  128 AEAD   Enabled  FIPS Domestic            
TLS_CHACHA20_POLY1305_SHA256:
  0x1303 TLS 1.3 TLS 1.3 CHACHA20POLY1305 256 AEAD   Enabled       Domestic
...
9.4.1.3.2. Displaying and Setting the Ciphers Used by Directory Server Using the Command Line

Displaying all Available Ciphers

To display the list of all available ciphers supported in Directory Server:
# ldapsearch -xLLL -H ldap://server.example.com:389 -D "cn=Directory Manager" -W \
     -b 'cn=encryption,cn=config' -s base nsSSLSupportedCiphers -o ldif-wrap=no

dn: cn=encryption,cn=config
nsSSLSupportedCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256::AES-GCM::AEAD::128
...
nsSSLSupportedCiphers: SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5::RC2::MD5::128
This is only a list of available ciphers you can enable or disable. The list does not display the ciphers Directory Server currently uses.

Displaying the Ciphers Directory Server Uses

The ciphers Directory Server currently uses are stored in the nsSSLEnabledCiphers read-only attribute. To display them:
# ldapsearch -xLLL -H ldap://server.example.com:389 -D "cn=Directory Manager" -W \
     -b 'cn=encryption,cn=config' -s base nsSSLEnabledCiphers -o ldif-wrap=no

dn: cn=encryption,cn=config
nsSSLEnabledCiphers: TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256::CHACHA20POLY1305::AEAD::256
nsSSLEnabledCiphers: TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256::CHACHA20POLY1305::AEAD::256
...
Additionally, you can display the ciphers which are configured to be enabled and disabled:
# dsconf -D "cn=Directory Manager" ldap://server.example.com security ciphers list
default
+tls_rsa_aes_128_sha
+tls_rsa_aes_256_sha
...
The default keyword refers to the preferred default ciphers provided by the NSS. See Section 9.4.1.3.1, “Displaying the Default Ciphers”.

Important

Directory Server uses the settings from the nsSSL3Ciphers attribute to generate the list of ciphers which are actually used. However, if you enabled weak ciphers in nsSSL3Ciphers, but set the allowWeakCiphers parameter to off, which is the default, Directory Server only uses the strong ciphers and displays them in the nsSSLSupportedCiphers read-only attribute.

Updating the List of Enabled Ciphers

To update the list of enabled ciphers:
  1. Display the list of currently enabled ciphers. See the section called “Displaying the Ciphers Directory Server Uses”.
  2. To enable only specific ciphers, update the nsSSL3Ciphers attribute. For example, to enable only the TLS_RSA_WITH_AES_128_GCM_SHA256 cipher:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security ciphers set "-all,+TLS_RSA_WITH_AES_128_GCM_SHA256"
  3. Restart the Directory Server instance:
    # dsctl instance_name restart
  4. Optionally, display the list of enabled ciphers to verify the result. See the section called “Displaying the Ciphers Directory Server Uses”.
9.4.1.3.3. Displaying and Setting the Ciphers Used by Directory Server Using the Web Console
To select and optionally update the ciphers using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Security menu.
  4. On the Cipher Preferences tab, Directory Server displays the currently enabled ciphers.
  5. Select Default Ciphers in the Ciphers Suite field to automatically enable the default ciphers. For details, see Section 9.4.1.3.1, “Displaying the Default Ciphers”.
    Alternatively, you can set Ciphers Suite to:
    • All Ciphers to enable all ciphers. Optionally, disable specific ciphers in the Deny Specific Ciphers field.
    • No Ciphers to disable all ciphers. Optionally, enable specific ciphers in the Allow Specific Ciphers field.
  6. Click Save Cipher Preferences.
  7. If you updated the list of ciphers, restart the Directory Server instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”

9.4.1.4. Starting Directory Server Without a Password File

If you start Directory Server with encryption enabled and a password set on the NSS database:
  • If the ns-slapd Directory Server process is started by the systemctl command, systemd prompts for the password and automatically passes the input to the systemd-tty-ask-password-agent utility. For example:
    # systemctl start dirsrv
    Enter PIN for Internal (Software) Token:
  • In rare cases, when the ns-slapd Directory Server process is not started by the systemctl utility and is detached from the terminal, a message is send to all terminals using the wall command. For example:
    Broadcast message from root@server (Fri 2017-01-01 06:00:00 CET):
    
    Password entry required for 'Enter PIN for Internal (Software) Token:' (PID 1234).
    Please enter password with the systemd-tty-ask-password-agent tool!
    To enter the password, run:
    # systemd-tty-ask-password-agent
    Enter PIN for Internal (Software) Token:

9.4.1.5. Creating a Password File for Directory Server

If encryption is enabled and a password set on the NSS database, Directory Server prompts for this password when the service starts. See Section 9.4.1.4, “Starting Directory Server Without a Password File”.
To bypass this prompt, you can store the NSS database password in the /etc/dirsrv/slapd-instance_name/pin.txt file. This enables Directory Server to start automatically without prompting for this password.

Warning

The password is stored in clear text. Do not use a password file if the server is running in an unsecured environment.
To create the password file:
  1. Create the /etc/dirsrv/slapd-instance_name/pin.txt file with the following content:
    • If you use the NSS software cryptography module, which is the default:
      Internal (Software) Token:password
    • If you use a Hardware Security Module (HSM):
      name_of_the_token:password
  2. Set the permissions:
    # chown dirsrv:dirsrv /etc/dirsrv/slapd-instance_name/pin.txt
    # chmod 400 /etc/dirsrv/slapd-instance_name/pin.txt

9.4.1.6. Managing How Directory Server Behaves If the Certificate Has Been Expired

By default, if encryption is enabled and the certificate has expired, Directory Server logs a warning and the service starts. To change this behavior, set the nsslapd-validate-cert parameter. You can set it to the following values:
  • warn: The Directory Server instance starts and log a warning about the expired certificate into the /var/log/dirsrv/slapd-instance_name/error log file. This is the default setting.
  • on: Directory Server validates the certificate and the instance fails to start if the certificate has expired.
  • off: Directory Server does not validate the certificate expiration date. The instance starts and no warning will be logged.

Example 9.1. Preventing Directory Server to Start If the Certificate Has Been Expired

To prevent Directory Server from starting if the certificate has expired:
  1. Set the nsslapd-validate-cert parameter to on:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-validate-cert=on
    Successfully replaced "nsslapd-validate-cert"
  2. Restart the Directory Server instance:
    # dsctl instance_name restart

9.4.2. Adding the CA Certificate Used By Directory Server to the Trust Store of Red Hat Enterprise Linux

When you enabled TLS encryption in Directory Server, you configured the instance to use a certificate issued by a CA. If a client now establishes a connection to the server using the LDAPS protocol or the STARTTLS command over LDAP, Directory Server uses this certificate to encrypt the connection. Client utilities use the CA certificate to verify if the server's certificate is valid. By default, these utilities cancel the connection if they do not trust the certificate of the server.

Example 9.2. Possible Connection Errors If Clients Utilities Do Not Use the CA Certificate

If client utilities do not use the CA certificate, the utilities cannot validate the server's certificate when using TLS encryption. As a consequence, the connection to the server fails. For example:
  • dsconf
    # dsconf -D "cn=Directory Manager" ldaps://consumer.example.com:636 config get
    Error: {'desc': "Can't contact LDAP server", 'info': 'error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed (self signed certificate in certificate chain)'}
  • ldapsearch
    # ldapsearch -H ldaps://server.example.com:636 -D "cn=Directory Manager" -W -b "dc=example,dc=com" -x
    Enter LDAP Password: 
    ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)
To enable client utilities on Red Hat Enterprise Linux to verify the certificate that Directory Server uses, add the CA certificate to the trust store of the operating system:
  1. If you do not have a local copy of the CA certificate used by Directory Server:
    1. List the certificates in the server's NSS database:
      # certutil -d /etc/dirsrv/slapd-instance_name/ -L
      
      Certificate Nickname                       Trust Attributes
                                                 SSL,S/MIME,JAR/XPI
      
      Example CA                                 C,,  
      server-cert                                u,u,u
    2. Use the nickname of the CA certificate in the NSS database to export the CA certificate:
      # certutil -d /etc/dirsrv/slapd-instance_name/ -L -n "Example CA" -a > /tmp/ds-ca.crt
  2. Copy the CA certificate to the /etc/pki/ca-trust/source/anchors/ directory. For example:
    # cp /tmp/ds-ca.crt /etc/pki/ca-trust/source/anchors/
  3. Rebuild the CA trust database:
    # update-ca-trust

9.5. Displaying the Encryption Protocols Enabled in Directory Server

To display the enabled encryption protocols in Directory Server:
# dsconf -D "cn=Directory Manager" ldap://server.example.com security get
...
sslversionmin: TLS1.2
sslversionmax: TLS1.3
The sslVersionMin and sslVersionMax parameter control which encryption protocol versions Directory Server uses. By default, only TLS 1.2 and later versions of the protocol are enabled.

9.6. Setting the Encryption Protocol Versions

Update the sslVersionMin and sslVersionMax parameters to set which encryption protocols Directory Server uses.

Important

To always use the strongest supported encryption protocol version in the sslVersionMax parameter, do not set this parameter. See Section 9.6.1, “Automatically Using the Strongest Protocol in the sslVersionMax Parameter”.
For example, to enable only 1.3:
  1. Update the sslVersionMin and sslVersionMax parameters:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security set --tls-protocol-min="TLS1.3" --tls-protocol-max="TLS1.3"
    
  2. Restart the Directory Server instance:
    # dsctl instance_name restart

9.6.1. Automatically Using the Strongest Protocol in the sslVersionMax Parameter

If the sslVersionMax parameter is not set, which is the default, Directory Server uses the strongest supported encryption protocol version for this parameter. This enables you to always have the strongest protocol version enabled after an update.

Identifying if sslVersionMax is Not Set

Even if sslVersionMax is not set, the parameter is returned in a search. To identify if the parameter is not set:
# grep sslVersionMax /etc/dirsrv/slapd-instance_name/dse.ldif
If the command displays no output, the parameter is not set and uses the default, which is the strongest supported encryption protocol.

Removing the sslVersionMax Parameter

Remove the sslVersionMax parameter to use its default setting:
  1. Remove the sslVersionMax parameter:
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    dn: cn=encryption,cn=config
    changetype: modify
    delete: sslVersionMax
  2. Restart the Directory Server instance:
    # dsctl instance_name restart

9.7. Using Hardware Security Modules

A security module serves as a medium between the Directory Server and the TLS layer. The module stores the keys and certificates used for encryption and decryption. The standard which defines these modules is Public Key Cryptography Standard (PKCS) #11, so these modules are PKCS#11 modules.
By default, Directory Server uses built-in security databases, key4.db and cert9.db, to store the keys and certificates used by the servers.
It is also possible to use external security devices to store Directory Server certificates and keys. For Directory Server to use an external PKCS#11 module, the module's drivers must be installed in Directory Server.
For more information, consult the documentation for your hardware security module.

9.8. Using Certificate-based Client Authentication

Directory Server supports certificate-based authentication of LDAP clients and for server-to-server connection, such as replication.
Depending on the configuration, the client can or must authenticate using a certificate, if you enabled certificate-based authentication. After verifying the certificate, the server searches for the user in the directory, based on the attributes in the subject field of the certificate. If the search return exactly one user entry, Directory Server uses this user for all further operations. Optionally, you can configure that the certificate used for authentication must match the Distinguished Encoding Rules (DER)-formatted certificate stored in the userCertificate attribute of the user.
Benefits of using certificate-based authentication:
  • Improved efficiency. When using applications that prompt once for the certificate database password and then use that certificate for all subsequent bind or authentication operations, it is more efficient than continuously providing a bind DN and password.
  • Improved security. The use of certificate-based authentication is more secure than non-certificate bind operations because certificate-based authentication uses public-key cryptography. Bind credentials cannot be intercepted across the network. If the certificate or device is lost, it is useless without the PIN, so it is immune from third-party interference like phishing attacks.

9.8.1. Setting up Certificate-based Authentication

To enable certificate-based authentication:
  1. Enable encrypted connections. For details, see Section 9.4, “Enabling TLS”.
  2. Install the CA certificate and set the trust options for client and server connections. See Section 9.3.2, “Installing a CA Certificate”.
  3. Optionally, verify that the CT,, trust options for client and server are set for the CA certificate:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security ca-certificate get "Self-Signed-CA"
    Certificate Name: Example-CA
    Subject DN: CN=server.example.com,ST=Queensland,C=AU
    Issuer DN: CN=server.example.com,,ST=Queensland,C=AU
    Expires: 2021-05-09 10:57:54
    Trust Flags: CT,,
  4. Create the /etc/dirsrv/slapd-instance_name/certmap.conf file to map information from the certificate to Directory Server users. For example:
    certmap default         default
    default:DNComps         dc
    default:FilterComps     mail,cn
    default:VerifyCert      on
    
    certmap example         o=Example Inc.,c=US
    example:DNComps
    This configures that for authenticating users who use a certificate that has the o=Example Inc.,c=US issuer Distinguished Name (DN) set, Directory Server does not generate a base DN from the subject of the certificate, because the DNComps parameter is set empty for this issuer. Additionally, the settings for the FilterComps and VerifyCert are inherited from the default entry.
    Certificates that have a different issuer DN than the specified one will use the settings from the default entry and generate the base DN based on the cn attributes in the subject of the certificate. This enables Directory Server to start the search under a specific DN, without searching the whole directory.
    For all certificates, Directory Server generates the search filter using the mail and the cn attribute from the certificate's subject. However, if the mail does not exist in the subject, Directory Server will automatically use the value of the certificate's e attribute in the subject.
    For further details and descriptions of the available parameters, see the description of the certmap.conf file in the Red Hat Directory Server Configuration, Command, and File Reference.
  5. Enable client authentication. For example, to configure that client authentication is optional:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security set --tls-client-auth="allowed"
    Alternatively, set the --tls-client-auth parameter to required to configure that clients must use a certificate to authenticate.
  6. If you enabled that the authenticating certificate must match the one stored in the userCertificate attribute of the user by setting alias_name:VerifyCert on in the /etc/dirsrv/slapd-instance_name/certmap.conf file, add the certificates to the user entries. See Section 9.8.2, “Adding a Certificate to a User”.

9.8.2. Adding a Certificate to a User

When you set up certificate-based authentication, you can set that the certificate used to authenticate must match the one stored in the userCertificate binary attribute of the user. If you enabled this feature by setting alias_name:VerifyCert on in the /etc/dirsrv/slapd-instance_name/certmap.conf file, you must add the certificate of the affected users to their directory entry.

Important

You must store the certificate in the Distinguished Encoding Rules (DER) format in the userCertificate attribute.
To store a certificate in the userCertificate attribute of a user:
  1. If the certificate is not DER-formatted, convert it. For example:
    # openssl x509 -in /root/certificate.pem -out /root/certificate.der -outform DER
  2. Add the certificate to the user's userCertificate attribute. For example:
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    
    dn: uid=user_name,ou=People,dc=example,dc=com
    changetype: modify
    add: userCertificate
    userCertificate: < /root/example.der
For further details about using binary attributes, see Section 3.8, “Using Binary Attributes”.

9.8.3. Forcing the EXTERNAL SASL Mechanism for Bind Requests

At the beginning of a TLS session, the client sends its certificate to the server. Then, it sends its bind request. Most clients issue the bind request using the EXTERNAL SASL mechanism, which signals Directory Server that it needs to use the identity in the certificate for the bind, instead of the credentials in the bind request.
However, if a client uses simple authentication or anonymous credentials, this information is missing. In this case, the TLS session fails with invalid credentials, even if the certificate and the client identity in the certificate was valid.
To configure that Directory Server forces clients to use the EXTERNAL SASL mechanism and to ignore any other bind method in the request:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-force-sasl-external=on
Successfully replaced "nsslapd-force-sasl-external"

9.8.4. Authenticating Using a Certificate

To use the OpenLDAP client tools, to authenticate to a Directory Server instance that supports authentication using a certificate:
  1. Set the following environment variables to the corresponding paths for the CA certificate, the user key, and the user certificate. For example:
    LDAPTLS_CACERT=/home/user_name/CA.crt
    LDAPTLS_KEY=/home/user_name/user.key
    LDAPTLS_CERT=/home/user_name/user.crt
    Alternatively, set the TLS_CACERT, TLS_KEY, and TLS_CERT parameters in the ~/.ldaprc file. For details, see the TLS OPTIONS section in the ldap.conf(5) man page.
  2. Connect to the server. For example:
    # ldapwhoami -H ldaps://server.example.com:636
If you use a different client, see the client application's documentation for how to connect using certificate-based authentication.

9.9. Setting up SASL Identity Mapping

Simple Authentication and Security Layer (SASL) is an abstraction layer between protocols like LDAP and authentication methods like GSS-API which allows any protocol which can interact with SASL to utilize any authentication mechanism which can work with SASL. Simply put, SASL is an intermediary that makes authenticating to applications using different mechanisms easier. SASL can also be used to establish an encrypted session between a client and server.
The SASL framework allows different mechanisms to be used to authenticate a user to the server, depending on what mechanism is enabled in both client and server applications. SASL also creates a layer for encrypted (secure) sessions. Using GSS-API, Directory Server utilizes Kerberos tickets to authenticate sessions and encrypt data.

9.9.1. About SASL Identity Mapping

When processing a SASL bind request, the server matches, or maps, the SASL authentication ID used to authenticate to the Directory Server with an LDAP entry stored within the server. When using Kerberos, the SASL user ID usually has the format userid@REALM, such as scarter@EXAMPLE.COM. This ID must be converted into the DN of the user's Directory Server entry, such as uid=scarter,ou=people,dc=example,dc=com.
If the authentication ID clearly corresponds to the LDAP entry for a person, it is possible to configure the Directory Server to map the authentication ID automatically to the entry DN. Directory Server has some pre-configured default mappings which handle most common configurations, and customized maps can be created. By default, during a bind attempt, only the first matching mapping rule is applied if SASL mapping fallback is not enabled. For further details about SASL mapping fallback, see Section 9.9.4, “Enabling SASL Mapping Fallback”.
Be sure to configure SASL maps so that only one mapping rule matches the authentication string.
SASL mappings are configured by entries under a container entry:
dn: cn=sasl,cn=config
objectClass: top
objectClass: nsContainer
cn: sasl
SASL identity mapping entries are children of this entry:
dn: cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsContainer
cn: mapping
Mapping entries are defined by the following attributes:
  • nsSaslMapRegexString: The regular expression which is used to map the elements of the supplied authid.
  • nsSaslMapFilterTemplate: A template which applies the elements of the nsSaslMapRegexString to create the DN.
  • nsSaslMapBaseDNTemplate: Provides the search base or a specific entry DN to match against the constructed DN.
  • Optional: nsSaslMapPriority: Sets the priority of this SASL mapping. The priority value is used, if nsslapd-sasl-mapping-fallback is enabled in cn=config. For details, see Section 9.9.4.1, “Setting SASL Mapping Priorities”.
For further details, see the corresponding section in the Red Hat Directory Server Configuration, Command, and File Reference.
For example:
dn: cn=mymap,cn=mapping,cn=sasl,cn=config
objectclass:top
objectclass:nsSaslMapping
cn: mymap
nsSaslMapRegexString: \(.*\)@\(.*\)\.\(.*\)
nsSaslMapFilterTemplate: (objectclass=inetOrgPerson)
nsSaslMapBaseDNTemplate: uid=\1,ou=people,dc=\2,dc=\3
The nsSaslMapRegexString attribute sets variables of the form \1, \2, \3 for bind IDs which are filled into the template attributes during a search. This example sets up a SASL identity mapping for any user in the ou=People,dc=example,dc=com subtree who belongs to the inetOrgPerson object class.
When a Directory Server receives a SASL bind request with mconnors@EXAMPLE.COM as the user ID (authid), the regular expression fills in the base DN template with uid=mconnors,ou=people,dc=EXAMPLE,dc=COM as the user ID, and authentication proceeds from there.

Note

The dc values are not case sensitive, so dc=EXAMPLE and dc=example are equivalent.
The Directory Server can also use a more inclusive mapping scheme, such as the following:
dn: cn=example map,cn=mapping,cn=sasl,cn=config
objectclass: top
objectclass: nsSaslMapping
cn: example map
nsSaslMapRegexString: \(.*\)
nsSaslMapBaseDNTemplate: ou=People,dc=example,dc=com
nsSaslMapFilterTemplate: (cn=\1)
This matches any user ID and map it an entry under the ou=People,dc=example,dc=com subtree which meets the filter cn=userId.
Mappings can be confined to a single realm by specifying the realm in the nsSaslMapRegexString attribute. For example:
dn: cn=example map,cn=mapping,cn=sasl,cn=config
objectclass: top
objectclass: nsSaslMapping
cn: example map
nsSaslMapRegexString: \(.*\)@US.EXAMPLE.COM   
nsSaslMapBaseDNTemplate: ou=People,dc=example,dc=com
nsSaslMapFilterTemplate: (cn=\1)
This mapping is identical to the previous mapping, except that it only applies to users authenticating from the US.EXAMPLE.COM realm. (Realms are described in Section 9.10.2.1, “About Principals and Realms”.)
When a server connects to another server, such as during replication or with chaining, the default mappings for the will not properly map the identities. This is because the principal (SASL identity) for one server does not match the principal on the server where authentication is taking place, so it does not match the mapping entries.
To allow server to server authentication using SASL, create a mapping for the specific server principal to a specific user entry. For example, this mapping matches the ldap1.example.com server to the cn=replication manager,cn=config entry. The mapping entry itself is created on the second server, such as ldap2.example.com.
dn: cn=z,cn=mapping,cn=sasl,cn=config
objectclass: top
objectclass: nsSaslMapping
cn: z
nsSaslMapRegexString: ldap/ldap1.example.com@EXAMPLE.COM
nsSaslMapBaseDNTemplate: cn=replication manager,cn=config
nsSaslMapFilterTemplate: (objectclass=*)
Sometimes, the realm name is not included in the principal name in SASL GSS-API configuration. A second mapping can be created which is identical to the first, only without specifying the realm in the principal name. For example:
dn: cn=y,cn=mapping,cn=sasl,cn=config
objectclass: top
objectclass: nsSaslMapping
cn: y
nsSaslMapRegexString: ldap/ldap1.example.com
nsSaslMapBaseDNTemplate: cn=replication manager,cn=config
nsSaslMapFilterTemplate: (objectclass=*)
Because the realm is not specified, the second mapping is more general (meaning, it has the potential to match more entries than the first. The best practice is to have more specific mappings processed first and gradually progress through more general mappings.
If a priority is not set for a SASL mapping using the nsSaslMapPriority parameter, there is no way to specify the order that mappings are processed. However, there is a way to control how SASL mappings are processed: the name. The Directory Server processes SASL mappings in reverse ASCII order. In the past two example, then the cn=z mapping (the first example) is processed first. If there is no match, the server processes the cn=y mapping (the second example).

Note

SASL mappings can be added when an instance is created during a silent installation by specifying the mappings in an LDIF file and adding the LDIF file with the ConfigFile directive. Using silent installation is described in the Installation Guide.

9.9.2. Default SASL Mappings for Directory Server

The Directory Server has pre-defined SASL mapping rules to handle some of the most common usage.
Kerberos UID Mapping

This matches a Kerberos principal using a two part realm, such as user@example.com. The realm is then used to define the search base, and the user ID (authid) defines the filter. The search base is dc=example,dc=com and the filter of (uid=user).

dn: cn=Kerberos uid mapping,cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsSaslMapping
cn: Kerberos uid mapping
nsSaslMapRegexString: \(.*\)@\(.*\)\.\(.*\)
nsSaslMapBaseDNTemplate: dc=\2,dc=\3
nsSaslMapFilterTemplate: (uid=\1)
RFC 2829 DN Syntax

This mapping matches an authid that is a valid DN (defined in RFC 2829) prefixed by dn:. The authid maps directly to the specified DN.

dn: cn=rfc 2829 dn syntax,cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsSaslMapping
cn: rfc 2829 dn syntax
nsSaslMapRegexString: ^dn:\(.*\)
nsSaslMapBaseDNTemplate: \1
nsSaslMapFilterTemplate: (objectclass=*)
RFC 2829 U Syntax

This mapping matches an authid that is a UID prefixed by u:. The value specified after the prefix defines a filter of (uid=value). The search base is hard-coded to be the suffix of the default userRoot database.

dn: cn=rfc 2829 u syntax,cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsSaslMapping
cn: rfc 2829 u syntax
nsSaslMapRegexString: ^u:\(.*\)
nsSaslMapBaseDNTemplate: dc=example,dc=com
nsSaslMapFilterTemplate: (uid=\1)
UID Mapping

This mapping matches an authid that is any plain string that does not match the other default mapping rules. It use this value to define a filter of (uid=value). The search base is hard-coded to be the suffix of the default userRoot database.

dn: cn=uid mapping,cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsSaslMapping
cn: uid mapping
nsSaslMapRegexString: ^[^:@]+$
nsSaslMapBaseDNTemplate: dc=example,dc=com
nsSaslMapFilterTemplate: (uid=&)

9.9.3. Configuring SASL Identity Mapping

(Simple Authentication and Security Layer) SASL identity mapping can be configured from either the Directory Server or the command line. For SASL identity mapping to work for SASL authentication, the mapping must return one, and only one, entry that matches and Kerberos must be configured on the host machine.

9.9.3.1. Configuring SASL Identity Mapping Using the Command Line

To configure SASL identity mapping from the command line, use the dsconf utility to add the identity mapping scheme.
  1. Add the identity mapping scheme. For example:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com sasl create --cn "example_map" --nsSaslMapRegexString "\(.*\)" --nsSaslMapBaseDNTemplate "ou=People,dc=example,dc=com" --nsSaslMapFilterTemplate "(cn=\1)" --nsSaslMapPriority 50
    Successfully created example_map
    This matches any user's common name and maps it to the result of the subtree search with base ou=People,dc=example,dc=com, based on the filter cn=userId.
  2. Restart the instance:
    # dsctl instance_name restart

Note

Adding the SASL map with dsconf adds the mapping to the end of the list, regardless of its ASCII order.

9.9.3.2. Configuring SASL Identity Mapping Using the Web Console

To add a SASL identity mapping scheme:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select Server SettingsSASL.
  4. Click Create SASL Mapping.
  5. Fill the form. For example:
  6. Click Save.

9.9.4. Enabling SASL Mapping Fallback

Using the default settings, Directory Server verifies only the first matching SASL mapping. If this first matching mapping fails, the bind operation fails and no further matching mappings are verified.
However, you can configure Directory Server to verify all matching mappings by enabling the nsslapd-sasl-mapping-fallback parameter:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-sasl-mapping-fallback=on
Successfully replaced "nsslapd-sasl-mapping-fallback"
If fallback is enabled and only one user identity is returned, the bind succeeds. If no user, or more than one user is returned, the bind fails.

9.9.4.1. Setting SASL Mapping Priorities

If you enabled SASL mapping fallback using the nsslapd-sasl-mapping-fallback attribute, you can optionally set the nsSaslMapPriority attribute in mapping configurations to prioritize them. The nsSaslMapPriority attribute supports values from 1 (highest priority) to 100 (lowest priority). The default is 100.
For example, to set the highest priority for the cn=Kerberos uid mapping,cn=mapping,cn=sasl,cn=config mapping:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=Kerberos uid mapping,cn=mapping,cn=sasl,cn=config
changetype: modify
replace: nsSaslMapPriority
nsSaslMapPriority: 1

9.10. Using Kerberos GSS-API with SASL

Kerberos v5 must be deployed on the host for Directory Server to utilize the GSS-API mechanism for SASL authentication. GSS-API and Kerberos client libraries must be installed on the Directory Server host to take advantage of Kerberos services.

9.10.1. Authentication Mechanisms for SASL in Directory Server

Directory Server support the following SASL encryption mechanisms:
  • PLAIN. PLAIN sends cleartext passwords for simple password-based authentication.
  • EXTERNAL. EXTERNAL, as with TLS, performs certificate-based authentication. This method uses public keys for strong authentication.
  • CRAM-MD5. CRAM-MD5 is a weak, simple challenge-response authentication method. It does not establish any security layer.

    Warning

    Red Hat recommends not using the insecure CRAM-MD5 mechanism.
  • DIGEST-MD5. DIGEST-MD5 is a weak authentication method for LDAPv3 servers.

    Warning

    Red Hat recommends not using the insecure DIGGEST-MD5 mechanism.
  • Generic Security Services (GSS-API). Generic Security Services (GSS) is a security API that is the native way for UNIX-based operating systems to access and authenticate Kerberos services. GSS-API also supports session encryption, similar to TLS. This allows LDAP clients to authenticate with the server using Kerberos version 5 credentials (tickets) and to use network session encryption.
    For Directory Server to use GSS-API, Kerberos must be configured on the host machine. See Section 9.10, “Using Kerberos GSS-API with SASL”.

    Note

    GSS-API and, thus, Kerberos are only supported on platforms that have GSS-API support. To use GSS-API, it may be necessary to install the Kerberos client libraries; any required Kerberos libraries will be available through the operating system vendor.

9.10.2. About Kerberos in Directory Server

On Red Hat Enterprise Linux, the supported Kerberos libraries are MIT Kerberos version 5.
The concepts of Kerberos, as well as using and configuring Kerberos, are covered at the MIT Kerberos website, http://web.mit.edu/Kerberos/.

9.10.2.1. About Principals and Realms

A principal is a user or service in the Kerberos environment. A realm defines what Kerberos manages in terms of who can access what. The client, the KDC, and the host or service you want to access must use the same realm.

Note

Kerberos realms are only supported for GSS-API authentication and encryption, not for DIGEST-MD5.
Realms are used by the server to associate the DN of the client in the following form, which looks like an LDAP DN:
uid=user_name/[server_instance],cn=realm,cn=mechanism,cn=auth
For example, Mike Connors in the engineering realm of the European division of example.com uses the following association to access a server in the US realm:
uid=mconnors/cn=Europe.example.com,cn=engineering,cn=gssapi,cn=auth
Babara Jensen, from the accounting realm of US.example.com, does not have to specify a realm when to access a local server:
uid=bjensen,cn=accounting,cn=gssapi,cn=auth
If realms are supported by the mechanism and the default realm is not used to authenticate to the server, then the realm must be specified in the Kerberos principal. Otherwise, the realm can be omitted.

Note

Kerberos systems treat the Kerberos realm as the default realm; other systems default to the server.

9.10.2.2. About the KDC Server and Keytabs

The Key Distribution Center (KDC) authenticates users and issues Ticket Granting Tickets (TGT) for them. This enables users to authenticate to Directory Server using GSS-API. To respond to Kerberos operations, Directory Server requires access to its keytab file. The keytab contains the cryptographic key that Directory Server uses to authenticate to other servers.
Directory Server uses the ldap service name in a Kerberos principal. For example:
ldap/server.example.com/EXAMPLE.COM
For details about creating the keytab, see your Kerberos documentation.

Note

You must create a Simple Authentication and Security Layer (SASL) mapping for the Directory Server Kerberos principal that maps to an existing entry Distinguished Name (DN).

9.10.3. Configuring SASL Authentication at Directory Server Startup

SASL GSS-API authentication has to be activated in Directory Server so that Kerberos tickets can be used for authentication. This is done by supplying a system configuration file for the init scripts to use which identifies the variable to set the keytab file location. When the init script runs at Directory Server startup, SASL authentication is then immediately active.
The default SASL configuration is stored in the /etc/sysconfig/dirsrv file.
If there are multiple Directory Server instances and not all of them will use SASL authentication, then there can be instance-specific configuration files created in the /etc/sysconfig/ directory named dirsrv-instance. For example, dirsrv-example. The default dirsrv file can be used if there is a single instance on a host.
To enable SASL authentication, uncomment the KRB5_KTNAME line in the /etc/sysconfig/dirsrv (or instance-specific) file, and set the keytab location for the KRB5_KTNAME variable. For example:
# In order to use SASL/GSSAPI the directory
# server needs to know where to find its keytab
# file - uncomment the following line and set
# the path and filename appropriately
KRB5_KTNAME=/etc/dirsrv/krb5.keytab

9.11. Setting SASL Mechanisms

Per default, Directory Server enables all mechanisms the simple authentication and security layer (SASL) library supports. These are listed in the root dse supportedSASLMechanisms parameter. To enable specific SASL mechanisms, set the nsslapd-allowed-sasl-mechanisms attribute in the cn=config entry. For example, to enable only the GSSAPI and DIGEST-MD5 mechanism, run:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-allowed-sasl-mechanisms="GSSAPI, DIGEST-MD5"
Successfully replaced "nsslapd-allowed-sasl-mechanisms"

Note

Even if EXTERNAL is not listed in the nsslapd-allowed-sasl-mechanisms parameter, this mechanism is always enabled.
For further details, see the corresponding section in the Red Hat Directory Server Configuration, Command, and File Reference.

9.12. Using SASL with LDAP Clients

To use SASL with the LDAP clients, such as ldapsearch, pass the -Y SASL_mechanism to the command. For example:
  • To use the GSSAPI SASL mechanism over the LDAP protocol:
    # ldapsearch -Y GSSAPI -U "dn:uid=user_name,ou=people,dc=example,dc=com" -R EXAMPLE.COM -H ldap://server.example.com -b "dc=example,dc=com"
  • To use the PLAIN SASL mechanism over the LDAPS protocol:
    # ldapsearch -Y PLAIN -D "uid=user_name,ou=people,dc=example,dc=com" -W -H ldaps://server.example.com -b "dc=example,dc=com"

Note

SASL proxy authorization is not supported in Directory Server. Therefore, Directory Server ignores any SASL authzid value supplied by the client.

Chapter 10. Configuring Attribute Encryption

The Directory Server offers a number of mechanisms to secure access to sensitive data, such as access control rules to prevent unauthorized users from reading certain entries or attributes within entries and TLS to protect data from eavesdropping and tampering on untrusted networks. However, if a copy of the server's database files should fall into the hands of an unauthorized person, they could potentially extract sensitive information from those files. Because information in a database is stored in plain text, some sensitive information, such as government identification numbers or passwords, may not be protected enough by standard access control measures.
For highly sensitive information, this potential for information loss could present a significant security risk. In order to remove that security risk, Directory Server allows portions of its database to be encrypted. Once encrypted, the data are safe even in the event that an attacker has a copy of the server's database files.
Database encryption allows attributes to be encrypted in the database. Both encryption and the encryption cipher are configurable per attribute per back end. When configured, every instance of a particular attribute, even index data, is encrypted for every entry stored in that database.
An additional benefit of attribute encryption is, that encrypted values can only be sent to a clients with a Security Strength Factor (SSF) greater than 1.

Note

There is one exception to encrypted data: any value which is used as the RDN for an entry is not encrypted within the entry DN. For example, if the uid attribute is encrypted, the value is encrypted in the entry but is displayed in the DN:
dn: uid=jsmith1234,ou=People,dc=example,dc=com
...
uid:: Sf04P9nJWGU1qiW9JJCGRg==
That would allow someone to discover the encrypted value.
Any attribute used within the entry DN cannot be effectively encrypted, since it will always be displayed in the DN. Be aware of what attributes are used to build the DN and design the attribute encryption model accordingly.
Indexed attributes may be encrypted, and attribute encryption is fully compatible with eq and pres indexing. The contents of the index files that are normally derived from attribute values are also encrypted to prevent an attacker from recovering part or all of the encrypted data from an analysis of the indexes.
Since the server pre-encrypts all index keys before looking up an index for an encrypted attribute, there is some effect on server performance for searches that make use of an encrypted index, but the effect is not serious enough that it is no longer worthwhile to use an index.

10.1. Encryption Keys

In order to use attribute encryption, the server must be configured for TLS and have TLS enabled because attribute encryption uses the server's TLS encryption key and the same PIN input methods as TLS. The PIN must either be entered manually upon server startup or a PIN file must be used.
Randomly generated symmetric cipher keys are used to encrypt and decrypt attribute data. A separate key is used for each configured cipher. These keys are wrapped using the public key from the server's TLS certificate, and the resulting wrapped key is stored within the server's configuration files. The effective strength of the attribute encryption is never higher than the strength of the server's TLS key used for wrapping. Without access to the server's private key, it is not possible to recover the symmetric keys from the wrapped copies.

Warning

There is no mechanism for recovering a lost key. Therefore, it is especially important to back up the server's certificate database safely. If the server's certificate were lost, it would not be possible to decrypt any encrypted data stored in its database.

Warning

If the TLS certificate is expiring and needs to be renewed, export the encrypted back end instance before the renewal. Update the certificate, then reimport the exported LDIF file.

10.2. Encryption Ciphers

The encryption cipher is configurable on a per-attribute basis and must be selected by the administrator at the time encryption is enabled for an attribute.
The following ciphers are supported:
  • Advanced Encryption Standard (AES)
  • Triple Data Encryption Standard (3DES)

Note

For strong encryption, Red Hat recommends using only AES ciphers.
All ciphers are used in Cipher Block Chaining mode.
Once the encryption cipher is set, it should not be changed without exporting and reimporting the data.

10.3. Configuring Attribute Encryption

Use the command line or the web console to enable and disable attribute encryption for certain attributes.

10.3.1. Enabling Encryption of an Attribute Using the Command Line

To configure that Directory Server stores, for example, telephoneNumber attributes in the userRoot database AES-encrypted:
  1. Optionally, to encrypt existing telephoneNumber attributes, export the database. See Section 10.4.1, “Exporting an Encrypted Database”.
  2. Enable AES encryption for the telephoneNumber attribute in the userRoot database:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend attr-encrypt --add-attr telephoneNumber userRoot
  3. If you exported the database to encrypt also existing attributes, reimport the database. See Section 10.4.2, “Importing an LDIF File into an Encrypted Database”.

10.3.2. Enabling Encryption of an Attribute Using the Web Console

To configure that Directory Server stores, for example, telephoneNumber attributes in the database AES-encrypted:
  1. Optionally, to encrypt existing telephoneNumber attributes, export the database. See Section 10.4.1, “Exporting an Encrypted Database”.
  2. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  3. Select the instance.
  4. Open the Database menu.
  5. Select the suffix entry.
  6. Open the Encrypted Attributes tab.
  7. Click Add Attribute.
  8. Select the attribute to encrypt from the list, and set an encryption algorithm. For example:
  9. Click Add Attribute.
  10. If you exported the database to encrypt also existing attributes, reimport the database. See Section 10.4.2, “Importing an LDIF File into an Encrypted Database”.

10.3.3. Disabling Encryption for an Attribute Using the Command Line

To configure that Directory Server no longer stores, for example, telephoneNumber attributes encrypted in the userRoot database:
  1. Optionally, to decrypt existing telephoneNumber attributes, export the database. See Section 10.4.1, “Exporting an Encrypted Database”.
  2. Disable encryption for the telephoneNumber attribute in the userRoot database:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend attr-encrypt --del-attr telephoneNumber userRoot
  3. If you exported the database to decrypt existing attributes, reimport the database. See Section 10.4.2, “Importing an LDIF File into an Encrypted Database”.

10.3.4. Disabling Encryption of an Attribute Using the Web Console

To configure that Directory Server stores, for example, telephoneNumber attributes in the database AES-encrypted:
  1. Optionally, to encrypt existing telephoneNumber attributes, export the database. See Section 10.4.1, “Exporting an Encrypted Database”.
  2. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  3. Select the instance.
  4. Open the Database menu.
  5. Select the suffix entry.
  6. Open the Encrypted Attributes tab.
  7. Click the Delete Attribute button to the right of the telephoneNumber attribute.
  8. Click Yes to confirm.
  9. If you exported the database to decrypt existing attributes, reimport the database. See Section 10.4.2, “Importing an LDIF File into an Encrypted Database”.

10.3.5. General Considerations after Enabling Attribute Encryption

When you enabled encryption for data that is already in the database:
  • Unencrypted data can persist in the server's database page pool backing file. To remove this data:
    1. Stop the instance:
      # dsctl instance_name stop
    2. Delete the /var/lib/dirsrv/slapd-instance_name/db/guardian file:
      # rm /var/lib/dirsrv/slapd-instance_name/db/guardian
    3. Start the instance:
      # dsctl instance_name start
  • After you enabled encryption and successfully imported the data, delete the LDIF file with the unencrypted data.
  • After enabling encryption, Directory Server deletes and creates a new database when reimporting the data.
  • The replication log file is not encrypted. To protect this data, store it on an encrypted disk.
  • Data in the server's memory (RAM) is unencrypted and can be temporarily stored in swap partitions. To protect this data, set up encrypted swap space.

Important

Even if you delete files that contain unencrypted data, this data can be restored under certain circumstances.

10.4. Exporting and Importing an Encrypted Database

Exporting and importing encrypted databases is similar to exporting and importing regular databases. However, the encrypted information must be decrypted when you export the data and re-encrypted when you reimport it to the database.

10.4.1. Exporting an Encrypted Database

To export data from an encrypted database, pass the -E parameter to the dsconf command.
For example, to export the complete userRoot database with decrypted attributes:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend export -E userRoot
Alternatively, you can export only a specific subtree. For example, to export all data from the ou=People,dc=example,dc=com entry:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend export -E -s "ou=People,dc=example,dc=com" userRoot
For further details about using dsconf to export data, see Section 6.2.1.1.1, “Exporting a Databases Using the dsconf backend export Command”.

10.4.2. Importing an LDIF File into an Encrypted Database

To import data to a database when attribute encryption is enabled:
  1. Stop the Directory Server instance:
    # dsctl instance_name stop
  2. If you replaced the certificate database between the last export and this import, edit the /etc/dirsrv/slapd-instance_name/dse.ldif file, and remove the following entries including their attributes:
    • cn=AES,cn=encrypted attribute keys,cn=database_name,cn=ldbm database,cn=plugins,cn=config
    • cn=3DES,cn=encrypted attribute keys,cn=database_name,cn=ldbm database,cn=plugins,cn=config

    Important

    Remove the entries for all databases. If any entry that contains the nsSymmetricKey attribute is left in the /etc/dirsrv/slapd-instance_name/dse.ldif file, Directory Server will fail to start.
  3. Import the LDIF file. For example, to import the /tmp/example.ldif into the userRoot database:
    # dsctl instance_name ldif2db --encrypted userRoot /tmp/example.ldif
    The --encrypted parameter enables the script to encrypt attributes configure for encryption during the import.
  4. Start the instance:
    # dsctl instance_name start

10.5. Updating the TLS Certificates Used for Attribute Encryption

Attribute encryption is based on the TLS certificate. To prevent that attribute encryption fails after renewing or replacing the TLS certificate:
  1. Export the database with decrypted attributes. See Section 10.4.1, “Exporting an Encrypted Database”.
  2. Delete the existing private key and certificate from the Network Security Services (NSS) database. See Section 9.3.7, “Removing a Private Key”
  3. Create a new Certificate Signing Request (CSR). See Section 9.3.1, “Creating a Certificate Signing Request”.
  4. Install the new certificate. See Section 9.3.3, “Installing a Server Certificate”.
  5. Stop the Directory Server instance:
    # dsctl instance_name stop
  6. Edit the /etc/dirsrv/slapd-instance_name/dse.ldif file and remove the following entries including their attributes:
    • cn=AES,cn=encrypted attribute keys,cn=database_name,cn=ldbm database,cn=plugins,cn=config
    • cn=3DES,cn=encrypted attribute keys,cn=database_name,cn=ldbm database,cn=plugins,cn=config

    Important

    Remove the entries for all databases. If any entry that contains the nsSymmetricKey attribute is left in the /etc/dirsrv/slapd-instance_name/dse.ldif file, Directory Server will fail to start.
  7. Start the instance:
    # dsctl instance_name start

Chapter 11. Managing FIPS Mode Support

Red Hat Directory Server fully supports the Federal Information Processing Standard (FIPS) 140-2. When Directory Server runs in FIPS mode, security-related settings change. For example, SSL is automatically disabled and only TLS 1.1 and 1.2 encryption is used.
For general details about FIPS, see Federal Information Processing Standard (FIPS) in the Red Hat Enterprise Linux Security Guide.

Enabling FIPS Mode Support

To enable FIPS mode support for Directory Server:
  1. Optionally, enable FIPS mode in Red Hat Enterprise Linux. For details, see the corresponding section in the Red Hat Enterprise Linux Security Guide.
  2. Enable FIPS mode for the network security services (NSS) database:
    # modutil -dbdir /etc/dirsrv/slapd-instance_name/ -fips true
  3. Restart the Directory Server instance:
    # dsctl instance_name restart

Disabling FIPS Mode Support

To disable FIPS mode support for Directory Server:
  1. Disable FIPS mode for the network security services (NSS) database:
    # modutil -dbdir /etc/dirsrv/slapd-instance_name/ -fips false
  2. Restart the Directory Server instance:
    # dsctl instance_name restart
  3. Optionally, disable FIPS mode in Red Hat Enterprise Linux. For details, see the corresponding section in the Red Hat Enterprise Linux Security Guide.

Chapter 12. Managing the Directory Schema

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

12.1. Overview of Schema

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

12.1.1. Default Schema Files

The schema for Directory Server is defined in several different schema files (LDIF files which define schema elements). The Directory Server schema files are located in the /usr/share/dirsrv/schema/ directory. The files in this directory are used as templates for new Directory Server instances. Adding a new schema into this directory will make it available to any new instances.
The attributes used by the Directory Server to perform operations and manage entries is described with other configuration settings in the Red Hat Directory Server 11 Configuration, Command, and File Reference.

12.1.2. Object Classes

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

Example 12.1. person Object Class Schema Entry

objectClasses: ( 2.5.6.6 NAME 'person' DESC 'Standard LDAP objectclass' SUP top MUST ( sn $ cn ) MAY ( description $ seeAlso $ telephoneNumber $ userPassword ) X-ORIGIN 'RFC 4519' )
Every object class defines a number of required attributes (MUST keyword in the schema) and of allowed attributes (MAY keyword in the schema). Required attributes must be present in entries using the specified object class, while allowed attributes are permissible and available for the entry to use, but are not required for the entry to be valid.
As in Example 12.1, “person Object Class Schema Entry”, the person object class requires the cn, sn, and objectClass attributes and allows the description, seeAlso, telephoneNumber, and userPassword attributes.
An object class can inherit attributes from another class, in addition to its own required and allowed attributes. The second object class is the superior or parent object class of the first.
For example, a user's entry has to have the inetOrgPerson object class. In that case, the entry must also include the superior object class for inetOrgPerson, organizationalPerson, and the superior object class for organizationalPerson, which is person:
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
An object class definition is an objectclasses attribute for the cn=schema entry. The objectclasses attribute has the format:
objectclasses: ( definition )
The object class definition contains several components:
  • An OID, usually a dot-separated number
  • A unique name, in the form NAME name
  • A description, in the form DESC description
  • The superior, or parent, object class for this object class, in the form SUP object_class; if there is no related parent, use SUP top
  • The word AUXILIARY, which gives the type of entry to which the object class applies; AUXILIARY means it can apply to any entry
  • A list of required attributes, preceded by the word MUST; to include multiple attributes, enclose the group in parentheses and separate with attributes with dollar signs ($)
  • A list of allowed attributes, preceded by the word MAY; to include multiple attributes, enclose the group in parentheses and separate with attributes with dollar signs ($)
Customer object class definitions are stored in the /etc/dirsrv/slapd-instance_name/schema/99user.ldif when using the command line or the web console to modify cn=schema entries.

12.1.3. Attributes

Directory entries are composed of attributes and their values. These pairs are called attribute-value assertions or AVAs. Any piece of information in the directory is associated with a descriptive attribute. For instance, the cn attribute is used to store a person's full name, such as cn: John Smith.
Additional attributes can supply additional information about John Smith:
givenname: John
surname: Smith
mail: jsmith@example.com
In a schema file, an attribute is described by:
  • OID
  • name
  • syntax matching rule (optional)
  • substring matching rules (optional)
  • ordering rule (optional)
  • description (optional)
  • syntax
  • single-valued or multi-valued attribute
  • details about where the attribute is defined

Example 12.2. uid Attribute Schema Entry

( 0.9.2342.19200300.100.1.1 NAME ( 'uid' 'userid' ) EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'RFC 4519' )

12.1.3.1. Directory Server Attribute Syntaxes

The attribute's syntax defines the format of the values which the attribute allows; as with other schema elements, the syntax is defined for an attribute using the syntax's OID in the schema file entry.
The Directory Server uses the attribute's syntax to perform sorting and pattern matching on entries.
For more information about LDAP attribute syntaxes, see RFC 4517.
Supported LDAP attribute syntaxes are covered in section Directory Server Attribute Syntaxes of the Red Hat Directory Server 10 Configuration, Command, and File Reference.

12.1.4. Extending the Schema

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

Warning

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

Note

Never delete or replace the standard schema. Doing so can lead to compatibility problems with other directories or other LDAP client applications.
The schema is loaded into the Directory Server instance when the instance is started; any new schema files are not loaded until the Directory Server is restarted or unless a reload task is initiated. The default custom schema file for an instance, 99user.ldif, is loaded as the last schema file. If it contains definitions already present in standard schema files, the custom definition will override the standard ones.

12.1.5. Schema Replication

When the directory schema is updated in the cn=schema sub-tree, Directory Server stores the changes in the local /etc/dirsrv/slapd-instance_name/schema/99user.ldif file, including a change state number (CSN). The updated schema is not automatically replicated to other replicas. The schema replication starts when directory content is updated in the replicated tree. For example, if you update a user or group entry after modifying the schema, the supplier compares the CSN stored in the nsSchemaCSN attribute with the one on the consumer. If the remote CSN is lower than the one on the supplier, the schema is replicated to the consumer. For a successful replication, all object classes and attribute types on the supplier must be a superset of the consumer's definition.

Example 12.3. Schema subsets and supersets

  • On server1, the demo object class allows the a1, a2, and a3 attributes.
  • On server2, the demo object class allows the a1 and a3 attributes.
In Example 12.3, “Schema subsets and supersets”, the schema definition of the demo object class on server1 is a superset of the object class on server2. During the validation phase, when the schema is being replicated or accepted, Directory Server retrieves the superset definitions. For example, if a consumer detects that an object class in the local schema allows less attributes than the object class in the supplier schema, the local schema is updated.
If the schema definitions are successfully replicated, the nsSchemaCSN attributes are identical on both servers and no longer compared at the beginning of a replication session.
In the following scenarios, the schema is not replicated:
  • The schema on one host is a subset of the schema of another host.
    For example, in Example 12.3, “Schema subsets and supersets”, the schema definition of the demo object class on server2 is a subset of the object class on server1. Subsets can also occur for attributes (a single-value attribute is a subset of a multi-value attribute) and attribute syntaxes (IA5 is a subset of Octet_string).
  • When definitions in supplier schema and consumer schema need to be merged.
    Directory Server does not support merging schemas. For example, if an object class on one server allows the a1, a2, and a3 attributes and a1, a3, and a4 on the other, the schemas are not subsets and cannot be merged.
  • Schema files other than /etc/dirsrv/slapd-instance_name/schema/99user.ldif are used.
    Directory Server enables you to add additional schema files in the /etc/dirsrv/slapd-instance_name/schema/ directory. However, only the CSN in the 99user.ldif file is updated. For this reasons, other schema file are only used locally and are not automatically transferred to replication partners. Copy the updated schema file manually to the consumers and reload the schema. For details, see Section 12.10, “Dynamically Reloading Schema”.
    To avoid duplicate schema definitions and to enable automatic replication, store all custom schema in the /etc/dirsrv/slapd-instance_name/schema/99user.ldif file. For further information about creating custom schema files, see Section 12.9, “Creating Custom Schema Files”.

12.2. Managing Object Identifiers

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

Note

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

12.3. Creating an Object Class

This section describes how to create a object class using the command line and the web console.

12.3.1. Creating an Object Class Using the Command Line

Use the ldapmodify utility to create a new object class entry. For example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com schema objectclasses add examplePerson --oid="2.16.840.1133730.2.123" --desc="Example Person Object Class" --sup="inetOrgPerson" --kind="AUXILIARY" --must="cn" --may exampleDateOfBirth examplePreferredOS
For further details about object class definitions, see Section 12.1.2, “Object Classes”.

12.3.2. Creating an Object Class Using the Web Console

To create an object class using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select SchemaObject Classes.
  4. Click Create Objectclass.
  5. Select the parent object class.
  6. Enter an object class name and, optionally, set a object identifier (OID).
  7. Use the Add and Remove buttons to update the list of required and allowed attributes.
  8. Click Save.

12.4. Updating an Object Class

This section describes how to update an object class using the command line and the web console.

12.4.1. Updating an Object Class Using the Command Line

Use the ldapmodify utility to update an object class entry. For example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com schema objectclasses edit examplePerson --oid="2.16.840.1133730.2.123" --desc="Example Person Object Class" --sup="inetOrgPerson" --kind="AUXILIARY" --must="cn" --may exampleDisplayName exampleAlias
For further details about object class definitions, see Section 12.1.2, “Object Classes”.

12.4.2. Updating an Object Class Using the Web Console

To update an object class using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select SchemaObject Classes.
  4. Click the Choose Action button to the right of the object class entry you want to edit.
  5. Select Edit Object Class.
  6. Update the parameters, and use the Add and Remove buttons to update the list of required and allowed attributes.
  7. Click Save.

12.5. Removing an Object Class

This section describes how to delete an object class using the command line and the web console.

Warning

Do not delete default schema elements. They are required by Directory Server.

12.5.1. Removing an Object Class Using the Command Line

Use the ldapmodify utility to delete an object class entry. For example, to delete the examplePerson object class:
  1. Remove the unwanted attributes from any entries that use them. For details, see Section 12.8, “Removing an Attribute”.
  2. Delete the object class entry:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com schema objectclasses delete examplePerson
For further details about object class definitions, see Section 12.1.2, “Object Classes”.

12.5.2. Removing an Object Class Using the Web Console

To remove an object class using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select SchemaObject Classes.
  4. Click the Choose Action button next to the object class entry you want to remove.
  5. Select Delete Objectclass.
  6. Click Yes to confirm.

12.6. Creating an Attribute

This section describes how to create a attribute using the command line and the web console.

12.6.1. Creating an Attribute Using the Command Line

Use the ldapmodify utility to create a new attribute. For example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com schema attributetypes add dateofbirth --desc="For employee birthdays" --syntax="1.3.6.1.4.1.1466.115.121.1.15" --single-value --x-origin="Example defined"
For further details about attribute definitions, see Section 12.1.3, “Attributes”.

12.6.2. Creating an Attribute Using the Web Console

To create an attribute using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select SchemaAttributes.
  4. Click Create Attribute.
  5. Fill the parameters.
  6. Click Save.

12.7. Updating an attribute

This section describes how to update an attribute using the command line and the web console.

12.7.1. Updating an Attribute Using the Command Line

Use the ldapmodify utility to update an attribute entry. For example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com schema attributetypes edit dateofbirth --desc="Employee birthday" --syntax="1.3.6.1.4.1.1466.115.121.1.15" --single-value --x-origin="Example defined"
For further details about object class definitions, see Section 12.1.2, “Object Classes”.

12.7.2. Updating an Attribute Using the Web Console

To update an attribute using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select SchemaAttributes.
  4. Click the Choose Action button next to the attribute you want to edit.
  5. Select Edit Attribute.
  6. Update the parameters.
  7. Click Save.

12.8. Removing an Attribute

This section describes how to delete an attribute using the command line and the web console.

12.8.1. Removing an Attribute Using the Command Line

Use the ldapmodify utility to delete an attribute. For example:
  1. Remove the unwanted attributes from any entries which use them.
  2. Delete the attribute:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com schema attributetypes remove dateofbirth
For further details about object class definitions, see Section 12.1.2, “Object Classes”.

12.8.2. Removing an Attribute Using the Web Console

To remove an attribute using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select SchemaObject Classes.
  4. Click the Choose Action button next to the attribute you want to remove.
  5. Select Delete Attribute.
  6. Click Yes to confirm.

12.9. Creating Custom Schema Files

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

Example 12.4. Example Schema File

dn: cn=schema
attributetypes: ( 2.16.840.1133730.1.123 NAME 'dateofbirth' DESC 'For employee birthdays' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'Example defined')
objectclasses: ( 2.16.840.1133730.2.123 NAME 'examplePerson' DESC 'Example Person Object Class' SUP inetOrgPerson AUXILIARY MAY (dateofbirth) )
Custom schema files should be added to the Directory Server instance's schema directory, /etc/dirsrv/slapd-instance/schema. The schema in these files are not loaded and available to the server unless the server is restarted or a dynamic reload task is run.

12.10. Dynamically Reloading Schema

By default, the schema files used by the Directory Server instance are loaded into the directory when it is started. This means that any new schema files added to the schema directory are not available for use unless the server is restarted. The Directory Server has a task which manually reloads the full schema for the Directory Server instance, including custom files, without requiring a server restart.
You can reload the schema using one of the following methods:

Note

Directory Server always additionally reloads the all schema files stored in the /usr/share/dirsrv/schema/ directory.

12.10.1. Dynamically Reloading the Schema Using the dsconf schema reload Command

Use the dsconf schema reload command to reload the schema:
# dsconf -D "cn=Directory Manager" ldap://server.example.com schema reload
Attempting to add task entry... This will fail if Schema Reload plug-in is not enabled.
Successfully added task entry cn=schema_reload_2018-08-28T09:45:48.027962,cn=schema reload task,cn=tasks,cn=config
To verify that the schema reload operation was successful, please check the error logs
By default, Directory Server reloads the schema files stored in the directory set in the nsslapd-schemadir parameter. Optionally, pass the -d directory option to the command to reload the schema stored in a different directory.

12.10.2. Dynamically Reloading the Schema Using a cn=tasks Entry

The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries the server uses to manage tasks. To initiate a schema reload operation, create a task in the cn=schema reload task,cn=tasks,cn=config entry.
By default, Directory Server reloads the schema files stored in the directory set in the nsslapd-schemadir parameter. For example, to reload the schema files stored in the directory set in this parameter:
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=example_schema_reload,cn=schema reload task,cn=tasks,cn=config
objectclass: extensibleObject
cn: cn=example_schema_reload
Optionally, specify the schemadir parameter, to reload the schema stored in a different directory. For example:
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=example_schema_reload,cn=schema reload task,cn=tasks,cn=config
objectclass: extensibleObject
cn: cn=example_schema_reload
schemadir: /example/schema/
When the task is completed, the entry is removed from the directory configuration.
For further details about the cn=schema reload task,cn=tasks,cn=config entry, see the cn=schema reload task section in the Red Hat Directory Server Configuration, Command, and File Reference.

12.10.3. Reloading The Schema in a Replication Topology

The schema reload task is a local operation, so schema changes are not replicated in a multi-master environment if the schema is added to one supplier but not to the others. To load the new schema files on all of the supplier servers:

12.10.4. Schema Reload Errors

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

12.11. Turning Schema Checking On and Off

When schema checking is on, the Directory Server ensures three things:
  • The object classes and attributes using are defined in the directory schema.
  • The attributes required for an object class are contained in the entry.
  • Only attributes allowed by the object class are contained in the entry.

Important

Red Hat recommends not to disable the schema checking.
Schema checking is turned on by default in the Directory Server, and the Directory Server should always run with schema checking turned on. The only situation where is may be beneficial to turn schema checking off is to accelerate LDAP import operations. However, there is a risk of importing entries that do not conform to the schema. Consequently, it is impossible to update these entries.

12.11.1. Turning Schema Checking On and Off Using the Command Line

To turn schema checking on and off, set the value of the nsslapd-schemacheck parameter. For example to disable schema checking:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-schemacheck=off
Successfully replaced "nsslapd-schemacheck"
For details about the nsslapd-schemacheck parameter, see the description of the parameter in the Red Hat Directory Server Configuration, Command, and File Reference.

12.11.2. Turning Schema Checking On and Off Using the Web Console

To enable or disable schema checking using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select Server SettingsServer Configuration.
  4. Click Show Advanced Settings.
  5. To enable schema checking, select the Enable Schema Checking check box. To disable the feature, clear the check box.
  6. Click Save.

12.12. Using Syntax Validation

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

Important

Red Hat recommends not to disable the syntax validation.

12.12.1. About Syntax Validation

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

12.12.2. Syntax Validation and Other Directory Server Operations

Syntax validation is mainly relevant for standard LDAP operations like creating entries (add) or editing attributes (modify). Validating attribute syntax can impact other Directory Server operations, however.
Database Encryption

For normal LDAP operations, an attribute is encrypted just before the value is written to the database. This means That encryption occurs after the attribute syntax is validated.

Encrypted databases (as described in Chapter 10, Configuring Attribute Encryption) can be exported and imported. Normally, it is strongly recommended that these export and import operations are done with the -E flag with db2ldif and ldif2db, which allows syntax validation to occur just fine for the import operation. However, if the encrypted database is exported without using the -E flag (which is not supported), then an LDIF with encrypted values is created. When this LDIF is then imported, the encrypted attributes cannot be validated, a warning is logged, and attribute validation is skipped in the imported entry.
Synchronization

There may be differences in the allowed or enforced syntaxes for attributes in Windows Active Directory entries and Red Hat Directory Server entries. In that case, the Active Directory values could not be properly synchronized over because syntax validation enforces the RFC standards in the Directory Server entries.

Replication

If the Directory Server 11 instance is a supplier which replicates its changes to a consumer, then there is no issue with using syntax validation. However, if the supplier in replication is an older version of Directory Server or has syntax validation disabled, then syntax validation should not be used on the consumer because the Directory Server 11 consumer may reject attribute values that the master allows.

12.12.2.1. Turning Syntax Validation On and Off Using the Command Line

To turn syntax validation on and off, set the value of the nsslapd-syntaxcheck parameter. For example to disable syntax validation:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-syntaxcheck=off
Successfully replaced "nsslapd-syntaxcheck"
For details about the nsslapd-syntaxcheck parameter, see the description of the parameter in the Red Hat Directory Server Configuration, Command, and File Reference.

12.12.2.2. Turning Syntax Validation On and Off Using the Web Console

To enable or disable syntax validation using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select Server SettingsServer Configuration.
  4. Click Show Advanced Settings.
  5. To enable attribute syntax checking, select the Enable Attribute Syntax Checking check box. To disable the feature, clear the check box.
  6. Click Save.

12.12.3. Enabling or Disabling Strict Syntax Validation for DNs

When syntax validation is enabled, distinguished names (DN) are validated as described in section 3 of RFC 4514. DN syntax validation is enabled separately because the strictness of later standards can invalidate older DNs that have a different syntax, and therefore directory trees.

Note

If strict DN validation is enabled and a DN value does not conform to the required syntax, then the operation fails with the LDAP result code 34, INVALID_DN_SYNTAX.

12.12.3.1. Enabling or Disabling Strict Syntax Validation for DNs Using the Command Line

To turn strict syntax validation for DNs on and off, set the value of the nsslapd-dn-validate-strict parameter. For example to disable strict syntax validation for DNs::
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-dn-validate-strict=off
Successfully replaced "nsslapd-dn-validate-strict"
For details about the nsslapd-syntaxcheck parameter, see the description of the parameter in the Red Hat Directory Server Configuration, Command, and File Reference.

12.12.3.2. Enabling or Disabling Strict Syntax Validation for DNs Using the Web Console

To enable or disable strict syntax validation for DNs using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select Server SettingsServer Configuration.
  4. Click Show Advanced Settings.
  5. Select or unselect the Enable Strict DN Syntax Validation option depending on whether you want to enable or disable the feature.
  6. Click Save.

12.12.4. Enabling Syntax Validation Logging

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

Note

Syntax violations discovered by the syntax validation script and task are logged in the Directory Server error log.
If both the nsslapd-syntaxlogging and nsslapd-syntaxcheck parameter are enabled, any invalid attribute modification is rejected and the message written to the log. If nsslapd-syntaxlogging is enabled but nsslapd-syntaxcheck is disabled, then the operation is allowed to succeed, but the warning message is still written to the error log.

12.12.4.1. Enabling Syntax Validation Logging Using the Command Line

To enable syntax validation logging, set the value of the nsslapd-syntaxlogging parameter to on.
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-syntaxlogging=on
Successfully replaced "nsslapd-syntaxlogging"
For details about the nsslapd-syntaxlogging parameter, see the description of the parameter in the Red Hat Directory Server Configuration, Command, and File Reference.

12.12.4.2. Enabling Syntax Validation Logging Using the Web Console

To enable validation logging using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select Server SettingsServer Configuration.
  4. Click Show Advanced Settings.
  5. Select the Enable Attribute Syntax Logging option.
  6. Click Save.

12.12.5. Validating the Syntax of Existing Attribute Values

In certain situations, you might want to manually validate the syntax of existing values. For example:
Directory Server logs results of syntax validation tasks to the /var/log/dirsrv/slapd-instance_name/errors file. For example:
  • If all verified values are valid:
    [28/Jun/2017:12:52:43.669867966 +0200] - ERR - syntax-plugin - syntax_validate_task_thread - Starting (base: "dc=example,dc=com", filter: "(objectclass=*)") ...
    [28/Jun/2017:12:52:43.696850129 +0200] - ERR - syntax-plugin - syntax_validate_task_thread - Complete.  Found 0 invalid entries.
  • If invalid entries were found:
    [28/Jun/2017:12:54:05.736087520 +0200] - ERR - syntax-plugin - syntax_validate_task_thread - Starting (base: "dc=example,dc=com", filter: "(objectclass=*)") ...
    [28/Jun/2017:12:54:05.754195607 +0200] - ERR - syntax-plugin - syntax_validate_task_callback - Entry "cn=user,ou=People,dc=example,dc=com" violates syntax.
    description: value #0 invalid per syntax
    [28/Jun/2017:12:54:05.759905671 +0200] - ERR - syntax-plugin - syntax_validate_task_thread - Complete.  Found 1 invalid entries.

    Note

    Syntax validation tasks only identifies syntax violations. You must fix incorrect values manually.

12.12.5.1. Validating the Syntax of Existing Attribute Values Using a cn=tasks Entry

The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries the server uses to manage tasks. To initiate a syntax validation operation, create a task in the cn=syntax validate,cn=tasks,cn=config entry.
For example, to create a task that validates the syntax of all values in the ou=People,dc=example,dc=com sub-tree which match the (objectclass=inetorgperson) filter:
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=example_syntax_validate,cn=syntax validate,cn=tasks,cn=config
objectclass: extensibleObject
cn: cn=example_syntax_validate
basedn: ou=People,dc=example,dc=com
filter: (objectclass=inetorgperson)
When the task is completed, the entry is removed from the directory configuration.
For further details, about the cn=syntax validate,cn=tasks,cn=config entry, see the cn=schema reload task section in the Red Hat Directory Server Configuration, Command, and File Reference.

Chapter 13. Managing Indexes

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

13.1. About Indexes

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

13.1.1. About Index Types

Indexes are stored in files in the directory's databases. The names of the files are based on the indexed attribute, not the type of index contained in the file. Each index file may contain multiple types of indexes if multiple indexes are maintained for the specific attribute. For example, all indexes maintained for the common name attribute are contained in the cn.db file.
Directory Server supports the following types of index:
  • Presence index (pres) contains a list of the entries that contain a particular attribute, which is very useful for searches. For example, it makes it easy to examine any entries that contain access control information. Generating an aci.db file that includes a presence index efficiently performs the search for ACI=* to generate the access control list for the server.
  • Equality index (eq) improves searches for entries containing a specific attribute value. For example, an equality index on the cn attribute allows a user to perform the search for cn=Babs Jensen far more efficiently.
  • Approximate index (approx) is used for efficient approximate or sounds-like searches. For example, an entry may include the attribute value cn=Firstname M Lastname. An approximate search would return this value for searches against cn~=Firstname Lastname, cn~=Firstname, or cn~=Lastname. Similarly, a search against l~=San Fransisco (note the misspelling) would return entries including l=San Francisco.
  • Substring index (sub) is a costly index to maintain, but it allows efficient searching against substrings within entries. Substring indexes are limited to a minimum of three characters for each entry.
    For example, searches of the form cn=*derson , match the common names containing strings such as Bill Anderson, Jill Henderson, or Steve Sanderson. Similarly, the search for telephoneNumber= *555* returns all the entries in the directory with telephone numbers that contain 555.
  • International index speeds up searches for information in international directories. The process for creating an international index is similar to the process for creating regular indexes, except that it applies a matching rule by associating an object identifier (OID) with the attributes to be indexed.
    The supported locales and their associated OIDs are listed in Appendix D, Internationalization. If there is a need to configure the Directory Server to accept additional matching rules, contact Red Hat Consulting.

13.1.2. About Default and Database Indexes

Directory Server contains a set of default indexes. When you create a new database, Directory Server copies these default indexes from cn=default indexes,cn=config,cn=ldbm database,cn=plugins,cn=config to the new database. Then the database only uses the copy of these indexes, which are stored in cn=index,cn=database_name,cn=ldbm database,cn=plugins,cn=config.
To display the Directory Server default indexes:
# ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com \
     -b "cn=default indexes,cn=config,cn=ldbm database,cn=plugins,cn=config" \
     '(objectClass=nsindex)'

Note

If you update the default index settings stored in cn=default indexes,cn=config,cn=ldbm database,cn=plugins,cn=config, the changes are not applied to the individual databases in cn=index,cn=database_name,cn=ldbm database,cn=plugins,cn=config.
To display the indexes of an individual database:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend index list database_name

13.1.3. Overview of the Searching Algorithm

Indexes are used to speed up searches. To understand how the directory uses indexes, it helps to understand the searching algorithm. Each index contains a list of attributes (such as the cn, common name, attribute) and a list of IDs of the entries which contain the indexed attribute value:
  1. An LDAP client application sends a search request to the directory.
  2. The directory examines the incoming request to make sure that the specified base DN matches a suffix contained by one or more of its databases or database links.
    • If they do match, the directory processes the request.
    • If they do not match, the directory returns an error to the client indicating that the suffix does not match. If a referral has been specified in the nsslapd-referral attribute under cn=config, the directory also returns the LDAP URL where the client can attempt to pursue the request.
    • The Directory Server examines the search filter to see what indexes apply, and it attempts to load the list of entry IDs from each index that satisfies the filter. The ID lists are combined based on whether the filter used AND or OR joins.
      Each filter component is handled independently and returns an ID list.
    • If the list of entry IDs is larger than the configured ID list scan limit or if there is no index defined for the attribute, then Directory Server sets the results for this filtercomponent to allids. If, after applying the logical operations to the results of the individual search components the list is still ALLIDs it searches every entry in the database. This is an unindexed search.
  3. The Directory Server reads every entry from the id2entry.db database or the entry cache for every entry ID in the ID list (or from the entire database for an unindexed search). The server then checks the entries to see if they match the search filter. Each match is returned as it is found.
    The server continues through the list of IDs until it has searched all candidate entries or until it hits one of the configured resource limits. (Resource limits are listed in Section 14.4.3, “Setting User and Global Resource Limits Using the Command Line”.)

    Note

    It's possible to set separate resource limits for searches using the simple paged results control. For example, administrators can set high or unlimited size and look-through limits with paged searches, but use the lower default limits for non-paged searches.

13.1.4. Approximate Searches

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

Note

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

13.1.5. Balancing the Benefits of Indexing

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

13.2. Creating Standard Indexes

This section describes how to create presence, equality, approximate, substring, and international indexes for specific attributes using the command line and the web console.

Note

When you create a new index type, Directory Server uses this default index as a template for each new database that will be created in future. If you update the default index, the updated settings are not applied to existing databases. To apply a new index to an existing database, use the dsctl db2index command or a cn=index,cn=tasks task, as described in Section 13.3, “Creating New Indexes to Existing Databases”.

13.2.1. Creating Indexes Using the Command Line

Note

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

Note

Avoid creating entries under cn=config in the dse.ldif file. The cn=config entry in the dse.ldif configuration file is not stored in the same highly scalable database as regular entries. As a result, if many entries, particularly entries that are likely to be updated frequently, are stored under cn=config, performance will probably suffer. Although we recommend you do not store simple user entries under cn=config for performance reasons, it can be useful to store special user entries such as the Directory Manager entry or replication manager (supplier bind DN) entry under cn=config since this centralizes configuration information.
For information on the LDIF update statements required to add entries, see Section 3.4, “Updating a Directory Entry”.
For example, to create presence, equality, and substring indexes for the sn (surname) attribute in the Example1 database:
  1. Run ldapmodify and add the LDIF entry for the new indexes:
    # ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    
    dn: cn=sn,cn=index,cn=Example1,cn=ldbm database,cn=plugins,cn=config
    changetype: add
    objectClass:top
    objectClass:nsIndex
    cn:sn
    nsSystemIndex:false
    nsIndexType:pres
    nsIndexType:eq
    nsIndexType:sub
    nsMatchingRule:2.16.840.1.113730.3.3.2.3.1
    The cn attribute contains the name of the attribute to index, in this example the sn attribute. The entry is a member of the nsIndex object class. The nsSystemIndex attribute is false, indicating that the index is not essential to Directory Server operations. The multi-valued nsIndexType attribute specifies the presence (pres), equality (eq) and substring (sub) indexes. Each keyword has to be entered on a separate line. The nsMatchingRule attribute in the example specifies the OID of the Bulgarian collation order; the matching rule can indicate any possible value match, such as languages or other formats like date or integer.
    You can use the keyword none in the nsIndexType attribute to specify that no indexes are to be maintained for the attribute. This example temporarily disables the sn indexes on the Example1 database by changing the nsIndexType to none:
    dn: cn=sn,cn=index,cn=Example1,cn=ldbm database,cn=plugins,cn=config
    objectClass:top
    objectClass:nsIndex
    cn:sn
    nsSystemIndex:false
    nsIndexType:none
For a complete list of matching rules and their OIDs, see Section 14.2.4, “Using Matching Rules”, and for the index configuration attributes, see the Red Hat Directory Server Configuration, Command, and File Reference.

Note

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

13.2.2. Creating Indexes Using the Web Console

To create presence, equality, approximate, substring, or international indexes:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Database menu.
  4. Select the suffix entry.
  5. Open the Indexes tab.
  6. Click the Add Index button.
  7. Select the attribute to index, the type of index, and optionally a matching rule.
  8. Click Create Index.

13.3. Creating New Indexes to Existing Databases

Learn how to initiate indexing operations on Directory Server. You must create indexes manually because Directory Server does not automatically index databases.

Important

Before you regenerate the index, searches proceed but can return incorrect or inconsistent results.

13.3.1. Creating an Index While the Instance is Running

13.3.1.1. Creating an Index Using the dsconf backend index reindex Command

To recreate the index of a database while the instance is running:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend index reindex database_name

13.3.1.2. Creating an Index Using a cn=tasks Entry

The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries the server uses to manage tasks. To initiate an index operation, create a task in the cn=index,cn=tasks,cn=config entry.
Use the ldapadd utility to add a new index task. For example, to add a task that creates the presence index for the cn attribute in the userRoot database:
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=example_presence_index,cn=index,cn=tasks,cn=config
objectclass: top
objectclass: extensibleObject
cn: example presence index
nsInstance: userRoot
nsIndexAttribute: "cn:pres"
When the task is completed, the entry is removed from the directory configuration.
For further details, about the cn=index,cn=tasks,cn=config entry, see the cn=index section in the Red Hat Directory Server Configuration, Command, and File Reference.

13.3.2. Creating an Index While the Instance Offline

After creating an indexing entry or adding additional index types to an existing indexing entry, use the dsconf db2index command:
  1. Shut down the instance:
    # dsctl instance_name stop
  2. Recreate the index:
    # dsctl instance_name db2index userRoot
    [13/Aug/2019:15:25:37.277426483 +0200] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
    [13/Aug/2019:15:25:37.289257996 +0200] - INFO - check_and_set_import_cache - pagesize: 4096, available bytes 1704378368, process usage 22212608 
    [13/Aug/2019:15:25:37.291738104 +0200] - INFO - check_and_set_import_cache - Import allocates 665772KB import cache.
    ...
    db2index successful
  3. Start the instance:
    # dsctl instance_name start

13.4. Creating Browsing Indexes

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

Note

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

13.4.1. Creating Browsing Indexes from the Command Line

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

13.4.1.1. Adding a Browsing Index Entry

The type of browsing index entry to create depends on the type of ldapsearch attribute sorting to accelerate. It is important to take the following into account:
  • The scope of the search (base, one, sub)
  • The base of the search (the entry to use as a starting point for the search)
  • The attributes to sort
  • The filter of the search
    For more information on specifying filters for searches, see Chapter 14, Finding Directory Entries.
  • The LDBM database to which the entry that forms the base of the search belongs. You can only create browsing indexes in LDBM databases.
For example, create a browsing index to accelerate an ldapsearch on the entry ou=People,dc=example,dc=com held in the Example1 database with the following attributes:
  • The search base is ou=People,dc=example,dc=com
  • The search filter is (ou=accounting)
  • The scope is one
  • The sorting order for the returned attributes is cn, givenname, o, ou, and sn
  1. Run ldapmodify and add an entry which specifies the base, scope, and filter of the browsing index:
    # ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    
    dn: cn=MCC ou=People dc=example dc=com,cn=userRoot,cn=ldbm database,cn=plugins,cn=config
    changetype: add
    objectClass: top
    objectClass: vlvSearch
    cn: MCC ou=People dc=example dc=com
    vlvBase: ou=People,dc=example,dc=com
    vlvScope: 1
    vlvFilter: (ou=accounting)
    • The cn contains the browsing index identifier, which specifies the entry on which to create the browsing index; in this example, the ou=People,dc=example,dc=com entry.
    • The vlvbase attribute value specifies the entry on which you want to create the browsing index; in this example, the ou=People,dc=example,dc=com entry (the browsing index identifier).
    • The vlvScope attribute is 1, indicating that the scope for the search you want to accelerate is 1. A search scope of 1 means that only the immediate children of the entry specified in the cn attribute, and not the entry itself, will be searched.
    • The vlvFilter specifies the filter to be used for the search; in this example, (|(objectclass=*)(objectclass=ldapsubentry)).
  2. Add the second entry, to specify the sorting order for the returned attributes:
    # ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    
    dc=example dc=com,cn=userRoot,cn=ldbm database,cn=plugins,
    cn= config
    objectClass: top
    objectClass: vlvIndex
    cn: by MCC ou=People dc=example dc=com
    vlvSort: cn givenName o ou sn
    • The cn contains the browsing index sort identifier. The entry is a member of the vlvIndex object class.
    • The vlvSort attribute value specifies the order in which you want your attributes to be sorted; in this example, cn, givenName, o, ou, and then sn.

Note

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

13.4.1.2. Recreating the VLV Index

After creating the two browsing indexing entries or added additional attribute types to an existing indexing browsing entries, run the dsconf backend vlv-index reindex command to generate the new set of browsing indexes to be maintained by the Directory Server. After running the command, the new set of browsing indexes is active for any new data added to the directory and any existing data in the directory.
  1. Stop the server.
    # dsctl instance_name stop
  2. Start the reindex process:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend vlv-index reindex --parent-name="by MCC ou=People dc=example dc=com" userRoot
  3. Start the server.
    # dsctl instance_name start

13.4.1.3. Creating a Browsing Index Using a cn=tasks Entry

The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries the server uses to manage tasks. To initiate an index operation, create a task in the cn=index,cn=tasks,cn=config entry.
Use the ldapadd utility to add a new browsing index task. For example:
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=example_VLV_index,cn=index,cn=tasks,cn=config
objectclass: top
objectclass: extensibleObject
cn: example_VLV_index
nsIndexVLVAttribute: "by MCC ou=people,dc=example,dc=com"
Set the nsIndexVLVAttribute attribute to the relative distinguished name RDN of the subentry of the VLV entry definition. The previous example uses the RND created in Section 13.4.1.1, “Adding a Browsing Index Entry”.
The preceding task initiates an operation on Directory Server to creates the index. When the task completes, the cn=tasks,cn=config entry is removed.
For further information, see the cn=index section in the Red Hat Directory Server Configuration, Command, and File Reference.

13.4.2. Setting Access Control for VLV Information

The default access control instruction (ACI) allows only authenticated users to use the VLV index information. If you additionally require to allow non-authenticated users to use the VLV index information, update the aci attribute to set the userdn parameter to ldap://anyone:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: oid=2.16.840.1.113730.3.4.9,cn=features,cn=config
changetype: modify
replace: aci
aci: (targetattr != "aci")(version 3.0; acl "VLV Request Control";
     allow( read, search, compare, proxy ) userdn = "ldap://anyone" ;)

13.5. Changing the Index Sort Order

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

13.5.1. Changing the Sort Order Using the Command Line

To change the sort order using the command line, change the nsMatchingRule for the attribute index. For example:
# ldapmodify -D "cn=Directory Manager" -W -x

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

13.7. Deleting Indexes

This section describes how to remove attributes and index types from the index.

13.7.1. Deleting an Attribute from the Default Index Entry

When using the default settings of Directory Server, several attributes listed in the default index entry, such as sn, are indexed. The following attributes are part of the default index:

Table 13.1. Default Index Attributes

aci
cn
entryusn
givenName
mail
mailAlternateAddress
mailHost
member
memberOf
nsUniqueId
ntUniqueId
ntUserDomainId
numsubordinates
objectclass
owner
parentid
seeAlso
sn
telephoneNumber
uid
uniquemember

Warning

Removing system indexes can significantly affect the Directory Server performance.
For example, to remove the sn attribute from the default index:
  1. Remove the attribute from the cn=default indexes,cn=config,cn=ldbm database,cn=plugins,cn=config entry:
    # ldapdelete -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    cn=sn,cn=default indexes,cn=config,cn=ldbm database,cn=plugins,cn=config
    If you do not remove the attribute from this entry, the index for the sn attribute is automatically recreated and corrupted after the server is restarted.
  2. Remove the cn=attribute_name,cn=index,cn=userRoot,cn=ldbm database,cn=plugins,cn=config entry. For details, see Section 13.7.2, “Removing an Attribute from the Index”

13.7.2. Removing an Attribute from the Index

In certain situations you want to remove an attribute from the index. This section describe the procedure using the command line and using the web console.

13.7.2.1. Removing an Attribute from the Index Using the Command Line

To remove an attribute from the index:
  1. If the attribute to remove is listed in the cn=default indexes,cn=config,cn=ldbm database,cn=plugins,cn=config default index entry, remove it from this entry first. For details, see Section 13.7.1, “Deleting an Attribute from the Default Index Entry”.
  2. Remove the attribute from the index. For example:
    # ldapdelete -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    cn=sn,cn=index,cn=database_name,cn=ldbm database,cn=plugins,cn=config
    After deleting the entry, Directory Server no longer maintains the index for the attribute.

13.7.2.2. Removing an Attribute from the Index Using the Web Console

To remove an attribute from the index:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Database menu.
  4. Select the suffix entry.
  5. Open the Indexes tab.
  6. Click the Actions button next to the attribute for which you want to remove the index, and select Delete Index.
  7. Click Yes to confirm.

13.7.3. Deleting Index Types Using the Command Line

For example, to remove the sub index type of the sn attribute from the index:
  1. Remove the index type:
    # ldapmodify -D "cn=Directory Manager" -W -x
    
    dn: cn=sn,cn=index,cn=database_name,cn=ldbm database,cn=plugins,cn=config
    changetype: modify
    delete: nsIndexType
    nsIndexType: sub
    After deleting the index entry, Directory Server no longer maintains the substring index for the attribute.

13.7.4. Removing Browsing Indexes

This section describes how to remove browsing entries from a database.

13.7.4.1. Removing Browsing Indexes Using the Command Line

The entries for an alphabetical browsing index and virtual list view (VLV) are the same. This section describes the steps involved in removing browsing indexes.
To remove a browsing index or virtual list view index using the command line:
  1. Remove the browsing index entries from the cn=index,cn=database_name,cn=ldbm database,cn=plugins,cn=config entry. For example:
    # ldapdelete -D "cn=Directory Manager" -W -p 389 -h server.example.com -x "cn=MCC ou=People dc=example dc=com,cn=userRoot,cn=ldbm database,cn=plugins,cn=config" "cn=by MCC ou=People dc=example dc=com,cn=MCC ou=People dc=example dc=com,cn=userRoot,cn=ldbm database,cn=plugins,cn=config"
    After deleting the two browsing index entries, Directory Server no longer maintains these indexed.

Chapter 14. Finding Directory Entries

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

14.1. Using ldapsearch

The ldapsearch command-line utility can locate and retrieve directory entries. This utility opens a connection to the specified server using the specified identity and credentials and locates entries based on a specified search filter. The search scope can include a single entry (-s base), an entry's immediate subentries (-s one), or an entire tree or subtree (-s sub).

Note

A common mistake is to assume that the directory is searched based on the attributes used in the distinguished name. The distinguished name is only a unique identifier for the directory entry and cannot be used as a search key. Instead, search for entries based on the attribute-data pairs stored on the entry itself. Thus, if the distinguished name of an entry is uid=bjensen,ou=People,dc=example,dc=com, then a search for dc=example does not match that entry unless dc:example has explicitly been added as an attribute in that entry.
Search results are returned in LDIF format. LDIF is defined in RFC 2849 and is described in detail in Appendix B, LDAP Data Interchange Format.
This section contains information about the following topics:

14.1.1. ldapsearch Command-Line Format

The ldapsearch command must use the following format:
# ldapsearch [-x | -Y mechanism] [options] [search_filter] [list_of_attributes]
  • Either -x (to use simple binds) or -Y (to set the SASL mechanism) must be used to configure the type of connection.
  • options is a series of command-line options. These must be specified before the search filter, if any are used.
  • search_filter is an LDAP search filter as described in Section 14.2, “LDAP Search Filters”. Do not specify a separate search filter if search filters are specified in a file using the -f option.
  • list_of_attributes is a list of attributes separated by a space. Specifying a list of attributes reduces the number of attributes returned in the search results. This list of attributes must appear after the search filter. For an example, see Section 14.3.6, “Displaying Subsets of Attributes”. If a list of attributes is not specified, the search returns values for all attributes permitted by the access control set in the directory, with the exception of operational attributes.
    For operational attributes to be returned as a result of a search operation, hey must be explicitly specified in the search command. To return all operational attributes of an object specify +. To retrieve regular attributes in addition to explicitly specified operational attributes, use an asterisk (*) in the list of attributes in the ldapsearch command.
    To retrieve only a list of matching DNs, use the special attribute 1.1. For example:
    # ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com \
         -b "dc=example,dc=com" -x ""(objectclass=inetorgperson)"" 1.1

14.1.2. Commonly Used ldapsearch Options

The following table lists the most commonly used ldapsearch command-line options. If a specified value contains a space ( ), the value should be surrounded by single or double quotation marks, such as -b "cn=My Special Group,ou=groups,dc=example,dc=com".

Important

The ldapsearch utility from OpenLDAP uses SASL connections by default. To perform a simple bind or to use TLS, use the -x argument to disable SASL and allow other connection methods.
Option Description
-b Specifies the starting point for the search. The value specified here must be a distinguished name that currently exists in the database. This is optional if the LDAP_BASEDN environment variable has been set to a base DN. The value specified in this option should be provided in single or double quotation marks. For example:
-b "cn=user,ou=Product Development,dc=example,dc=com"
To search the root DSE entry, specify an empty string here, such as -b "" .
-D Specifies the distinguished name with which to authenticate to the server. This is optional if anonymous access is supported by the server. If specified, this value must be a DN recognized by the Directory Server, and it must also have the authority to search for the entries. For example, -D "uid=user_name,dc=example,dc=com".
-H
Specifies an LDAP URL to use to connect to the server. For a traditional LDAP URL, this has the following format:
ldap[s]://hostname[:port]
The port is optional; it will use the default LDAP port of 389 or LDAPS port of 636 if the port is not given.
This can also use an LDAPI URL, with each element separated by the HTML hex code %2F, rather than a forward slash (/):
ldapi://%2Ffull%2Fpath%2Fto%2Fslapd-example.socket
For LDAPI, specify the full path and filename of the LDAPI socket the server is listening to. Since this value is interpreted as an LDAP URL, the forward slash characters (/) in the path and filename must be escaped encoded as the URL escape value %2F.
The -H option is used instead of -h and -p.
-h Specifies the host name or IP address of the machine on which the Directory Server is installed. For example, -h server.example.com. If a host is not specified, ldapsearch uses the localhost.

Note

Directory Server supports both IPv4 and IPv6 addresses.
-l Specifies the maximum number of seconds to wait for a search request to complete. For example, -l 300. The default value for the nsslapd-timelimit attribute is 3600 seconds. Regardless of the value specified, ldapsearch will never wait longer than is allowed by the server's nsslapd-timelimit attribute.
-p Specifies the TCP port number that the Directory Server uses. For example, -p 1049. The default is 389.
If -h is specified, -p must also be specified, even if it gives the default value.
-s scope Specifies the scope of the search. The scope can be one of the following:
base searches only the entry specified in the -b option or defined by the LDAP_BASEDN environment variable.
one searches only the immediate children of the entry specified in the -b option. Only the children are searched; the actual entry specified in the -b option is not searched.
sub searches the entry specified in the -b option and all of its descendants; that is, perform a subtree search starting at the point identified in the -b option. This is the default.
-W
Prompt for the password. If this option is not set, anonymous access is used.
Alternatively, use the -w option to pass the password to the utility. Note that the password can be visible in the process list for other users and is saved in the shell's history.
-x Disables the default SASL connection to allow simple binds.
-Y SASL_mechanism
Sets the SASL mechanism to use for authentication. If no mechanism is set, ldapsearch selects the best mechanism supported by the server.
If If -x is not used, then the -Y option must be used.
-z number Sets the maximum number of entries to return in a response to a search request. This value overwrites the server-side nsslapd-sizelimit parameter when binding using the root DN. wibrown>

14.1.3. Using Special Characters

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

14.2. LDAP Search Filters

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

Note

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

Note

A common mistake is to assume that the directory is searched based on the attributes used in the distinguished name. The distinguished name is only a unique identifier for the directory entry and cannot be used as a search key. Instead, search for entries based on the attribute-data pairs stored on the entry itself. Thus, if the distinguished name of an entry is uid=user_name,ou=People,dc=example,dc=com, then a search for dc=example does not match that entry unless the dc attribute exists in this entry and is set to example.

14.2.1. Using Attributes in Search Filters

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

14.2.2. Using Operators in Search Filters

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

Table 14.1. Search Filter Operators

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

14.2.3. Using Compound Search Filters

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

Table 14.2. Search Filter Boolean Operators

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