Menu Close
Settings Close

Language and Page Formatting Options

Administration Guide

Red Hat Directory Server 11

Basic and advanced administration of Directory Server

Abstract

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

Making Open Source More Inclusive

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

Chapter 1. General Directory Server Management Tasks

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

1.1. System Requirements

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

1.2. File Locations

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 Red Hat Directory Server entry.

1.5. Starting and Stopping a Directory Server Instance

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

Use the dsctl utility to start, stop, or restart an instance:
  • To start the instance:
    # dsctl instance_name start
  • To stop the instance:
    # dsctl instance_name stop
  • To restart the instance:
    # dsctl instance_name restart
Optionally, you can enable Directory Server instances to automatically start when the system boots:
  • For a single instance:
    # systemctl enable dirsrv@instance_name
  • For all instances on a server:
    # systemctl enable dirsrv.target
For further details, see the Managing System Services section in the Red Hat System Administrator's Guide.

1.5.2. Starting and Stopping a Directory Server Instance Using the Web Console

As an alternative to command line, you can use the web console to start, stop, or restart instances.
To start, stop, or restart a Directory Server instance:
  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/ and /etc/dirsrv/slapd-instance_name/ directories are removed.

Important

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

1.7.1. Removing an Instance Using the Command Line

To remove an instance using the command line:
# dsctl instance_name remove --do-it
Removing instance ...
Completed instance removal

1.7.2. Removing an Instance Using the Web Console

To remove an instance using the web console:
  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

To change the port numbers using the command line, update the following parameters:
  • nsslapd-port: Stores the port number the instance uses for the LDAP protocol.
  • nsslapd-secureport: Stores the port number the instance uses for the LDAPS protocol.
To change the port numbers of the LDAP and LDAPS protocol using the command line:
  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.
    2. On the Server Settings tab, fill the new port number into the LDAP Port field.
    3. Click Save.
  4. To change the LDAPS port:
    1. Open the Server Settings menu.
    2. On the General Settings tab, fill the new port number into the LDAPS Port field.
    3. Click Save.

1.10. Using Directory Server Plug-ins

Directory Server provides several core plug-ins, such as for replication, class of service, and attribute syntax validation. Core plug-ins are enabled by default.
Additionally, the Directory Server packages contain further plug-ins to enhance the functionality, such as for attribute uniqueness and attribute linking. However, not all of these plug-ins are enabled by default.
For further details, see the Plug-in Implemented Server Functionality Reference chapter in the Red Hat Directory Server  Configuration, Command, and File Reference.

1.10.1. Listing Available Plug-ins

1.10.1.1. Listing Available Plug-ins Using the Command Line

To list all available plug-ins using the command line:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin list
7-bit check
Account Policy Plugin
...
You require the exact name of the plug-in, for example, to enable or disable it using the command line.

1.10.1.2. Listing Available Plug-ins Using the Web Console

To display all available plug-ins using the web console:
  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 Filter 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 Automember plug-in:
  1. Enable the plug-in:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin automember 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.

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

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

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

1.11.1. How a .dsrc File Simplifies Commands

The following is an example of a ~/.dsrc file that specifies the LDAP URL of an instance and a bind DN:
[server1]
uri = ldap://server1.example.com
binddn = cn=Directory Manager
binddn = dc=example,dc=com
With these settings, you can use shorter Directory Server commands. For example, to create a user account:
# dsidm server1 user create
Without the ~/.dsrc file, you must specify the bind DN, LDAP URL, and base DN in the command:
# dsidm -D cn=Directory Manager ldap://server1.example.com -b "dc=example,dc=com" user create

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

