Administration Guide
Updated for Directory Server 10.6
Abstract
Deprecated Documentation
Important
Chapter 1. Basic Red Hat Directory Server Settings
- The Directory Server is the core LDAP server daemon. It is compliant with LDAP v3 standards. This component includes command-line server management and administration programs and scripts for common operations like export and backing up databases.
- The Directory Server Console is the user interface that simplifies management of users, groups, and other LDAP data. The Console is used for all aspects of the server management, including backups; security, replication, or databases configuration; server monitoring; and viewing statistics.
- The Administration Server is the management agent which administers Directory Server instances. It communicates with the Directory Server Console and performs operations on the Directory Server instances. It also provides a simple HTML interface and online help pages.
1.1. System Requirements
1.2. File Locations
1.3. Starting the Directory Server Management Console
- Managing Directory Server instances
- Managing the Administration Server
- Managing users and groups
Note
# redhat-idm-console
1.3.1. Opening the Directory Server Console
- Start the Directory Server Management Console:
# redhat-idm-console
- Log in as the
cn=Directory Manager
user: - On the Servers and Applications tab, navigate to → → → , and click .
1.3.2. Opening the Administration Server Console
- Start the Directory Server Management Console:
# redhat-idm-console
- Log in as the
cn=Directory Manager
user: - On the Servers and Applications tab, navigate to → → → , and click .
1.4. Starting and Stopping a Directory Server Instance
1.4.1. Starting and Stopping a Directory Server Instance Using the Command Line
systemctl
utility to start, stop, or restart an instance:
- To start an instance:
# systemctl start dirsrv@instance_name
- To stop an instance:
# systemctl stop dirsrv@instance_name
- To restart an instance:
# systemctl restart dirsrv@instance_name
- for a single instance:
# systemctl enable dirsrv@instance_name
- for all instances on a server:
# systemctl enable dirsrv.target
1.4.2. Starting and Stopping a Directory Server Instance Using the Console
Important
enforcing
mode, you cannot use the Console to start or stop an instance. To work around the problem, use the command line to manage the services. See Section 1.4, “Starting and Stopping a Directory Server Instance”.
Important
- use the command line to manage the service. See Section 1.4.1, “Starting and Stopping a Directory Server Instance Using the Command Line”.
- create a password file. See Section 9.4.1.5, “Creating a Password File for Directory Server”.
- Start the Directory Server Console and log in using the
cn=Directory Manager
user name.For details, see Section E.2.2, “Opening the Administration Server Console”. - On the Servers and Applications tab, navigate to → → → , and click .
- On the Tasks tab, click the task you want to execute:
- Clickto confirm.
1.5. Starting and Stopping the Directory Server Administration Server Service
1.5.1. Starting and Stopping the Administration Server Service Using the Command Line
systemctl
utility to start, stop, or restart the Administration Server service:
- To start the service:
# systemctl start dirsrv-admin
- To stop the service:
# systemctl stop dirsrv-admin
- To restart the service:
# systemctl restart dirsrv-admin
# systemctl enable dirsrv-admin
1.5.2. Restarting and Stopping the Administration Server Service Using the Console
- Start the Directory Server Console and log in using the
cn=Directory Manager
user name.For details, see Section E.2.2, “Opening the Administration Server Console”. - On the Servers and Applications tab, navigate to → → → , and click .
- On the Tasks tab, click the task you want to execute:
- Clickto confirm.
1.6. Enabling LDAPI
nsslapd-ldapilisten
to enable LDAPI for Directory Servernsslapd-ldapifilepath
to point to the Unix socket file
- Modify the
nsslapd-ldapilisten
to turn LDAPI on and add the socket file attribute.# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=config changetype: modify replace: nsslapd-ldapilisten nsslapd-ldapilisten: on - add: nsslapd-ldapifilepath nsslapd-ldapifilepath: /var/run/slapd-example.socket
- Restart the server to apply the new configuration.
# systemctl restart dirsrv@instance
1.7. Changing Directory Server Port Numbers
nsslapd-port
or nsslapd-secureport
attribute under the cn=config
entry in the dse.ldif
.
Note
o=NetscapeRoot
subtree, should be done through the Directory Server Console.
1.7.1. Changing Standard Port Numbers
- In the Directory Server Console, select the Configuration tab, and then select the top entry in the navigation tree in the left pane.
- Select the Settings tab in the right pane.
- Change the port numbers. The port number for the server to use for non-TLS communications in the Port field, with a default value of
389
. - Click.
- The Console returns a warning, You are about to change the port number for the Configuration Directory. This will affect all Administration Servers that use this directory and you'll need to update them with the new port number. Are you sure you want to change the port number? Click .
- Then a dialog appears, reading that the changes will not take effect until the server is restarted. Click.
Note
Do not restart the Directory Server at this point. If you do, you will not be able to make the necessary changes to the Administration Server through the Console. - Open the Administration Server Console.
- In the Configuration tab, select the Configuration DS tab.
- In the LDAP Port field, type in the new LDAP port number for your Directory Server instance.
- Change the SELinux labels for the Directory Server ports so that the new port number is used in the Directory Server policies. For example:
# semanage port -a -t ldap_port_t -p tcp 1389
Warning
If the SELinux label is not reset, then the Directory Server will not be able to be restarted. - In the Tasks tab of the Directory Server Console, click Restart Directory Server. A dialog to confirm that you want to restart the server. Click .
- Open the Configuration DS tab of the Administration Server Console and select .A dialog will appear, reading The Directory Server setting has been modified. You must shutdown and restart your Administration Server and all the servers in the Server Group for the changes to take effect. Click .
- In the Tasks tab of the Administration Server Console, click Restart Admin Server. A dialog opens reading that the Administration Server has been successfully restarted. Click .
Note
You must close and reopen the Console before you can do anything else in the Console. Refresh may not update the Console, and, if you try to do anything, you will get a warning that reads Unable to contact LDAP server.
1.7.2. Changing the LDAPS Port Numbers
- The Directory Server port number must also be updated in the Administration Server configuration.
- If there are other Directory Server instances that point to the configuration or user directory, update those servers to point to the new port number.
- Make sure that the CA certificate used to issue the Directory Server instance's certificate is in the Administration Server certificate database. Importing CA certificates for the Administration Server is the same as the Directory Server process described in Section 9.3.3, “Installing a CA Certificate”.
- The secure port can be configured using the Directory Server Console, much like the process in Section 1.7.1, “Changing Standard Port Numbers” (only setting the value in the Encrypted Port field). However, in some circumstances, such as if there are multiple Directory Server instances on the same machine, where changing port numbers may not be possible through the Directory Server Console. It may be be better to use
ldapmodify
to change the port number.For example:# ldapmodify -x -h server.example.com -p 1389 -D "cn=Directory Manager" -W dn: cn=config replace: nsslapd-securePort nsslapd-securePort: 1636
- Edit the corresponding port configuration for the Directory Server instance in th Administration Server configuration (
o=netscaperoot
).First, search for the current configuration:# ldapsearch -x -h config-ds.example.com -p 389 -D "cn=Directory Manager" -W -b "cn=slapd-ID,cn=389 Directory Server,cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot" -s base "(objectclass=*)" nsSecureServerPort dn: cn=slapd-ID,cn=389 Directory Server,cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot nsSecureServerPort: 636
Then, edit the configuration:# ldapmodify -x -h config-ds.example.com -p 389 -D "cn=Directory Manager" -W dn: cn=slapd-ID,cn=389 Directory Server,cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot replace: nsSecureServerPort nsSecureServerPort: 1636
- Start the Directory Server Console for the instance and confirm that the new LDAPS port number is listed in the Configuration tab.
- Optionally, select the Use SSL in Console check box.
- Change the SELinux labels for the Directory Server ports so that the new port number is used in the Directory Server policies. For example:
# semanage port -a -t ldap_port_t -p tcp 1636
Warning
If the SELinux label is not reset, then the Directory Server will not be able to be restarted. - Restart the Directory Server instance.
1.8. Managing Directory Server Instances
1.8.1. Creating a New Directory Server Instance
1.8.2. Removing a Directory Server Instance
1.8.2.1. Removing a Directory Server Instance Using the Command Line
# remove-ds.pl -i slapd-instance_name -a
remove-ds.pl
script removes any related files and directories if the -a
(all) option is specified. But the Directory Server instance is not unregistered from the Configuration Directory Server.
key
and cert
files are left in the instance configuration directory, and the configuration directory is renamed slapd-instance-name.removed
. Using the -a
option (as shown) removes the security databases, as well.
Note
remove-ds.pl
script fails. In this case, try the -f
option to force the removal process.
1.8.2.1.1. Removing a Directory Server Instance and Administration Server
-y
option is required for the script to perform the removal operation. Otherwise, the remove-ds-admin.pl
script performs a dry-run but does not remove any servers.
-a
option is not required, but it is recommended if a Directory Server or Administration Server instance may be re-configured on the system later. By default, all of the security databases are preserved by the removal script. The -a
option removes the security databases, as well.
Note
Note
remove-ds-admin.pl
script fails. In this case, try the -f
option to force the removal process.
1.8.3. Removing a Directory Server Instance Using the Console
- Open the Directory Server Console. For details, see Section 1.3.1, “Opening the Directory Server Console”.
- Right-click the server instance, and select Remove Server.
- Click Yes to confirm.
1.9. Using Directory Server Plug-ins
- The Plug-in Implemented Server Functionality Reference section in the Red Hat Directory Server Configuration, Command, and File Reference
1.9.1. Enabling Plug-ins Dynamically
nsslapd-pluginEnabled
attribute. For example:
# ldapmodify -x -D 'cn=Directory Manager' -W dn: cn=Plug-in_name,cn=plugins,cn=config changetype: modify replace: nsslapd-pluginEnabled nsslapd-pluginEnabled: on
nsslapd-dynamic-plugins
switch under the cn=config
entry. To enable the dynamic plug-in feature, set the nsslapd-dynamic-plugins
attribute to on
:
dn: cn=config nsslapd-dynamic-plugins: on
nsslapd-dynamic-plugins
attribute to off
:
dn: cn=config nsslapd-dynamic-plugins: off
nsslapd-dynamic-plugins
is set to off
.
1.9.2. Enabling Plug-ins
1.9.2.1. Enabling Plug-ins in the Command Line
ldapmodify
utility to edit the value of the nsslapd-pluginEnabled
attribute. For example:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=ACL Plugin,cn=plugins,cn=config changetype: modify replace: nsslapd-pluginEnabled nsslapd-pluginEnabled: on
1.9.2.2. Enabling Plug-ins in the Directory Server Console
- In the Directory Server Console, select the Configuration tab.
- Double-click the Plugins folder in the navigation tree.
- Select the plug-in from the Plugins list.
- To disable the plug-in, clear the Enabled check box. To enable the plug-in, check this check box.
- Click.
- Restart the Directory Server.
# systemctl restart dirsrv@instance
Note
NONE
.
1.9.3. Configuring Plug-ins
nsslapd-pluginarg*
attributes. Directory Server 10 added support for specific configuration attributes for certain plug-ins.
Important
nsslapd-pluginarg*
attributes are set in a plug-in's configuration, Directory Server only uses settings in plug-in-specific attributes.
Referential Integrity
plug-in but using the different configuration options:
Example 1.1. Plug-in Configuration using Configuration Attributes
referint-update-delay: 0 referint-logfile: /var/log/dirsrv/slapd-localhost/referint referint-logchanges: 0 referint-membership-attr: member referint-membership-attr: uniquemember referint-membership-attr: owner referint-membership-attr: seeAlso
Note
Example 1.2. Plug-in Configuration using Plug-in Argument Attributes (Deprecated)
nsslapd-pluginarg0: 0 nsslapd-pluginarg1: /var/log/dirsrv/slapd-localhost/referint nsslapd-pluginarg2: 0 nsslapd-pluginarg3: member nsslapd-pluginarg4: uniquemember nsslapd-pluginarg5: owner nsslapd-pluginarg6: seeAlso
1.9.3.1. Configuring Plug-ins using the Command Line
ldapmodify
utility to configure settings of a plug-in:
- Identify the distinguished name (DN) of the plug-in's configuration. For details, see the corresponding section in the Red Hat Directory Server Configuration, Command, and File Reference.
- Set the new value. For example, to set the update delay of the
Referential Integrity
plug-in to0
:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=referential integrity postoperation,cn=plugins,cn=config changetype: modify replace: referint-update-delay referint-update-delay: 0
- Restart the Directory Server instance:
# systemctl restart dirsrv@instance_name
1.9.3.2. Configuring Plug-ins using the Console
- Start the Directory Server Console and log in using the
cn=Directory Manager
user name.For details, see Section E.2.2, “Opening the Administration Server Console”. - On the Servers and Applications tab, navigate to → → → , and click .
- Navigate toand select the plug-in to configure.
- Click thebutton in the right panel.
Note
Red Hat recommends to configure the plug-in using the Property Editor, which uses the plug-in-specific attributes. - Set the plug-in-specific attributes.
- Click Property Editor.to close the
- Restart Directory Server. For details, see Section 1.5.2, “Restarting and Stopping the Administration Server Service Using the Console”.
1.9.4. Setting the Plug-in Precedence
nsslapd-pluginPrecedence
attribute on the plug-in's configuration entry. This attribute has a value of 1 (highest priority) to 99 (lowest priority). If the attribute is not set, it has a default value of 50.
Important
nsslapd-pluginPrecedence
attribute is set using the ldapmodify
command. For example:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=My Example Plugin,cn=plugins,cn=config changetype: modify replace: nsslapd-pluginPrecedence nsslapd-pluginPrecedence: 1
1.10. Server Configuration Attributes
cn=config
entry in the /etc/dirsrv/slapd-instance_name/dse.ldif
file. If you set up a new instance, Directory Server only stores configuration attributes that have been modified in this file. Attributes that are not listed, use their default value.
- Identify all configuration parameters set in this instance by displaying the
/etc/dirsrv/slapd-instance_name/dse.ldif
file. - Restore a default value by deleting the parameter.If you delete a configuration parameter, the parameter is no longer listed in the
/etc/dirsrv/slapd-instance_name/dse.ldif
file. However, the parameter and its default value is displayed when you search the parameter in thecn=config
entry using the LDAP protocol.Note that you cannot delete the parameters listed in Table 1.1, “Configuration Attributes That Cannot Be Deleted” to reset them to their default. If you try to delete them, the server will reject the request with aServer is unwilling to perform (53)
error. - Use the latest default values provided by a new Directory Server version.New versions often provide optimized settings and increased security. For example, if you do not set the
passwordStorageScheme
attribute, Directory Server automatically uses the strongest supported password storage scheme available. If a future update changes the default value to increase security, passwords will be automatically encrypted using the new storage scheme when a user set a passwords.Note
If you manually set a parameter to the same value as its default, the value is not updated. This happens, when a newer version uses a different default value.
Table 1.1. Configuration Attributes That Cannot Be Deleted
nsslapd-accesslog | nsslapd-auditlog | nsslapd-bakdir |
nsslapd-certdir | nsslapd-certmap-basedn | nsslapd-conntablesize |
nsslapd-errorlog | nsslapd-instancedir | nsslapd-ldifdir |
nsslapd-localhost | nsslapd-localuser | nsslapd-lockdir |
nsslapd-rootpw | nsslapd-referral | nsslapd-referralmode |
nsslapd-rundir | nsslapd-saslpath | nsslapd-schemadir |
nsslapd-tmpdir | nsslapd-workingdir |
Chapter 2. Configuring Directory Databases
2.1. Creating and Maintaining Suffixes

Figure 2.1. A Directory Tree with One Root Suffix
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
example.com
and one for redhat.com
. Here, two root suffixes are required, one corresponding to the dc=example,dc=com
naming context and one corresponding to the dc=redhat,dc=com
naming context, as shown in Figure 2.2, “A Directory Tree with Two Root Suffixes”.

Figure 2.2. A Directory Tree with Two Root Suffixes
dc=example,dc=com
, and one root suffix corresponds to the European branch of their directory tree, l=europe,dc=example,dc=com
. From a client application's perspective, the directory tree looks as illustrated in Figure 2.3, “A Directory Tree with a Root Suffix Off Limits to Search Operations”.

Figure 2.3. A Directory Tree with a Root Suffix Off Limits to Search Operations
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.
dc=example,dc=com
, and then create a sub suffix beneath it for the European directory entries, l=europe,dc=example,dc=com
. From a client application's perspective, the directory tree would appear as illustrated in Figure 2.4, “A Directory Tree with a Sub Suffix”.

Figure 2.4. A Directory Tree with a Sub Suffix
2.1.1.1. Creating a New Root Suffix Using the Console
- In the Directory Server Console, select the Configuration tab.
- Right-click Data in the left navigation pane, and select New Root Suffix from the pop-up menu.
- Enter a unique suffix in the New suffix field.The suffix must be named in line with
dc
naming conventions, such asdc=example,dc=com
. - Select the Create associated database automatically to create a database at the same time as the new root suffix, and enter a unique name for the new database in the Database name field, such as
example2
. The name can be a combination of alphanumeric characters, dashes (-
), and underscores (_
). No other characters are allowed.Deselect the check box to create a database for the new root suffix later. This option specifies a directory where the database will be created. The new root suffix will be disabled until a database is created.

2.1.1.2. Creating a New Sub Suffix Using the Console
- In the Directory Server Console, select the Configuration tab.
- Under the Data in the left navigation pane, select the suffix under which to add a new sub suffix. Right-click the suffix, and select New Sub Suffix from the pop-up menu.The Create new sub suffix dialog box is displayed.
- Enter a unique suffix name in the New suffix field. The suffix must be named in line with
dc
naming conventions, for exampleou=groups
.The root suffix is automatically added to the name. For example, if the sub suffixou=groups
is created under thedc=example,dc=com
suffix, the Console automatically names itou=groups,dc=example,dc=com
. - Select the Create associated database automatically check box to create a database at the same time as the new sub suffix, and enter a unique name for the new database in the Database name field, such as
example2
. The name can be a combination of alphanumeric characters, dashes (-
), and underscores (_
). No other characters are allowed.If the check box is not selected, than the database for the new sub suffix must be created later. The new sub suffix is disabled until a database is created.

2.1.1.3. Creating Root and Sub Suffixes using the Command Line
cn=mapping tree,cn=config
entry. Use the ldapmodify
utility to add new suffixes to the directory.
Creating a Root Suffix
dc=example,dc=com
root suffix:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn="dc=example,dc=com",cn=mapping tree,cn=config changetype: add cn: dc=example,dc=com objectclass: top objectclass: extensibleObject objectclass: nsMappingTree nsslapd-state: backend nsslapd-backend: UserData
Creating a Sub Suffix
nsslapd-parent-suffix
.
ou=groups
sub suffix under the dc=example,dc=com
root suffix:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn="ou=groups,dc=example,dc=com",cn=mapping tree,cn=config
changetype: add
cn: ou=groups,dc=example,dc=com
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: GroupData
nsslapd-parent-suffix: dc=example,dc=com
2.1.2. Maintaining Suffixes
2.1.2.1. Viewing the Default Naming Context
dc=example,dc=com
, a configuration suffix in cn=config
, and an administrative configuration suffix in o=netscaperoot
.
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
nsslapd-defaultnamingcontext
attribute from the nsslapd-allowed-to-delete-attrs
list.
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.
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
2.1.2.2.1. Disabling a Suffix Using the Command Line
nsslapd-state
attribute of the corresponding suffix entry to disabled
:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=suffix_DN,cn=mapping tree,cn=config changetype: modify replace: nsslapd-state nsslapd-state: disabled
2.1.2.2.2. Disabling a Suffix Using the Console
- In the Directory Server Console, select the Configuration tab.
- Under Data in the left navigation pane, click the suffix to disable.
- Click the Suffix Setting tab, and deselect the Enable this suffix check box.
2.1.2.3. Deleting a Suffix
Warning
2.1.2.3.1. Deleting a Suffix Using the Command Line
- Delete the suffix from the mapping tree:
# ldapdelete -D "cn=Directory Manager" -W -p 389 -h server.example.com -x "cn="suffix_DN",cn=mapping tree,cn=config"
- If the suffix uses a separate database, delete the database:
# ldapdelete -D "cn=Directory Manager" -W -p 389 -h server.example.com -x "cn=database_name,cn=ldbm database,cn=plugins,cn=config"
2.1.2.3.2. Deleting a Suffix Using the Console
- In the Directory Server Console, select the Configuration tab.
- Under Data in the left navigation pane, select the suffix to delete.
- Right-click the suffix, and select Delete from the menu.
- Select either Delete this suffix and all of its sub suffixes or Delete this suffix only.
2.2. Creating and Maintaining Databases
2.2.1. Creating 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 fordc=example,dc=com
, so that clients can conduct searches based atdc=example,dc=com
. However, DB2 only contains the data forou=groups
, and DB3 only contains the data forou=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 byou=people
could be distributed across two databases:DB1 contains people with names fromA-K
, and DB2 contains people with names fromL-Z
. DB3 contains theou=groups
data, and DB4 contains theou=contractors
data.A custom plug-in distributes data from a single suffix across multiple databases. Contact Red Hat Consulting for information on how to create distribution logic for Directory Server.
2.2.1.1. Creating a New Database for an Existing Suffix Using the Console
- In the Directory Server Console, select the Configuration tab.
- In the left pane, expand Data, then click the suffix to which to add the new database.
- Right-click the suffix, and select New Database from the pop-up menu.
- Enter a unique name for the database, such as
example2
. The database name can be a combination of alphanumeric characters, dashes (-
), and underscores (_
).The Create database in field is automatically filled with the default database directory (/var/lib/dirsrv/slapd-instance/db
) and the name of the new database. It is also possible to enter or browse for a different directory location.
2.2.1.2. Creating a New Database for a Single Suffix from the Command Line
ldapmodify
command-line utility to add a new database to the directory configuration file. The database configuration information is stored in the cn=ldbm database,cn=plugins,cn=config
entry. For example, add a new database to the server example1
:
- Run
ldapmodify
and create the entry for the new database.# ldapmodify
-a
-D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=UserData,cn=ldbm database,cn=plugins,cn=config changetype: add objectclass: extensibleObject objectclass: nsBackendInstance nsslapd-suffix: ou=people,dc=example,dc=comThe added entry corresponds to a database namedUserData
that contains the data for the root or sub suffixou=people,dc=example,dc=com
. - Create a root or a sub-suffix, as described in Section 2.1.1.3, “Creating Root and Sub Suffixes using the Command Line”. The database name, given in the DN attribute, must correspond with the value in the
nsslapd-backend
attribute of the suffix entry.
2.2.1.3. Adding Multiple Databases for a Single Suffix
Note
- 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.
2.2.1.3.1. Adding the Custom Distribution Function to a Suffix Using the Directory Server Console
- In the Directory Server Console, select the Configuration tab.
- Expand Data in the left navigation pane. Select the suffix to which to apply the distribution function.
- Select the Databases tab in the right window.
- The databases associated with the suffix are already listed in the Databases tab. Click to associate additional databases with the suffix.
- Enter the path to the distribution library.
- Enter the name of the distribution function in the Function name field.
2.2.1.3.2. Adding the Custom Distribution Function to a Suffix Using the Command Line
- Run
ldapmodify
.# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
- Add the following attributes to the suffix entry itself, supplying the information about the custom distribution logic:
dn: suffix changetype: modify add: nsslapd-backend nsslapd-backend: Database1 - add: nsslapd-backend nsslapd-backend: Database2 - add: nsslapd-backend nsslapd-backend: Database3 - add: nsslapd-distribution-plugin nsslapd-distribution-plugin: /full/name/of/a/shared/library - add: nsslapd-distribution-funct nsslapd-distribution-funct: distribution-function-name
Thensslapd-backend
attribute specifies all databases associated with this suffix. Thensslapd-distribution-plugin
attribute specifies the name of the library that the plug-in uses. Thensslapd-distribution-funct
attribute provides the name of the distribution function itself.
ldapmodify
command-line utility, see Section 3.1, “Managing Entries Using the Command Line”.
2.2.2. Maintaining Directory Databases
2.2.2.1. Placing a Database in Read-Only Mode
2.2.2.1.1. Making a Database Read-Only Using the Console
- In the Directory Server Console, select the Configuration tab.
- Expand Data in the left pane. Expand the suffix containing the database to put in read-only mode.
- Select the database to put into read-only mode.
- Select the Database Settings tab in the right pane.
- Select the database is read-only check box.
2.2.2.1.2. Making a Database Read-Only from the Command Line
- Run
ldapmodify
.# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
- Change the read-only attribute to
on
dn: cn=database_name,cn=ldbm database,cn=plugins,cn=config changetype: modify replace: nsslapd-readonly nsslapd-readonly: on
Note
userRoot
.
2.2.2.1.3. Placing the Entire Directory Server in Read-Only Mode
Warning
Note
- In the Directory Server Console, select the Configuration tab, and then select the top entry in the navigation tree in the left pane.
- Select the Settings tab in the right pane.
- Select the Make Entire Server Read-Only check box.
- Click, and then restart the server.
2.2.2.2. Deleting a Database
- In the Directory Server Console, select the Configuration tab.
- Expand the Data folder, and then select the suffix.
- Select the database to delete.
- Right-click the database and select Delete from the pop-up menu.
- Confirm that the database should be deleted in the Delete Database dialog box.
2.2.2.3. Changing the Transaction Log Directory
Note
- Stop the Directory Server instance:
# systemctl stop dirsrv@instance_name
- Create a new location for the transaction logs. For example:
# mkdir -p /srv/dirsrv/instance_name/db/
- Set permissions to enable only Directory Server to access the directory:
# chown dirsrv:dirsrv /srv/dirsrv/instance_name/db/ # chmod 770 /srv/dirsrv/instance_name/db/
- Remove all
__db.*
files from the previous transaction log directory. For example:# rm /var/lib/dirsrv/slapd-instance_name/db/__db.*
- Move all
log.*
files from the previous to the new transaction log directory. For example:# mv /var/lib/dirsrv/slapd-instance_name/db/log.* \ /srv/dirsrv/instance_name/db/
- If SELinux is running in
enforcing
mode, set thedirsrv_var_lib_t
context on the directory:# semanage fcontext -a -t dirsrv_var_lib_t /srv/dirsrv/instance_name/db/ # restorecon -Rv /srv/dirsrv/instance_name/db/
- Edit the
/etc/dirsrv/slapd-instance_name/dse.ldif
file, and update thensslapd-db-logdirectory
parameter under thecn=config,cn=ldbm database,cn=plugins,cn=config
entry. For example:dn: cn=config,cn=ldbm database,cn=plugins,cn=config ... nsslapd-db-logdirectory: /srv/dirsrv/instance_name/db/
- Start the instance:
# systemctl start dirsrv@instance_name
2.3. Creating and Maintaining Database Links
2.3.1. Creating a New Database Link
- Suffix information. A suffix is created in the directory tree that is managed by the database link, not a regular database. This suffix corresponds to the suffix on the remote server that contains the data.
- Bind credentials. When the database link binds to a remote server, it impersonates a user, and this specifies the DN and the credentials for each database link to use to bind with remote servers.
- LDAP URL. This supplies the LDAP URL of the remote server to which the database link connects. The URL consists of the protocol (ldap or ldaps), the host name or IP address (IPv4 or IPv6) for the server, and the port.
- List of failover servers. This supplies a list of alternative servers for the database link to contact in the event of a failure. This configuration item is optional.
Note
2.3.1.1. Creating a New Database Link Using the Console
- In the Directory Server Console, select the Configuration tab.
- Create a new suffix as described in Section 2.1.1, “Creating Suffixes”.Deselect the Create associated database automatically check box. It is simpler to configure a database link on a suffix without a database associated with it because having both a database and database link requires custom distribution functions to distribute directory data.
- In the left pane, right-click the new suffix, and select New Database Link from the pop-up menu.
- Fill in the database link name. The name can be a combination of alphanumeric characters, dashes (
-
), and underscores (_
). No other characters, like spaces, are allowed. - Set the radio button for the appropriate method for authentication.There are four authentication methods:
- Simple means that the server connects over the standard port with no encryption. The only required information is the bind DN and password for the user as whom the server connects to the remote server.
- Server TLS/SSL Certificate uses the local server's TLS certificate to authenticate to the remote server. A certificate must be installed on the local server for certificate-based authentication, and the remote server must have certificate mapping configured so that it can map the subject DN in the local server's certificate to the corresponding user entry.Configuring TLS and certificate mapping is described in Section 9.4, “Enabling TLS”.
Note
When the database link and remote server are configured to communicate using TLS, this does not mean that the client application making the operation request must also communicate using TLS. The client can bind using a normal port. - SASL/DIGEST-MD5 requires only the bind DN and password to authenticate.
- SASL/GSSAPI requires the local server to have a Kerberos keytab (as in Section 9.10.2.2, “About the KDC Server and Keytabs”), and the remote server to have a SASL mapping to map the local server's principal to the real user entry (as in Section 9.9.3.1, “Configuring SASL Identity Mapping from the Console”).
- In the Remote Server Information section, select the connection type for the local server to use to connect to the remote server. There are three options:
- Use LDAP. This sets a standard, unencrypted connection.
- Use TLS/SSL. This uses a secure connection over the server's secure LDAPS port, such as
636
. This setting is required to use TLS/TLS.When using TLS, make sure that the remote server's port number is set to its secure port. - Use Start TLS. This uses Start TLS to establish a secure connection over the server's standard port.
Note
If secure binds are required for simple password authentication (Section 19.11.1, “Requiring Secure Binds”), then any chaining operations will fail unless they occur over a secure connection. Using a secure connection (TLS and Start TLS connections or SASL authentication) is recommended, anyway. - In the Remote Server Information section, fill in the name (host name, IPv4 address, or IPv6 address) and port number for the remote server.For any failover servers, fill in the host name and port number, and click thebutton. A failover server is a backup server, so that if the primary remote server fails, the database link contacts the first server in the failover servers list and cycles through the list until a server is accessed.