Instead of manually creating a ~/.dsrc file, you can use the dsctl utility to create it:
# dsctl instance_name dsrc create ...
You can pass the following options to the command:
  • --uri: Sets the URL to the instance in the format protocol://host_name_or_IP_address_or_socket.
    Examples:
    • --uri ldap://server.example.com
    • --uri = ldaps://server.example.com
    • --uri = ldapi://%%2fvar%%2frun%%2fslapd-instance_name.socket
      If you set the path to an Directory Server socket, use %%02 instead of slashes (/) in the path.

      Important

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

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:
  1. Optional: Identify the suffixes and back end databases that are already in use:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list
    dc=example,dc=com (userroot)
    The name in parentheses is the back end database that stores the data of the corresponding suffix. You cannot use existing database names when you create the root suffix in the next step.
  2. Create the dc=example,dc=net root suffix in the example back end database:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend create \
         --suffix="dc=example,dc=net" --be-name="example"
2.1.1.1.2. Creating a Root Suffix Using the Web Console
To create a new root suffix using the web console:
  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. Select Create The Top Suffix Entry.
  7. 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:
  1. Optional: Identify the suffixes and back end databases that are already in use:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list
    dc=example,dc=com (userroot)
    The name in parentheses is the back end database that stores the data of the corresponding suffix. You cannot use existing database names when you create the sub-suffix in the next step.
  2. Create the sub-suffix. For example, to create the ou=People,dc=example,dc=com sub-suffix along with the example back end database, enter:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend create \
         --suffix="ou=People,dc=example,dc=com" --be-name="example" \
         --parent-suffix="dc=example,dc=com"
2.1.1.2.2. Creating a Sub-suffix Using the Web Console
To create a new sub-suffix using the web console:
  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. Select Create The Top Sub-Suffix Entry.
  7. 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. To add a new database:
  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-supplier replication, this might not be a problem.
2.2.2.1.1. Setting a Database in Read-only Mode Using the Command Line
To set a database in read-only mode, use the dsconf backend suffix set command. For example, to set the database of the o=test suffix in read-only mode:
  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 on:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-readonly=on
  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, and select the Server Settings entry.
  4. On the Advanced Settings tab, select Server Read-Only.
  5. 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 backend suffix set --add-referral="ldap://directory.example.com/" database_name

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.

2.6. Verifying the Integrity of Back-end Databases

The dsctl dbverify command enables administrators to verify the integrity of back-end databases. For example, to verify the userroot database:
  1. Optionally, list the back-end databases of the instance:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list
    dc=example,dc=com (userroot)
    You need the name of the database in a later step.
  2. Stop the Directory Server instance:
    # dsctl instance_name stop
  3. Verify the database:
    # dsctl instance_name dbverify userroot
    [04/Feb/2020:13:11:02.453624171 +0100] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
    [04/Feb/2020:13:11:02.465339507 +0100] - WARN - ldbm_instance_add_instance_entry_callback - ldbm instance userroot already exists
    [04/Feb/2020:13:11:02.468060144 +0100] - ERR - ldbm_config_read_instance_entries - Failed to add instance entry cn=userroot,cn=ldbm database,cn=plugins,cn=config
    [04/Feb/2020:13:11:02.471079045 +0100] - ERR - bdb_config_load_dse_info - failed to read instance entries
    [04/Feb/2020:13:11:02.476173304 +0100] - ERR - libdb - BDB0522 Page 0: metadata page corrupted
    [04/Feb/2020:13:11:02.481684604 +0100] - ERR - libdb - BDB0523 Page 0: could not check metadata page
    [04/Feb/2020:13:11:02.484113053 +0100] - ERR - libdb - /var/lib/dirsrv/slapd-instance_name/db/userroot/entryrdn.db: BDB0090 DB_VERIFY_BAD: Database verification failed
    [04/Feb/2020:13:11:02.486449603 +0100] - ERR - dbverify_ext - verify failed(-30970): /var/lib/dirsrv/slapd-instance_name/db/userroot/entryrdn.db
    dbverify failed
  4. If the verification process reported any problems, fix them manually or restore a backup.
  5. Start the Directory Server instance:
    # dsctl instance_name start

Chapter 3. Managing Directory Entries

You can manage directory entries using the command line or the web console.

3.1. Managing Directory Entries Using the Command Line

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:
# yum 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.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.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.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.1.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.1.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.1.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.1.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.1.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.1.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.1.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,ou=People,dc=example,dc=com entry:
# 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: 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,ou=People,dc=example,dc=com:
# 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: telephoneNumber
telephoneNumber: 555-1234567
telephoneNumber: 555-7654321

3.1.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,ou=People,dc=example,dc=com entry:
# 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: manager
manager: uid=manager_name,ou=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,ou=People,dc=example,dc=com entry:
# 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
telephoneNumber: 555-1234567
-
add: telephoneNumber
telephoneNumber: 555-9876543

3.1.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,ou=People,dc=example,dc=com entry:
# 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: 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,ou=People,dc=example,dc=com entry:
# 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
telephoneNumber: 555-1234567

3.1.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.1.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.1.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,ou=People,dc=example,dc=com
changetype: delete

3.1.6. Renaming and Moving an Entry

This section explains how to rename or move entries.

Note

Use the moddn Access Control List (ACL) to grant permissions to move entries. For details, see Section 18.9.2.1, “Targeting Source and Destination DNs”.
The following rename operations exist:
Renaming an Entry
If you rename an 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.1.6.1. 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.1.6.2. Renaming Users, Groups, POSIX Groups, and OUs

The dsidm utility can rename several types of objects:
  • Users:
    # dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" user rename current_user_name new_user_name
    Note that the dsidm user rename command automatically places ou=People in front of the base DN you have specified.
  • Groups:
    # dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" group rename current_group_name new_group_name
    Note that the dsidm group rename command automatically places ou=Groups in front of the base DN you have specified.
  • POSIX Groups:
    # dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" posixgroup rename current_posix_group_name new_posix_group_name
    Note that the dsidm posixgroup rename command automatically places ou=Groups in front of the base DN you have specified.
  • Organizational Units (OU)
    # dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" organizationalunit rename current_ou_name new_ou_name
    The dsidm organizationalunit rename command performs the rename operation directly in the base DN you have specified.

3.1.6.3. The deleteOldRDN Parameter When Renaming Entries Using LDIF Statements

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.1.6.4. Renaming an Entry or Subtree Using LDIF Statements

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=demo1,dc=example,dc=com entry to cn=demo2,dc=example,dc=com:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=demo1,dc=example,dc=com
changetype: modrdn
newrdn: cn=demo2
deleteOldRDN: 1

3.1.6.5. Moving an Entry to a New Parent Using LDIF Statements

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 cn=demo entry from ou=Germany,dc=example,dc=com to ou=France,dc=example,dc=com:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=demo,ou=Germany,dc=example,dc=com
changetype: modrdn
newrdn: cn=demo
newSuperior: ou=France,dc=example,dc=com
deleteOldRDN: 1

3.1.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.1.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 ldapmodify utility.
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 /home/user_name/photo.jpg file, enter:
# 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:< file:///home/user_name/photo.jpg

Important

Note that there is no space between : and <.

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

3.2. Managing Directory Entries Using the Web Console

You can add, edit, rename, and delete LDAP entries using the web console.

3.2.1. Adding an LDAP Entry Using the Web Console

You can use the LDAP Browser in the web console to search for entries in the Directory Server databases.
You can create the following entries using the web console:
  • users
  • groups
  • roles
  • organizational units (OUs)
  • custom entries
For example, you want to create a POSIX user cn=John Smith,ou=people,dc=example,dc=com with a password.

Prerequisites

  • You are logged in to the Directory Server web console.
  • The parent entry exists. For example, ou=people,dc=example,dc=com.