Note
2.3.1.2. Creating a Database Link from the Command Line
- Use the
ldapmodify
command-line utility to create a new database link. The new instance must be located in thecn=chaining database,cn=plugins,cn=config
entry.# ldapmodify
-a
-D "cn=Directory Manager" -W -p 389 -h server.example.com -x - Specify the configuration information for the database link:
dn: cn=examplelink,cn=chaining database,cn=plugins,cn=config changetype: add objectclass: top objectclass: extensibleObject objectclass: nsBackendInstance nsslapd-suffix: ou=people,dc=example,dc=com suffix being chained nsfarmserverurl: ldap://people.example.com:389/ LDAP URL to remote server nsMultiplexorBindDN: cn=proxy admin,cn=config bind DN nsMultiplexorCredentials: secret bind password cn: examplelink
Note
cn=default instance config,cn=chaining database,cn=plugins,cn=config
entry. These configuration attributes apply to all database links at creation time. Changes to the default configuration only affect new database links. The default configuration attributes on existing database links cannot be changed.
cn=
database_link, cn=chaining database,cn=plugins,cn=config
. For more information about configuration attributes, see the Red Hat Directory Server Configuration, Command, and File Reference.
2.3.1.2.1. Providing Suffix Information
nsslapd-suffix
attribute to define the suffix managed by the database link. For example, for the database link to point to the people information for a remote site of the company, enter the following suffix information:
nsslapd-suffix: l=Zanzibar,ou=people,dc=example,dc=com
cn=
database_link, cn=chaining database,cn=plugins,cn=config
entry.
Note
nsslapd-nsslapd-suffix
attribute are applied only after the server containing the database link is restarted.
2.3.1.2.2. Providing Bind Credentials
anonymous
.
- On the remote server:
- Create an administrative user for the database link.For information on adding entries, see Chapter 3, Managing Directory Entries.
- Provide proxy access rights for the administrative user created in step 1 on the subtree chained to by the database link.For more information on configuring ACIs, see Chapter 18, Managing Access Control
- On the server containing the database link, use
ldapmodify
to provide a user DN for the database link in thensMultiplexorBindDN
attribute of thecn=
database_link,cn=chaining database,cn=plugins,cn=config
entry.Warning
ThensMultiplexorBindDN
cannot be that of the Directory Manager.Useldapmodify
to provide a user password for the database link in thensMultiplexorCredentials
attribute of thecn=
database_link,cn=chaining database,cn=plugins,cn=config
entry.

nsMultiplexorBindDN
attribute and a user password as defined in the nsMultiplexorCredentials
attribute. In this example, Server A uses the following bind credentials:
nsMultiplexorBindDN: cn=proxy admin,cn=config nsMultiplexorCredentials: secret

nsMultiplexorBindDN
, and set the proxy authentication rights for this user. To set the proxy authorization correctly, set the proxy ACI as any other ACI.
Warning
Note
creatorsName
and modifiersName
do not reflect the real creator or modifier of the entries. These attributes contain the name of the administrative user granted proxied authorization rights on the remote data server.
2.3.1.2.3. Providing an LDAP URL
ldap://
server:port, where the server can be a host name, IPv4 address, or IPv6 address.
nsFarmServerURL
attribute is set in the cn=
database_link, cn=chaining database,cn=plugins,cn=config
entry of the configuration file.
nsFarmServerURL: ldap://example.com:389/
Note
nsFarmServerURL: ldaps://africa.example.com:636/
Note
2.3.1.2.4. Providing a List of Failover Servers
nsFarmServerURL
attribute, separated by spaces.
nsFarmServerURL: ldap://example.com us.example.com:389 africa.example.com:1000/
example.com
on the standard port to service an operation. If it does not respond, the database link then contacts the server us.example.com
on port 389
. If this server fails, it then contacts africa.example.com
on port 1000
.
2.3.1.2.5. Using Different Bind Mechanisms
- Over the standard LDAP port
- Over a dedicated LDAPS port
- Using Start TLS, which is a secure connection over a standard port
Note
nsUseStartTLS
attribute. When this is on
, then the server initiates a Start TLS connect over the standard port. If this is off
, then the server either uses the LDAP port or the LDAPS port, depending on what is configured for the remote server in the nsFarmServerURL
attribute.
nsUseStartTLS: on
nsUseStartTLS: off
- empty. If there is no bind mechanism set, then the server performs simple authentication and requires the
nsMultiplexorBindDN
andnsMultiplexorCredentials
attributes to give the bind information. - EXTERNAL. This uses an TLS certificate to authenticate the farm server to the remote server. Either the farm server URL must be set to the secure URL (
ldaps
) or thensUseStartTLS
attribute must be set toon
.Additionally, the remote server must be configured to map the farm server's certificate to its bind identity, as described in the certmap.conf section in the Red Hat Directory Server Configuration, Command, and File Reference. - DIGEST-MD5. This uses SASL authentication with DIGEST-MD5 encryption. As with simple authentication, this requires the
nsMultiplexorBindDN
andnsMultiplexorCredentials
attributes to give the bind information. - GSSAPI. This uses Kerberos-based authentication over SASL.The farm server must be configured with a Kerberos keytab, and the remote server must have a defined SASL mapping for the farm server's bind identity. Setting up Kerberos keytabs and SASL mappings is described in Section 9.9, “Setting up SASL Identity Mapping”.
Note
nsBindMechanism: EXTERNAL
Note
ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=config,cn=chaining database,cn=plugins,cn=config changetype: modify add: nsActiveChainingComponents nsActiveChainingComponents: cn=password policy,cn=components,cn=config - add: nsActiveChainingComponents nsActiveChainingComponents: cn=sasl,cn=components,cn=config ^D
2.3.1.2.6. Summary of Database Link Configuration Attributes
cn=
database_link, cn=chaining database,cn=plugins,cn=config
entry.
Table 2.1. Database Link Configuration Attributes
Attributes | Value |
---|---|
nsTransmittedControls [†] | Gives the OID of LDAP controls forwarded by the database link to the remote data server. |
nsslapd-suffix | The suffix managed by the database link. Any changes to this attribute after the entry has been created take effect only after the server containing the database link is restarted. |
nsslapd-timelimit | Default search time limit for the database link, given in seconds. The default value is 3600 seconds. |
nsslapd-sizelimit | Default size limit for the database link, given in number of entries. The default value is 2000 entries. |
nsFarmServerURL | Gives the LDAP URL of the remote server (or farm server) that contains the data. This attribute can contain optional servers for failover, separated by spaces. If using cascading chaining, this URL can point to another database link. |
nsUseStartTLS | Sets whether to use Start TLS to establish a secure connection over a standard port. The default is off , which is used for both simple (standard) connections and TLS connections. |
nsBindMechanism | Sets the authentication method to use to authenticate (bind) to the remote server. If you set an empty value, simple bind is used (LDAP_SASL_SIMPLE). |
nsMultiplexorBindDN | DN of the administrative entry used to communicate with the remote server. The term multiplexor in the name of the attribute means the server which contains the database link and communicates with the remote server. This bind DN cannot be the Directory Manager. If this attribute is not specified, the database link binds as anonymous . |
nsMultiplexorCredentials | Password for the administrative user, given in plain text. If no password is provided, it means that users can bind as anonymous . The password is encrypted in the configuration file. |
nsCheckLocalACI | Reserved for advanced use only. Controls whether ACIs are evaluated on the database link as well as the remote data server. Takes the values on or off . Changes to this attribute occur only after the server has been restarted. The default value is off . |
nsProxiedAuthorization | Reserved for advanced use only. Disables proxied authorization. A value of off means proxied authorization is disabled. The default value is on . |
nsActiveChainingComponents[†] | Lists the components using chaining. A component is any functional unit in the server. The value of this attribute in the database link instance overrides the value in the global configuration attribute. To disable chaining on a particular database instance, use the value none . The default policy is not to allow chaining. For more information, see Section 2.3.2.1, “Chaining Component Operations”. |
nsReferralOnScopedSearch | Controls whether referrals are returned by scoped searches. This attribute is for optimizing the directory because returning referrals in response to scoped searches is more efficient. Takes the values on or off . The default value is off . |
nsHopLimit | Maximum number of times a request can be forwarded from one database link to another. The default value is 10 . |
[†]
Can be both a global and instance attribute. This global configuration attribute is located in the cn=config,cn=chaining database,cn=plugins,cn=config entry. The global attributes are dynamic, meaning any changes made to them automatically take effect on all instances of the database link within the directory.
|
2.3.1.2.7. Database Link Configuration Example
us.example.com
domain contains the subtree l=Walla Walla,ou=people,dc=example,dc=com
on a database and that operation requests for the l=Zanzibar,ou=people,dc=example,dc=com
subtree should be chained to a different server in the africa.example.com
domain.

- Run
ldapmodify
to add a database link to Server A:# ldapmodify
-a
-D "cn=Directory Manager" -W -p 389 -h server.example.com -x - Specify the configuration information for the database link:
dn: cn=DBLink1,cn=chaining database,cn=plugins,cn=config changetype: add objectclass: top objectclass: extensibleObject objectclass: nsBackendInstance nsslapd-suffix: c=africa,ou=people,dc=example,dc=com nsfarmserverurl: ldap://africa.example.com:389/ nsMultiplexorBindDN: cn=proxy admin,cn=config nsMultiplexorCredentials: secret cn: DBLink1 dn: cn="c=africa,ou=people,dc=example,dc=com",cn=mapping tree,cn=config objectclass: top objectclass: extensibleObject objectclass: nsMappingTree nsslapd-state: backend nsslapd-backend: DBLink1 nsslapd-parent-suffix: ou=people,dc=example,dc=com cn: c=africa,ou=people,dc=example,dc=com
In the first entry, thensslapd-suffix
attribute contains the suffix on Server B to which to chain from Server A. ThensFarmServerURL
attribute contains the LDAP URL of Server B.The second entry creates a new suffix, allowing the server to route requests made to the new database link. Thecn
attribute contains the same suffix specified in thensslapd-suffix
attribute of the database link. Thensslapd-backend
attribute contains the name of the database link. Thensslapd-parent-suffix
attribute specifies the parent of this new suffix,ou=people,dc=example,dc=com
. - Create an administrative user on Server B, as follows:
dn: cn=proxy admin,cn=config objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: proxy admin sn: proxy admin userPassword: secret description: Entry for use by database links
Warning
Do not use the Directory Manager user as the proxy administrative user on the remote server. This creates a security hole. - Add the following proxy authorization ACI to the
l=Zanzibar,ou=people,dc=example,dc=com
entry on Server B:aci: (targetattr = "*")(version 3.0; acl "Proxied authorization for database links"; allow (proxy) userdn = "ldap:///cn=proxy admin,cn=config";)
This ACI gives the proxy admin user read-only access to the data contained on the remote server within thel=Zanzibar,ou=people,dc=example,dc=com
subtree only.Note
When a user binds to a database link, the user's identity is sent to the remote server. Access controls are always evaluated on the remote server. For the user to modify or write data successfully to the remote server, set up the correct access controls on the remote server. For more information about how access controls are evaluated in the context of chained operations, see Section 2.3.6, “Database Links and Access Control Evaluation”.
2.3.2. Configuring the Chaining Policy
2.3.2.1. Chaining Component Operations
- ACI plug-in
- This plug-in implements access control. Operations used to retrieve and update ACI attributes are not chained because it is not safe to mix local and remote ACI attributes. However, requests used to retrieve user entries may be chained by setting the chaining components attribute:
nsActiveChainingComponents: cn=ACI Plugin,cn=plugins,cn=config
Permissions: Read, search, and compare - Resource limit component
- This component sets server limits depending on the user bind DN. Resource limits can be applied on remote users if the resource limitation component is allowed to chain. To chain resource limit component operations, add the chaining component attribute:
nsActiveChainingComponents: cn=resource limits,cn=components,cn=config
Permissions: Read, search, and compare - Certificate-based authentication checking component
- This component is used when the external bind method is used. It retrieves the user certificate from the database on the remote server. Allowing this component to chain means certificate-based authentication can work with a database link. To chain this component's operations, add the chaining component attribute:
nsActiveChainingComponents: cn=certificate-based authentication,cn=components,cn=config
Permissions: Read, search, and compare - Password policy component
- This component is used to allow SASL binds to the remote server. Some forms of SASL authentication require authenticating with a user name and password. Enabling the password policy allows the server to verify and implement the specific authentication method requested and to apply the appropriate password policies. To chain this component's operations, add the chaining component attribute:
nsActiveChainingComponents: cn=password policy,cn=components,cn=config
Permissions: Read, search, and compare - SASL component
- This component is used to allow SASL binds to the remote server. To chain this component's operations, add the chaining component attribute:
nsActiveChainingComponents: cn=password policy,cn=components,cn=config
Permissions: Read, search, and compare - Referential Integrity plug-in
- This plug-in ensures that updates made to attributes containing DNs are propagated to all entries that contain pointers to the attribute. For example, when an entry that is a member of a group is deleted, the entry is automatically removed from the group. Using this plug-in with chaining helps simplify the management of static groups when the group members are remote to the static group definition. To chain this component's operations, add the chaining component attribute:
nsActiveChainingComponents: cn=referential integrity postoperation,cn=plugins,cn=config
Permissions: Read, search, and compare - Attribute Uniqueness plug-in
- This plug-in checks that all the values for a specified attribute are unique (no duplicates). If this plug-in is chained, it confirms that attribute values are unique even on attributes changed through a database link. To chain this component's operations, add the chaining component attribute:
nsActiveChainingComponents: cn=attribute uniqueness,cn=plugins,cn=config
Permissions: Read, search, and compare - Roles component
- This component chains the roles and roles assignments for the entries in a database. Chaining this component maintains the roles even on chained databases. To chain this component's operations, add the chaining component attribute:
nsActiveChainingComponents: cn=roles,cn=components,cn=config
Permissions: Read, search, and compare
Note
- Roles plug-in
- Password policy component
- Replication plug-ins
- Referential Integrity plug-in
2.3.2.1.1. Chaining Component Operations Using the Console
- In the Directory Server Console, select the Configuration tab.
- Expand Data in the left pane, and click Database Link Settings.
- Select the Settings tab in the right window.
- Click the Components allowed to chain section.button in the
- Select the component to chain from the list, and click.
- Restart the server in order for the change to take effect.
aci: (targetattr "*")(target="ldap:///ou=customers,l=us,dc=example,dc=com") (version 3.0; acl "RefInt Access for chaining"; allow (read,write,search,compare) userdn = "ldap:///cn=referential integrity postoperation,cn=plugins,cn=config";)
2.3.2.1.2. Chaining Component Operations from the Command Line
- Specify components to include in chaining using the
nsActiveChainingComponents
attribute in thecn=config,cn=chaining database,cn=plugins,cn=config
entry of the configuration file.For example, to allow the referential integrity component to chain operations, add the following to the database link configuration file:nsActiveChainingComponents: cn=referential integrity postoperation,cn=components,cn=config
See Section 2.3.2.1, “Chaining Component Operations” for a list of the components which can be chained. - Restart the server for the change to take effect.
# systemctl restart dirsrv@instance_name
- Create an ACI in the suffix on the remote server to which the operation will be chained. For example, this creates an ACI for the Referential Integrity plug-in:
aci: (targetattr "*")(target="ldap:///ou=customers,l=us,dc=example,dc=com") (version 3.0; acl "RefInt Access for chaining"; allow (read,write,search,compare) userdn = "ldap:///cn=referential integrity postoperation,cn=plugins,cn=config";)
2.3.2.2. Chaining LDAP Controls
- Virtual List View (VLV). This control provides lists of parts of entries rather than returning all entry information.
- Server-side sorting. This control sorts entries according to their attribute values, usually using a specific matching rule.
- Dereferencing. This control tracks back over references in entry attributes in a search and pulls specified attribute information from the referenced entry and returns it with the rest of the search results.
- Managed DSA. This controls returns smart referrals as entries, rather than following the referral, so the smart referral itself can be changed or deleted.
- Loop detection. This control keeps track of the number of times the server chains with another server. When the count reaches the configured number, a loop is detected, and the client application is notified. For more information about using this control, see Section 2.4.4, “Detecting Loops”.
Note
2.3.2.2.1. Chaining LDAP Controls Using the Console
- In the Directory Server Console, select the Configuration tab.
- Expand the Data folder in the left pane, and click Database Link Settings.
- Select the Settings tab in the right window.
- Click the LDAP Controls forwarded by the database link section to add an LDAP control to the list.button in the
- Select the OID of a control to add to the list, and click.
2.3.2.2.2. Chaining LDAP Controls from the Command Line
nsTransmittedControls
attribute of the cn=config,cn=chaining database,cn=plugins,cn=config
entry. For example, to forward the virtual list view control, add the following to the database link entry in the configuration file:
nsTransmittedControls: 2.16.840.1.113730.3.4.9
nsTransmittedControls
attribute.
Table 2.2. LDAP Controls and Their OIDs
Control Name | OID |
---|---|
Virtual list view (VLV) | 2.16.840.1.113730.3.4.9 |
Server-side sorting | 1.2.840.113556.1.4.473 |
Managed DSA | 2.16.840.1.113730.3.4.2 |
Loop detection | 1.3.6.1.4.1.1466.29539.12 |
Dereferencing searches | 1.3.6.1.4.1.4203.666.5.16 |
2.3.3. Maintaining Database Links
- In the Directory Server Console, select the Configuration tab.
- In the left pane, expand the Data folder, and select the database link under the suffix.
- In the right navigation pane, click the Authentication tab.
- Change the connection information.
- The LDAP URL for the remote server.[]
- The bind DN and password used by the database link to bind to the remote server.
2.3.4. Configuring Database Link Defaults
- Select the Configuration tab.
- Expand the Data folder in the left pane, and click Database Link Settings. Open the Default Creation Parameters tab.
- Fill in the new configuration parameters.
Note
2.3.5. Deleting Database Links
- In the Directory Server Console, select the Configuration tab.
- Under Data in the left navigation pane, open the suffix and select the database link to delete.
- Right-click the database link, and select Delete from the menu.
2.3.6. Database Links and Access Control Evaluation
- Not all types of access control can be used.For example, role-based or filter-based ACIs need access to the user entry. Because the data are accessed through database links, only the data in the proxy control can be verified. Consider designing the directory in a way that ensures the user entry is located in the same database as the user's data.
- All access controls based on the IP address or DNS domain of the client may not work since the original domain of the client is lost during chaining. The remote server views the client application as being at the same IP address and in the same DNS domain as the database link.
Note
Directory Server supports both IPv4 and IPv6 IP addresses.
- ACIs must be located with any groups they use. If the groups are dynamic, all users in the group must be located with the ACI and the group. If the group is static, it links to remote users.
- ACIs must be located with any role definitions they use and with any users intended to have those roles.
- ACIs that link to values of a user's entry (for example,
userattr
subject rules) will work if the user is remote.
- During access control evaluation, contents of user entries are not necessarily available (for example, if the access control is evaluated on the server containing the database link and the entry is located on a remote server).For performance reasons, clients cannot do remote inquiries and evaluate access controls.
- The database link does not necessarily have access to the entries being modified by the client application.When performing a modify operation, the database link does not have access to the full entry stored on the remote server. If performing a delete operation, the database link is only aware of the entry's DN. If an access control specifies a particular attribute, then a delete operation will fail when being conducted through a database link.
Note
nsCheckLocalACI
attribute in the cn=
database_link, cn=chaining database,cn=plugins,cn=config
entry. However, evaluating access controls on the server containing the database link is not recommended except with cascading chaining.
2.4. Configuring Cascading Chaining
2.4.1. Overview of Cascading Chaining


dc=example,dc=com
and
the ou=people
and ou=groups
sub suffixes are stored on Server A. The l=europe,dc=example,dc=com
and ou=groups
suffixes are stored in on Server B, and the ou=people
branch of the l=europe,dc=example,dc=com
suffix is stored on Server C.
ou=people,l=europe,dc=example,dc=com
entry would be routed by the directory as follows:

ou=people,l=europe,dc=example,dc=com
branch. Because at least two hops are required for the directory to service the client request, this is considered a cascading chain.
2.4.2. Configuring Cascading Chaining Using the Console
- Select the Configuration tab. Expand the Data folder in the left pane, and select the suffix, then the database link.
- Click the Limits and Controls tab in the right navigation pane.
- Select the Check local ACI check box to enable the evaluation of local ACIs on the intermediate database links involved in the cascading chain. Selecting this check box may require adding the appropriate local ACIs to the database link.
- Enter the maximum number of times a database link can point to another database link in the Maximum hops field.By default, the maximum is ten hops. After ten hops, a loop is detected by the server, and an error is returned to the client application.
2.4.3. Configuring Cascading Chaining from the Command Line
- Point one database link to the URL of the server containing the intermediate database link.To create a cascading chain, the
nsFarmServerURL
attribute of one database link must contain the URL of the server containing another database link. Suppose the database link on the server calledexample1.com
points to a database link on the server calledafrica.example.com
. For example, thecn=
database_link,cn=chaining database,cn=plugins,cn=config
entry of the database link on Server 1 would contain the following:nsFarmServerURL: ldap://africa.example.com:389/
- Configure the intermediate database link or links (in the example, Server 2) to transmit the Proxy Authorization Control.By default, a database link does not transmit the Proxy Authorization Control. However, when one database link contacts another, this control is used to transmit information needed by the final destination server. The intermediate database link needs to transmit this control. To configure the database link to transmit the proxy authorization control, add the following to the
cn=config,cn=chaining database,cn=plugins,cn=config
entry of the intermediate database link:nsTransmittedControls: 2.16.840.1.113730.3.4.12
The OID value represents the Proxy Authorization Control. For more information about chaining LDAP controls, see Section 2.3.2.2, “Chaining LDAP Controls”. - Create a proxy administrative user ACI on all intermediate database links.The ACI must exist on the server that contains the intermediate database link that checks the rights of the first database link before translating the request to another server. For example, if Server 2 does not check the credentials of Server 1, then anyone could bind as
anonymous
and pass a proxy authorization control allowing them more administrative privileges than appropriate. The proxy ACI prevents this security breach.- Create a database, if one does not already exist, on the server containing the intermediate database link. This database will contain the admin user entry and the ACI. For information about creating a database, see Section 2.2.1, “Creating Databases”.
- Create an entry that corresponds to the administrative user in the database.
- Create an ACI for the administrative user that targets the appropriate suffix. This ensures the administrator has access only to the suffix of the database link. For example:
aci: (targetattr = "*")(version 3.0; acl "Proxied authorization for database links"; allow (proxy) userdn = "ldap:///cn=proxy admin,cn=config";)
This ACI is like the ACI created on the remote server when configuring simple chaining.
Warning
Carefully examine access controls when enabling chaining to avoid giving access to restricted areas of the directory. For example, if a default proxy ACI is created on a branch, the users that connect through the database link will be able to see all entries below the branch. There may be cases when not all of the subtrees should be viewed by a user. To avoid a security hole, create an additional ACI to restrict access to the subtree. - Enable local ACI evaluation on all intermediate database links.To confirm that the proxy administrative ACI is used, enable evaluation of local ACIs on all intermediate database links involved in chaining. Add the following attribute to the
cn=
database_link,cn=chaining database,cn=plugins,cn=config
entry of each intermediate database link:nsCheckLocalACI: on
Setting this attribute toon
in thecn=default instance config,cn=chaining database,cn=plugins,cn=config
entry means that all new database link instances will have thensCheckLocalACI
attribute set toon
in theircn=
database_link,cn=chaining database,cn=plugins,cn=config
entry. - Create client ACIs on all intermediate database links and the final destination database.Because local ACI evaluation is enabled, the appropriate client application ACIs must be created on all intermediate database links, as well as the final destination database. To do this on the intermediate database links, first create a database that contains a suffix that represents a root suffix of the final destination suffix.For example, if a client request made to the
c=africa,ou=people,dc=example,dc=com
suffix is chained to a remote server, all intermediate database links need to contain a database associated with thedc=example,dc=com
suffix.Add any client ACIs to this superior suffix entry. For example:aci: (targetattr = "*")(version 3.0; acl "Client authentication for database link users"; allow (all) userdn = "ldap:///uid=* ,cn=config";)
This ACI allows client applications that have auid
in thecn=config
entry of Server 1 to perform any type of operation on the data below theou=people,dc=example,dc=com
suffix on server three.
2.4.4. Detecting Loops
0
, it determines that a loop has been detected and notifies the client application.
nsHopLimit
attribute. If not specified, the default value is 10
.
nsTransmittedControl
attribute in the cn=config,cn=chaining database,cn=plugins,cn=config
entry:
nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12
2.4.5. Summary of Cascading Chaining Configuration Attributes
nsFarmServerURL
- URL of the server containing the next database link in the cascading chain.
nsTransmittedControls
- Enter the following OIDs to the database links involved in the cascading chain:
nsTransmittedControls: 2.16.840.1.113730.3.4.12 nsTransmittedControls: 1.3.6.1.4.1.1466.29539.12
aci
- This attribute must contain the following ACI:
aci: (targetattr = "*")(version 3.0; acl "Proxied authorization for database links"; allow (proxy) userdn = "ldap:///cn=proxy admin,cn=config";)
nsCheckLocalACI
- To enable evaluation of local ACIs on all database links involved in chaining, turn local ACI evaluation on, as follows:
nsCheckLocalACI: on
2.4.6. Cascading Chaining Configuration Example

2.4.6.1. Configuring Server One
- Run
ldapmodify
and specify the configuration information for the database link, DBLink1, on Server 1:# ldapmodify
-a
-D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=DBLink1,cn=chaining database,cn=plugins,cn=config changetype: add objectclass: top objectclass: extensibleObject objectclass: nsBackendInstance nsslapd-suffix: c=africa,ou=people,dc=example,dc=com nsfarmserverurl: ldap://africa.example.com:389/ nsMultiplexorBindDN: cn=server1 proxy admin,cn=config nsMultiplexorCredentials: secret cn: DBLink1 nsCheckLocalACI:off dn: cn="c=africa,ou=people,dc=example,dc=com",cn=mapping tree,cn=config changetype: add objectclass: nsMappingTree nsslapd-state: backend nsslapd-backend: DBLink1 nsslapd-parent-suffix: ou=people,dc=example,dc=com cn: c=africa,ou=people,dc=example,dc=comThe first section creates the entry associated withDBLink1
. The second section creates a new suffix, allowing the server to direct requests made to the database link to the correct server. ThensCheckLocalACI
attribute does not need to be configured to check local ACIs, as this is only required on the database link,DBLink2
, on Server 2. - To implement loop detection, to specify the OID of the loop detection control in the
nsTransmittedControl
attribute stored incn=config,cn=chaining database,cn=plugins,cn=config
entry on Server 1.dn: cn=config,cn=chaining database,cn=plugins,cn=config changetype: modify add: nsTransmittedControl nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12
As thensTransmittedControl
attribute is usually configured by default with the loop detection control OID1.3.6.1.4.1.1466.29539.12
value, it is wise to check beforehand whether it already exists. If it does exist, this step is not necessary.
2.4.6.2. Configuring Server Two
- Create a proxy administrative user on Server 2. This administrative user will be used to allow Server 1 to bind and authenticate to Server 2. It is useful to choose a proxy administrative user name which is specific to Server 1, as it is the proxy administrative user which will allow server one to bind to Server 2. Create the proxy administrative user, as follows:
dn: cn=server1 proxy admin,cn=config objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: server1 proxy admin sn: server1 proxy admin userPassword: secret description: Entry for use by database links
Warning
Do not use the Directory Manager or Administrator ID user as the proxy administrative user on the remote server. This creates a security hole. - Configure the database link,
DBLink2
, on Server 2:dn: cn=DBLink2,cn=chaining database,cn=plugins,cn=config objectclass: top objectclass: extensibleObject objectclass: nsBackendInstance nsslapd-suffix: l=Zanzibar,c=africa,ou=people,dc=example,dc=com nsfarmserverurl: ldap://zanz.africa.example.com:389/ nsMultiplexorBindDN: cn=server2 proxy admin,cn=config nsMultiplexorCredentials: secret cn: DBLink2 nsCheckLocalACI:on dn: cn="l=Zanzibar,c=africa,ou=people,dc=example,dc=com",cn=mapping tree,cn=config objectclass: top objectclass: extensibleObject objectclass: nsMappingTree nsslapd-state: backend nsslapd-backend: DBLink2 nsslapd-parent-suffix: c=africa,ou=people,dc=example,dc=com cn: l=Zanzibar,c=africa,ou=people,dc=example,dc=com
Since database link DBLink2 is the intermediate database link in the cascading chaining configuration, set thensCheckLocalACI
attribute toon
to allow the server to check whether it should allow the client and proxy administrative user access to the database link. - The database link on Server 2 must be configured to transmit the proxy authorization control and the loop detection control. To implement the proxy authorization control and the loop detection control, specify both corresponding OIDs. Add the following information to the
cn=config,cn=chaining database,cn=plugins,cn=config
entry on Server 2:dn: cn=config,cn=chaining database,cn=plugins,cn=config changetype: modify add: nsTransmittedControl nsTransmittedControl: 2.16.840.1.113730.3.4.12 nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12
nsTransmittedControl: 2.16.840.1.113730.3.4.12
is the OID for the proxy authorization control.nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12
is the or the loop detection control.Check beforehand whether the loop detection control is already configured, and adapt the above command accordingly. - Configure the ACIs. On Server 2, ensure that a suffix exists above the
l=Zanzibar,c=africa,ou=people,dc=example,dc=com
suffix, so that the following actions are possible:- Add the database link suffix
- Add a local proxy authorization ACI to allow Server 1 to connect using the proxy authorization administrative user created on Server 2
- Add a local client ACI so the client operation succeeds on Server 2, and it can be forwarded to server three. This local ACI is needed because local ACI checking is turned on for the
DBLink2
database link.
Both ACIs will be placed on the database that contains thec=africa,ou=people,dc=example,dc=com
suffix.Note
To create these ACIs, the database corresponding to thec=africa,ou=people,dc=example,dc=com
suffix must already exist to hold the entry. This database needs to be associated with a suffix above the suffix specified in thensslapd-suffix
attribute of each database link. That is, the suffix on the final destination server should be a sub suffix of the suffix specified on the intermediate server.- Add the local proxy authorization ACI to the
c=africa,ou=people,dc=example,dc=com
entry:aci:(targetattr="*")(target="l=Zanzibar,c=africa,ou=people,dc=example,dc=com") (version 3.0; acl "Proxied authorization for database links"; allow (proxy) userdn = "ldap:///cn=server1 proxy admin,cn=config";)
- Then add the local client ACI that will allow the client operation to succeed on Server 2, given that ACI checking is turned on. This ACI is the same as the ACI created on the destination server to provide access to the
l=Zanzibar,c=africa,ou=people,dc=example,dc=com
branch. All users withinc=us,ou=people,dc=example,dc=com
may need to have update access to the entries inl=Zanzibar,c=africa,ou=people,dc=example,dc=com
on server three. Create the following ACI on Server 2 on thec=africa,ou=people,dc=example,dc=com
suffix to allow this:aci:(targetattr="*")(target="l=Zanzibar,c=africa,ou=people,dc=example,dc=com") (version 3.0; acl "Client authorization for database links"; allow (all) userdn = "ldap:///uid=*,c=us,ou=people,dc=example,dc=com";)
This ACI allows clients that have a UID inc=us,ou=people,dc=example,dc=com
on Server 1 to perform any type of operation on thel=Zanzibar,c=africa,ou=people,dc=example,dc=com
suffix tree on server three. If there are users on Server 2 under a different suffix that will require additional rights on server three, it may be necessary to add additional client ACIs on Server 2.
2.4.6.3. Configuring Server Three
- Create an administrative user on server three for Server 2 to use for proxy authorization:
dn: cn=server2 proxy admin,cn=config objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: server2 proxy admin sn: server2 proxy admin userPassword: secret description: Entry for use by database links
- Then add the same local proxy authorization ACI to server three as on Server 2. Add the following proxy authorization ACI to the
l=Zanzibar,ou=people,dc=example,dc=com
entry:aci: (targetattr = "*")(version 3.0; acl "Proxied authorization for database links"; allow (proxy) userdn = "ldap:///cn=server2 proxy admin,cn=config";)
This ACI gives the Server 2 proxy admin read-only access to the data contained on the remote server, server three, within thel=Zanzibar,ou=people,dc=example,dc=com
subtree only. - Create a local client ACI on the
l=Zanzibar,ou=people,dc=example,dc=com
subtree that corresponds to the original client application. Use the same ACI as the one created for the client on Server 2:aci: (targetattr ="*")(target="l=Zanzibar,c=africa,ou=people,dc=example,dc=com") (version 3.0; acl "Client authentication for database link users"; allow (all) userdn = "ldap:///uid=*,c=us,ou=people,dc=example,dc=com";)
l=Zanzibar,c=africa,ou=people,dc=example,dc=com
branch on server three. Depending on your security needs, it may be necessary to provide more detailed access control.
2.5. Using Referrals
2.5.1. Starting the Server in Referral Mode
refer
command.
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 7.- port is the optional port number of the Directory Server to start in referral mode.
- referral_url is the referral returned to clients. The format of an LDAP URL is covered in Appendix C, LDAP URLs.
2.5.2. Setting Default Referrals
2.5.2.1. Setting a Default Referral Using the Console
- In the Directory Server Console, select the Configuration tab.
- Select the top entry in the navigation tree in the left pane.
- Select the Settings tab in the right pane.
- Enter an LDAP URL for the referral.Enter multiple referral URLs separated by spaces and in quotes:
"ldap://dir1.example.com:389/dc=example,dc=com" "ldap://dir2.example.com/"
For more information about LDAP URLs, see Appendix C, LDAP URLs.
2.5.2.2. Setting a Default Referral from the Command Line
ldapmodify
can add a default referral to the cn=config
entry in the directory's configuration file. For example, to add a new default referral from one Directory Server, dir1.example.com
, to a server named dir2.example.com
, add a new line to the cn=config
entry.
- Run the
ldapmodify
utility and add the default referral to thedir2.example.com
server:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=config changetype: modify replace: nsslapd-referral nsslapd-referral: ldap://dir2.example.com/
cn=config
entry of the directory, the directory will return the default referral in response to requests made by client applications. The Directory Server does not need to be restarted.
2.5.3. Creating Smart Referrals
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
.
2.5.3.1. Creating Smart Referrals Using the Directory Server Console
- In the Directory Server Console, select the Directory tab.
- Browse through the tree in the left navigation pane, and select the entry for which to add the referral.
- Right-click the entry, and select Set Smart Referrals.
- Select the Enable Smart Referral check box. (Unchecking the option removes all smart referrals from the entry and deletes the
referral
object class from the entry.) - In the Enter a new Smart Referral field, enter a referral in the LDAP URL format, and then click . The LDAP URL must be in the following format:
ldap://server:port/[optional_dn]
server can be the host name, IPv4 address, or IPv6 address for the server. optional_dn is the explicit DN for the server to return to the requesting client application.The Smart Referral List lists the referrals currently in place for the selected entry. The entire list of referrals is returned to client applications in response to a request with the Return Referrals for All Operations or Return Referrals for Update Operations options in the Suffix Settings tab, which is available under the Configuration tab.To modify the list, click Edit to edit the selected referral or Delete to delete the selected referral. - To set the referral to use different authentication credentials, click Authentication, and specify the appropriate DN and password. This authentication remains valid only until the Console is closed; then it is reset to the same authentication used to log into the Console.
2.5.3.2. Creating Smart Referrals from the Command Line
ldapmodify
command-line utility to create smart referrals from the command line.
referral
object class. This object class allows a single attribute, ref
. The ref
attribute must contain an LDAP URL.
uid=jdoe
:
dn: uid=jdoe,ou=people,dc=example,dc=com objectclass: referral ref: ldap://directory.europe.example.com/cn=john%20doe,ou=people,l=europe,dc=example,dc=com
Note
%20
instead of spaces in any LDAP URL used as a referral.
uid=jdoe,ou=people,dc=example,dc=com
with a referral to directory.europe.example.com
, include the following in the LDIF file before importing:
dn: uid=jdoe,ou=people,dc=example,dc=com objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson objectclass: referral cn: john doe sn: doe uid: jdoe ref: ldap://directory.europe.example.com/cn=john%20doe,ou=people,l=europe,dc=example,dc=com
-M
option with ldapmodify
when there is already a referral in the DN path. For more information on smart referrals, see the Red Hat Directory Server Deployment Guide.
2.5.4. Creating Suffix Referrals
Warning
2.5.4.1. Creating Suffix Referrals Using the Console
- In the Directory Server Console, select the Configuration tab.
- Under Data in the left pane, select the suffix for which to add a referral.
- Click the Suffix Settings tab, and select the Return Referrals for ... Operations radio button.Selecting Return Referrals for Update Operations means that the directory redirects only update and write requests to a read-only database. For example, there may be a local copy of directory data, and that data should be available for searches but not for updates, so it is replicated across several servers. Enabling referrals for that Directory Server only for update requests means that when a client asks to update an entry, the client is referred to the server that owns the data, where the modification request can proceed.
- Click the Referrals tab. Enter an LDAP URL in the[1] in the Enter a new referral field, or click Construct to create an LDAP URL.
- Clickto add the referral to the list.You can enter multiple referrals. The directory returns the entire list of referrals in response to requests from client applications.
2.5.4.2. Creating Suffix Referrals from the Command Line
cn=mapping tree,cn=config
branch.
ldapmodify
and add a suffix referral to the ou=people,dc=example,dc=com
root suffix:
# ldapmodify -a
-D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=ou=people,dc=example,dc=com,cn=mapping tree,cn=config
changetype: add
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: referral
nsslapd-referral: ldap://zanzibar.com/
nsslapd-state
attribute is set to referral
, meaning that a referral is returned for requests made to this suffix. The nsslapd-referral
attribute contains the LDAP URL of the referral returned by the suffix, in this case a referral to the zanzibar.com
server.
nsslapd-state
attribute can also be set to referral on update
. This means that the database is used for all operations except update requests. When a client application makes an update request to a suffix set to referral on update
, the client receives a referral.
ldap://
server:port/
, where server can be the host name, IPv4 address, or IPv6 address.
Chapter 3. Managing Directory Entries
ldapmodify
and ldapdelete
command-line utilities to modify the contents of your directory.
3.1. Managing Entries Using the Command Line
- Add new entries
- Add new attributes to existing entries
- Update existing entries and attributes
- Delete entries and attributes from entries
- Perform bulk operations
# yum install openldap-clients
Note
3.1.1. Providing Input to the ldapadd
, ldapmodify
, and ldapdelete
Utilities
3.1.1.1. Providing Input Using the Interactive Mode
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.
- To enter LDIF statements without creating a file:
Example 3.1. Using the
ldapmodify
Interactive Mode to Enter LDIF StatementsThe following example startsldapmodify
in interactive mode, deletes thetelephoneNumber
attribute, and adds the manager attribute with thecn=manager_name,ou=people,dc=example,dc=com
value to theuid=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 ContentThe following example redirects the output of thecommand_that_outputs_LDIF
command toldapmodify
. 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
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
- 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 thetelephoneNumber
attribute and to adds the manager attribute with thecn=manager_name,ou=people,dc=example,dc=com
value to theuid=user,ou=people,dc=example,dc=com
entry - 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
-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
ldapadd
or ldapmodify
utility. Note that ldapadd
is a symbolic link to /bin/ldapmodify
. Therefore, ldapadd
performs the same operation as ldapmodify -a
.
Note
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
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
ldapadd
automatically performs a changetype: add
operation. Therefore, you do not need to specify changetype: add
in the LDIF statement.
3.1.3.2. Adding an Entry Using ldapmodify
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
-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.
3.1.3.3. Creating a Root Entry
dc=example,dc=com
, bind as the cn=Directory Manager
user and add the entry.
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
ldif2db
utility with the -n back_end
option to set the database that will hold the new entries. For details, see Section 6.1.4, “Importing from the Command Line”.
3.1.4. Updating a Directory Entry
changetype: modify
statement. Depending on the change operation, you can add, change, or delete attributes from the entry.
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
ldapmodify
commands, see the ldapmodify(1) man page.
3.1.4.1. Adding Attributes to an Entry
add
operation.
telephoneNumber
attribute with the 555-1234567
value to the uid=user,dc=people,dc=example,dc=com
entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: uid=user,dc=people,dc=example,dc=com changetype: modify add: telephoneNumber telephoneNumber: 555-1234567
telephoneNumber
attributes at once to the uid=user,dc=people,dc=example,dc=com
:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: uid=user,dc=people,dc=example,dc=com changetype: modify add: telephoneNumber telephoneNumber: 555-1234567 telephoneNumber: 555-7654321
3.1.4.2. Updating an Attribute's Value
Updating a Single-value Attribute
replace
operation to override the existing value. The following command updates the manager
attribute of the uid=user,dc=people,dc=example,dc=com
entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: uid=user,dc=people,dc=example,dc=com changetype: modify replace: manager manager: uid=manager_name,dc=people,dc=example,dc=com
Updating a Specific Value of a Multi-value Attribute
telephoneNumber
attribute that is currently set to 555-1234567
in the uid=user,dc=people,dc=example,dc=com
entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: uid=user,dc=people,dc=example,dc=com changetype: modify delete: telephoneNumber telephoneNumber: 555-1234567 - add: telephoneNumber telephoneNumber: 555-9876543
3.1.4.3. Deleting Attributes from an Entry
delete
operation.
Deleting an Attribute
manager
attribute from the uid=user,dc=people,dc=example,dc=com
entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: uid=user,dc=people,dc=example,dc=com changetype: modify delete: manager
Note
Deleting a Specific Value of a Multi-value Attribute
telephoneNumber
attribute that is set to 555-1234567
from the uid=user,dc=people,dc=example,dc=com
entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: uid=user,dc=people,dc=example,dc=com changetype: modify delete: telephoneNumber telephoneNumber: 555-1234567
3.1.5. Deleting an Entry
Note
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
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"
# 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"
3.1.5.2. Deleting an Entry Using ldapmodify
ldapmodify
utility, use the changetype: delete
operation. For example, to delete the uid=user,ou=People,dc=example,dc=com
entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: uid=user,dc=people,dc=example,dc=com changetype: delete
3.1.6. Renaming and Moving an Entry
ldapmodify
utility to send the LDIF statements to Directory Server when you rename an entry. For example, in interactive mode:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
ldapmodify
commands, see the ldapmodify(1) man page.
Note
moddn
Access Control List (ACL) to grant permissions to move entries. For details, see Section 18.11.2.1, “Targeting Source and Destination DNs”.
3.1.6.1. Types of Rename Operations
- Renaming an Entry
- If you rename a entry, the
modrdn
operation changes the Relative Distinguished Name (RDN) of the entry: - Renaming a Subentry
- For subtree entries, the
modrdn
operation renames the subtree and also the DN components of child entries:Note that for large subtrees, this process can take a lot of time and resources. - Moving an Entry to a New Parent
- A similar action to renaming a subtree is moving an entry from one subtree to another. This is an expanded type of the
modrdn
operation, which simultaneously renames the entry and sets anewSuperior
attribute which moves the entry from one parent to another:
3.1.6.2. Considerations for Renaming Entries
- 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
todc
, might fail with a schema violation. For example, theorganizationalUnit
object class requires theou
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 thecn=memberof task
entry or use thefixup-memberof.pl
to update the relatedmemberOf
attributes.For details about cleaning upmemberOf
attribute references, see Section 8.1.4.7, “Synchronizing memberOf Values”.
3.1.6.3. The deleteOldRDN
Parameter
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 fromcn=old_group,dc=example,dc=com
tocn=new_group,dc=example,dc=com
with thedeleteOldRDN: 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 tocn=new_group,dc=example,dc=com
with thedeleteOldRDN: 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
changetype: modrdn
operation and set the new RDN in the newrdn
attribute.
cn=old_group,ou=Groups,dc=example,dc=com
entry to cn=new_group,ou=Groups,dc=example,dc=com
:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=old_group,ou=Groups,dc=example,dc=com changetype: modrdn newrdn: cn=new_group deleteOldRDN: 1
deleteOldRDN
, see Section 3.1.6.3, “The deleteOldRDN
Parameter”.
3.1.6.5. Moving an Entry to a New Parent
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.
uid=user
entry from ou=Engineering,ou=People,dc=example,dc=com
to ou=Marketing,ou=People,dc=example,dc=com
:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: uid=user,ou=Engineering,ou=People,dc=example,dc=com changetype: modrdn newrdn: uid=user newSuperior= ou=Marketing,ou=People,dc=example,dc=com deleteOldRDN: 1
deleteOldRDN
, see Section 3.1.6.3, “The deleteOldRDN
Parameter”.
3.1.7. Using Special Characters
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
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
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.
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
:
and <
.
3.1.9. Updating an Entry in an Internationalized Directory
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.
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 Entries Using the Directory Console
Note
3.2.1. Creating a Root Entry
- In the Directory Server Console, select the Configuration tab.
- Right-click on the Data entry in the left menu, and select New Root Suffix from the menu.
- Fill in the new suffix and database information.
- In the Directory tab, right-click the top object representing the Directory Server, and choose New Root Object.The secondary menu under New Root Object displays the new suffixes without a corresponding directory entry. Choose the suffix corresponding to the entry to create.
- In the New Object window, select the object class corresponding to the new entry.The object class must contain the attribute used to name the suffix. For example, if the entry corresponds to the suffix
ou=people,dc=example,dc=com
, then choose theorganizationalUnit
object class or another object class that allows theou
attribute. - Clickin the New Object window.
3.2.2. Creating Directory Entries
Table 3.1. Entry Templates and Corresponding Object Classes
Template | Object Class |
---|---|
User | inetOrgPerson |
Group | groupOfUniqueNames |
Organizational Unit | organizationalUnit |
Role | nsRoleDefinition |
Class of Service | cosSuperDefinition |
- In the Directory Server Console, select the Directory tab.
- In the left pane, right-click the main entry to add the new entry, and select the type of entry: User, Group, Organizational Unit, Role, Class of Service, or Other.
- If the new entry type was Other, then a list of object classes opens. Select an object class from the list to define the new entry.
- Supply a value for all the listed attributes. Required attributes are marked with an asterisk (
*
). - To display the full list of attributes available for the object class (entry type), click the Advanced button.In the Property Editor, select any additional attributes, and fill in the attribute values.
- Clickto save the entry. The new entry is listed in the right pane.
3.2.3. Modifying Directory Entries