Procedure

  1. In the web console, open the LDAP Browser menu to reveal the list of existing suffixes.
  2. Using the Tree or Table view, expand the parent entry ou=people,dc=example,dc=com under which you want to create a user.
  3. Click the Options menu (⫶) and select New to open the wizard window.
  4. Select the Create a new User option and click Next.
  5. For the user entry, select Posix Account type and click Next.
  6. Optional: Select additional attributes, such as userPassword, and click Next. You can view all selected attributes by expanding the drop-down list near the step name.
  7. Set a value for each attribute:
    1. Click on the pencil button of the attribute and add a value.
      Note that a separate menu opens when you set the userPassword value. The value is filled with asterisks (*) to hide the plain text.
    2. Click on the check button to save changes.
    3. Optional: Set an additional attribute value by clicking the Options menu (⫶)Add Another Value.
    4. After you have set all values, click Next.
  8. Verify that all entry details are correct and click Create User. Directory Server creates the entry with mandatory attributes for a POSIX user and sets the password to it. You can click Back to modify entry settings, or click Cancel to cancel the entry creation.
  9. View the Result for Entry Creation and click Finish.

Verification

  1. Navigate to LDAP BrowserSearch.
  2. Select the database suffix that contains the entry, such as dc=example,cd=com.
  3. Enter your search criteria in the field, such as John, and press Enter.
  4. Find the entry you recently created in the list of entries.

3.2.2. Editing an LDAP Entry Using the Web Console

You can modify a directory entry using the web console. This example modifies a user entry cn=John Smith,ou=people,dc=example,dc=com by:
  • adding telephone numbers 556778987 and 556897445.
  • adding email jsmith@example.com.
  • changing the password.

Prerequisites

You are logged into the Directory Server web console.

Procedure

  1. In the web console, open the LDAP Browser menu to reveal the list of existing suffixes.
  2. Using the Tree or Table view, expand the entry you want to edit, such as cn=John Smith,ou=people,dc=example,dc=com.
  3. Click the Options menu (⫶) and select Edit to open the wizard window.
  4. Optional: In the Select ObjectClasses step, add or delete object classes for the entry. Click Next.
  5. In the Select Attributes step, add telephoneNumber and mail attributes to the entry and click Next. If you do not see an attribute you want to add to the entry it means that you did not add corresponding object class in the previous step.

    Note

    In this step, you can not delete mandatory attributes of the selected object classes.
  6. In the Edit Attribute Values step, set telephoneNumber to 556778987 and 556897445, mail to jsmith@example.com and change userPassword value:
    1. Click on the pencil button of the attribute and add or change a new value.
    2. Click on the check button to save changes.
    3. Optional: Set an additional value to an attribute by clicking the Options menu (⫶)Add Another Value. The telephoneNumber attribute has two values in this example. When you set all values, click Next.
  7. Review your changes and click Next.
  8. To edit the entry, click Modify Entry. You can click Back to modify entry settings, or click Cancel to cancel the entry editing.
  9. View the Result for Entry Modification and click Finish.

Verification

  • Expand the entry details and view the new changes appear among the entry attributes.

3.2.3. Renaming and Relocating an LDAP Entry or Subtree Using the Web Console

You can rename or relocate a directory entry or a subtree using the web console. This example renames and relocates the entry cn=John Smith,ou=people,dc=example,dc=com to cn=Tom Smith,ou=clients,dc=example,dc=com.

Prerequisites

You are logged into the Directory Server web console.

Procedure

  1. In the web console, open the LDAP Browser menu to reveal the list of existing suffixes.
  2. Using the Tree or Table view, expand the entry you want to modify, such as cn=John Smith,ou=people,dc=example,dc=com.
  3. Click the Options menu (⫶) and select Rename to open the wizard window.
  4. In the Select The Naming Attribute And Value step:
    1. Set a new value Tom Smith for the naming attribute cn and click Next.
    2. Optional: Select another naming attribute from the drop-down menu.
    3. Optional: In case you want to delete the old entry and create a new one using the new RDN, check Delete the old RDN.
  5. In Select The Entry Location step, select the parent entry for the new location, and click Next.
  6. Review changes you made to the entry and click Next.
  7. If the entry details are correct, click Change Entry Name. You can click Back to make other changes to the entry or click Cancel to cancel the entry modification.
  8. View Result for Entry Modification and click Finish.