- From the Directory tab, by right-clicking an entry, and selecting Advanced Properties from the pop-up menu.
- From the Directory tab, by double-clicking an entry and clicking the Advanced button
- From the Create... new entry forms, by clicking the Advanced button
- From the New Object window, by clicking
3.2.3.1. Adding or Removing an Object Class to an Entry
- In the Directory tab of the Directory Server Console, right-click the entry to modify, and select Advanced from the pop-up menu.
- Select the object class field, and click Add Value.The Add Object Class window opens. It shows a list of object classes that can be added to the entry.
- Select the object class to add, and click.
3.2.3.2. Adding an Attribute to an Entry
- In the Directory tab of the Directory Server Console, right-click the entry to modify, and select Advanced from the pop-up menu.
- Click Add Attribute.
- Select the attribute to add from the list, and click.
Note
If the attribute you want to add is not listed, add the object class containing the attribute first, then add the attribute. See Section 3.2.3.1, “Adding or Removing an Object Class to an Entry” for instructions on adding an object class. If you do not know which object class contains the attribute you need, look up the attribute in the Red Hat Directory Server 10 Configuration, Command, and File Reference., which lists the object classes which use that attribute. - Type in the value for the new attribute in the field to the right of the attribute name.
3.2.3.3. Adding Very Large Attributes
nsslapd-maxbersize
sets the maximum size limit for LDAP requests. The default configuration of Directory Server sets this attribute at 2 megabytes. LDAP add or modify operations will fail when attempting to add very large attributes that result in a request that is larger than 2 megabytes. However, the limit is not applied to replication processes.
nsslapd-maxbersize
configuration attribute to a value larger than the largest LDAP request you will make.
- The size of each attribute name in the request
- The size of the values of each of the attributes in the request
- The size of the DN in the request
- Some overhead, usually 10 kilobytes
nsslapd-maxbersize
setting is using attributes which hold CRL values, such as certificateRevocationList
, authorityRevocationList
, and deltaRevocationList
.
nsslapd-maxbersize
attribute, see the corresponding section in the Red Hat Directory Server Configuration, Command, and File Reference.
3.2.3.4. Adding Attribute Values
- In the Directory tab of the Directory Server Console, right-click the entry to modify, and select Advanced from the pop-up menu.
- Select the attribute to which to add a value, and then click Add Value.
- Type in the new attribute value.
3.2.3.5. Adding an Attribute Subtype
- In the Directory tab of the Directory Server Console, right-click the entry to modify, and select Properties from the pop-up menu.
- Click Add Attribute, and select the attribute to add from the list.
- Add a language subtype by selecting a value from the Language drop-down list. Add either a binary or pronunciation subtype by selecting a value from the Subtype drop-down list.
Sometimes a user's name can be more accurately represented in characters of a language other than the default language. For example, a user, Noriko, has a name in Japanese and prefers that her name be represented by Japanese characters when possible. You can select Japanese as a language subtype for the givenname
attribute so that other users can search for her name in Japanese as well as English. For example:
givenname;lang-ja
attribute;lang-subtype:attribute value
cn;lang-ja;lang-en-GB
:value
cn;lang-ja
:ja-value cn;lang-en-GB
:value
Assigning the binary subtype to an attribute indicates that the attribute value is binary, such as user certificates (usercertificate;binary
).
binary
subtype (for example, jpegphoto
), the binary
subtype indicates to clients that multiple variants of the attribute type may exist.
Assigning the pronunciation subtype to an attribute indicates that the attribute value is a phonetic representation. The subtype is added to the attribute name as attribute;phonetic
. This subtype is commonly used in combination with a language subtype for languages that have more than one alphabet, where one is a phonetic representation.
cn
or givenname
. For example, givenname;lang-ja;phonetic
indicates that the attribute value is the phonetic version of the user's Japanese name.
Chapter 4. Tracking Modifications to Directory Entries
- 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
ldapsearch
. For details on running a search for operational attributes, see Section 14.5.7, “Searching for Operational Attributes”.
4.1. Tracking Modifications to the Database through Update Sequence Numbers
4.1.1. An Overview of the Entry Sequence Numbers
4.1.1.1. Local and Global USNs
entryUSN
operational attribute. (For details on running a search for operational attributes, see Section 14.5.7, “Searching for Operational Attributes”.)
Example 4.1. Example Entry USN
dn: uid=jsmith,ou=People,dc=example,dc=com
mail: jsmith@example.com
uid: jsmith
givenName: John
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
sn: Smith
cn: John Smith
userPassword: {SSHA}EfhKCI4iKl/ipZMsWlITQatz7v2lUnptxwZ/pw==
entryusn: 1122
- 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.
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
lastusn;example1: 2130 lastusn;example2: 2070
lastUSN
attribute shows the latest USN only:
lastusn: 4200
4.1.1.2. Importing USN Entries
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. Configuring the USN Plug-in
# ldapmodify -D "cn=Directory Manager" -W -x dn: cn=USN,cn=plugins,cn=config changetype: modify replace: nsslapd-pluginEnabled nsslapd-pluginEnabled: on
4.1.3. Enabling Global USN
- Enable the USN plug-in. See Section 4.1.2, “Configuring the USN Plug-in”.
- Set the
nsslapd-entryusn-global
parameter toon
:# ldapmodify -D "cn=Directory Manager" -W -x dn: cn=config changetype: modify replace: nsslapd-entryusn-global nsslapd-entryusn-global: on
4.1.4. Cleaning up USN Tombstone Entries
usn-tombstone-cleanup.pl
command deletes USN tombstone entries for a specific database back end or specific suffix. Optionally, it can delete all of tombstone entries up to a certain USN. For example:
# /usr/lib64/dirsrv/instance/usn-tombstone-cleanup.pl -D "cn=Directory Manager" -w secret -s "ou=people,dc=example,dc=com" -m 1100
-n
option or the suffix, using the -s
option. If both are given, then the suffix in the -s
option is used.
usn-tombstone-cleanup.pl
command are listed in Table 4.1, “usn-tombstone-cleanup.pl Options”. More details for this tool are in the Configuration, Command, and File Reference.
Table 4.1. usn-tombstone-cleanup.pl Options
Option | Description |
---|---|
-D rootdn | Gives the user DN with root permissions, such as Directory Manager. The default is the DN of the Directory Manager, which is read from the nsslapd-root attribute under cn=config . |
-m maximum_USN | Sets the upper bound for entries to delete. All tombstone entries with an entryUSN value up to the specified maximum (inclusive) are deleted, but not past that USN value. If no maximum USN value is set, then all back end tombstone entries are deleted. |
-n backendInstance | Gives the name of the database containing the entries to clean (delete). |
-s suffix | Gives the name of the suffix containing the entries to clean (delete). |
-w password | The password associated with the user DN. |
4.2. Tracking Entry Modifications through Operational Attributes
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.
Important
nsUniqueID
attribute and replication does not work.
4.2.1. Entries Modified or Created by a Database Link
creatorsName
and modifiersName
attributes contain the name of the user who is granted proxy authorization rights on the remote server. In this case, the attributes do not display the original creator or latest modifier of the entry. However, the access logs show both the proxy user (dn
) and the original user (authzid
). For example:
[23/May/2011:18:13:56.145747965 +051800] conn=1175 op=0 BIND dn="cn=proxy admin,ou=People,dc=example,dc=com" method=128 version=3 [23/May/2011:18:13:56.575439751 +051800] conn=1175 op=0 RESULT err=0 tag=97 nentries=0 etime=0 dn="cn=proxy admin,ou=people,dc=example,dc=com" [23/May/2011:18:13:56.744359706 +051800] conn=1175 op=1 SRCH base="dc=example,dc=com" scope=2 filter="(objectClass=*)" attrs=ALL authzid="uid=user_name,ou=People,dc=example,dc=com"
4.2.2. How to Enable Tracking Of Modifications Using the Command Line
- Set the
nsslapd-lastmod
toon
:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=config nsslapd-lastmod: on
- Optionally, to regenerate the missing
nsUniqueID
attributes:- Export the database to an LDAP Data Interchange Format (LDIF) file. See Section 6.2.3, “Exporting a Database to LDIF Using the Command Line”.
- Import the database from the LDIF file. See Section 6.1.4, “Importing from the Command Line”.
4.2.3. How to Enable Tracking Of Modifications Using the Console
- Open the Directory Server Console. See Section 1.3.1, “Opening the Directory Server Console”.
- On the Configuration tab, select the server name.
- On the Settings tab, select the Track Entry Modification Times check box.
- Optionally, to regenerate the missing
nsUniqueID
attributes:- Export the database to an LDAP Data Interchange Format (LDIF) file. See Section 6.2.3, “Exporting a Database to LDIF Using the Command Line”.
- Import the database from the LDIF file. See Section 6.1.4, “Importing from the Command Line”.
4.3. Tracking the Bind DN for Plug-in Initiated Updates
dn: cn=my_group,ou=groups,dc=example,dc=com modifiersname: uid=jsmith,ou=people,dc=example,dc=com dn: uid=bjensen,ou=people,dc=example,dc=com modifiersname: cn=memberOf plugin,cn=plugins,cn=config
nsslapd-plugin-binddn-tracking
attribute allows the server to track which user originated an update operation, as well as the internal plug-in which actually performed it. The bound user is shown in the modifiersname
and creatorsname
operational attributes, while the plug-in which performed it is shown in the internalModifiersname
and internalCreatorsname
operational attributes. For example:
dn: uid=bjensen,ou=people,dc=example,dc=com modifiersname: uid=jsmith,ou=people,dc=example,dc=com internalModifiersname: cn=memberOf plugin,cn=plugins,cn=config
nsslapd-plugin-binddn-tracking
attribute tracks and maintains the relationship between the bound user and any updates performed for that connection.
Note
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
.
nsslapd-plugin-binddn-tracking
attribute is disabled by default. To allow the server to track operations based on bind DN, enable that attribute using ldapmodify
:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=config changetype: modify replace: nsslapd-plugin-binddn-tracking nsslapd-plugin-binddn-tracking: on
4.4. Tracking Password Change Times
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.
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).
passwordTrackUpdateTime
attribute can be set as part of the global password policy or on a subtree or user-level policy, depending on what clients need to access the password change time. Setting password policies is described in Section 19.4, “Managing the Password Policy”.
Chapter 5. Maintaining Referential Integrity
5.1. How Referential Integrity Works
Note
- For entries, marked in the log file as deleted, the corresponding attribute in the directory is deleted.
- For entries, marked in the log file as updated, the corresponding attribute in the directory is updated.
- For entries, marked in the log file as renamed or moved, the value of the corresponding attribute in the directory is renamed.
member
, uniquemember
, owner
, and seeAlso
attributes immediately after a delete or rename operation. However, the behavior of the Referential Integrity Postoperation plug-in can be configured to suit the needs of the directory in several different ways:
- Record Referential Integrity updates in the replication change log.
- Modify the update interval.
- Select the attributes to which to apply Referential Integrity.
- Disable Referential Integrity.
nsIndexType: pres nsIndexType: eq nsIndexType: subSee Section 13.2, “Creating Standard Indexes” for more information about checking and creating indexes.
5.2. Using Referential Integrity with Replication
- Never enable it on a dedicated consumer server (a server that contains only read-only replicas).
- Never enable it on a server that contains a combination of read-write and read-only replicas.
- It is possible to enable it on a supplier server that contains only read-write replicas.
- With multi-master replication, enable the plug-in on just one supplier.
- Enable the Referential Integrity Postoperation plug-in as described in Section 5.3, “Enabling and Disabling Referential Integrity”.
- Configure the plug-in to record any integrity updates in the changelog.
- Ensure that the Referential Integrity Postoperation plug-in is disabled on all consumer servers.
Note
Because the supplier server sends any changes made by the Referential Integrity Postoperation Integrity plug-in to consumer servers, it is unnecessary to run the Referential Integrity Postoperation plug-in on consumer servers.
5.3. Enabling and Disabling Referential Integrity
5.3.1. Enabling and Disabling Referential Integrity from the Command Line
nsslapd-pluginEnabled
parameter in the plug-in's configuration entry:
- Set the
nsslapd-pluginEnabled
parameter toon
:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=,cn=plugins,cn=config changetype: modify replace: nsslapd-pluginEnabled nsslapd-pluginEnabled: on
- Restart the instance:
# systemctl restart dirsrv@instance_name
5.3.2. Enabling and Disabling Referential Integrity in the Console
5.4. Modifying the Update Interval
delete
or a modrdn
operation. Depending on the amount of operations, this can cause a performance impact. To reduce the performance impact, you can increase the amount of time between updates.
0
: The check for referential integrity is performed immediately.-1
: No check for referential integrity is performed.
Important
0
, you can only enable the plug-in on all masters in a multi-master replication environment if you also set their Referential Integrity Postoperation plug-in's update interval to 0
. However, if you configure a positive value on one master, you must not enable the plug-in on any other master to prevent replication loops and directory inconsistencies.
0
and to enable the plug-in on all masters.
5.4.1. Modifying the Update Interval Using the Command Line
- Set the interval in seconds in the
referint-update-delay
parameter:# ldapmodify -D "cn=Directory Manager" -W -x dn: cn=referential integrity postoperation,cn=plugins,cn=config changetype: modify replace: referint-update-delay referint-update-delay: 0
- Restart the Directory Server instance:
# systemctl restart dirsrv@instance_name
0
, Directory Server cleans up references replicates these changes to all consumers immediately. If you set the interval to a value greater than 0
, and the master who has Referential Integrity enabled is offline, the references are not cleaned up before this master is up again.
5.4.2. Modifying the Update Interval using the Console
- Open the Property Editor in the Referential Integrity Postoperation plug-in's configuration. For details, see Section 1.9.3.2, “Configuring Plug-ins using the Console”.
- Set the interval in seconds in the
referint-update-delay
parameter. - Restart the Directory Server instance. See Section 1.4.2, “Starting and Stopping a Directory Server Instance Using the Console”.
5.5. Modifying the Attribute List
member
, uniquemember
, owner
, and seeAlso
attributes. You can add or delete attributes to be updated using the command line or the Console.
Note
5.5.1. Modifying the Attribute List Using the Console
- Open the Property Editor in the Referential Integrity Postoperation plug-in's configuration. For details, see Section 1.9.3.2, “Configuring Plug-ins using the Console”.
- Update the attributes in the
referint-membership-attr
attribute.You can add additional values or delete existing ones using theand buttons. - Restart the Directory Server instance. See Section 1.4.2, “Starting and Stopping a Directory Server Instance Using the Console”.
5.5.2. Configuring the Attribute List from the Command Line
- Update the attribute list:
- To add an additional attribute that should be checked and updated by the plug-in:
# ldapmodify -D "cn=Directory Manager" -W -x dn: cn=referential integrity postoperation,cn=plugins,cn=config add: referint-membership-attr referint-membership-attr: attribute_name
- To delete an attribute that should no longer be checked and updated by the plug-in:
# ldapmodify -D "cn=Directory Manager" -W -x dn: cn=referential integrity postoperation,cn=plugins,cn=config delete: referint-membership-attr referint-membership-attr: attribute_name
- Restart the Directory Server instance:
# systemctl restart dirsrv@instance_name
5.6. Configuring Scope for the Referential Integrity
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.
- The
nsslapd-pluginEntryScope
attribute - This multi-value attribute 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 attribute allows you to specify to which branches of the database the plug-in should apply the operation.
nsslapd-pluginEntryScope: dn
- The
nsslapd-pluginExcludeEntryScope
attribute - This attribute 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-pluginExcludeEntryScope: dn
- The
nsslapd-pluginContainerScope
attribute - This attribute 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 attribute 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.
nsslapd-pluginContainerScope: dn
Chapter 6. Populating Directory Databases
6.1. Importing Data
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 Console | Local to Console or local to server |
Imports configuration information (cn=config ) | Yes | No |
6.1.1. Setting EntryUSN Initial Values During Import
nsslapd-entryusn-import-initval
attribute, which sets a starting USN for all imported entries.
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.
nsslapd-entryusn-import-initval
is not set, then all entry USNs begin at zero.
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=jsmith,ou=people,dc=example,dc=com entryusn: 1001 ...
nsslapd-entryusn-import-initval
attribute to the server into which data are being imported or to the master server which will perform the initialization.
# ldapmodify -D "cn=Directory Manager" -W -x -D "cn=directory manager" -W -p 389 -h server.example.com -x dn: cn=config changetype: modify add: nsslapd-entryusn-import-initval nsslapd-entryusn-import-initval: next
Note
nsslapd-entryusn-import-initval
attribute is not replicated between servers. This means that the value must be set specifically on whichever supplier server is being used to initialize a replica.
nsslapd-entryusn-import-initval
set to next and is used to initialize a replica, then the entry USNs for imported entries have the highest value plus one. If Supplier2 does not have nsslapd-entryusn-import-initval
set and is used to initialize a replica, then all entry USNs for imported entries begin at zero — even if Supplier1 and Supplier 2 have a multi-master replication agreement between them.
6.1.2. Importing a Database from the Console
ldapmodify
operation is executed to append data, as well as to modify and delete entries. The operation is performed on all of the databases managed by the Directory Server and on remote databases to which the Directory Server has a configured database link.
Note
Warning
- Select the Tasks tab. Scroll to the bottom of the screen, and select Import Database.Alternatively, open the Configuration tab and select Import from the Console menu.
- In the Import Database dialog box, enter the full path to the LDIF file to import in the LDIF file field, or click to select the file to import.If the Console is running on a machine remote to the directory, the field name appears as LDIF file (on the machine running the Console). When browsing for a file, you are not browsing the current directory for the Directory Server host, but the filesystem of the machine running the Console.When importing a database through a remote Console, do not use a relative path to the database. For remote imports, the operation fails with the error Cannot write to file... if a relative path is given for the file. Always use an absolute path for remote import operations.
- In the Options box, select one or both of the following options:
- Add Only. The LDIF file may contain modify and delete instructions in addition to the default add instructions. For the server to ignore operations other than add, select the Add only check box.
- Continue on Error. Select the Continue on error check box for the server to continue with the import even if errors occur. For example, use this option to import an LDIF file that contains some entries that already exist in the database in addition to new ones. The server notes existing entries in the rejects file while adding all new entries.
- In the File for Rejects field, enter the full path to the file in which the server is to record all entries it cannot import, or click to select the file which will contain the rejects.A reject is an entry which cannot be imported into the database; for example, the server cannot import an entry that already exists in the database or an entry that has no parent object. The Console will write the error message sent by the server to the rejects file.Leaving this field blank means the server will not record rejected entries.
Note
ldif2db
import operations.
6.1.3. Initializing a Database from the Console
Directory Manager
in order to initialize a database because an LDIF file that contains a root entry cannot be imported into a database except as the Directory Manager (root DN). Only the Directory Manager has access to the root entry, such as dc=example,dc=com
.
Warning
o=NetscapeRoot
suffix unless you are restoring data. Otherwise, initializing the database deletes information and may require re-installing the Directory Server.
- Select the Configuration tab.
- Expand the Data tree in the left navigation pane. Expand the suffix of the database to initialize, then click the database itself.
- Right-click the database, and select Initialize Database.Alternatively, select Initialize Database from the Object menu.
- In the LDIF file field, enter the full path to the LDIF file to import, or click .
- If the Console is running from a machine local to the file being imported, clickand proceed with the import immediately. If the Console is running from a machine remote to the server containing the LDIF file, select one of the following options, then click :
- From local machine. Indicates that the LDIF file is located on the local machine.
- From server machine. Indicates that the LDIF file is located on a remote server.
The default LDIF directory is/var/lib/dirsrv/slapd-instance/ldif
.
6.1.4. Importing from the Command Line
- Using ldif2db. This import method overwrites the contents of the database and requires the server to be stopped; see Section 6.1.4.1, “Importing Using the ldif2db Command-Line Script”.
- Using ldif2db.pl. This import method overwrites the contents of the database while the server is still running; see Section 6.1.4.2, “Importing Using the ldif2db.pl Perl Script”.
- Using ldif2ldap. This method appends the LDIF file through LDAP. This method is useful to append data to all of the databases; see Section 6.1.4.3, “Importing Using the ldif2ldap Command-Line Script”.
- Creating a cn=tasks entry. This method creates a temporary task entry which automatically launches an import operation. This is functionally like running
ldif2db
. See Section 6.1.4.4, “Importing through the cn=tasks Entry”.
Note
Warning
Note
-E
option with the script. See Section 10.7, “Exporting and Importing an Encrypted Database” for more information.
6.1.4.1. Importing Using the ldif2db Command-Line Script
ldif2db
script overwrites the data in the specified database. Also, the script requires that the Directory Server be stopped when the import begins.
o=NetscapeRoot
configuration information with the o=NetscapeRoot
configuration information in the files being imported.
Warning
- Stop the server:
# systemctl stop dirsrv@instance
- Run the
ldif2db
command-line script:# ldif2db -Z instance_name -n Database1 -i /var/lib/dirsrv/slapd-instance/ldif/demo.ldif -i /var/lib/dirsrv/slapd-instance/ldif/demo2.ldif
For information about the parameters used in the example, see the description of theldif2db
script in the Red Hat Directory Server Configuration, Command, and File Reference.Warning
If the database specified in the-n
option does not correspond with the suffix contained by the LDIF file, all of the data contained by the database is deleted, and the import fails. Make sure that the database name is not misspelled. - Start the server:
# systemctl start dirsrv@instance
6.1.4.2. Importing Using the ldif2db.pl Perl Script
ldif2db
script, the ldif2db.pl
script overwrites the data in the specified database. This script requires the server to be running in order to perform the import.
Warning
ldif2db.pl
script:
# ldif2db.pl -Z instance_name -D "cn=Directory Manager" -w secret -i /var/lib/dirsrv/slapd-instance/ldif/demo.ldif -n Database1
ldif2db.pl
script in the Red Hat Directory Server Configuration, Command, and File Reference.
Note
root
privileges to run the script, but you must authenticate as the Directory Manager.
6.1.4.3. Importing Using the ldif2ldap Command-Line Script
ldif2ldap
script appends the LDIF file through LDAP. Using this script, data are imported to all directory databases at the same time. The server must be running in order to import using ldif2ldap
.
ldif2ldap
:
[root@server ~]# ldif2ldap -Z instance_name -D "cn=Directory Manager" -w secretpwd /var/lib/dirsrv/slapd-instance/ldif/demo.ldif
ldif2ldap
script requires the DN of the administrative user, the password of the administrative user, and the absolute path and filename of the LDIF files to be imported.
ldif2ldap
script in the Red Hat Directory Server Configuration, Command, and File Reference.
6.1.4.4. Importing through the cn=tasks Entry
cn=tasks,cn=config
entry in the Directory Server configuration is a container entry for temporary entries that the server uses to manage tasks. Several common directory tasks have container entries under cn=tasks,cn=config
. Temporary task entries can be created under cn=import,cn=tasks,cn=config
to initiate an import operation.
ldif2db
and ldif2db.pl
scripts, an import operation in cn=tasks
overwrites all of the information in the database.
- A unique name (
cn
) - The filename of the LDIF file to import (
nsFilename
) - The name of the database into which to import the file (
nsInstance
)
-s
and -x
options, respectively, for the ldif2db
and ldif2db.pl
scripts.
ldapmodify
, as described in Section 3.1.3.2, “Adding an Entry Using ldapmodify
”. For example:
# ldapmodify -a
-D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=example import,cn=import,cn=tasks,cn=config
changetype: add
objectclass: extensibleObject
cn: example import
nsFilename: /home/files/example.ldif
nsInstance: userRoot
nsIncludeSuffix: ou=People,dc=example,dc=com
nsExcludeSuffix: ou=Groups,dc=example,dc=com
cn=import,cn=tasks,cn=config
entry description in the Red Hat Directory Server Configuration, Command, and File Reference
6.2. Exporting Data
- 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.
Note
cn=config
), schema information (cn=schema
), or monitoring information (cn=monitor
).

Figure 6.1. Splitting a Database Contents into Two Databases
Warning
6.2.1. Exporting Directory Data to LDIF Using the Console
- Select the Tasks tab. Scroll to the bottom of the screen, and click Export Database(s).Alternatively, select the Configuration tab and click the Export from the Console menu.
- Enter the full path and filename of the LDIF file in the LDIF File field, or click to locate the file.
/var/lib/dirsrv/slapd-instance/ldif
. - If the Console is running on a machine remote to the server, two radio buttons are displayed beneath the LDIF File field.
- Select To local machine to export the data to an LDIF file on the machine from which the Console is running.
- Select To server machine to export to an LDIF file located on the server's machine.
- To export the whole directory, select the Entire database radio button.To export only a single subtree of the suffix contained by the database, select the Subtree radio button, and then enter the name of the suffix in the Subtree text box. This option exports a subtree that is contained by more than one database.Alternatively, clickto select a suffix or subtree.
6.2.2. Exporting a Single Database to LDIF Using the Console
- Select the Configuration tab.
- Expand the Data tree in the left navigation pane. Expand the suffix, and select the database under the suffix.
- Right-click the database, and select Export Database.Alternatively, select Export Database from the Object menu.
- In the LDIF file field, enter the full path to the LDIF file, or click .When thebutton is not enabled, the file is stored in the default directory,
/var/lib/dirsrv/slapd-instance/ldif
.
6.2.3. Exporting a Database to LDIF Using the Command Line
6.2.3.1. Exporting a Database While Directory Server is Running
db2ldif.pl
script to create it or create the task manually. After the task is completed, Directory Server automatically removes the task entry from the cn=export,cn=tasks,cn=config
entry.
db2ldif.pl
command-line option sets which attribute in the task entry, see the Red Hat Directory Server Configuration, Command, and File Reference.
6.2.3.1.1. Exporting a Database Using the db2ldif.pl
Script
db2ldif.pl
script creates a task to export a database while Directory Server is running. For example, to export the userRoot
database:
# db2ldif.pl -Z instance_name -D "cn=Directory Manager" -w - -n userRoot
/var/lib/dirsrv/slapd-instance_name/ldif/
directory. The created file is named instance_name-database_or_suffix_name-time_stamp.ldif
. Alternatively, you can pass the -a file_name
option to the script to set a different location. Note that the Directory Server user requires write permissions in the destination directory.
6.2.3.1.2. Manually Creating an Export Task
db2ldif.pl
script to create an export task, you can create the task entry manually. For example, to create a task that exports the userRoot
database to the /tmp/export.ldif
file:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=task_name,cn=export,cn=tasks,cn=config objectclass: extensibleObject cn: task_name nsInstance: userRoot nsFilename: /tmp/export.ldif
6.2.3.2. Exporting a Database While Directory Server is Stopped
db2ldif
script. The script takes the same options as the db2ldif.pl
script, which can export data while the instance is running.
userRoot
database while the instance is stopped:
# db2ldif -Z instance_name -n userRoot
/var/lib/dirsrv/slapd-instance_name/ldif/
directory. The created file is named instance_name-database_or_suffix_name-time_stamp.ldif
. Alternatively, you can pass the -a file_name
option to the script to set a different location. Note that the Directory Server user requires write permissions in the destination directory.
6.3. Backing up and Restoring Data
- All database files, such as for
userRoot
andNetscapeRoot
, including the data stored within these databases - The transaction logs
- The Indices
Warning
6.3.1. Backing up All Databases
Note
6.3.1.1. Backing up All Databases from the Console
- Select the Tasks tab.
- Click Back Up Directory Server.
- Enter the full path of the directory to store the backup file in the Directory text box, or click , and the server provides a name for the backup directory.If the Console is running on the same machine as the directory, clickto select a local directory.With the default location, the backup files are placed in
/var/lib/dirsrv/slapd-instance/bak
. By default, the backup directory name contains the name of the server instance and the time and date the backup was created (instance-YYYY_MM_DD_hhmmss).
6.3.1.2. Backing up All Databases from the Command Line
db2bak
command-line script or the db2bak.pl
Perl script. The command-line script works when the server is running or when the server is stopped; the Perl script can only be used when the server is running.
Important
db2bak.pl
Perl script or using the Directory Server Console if the server is kept running. The changelog only writes its RUV entries to the database when the server is shut down; while the server is running, the changelog keeps its changes in memory. For the Perl script and the Console, these changelog RUVs are written to the database before the backup process runs. However, that step is not performed by the command-line script.
db2bak
should not be run on a running master server. Either use the Perl script or stop the server before performing the backup.
db2bak.pl
script, run the db2bak.pl
Perl script, specifying the backup filename and directory.
#
db2bak.pl -Z instance_name -D "cn=Directory Manager" -w password -a /var/lib/dirsrv/slapd-example/bak/instance-2020_04_30_16_27_5-custom-name
Note
/
") when using the -a
option to specify the default backup directory that is configured using the nsslapd-bakdir
directive. For example:
#
db2bak.pl -Z instance_name -D "cn=Directory Manager" -w password -a /var/lib/dirsrv/slapd-example/bak
slapd-example/bak
.
nsslapd-bakdir
. Any other directory, even inside the default backup directory (for example, bak/custom-name/
) can be specified with or without a trailing slash.
/var/lib/dirsrv/slapd-instance/bak
. By default, the backup directory is named with the Directory Server instance name and the date of the backup (serverID-YYYY_MM_DD_hhmmss).
ldif2db
, see the script's description in the Red Hat Directory Server Configuration, Command, and File Reference.
6.3.1.3. Backing up the Database through the cn=tasks Entry
cn=tasks,cn=config
entry in the Directory Server configuration is a container entry for temporary entries that the server uses to manage tasks. Several common directory tasks have container entries under cn=tasks,cn=config
. Temporary task entries can be created under cn=backup,cn=tasks,cn=config
to initiate a backup operation.
- A unique name (
cn
). - The directory to write the backup file to (
nsArchiveDir
). The backup file is named with the Directory Server instance name and the date of the backup (serverID-YYYY_MM_DD_hhmmss). - The type of database (
nsDatabaseType
); the only option isldbm database
.
ldapmodify
, as described in Section 3.1.3.2, “Adding an Entry Using ldapmodify
”. For example:
# ldapmodify -a
-D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=example backup,cn=backup,cn=tasks,cn=config
changetype: add
objectclass: extensibleObject
cn: example backup
nsArchiveDir: /export/backups/
nsDatabaseType: ldbm database
cn=backup,cn=tasks,cn=config
entry description in the Red Hat Directory Server Configuration, Command, and File Reference
6.3.2. Backing up the dse.ldif Configuration File
dse.ldif
configuration file. When the Directory Server is started, the directory creates a backup of the dse.ldif
file automatically in a file named dse.ldif.startOK
in the /etc/dirsrv/slapd-instance
directory.
dse.ldif
file is modified, the file is first backed up to a file called dse.ldif.bak
in the /etc/dirsrv/slapd-instance
directory before the directory writes the modifications to the dse.ldif
file.
6.3.3. Restoring All Databases
Note
Important
6.3.3.1. Restoring All Databases from the Console
Warning
Important
- In the Directory Server Console, select the Tasks tab.
- Click Restore Directory Server.
- Select the backup from the Available Backups list, or enter the full path to a valid backup in the Directory text box.The Available Backups list shows all backups located in the default directory,
/var/lib/dirsrv/slapd-instance/bak/
backup_directory. backup_directory is the directory of the most recent backup, in the form serverID-YYYY_MM_DD_hhmmss.
6.3.3.2. Restoring Databases from the Command Line
- Using the
bak2db
command-line script. This script requires the server to be shut down. - Using the
bak2db.pl
Perl script. This script works while the server is running. - Creating a temporary entry under
cn=restore,cn=tasks,cn=config
. This method can also be run while the server is running.
Important
bak2db
command-line script). However, the databases will be unavailable for processing operations during the restore.
6.3.3.2.1. Using the bak2db Command-Line Script
- If the Directory Server is running, stop it:
# systemctl stop dirsrv@instance
- Run the
bak2db
command-line script. Thebak2db
script requires the full path and name of the input file.# bak2db -Z instance_name /var/lib/dirsrv/slapd-instance/bak/instance-2020_04_30_11_48_30
For information about the parameters used in the example, see the description of thebak2db
script in the Red Hat Directory Server Configuration, Command, and File Reference.
6.3.3.2.2. Using bak2db.pl Perl Script
bak2db.pl
Perl script.
# bak2db.pl -Z instance_name -D "cn=Directory Manager" -w secret -a /var/lib/dirsrv/slapd-instance/bak/instance-2020_04_30_11_48_30
bak2db.pl
script in the Red Hat Directory Server Configuration, Command, and File Reference.
Important
6.3.3.2.3. Restoring the Database through the cn=tasks Entry
cn=tasks,cn=config
entry in the Directory Server configuration is a container entry for temporary entries that the server uses to manage tasks. Several common directory tasks have container entries under cn=tasks,cn=config
. Temporary task entries can be created under cn=restore,cn=tasks,cn=config
to initiate a restore operation.
Important
- A unique name (
cn
). - The directory from which to retrieve the backup file (
nsArchiveDir
). - The type of database (
nsDatabaseType
); the only option isldbm database
.
ldapmodify
, as described in Section 3.1.3.2, “Adding an Entry Using ldapmodify
”. For example:
# ldapmodify -a
-D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=example restore,cn=restore,cn=tasks,cn=config
changetype: add
objectclass: extensibleObject
cn: example restore
nsArchiveDir: /export/backups/
nsDatabaseType: ldbm database
cn=restore,cn=tasks,cn=config
entry description in the Red Hat Directory Server Configuration, Command, and File Reference
6.3.4. Restoring a Single Database
- Stop the Directory Server if it is running.
# systemctl stop dirsrv@instance
- Restore the back end from the
/var/lib/dirsrv/slapd-instance/bak
archives with thebak2db
script, using the-n
parameter to specify the database name. For example:# bak2db -Z instance_name /var/lib/dirsrv/slapd-instance/bak/backup_file -n userRoot
- Restart the Directory Server.
# systemctl start dirsrv@instance
Note
If the Directory Server fails to start, remove the database transaction log files in/var/lib/dirsrv/slapd-instance/db/log.###
, then retry starting the server.
6.3.5. Restoring Databases That Include Replicated Entries
- 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 thecn=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.18, “Initializing Consumers”.
Example 6.1. Restoring a Directory Server Replication Topology
- Restore the first master. Use the
ldif2db
utility without the-r
option to import the data. See Section 6.1.4, “Importing from the Command Line”. - Online-initialize the remaining servers by using replication:
- Initialize the second master from the first one.
- Initialize the consumers from the master.
For details, see Section 15.18, “Initializing Consumers”. - On each server, display the
nsds5replicaLastUpdateStatus
attribute to verify that replication works correctly:# ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com -b "cn=example_agreement,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config" nsds5replicaLastUpdateStatus
For details about possible statuses, see the Replication Agreement Status appendix in the Red Hat Directory Server Configuration, Command, and File Reference.
6.3.6. Restoring the dse.ldif Configuration File
dse.ldif
file in the /etc/dirsrv/slapd-instance
directory. The dse.ldif.startOK
file records a copy of the dse.ldif
file at server start up. The dse.ldif.bak
file contains a backup of the most recent changes to the dse.ldif
file. Use the version with the most recent changes to restore the directory.
dse.ldif
configuration file:
- Stop the server.
# systemctl stop dirsrv@instance
- Restore the database as outlined in Section 6.3.4, “Restoring a Single Database” to copy the backup copy of the
dse.ldif
file into the directory. - Restart the server.
# systemctl restart dirsrv@instance
Chapter 7. Managing Attributes and Values
7.1. Enforcing Attribute Uniqueness
7.1.1. Creating a New Configuration Record of the Attribute Uniqueness Plug-in
Note
Example Attribute Uniqueness
:
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=Example Attribute Uniqueness,cn=plugins,cn=config objectClass: top objectClass: nsSlapdPlugin objectClass: extensibleObject cn: Example Attribute Uniqueness nsslapd-pluginPath: libattr-unique-plugin nsslapd-pluginInitfunc: NSUniqueAttr_Init nsslapd-pluginType: betxnpreoperation nsslapd-pluginEnabled: off nsslapd-plugin-depends-on-type: database nsslapd-pluginId: NSUniqueAttr nsslapd-pluginVersion: none nsslapd-pluginVendor: 389 Project nsslapd-pluginDescription: Enforce unique attribute values uniqueness-attribute-name: uid
7.1.2. Configuring Attribute Uniqueness over Suffixes or Subtrees
7.1.2.1. Configuring Attribute Uniqueness over Suffixes or Subtrees Using the Command Line
mail
attributes are unique:
- 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”. - Enable the plug-in configuration record and configure that values stored in
mail
attributes must be unique inside, for example, theou=Engineering,dc=example,dc=com
andou=Sales,dc=example,dc=com
subtrees:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=mail Attribute Uniqueness,cn=plugins,cn=config changetype: modify replace: nsslapd-pluginEnabled nsslapd-pluginEnabled: on - add: uniqueness-attribute-name uniqueness-attribute-name: mail - add: uniqueness-subtrees uniqueness-subtrees: ou=Engineering,dc=example,dc=com uniqueness-subtrees: ou=Sales,dc=example,dc=com
- Optionally, to configure uniqueness across all subtrees configured in this plug-in configuration record:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=mail Attribute Uniqueness,cn=plugins,cn=config changetype: modify add: uniqueness-across-all-subtrees uniqueness-across-all-subtrees: on
- Restart the instance:
# systemctl restart dirsrv@instance_name
7.1.2.2. Configuring Attribute Uniqueness over Suffixes or Subtrees Using the Console
mail
attributes are unique:
- Create a new configuration record of the Attribute Uniqueness plug-in. See Section 7.1.1, “Creating a New Configuration Record of the Attribute Uniqueness Plug-in”.
- Open the Property Editor in the plug-in configuration record's configuration. For details, see Section 1.9.3.2, “Configuring Plug-ins using the Console”.
- To enable the plug-in, set:
nsslapd-pluginEnabled: on
- Set that the
mail
attribute must be unique:uniqueness-attribute-name: mail
- Set the subtrees in which the attribute's value must be unique:
uniqueness-subtrees: ou=Engineering,dc=example,dc=com uniqueness-subtrees: ou=Sales,dc=example,dc=com
Select the value field of theuniqueness-subtrees
attribute and click the button to add the seconduniqueness-subtrees
attribute. - Optionally, to configure uniqueness across all subtrees configured in this plug-in configuration record, add the
uniqueness-across-all-subtrees
attribute and set it toon
:uniqueness-across-all-subtrees: on
- Click Property Editorto close the
- Restart the Directory Server instance. See Section 1.4.2, “Starting and Stopping a Directory Server Instance Using the Console”.
7.1.3. Configuring Attribute Uniqueness over Object Classes
uniqueness-attribute-name
is unique in this subtree.
Note
mail
attributes are unique under the entry that contains the nsContainer
object class:
- 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”. - Enable the plug-in configuration record and configure that values stored in
mail
attributes must be unique under the entry that contains thensContainer
object class:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=mail Attribute Uniqueness,cn=plugins,cn=config changetype: modify replace: nsslapd-pluginEnabled nsslapd-pluginEnabled: on - add: uniqueness-top-entry-oc uniqueness-top-entry-oc: nsContainer
- 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 theuniqueness-subtree-entries-oc
parameter. This additional class will also have to be present.For example, themail
attribute must be unique in all entries under the entry that contains thensContainer
object class set. However, you want that the plug-in only searches themail
in entries that contain a object class that provides this attribute, such asinetOrgPerson
. In this situation enter:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=mail Attribute Uniqueness,cn=plugins,cn=config add: uniqueness-subtree-entries-oc uniqueness-subtree-entries-oc: inetOrgPerson
- Restart the instance:
# systemctl restart dirsrv@instance_name
7.1.4. Attribute Uniqueness Plug-in Configuration Parameters
cn=attribute_uniqueness_configuration_record_name,cn=plugins,cn=config
entry.
nsslapd-plugarg*
attributes (Example 7.2, “Attribute Uniqueness Plug-in Configuration Using nsslapd-pluginarg*
Attributes”).
Important
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
Example 7.2. Attribute Uniqueness Plug-in Configuration Using nsslapd-pluginarg*
Attributes
dn: cn=Example Attribute Uniqueness,cn=plugins,cn=config nsslapd-pluginEnabled: on nsslapd-pluginarg0: attribute=mail nsslapd-pluginarg1: markerObjectClass=objectclass1 nsslapd-pluginarg2: requiredObjectClass=objectclass2
Table 7.1. Attribute Uniqueness Plug-in Configuration Parameters
Parameter | New or Old Syntax | Definition |
---|---|---|
cn | Both | Sets the name of the Attribute Uniqueness plug-in configuration record. You can use any string, but Red Hat recommends naming the configuration record attribute_name Attribute Uniqueness . |
nsslapd-pluginEnabled | Both | Enables (on ) or disables (off ) the plug-in configuration record. |
uniqueness-attribute-name | New | Sets the name of the attribute whose values must be unique. This attribute is multi-valued. |
uniqueness-subtrees | New | Sets the DN under which the plug-in checks for uniqueness of the attribute's value. This attribute is multi-valued. |
uniqueness-across-all-subtrees | New | If enabled (on ), the plug-in checks that the attribute is unique across all subtrees set. If you set the attribute to off , uniqueness is only enforced within the subtree of the updated entry. |
uniqueness-top-entry-oc | New | Directory Server searches this object class in the parent entry of the updated object. If it was not found, 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. |
uniqueness-subtree-entries-oc | New | Optionally, when using the uniqueness-top-entry-oc parameter, you can configure that the Attribute Uniqueness plug-in only verifies if an attribute is unique, if the entry contains the object class set in this parameter. For details, see Section 7.1.3, “Configuring Attribute Uniqueness over Object Classes”. |
nsslapd-pluginarg0 | Old |
The plug-in-specific attribute equivalent of this
nsslapd-pluginarg* parameter is uniqueness-attribute-name . See this parameter for a description.
Set the attribute to
attribute=attribute_name .
|
nsslapd-pluginarg[1-9] | Old |
The plug-in-specific attribute equivalent of this
nsslapd-pluginarg* parameter is uniqueness-top-entry-oc . See this parameter for a description.
Set the attribute to
markerObjectClass=object_class .
|
nsslapd-pluginarg[1-9] | Old |
The equivalent plug-in-specific attribute is
uniqueness-subtree-entries-oc . See this parameter for a description.
Set the attribute to
requiredObjectClass=object_class .
|
7.2. Assigning Class of Service
- 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.
7.2.1. About the CoS Definition Entry
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.
- 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 themanager
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.
7.2.2. About the CoS Template Entry
cosTemplate
. The CoS template entries for a given CoS are stored in the directory tree along with the CoS definition.
- 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
dc=example,dc=com
. The three entries for this CoS appear as illustrated in Figure 7.1, “Sample Pointer CoS”.

Figure 7.1. Sample Pointer CoS
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
manager
attribute of the target entry to identify the template entry. The three CoS entries appear as illustrated in Figure 7.2, “Sample Indirect CoS”.

Figure 7.2. Sample Indirect CoS
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

Figure 7.3. Sample Classic CoS
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
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
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. Whenoperational
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 thedescription
attribute, it is not possible to use theoperational
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.
default
is assumed.
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
7.2.7. Handling Multi-valued Attributes with CoS
- 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
cosPriority
attribute.
cosAttribute: attribute override merge-schemes
Note
cosAttribute
for every competing CoS definition. Otherwise, one combination is chosen arbitrarily from all possible CoS definitions.
- 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
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.
dn: cn=data,dc=example,dc=com objectclass: top objectclass: extensibleObject objectclass: cosTemplate departmentNumber: 71776 cosPriority: 0
departmentNumber
attribute. It has a priority of zero, meaning this template takes precedence over any other conflicting templates that define a different departmentNumber
value.
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
cosPriority
values is not defined in Directory Server; do not enter negative values.
7.2.8. Searches for CoS-Specified Attributes
postalCode
attribute for every entry in a subtree. Searches against those CoS-defined attributes, however, do not behave like searches against regular entries.
- 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.
ldapsearch
command uses the filter (postalCode=*)
, then Barbara Jensen's entry is returned, while Ted Morris's is not.
- 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.
ldapsearch
command uses the filter (postalCode=*)
, then both Barbara Jensen's and Ted Morris's entries are returned.
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.
7.2.9. Access Control and CoS
7.2.10. Managing CoS Using the Console
7.2.10.1. Creating a New CoS
- In the Directory Server Console, select the Directory tab.
- Browse the tree in the left navigation pane, and select the parent entry for the new class of service.
- Go to the Object menu, and select New > Class of Service.Alternatively, right-click the entry and select New > Class of Service.
- Select General in the left pane. In the right pane, enter the name of the new class of service in the Class Name field. Enter a description of the class in the Description field.
- Click Attributes in the left pane. The right pane displays a list of attributes generated on the target entries.Clickto browse the list of possible attributes and add them to the list.
- After an attribute is added to the list, a drop-down list appears in the Class of Service Behavior column.
- Select Does not override target entry attribute to tell the directory to only return a generated value if there is no corresponding attribute value stored with the entry.
- Select Overrides target entry attribute to make the value of the attribute generated by the CoS override the local value.
- Select Overrides target entry attribute and is operational to make the attribute override the local value and to make the attribute operational, so that it is not visible to client applications unless explicitly requested.
- Select Does not override target entry attribute and is operational to tell the directory to return a generated value only if there is no corresponding attribute value stored with the entry and to make the attribute operational (so that it is not visible to client applications unless explicitly requested).
Note
An attribute can only be made operational if it is also defined as operational in the schema. For example, if a CoS generates a value for thedescription
attribute, you cannot select Overrides target entry attribute and is operational because this attribute is not marked operational in the schema. - Click Template in the left pane. In the right pane, select how the template entry is identified.
- By its DN. To have the template entry identified by only its DN (a pointer CoS), enter the DN of the template in the Template DN field. Click to locate the DN on the local server. This will be an exact DN, such as
cn=CoS template,ou=People,dc=example,dc=com
. - Using the value of one of the target entry's attribute. To have the template entry identified by the value of one of the target entry's attributes (an indirect CoS), enter the attribute name in the Attribute Name field. Click to select a different attribute from the list of available attributes.
- Using both its DN and the value of one of the target entry's attributes. To have the template entry identified by both its DN and the value of one of the target entry's attributes (a classic CoS), enter both a template DN and an attribute name. The template DN in a classic CoS is more general than for a pointer CoS; it references the suffix or subsuffix where the template entries will be. There can be more than one template for a classic CoS.
- Click.
7.2.10.2. Creating the CoS Template Entry
cosTemplateDn
attribute reflects that DN, it is best to place the template entries under the CoS itself.
- For a pointer CoS, make sure that this entry reflects the exact DN given when the CoS was created.
- For a classic CoS, the template DN should be recursive, pointing back to the CoS entry itself as the base suffix for the template.
- In the Directory Server Console, select the Directory tab.
- Browse the tree in the left navigation pane, and select the parent entry that contains the class of service.The CoS appears in the right pane with other entries.
- Right-click the CoS, and select New > Other.Alternatively, select the CoS in the right pane, click Object in the menu at the top, and select New > Other.
- Select
cosTemplate
from the list of object classes.Note
TheLDAPsubentry
object class can be added to a new template entry. Making the CoS template entry an instance of theLDAPsubentry
object class allows ordinary searches to be performed unhindered by the configuration entries. However, if the template entry already exists and is used for something else (for example, if it is a user entry), theLDAPsubentry
object class does not need to be added to the template entry. - Select the object classes attribute, and click.
- Add the
extensibleObject
object class. This makes it possible to add any attribute available in the directory. - Click thebutton.
- Add the
cn
attribute, and give it a value that corresponds to the attribute value in the target entry. For example, if themanager
attribute is used to set the value for a classic CoS, give thecn
a value of a manager's DN, such asuid=bparker,ou=people,dc=example,dc=com
. Alternatively, set it to a role, such ascn=QA Role,dc=example,dc=com
or a regular attribute value. For example, if theemployeeType
attribute is selected, it can befull time
ortemporary
. - Click thebutton in the lower right corner to change the naming attribute.
- Use the
cn
of the entry as the naming attribute instead ofcospriority
. - Click thebutton, and add the attributes listed in the CoS. The values used here will be used throughout the directory in the targeted entries.
- Set the
cospriority
. There may be more than one CoS that applies to a given attribute in an entry; thecospriority
attribute ranks the importance of that particular CoS. The highercospriority
will take precedence in a conflict. The highest priority is0
.Templates that contain nocosPriority
attribute are considered the lowest priority. In the case where two or more templates could supply an attribute value and they have the same (or no) priority, a value is chosen arbitrarily.Note
The behavior for negativecosPriority
values is not defined in Directory Server; do not enter negative values.Note
ThecosPriority
attribute is not supported by indirect CoS.
7.2.11. Managing CoS from the Command Line
7.2.11.1. Creating the CoS Definition Entry from the Command Line
LDAPsubentry
object class and the cosSuperDefinition
object class.
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.3, “An Example Pointer CoS Entry”.
Example 7.3. 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
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.4, “An Example Indirect CoS Entry”.
Example 7.4. 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
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.5, “An Example Classic CoS Entry”.
Example 7.5. An Example Classic CoS Entry
dn: cn=classicCoS,dc=example,dc=com objectclass: top objectclass: cosSuperDefinition objectclass:cosClassicDefinition
cosTemplateDn
:DN_stringcosSpecifier
:attribute_name cosAttribute:list_of_attributes qualifier cn: classicCoS
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.11.2. Creating the CoS Template Entry from the Command Line
cosTemplate
object class.
Note
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.
cosAttribute
attribute of the CoS definition entry) and the value for that attribute.
postalCode
attribute follows:
dn:cn=exampleUS,ou=data,dc=example,dc=com objectclass: top objectclass: extensibleObject objectclass: cosTemplate postalCode: 44438
7.2.11.3. Example of a Pointer CoS
dc=example,dc=com
tree.
- Add a new pointer CoS definition entry to the
dc=example,dc=com
suffix usingldapmodify
: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
- Create the template entry:
dn: cn=exampleUS,ou=data,dc=example,dc=com changetype: add objectclass: top objectclass: extensibleObject objectclass: cosTemplate postalCode: 44438
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.11.4. Example of an Indirect CoS
manager
attribute of the target entry to identify the CoS template entry, which varies depending on the different values of the attribute.
- Add a new indirect CoS definition entry to the
dc=example,dc=com
suffix usingldapmodify
:dn: cn=indirectCoS,dc=example,dc=com changetype: add objectclass: top objectclass: cosSuperDefinition objectclass: cosIndirectDefinition cosIndirectSpecifier: manager cosAttribute: departmentNumber
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.11.5. Example of a Classic CoS
cosSpecifier
attribute.
- Add a new classic CoS definition entry to the
dc=example,dc=com
suffix usingldapmodify
: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
- 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 thebusinessCategory
attribute in the target entry, and then the attributes are added or overwritten according to the value in the template:dn: cn=sales,cn=classicCoS,dc=example,dc=com changetype: add objectclass: top objectclass: extensibleObject objectclass: cosTemplate postalCode: 44438 dn: cn=marketing,cn=classicCoS,dc=example,dc=com changetype: add objectclass: top objectclass: extensibleObject objectclass: cosTemplate postalCode: 99111
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.11.6. Searching for CoS Entries
ou=People,dc=example,dc=com
, for example, the following ldapsearch
command will not return them:
ldapsearch -x -s sub -b ou=People,dc=example,dc=com "(objectclass=*)"
ldapSubEntry
object class to the CoS definition entries. For example:
dn: cn=pointerCoS,ou=People,dc=example,dc=com objectclass: top objectclass: cosSuperDefinition objectclass: cosPointerDefinition objectclass: ldapSubEntry cosTemplateDn: cn=exampleUS,ou=data,dc=example,dc=com cosAttribute: postalCode override
(objectclass=ldapSubEntry)
, with the search. This filter can be added to any other search filter using OR (|):
ldapsearch -x -s sub -b ou=People,dc=example,dc=com "(|(objectclass=*)(objectclass=ldapSubEntry))"
ou=People,dc=example,dc=com
subtree.
Note
7.2.12. Creating Role-Based Attributes
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.
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
nsRoleFilter
attribute cannot accept virtual attribute values.
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
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.
dn:cn="cn=ManagerRole,ou=people,dc=example,dc=com",cn=managerCOS,dc=example,dc=com objectclass: top objectclass: extensibleObject objectclass: cosTemplate mailboxquota: 1000000
mailboxquota
attribute, 1000000
.
Note
7.3. Linking Attributes to Manage Attribute Values
7.3.1. About Linking Attributes
linkType
) and one attribute which is automatically maintained by the plug-in (managedType
).