Verification

  • Expand the entry details and review the updated entry.

3.2.4. Deleting an LDAP Entry Using the Web Console

You can delete a directory entry or a subtree using the web console. This example deletes the entry cn=Tom Smith,ou=clients,dc=example,dc=com.

Prerequisites

You are logged into the Directory Server web console.

Procedure

  1. In the web console, open the LDAP Browser menu to reveal the list of existing suffixes.
  2. Using the Tree or Table view, expand the entry you want to delete, such as cn=Tom Smith,ou=clients,dc=example,dc=com.
  3. Click the Options menu (⫶) and select Delete to open the wizard window.
  4. Click Next after you review the data about the entry you want to delete.
  5. In the Deletion step, toggle the switch to the Yes, I’m sure position and click Delete. You can click Cancel to cancel the entry deletion.
  6. View the Result for Entry Deletion and click Finish.

Verification

  1. Navigate to LDAP BrowserSearch.
  2. Select the suffix where the entry previously existed, such as dc=example,cd=com.
  3. Enter your search criteria in the field, such as Tom, and press Enter.
  4. Verify that the deleted entry is no longer present.

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.4.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.4.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. Select the Plugins menu.
  4. Select the USN plug-in.
  5. Verify that the USN Global switch is set to On.

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. Change the USN Global status to On.
  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.

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.4.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. Open the Server Settings menu, and select the Server Settings entry.
  4. On the Advanced Settings tab, 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 20.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

You must enable Referential Integrity Postoperation plug-in on all suppliers in a multi-supplier replication environment.
When you delete, rename, or move a user or group entry 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 renamed or moved, the value of the corresponding attribute in the directory is renamed.
By default, when the Referential Integrity Postoperation plug-in is enabled, it performs integrity updates on the member, uniquemember, owner, and seeAlso attributes immediately after a delete or rename operation. However, you can configure the behavior of the Referential Integrity Postoperation plug-in 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, equality, and substring; 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.
  • Enable it on a supplier server that contains only read-write replicas.
  • Enable the plug-in for each supplier server in multi-supplier replication topology. The plug-in configuration must be the same on all supplier 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 and hub 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 plugin referential-integrity 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.

5.4. The Referential Integrity Update Interval

By default, the server performs Referential Integrity updates immediately after a delete or rename 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

In multi-supplier replication environment, Red Hat recommends setting the update interval to 0 on all suppliers.

Note

On a supplier, if you set the interval to a value greater than 0 (for example, 5) there is a chance that the supplier receives a direct delete or rename operation, replicate the operation, and go offline before it cleans up the references to the target entry. In such cases, the rest of the topology still contains references to the target entry until the server is up again (possibly longer than 5 sec).

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.

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.

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

    Important

    To import data, you must store the LDIF file that you want to import in the /var/lib/dirsrv/slapd-instance_name/ldif/ directory.
  • Initializing a database for replication
The following table 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 supplier 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-supplier 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-supplier 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

This section describes how you can import data while Directory 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:
  1. Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
  2. If the LDIF you want to import does not contain statements that add the suffix entry, create this entry manually as described in Section 3.1.3.3, “Creating a Root Entry”.
  3. Import the LDIF file:
    # 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 /var/lib/dirsrv/slapd-instance_name/ldif/example.ldif file into the userRoot database:
  1. Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
  2. If the LDIF you want to import does not contain statements that add the suffix entry, create this entry manually as described in Section 3.1.3.3, “Creating a Root Entry”.
  3. Add the import task:
    # 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: /var/lib/dirsrv/slapd-instance_name/ldif/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. Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
  2. If the LDIF you want to import does not contain statements that add the suffix entry, create this entry manually as described in Section 3.1.3.3, “Creating a Root Entry”.
  3. Stop the instance:
    # dsctl instance_name stop
  4. Import the data from the LDIF file. For example, to import the /var/lib/dirsrv/slapd-instance_name/ldif/example.ldif file into the userRoot database:
    # dsctl instance_name ldif2db userroot /var/lib/dirsrv/slapd-instance_name/ldif/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.
  5. 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. Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
  2. If the LDIF you want to import does not contain statements that add the suffix entry, create this entry manually as described in Section 3.1.3.3, “Creating a Root Entry”.
  3. Store the LDIF file you want to import in the /var/lib/dirsrv/slapd-instance_name/ldif/ directory.
  4. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  5. Select the instance.
  6. Open the Database menu.
  7. Select the suffix entry.
  8. Click Suffix Tasks, and select Initialize Suffix.
  9. Select the LDIF file to import or enter the full path to the file.
  10. Select Yes, I am sure., and click Initialize Database to confirm.

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 /var/lib/dirsrv/slapd-instance_name/ldif/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: /var/lib/dirsrv/slapd-instance_name/ldif/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 /var/lib/dirsrv/slapd-instance_name/ldif/example.ldif file:
    # dsctl instance_name db2ldif userroot /var/lib/dirsrv/slapd-instance_name/ldif/example.ldif 
    OK group dirsrv exists
    OK user dirsrv exists
    ldiffile: /var/lib/dirsrv/slapd-instance_name/ldif/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.2.3. Enabling Members of a Group to Export Data and Performing the Export as One of the Group Members

You can configure that members of a group have permissions to export data. This increases the security because you no longer need to set the credentials of cn=Directory Manager in your scripts. Additionally, you can easily grant and revoke the export permissions by modifying the group.

6.2.3.1. Enabling a Group to Export Data

Use this procedure to add the cn=export_users,ou=groups,dc=example,dc=com group and enable members of this group to create export tasks.

Procedure

  1. Create the cn=export_users,ou=groups,dc=example,dc=com group:
    # dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" group create --cn export_users
  2. Add access control instructions (ACI) that allows members of the cn=export_users,ou=groups,dc=example,dc=com group to create export tasks:
    # ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com
    
    dn: cn=config
    changetype: modify
    add: aci
    aci: (target = "ldap:///cn=export,cn=tasks,cn=config")(targetattr="*")
     (version 3.0 ; acl "permission: Allow export_users
      group to export data" ; allow (add, read, search) groupdn
      = "ldap:///cn=export_users,ou=groups,dc=example,dc=com";)
    -
    add: aci
    aci: (target = "ldap:///cn=config")(targetattr =
      "objectclass || cn || nsslapd-suffix || nsslapd-ldifdir")
     (version 3.0 ; acl "permission: Allow export_users
      group to access ldifdir attribute" ; allow
      (read,search) groupdn = "ldap:///cn=export_users,ou=groups,dc=example,dc=com";)
  3. Create a user:
    1. Create a user account:
      # dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" user create --uid="example" --cn="example" --uidNumber="1000" --gidNumber="1000" --homeDirectory="/home/example/" --displayName="Example User"
    2. Set a password on the user account:
      # dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" account reset_password "uid=example,ou=People,dc=example,dc=com" "password"
  4. Add the uid=example,ou=People,dc=example,dc=com user to the cn=export_users,ou=groups,dc=example,dc=com group:
    # dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" group add_member export_users uid=example,ou=People,dc=example,dc=com

Verification

  • Display the ACIs set on the cn=config:
    # ldapsearch -o ldif-wrap=no -LLLx -D "cn=Directory Manager" -W -H ldap://server.example.com -b cn=config aci=* aci -s base
    dn: cn=config
    aci: (target = "ldap:///cn=export,cn=tasks,cn=config")(targetattr="*")(version 3.0 ; acl "permission: Allow export_users group to export data" ; allow (add, read, search) groupdn = "ldap:///cn=export_users,ou=groups,dc=example,dc=com";)
    aci: (target = "ldap:///cn=config")(targetattr = "objectclass || cn || nsslapd-suffix || nsslapd-ldifdir")(version 3.0 ; acl "permission: Allow export_users group to access ldifdir attribute" ; allow (read,search) groupdn = "ldap:///cn=export_users,ou=groups,dc=example,dc=com";)
    ...