Figure 7.4. Basic Linked Attribute Configuration
Note

Figure 7.5. Restricting the Linked Attribute Plug-in to a Specific Subtree
- Both the managed attribute and linked attribute must require the Distinguished Name syntax in their attribute definitions. The linked attributes are essentially managed cross-references, and the way that the plug-in handles these cross-references is by pulling the DN of the entry from the attribute value.For information on planning custom schema elements, see Chapter 12, Managing the Directory Schema.
- Each Linked Attribute Plug-in instance must be local and any managed attributes must be blocked from replication using fractional replication.Any changes that are made on one supplier will automatically trigger the plug-in to manage the values on the corresponding directory entries, so the data stay consistent across servers. However, the managed attributes must be maintained by the plug-in instance for the data to be consistent between the linked entries. This means that managed attribute values should be maintained solely by the plug-in processes, not the replication process, even in a multi-master replication environment.For information on using fractional replication, see Section 15.1.7, “Replicating a Subset of Attributes with Fractional Replication”.
7.3.2. Looking at the Linking Attributes Plug-in Syntax
- 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.6. 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
Table 7.2. Linked Attributes Plug-in Instance Attributes
Plug-in Attribute | Description |
---|---|
cn | Gives a unique name for the plug-in instance. |
linkScope | Contains the DN of a suffix to which to restrict the function of the plug-in instance. |
linkType | Gives the attribute which is maintained by an administrator. This attribute is manually maintained and is used as the reference for the plug-in. This attribute must have a DN value format. When the attribute is added, modified, or deleted, then its value contains the DN of the target entry for the plug-in to update. |
managedType | Gives the attribute which is maintained by the plug-in. This attribute is created and updated on target entries. This attribute must have a DN value format. When the attribute is added to the entry, its value will point back as a cross-reference to the managed entry. |
7.3.3. Configuring Attribute Links
Note
- If it is not already enabled, enable the Linked Attributes Plug-in, as described in Section 1.9.2.2, “Enabling Plug-ins in the Directory Server Console” or Section 1.9.1, “Enabling Plug-ins Dynamically”.
- Create the plug-in instance. Both the
managedType
andlinkType
attributes are required. The plug-in syntax is covered in Section 7.3.2, “Looking at the Linking Attributes Plug-in Syntax”. The following example shows the plug-in instance created by usingldapmodify
:dn: cn=Manager Link,cn=Linked Attributes,cn=plugins,cn=config changetype: add objectClass: top objectClass: extensibleObject cn: Manager Link linkType: directReport managedType: manager
- If the server is not configured to enable dynamic plug-ins using
nsslapd-dynamic-plugins
, restart the server to apply the new plug-in instance:# systemctl restart dirsrv.target
7.3.4. Cleaning up Attribute Links
fixup-linkedattrs.pl
) or by launching a fix-up task.
7.3.4.1. Regenerating Linked Attributes Using fixup-linkedattrs.pl
fixup-linkedattrs.pl
script launches a special task to regenerate all of the managed-link attribute pairs on directory entries. One or the other may be lost in certain situations. If the link attribute exists in an entry, the task traces the cross-referenced DN in the available attribute and creates the corresponding configured managed attribute on the referenced entry. If a managed attribute exists with no corresponding link attribute, then the managed attribute value is removed.
# fixup-linkedattrs.pl -D "cn=Directory Manager" -w password
-l
option to specify the target plug-in instance DN:
# fixup-linkedattrs.pl -D "cn=Directory Manager" -w password -l "cn=Manager Link,cn=Linked Attributes,cn=plugins,cn=config"
fixup-linkedattrs.pl
script in the Red Hat Directory Server Configuration, Command, and File Reference.
7.3.4.2. Regenerating Linked Attributes Using ldapmodify
cn=tasks
configuration entry in the dse.ldif
file, so it is also possible to initiate a task by adding the entry using ldapmodify
. When the task is complete, the entry is removed from the directory.
fixup-linkedattrs.pl
script when it is run.
cn=fixup linked attributes,cn=tasks,cn=config
entry. The only required attribute is the cn
for the specific task, though it also allows the ttl
attribute to set a timeout period. Using ldapmodify
:
dn: cn=example,cn=fixup linked attributes,cn=tasks,cn=config changetype: add cn:example ttl: 5
dse.ldif
configuration, so it is possible to reuse the same task entry continually.
cn=fixup linked attributes
task configuration is described in more detail in the Configuration, Command, and File Reference.
7.4. Assigning and Managing Unique Numeric Attribute Values
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
7.4.1. About Dynamic Number Assignments
7.4.1.1. Filters, Searches, and Target Entries
Important
7.4.1.2. Ranges and Assigning Numbers
- 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
....
7.4.1.3. Multiple Attributes in the Same Range
- 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.
employeeID
to a new employee entry, it is important each employee entry is assigned a unique employeeID
.
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
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.
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
Example 7.7. DNA and Unique Bank Account Numbers
primaryAccount
and customerID
attributes. The Example Bank administrator configured the DNA Plug-in to assign unique values for both attributes from the same range.
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 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)
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.
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
- 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 is1
. - 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 is10
, 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.
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
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.
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
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.
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
7.4.3.1. Configuring Unique Number Assignments
Note
dnaNextvalue
is already taken, which requires an equality index on an integer attribute, with the proper ordering matching rule.
Note
- Create the shared container entry in the replicated subtree. The following example uses
ldapmodify
to do so:dn: ou=Ranges,dc=example,dc=coma changetype: add objectclass: top objectclass: extensibleObject objectclass: organizationalUnit ou: Ranges dn: cn=Account UIDs,ou=Ranges,dc=example,dc=coma changetype: add objectclass: top objectclass: extensibleObject cn: Account UIDs
- Enable the DNA Plug-in and configure it as dynamic. By default, the plug-in entry (which is the container entry) is disabled. For details on configuring dynamic plug-ins, see Section 1.9.1, “Enabling Plug-ins Dynamically”.
- Create the new DNA Plug-in instance beneath the container entry. For example:
Note
The plug-in attribute which sets which entry attributes have unique number assignments,dnaType
, is multi-valued. If multiple attributes are set in the same plug-in instance, then their number assignments are taken from the same range. To use different ranges, configure different plug-in instances.Usingldapmodify
:dn: cn=Account UIDs,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config changetype: add objectClass: top objectClass: dnaPluginConfig cn: Account UIDs dnatype: uidNumber dnafilter: (objectclass=posixAccount) dnascope: ou=People,dc=example,dc=com dnanextvalue: 1 dnaMaxValue: 1300 dnasharedcfgdn: cn=Account UIDs,ou=Ranges,dc=example,dc=com dnathreshold: 100 dnaRangeRequestTimeout: 60 dnaMagicRegen: magic
For a list of attributes supported in thecn=DNA_config_entry,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config
entry, see the Red Hat Directory Server Configuration, Command, and File Reference. - For servers in multi-master replication, create a configuration entry for the host, which specifies its connection information and range.The DN of the entry is a combination of the host name and the port number (
dnaHostname+dnaPortNum
).Usingldapmodify
:dn: dnaHostname=ldap1.example.com+dnaPortNum=389,cn=Account UIDs,ou=Ranges,dc=example,dc=com changetype: add objectClass: dnaSharedConfig objectClass: top dnahostname: ldap1.example.com dnaPortNum: 389 dnaSecurePortNum: 636 dnaRemainingValues: 1000
- If the server is not configured to enable dynamic plug-in, restart the server to load the new plug-in instance.
# systemctl restart dirsrv@instance
7.4.3.2. Editing the DNA Plug-in in the Console
Note
dnaNextvalue
is already taken, which requires an equality index on an integer attribute, with the proper ordering matching rule.
- Click the Directory tab.
- Open the config folder, and then expand the plugins folder.
- Click the Distributed Numeric Assignment plug-in folder. All of the DNA Plug-in instances are listed in the main window.
- Highlight the DNA instance entry, and right-click on the Advanced link to open the property editor.
- Edit the DNA-related attributes.
7.4.4. Distributed Number Assignment Plug-in Performance Notes
Chapter 8. Organizing and Grouping Entries
8.1. Using Groups
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.
8.1.1. Creating Static Groups in the Console
Note
- In the Directory Server Console, select the Directory tab.
- In the left pane, right-click the entry under which to add a new group, and select New > Group.Alternatively, go to the Object menu, and select New > Group.
- Click General in the left pane. Type a name for the new group in the Group Name field (the name is required), and enter a description of the new group in the Description field.
- Click Members in the left pane. In the right pane, select the Static Group tab. Click to add new members to the group.
- In the Search drop-down list, select what sort of entries to search for (users, groups, or both) then click Search.
- Select the members from the returned entries, and click.
- Click Languages in the left pane to add language-specific information for the group.
- Clickto create the new group. It appears in the right pane.
Note
(objectclass=person)
and scope sub-tree
. See Section 13.4.2, “Creating Browsing Indexes from the Command Line”.
8.1.2. Creating Dynamic Groups in the Console
- In the Directory Server Console, select the Directory tab.
- In the left pane, right-click the entry under which to add a new group, and select New > Group.Alternatively, go to the Object menu, and select New > Group.
- Click General in the left pane. Type a name for the new group in the Group Name field (the name is required), and enter a description of the new group in the Description field.
- Click Members in the left pane. In the right pane, select the Dynamic Group tab. Click to create a LDAP URL for querying the database.
- Enter an LDAP URL in the text field or selectto be guided through the construction of an LDAP URL.The results show the current entries (group members) which correspond to the filter.
- Click Languages in the left pane to add language-specific information for the group.
- Click. The new group appears in the right pane.
Note
(objectclass=person)
and scope sub-tree
. See Section 13.4.2, “Creating Browsing Indexes from the Command Line”.
8.1.3. Creating Groups in the Command Line
groupOfNames
(recommended) is a simple group, that allows any entry to be added. The attribute used to determine members for this ismember
.groupOfUniqueNames
, likegroupOfNames
, 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 isuniqueMember
.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 withgroupOfNames
andgroupOfUniqueNames
.groupOfCertificates
is similar togroupOfURLs
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 ismemberCertificate
.
Table 8.1. Dynamic and Static Group Schema
Type of Group | Group Object Classes | Member Attributes |
---|---|---|
Static | groupOfUniqueNames | uniqueMember |
Dynamic |
groupOfUniqueNames
groupOfURLs
| memberURL |
ldapmodify
:
dn: cn=static group,ou=Groups,dc=example,dc=com changetype: add objectClass: top objectClass: groupOfUniqueNames cn: static group description: Example static group. uniqueMember: uid=mwhite,ou=People,dc=example,dc=com uniqueMember: uid=awhite,ou=People,dc=example,dc=com
groupOfUniqueNames
, can explicitly list some group members along with the dynamic LDAP URL. For example, using ldapmodify
:
dn: cn=dynamic group,ou=Groups,dc=example,dc=com changetype: add objectClass: top objectClass: groupOfUniqueNames objectClass: groupOfURLs cn: dynamic group description: Example dynamic group. memberURL: ldap:///dc=example,dc=com??sub?(&(objectclass=person)(cn=*sen*))
Note
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.4. Listing Group Membership in User Entries
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.)
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.
8.1.4.1. Considerations When Using the memberOf
Plug-in
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:- Enable the
memberOf
plug-in on all master and read-only replica servers in the topology. In this case, you must exclude thememberOf
attribute from replication in all replication agreements. For details about about excluding attributes, see Section 15.1.7, “Replicating a Subset of Attributes with Fractional Replication”. - Enable the
memberOf
plug-in only on all master servers in the topology. For this:- You must disable replication of the
memberOf
attribute to all write-enabled masters in the replication agreement. For details about about excluding attributes, see Section 15.1.7, “Replicating a Subset of Attributes with Fractional Replication”. - You must Enable replication of the
memberOf
attribute to all read-only replicas in their replication agreement. - You must not enable the
memberOf
plug-in on read-only replicas.
- 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 thememberOfAllBackends
parameter toon
. See Section 8.1.4.4.1, “Editing the MemberOf Plug-in from the Console”.
8.1.4.2. Required Object Classes by the memberOf
Plug-In
memberOf
plug-in will add the nsMemberOf
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.
extensibleObject
object class.
Note
LDAP: error code 65 - Object Class Violation
8.1.4.3. The MemberOf Plug-in Syntax
memberOfGroupAttr
) and the other for the attribute to create and manage in the member's user entry (memberOfAttr
).
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.
Example 8.1. Default MemberOf Plug-in Entry
dn: cn=MemberOf Plugin,cn=plugins,cn=config objectClass: top objectClass: nsSlapdPlugin objectClass: extensibleObjectcn: MemberOf Plugin
nsslapd-pluginPath: libmemberof-plugin
nsslapd-pluginInitfunc: memberof_postop_init
nsslapd-pluginType: postoperationnsslapd-pluginEnabled: on
nsslapd-plugin-depends-on-type: databasememberOfGroupAttr: member
memberOfGroupAttr: uniqueMember
memberOfAttr: memberOf
memberOfAllBackends: on
nsslapd-pluginId: memberOf nsslapd-pluginVersion:X.Y.Z
nsslapd-pluginVendor: Red Hat, Inc. nsslapd-pluginDescription: memberOf plugin
Note
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. Configuring an Instance of the MemberOf Plug-in
8.1.4.4.1. Editing the MemberOf Plug-in from the Console
- Select the Configuration tab, and expand to the Plugins folder.
- Scroll to the Memberof Plugin entry.
- Make sure that the plug-in is enabled. This is disabled by default.
- Click the Advanced Properties Editor.button to open the
- The
memberOfGroupAttr
attribute sets the attribute in the group entry which the server uses to identify member entries; this attribute can be used multiple times for different group/member types. ThememberOfAttr
attribute sets the attribute which the plug-in creates and manages on user entries. - Save the changes.
- If the Directory Server is not configured to enable dynamic plug-ins, restart the server to update the plug-in.
8.1.4.4.2. Editing the MemberOf Plug-in from the Command Line
- Enable the MemberOf Plug-in. Using
ldapmodify
:dn: cn=MemberOf Plugin,cn=plugins,cn=config changetype: modify replace: nsslapd-pluginEnabled nsslapd-pluginEnabled: on
- Set the attribute to use for the group member entry attribute. The default attribute is
member
, which can be changed using thereplace
command, or, since thememberOfGroupAttr
attribute is multi-valued, additional member types can be added to the definition. For example, usingldapmodify
:dn: cn=MemberOf Plugin,cn=plugins,cn=config changetype: modify add: memberOfGroupAttr memberOfGroupAttr: uniqueMember add: memberOfGroupAttr memberOfGroupAttr: customMember-
- Set the attribute to set on the user entries to show group membership. For example, using
ldapmodify
:dn: cn=MemberOf Plugin,cn=plugins,cn=config changetype: modify replace: memberOfAttr memberOfAttr: memberOf
- Optional. If the deployment uses distributed databases, then enable the
memberOfAllBackends
attribute to search through all databases, not just the local one, for user entries. Usingldapmodify
:dn: cn=MemberOf Plugin,cn=plugins,cn=config changetype: modify replace: memberOfAllBackends memberOfAllBackends: on
- If the Directory Server is not configured to enable dynamic plug-ins, restart the server to load the modified new plug-in instance.
8.1.4.6. Setting the Scope of the MemberOf Plug-in
memberOfEntryScope
and memberOfEntryScopeExcludeSubtree
parameters to set what suffixes the MemberOf
plug-in works on.
MemberOf
plug-in only adds the memberOf
attribute to the group if both the user and the group are in the plug-in's scope. For example, to configure the MemberOf
plug-in to work on all entries in dc=example,dc=com
, but to exclude entries in ou=private,dc=example,dc=com
, set:
memberOfEntryScope: dc=example,dc=com memberOfEntryScopeExcludeSubtree: ou=private,dc=example,dc=com
memberOfEntryScope
parameter:
- The membership attribute, such as
member
, is updated in the group entry to remove the user DN value. - The
memberOf
attribute is updated in the user entry to remove the group DN value.
Note
memberOfEntryScopeExcludeSubtree
parameter has a higher priority than values set in memberOfEntryScope
. If the scopes set in both parameters overlap, the MemberOf
plug-in only works on the non-overlapping directory entries.
8.1.4.7. Synchronizing memberOf Values
memberOf
attribute on group member entries, based on the configuration in the group entry itself. However, the memberOf
attribute can be edited on a user entry directly (which is improper) or new entries can be imported or replicated over to the server that have a memberOf
attribute already set. These situations create inconsistencies between the memberOf
configuration managed by the server plug-in and the actual memberships defined for an entry.
memberOf
repair task which manually runs the plug-in to make sure the appropriate memberOf
attributes are set on entries. There are three ways to trigger this task:
- In the Directory Server Console
- Using the
fixup-memberof.pl
script - Running a
cn=memberof task,cn=tasks,cn=config
tasks entry
Note
memberOf
attributes for the entries on other servers are not updated until the updated entry is replicated.
8.1.4.7.1. Initializing and Regenerating memberOf Attributes Using fixup-memberof.pl
fixup-memberof.pl
is a Perl script wrapper used to regenerate memberOf
attributes as described in Section 8.1.4.7.2, “Initializing and Regenerating memberOf Attributes Using ldapmodify”.
man fixup-memberof.pl
.
8.1.4.7.2. Initializing and Regenerating memberOf Attributes Using ldapmodify
memberOf
attributes is one of the tasks which can be managed through a special task configuration entry. Task entries occur under the cn=tasks
configuration entry in the dse.ldif
file, so it is also possible to initiate a task by adding the entry using ldapmodify
. As soon as the task is complete, the entry is removed from the directory.
fixup-memberof.pl
script creates a special task entry in a Directory Server instance which regenerates the memberOf
attributes.
cn=memberof task,
cn=tasks,cn=config
entry. The only required attribute is the cn
for the specific task. Using ldapmodify
:
dn: cn=example memberOf,cn=memberof task,cn=tasks,cn=config changetype: add cn:example memberOf
dse.ldif
configuration, so it is possible to reuse the same task entry continually.
cn=memberof task
configuration is described in more detail in the Configuration, Command, and File Reference.
8.1.5. Automatically Adding Entries to Specified Groups
Note
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.
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.
Note
8.1.5.1. Looking at the Structure of an Automembership Rule
cn=plugins,cn=config
. Group assignments are defined through child entries.
8.1.5.1.1. The Automembership Configuration Entry
- An LDAP search to identify entries, including both a search scope and a search filter (
autoMemberScope
andautoMemberFilter
) - 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 asdn
(autoMemberGroupingAttr
)
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
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
Example 8.2. Automember Definition for a Host Group
dn: cn=Hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config objectclass: autoMemberDefinition cn: Hostgroups autoMemberScope: dc=example,dc=com autoMemberFilter: objectclass=ipHost autoMemberDefaultGroup: cn=systems,cn=hostgroups,dc=example,dc=com autoMemberGroupingAttr: member:dn
Example 8.3. Regular Expression Condition for a Web Server Group
dn: cn=webservers,cn=Hostgroups,cn=Auto Membership Plugin,cn=plugins,cn=config objectclass: autoMemberRegexRule description: Group for webservers cn: webservers autoMemberTargetGroup: cn=webservers,cn=hostgroups,dc=example,dc=com autoMemberInclusiveRegex: fqdn=^www\.web[0-9]+\.example\.com
^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.

Figure 8.1. Regular Expression Conditions
Table 8.3. 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. Examples of Automembership Rules
- Different host groups based on IP address
- Windows user groups
- Different user groups based on employee ID
Example 8.4. Host Groups by IP Address

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.5. Windows User Group
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.
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.6. User Groups by Employee Type
employeeType
attribute.
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.3. Creating Automembership Definitions
- If necessary, enable the Auto Membership Plug-in. Using
ldapmodify
:dn: cn=Auto Membership Plugin,cn=plugins,cn=config changetype: replace replace: nsslapd-pluginEnabled nsslapd-pluginEnabled: on
- Create the new plug-in instance below the
cn=Auto Membership Plugin,cn=plugins,cn=config
container entry. This entry must belong to theautoMemberDefinition
object class. Usingldapmodify
:dn: cn=Example Automember Definition,cn=Auto Membership Plugin,cn=plugins,cn=config objectclass: autoMemberDefinition ...
The required attributes for the definition are listed in the Red Hat Directory Server Configuration, Command, and File Reference. - Set the scope and filter for the definition. This is used for the initial search for matching entries.For example, for new entries added to the
ou=People
subtree and containing thentUser
attribute:autoMemberScope: ou=People,dc=example,dc=com autoMemberFilter: objectclass=ntUser
- Set the group to which to add matching entries (as the default or fallback group) and the format of the member entries for that group type.
autoMemberDefaultGroup: cn=windows-group,cn=groups,dc=example,dc=com autoMemberGroupingAttr: member:dn
- Optional. Create inclusive or exclusive regular expression filters and set a group to use for entries matching those filters.The attributes for the regular expression condition are listed in Table 8.3, “Regular Expression Condition Attributes”.Regular expression conditions are added as children of the automember definition. These conditions must belong to the
autoMemberRegexRule
object class.Usingldapmodify
:dn: cn=Example Regex,cn=Example Automember Definition,cn=Auto Membership Plugin,cn=plugins,cn=config objectclass: autoMemberRegexRule ...
Then add the target group name and any inclusive or exclusive regular expressions. Both include and exclude conditions can be used, and multiple expressions of both types can be used.autoMemberTargetGroup: cn=windows-admin-group,cn=groups,dc=example,dc=com autoMemberInclusiveRegex: cn=\.* Administrator \*
If a new entry matches a regular expression condition, it is added to that group instead of the default group set in the automember definition. - If the Directory Server is not configured to enable dynamic plug-ins, restart the server to load the modified new plug-in instance.
8.1.5.4. Updating Existing Entries for Automembership Definitions
cn=automember rebuild membership
) requires three elements to run, based on LDAP search parameters to identify which existing entries to process:
- The search filter
- The search scope
- The base DN from which to begin the search
ldapmodify
; when the task completes, the entry is automatically removed. For example:
dn: cn=my rebuild task, cn=automember rebuild membership,cn=tasks,cn=config objectClass: top objectClass: extensibleObject cn: my rebuild task basedn: dc=example,dc=com filter: (uid=*) scope: sub
8.1.5.5. Testing Automembership Definitions
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.
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.
ldapmodify
:
dn: cn=test export, cn=automember export updates,cn=tasks,cn=config objectClass: top objectClass: extensibleObject cn: test export basedn: dc=example,dc=com filter: (uid=*) scope: sub ldif: /tmp/automember-updates.ldif
cn=automember map updates
takes an import LDIF of new users and then runs the new users against the current automembership rules. This can be very useful for testing a new rule, before applying it to (real) new or existing user entries.
ldapmodify
:
dn: cn=test mapping, cn=automember map updates,cn=tasks,cn=config objectClass: top objectClass: extensibleObject cn: test mapping ldif_in: /tmp/entries.ldif ldif_out: /tmp/automember-updates.ldif
8.2. Using Roles
8.2.1. About Roles
- Managed roles have an explicit enumerated list of members.
- Filtered roles are assigned entries to the role depending upon the attribute contained by each entry, specified in an LDAP filter. Entries that match the filter possess the role.
- Nested roles are roles that contain other roles.
Note
nsRole
attribute. The nsRole
attribute is a computed attribute, which identifies to which roles an entry belongs; the nsRole
attribute is not stored with the entry itself. From the client application point of view, the method for checking membership is uniform and is performed on the server side.
8.2.2. Creating a Managed Role
nsRoleDN
attribute to the entry.
8.2.2.1. Creating a Managed Role in the Console
- In the Directory Server Console, select the Directory tab.
- Browse the tree in the left navigation pane, and select the parent entry for the new role.
- Go to the Object menu, and select New > Role.Alternatively, right-click the entry and select New > Role.
- Click General in the left pane. Type a name for the new role in the Role Name field. The role name is required.
- Enter a description of the new role in the Description field.
- Click Members in the left pane.
- In the right pane, select Managed Role. Clickto add new entries to the list of members.
- In the Search drop-down list, select Users from the Search drop-down list, then click Search. Select one of the entries returned, and click .
- After adding all of the entries, click.
8.2.2.2. Creating Managed Roles through the Command Line
ldapsubentry
object class, which is defined in the ITU X.509 standard. In addition, each managed role requires two object classes that inherit from the nsRoleDefinition
object class:
- nsSimpleRoleDefinition
- nsManagedRoleDefinition
description
attribute.
nsRoleDN
attribute in their entry.
- Use
ldapmodify
with the-a
option to add the managed role entry. The new entry must contain thensManagedRoleDefinition
object class, which in turn inherits from theLdapSubEntry
,nsRoleDefinition
, andnsSimpleRoleDefinition
object classes.dn: cn=Marketing,ou=people,dc=example,dc=com objectclass: top objectclass: LdapSubEntry objectclass: nsRoleDefinition objectclass: nsSimpleRoleDefinition objectclass: nsManagedRoleDefinition cn: Marketing description: managed role for marketing staff
- Assign the role to the marketing staff members, one by one, using
ldapmodify
:dn: cn=Bob,ou=people,dc=example,dc=com changetype: modify add: nsRoleDN nsRoleDN: cn=Marketing,ou=people,dc=example,dc=com
ThensRoleDN
attribute in the entry indicates that the entry is a member of a managed role,cn=Marketing,ou=people,dc=example,dc=com
.
8.2.3. Creating a Filtered Role
8.2.3.1. Creating a Filtered Role in the Console
- In the Directory Server Console, select the Directory tab.
- Browse the tree in the left navigation pane, and select the parent entry for the new role.
- Go to the Object menu, and select New > Role.Alternatively, right-click the entry and select New > Role.
- Click General in the left pane. Type a name for the new role in the Role Name field. The role name is required.
- Enter a description of the new role in the Description field.
- Click Members in the left pane.A search dialog box appears briefly.
- In the right pane, select Filtered Role.
- Enter an LDAP filter in the text field, or clickto be guided through the construction of an LDAP filter.The LDAP Server Host, Port, Base DN, and Search (since the search scope cannot be set filtered role definitions).opens the standard LDAP URL construction dialog. Ignore the fields for
- Select the types of entries to filter from the For drop-down list. The entries can be users, groups, or both.
- Select an attribute from the Where drop-down list. The two fields following it refine the search by selecting one of the qualifiers from the drop-down list, such
as contains
,does not contain
,is
, oris not
. Enter an attribute value in the text box. To add additional filters, click . To remove unnecessary filters, click .
- Clickto try the filter.
- Click.
8.2.3.2. Creating a Filtered Role through the Command Line
ldapsubentry
object class, which is defined in the ITU X.509 standard. In addition, each filtered role requires two object classes that inherit from the nsRoleDefinition
object class:
- nsComplexRoleDefinition
- nsFilteredRoleDefinition
nsRoleFilter
attribute to define the LDAP filter to determine role members. Optionally, the role can take a description
attribute.
nsRoleFilter
attribute.
- Run
ldapmodify
with the-a
option to add a new entry. - Create the filtered role entry.The role entry has the
nsFilteredRoleDefinition
object class, which inherits from theLdapSubEntry
,nsRoleDefinition
, andnsComplexRoleDefinition
object classes.ThensRoleFilter
attribute sets a filter foro
(organization) attributes that contain a value ofsales managers
.dn: cn=SalesManagerFilter,ou=people,dc=example,dc=com changetype: add objectclass: top objectclass: LDAPsubentry objectclass: nsRoleDefinition objectclass: nsComplexRoleDefinition objectclass: nsFilteredRoleDefinition cn: SalesManagerFilter nsRoleFilter: o=sales managers Description: filtered role for sales managers
o
attribute with the value sales managers
), and, therefore, it is a member of this filtered role automatically:
dn: cn=Pat Smith,ou=people,dc=example,dc=com objectclass: person cn: Pat sn: Smith userPassword: secret o: sales managers
8.2.4. Creating a Nested Role
nsRoleDN
attribute.
8.2.4.1. Creating a Nested Role in the Console
- In the Directory Server Console, select the Directory tab.
- Browse the tree in the left navigation pane, and select the parent entry for the new role.
- Go to the Object menu, and select New > Role.Alternatively, right-click the entry and select New > Role.
- Click General in the left pane. Type a name for the new role in the Role Name field. The role name is required.
- Click Members in the left pane.
- In the right pane, select Nested Role.
- Clickto add roles to the list. The members of the nested role are members of other existing roles.
- Select a role from the Available roles list, and click .
8.2.4.2. Creating Nested Role through the Command Line
ldapsubentry
object class, which is defined in the ITU X.509 standard. In addition, each nested role requires two object classes that inherit from the nsRoleDefinition
object class:
- nsComplexRoleDefinition
- nsNestedRoleDefinition
nsRoleDN
attribute to identify the roles to nest within the container role. Optionally, the role can take a description
attribute.
nsRoleDN
attributes of the nested role definition entry.
- Run
ldapmodify
with the-a
option to add a new entry. - Create the nested role entry. The nested role has four object classes:
nsNestedRoleDefinition
LDAPsubentry
(inherited)nsRoleDefinition
(inherited)nsComplexRoleDefinition
(inherited)
ThensRoleDN
attributes contain the DNs for both the marketing managed role and the sales managers filtered role.dn: cn=MarketingSales,ou=people,dc=example,dc=com objectclass: top objectclass: LDAPsubentry objectclass: nsRoleDefinition objectclass: nsComplexRoleDefinition objectclass: nsNestedRoleDefinition cn: MarketingSales nsRoleDN: cn=SalesManagerFilter,ou=people,dc=example,dc=com nsRoleDN: cn=Marketing,ou=people,dc=example,dc=com
8.2.5. Editing and Assigning Roles to an Entry
- Select the Directory tab.
- In the left navigation pane, browse the tree, and select the entry for which to view or edit a role.
- Select Set Roles from the Object menu.
- Select the Managed Roles tab to display the managed roles to which this entry belongs.
- To add a new managed role, click Role Selector window., and select an available role from the
Note
The configuration for a managed role associated with an entry can be edited by clicking the Edit Entry dialog box opens, and the general information or members for the role can be changed.button. The - Select the Other Roles tab to view the filtered or nested roles to which this entry belongs.Clickto make changes to any filtered or nested roles associated with the entry.
8.2.6. Viewing Roles for an Entry through the Command Line
+
to output all operational attributes for result objects. For example, this ldapsearch
command returns the list of roles of which uid=scarter
is a member, in addition to the regular attributes for the entry:
# ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com -b "dc=example,dc=com" -s sub -x "(uid=scarter)"\* nsRole
dn: uid=scarter,ou=people,dc=example,dc=com objectClass: inetorgperson objectClass: top objectClass: person objectClass: organizationalPerson uid: scarter cn: Sam Carter sn: Carter givenName: Sam mail: scarter@example.com userPassword: {SSHA}6BE31mhTfcYyIQF60kWlnEL8sIvPZ59hvFTRKw== manager: uid=lbrown,ou=people,dc=example,dc=comnsRole: cn=Role for Managers,dc=example,dc=com
nsRole: cn=Role for Accounting,dc=example,dc=com
Important
nsRole
attribute, not the nsRoleDN
attribute, to evaluate role membership.
8.2.7. Making a Role Inactive or Active
nsAccountLock
attribute set to true
.
- Select the Directory tab.
- Browse the navigation tree in the left pane to locate the base DN for the role. Roles appear in the right pane with other entries.
- Double-click the role, open the Account tab, and click the Inactivate button.Alternatively, select the role. Right-click the role and select Inactivate from the menu.
8.2.8. Viewing the Activation Status for Entries
nsAccountLock
set to true
. There can be several layers of nested roles, and inactivating a nested role at any point in the nesting will inactivate all roles and users beneath it.

nsAccountLock
attribute is an operational attribute and must be explicitly requested in the search command in the list of search attributes or specify +
to request all operational attributes. For example:
# ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com -b "dc=example,dc=com" -s sub -x "(uid=scarter)" nsAccountLock
8.2.9. About Deleting Roles
nsRoleDN
attribute for each role member. To delete the nsRoleDN
attribute for each role member, enable the Referential Integrity plug-in, and configure it to manage the nsRoleDN
attribute. For more information on the Referential Integrity plug-in, see Chapter 5, Maintaining Referential Integrity.
8.2.10. Using Roles Securely
Mountain Biking
, interested users should be able to add themselves or remove themselves easily.
MR
. The MR
role has been locked using account inactivation. This means that user A cannot bind to the server because the nsAccountLock
attribute is computed as true
for that user. However, if user A was already bound to Directory Server and noticed that he is now locked through the MR role, the user can remove the nsRoleDN
attribute from his entry and unlock himself if there are no ACIs preventing him.
nsRoleDN
attribute, use the following ACIs depending upon the type of role being used.
- Managed roles. For entries that are members of a managed role, use the following ACI to prevent users from unlocking themselves by removing the appropriate
nsRoleDN
:aci: (targetattr="nsRoleDN") (targattrfilters= add=nsRoleDN:(!(nsRoleDN=cn=AdministratorRole,dc=example,dc=com)), del=nsRoleDN:(!(nsRoleDN=cn=nsManagedDisabledRole,dc=example,dc=com))) (version3.0;acl "allow mod of nsRoleDN by self but not to critical values"; allow(write) userdn=ldap:///self;)
- Filtered roles. The attributes that are part of the filter should be protected so that the user cannot relinquish the filtered role by modifying an attribute. The user should not be allowed to add, delete, or modify the attribute used by the filtered role. If the value of the filter attribute is computed, then all attributes that can modify the value of the filter attribute should be protected in the same way.
- Nested roles. A nested role is comprised of filtered and managed roles, so both ACIs should be considered for modifying the attributes (
nsRoleDN
or something else) of the roles that comprise the nested role.
8.3. Automatically Creating Dual Entries
8.3.1. About Managed Entries
posixAccount
entry) is created, a corresponding group entry (posixGroup
entry) should also be created. An instance of the Managed Entries Plug-in identifies what entry (the origin entry) triggers the plug-in to automatically generate a new entry (the managed entry).
- A definition entry, that identifies the scope of the plug-in instance and the template to use
- A template entry, that models what the final managed entry will look like
8.3.1.1. About the Instance Definition Entry
cn=plugins,cn=config
, and each unique configuration instance of the plug-in has a definition entry beneath that container.
- The search criteria to identify the origin entries (using a search scope and a search filter)
- The subtree under which to create the managed entries (the new entry location)
- The template entry to use for the managed entries

Figure 8.2. Defining Managed Entries
dn: cn=Posix User-Group,cn=Managed Entries,cn=plugins,cn=config objectclass: extensibleObject cn: Posix User-Group originScope: ou=people,dc=example,dc=com originFilter: objectclass=posixAccount managedBase: ou=groups,dc=example,dc=com managedTemplate: cn=Posix User-Group Template,ou=Templates,dc=example,dc=com
8.3.1.2. About the Template Entry
Note

Figure 8.3. Templates, Managed Entries, and Origin Entries
dn: cn=Posix User-Group Template,ou=Templates,dc=example,dc=com objectclass: mepTemplateEntry cn: Posix User-Group Template mepRDNAttr: cn mepStaticAttr: objectclass: posixGroup mepMappedAttr: cn: $cn Group Entry mepMappedAttr: gidNumber: $gidNumber mepMappedAttr: memberUid: $uid
Attr: ${cn}test
. Quoting a token value is not required if the token name is not immediately followed by a character that is valid in an attribute name, such as a space or comma. For example, $cn test
is acceptable in an attribute definition because a space character immediately follow the attribute name, but $cntest
is not valid because the Managed Entries Plug-in attempts to look for an attribute named cntest
in the origin entry. Using curly braces identifies the attribute token name.
Note
8.3.1.3. Entry Attributes Written by the Managed Entries Plug-in
dn: uid=jsmith,ou=people,dc=example,dc=com objectclass: mepOriginEntry objectclass: posixAccount ... sn: Smith mail: jsmith@example.com mepManagedEntry: cn=jsmith Posix Group,ou=groups,dc=example,dc=com
dn: cn=jsmith Posix Group,ou=groups,dc=example,dc=com objectclass: mepManagedEntry objectclass: posixGroup ... mepManagedBy: uid=jsmith,ou=people,dc=example,dc=com
8.3.1.4. Managed Entries Plug-in and Directory Server Operations
Table 8.4. Managed Entries Plug-in and Directory Server Operations
Operation | Effect by the Managed Entries Plug-in |
---|---|
Add | With every add operation, the server checks to see if the new entry is within the scope of any Managed Entries Plug-in instance. If it meets the criteria for an origin entry, then a managed entry is created and managed entry-related attributes are added to both the origin and managed entry. |
Modify |
If an origin entry is modified, it triggers the plug-in to update the managed entry. Changing a template entry, however, does not update the managed entry automatically. Any changes to the template entry are not reflected in the managed entry until after the next time the origin entry is modified.
The mapped managed attributes within a managed entry cannot be modified manually, only by the Managed Entry Plug-in. Other attributes in the managed entry (including static attributes added by the Managed Entry Plug-in) can be modified manually.
|
Delete | If an origin entry is deleted, then the Managed Entries Plug-in will also delete any managed entry associated with that entry. There are some limits on what entries can be deleted.
|
Rename | If an origin entry is renamed, then plug-in updates the corresponding managed entry. If the entry is moved out of the plug-in scope, then the managed entry is deleted, while if an entry is moved into the plug-in scope, it is treated like an add operation and a new managed entry is created. As with delete operations, there are limits on what entries can be renamed or moved.
|
Replication | The Managed Entries Plug-in operations are not initiated by replication updates. If an add or modify operation for an entry in the plug-in scope is replicated to another replica, that operation does not trigger the Managed Entries Plug-in instance on the replica to create or update an entry. The only way for updates for managed entries to be replicated is to replicate the final managed entry over to the replica. |
8.3.2. Creating the Managed Entries Template Entry
mepStaticAttr: attribute: specific_value mepMappedAttr: attribute: $token_value
mepMappedAttr: cn: Managed Group for $cn
- A mapped value use a combination of token (dynamic values) and static values, but it can only use one token per mapped attribute.
- The mapped attributes in the template use tokens, prepended by a dollar sign ($), to pull in values from the origin entry and use it in the managed entry. (If a dollar sign is actually in the managed attribute value, then the dollar sign can be escaped by using two dollar signs in a row.)
- A mapped attribute definition can be quoted with curly braces, such as
Attr: ${cn}test
. Quoting a token value is not required if the token name is not immediately followed by a character that is valid in an attribute name, such as a space or comma. For example,$cn test
is acceptable in an attribute definition because a space character immediately follow the attribute name, but$cntest
is not valid because the Managed Entries Plug-in attempts to look for an attribute namedcntest
in the origin entry. Using curly braces identifies the attribute token name. - Make sure that the values given for static and mapped attributes comply with the required attribute syntax.
Note
gidNumber
, then the mapped value should be an integer.
Table 8.5. Attributes for the Managed Entry Template
Attribute | Description |
---|---|
mepTemplateEntry (object class) | Identifies the entry as a template. |
cn | Gives the common name of the entry. |
mepMappedAttr | Contains an attribute-token pair that the plug-in uses to create an attribute in the managed entry with a value taken from the originating entry. |
mepRDNAttr | Specifies which attribute to use as the naming attribute in the managed entry. The attribute used as the RDN must be a mapped attribute for the configuration to be valid. |
mepStaticAttr | Contains an attribute-value pair that will be used, with that specified value, in the managed entry. |
- Run
ldapmodify
to add the entry. This entry can be located anywhere in the directory tree.dn: cn=Posix User Template,ou=templates,dc=example,dc=com cn: Posix User Template ...
You can also use the Directory Server Console to create the entry, as described in Section 3.2.2, “Creating Directory Entries”. - Give it the
mepTemplateEntry
object class to indicate that it is a template entry.objectClass: top objectclass: mepTemplateEntry ...
- Set the attributes for the entry; these are described in Table 8.5, “Attributes for the Managed Entry Template”. The RDN attribute (
mepRDNAttr
) is required. The attribute parameters are optional and the values depend on the type of entry that the plug-in will create. Make sure that whatever attribute you use for the naming attribute is also contained in the template entry as a mapped attribute.Note
Attributes which will be the same for each managed entry — like the object class for the entries — should use themepStaticAttr
attribute to set the values manually.mepRDNAttr: cn mepStaticAttr: objectclass: posixGroup mepMappedAttr: cn: $cn Group Entry mepMappedAttr: gidNumber: $gidNumber mepMappedAttr: memberUid: $uid
8.3.3. Creating the Managed Entries Instance Definition
Note
Table 8.6. Attributes for the Managed Entries Definition Entry
Attribute Name | Description |
---|---|
originFilter | The search filter to use to search for and identify the entries within the subtree which require a managed entry. The syntax is the same as a regular search filter. |
originScope | The base subtree which contains the potential origin entries for the plug-in to monitor. |
managedTemplate | Identifies the template entry to use to create the managed entry. This entry can be located anywhere in the directory tree. |
managedBase | The subtree under which to create the managed entries. |
Note
- Create the new plug-in instance below the
cn=Managed Entries,cn=plugins,cn=config
container entry usingldapmodify
.dn: cn=instance,cn=Managed Entries,cn=plugins,cn=config ...
- Set the scope and filter for the origin entry search, the location of the new managed entries, and the template entry to use. These required attributes are listed in Table 8.6, “Attributes for the Managed Entries Definition Entry”.
objectClass: top objectClass: extensibleObject cn: Posix User-Group originScope: ou=people,dc=example,dc=com originFilter: objectclass=posixAccount managedBase: ou=groups,dc=example,dc=com managedTemplate: cn=Posix User-Group Template,ou=Templates,dc=example,dc=com
- If the Directory Server is not configured to enable dynamic plug-ins, restart the server to load the modified new plug-in instance.
8.3.4. Putting Managed Entries Plug-in Configuration in a Replicated Database
cn=plugins,cn=com
. (This is common for plug-ins which allow multiple instances.) The drawback to this is that the configuration entries in cn=plugins,cn=com
are not replicated, so the configuration has to be re-created on each Directory Server instance.
nsslapd-pluginConfigArea
attribute. This attribute to another container entry, in the main database area, which contains the plug-in instance entries. This container entry can be in a replicated database, which allows the plug-in configuration to be replicated.
- Using
ldapmodify
, create a container entry in a subtree that is replicated.dn: cn=managed entries container,ou=containers,dc=example,dc=com objectclass: top objectClass: extensibleObject objectClass: nsContainer cn: managed entries container
- Using
ldapmodify
, add thensslapd-pluginConfigArea
attribute to the Managed Entries Plug-in entry that points back to the container entry.dn: cn=Managed Entries,cn=plugins,cn=config changetype: modify add: nsslapd-pluginConfigArea nsslapd-pluginConfigArea: cn=managed entries container,ou=containers,dc=example,dc=com
- Move or create the definition (Section 8.3.3, “Creating the Managed Entries Instance Definition”) and template (Section 8.3.2, “Creating the Managed Entries Template Entry”) entries under the new container entry.
8.4. Using Views
8.4.1. About Views
nsview
) and a filter attribute (nsviewfilter
) that set up a filter for the entries which belong in that view. Once the view container entry is added, all of the entries that match the view filter instantly populate the view. The target entries only appear to exist in the view; their true location never changes. For example, a view may be created as ou=Location Views
, and a filter is set for l=Mountain View
. Every entry, such as cn=Jane Smith,l=Mountain View,ou=People,dc=example,dc=com
, is immediately listed under the ou=Location Views
entry, but the real cn=Jane Smith
entry remains in the ou=People,dc=example,dc=com
subtree.