6.2.3.2. Performing an Export as a Regular User

You can perform exports as a regular user instead of cn=Directory Manager.

Prerequisites

Procedure

  • Create a export task using one of the following methods:
    • Using the dsconf backend export command:
      # dsconf -D "uid=example,ou=People,dc=example,dc=com" ldap://server.example.com backend export userRoot
    • By manually creating the task:
      # ldapadd -D "uid=example,ou=People,dc=example,dc=com" -W -H ldap://server.example.com
      
      dn: cn=userRoot-2021_07_23_12:55_00,cn=export,cn=tasks,cn=config
      changetype: add
      objectClass: extensibleObject
      nsFilename: /var/lib/dirsrv/slapd-instance_name/ldif/None-userroot-2021_07_23_12:55_00.ldif
      nsInstance: userRoot
      cn: export-2021_07_23_12:55_00

Verification

  • Verify that the backup was created:
    # ls -l /var/lib/dirsrv/slapd-instance_name/ldif/*.ldif
    total 0
    -rw-------. 1 dirsrv dirsrv 10306 Jul 23 12:55 None-userroot-2021_07_23_12_55_00.ldif
    ...

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.
# 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
    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 Manage Backup.
  4. Click Create Backup.
  5. Enter a name for the backup, such as a time stamp to indicate the creation date and time of the backup.
  6. Click Create 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.3.4. Enabling Members of a Group to Back up Directory Server and Performing the Backup as One of the Group Members

You can configure that members of a group have permissions to back up an instance and perform the backup. This increases the security because you no longer need to set the credentials of cn=Directory Manager in your backup script or cron jobs. Additionally, you can easily grant and revoke the backup permissions by modifying the group.

6.3.4.1. Enabling a Group to Back up Directory Server

Use this procedure to add the cn=backup_users,ou=groups,dc=example,dc=com group and enable members of this group to create backup tasks.

Procedure

  1. Create the cn=backup_users,ou=groups,dc=example,dc=com group:
    # dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" group create --cn backup_users
  2. Add access control instructions (ACI) that allows members of the cn=backup_users,ou=groups,dc=example,dc=com group to create backup tasks:
    # ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com
    
    dn: cn=config
    changetype: modify
    add: aci
    aci: (target = "ldap:///cn=backup,cn=tasks,cn=config")(targetattr="*")
     (version 3.0 ; acl "permission: Allow backup_users
      group to create backup tasks" ; allow (add, read, search) groupdn
      = "ldap:///cn=backup_users,ou=groups,dc=example,dc=com";)
    -
    add: aci
    aci: (target = "ldap:///cn=config")(targetattr = "nsslapd-bakdir || objectClass")
     (version 3.0 ; acl "permission: Allow backup_users group
      to access bakdir attribute" ; allow (read,search) groupdn
      = "ldap:///cn=backup_users,ou=groups,dc=example,dc=com";)
  3. Create a user:
    1. Create a user account:
      # dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" user create --uid="example" --cn="example" --uidNumber="1000" --gidNumber="1000" --homeDirectory="/home/example/" --displayName="Example User"
    2. Set a password on the user account:
      # dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" account reset_password "uid=example,ou=People,dc=example,dc=com" "password"
  4. Add the uid=example,ou=People,dc=example,dc=com user to the cn=backup_users,ou=groups,dc=example,dc=com group:
    # dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" group add_member backup_users uid=example,ou=People,dc=example,dc=com