Figure 8.4. A Directory Tree with a Virtual DIT View hierarchy
Note
Example-views.ldif
, installed with Directory Server. This file is in the /usr/share/dirsrv/data/
directory on Red Hat Enterprise Linux 7. The sections in this chapter assume Example-views.ldif
is imported to the server.
8.4.2. Creating Views in the Console
- Select the Directory tab.
- In the left navigation tree, create an organizational unit suffix to hold the views. For instance, for views based on the locality (
l
) attribute, name this organizational unitLocation Views
. Creating sub suffixes is described in Section 2.1.1.2, “Creating a New Sub Suffix Using the Console”. - Right-click
ou=Location Views
, and select New > Other. - Select
nsview
from the New Object menu, and click . - In the Property Editor window, click the button, and add the organization unit object class.
- Name the organization unit according to how to organize the views. For instance,
ou=Sunnyvale
. Make theou
attribute the naming attribute. - Click thebutton, and add the
nsviewfilter
attribute. - Create a filter that reflects the views, such as
(l=Sunnyvale)
. - Click thebutton in the lower right corner to change the naming attribute.Use the
ou
of the entry as the naming attribute instead ofdescription
. - Clickto close the attributes box, and click again to save the new view entry.
8.4.3. Creating Views from the Command Line
- Use the
ldapmodify
utility to bind to the server and prepare it to add the new view entry to the configuration file. - Assuming the view container
ou=Location Views,dc=example,dc=com
from theExample-views.ldif
file is in the Directory Server, add the new views container entry, in this example, under thedc=example,dc=com
root suffix. This entry must have thensview
object class and thensViewFilter
attribute. ThensViewFilter
attribute sets the attribute-value which identifies entries that belong in the view.dn: ou=Mountain View,ou=Location Views,dc=example,dc=com changetype: add objectClass: top objectClass: organizationalUnit objectClass: nsview ou: Mountain View nsViewFilter: l=Mountain View description: views categorized by location
8.4.4. Improving Views Performance
nsViewFilter
attribute; the rest of the filter is based on the entry hierarchy, looking for the entryid
and parentid
of the real entries included in the view.
(|(parentid=search_base_id)(entryid=search_base_id)
entryid
, parentid
, or the attribute set in nsViewFilter
— are not indexed, then the views search becomes an unindexed search because the views operation searches the entire tree for matching entries.
entryid
, parentid
, and the attribute set in nsViewFilter
.
Chapter 9. Configuring Secure Connections
StartTLS
connection, and SASL authentication, which provide layers of encryption and security that protect directory data from being read even if it is intercepted.
9.1. Requiring Secure Connections
- LDAPS
- When you use the LDAPS protocol, the connection starts using encryption and either succeeds or fails. However, no unencrypted data is ever send over the network. For this reason, prefer LDAPS instead of using
StartTLS
over unencrypted LDAP. StartTLS
over LDAP- Clients establish an unencrypted connection over the LDAP protocol and then send the
StartTLS
command. If the command succeeds, all further communication is encrypted.Warning
If theStartTLS
command fails and the client does not cancel the connection, all further data, including authentication information, is sent unencrypted over the network. - SASL
- Simple Authentication and Security Layer (SASL) enables you to authenticate a user using external authentication methods, such as Kerberos. For details, see Section 9.9, “Setting up SASL Identity Mapping”.
9.2. Setting a Minimum Strength Factor
nsslapd-minssf
configuration attribute. When enforcing a minimum SSF, Directory Server looks at each available encryption type for an operation — TLS or SASL — and determines which has the higher SSF value and then compares the higher value to the minimum SSF. It is possible for both SASL authentication and TLS to be configured for some server-to-server connections, such as replication.
Note
nsslapd-minssf-exclude-rootdse
configuration attribute. This sets a minimum SSF setting for all connections to the Directory Server except for queries against the root DSE. A client may need to obtain information about the server configuration, like its default naming context, before initiating an operation. The nsslapd-minssf-exclude-rootdse
attribute allows the client to get that information without having to establish a secure connection first.
StartTLS
and SASL binds to succeed, even though those two connections initially open a regular connection. After the TLS or SASL session is opened, then the SSF is evaluated. Any connection which does not meet the SSF requirements is closed with an LDAP unwilling to perform error.
Warning
nsslapd-minssf
attribute value is 0, which means there is no minimum SSF for server connections. The value can be set to any reasonable positive integer. The value represents the required key strength for any secure connection.
nsslapd-minssf
attribute to the cn=config
entry:
#
ldapmodify -D "cn=Directory Manager" -W -x
dn: cn=config changetype: modify replace: nsslapd-minssf nsslapd-minssf: 128
Note
nsslapd-require-secure-binds
attribute, as in Section 19.11.1, “Requiring Secure Binds”.
9.3. Managing the NSS Database Used by Directory Server
9.3.1. Creating the NSS Database for a Directory Server Instance
/etc/dirsrv/slapd-instance_name/
directory. Before you can manage the certificates, you must create the database.
Note
9.3.1.1. Creating the NSS Database Using the Command Line
- Create the NSS database and set a password:
# certutil -d /etc/dirsrv/slapd-instance_name/ -N Enter a password which will be used to encrypt your keys. The password should be at least 8 characters long, and should contain at least one non-alphabetic character. Enter new password: Re-enter password:
- Set the permissions:
# chown dirsrv:dirsrv /etc/dirsrv/slapd-instance_name/*.db # chown dirsrv:dirsrv /etc/dirsrv/slapd-instance_name/pkcs11.txt # chmod 600 /etc/dirsrv/slapd-instance_name/*.db # chmod 600 /etc/dirsrv/slapd-instance_name/pkcs11.txt
9.3.1.2. Creating the NSS Database Using the Console
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates, and set a password to protect the database.
9.3.2. Creating a Certificate Signing Request
9.3.2.1. Creating a Certificate Signing Request Using the Command Line
certutil
utility:
# certutil -d instance_directory -R -g key_size -a \ -o output_file -8 FQDN -s "certificate_subject"
Example 9.1. Creating a Private Key and CSR for a Single Host Name
server.example.com
host and stores the CSR in the /root/instance_name.csr
file:
# certutil -d /etc/dirsrv/slapd-instance_name/ -R -g 4096 -a \ -o /root/instance_name.csr -8 server.example.com \ -s "CN=server.example.com,O=example_organization,OU=IT,ST=North Carolina,C=US"
-8 server.example.com
option adds the subject alternative name (SAN) extension with the DNS:server.example.com
entry to the CSR. The string specified in the -s
parameter must be a valid subject name according to RFC 1485. The CN
field is required, and you must set it to the Fully Qualified Domain Name (FQDN) of the server. The other fields are optional.
Example 9.2. Creating a Private Key and CSR for a Multi-homed Host
server.example.com
and server.example.net
host names. The command stores the CSR in the /root/instance_name.csr
file.
# certutil -d /etc/dirsrv/slapd-instance_name/ -R -g 4096 -a \ -o /root/instance_name.csr -8 server.example.com,server.example.net \ -s "CN=server.example.com,O=example_organization,OU=IT,ST=North Carolina,C=US"
-8 server.example.com,server.example.net
option adds the SAN extension with the DNS:server.example.com, DNS:server.example.net
entries to the CSR. The string specified in the -s
parameter must be a valid subject name according to RFC 1485. The CN
field is required, and you must set it to one of the FQDNs of the server. The other fields are optional.
certutil
and extended usage information, see the certutil(1) man page.
9.3.2.2. Creating a Certificate Signing Request Using the Console
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates.
- On the Server Certs tab, click the button.
- Select if you want to request the certificate manually or from one of the displayed CAs and click.
- Enter the requested information and click.
Important
Enter the Fully-qualified Domain Name (FQDN) of the server into the Server name field. - Select the key size and signing algorithm. Click.For security reasons:
- an RSA key size of
2048
bits or higher - a strong signing algorithm, such as
SHA-256
or higher
- Enter the password of the Network Security Services (NSS) database and click Done.If you use an Hardware Security Module (HSM) to store the certificates, the device is plugged in, and the module has been installed as described in Section 9.7, “Using Hardware Security Modules”, then the module is available in the Active Encryption Token menu.
- Copy the CSR to the clipboard or save it into a file.
- Click.
9.3.3. Installing a CA Certificate
Table 9.1. CA Trust Options
Console Option | certutil Option | Description |
---|---|---|
Accepting connections from clients (Client Authentication) | T,, | The server trusts this CA certificate for issuing client certificates suitable for TLS EXTERNAL binds. |
Accepting connections to other servers (Server Authentication) | C,, | The server verifies that certificates, used to establish an encrypted connection to a replication partner, have been issued by a trusted CA. |
certutil
, pass the -T "CT,,"
parameter to the utility.
9.3.3.1. Installing a CA Certificate Using the Command Line
certutil
utility. For example, to import the CA certificate stored in the /etc/pki/CA/nss/ca.crt
file:
# certutil -d /etc/dirsrv/slapd-instance_name/ -A -n "certificate_nickname" \ -t "C,," -i /etc/pki/CA/nss/ca.crt
-t trust_options
parameter sets which certificates issued by the CA should be trusted. See Table 9.1, “CA Trust Options”.
9.3.3.2. Installing a CA Certificate Using the Console
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates.
- Select the CA Certs tab and click the button.
- Either select the file that contains the server certificate or paste the certificate into the field. Click.
- Verify the certificate details and click.
- Verify the certificate nickname and click.
- Set which certificates issued by the CA should be trusted. You can select one or both of the options. See Table 9.1, “CA Trust Options”.
9.3.4. Installing a Certificate
9.3.4.1. Installing a Server Certificate Using the Command Line
certutil
utility. For example:
- Install the CA certificate. See Section 9.3.3, “Installing a CA Certificate”.
- Import the certificate. For example to import the certificate stored in the
/root/instance_name.crt
file:# certutil -d /etc/dirsrv/slapd-instance_name/ -A \ -n "server-cert" -t ",," -a -i /root/instance_name.crt
- Optionally, verify the certificate:
# certutil -d /etc/dirsrv/slapd-instance_name/ -V -n "server-cert" -u V
certutil
commands, see the certutil(1) man page.
9.3.4.2. Installing a Certificate Using the Console
- Install the CA certificate. See Section 9.3.3, “Installing a CA Certificate”.
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates.
- Click thebutton.
- Select the file that contains the server certificate or, alternatively, paste the certificate into the field. Click.
- Verify the certificate details and click.
- Set a certificate nickname and click.
Note
The Directory Server Console does not support installing a certificate that uses the same nickname as an existing one. To work around the problem, install the certificate using the command line. See Section 9.3.4.1, “Installing a Server Certificate Using the Command Line”. - Enter the password of the NSS database and click.
9.3.5. Generating and Installing a Self-signed Certificate
Note
- Verify if the Network Security Services (NSS) database is already initialized:
# certutil -d /etc/dirsrv/slapd-instance_name -L
If the command fails, initalize the database. For details, see Section 9.3.1, “Creating the NSS Database for a Directory Server Instance”. - Generate a noise file with random data. For example, to generate a file with a size of 4096 bits:
# openssl rand -out /tmp/noise.bin 4096
- Create the self-signed certificate and add it to the NSS database:
# certutil -S -x -d /etc/dirsrv/slapd-instance_name/ -z /tmp/noise.bin \ -n "server-cert" -s "CN=$HOSTNAME" -t "CT,C,C" -m $RANDOM \ --keyUsage digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment
Red Hat Enterprise Linux automatically replaces the$HOSTNAME
variable with the Fully Qualified Domain Name (FQDN) and$RANDOM
with a randomly-generated number. For further details about the parameters used in the previous commands, see the certutil(1) man page. - Optionally, verify that the generated certificate is self-signed:
# certutil -L -d /etc/dirsrv/slapd-instance_name/ -n "server-cert" | egrep "Issuer|Subject" Issuer: "CN=server.example.com" Subject: "CN=server.example.com"
The output of this command must display the FQDN of the Directory Server host for both the issuer and subject of the certificate.
9.3.6. Renewing a Certificate
9.3.6.1. Renewing a Certificate Using the Command Line
- Create a new Certificate Signing Request (CSR) with the same options, such as key size, host name, and subject. For details about creating a CSR, see Section 9.3.2.1, “Creating a Certificate Signing Request Using the Command Line”
- After you received the issued certificate from your CA, install it in the database using the same nickname. See Section 9.3.3.1, “Installing a CA Certificate Using the Command Line”.
9.3.6.2. Renewing a Certificate Using the Console
9.3.7. Removing a Certificate
9.3.7.1. Removing a Certificate Using the Command Line
- Remove the private key. See Section 9.3.8, “Removing a Private Key”.
- Optionally, display the certificates in the database:
# certutil -d /etc/dirsrv/slapd-instance_name/ -L Certificate Nickname Trust Attributes SSL,S/MIME,JAR/XPI Example CA CT,, server-cert u,u,u
- Remove the certificate. For example, to remove the certificate with the server-cert nickname:
# certutil -d /etc/dirsrv/slapd-instance_name/ -D -n "server-cert"
9.3.7.2. Removing a Certificate Using the Console
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates.
- On the Server Certs tab, select the certificate and click the button.
- Clickto confirm.
9.3.8. Removing a Private Key
Warning
9.3.8.1. Removing a Private Key Using the Command Line
- Remove all certificates based on the key you want to delete. See Section 9.3.7, “Removing a Certificate”.
- Optionally, display the keys in the database:
# certutil -d /etc/dirsrv/slapd-instance_name/ -K certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate Services" Enter Password or Pin for "NSS Certificate DB": < 0> rsa 7a2fb6c269d83c4036eac7e4edb6aaf2ed08bc4a server-cert < 1> rsa 662b826aa3dd4ca7fd7e6883558cf3866c42f4e2 example-cert
- Remove the private key. For example, to remove the private key with the example-cert nickname:
# certutil -d /etc/dirsrv/slapd-instance_name/ -F -n "example-cert"
9.3.8.2. Removing a Private Key Using the Console
9.3.9. Changing the CA Trust Options
9.3.9.1. Changing the CA Trust Options Using the Command Line
-t
parameter to the certutil
utility.
example-CA
:
# certutil -d /etc/dirsrv/slapd-instance_name/ -M -t "T,," -n "example-CA"
-t trust_options
parameter sets which certificates issued by the CA should be trusted. See Table 9.1, “CA Trust Options”.
9.3.9.2. Changing the CA Trust Options Using the Console
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates.
- Select the CA Certs tab.
- Select the CA to edit, click the Table 9.1, “CA Trust Options”.button, and set which certificates issued by the CA should be trusted. You can select one or both of the options. See
9.3.10. Changing the Password of the NSS Database
Important
9.3.10.1. Changing the Password of the NSS Database Using the Command Line
# certutil -d /etc/dirsrv/slapd-instance_name -W Enter Password or Pin for "NSS Certificate DB": Enter a password which will be used to encrypt your keys. The password should be at least 8 characters long, and should contain at least one non-alphabetic character. Enter new password: Re-enter password: Password changed successfully.
9.3.10.2. Changing the Password of the NSS Database Using the Console
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates.
- Click the Change Password button.
- Enter the current and the new password and click
9.3.11. Adding a Certificate Revocation List
9.3.11.1. Adding a Certificate Revocation List Using the Command Line
certutil
, pass the -4 URL_to_CRL_file
parameter to the utility when you install the CA certificate.
9.3.11.2. Adding a Certificate Revocation List Using the Console
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates.
- Select the Revoked Certs tab and click the button.
- Enter the path to the file, select the list format, and click.
9.4. Enabling TLS
- The LDAPS protocol: TLS encryption is used directly after the connection has been established.
- The
STARTTLS
command over the LDAP protocol: The connection is unencrypted until the client sends theSTARTTLS
command.
Important
9.4.1. Enabling TLS in Directory Server
9.4.1.1. Enabling TLS in Directory Server Using the Command Line
- Verify if the NSS database for Directory Server already exists:
# ls -1 /etc/dirsrv/slapd-instance_name/*.db
Create the databases if they do not exist. See Section 9.3.1.1, “Creating the NSS Database Using the Command Line”. - Request and install the certificate:
- For a certificate issued by a Certificate Authority (CA):
- Create a Certificate Signing Request (CSR). See Section 9.3.2.1, “Creating a Certificate Signing Request Using the Command Line”
- Import the CA certificate. See Section 9.3.3.1, “Installing a CA Certificate Using the Command Line”.
- Import the server certificate issued by the CA. See Section 9.3.4.1, “Installing a Server Certificate Using the Command Line”.
- For a self-signed certificate, see Section 9.3.5, “Generating and Installing a Self-signed Certificate”.
- Enable TLS and set the LDAPS port:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=config changetype: modify replace: nsslapd-securePort nsslapd-securePort: 636 - replace: nsslapd-security nsslapd-security: on
- Display the nickname of the server certificate in the NSS database:
# certutil -L -d /etc/dirsrv/slapd-instance_name/ Certificate Nickname Trust Attributes SSL,S/MIME,JAR/XPI Example CA CT,, server-cert u,u,u
You need the nickname in the next step. - To enable the RSA cipher family, setting the NSS database security device, and the server certificate nickname, add the following entry to the directory:
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=RSA,cn=encryption,cn=config cn: RSA objectClass: top objectClass: nsEncryptionModule nsSSLToken: internal (software) nsSSLPersonalitySSL: server-cert nsSSLActivation: on
Note
By default, the name of the security device in the NSS database isinternal (software)
.If the previous command fails, because thecn=RSA,cn=encryption,cn=config
entry already exists, update the corresponding attributes:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=RSA,cn=encryption,cn=config changetype: modify replace: nsSSLToken nsSSLToken: internal (software) - replace: nsSSLPersonalitySSL nsSSLPersonalitySSL: server-cert - replace: nsSSLActivation nsSSLActivation: on
- Optionally, update the list of ciphers Directory Server supports. For details, see Section 9.4.1.3.1, “Displaying and Setting the Ciphers Used by Directory Server Using the Command Line”.
- Optionally, enable certificate-based authentication. For details, see Section 9.8, “Using Certificate-based Client Authentication”.
- Optionally, create a password file to enable Directory Server to start without prompting for the password of the NSS database. For details, see Section 9.4.1.5, “Creating a Password File for Directory Server”.
- Restart the Directory Server instance:
# systemctl restart dirsrv@instance_name
If you set a password on the NSS database and did not create a password file, Directory Server prompts for the password of the NSS database. For details, see Section 9.4.1.4, “Starting Directory Server Without a Password File”. - Optionally, enable the Directory Server Console to use TLS when connecting to the server. See Section 9.4.2.1, “Enabling TLS for Connections from the Console to Directory Server Using the Command Line”.
- Optionally, enable TLS for the Red Hat Identity Management Console to use TLS. See Section 9.4.3, “Enabling TLS in the Administration Server”.
9.4.1.2. Enabling TLS in Directory Server Using the Console
- Create a CSR. See Section 9.3.2.2, “Creating a Certificate Signing Request Using the Console”.
- Import the Certificate Authority (CA) certificate. See Section 9.3.3.2, “Installing a CA Certificate Using the Console”.
- Import the server certificate issued by the CA. See Section 9.3.4.2, “Installing a Certificate Using the Console”.
- Open the Directory Server Console and select the host name on the Configuration tab.
- On the Settings tab in the right pane, enter the LDAPS port into the Encrypted port field and click the button.The default port for LDAPS is
636
.Note
The LDAPS port must be different to the one set for unencrypted connections in the Port field. - On the Encryption tab in the right pane:
- Select Enable SSL for this server.
- Enable Use this cipher family: RSA, select the security device and certificate from the list.
- button to update the list of ciphers Directory Server supports. For details, see
- Optionally, enable users to authenticate using certificates. For details, see Section 9.8, “Using Certificate-based Client Authentication”.
Important
If TLS is only enabled in Directory Server and not in the Directory Server Console, do not select Require client authentication. - Select the Check host name against name in certificate for outbound SSL connections option to verify that the host name matches the
cn
attribute in the subject name of the certificate the client presents to the server for authentication.Important
Red Hat recommends enabling this option in a replication environment to protect outgoing TLS connections against a man-in-the-middle attack (MITM). - Make sure that the Use SSL in Console option is not selected.
Warning
Do not enable the Use SSL in Console option before you finished this procedure, because it takes effect immediately after you save the setting. As a consequence, the Console fails to connect to the server.If you accidentally enabled this option and the Console fails to connect to the server, disable the option using the command line:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=slapd-instance_name,cn=Red Hat Directory Server, cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot changetype: modify replace: nsServerSecurity nsServerSecurity: off
- Click.
- Optionally, create a password file to enable Directory Server to start without prompting for the password of the NSS database. For details, see Section 9.4.1.5, “Creating a Password File for Directory Server”.
- Restart the Directory Server instance:
# systemctl restart dirsrv@instance_name
If you set a password on the NSS database and did not create a password file, Directory Server prompts for the password of the NSS database. For details, see Section 9.4.1.4, “Starting Directory Server Without a Password File”. - Optionally, enable the Directory Server Console to use TLS when connecting to the server. See Section 9.4.2.2, “Enabling TLS for Connections from the Console to Directory Server Using the Console”.
- Optionally, enable that the Red Hat Identity Management Console uses TLS. See Section 9.4.3, “Enabling TLS in the Administration Server”.
9.4.1.3. Setting Encryption Ciphers
9.4.1.3.1. Displaying and Setting the Ciphers Used by Directory Server Using the Command Line
Displaying all Available Ciphers
# ldapsearch -xLLL -H ldap://server.example.com:389 -D "cn=Directory Manager" -W \ -b 'cn=encryption,cn=config' -s base nsSSLSupportedCiphers -o ldif-wrap=no dn: cn=encryption,cn=config nsSSLSupportedCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256::AES-GCM::AEAD::128 ... nsSSLSupportedCiphers: SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5::RC2::MD5::128
Displaying the Ciphers Directory Server Uses
nsSSLEnabledCiphers
read-only attribute. To display them:
# ldapsearch -xLLL -H ldap://server.example.com:389 -D "cn=Directory Manager" -W \ -b 'cn=encryption,cn=config' -s base nsSSLEnabledCiphers -o ldif-wrap=no dn: cn=encryption,cn=config nsSSLEnabledCiphers: TLS_RSA_WITH_AES_256_CBC_SHA::AES::SHA1::256 nsSSLEnabledCiphers: TLS_RSA_WITH_AES_128_CBC_SHA::AES::SHA1::128 ...
# ldapsearch -xLLL -H ldap://server.example.com:389 -D "cn=Directory Manager" -W \ -b 'cn=encryption,cn=config' -s base nsSSL3Ciphers -o ldif-wrap=no dn: cn=encryption,cn=config nsSSL3Ciphers: -all,+tls_rsa_aes_128_sha,+tls_rsa_aes_256_sha,...
Important
nsSSL3Ciphers
attribute to generate the list of ciphers which are actually used. However, if you enabled weak ciphers in nsSSL3Ciphers
, but set the allowWeakCiphers
parameter to off
, which is the default, Directory Server only uses the strong ciphers and displays them in the nsSSLSupportedCiphers
read-only attribute.
Updating the List of Enabled Ciphers
- Display the list of currently enabled ciphers. See the section called “Displaying the Ciphers Directory Server Uses”.
- To enable only specific ciphers, update the
nsSSL3Ciphers
attribute. For example, to enable only theTLS_RSA_WITH_AES_128_GCM_SHA256
cipher:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=encryption,cn=config changetype: modify add: nsSSL3Ciphers nsSSL3Ciphers: -all,+TLS_RSA_WITH_AES_128_GCM_SHA256
- Restart the Directory Server instance:
# systemctl restart dirsrv@instance_name
- Optionally, display the list of enabled ciphers to verify the result. See the section called “Displaying the Ciphers Directory Server Uses”.
9.4.1.3.2. Displaying and Setting the Ciphers Used by Directory Server Using the Console
- Open the Directory Server Console.
- On the Configuration tab, select the server name.
- Select the Encryption tab in the right pane and click the button.
- Optionally, update the list of ciphers. For example:
- Click.
- Click.
- If you updated the list of ciphers, restart the Directory Server instance:
# systemctl restart dirsrv@instance_name
9.4.1.4. Starting Directory Server Without a Password File
- If the
ns-slapd
Directory Server process is started by thesystemctl
command,systemd
prompts for the password and automatically passes the input to thesystemd-tty-ask-password-agent
utility. For example:# systemctl start dirsrv Enter PIN for Internal (Software) Token:
- In rare cases, when the
ns-slapd
Directory Server process is not started by thesystemctl
utility and is detached from the terminal, a message is send to all terminals using thewall
command. For example:Broadcast message from root@server (Fri 2017-01-01 06:00:00 CET): Password entry required for 'Enter PIN for Internal (Software) Token:' (PID 1234). Please enter password with the systemd-tty-ask-password-agent tool!
To enter the password, run:# systemd-tty-ask-password-agent Enter PIN for Internal (Software) Token:
9.4.1.5. Creating a Password File for Directory Server
/etc/dirsrv/slapd-instance_name/pin.txt
file. This enables Directory Server to start automatically without prompting for this password.
Warning
- Create the
/etc/dirsrv/slapd-instance_name/pin.txt
file with the following content:- If you use the NSS software cryptography module, which is the default:
Internal (Software) Token:password
- If you use a Hardware Security Module (HSM):
name_of_the_token:password
- Set the permissions:
# chown dirsrv:dirsrv /etc/dirsrv/slapd-instance_name/pin.txt # chmod 400 /etc/dirsrv/slapd-instance_name/pin.txt
9.4.1.6. Managing How Directory Server Behaves If the Certificate Has Been Expired
nsslapd-validate-cert
attribute in the cn=config
entry. You can set it to the following values:
warn
: The Directory Server instance starts and log a warning about the expired certificate into the/var/log/dirsrv/slapd-instance_name/error
log file. This is the default setting.on
: Directory Server validates the certificate and the instance fails to start if the certificate has expired.off
: Directory Server does not validate the certificate expiration date. The instance starts and no warning will be logged.
Example 9.3. Preventing Directory Server to Start If the Certificate Has Been Expired
- Set the
nsslapd-validate-cert
attribute toon
:# ldapmodify -D "cn=Directory Manager" -W -p 636 -h server.example.com -x dn: cn=config changetype: modify replace: nsslapd-validate-cert nsslapd-validate-cert: on
- Restart the Directory Server instance:
# systemctl restart dirsrv@instance_name
9.4.2. Enabling TLS for Connections from the Console to Directory Server
Important
9.4.2.1. Enabling TLS for Connections from the Console to Directory Server Using the Command Line
# ldapmodify -D "cn=Directory Manager" -W -p 636 -h server.example.com -x dn: cn=slapd-instance_name,cn=Red Hat Directory Server, cn=Server Group,cn=server.example.com,ou=example.com,o=NetscapeRoot changetype: modify replace: nsServerSecurity nsServerSecurity: on
9.4.2.2. Enabling TLS for Connections from the Console to Directory Server Using the Console
- Open the Directory Server Console and select the host name on the Configuration tab.
- On the Encryption tab in the right pane:
- Select Use SSL in the Console.
- Click
- Restart the Directory Server Console.
9.4.3. Enabling TLS in the Administration Server
- Enable the HTTPS protocol when connecting to the Red Hat Identity Management Console application
- Set that the Administration Server stores its data in the
o=NetscapeRoot
entry using an encrypted connection to Directory Server - Enable the Red Hat Identity Management Console application to use the LDAPS protocol to manage users and groups stored in the directory
Important
- Import the required certificates. Select one of the following ways:
- To use the same private key and certificate for the Administration Server as for Directory Server, see Section E.2.7.1.1, “Using the Directory Server Private Key and Certificate for the Admin Server”.
- To use a separate key and certificate for Administration Server, see:
Important
Perform the steps in the Manage Certificates menu of the Administration Server Console instead of the Directory Server Console.
The Administration Server and Directory Server must share at least one CA certificate to trust the other's non-shared certificates. - Open the Administration Server Console.
- On the Configuration tab, select the Administration Server entry in the left pane.
- Select the Encryption tab in the right pane to enable encryption for the Red Hat Identity Management Console:
- Select Enable SSL for this server.
- Enable Use this cipher family: RSA, select the security device and certificate from the list.
- Optionally, click thebutton to update the list of ciphers the Administration Server supports.
- Optionally, enable client authentication using certificates. For details, see Section 9.8, “Using Certificate-based Client Authentication”.
- Click.
- Select the Configuration DS tab in the right pane to configure that the Administration Server stores its data in the
o=NetscapeRoot
entry using the LDAP protocol:- Set the LDAPS port of the Directory Server instance that stores the
o=NetscapeRoot
entry. By default, LDAPS uses the636
port. - Select Secure Connection.
- Click.
- Select the User DS tab in the right pane to configure that the Red Hat Identity Management Console uses an encrypted connection to manage users and groups:
- Select Set User Directory and fill the fields. For encrypted connections, the Secure Connections option must be selected and the port port specified in the LDAP Host and Port field must support LDAPS.
- Click.
- Optionally, set the minimum and maximum TLS version for connections from the Console to the server in the
~/.redhat-idm-console/Console.version.Login.preferences
file. For example:sslVersionMin: TLS1.1 sslVersionMax: TLS1.2
- Optionally, create a password file to enable the Administration Server to start without prompting for the password of the Network Security Services (NSS) database. For details, see Section E.2.7.3, “Creating a Password File for the Administration Server”.
- Restart the Administration Server:
# systemctl restart dirsrv-admin
If you did not create a password file, the system prompts for the password of the NSS database. - To configure that the Console trusts the certificate, see Section 9.4.3.1, “Managing Certificates Used by the Directory Server Console”.
# redhat-idm-console -a https://server.example.com:9830
9.4.3.1. Managing Certificates Used by the Directory Server Console
/etc/dirsrv/slapd-instance_name/
directory. The Directory Server Console itself also uses certificates and keys for TLS connections; these certificates are stored in a separate database in the user's home directory. If the Directory Server Console is used to connect to multiple instances of Directory Server over TLS, then it is necessary to trust every CA which issued the certificates for every Directory Server instance.
Note
Importing a CA Certificate When Using the Console on Linux
/root/ca.crt
file to the database:
# certutil -d ~/.redhat-idm-console/ -A -n "Example CA" -t CT,, -a -i /root/ca.crt
Importing a CA Certificate When Using the Console on Windows
C:\ca.crt
file to the database:
> cd C:\Program Files\Red Hat Identity Management Console\ > certutil.exe -d "C:\Documents and Settings\user_name\.389-console\" -A -n "Example CA" -t CT,, -a -i C:\ca.crt
9.4.4. Adding the CA Certificate Used By Directory Server to the Trust Store of Red Hat Enterprise Linux
STARTTLS
command over LDAP, Directory Server uses this certificate to encrypt the connection. Client utilities use the CA certificate to verify if the server's certificate is valid. By default, these utilities cancel the connection if they do not trust the certificate of the server.
Example 9.4. Possible Connection Error If a Client Utility Does Not Use the CA Certificate
# ldapsearch -H ldaps://server.example.com:636 -D "cn=Directory Manager" -W -b "dc=example,dc=com" -x Enter LDAP Password: ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)
- If you do not have a local copy of the CA certificate used by Directory Server:
- List the certificates in the server's NSS database:
# certutil -d /etc/dirsrv/slapd-instance_name/ -L Certificate Nickname Trust Attributes SSL,S/MIME,JAR/XPI Example CA C,, server-cert u,u,u
- Use the nickname of the CA certificate in the NSS database to export the CA certificate:
# certutil -d /etc/dirsrv/slapd-instance_name/ -L -n "Example CA" -a > /tmp/ds-ca.crt
- Copy the CA certificate to the
/etc/pki/ca-trust/source/anchors/
directory. For example:# cp /tmp/ds-ca.crt /etc/pki/ca-trust/source/anchors/
- Rebuild the CA trust database:
# update-ca-trust
9.5. Displaying the Encryption Protocols Enabled in Directory Server
# ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com -x \ -s base -b 'cn=encryption,cn=config' sslVersionMin sslVersionMax dn: cn=encryption,cn=config sslVersionMin: TLS1.0 sslVersionMax: TLS1.2
sslVersionMin
and sslVersionMax
parameter control which encryption protocol versions Directory Server uses. By default, only TLS 1.0 and later versions of the protocol are enabled.
Important
SSL2
or SSL3
protocol versions.
9.6. Setting the Encryption Protocol Versions
sslVersionMin
and sslVersionMax
parameters to set which encryption protocols Directory Server uses.
Important
sslVersionMax
parameter, do not set this parameter. See Section 9.6.1, “Automatically Using the Strongest Protocol in the sslVersionMax
Parameter”.
- Update the
sslVersionMin
andsslVersionMax
parameters:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=encryption,cn=config changetype: modify replace: sslVersionMin sslVersionMin: TLS1.1 - replace: sslVersionMax sslVersionMax: TLS1.2
- Restart the Directory Server instance:
# systemctl restart dirsrv@instance_name
9.6.1. Automatically Using the Strongest Protocol in the sslVersionMax
Parameter
sslVersionMax
parameter is not set, which is the default, Directory Server uses the strongest supported encryption protocol version for this parameter. This enables you to always have the strongest protocol version enabled after an update.
Identifying if sslVersionMax
is Not Set
sslVersionMax
is not set, the parameter is retur