Verification

  • Display the ACIs set on the cn=config entry:
    # ldapsearch -o ldif-wrap=no -LLLx -D "cn=directory manager" -W -H ldap://server.example.com -b cn=config aci=* aci -s base
    dn: cn=config
    aci: (target = "ldap:///cn=backup,cn=tasks,cn=config")(targetattr="*")(version 3.0 ; acl "permission: Allow backup_users group to create backup tasks" ; allow (add, read, search) groupdn = "ldap:///cn=backup_users,ou=groups,dc=example,dc=com";)
    aci: (target = "ldap:///cn=config")(targetattr = "nsslapd-bakdir || objectClass")(version 3.0 ; acl "permission: Allow backup_users group to access bakdir attribute" ; allow (read,search) groupdn = "ldap:///cn=backup_users,ou=groups,dc=example,dc=com";)
    ...

6.3.4.2. Performing a Backup as a Regular User

You can perform backups as a regular user instead of cn=Directory Manager.

Prerequisites

Procedure

  • Create a backup task using one of the following methods:
    • Using the dsconf backup create command:
      # dsconf -D uid=example,ou=People,dc=example,dc=com ldap://server.example.com backup create
    • By manually creating the task:
      # ldapadd -D uid=example,ou=People,dc=example,dc=com -W -H ldap://server.example.com
      
      dn: cn=backup-2021_07_23_12:55_00,cn=backup,cn=tasks,cn=config
      changetype: add
      objectClass: extensibleObject
      nsarchivedir: /var/lib/dirsrv/slapd-instance_name/bak/backup-2021_07_23_12:55_00
      nsdatabasetype: ldbm database
      cn: backup-2021_07_23_12:55_00

Verification

  • Verify that the backup was created:
    # ls -l /var/lib/dirsrv/slapd-instance_name/bak/
    total 0
    drwx------. 3 dirsrv dirsrv 108 Jul 23 12:55 backup-2021_07_23_12_55_00
    ...

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/
    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.
  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. Open the Actions menu next to the backup you want to restore, and select Restore Backup.
  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.8.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 suppliers and two consumer server:
  1. Restore the first supplier. 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 supplier from the first one.
    2. Initialize the consumers from the supplier.
  3. On each server, display the replication status to verify that replication works correctly. For details, see Section 15.22, “Displaying the Status of a Specific Replication Agreement”.
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.10.7. The costargettree attribute

The costargettree attribute defines the subtrees to which the CoS schema applies. The values for costargettree for the schema and for multiple CoS schema may overlap their target trees arbitrarily.

Table 7.1. The costargettree attribute

OID 2.16.840.1.113730.3.1.552
Syntax DirectoryString
Multi or Single-Valued Single-valued
Defined in Directory Server

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-supplier 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-supplier replication, when each supplier 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 --magic-regen magic
    For details about the value you can set in the --magic-regen parameter, see the dnaMagicRegen attribute description in the Configuration, Command and File Reference.
  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. 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 set --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 set --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 set --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 set --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 set --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 "(|(objectclass=inetuser)(objectclass=inetadmin)(objectclass=nsmemberof))" "dc=example,dc=com"
Attempting to add task entry...
Successfully added task entry
The -f filter option is optional. Use the filter 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. 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

By default, the autoMemberProcessModifyOps parameter in the cn=Auto Membership Plugin,cn=plugins,cn=config entry is set to on. With this setting, the Automembership plug-in also updates group memberships when an administrator moves a user to a different group by editing a user entry.
If you set autoMemberProcessModifyOps to off, Directory Server invokes the plug-in only when you add a group entry to the user, and you must manually run a fix-up task to update 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 Membership plug-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

By default, the autoMemberProcessModifyOps parameter in the cn=Auto Membership Plugin,cn=plugins,cn=config entry is enabled. With this setting, the Automembership plug-in also updates group memberships when an administrator moves a user to a different group by editing a user entry. However, if you set autoMemberProcessModifyOps to off, you must manually run a fix-up task when you added new entries to the directory or changed existing entries.
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