Administration Guide
Basic and advanced administration of Directory Server
Abstract
Making Open Source More Inclusive
Chapter 1. General Directory Server Management Tasks
1.1. System Requirements
1.2. File Locations
1.3. Supported Methods to Configure Directory Server
- the command-line utilities provided by Directory Server
- the web console
Important
1.4. Logging Into Directory Server Using the Web Console
- Use a browser and connect to the web console running on port 9090 on the Directory Server host. For example:
https://server.example.com:9090
- Log in as the
root
user or as a user withsudo
privileges. - Select the
Red Hat Directory Server
entry.
1.5. Starting and Stopping a Directory Server Instance
1.5.1. Starting and Stopping a Directory Server Instance Using the Command Line
dsctl
utility to start, stop, or restart an instance:
- To start the instance:
# dsctl instance_name start
- To stop the instance:
# dsctl instance_name stop
- To restart the instance:
# dsctl instance_name restart
- For a single instance:
# systemctl enable dirsrv@instance_name
- For all instances on a server:
# systemctl enable dirsrv.target
1.5.2. Starting and Stopping a Directory Server Instance Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Click thebutton and select the action to execute:
- Start Instance
- Stop Instance
- Restart Instance
1.6. Creating a New Directory Server Instance
1.7. Removing a Directory Server Instance
/var/lib/dirsrv/slapd-instance_name/
and /etc/dirsrv/slapd-instance_name/
directories are removed.
Important
/var/lib/dirsrv/slapd-instance_name/
directory contains the database, as well as the backup and export directory. The /etc/dirsrv/slapd-instance_name/
directory contains the instance configuration and the network security services (NSS) database. Before you remove an instance, backup this data.
1.7.1. Removing an Instance Using the Command Line
# dsctl instance_name remove --do-it Removing instance ... Completed instance removal
1.7.2. Removing an Instance Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Click the Remove instance.button, and select
1.8. Setting Directory Server Configuration Parameters
cn=config
directory entry. Each configuration parameter is an LDAP attribute and the parameter's value is the value set in this attribute.
1.8.1. Managing Configuration Parameters
- Using the
dsconf
utility:Note
Red Hat recommends using thedsconf
utility to manage the Directory Server configuration.Example 1.1. Setting a Configuration Parameter Using
dsconf
For example, to set the error log level to16384
, update thensslapd-errorlog-level
parameter using thedsconf
utility:# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-errorlog-level=16384
For further details about usingdsconf
, see the dsconf(8) man page. - Using the LDAP interface:
Example 1.2. Setting a Configuration Parameter using the LDAP Interface
For example, to set the error log level to16384
, update thensslapd-errorlog-level
parameter using the LDAP interface:# ldapmodify -D "cn=Directory Manager" -W -x -H ldap://server.example.com:389 dn: cn=config replace: nsslapd-errorlog-level nsslapd-errorlog-level: 16384
- Editing the
/etc/dirsrv/slapd-instance_name/dse.ldif
file.Warning
As long as an instance starts successfully, do not manually edit this file because this can cause Directory Server to not work as expected, or the instance can fail to start.
1.8.2. Where Directory Server Stores its Configuration
cn=config
entry in the /etc/dirsrv/slapd-instance_name/dse.ldif
file. The server stores only parameters you modified in this file. Attributes that are not listed, use their default value. This enables you to identify all configuration parameters you set in this instance by displaying the /etc/dirsrv/slapd-instance_name/dse.ldif
file.
Important
/etc/dirsrv/slapd-instance_name/dse.ldif
file as long as the instance starts successfully.
1.8.3. Benefits of Using Default Values
passwordStorageScheme
attribute, Directory Server automatically uses the strongest supported password storage scheme available. If a future update changes the default value to increase security, passwords will be automatically encrypted using the new storage scheme when a user sets a password.
1.8.3.1. Removing a Parameter to Use the Default Value
# dsconf -D "cn=Directory Manager" ldap://server.example.com config delete parameter_name
Important
nsslapd-secureport
to reset them to default. If you try to delete them, the server rejects the request with a Server is unwilling to perform (53)
error.
1.8.4. The dsconf config backend
command limitations
dsconf config backend
command retrieves and sets backends configuration. The command has the following arguments:
- get
- set
dsconf config backend get
command retrieves all server backend configuration attributes with set values, for example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com:389 backend config get nsslapd-lookthroughlimit: 5000 nsslapd-mode: 600 nsslapd-idlistscanlimit: 2147483646 …
Note
dsconf config backend get
command, not a value for a specified attribute.
dsconf config backend set
command sets backends configuration attributes individually. To set a value, specify an option that matches the LDAP attribute name, for example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com:389 backend config set --lookthroughlimit 4000 --cache-autosize-split 24
dsconf backend config set
command options and LDAP attribute names mapping:
The dsconf backend config set command options | LDAP attribute names |
---|---|
--lookthroughlimit | nsslapd-lookthroughlimit |
--mode | nsslapd-mode |
--idlistscanlimit | nsslapd-idlistscanlimit |
--directory | nsslapd-directory |
--dbcachesize | nsslapd-dbcachesize |
--logdirectory | nsslapd-db-logdirectory |
--txn-wait | nsslapd-db-transaction-wait |
--checkpoint-interval | nsslapd-db-checkpoint-interval |
--compactdb-interval | nsslapd-db-compactdb-interval |
--compactdb-time | nsslapd-db-compactdb-time |
--txn-batch-val | nsslapd-db-transaction-batch-val |
--txn-batch-min | nsslapd-db-transaction-batch-min-wait |
--txn-batch-max | nsslapd-db-transaction-batch-max-wait |
--logbufsize | nsslapd-db-logbuf-size |
--locks | nsslapd-db-locks |
--locks-monitoring-enabled | nsslapd-db-locks-monitoring-enabled |
--locks-monitoring-threshold | nsslapd-db-locks-monitoring-threshold |
--locks-monitoring-pause | nsslapd-db-locks-monitoring-pause |
--import-cache-autosize | nsslapd-import-cache-autosize |
--import-cachesize | nsslapd-import-cachesize |
--cache-autosize | nsslapd-cache-autosize |
--cache-autosize-split | nsslapd-cache-autosize-split |
--exclude-from-export | nsslapd-exclude-from-export |
--pagedlookthroughlimit | nsslapd-pagedlookthroughlimit |
--pagedidlistscanlimit | nsslapd-pagedidlistscanlimit |
--rangelookthroughlimit | nsslapd-rangelookthroughlimit |
--backend-opt-level | nsslapd-backend-opt-level |
--deadlock-policy | nsslapd-db-deadlock-policy |
--db-home-directory | nsslapd-db-home-directory |
--db-lib | nsslapd-backend-implement |
1.9. Changing the LDAP and LDAPS Port Numbers
Important
1.9.1. Changing the Port Numbers Using the Command Line
nsslapd-port
: Stores the port number the instance uses for the LDAP protocol.nsslapd-secureport
: Stores the port number the instance uses for the LDAPS protocol.
- Optionally, display the currently configured port numbers for the instance:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config get nsslapd-port nsslapd-secureport nsslapd-port: 389 nsslapd-secureport: 636
- To change the LDAP port:
- Set the port for the LDAP protocol. For example, to set it to
1389
:# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-port=1389 Successfully replaced "nsslapd-port"
- Set the
ldap_port_t
type for the LDAP port you assigned in the previous step:# semanage port -a -t ldap_port_t -p tcp 1389
- To change the LDAPS port:
- Set the port for the LDAPS protocol. For example, to set it to
1636
:# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-secureport=1636 Successfully replaced "nsslapd-secureport"
- Set the
ldap_port_t
type for the LDAPS port you assigned in the previous step:# semanage port -a -t ldap_port_t -p tcp 1636
- Restart the instance:
# dsctl instance_name restart
1.9.2. Changing the Port Numbers Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- To change the LDAP port:
- Open themenu.
- On the Server Settings tab, fill the new port number into the LDAP Port field.
- Click.
- To change the LDAPS port:
- Open themenu.
- On the General Settings tab, fill the new port number into the LDAPS Port field.
- Click.
- Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.
1.10. Using Directory Server Plug-ins
1.10.1. Listing Available Plug-ins
1.10.1.1. Listing Available Plug-ins Using the Command Line
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin list 7-bit check Account Policy Plugin ...
1.10.1.2. Listing Available Plug-ins Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Select themenu.
1.10.2. Enabling and Disabling Plug-ins
1.10.2.1. Enabling and Disabling Plug-ins Using the Command Line
dsconf
utility.
Note
dsconf
command requires that you provide the name of the plug-in. For details about displaying the names of all plug-ins, see Section 1.10.1.1, “Listing Available Plug-ins Using the Command Line”.
- Enable the plug-in:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin automember enable
- Restart the instance:
# dsctl instance_name restart
1.10.2.2. Enabling and Disabling Plug-ins Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Select themenu.
- Select the All Plugins tab.
- Click thebutton to the right of the plug-in you want to enable or disable.
- Change the status to
ON
to enable or toOFF
to disable the plug-in. - Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.
1.10.3. Configuring Plug-ins
1.10.3.1. Configuring Plug-ins Using the Command Line
dsconf plugin
command:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin \ plug-in-specific_subcommand ...
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin --help
1.10.3.2. Configuring Plug-ins Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Select themenu.
- Select the All Plugins tab.
- Select the plug-in and click Show Advanced Settings.
- Open the plug-in-specific tab.
- Set the appropriate settings.
- Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.
1.10.4. Setting the Plug-in Precedence
1
(highest priority) to 99
(lowest priority). If no precedence is set, the default is 50
.
Warning
1.10.4.1. Setting the Plug-in Precedence Using the Command Line
- Set precedence of the plug-in. For example, to set the precedence for the
example
plug-in to1
:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin edit example --precedence 1
- Restart the instance:
# dsctl instance_name restart
1.10.4.2. Setting the Plug-in Precedence Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select All Plugins.
- Press thebutton next to the plug-in for which you want to configure the precedence value.
- Update the value in the Plugin Precedence field.
- Click.
- Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.
1.11. Creating and Using a .dsrc File to Set Default Options for Directory Server Command-line Utilities
~/.dsrc
file simplifies commands that use the Directory Server command-line utilities. By default, these utilities require that you pass, for example, an LDAP URL or bind distinguished name (DN) to the command. If you store these settings in a ~/dsrc
file, you can use the command-line utilities without specifying these settings each time.
1.11.1. How a .dsrc File Simplifies Commands
~/.dsrc
file that specifies the LDAP URL of an instance and a bind DN:
[server1] uri = ldap://server1.example.com binddn = cn=Directory Manager basedn = dc=example,dc=com
# dsidm server1 user create
~/.dsrc
file, you must specify the bind DN, LDAP URL, and base DN in the command:
# dsidm -D cn=Directory Manager ldap://server1.example.com -b "dc=example,dc=com" user create
1.11.2. Using the dsctl Utility to Create a .dsrc File
~/.dsrc
file, you can use the dsctl
utility to create it:
# dsctl instance_name dsrc create ...
--uri
: Sets the URL to the instance in the formatprotocol://host_name_or_IP_address_or_socket
.Examples:--uri ldap://server.example.com
--uri = ldaps://server.example.com
--uri = ldapi://%%2fvar%%2frun%%2fslapd-instance_name.socket
If you set the path to an Directory Server socket, use%%02
instead of slashes (/
) in the path.Important
If you use anldapi
URL, the server identifies the user ID (UID) and group ID (GID) of the user who runs the Directory Server command-line utility. If you run the command as theroot
user, both UID and GID are0
and Directory Server automatically authenticates you ascn=Directory Manager
without entering the corresponding password.
--starttls
: Sets configures the utilities to connect to an LDAP port and then send theSTARTTLS
command to switch to an encrypted connection.--basedn
: Sets the base distinguished name (DN). For example:--basedn dc=example,dc=com
--binddn
: Sets the bind DN. For example:--binddn cn=Directory Manager
--pwdfile
: Sets the path to a file that contains the password of bind DN. For example:--pwdfile /root/rhds.pwd
--tls-cacertdir
: When you use an LDAPS connection, the path set in this parameter defines the directory with the certificate authority (CA) certificate that is required to verify the server's certificate. For example:--tls-cacertdir /etc/pki/CA/certs/
Note that you must use thec_rehash /etc/pki/CA/certs/
command after you copied the CA certificate to the specified directory.--tls-cert
: Sets the absolute path to the server's certificate. For example:--tls-cert /etc/dirsrv/slapd-instance_name/Server-Cert.crt
--tls-key
: Sets the absolute path to the server's private key. For example:--tls-key /etc/dirsrv/slapd-instance_name/Server-Cert.key
--tls-reqcert
: Sets what checks the client utilities perform on server certificates in a TLS session. For example:--tls-reqcert hard
The following parameters are available:never
: The utilities do not request or check the server certificate.allow
: The utilities ignore certificate errors and the connection is established anyway.hard
: The utilities terminate the connection on certificate errors.
--saslmech
: Sets the SASL mechanism to use toPLAIN
orEXTERNAL
. For example:--saslmech PLAIN
1.11.3. Remote and Local Connection Resolution When Using Directory Server Utilities
/etc/openldap/ldap.conf
configuration file along with system-wide settings to proceed with the command.
~/.dsrc
file is present and applies the following logic to proceed:
- If the
~/.dsrc
file exists and contains both the instance name and the LDAP URL, Directory Server considers it as a remote connection and checks/etc/openldap/ldap.conf
configuration file and system-wide settings. - If the
~/.dsrc
file exists and contains only the specified instance name, or if the~/.dsrc
file does not exist, Directory Server considers it as a local connection and uses thensslapd-certdir
setting from the localdse.ldif
file to secure the connection. Ifnsslapd-certdir
is not present, the server uses the default path/etc/dirsrv/slapd-instance_name/
to store the Network Security Services (NSS) database of the instance.
nsslapd-certdir
parameter refer to nsslapd-certdir (Certificate and Key Database Directory) section.
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
2.1.1.1. Creating a Root Suffix
example.com
and one for redhat.com
. In this scenario, two root suffixes are required. One corresponding to the dc=example,dc=com
naming context and one corresponding to the dc=redhat,dc=com
naming context, as displayed in the following diagram:
Figure 2.2. A Directory with Two Root Suffixes
dc=example,dc=com
, and one root suffix corresponds to the European branch of their directory tree, ou=europe,dc=example,dc=com
. From a client application's perspective, the directory tree looks as illustrated the following diagram:
Figure 2.3. A Directory with a Root Suffix Off Limits to Search Operations
dc=example,dc=com
branch of the directory will not return entries from the ou=europe,dc=example,dc=com
branch of the directory, as it is a separate root suffix.
2.1.1.1.1. Creating a Root Suffix Using the Command Line
dsconf backend create
command to create a new root suffix:
- Optional: Identify the suffixes and back end databases that are already in use:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list dc=example,dc=com (userroot)
The name in parentheses is the back end database that stores the data of the corresponding suffix. You cannot use existing database names when you create the root suffix in the next step. - Create the
dc=example,dc=net
root suffix in theexample
back end database:# dsconf -D "cn=Directory Manager" ldap://server.example.com backend create \ --suffix="dc=example,dc=net" --be-name="example"
2.1.1.1.2. Creating a Root Suffix Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Click.
- Enter the suffix DN and back end name. For example:
- Select
Create The Top Suffix Entry
. - Click.
2.1.1.2. Creating a Sub-suffix
ou=europe,dc=example,dc=com
entry as a sub-suffix, this suffix is stored in a separate database. At the same time, the dc=example,com
root suffix and all its sub-entries - except ou=europe,dc=example,dc=com
and subentries - are stored also in a separate database.
Figure 2.4. A Directory Tree with a Sub Suffix
2.1.1.2.1. Creating a Sub-suffix Using the Command Line
dsconf backend create
command to create a new sub-suffix. For example, to create the ou=People,dc=example,dc=com
sub-suffix in a new database called people
under the dc=example,dc=com
root suffix:
- Optional: Identify the suffixes and back end databases that are already in use:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list dc=example,dc=com (userroot)
The name in parentheses is the back end database that stores the data of the corresponding suffix. You cannot use existing database names when you create the sub-suffix in the next step. - Create the sub-suffix. For example, to create the
ou=People,dc=example,dc=com
sub-suffix along with theexample
back end database, enter:# dsconf -D "cn=Directory Manager" ldap://server.example.com backend create \ --suffix="ou=People,dc=example,dc=com" --be-name="example" \ --parent-suffix="dc=example,dc=com"
2.1.1.2.2. Creating a Sub-suffix Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the suffix, under which you want to create the sub-suffix, click, and select .
- Enter the sub-suffix DN and back end name. For example:
- Select
Create The Top Sub-Suffix Entry
. - Click.
2.1.2. Maintaining Suffixes
2.1.2.1. Viewing the Default Naming Context
dc=example,dc=com
and a configuration suffix in cn=config
.
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
dsconf backend suffix set --disable
command. For example, to disable the o=test
suffix:
- Display the suffixes and their corresponding back end:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list dc=example,dc=com (userroot) o=test (test_database)
This command displays the name of the back end database next to each suffix. You require the suffix's database name in the next step. - Disable the suffix:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend \ suffix set --disable "test_database"
2.1.2.3. Deleting a Suffix
Warning
2.1.2.3.1. Deleting a Suffix Using the Command Line
dsconf backend delete
command. For example, to delete the o=test
suffix:
- Display the suffixes and their corresponding back end:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list dc=example,dc=com (userroot) o=test (test_database)
This command displays the name of the back end database next to each suffix. You require the suffix's database name in the next step. - Delete the back end database and the corresponding suffix:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend delete test_database Deleting Backend cn=test_database,cn=ldbm database,cn=plugins,cn=config : Type 'Yes I am sure' to continue: Yes I am sure The database, and any sub-suffixes, were successfully deleted
2.1.2.3.2. Deleting a Suffix Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the suffix, click Delete Suffix., and select
- Clickto confirm.
2.2. Creating and Maintaining Databases
Note
dsconf
utility or the web console to create the suffix, Directory Server created the database automatically.
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 a Single Suffix Using 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. To add a new database:
- Run
ldapmodify
and create the entry for the new database.# ldapmodify
-a
-D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=UserData,cn=ldbm database,cn=plugins,cn=config changetype: add objectclass: extensibleObject objectclass: nsBackendInstance nsslapd-suffix: ou=people,dc=example,dc=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.1.1, “Creating a Root Suffix Using the Command Line” and Section 2.1.1.2.1, “Creating a Sub-suffix Using the Command Line”. The database name, given in the DN attribute, must correspond with the value in the
nsslapd-backend
attribute of the suffix entry.
2.2.1.2. Adding Multiple Databases for a Single Suffix
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.
- 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.
2.2.2. Maintaining Directory Databases
2.2.2.1. Setting a Database in Read-Only Mode
2.2.2.1.1. Setting a Database in Read-only Mode Using the Command Line
dsconf backend suffix set
command. For example, to set the database of the o=test
suffix in read-only mode:
- Display the suffixes and their corresponding back end:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list dc=example,dc=com (userroot) o=test (test_database)
This command displays the name of the back end database next to each suffix. You require the suffix's database name in the next step. - Set the database in read-only mode:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix set --enable-readonly "test_database"
2.2.2.1.2. Setting a Database in Read-only Mode Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the suffix entry.
- Select Database Read-Only Mode.
- Click.
2.2.2.2. Placing the Entire Directory Server in Read-Only Mode
Warning
Note
2.2.2.2.1. Placing the Entire Directory Server in Read-Only Mode Using the Command Line
- Set the
nsslapd-readonly
parameter toon
:# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-readonly=on
- Restart the instance:
# dsctl instance_name restart
2.2.2.2.2. Placing the Entire Directory Server in Read-Only Mode Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open the Server Settings entry.menu, and select the
- On the Advanced Settings tab, select Server Read-Only.
- Click Save.
2.2.2.3. Deleting a Database
2.2.2.3.1. Deleting a Database Using the Command Line
dsconf backend delete
command. For example, to delete the database of the o=test
suffix:
- Display the suffixes and their corresponding back end:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list dc=example,dc=com (userroot) o=test (test_database)
You require the name of the back end database, which is displayed next to the suffix, in the next step. - Delete the database:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend delete "test_database"
2.2.2.3.2. Deleting a Database Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the suffix to delete, click Delete Suffix., and select
- Clickto confirm.
2.2.2.4. Changing the Transaction Log Directory
Note
- Stop Directory Server instance:
# dsctl instance_name stop
- Create a new location for the transaction logs. For example:
# mkdir -p /srv/dirsrv/instance_name/db/
- Set permissions to enable only Directory Server to access the directory:
# chown dirsrv:dirsrv /srv/dirsrv/instance_name/db/ # chmod 770 /srv/dirsrv/instance_name/db/
- Remove all
__db.*
files from the previous transaction log directory. For example:# rm /var/lib/dirsrv/slapd-instance_name/db/__db.*
- Move all
log.*
files from the previous to the new transaction log directory. For example:# mv /var/lib/dirsrv/slapd-instance_name/db/log.* \ /srv/dirsrv/instance_name/db/
- If SELinux is running in
enforcing
mode, set 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:
# dsctl instance_name start
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 Command Line
dsconf chaining link-create
command. For example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining link-create --suffix="ou=Customers,dc=example,dc=com" --server-url="ldap://remote_server.example.com:389" --bind-mech="" --bind-dn="cn=proxy_user,cn=config" --bind-pw="password" "example_chain_name"
example_chain_name
for the ou=Customers,dc=example,dc=com
. The link refers to the server ldap://remote_server.example.com:389
and uses the specified bind DN and password to authenticate. Because the --bind-mech
is set empty, the link uses simple authentication.
Note
dc=example,dc=com
suffix on remote server. How to do so, refer to the section Section 2.3.1.4, “Additional Information on Required Settings When Creating a Database Link”
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining link-create --help
2.3.1.2. Creating a New Database Link Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Create a new suffix as described in Section 2.1.1, “Creating Suffixes”.
- Select the suffix, click Create Database Link., and select
- Fill the fields with the details about the connection to the remote server. For example:For further details, see Section 2.3.1.4, “Additional Information on Required Settings When Creating a Database Link”.
- Click.
2.3.1.3. Managing the Default Configuration for New Database Links
dsconf chaining
command you can manage the default configuration of database links.
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining config-get-def
dsconf chaining config-set-def
command. For example, to set response-delay
parameter to 30
, run:
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining config-set-def --response-delay 30
dsconf instance chaining link-set
command.
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining config-set-def --help
2.3.1.4. Additional Information on Required Settings When Creating a Database Link
Suffix Information
Bind Credentials
anonymous
.
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.
- Create an administrative user, such as
cn=proxy_user,cn=config
, for the database link. For information on adding entries, see Chapter 3, Managing Directory Entries. - Provide proxy access rights for the administrative user created in the previous step on the subtree chained to by the database link. For more information on configuring ACIs, see Chapter 18, Managing Access ControlFor example, the following ACI grants read-only access to the
cn=proxy_admin,cn=config
user to access data contained on the remote server only within the subtree where the ACI is set.aci: (targetattr = "*")(version 3.0; acl "Proxied authorization for database links"; allow (proxy) userdn = "ldap:///cn=proxy_admin ,cn=config";)
Note
LDAP URL
ldap://host_name:port
.
ldaps://africa.example.com:636/
Note
Bind Mechanisms
- Over the standard LDAP port
- Over a dedicated LDAPS port
- Using STARTTLS, which is a secure connection over a standard port
Note
- empty: If there is no bind mechanism set, then the server performs simple authentication and requires a bind DN and password.
- EXTERNAL: This uses an TLS certificate to authenticate the farm server to the remote server. Either the farm server URL must be set to the secure URL (
ldaps
) or 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.10, “Setting up SASL Identity Mapping”.
Note
Note
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 Command Line
- Specify the components to include in chaining. For example, to configure that the referential integrity component can chain operations:
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining config-set \ --add-comp="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 instance:
# dsctl instance_name restart
- Create an ACI in the suffix on the remote server to which the operation will be chained. For example, to create an ACI for the Referential Integrity plug-in:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h remoteserver.example.com -x dn: ou=People,dc=example,dc=com changetype: modify add: aci 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 Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open thetab.
- In the navigation on the left, select theentry.
- Click the Components to Chain field.button below the
- Select the component, and click.
- Create an ACI in the suffix on the remote server to which the operation will be chained. For example, to create an ACI for the Referential Integrity plug-in:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h remoteserver.example.com -x dn: ou=People,dc=example,dc=com changetype: modify add: aci 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 pulls specified attribute information from the referenced entry and returns this information 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.3, “Detecting Loops”.
Note
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.2.2.1. Chaining LDAP Controls Using the Command Line
dsconf chaining config-set --add-control
command. For example, to forward the virtual list view control:
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining \ config-set --add-control="2.16.840.1.113730.3.4.9"
2.3.2.2.2. Chaining LDAP Controls Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select theentry.
- Click the Forwarded LDAP Controls field.button below the
- Select the LDAP control and click.If clients of Directory Server create their own controls and their operations should be chained to remote servers, add the object identifier (OID) of the custom control.For a list of LDAP controls that can be chained and their OIDs, see Table 2.1, “LDAP Controls and Their OIDs”.
- Click.
2.3.3. 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 ou=people
and ou=groups
sub-suffixes are stored on Server A. The ou=europe,dc=example,dc=com
and ou=groups
suffixes are stored in on Server B, and the ou=people
branch of the ou=europe,dc=example,dc=com
suffix is stored on Server C.
ou=people,ou=europe,dc=example,dc=com
entry would be routed by the directory as follows:
ou=people,ou=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 Command Line
Configuration Steps on Server 1
- Create the suffix
c=africa,ou=people,dc=example,dc=com
:# dsconf -D "cn=Directory Manager" ldap://server1.example.com backend create --parent-suffix="ou=people,dc=example,dc=com" --suffix="c=africa,ou=people,dc=example,dc=com"
- Create the
DBLink1
database link:# dsconf -D "cn=Directory Manager" ldap://server1.example.com chaining link-create --suffix="c=africa,ou=people,dc=example,dc=com" --server-url="ldap://africa.example.com:389/" --bind-mech="" --bind-dn="cn=server1 proxy admin,cn=config" --bind-pw="password" --check-aci="off" "DBLink1"
- Enable loop detection:
# dsconf -D "cn=Directory Manager" ldap://server1.example.com chaining config-set --add-control="1.3.6.1.4.1.1466.29539.12"
Configuration Steps on Server 2
- Create a proxy administrative user on server 2 for server 1 to use for proxy authorization:
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server2.example.com -x dn: cn=server1 proxy admin,cn=config objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: server1 proxy admin sn: server1 proxy admin userPassword: password description: Entry for use by database links
Important
For security reasons, do not use thecn=Directory Manager
account. - Create the suffix
ou=Zanzibar,c=africa,ou=people,dc=example,dc=com
:# dsconf -D "cn=Directory Manager" ldap://server2.example.com backend create --parent-suffix="c=africaou=people,dc=example,dc=com" --suffix="ou=Zanzibar,c=africa,ou=people,dc=example,dc=com"
- Create the
DBLink2
database link:# dsconf -D "cn=Directory Manager" ldap://server2.example.com chaining link-create --suffix="ou=Zanzibar,c=africa,ou=people,dc=example,dc=com" --server-url="ldap://zanz.africa.example.com:389/" --bind-mech="" --bind-dn="server2 proxy admin,cn=config" --bind-pw="password" --check-aci="on "DBLink2"
Because theDBLink2
link is the intermediate database link in the cascading chaining configuration, enable the ACL check to allow the server to check whether it should allow the client and proxy administrative user access to the database link. - Enable loop detection:
# dsconf -D "cn=Directory Manager" ldap://server2.example.com chaining config-set --add-control="1.3.6.1.4.1.1466.29539.12"
- Enable the proxy authorization control:
# dsconf -D "cn=Directory Manager" ldap://server2.example.com chaining config-set --add-control="2.16.840.1.113730.3.4.12"
- Add the local proxy authorization ACI:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server2.example.com -x dn: c=africa,ou=people,dc=example,dc=com changetype: modify add: aci aci:(targetattr="*")(target="lou=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";)
- Add an ACI that enables users in
c=us,ou=people,dc=example,dc=com
on server 1 who have auid
attribute set, to perform any type of operation on theou=Zanzibar,c=africa,ou=people,dc=example,dc=com
suffix tree on server 3:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server2.example.com -x dn: c=africa,ou=people,dc=example,dc=com changetype: modify add: aci aci:(targetattr="*")(target="ou=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";)
If there are users on server 3 under a different suffix that will require additional rights on server 3, it is necessary to add additional client ACIs on server 2.
Configuration Steps on Server 3
- Create a proxy administrative user on server 3 for server 2 to use for proxy authorization:
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server3.example.com -x dn: cn=server2 proxy admin,cn=config objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: server2 proxy admin sn: server2 proxy admin userPassword: password description: Entry for use by database links
Important
For security reasons, do not use thecn=Directory Manager
account. - Add the local proxy authorization ACI:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server3.example.com -x dn: ou=Zanzibar,ou=people,dc=example,dc=com changetype: modify add: aci aci: (targetattr = "*")(version 3.0; acl "Proxied authorization for database links"; allow (proxy) userdn = "ldap:///cn=server2 proxy admin,cn=config";)
- Add an ACI that enables users in
c=us,ou=people,dc=example,dc=com
on server 1 who have auid
attribute set, to perform any type of operation on theou=Zanzibar,c=africa,ou=people,dc=example,dc=com
suffix tree on server 3:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server3.example.com -x dn: ou=Zanzibar,ou=people,dc=example,dc=com changetype: modify add: aci aci: (targetattr ="*")(target="ou=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";)
If there are users on server 3 under a different suffix that will require additional rights on server 3, it is necessary to add additional client ACIs on server 2.
ou=Zanzibar,c=africa,ou=people,dc=example,dc=com
branch on server 3. Depending on your security needs, it can be necessary to provide more detailed access control.
2.4.3. Detecting Loops
0
, it determines that a loop has been detected and notifies the client application.
1.3.6.1.4.1.1466.29539.12
OID. For details about adding an LDAP control, see Section 2.3.2.2, “Chaining LDAP Controls”. If the control is not present in the configuration file of each database link, loop detection will not be implemented.
nsHopLimit
parameter. By default, the parameter is set to 10
. For example, to set the hop limit of the example
chain to 5
:
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining link-set --hop-limit 5 example
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.- port is the optional port number of Directory Server to start in referral mode.
- referral_url is the referral returned to clients. The format of an LDAP URL is covered in Appendix C, LDAP URLs.
2.5.2. Setting Default Referrals
2.5.2.1. Setting a Default Referral Using the Command Line
dsconf config replace
command, to set the default referral in the nsslapd-referral
parameter. For example, to set ldap://directory.example.com/
as the default referral:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-referral="ldap://directory.example.com/"
2.5.3. Creating Smart Referrals
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,ou=europe,dc=example,dc=com
on the server directory.europe.example.com
.
2.5.3.1. Creating Smart Referrals Using the Command Line
referral
object class and set the ref
attribute to the referral LDAP URL.
uid=user,ou=people,dc=example,dc=com
that refers to ldap://directory.europe.example.com/cn=user,ou=people,ou=europe,dc=example,dc=com
:
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server2.example.com -x dn: uid=user,ou=people,dc=example,dc=com objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson objectclass: referral sn: user uid: user cn: user ref: ldap://directory.europe.example.com/cn=user,ou=people,ou=europe,dc=example,dc=com
Note
%20
instead of spaces in LDAP URLs used as a referral.
-M
option with ldapadd
if there is already a referral in the DN path. For more information on smart referrals, see the Directory Server Deployment Guide.
2.5.4. Creating Suffix Referrals
Warning
2.5.4.1. Creating Suffix Referrals Using the Command Line
- Optionally, create a root or sub-suffix, if it does not already exist. For details, see Section 2.1.1, “Creating Suffixes”.
- Add the referral to the suffix. For example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix set --add-referral="ldap://directory.example.com/" database_name
2.5.4.2. Creating Suffix Referrals Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Optionally, create a root or sub-suffix, if it does not already exist. For details, see Section 2.1.1, “Creating Suffixes”.
- Select the suffix in the list, and open the Referrals tab.
- Click.
- Fill the fields to create the referral URL.
- Click.
2.6. Verifying the Integrity of Back-end Databases
dsctl dbverify
command enables administrators to verify the integrity of back-end databases. For example, to verify the userroot
database:
- Optionally, list the back-end databases of the instance:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list dc=example,dc=com (userroot)
You need the name of the database in a later step. - Stop the Directory Server instance:
# dsctl instance_name stop
- Verify the database:
# dsctl instance_name dbverify userroot [04/Feb/2020:13:11:02.453624171 +0100] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000 [04/Feb/2020:13:11:02.465339507 +0100] - WARN - ldbm_instance_add_instance_entry_callback - ldbm instance userroot already exists [04/Feb/2020:13:11:02.468060144 +0100] - ERR - ldbm_config_read_instance_entries - Failed to add instance entry cn=userroot,cn=ldbm database,cn=plugins,cn=config [04/Feb/2020:13:11:02.471079045 +0100] - ERR - bdb_config_load_dse_info - failed to read instance entries [04/Feb/2020:13:11:02.476173304 +0100] - ERR - libdb - BDB0522 Page 0: metadata page corrupted [04/Feb/2020:13:11:02.481684604 +0100] - ERR - libdb - BDB0523 Page 0: could not check metadata page [04/Feb/2020:13:11:02.484113053 +0100] - ERR - libdb - /var/lib/dirsrv/slapd-instance_name/db/userroot/entryrdn.db: BDB0090 DB_VERIFY_BAD: Database verification failed [04/Feb/2020:13:11:02.486449603 +0100] - ERR - dbverify_ext - verify failed(-30970): /var/lib/dirsrv/slapd-instance_name/db/userroot/entryrdn.db dbverify failed
- If the verification process reported any problems, fix them manually or restore a backup.
- Start the Directory Server instance:
# dsctl instance_name start
Chapter 3. Managing Directory Entries
3.1. Managing Directory 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.2, “Importing Using 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,ou=People,dc=example,dc=com
entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: uid=user,ou=People,dc=example,dc=com changetype: modify add: telephoneNumber telephoneNumber: 555-1234567
telephoneNumber
attributes at once to the uid=user,ou=People,dc=example,dc=com
:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: uid=user,ou=People,dc=example,dc=com changetype: modify add: telephoneNumber telephoneNumber: 555-1234567 telephoneNumber: 555-7654321
3.1.4.2. Updating an Attribute's Value
Updating a Single-value Attribute
replace
operation to override the existing value. The following command updates the manager
attribute of the uid=user,ou=People,dc=example,dc=com
entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: uid=user,ou=People,dc=example,dc=com changetype: modify replace: manager manager: uid=manager_name,ou=People,dc=example,dc=com
Updating a Specific Value of a Multi-value Attribute
telephoneNumber
attribute that is currently set to 555-1234567
in the uid=user,ou=People,dc=example,dc=com
entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: uid=user,ou=People,dc=example,dc=com changetype: modify delete: telephoneNumber telephoneNumber: 555-1234567 - add: telephoneNumber telephoneNumber: 555-9876543
3.1.4.3. Deleting Attributes from an Entry
delete
operation.
Deleting an Attribute
manager
attribute from the uid=user,ou=People,dc=example,dc=com
entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: uid=user,ou=People,dc=example,dc=com changetype: modify delete: manager
Note
Deleting a Specific Value of a Multi-value Attribute
telephoneNumber
attribute that is set to 555-1234567
from the uid=user,ou=People,dc=example,dc=com
entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: uid=user,ou=People,dc=example,dc=com changetype: modify delete: telephoneNumber telephoneNumber: 555-1234567
3.1.5. Deleting an Entry
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,ou=People,dc=example,dc=com changetype: delete
3.1.6. Renaming and Moving an Entry
Note
moddn
Access Control List (ACL) to grant permissions to move entries. For details, see Section 18.9.2.1, “Targeting Source and Destination DNs”.
- Renaming an Entry
- If you rename an entry, the
modrdn
operation changes the Relative Distinguished Name (RDN) of the entry: - Renaming a Subentry
- For subtree entries, the
modrdn
operation renames the subtree and also the DN components of child entries:Note that for large subtrees, this process can take a lot of time and resources. - Moving an Entry to a New Parent
- A similar action to renaming a subtree is moving an entry from one subtree to another. This is an expanded type of the
modrdn
operation, which simultaneously renames the entry and sets anewSuperior
attribute which moves the entry from one parent to another:
3.1.6.1. 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.8, “RegeneratingmemberOf
Values”.
3.1.6.2. Renaming Users, Groups, POSIX Groups, and OUs
dsidm
utility can rename several types of objects:
- Users:
# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" user rename current_user_name new_user_name
Note that thedsidm user rename
command automatically placesou=People
in front of the base DN you have specified. - Groups:
# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" group rename current_group_name new_group_name
Note that thedsidm group rename
command automatically placesou=Groups
in front of the base DN you have specified. - POSIX Groups:
# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" posixgroup rename current_posix_group_name new_posix_group_name
Note that thedsidm posixgroup rename
command automatically placesou=Groups
in front of the base DN you have specified. - Organizational Units (OU)
# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" organizationalunit rename current_ou_name new_ou_name
Thedsidm organizationalunit rename
command performs the rename operation directly in the base DN you have specified.
3.1.6.3. The deleteOldRDN
Parameter When Renaming Entries Using LDIF Statements
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 Using LDIF Statements
changetype: modrdn
operation and, set the new RDN in the newrdn
attribute.
cn=demo1,dc=example,dc=com
entry to cn=example_user,dc=example,dc=com
:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=example_user,cn=ldap_connect,dc=example,dc=com changetype: modrdn newrdn: cn=example_user deleteOldRDN: 1 newSuperior: dc=example,dc=com
deleteOldRDN
, see Section 3.1.6.3, “The deleteOldRDN
Parameter When Renaming Entries Using LDIF Statements”.
3.1.6.5. Moving an Entry to a New Parent Using LDIF Statements
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.
cn=demo
entry from ou=Germany,dc=example,dc=com
to ou=France,dc=example,dc=com
:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=demo,ou=Germany,dc=example,dc=com changetype: modrdn newrdn: cn=demo deleteOldRDN: 1 newSuperior: ou=France,dc=example,dc=com
deleteOldRDN
, see Section 3.1.6.3, “The deleteOldRDN
Parameter When Renaming Entries Using LDIF Statements”.
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 Directory Entries Using the Web Console
3.2.1. Adding an LDAP Entry Using the Web Console
- users
- groups
- roles
- organizational units (OUs)
- custom entries
cn=John Smith,ou=people,dc=example,dc=com
with a password.
Prerequisites
- You are logged in to the Directory Server web console.
- The parent entry exists. For example,
ou=people,dc=example,dc=com
.
Procedure
- In the web console, open themenu to reveal the list of existing suffixes.
- Using theor view, expand the parent entry
ou=people,dc=example,dc=com
under which you want to create a user. - Click theand select to open the wizard window.
- Select theoption and click .
- For the user entry, selecttype and click .
- Optional: Select additional attributes, such as
userPassword
, and click . You can view all selected attributes by expanding the drop-down list near the step name. - Set a value for each attribute:
- Click on the pencil button of the attribute and add a value.Note that a separate menu opens when you set the
userPassword
value. The value is filled with asterisks (*) to hide the plain text. - Click on the check button to save changes.
- Optional: Set an additional attribute value by clicking the→ .
- After you have set all values, click.
- Verify that all entry details are correct and click. Directory Server creates the entry with mandatory attributes for a POSIX user and sets the password to it. You can click to modify entry settings, or click to cancel the entry creation.
- View theand click .
Verification
- Navigate to→ .
- Select the database suffix that contains the entry, such as
dc=example,cd=com
. - Enter your search criteria in the field, such as
John
, and press . - Find the entry you recently created in the list of entries.
3.2.2. Editing an LDAP Entry Using the Web Console
cn=John Smith,ou=people,dc=example,dc=com
by:
- adding telephone numbers
556778987
and556897445
. - adding email
jsmith@example.com
. - changing the password.
Prerequisites
Procedure
- In the web console, open themenu to reveal the list of existing suffixes.
- Using theor view, expand the entry you want to edit, such as
cn=John Smith,ou=people,dc=example,dc=com
. - Click theand select to open the wizard window.
- Optional: In thestep, add or delete object classes for the entry. Click .
- In thestep, add
telephoneNumber
andmail
attributes to the entry and click . If you do not see an attribute you want to add to the entry it means that you did not add corresponding object class in the previous step.Note
In this step, you can not delete mandatory attributes of the selected object classes. - In thestep, set
telephoneNumber
to556778987
and556897445
,mail
tojsmith@example.com
and changeuserPassword
value:- Click on the pencil button of the attribute and add or change a new value.
- Click on the check button to save changes.
- Optional: Set an additional value to an attribute by clicking the→ . The
telephoneNumber
attribute has two values in this example. When you set all values, click .
- Review your changes and click.
- To edit the entry, click. You can click to modify entry settings, or click to cancel the entry editing.
- View theand click .
Verification
- Expand the entry details and view the new changes appear among the entry attributes.
3.2.3. Renaming and Relocating an LDAP Entry or Subtree Using the Web Console
cn=John Smith,ou=people,dc=example,dc=com
to cn=Tom Smith,ou=clients,dc=example,dc=com
.
Prerequisites
Procedure
- In the web console, open themenu to reveal the list of existing suffixes.
- Using theor view, expand the entry you want to modify, such as
cn=John Smith,ou=people,dc=example,dc=com
. - Click theand select to open the wizard window.
- In thestep:
- Set a new value
Tom Smith
for the naming attributecn
and click . - Optional: Select another naming attribute from the drop-down menu.
- Optional: In case you want to delete the old entry and create a new one using the new RDN, check.
- Instep, select the parent entry for the new location, and click .
- Review changes you made to the entry and click.
- If the entry details are correct, click. You can click to make other changes to the entry or click to cancel the entry modification.
- Viewand click .
Verification
- Expand the entry details and review the updated entry.
3.2.4. Deleting an LDAP Entry Using the Web Console
cn=Tom Smith,ou=clients,dc=example,dc=com
.
Prerequisites
Procedure
- In the web console, open themenu to reveal the list of existing suffixes.
- Using theor view, expand the entry you want to delete, such as
cn=Tom Smith,ou=clients,dc=example,dc=com
. - Click theand select to open the wizard window.
- Clickafter you review the data about the entry you want to delete.
- In thestep, toggle the switch to the position and click . You can click to cancel the entry deletion.
- View theand click .
Verification
- Navigate to→ .
- Select the suffix where the entry previously existed, such as
dc=example,cd=com
. - Enter your search criteria in the field, such as
Tom
, and press . - Verify that the deleted entry is no longer present.
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.4.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 further details about operational attributes, see Section 14.4.7, “Searching for Operational Attributes”.
Example 4.1. Example Entry USN
entryusn
attribute of the uid=example,ou=People,dc=example,dc=com
user entry:
# ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com:389 -x -b "uid=example,ou=People,dc=example,dc=com" -s base -x entryusn
dn: uid=example,ou=People,dc=example,dc=com
entryusn: 17653
- 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. Enabling the USN Plug-in
4.1.2.1. Enabling the USN Plug-in Using the Command Line
- Use the
dsconf
utility to enable the plug-in:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin usn enable
- Restart the instance:
# dsctl instance_name restart
4.1.2.2. Enabling the USN Plug-in Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Select themenu.
- Select the USN plug-in.
- Change the status to
ON
to enable the plug-in. - Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.
4.1.3. Global USNs
Note
4.1.3.1. Identifying Whether Global USNs are Enabled
4.1.3.1.1. Identifying Whether Global USNs are Enabled Using the Command Line
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin usn global USN global mode is disabled
4.1.3.1.2. Identifying Whether Global USNs are Enabled Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Select themenu.
- Select the USN plug-in.
- Verify that theswitch is set to
On
.
4.1.3.2. Enabling Global USNs
4.1.3.2.1. Enabling Global USNs Using the Command Line
- Enable global USNs:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin usn global on
- Restart the instance:
# dsctl instance_name restart
4.1.3.2.2. Enabling Global USNs Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the USN plug-in.
- Change the status of the plug-in to
On
. - Change the USN Global status to
On
. - Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.
4.1.4. Cleaning up USN Tombstone Entries
- before converting a server to a replica
- to free memory for the server
4.1.4.1. Cleaning up USN Tombstone Entries Using the Command Line
dc=example,dc=com
suffix using the command line:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin usn cleanup -s "dc=example,dc=com"
-o max_USN
option to the command to delete USN tombstone entries up to the specified value.
4.1.4.2. Cleaning up USN Tombstone Entries Using the Web Console
dc=example,dc=com
suffix using the web console:
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the USN plug-in.
- Press thebutton.
- Fill the fields, and press.
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/2018: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/2018: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/2018: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. Enabling Tracking of Modifications
Note
4.2.2.1. Enabling Tracking Of Modifications Using the Command Line
- Set the
nsslapd-lastmod
parameter toon
:# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-lastmod=on
- Optionally, to regenerate the missing
nsUniqueID
attributes:- Export the database into an LDAP Data Interchange Format (LDIF) file. See Section 6.2.1, “Exporting Data into an LDIF File Using the Command Line”.
- Import the database from the LDIF file. See Section 6.1.2, “Importing Using the Command Line”.
4.3. Tracking the Bind DN for Plug-in Initiated Updates
dn: cn=example_group,ou=groups,dc=example,dc=com modifiersname: uid=example,ou=people,dc=example,dc=com dn: uid=example,ou=people,dc=example,dc=com modifiersname: cn=memberOf plugin,cn=plugins,cn=config
nsslapd-plugin-binddn-tracking
parameter enables the server to track which user originated an update operation, as well as the internal plug-in which actually performed it. The bound user is shown in the modifiersname
and creatorsname
operational attributes, while the plug-in which performed it is shown in the internalModifiersname
and internalCreatorsname
operational attributes. For example:
dn: uid=example,ou=people,dc=example,dc=com modifiersname: uid=admin,ou=people,dc=example,dc=com internalModifiersname: cn=memberOf plugin,cn=plugins,cn=config
nsslapd-plugin-binddn-tracking
parameter 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
.
4.3.1. Enabling Tracking the Bind DN for Plug-in Initiated Updates Using the Command Line
- Set the
nsslapd-plugin-binddn-tracking
parameter toon
:# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-plugin-binddn-tracking=on
- Restart the instance:
# dsctl instance_name restart
4.3.2. Enabling Tracking the Bind DN for Plug-in Initiated Updates Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open the Server Settings entry.menu, and select the
- On the Advanced Settings tab, select Enable Plugin Bind DN Tracking.
- Click.
- Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.
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 20.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 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, you can configure the behavior of the Referential Integrity Postoperation plug-in to suit the needs of the directory in several different ways:
- Record Referential Integrity updates in the replication change log.
- Modify the update interval.
- Select the attributes to which to apply Referential Integrity.
- Disable Referential Integrity.
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.
- Enable it on a supplier server that contains only read-write replicas.
- Enable the plug-in for each supplier server in multi-supplier replication topology. The plug-in configuration must be the same on all supplier servers.
Note
5.3. Enabling Referential Integrity
5.3.1. Enabling Referential Integrity Using the Command Line
- Use the
dsconf
utility to enable the plug-in:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity enable
- Restart the instance:
# dsctl instance_name restart
5.3.2. Enabling Referential Integrity Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Select the Plugins menu.
- Select the Referential Integrity plug-in and click Show Advanced Settings.
- Change the status to
ON
to enable the plug-in.
5.4. The Referential Integrity Update Interval
0
: The check for referential integrity is performed immediately.-1
: No check for referential integrity is performed.
Important
0
on all suppliers.
Note
5.4.1. Displaying the Update Interval Using the Command Line
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity show
referint-update-delay: 0
...
5.4.2. Displaying the Update Interval Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the Referential Integrity plug-in.
- See the Update Delay field for the update interval.
5.4.3. Modifying the Update Interval Using the Command Line
- Set the update interval to
0
:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --update-delay=0
- Restart the instance:
# dsctl instance_name restart
5.4.4. Modifying the Update Interval Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the Referential Integrity plug-in.
- Set the interval in the Update Delay field.
- Press.
- Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.
5.5. Displaying and 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 web console.
Note
5.5.1. Displaying the Attribute List Using the Command Line
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity show
5.5.2. Displaying the Attribute List Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the Referential Integrity plug-in.
- See the Membership Attribute field for the list of attributes.
5.5.3. Configuring the Attribute List Using the Command Line
- Optionally, display the current list of attributes. See Section 5.5.1, “Displaying the Attribute List Using the Command Line”.
- Update the attribute list:
- To set an attribute list that should be checked and updated by the plug-in:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --membership-attr attribute_name_1 attribute_name_2
- To delete all attributes that should no longer be checked and updated by the plug-in:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --membership-attr delete
- Restart the instance:
# dsctl instance_name restart
5.5.4. Configuring the Attribute List Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the Referential Integrity plug-in.
- Update the Membership Attribute field to set the attributes.
- To add an attribute, enter the name into the Membership Attribute field.
- To remove an attribute, press the Membership Attribute field.button right next to the attribute's name in the
- Press.
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.
5.6.1. Parameters That Control the Referential Integrity Scope
nsslapd-pluginEntryScope
- This multi-value parameter controls the scope of the entry that is deleted or renamed. It defines the subtree in which the Referential Integrity Postoperation plug-in looks for the delete or rename operations of a user entry. If a user is deleted or renamed that does not exist under the defined subtree, the plug-in ignores the operation. The parameter allows you to specify to which branches of the database the plug-in should apply the operation.
nsslapd-pluginExcludeEntryScope
- This parameter also controls the scope of the entry that is deleted or renamed. It defines the subtree in which the Referential Integrity Postoperation plug-in ignores any operations for deleting or renaming a user.
nsslapd-pluginContainerScope
- This parameter controls the scope of groups in which references are updated. After a user is deleted, the Referential Integrity Postoperation plug-in looks for the groups to which the user belongs and updates them accordingly. This parameter specifies which branch the plug-in searches for the groups to which the user belongs. The Referential Integrity Postoperation plug-in only updates groups that are under the specified container branch, and leaves all other groups not updated.
5.6.2. Displaying the Referential Integrity Scope Using the Command Line
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity show ... nsslapd-pluginEntryScope: DN nsslapd-pluginExcludeEntryScope: DN nsslapd-pluginContainerScope: DN
5.6.3. Displaying the Referential Integrity Scope Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the Referential Integrity plug-in.
- See the Entry Scope, Exclude Entry Scope, and Container Scope fields for the currently configured scope.
5.6.4. Configuring the Referential Integrity Scope Using the Command Line
- Optionally, display the scope settings. See Section 5.6.2, “Displaying the Referential Integrity Scope Using the Command Line”.
- The following commands show how to configure the individual referential integrity scope settings using the command line:
- To set a distinguished name (DN):
- To the
nsslapd-pluginEntryScope
parameter:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --entry-scope="DN"
- To the
nsslapd-pluginExcludeEntryScope
parameter:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --exclude-entry-scope="DN"
- To the
nsslapd-pluginContainerScope
parameter:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --container-scope="DN"
- To remove a DN:
- From the
nsslapd-pluginEntryScope
parameter:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --entry-scope=delete
- From the
nsslapd-pluginExcludeEntryScope
parameter:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --exclude-entry-scope=delete
- From the
nsslapd-pluginContainerScope
parameter:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --container-scope=delete
- Restart the instance:
# dsctl instance_name restart
5.6.5. Configuring the Referential Integrity Scope Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Select themenu.
- Select the Referential Integrity plug-in.
- Set the scope in the Entry Scope, Exclude Entry Scope, and Container Scope fields.
- Click.
Chapter 6. Populating Directory Databases
6.1. Importing Data
- Importing data
Important
To import data, you must store the LDIF file that you want to import in the/var/lib/dirsrv/slapd-instance_name/ldif/
directory. Directory Server usesPrivateTmp
systemd directive by default. As a result, if you export LDIF files into the/tmp/
or/var/tmp/
system directories, Directory Server does not see these LDIF files during import. For more information aboutPrivateTmp
, seesystemd.exec(5)
man page. - Initializing a database for replication
Action | Import | Initialize Database |
---|---|---|
Overwrites database | No | Yes |
LDAP operations | Add, modify, delete | Add only |
Performance | More time-consuming | Fast |
Partition specialty | Works on all partitions | Local partitions only |
Response to server failure | Best effort (all changes made up to the point of the failure remain) | Atomic (all changes are lost after a failure) |
LDIF file location | Local to the web console | Local to the web console or local to server |
Imports configuration information (cn=config ) | Yes | No |
6.1.1. Setting EntryUSN Initial Values During Import
nsslapd-entryusn-import-initval
parameter, 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.
Example 6.1. How the nsslapd-entryusn-import-initval
Parameter works
1000
before the import or initialization operation, and the nsslapd-entryusn-import-initval
value is next
, then every imported entry is assigned a USN of 1001
:
# ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com -x "(cn=*)" entryusn dn: dc=example,dc=com entryusn: 1001 dn: ou=Accounting,dc=example,dc=com entryusn: 1001 dn: ou=Product Development,dc=example,dc=com entryusn: 1001 ... dn: uid=user_name,ou=people,dc=example,dc=com entryusn: 1001 ...
nsslapd-entryusn-import-initval
parameter to the server into which data are being imported or to the supplier server which will perform the initialization. For example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-entryusn-import-initval=next
Note
nsslapd-entryusn-import-initval
parameter is not replicated between servers. This means that the value must be set specifically on whichever supplier server is being used to initialize a replica.
Supplier1
host has nsslapd-entryusn-import-initval
set to next and is used to initialize a replica, then the entry USNs for imported entries have the highest value plus one. If the Supplier2
host does not have nsslapd-entryusn-import-initval
set and is used to initialize a replica, then all entry USNs for imported entries begin at zero — even if Supplier1
and Supplier2
have a multi-supplier replication agreement between them.
6.1.2. Importing Using the Command Line
- Use one of the following methods if the instance is running:
- Use the
dsconf backend import
command. See Section 6.1.2.1.1, “Importing Using thedsconf backend import
Command”. - Create a
cn=tasks
entry. See Section 6.1.2.1.2, “Importing Data Using acn=tasks
Entry”.
- If the instance is offline, use the
dsctl ldif2db
command. See Section 6.1.2.2, “Importing Data While the Server is Offline”.
Warning
UTF-8
character set encoding. Import operations do not convert data from the local character set encoding to UTF-8
. Additionally, all imported LDIF files must contain the root suffix entry.
dirsrv
user. Therefore, the permissions of the LDIF file must allow this user to read the file.
6.1.2.1. Importing Data While the Server is Running
6.1.2.1.1. Importing Using the dsconf backend import
Command
dsconf backend import
command to automatically create a task that imports data from an LDIF file. For example, to import the /var/lib/dirsrv/slapd-instance_name/ldif/instance_name-database_name-time_stamp.ldif
file into the userRoot
database:
- Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
- If the LDIF you want to import does not contain statements that add the suffix entry, create this entry manually as described in Section 3.1.3.3, “Creating a Root Entry”.
- Import the LDIF file:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend import userRoot /var/lib/dirsrv/slapd-instance_name/ldif/instance_name-database_name-time_stamp.ldif The import task has finished successfully
Thedsconf backend import
command supports additional options, for example, to exclude a specific suffix. To display all available options, enter:# dsconf ldap://server.example.com backend import --help
6.1.2.1.2. Importing Data Using a cn=tasks
Entry
cn=tasks,cn=config
entry in the Directory Server configuration is a container entry for temporary entries the server uses to manage tasks. To initiate an import operation, create a task in the cn=import,cn=tasks,cn=config
entry.
cn
: Sets the unique name of the task.nsFilename
: Sets the name of the LDIF file to import.nsInstance
: Sets the name of the database into which the file should be imported.
/var/lib/dirsrv/slapd-instance_name/ldif/example.ldif
file into the userRoot
database:
- Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
- If the LDIF you want to import does not contain statements that add the suffix entry, create this entry manually as described in Section 3.1.3.3, “Creating a Root Entry”.
- Add the import task:
# ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com -x dn: cn=example_import,cn=import,cn=tasks,cn=config changetype: add objectclass: extensibleObject cn: example_import nsFilename: /var/lib/dirsrv/slapd-instance_name/ldif/example.ldif nsInstance: userRoot
6.1.2.2. Importing Data While the Server is Offline
dsctl ldif2db
command:
- Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
- If the LDIF you want to import does not contain statements that add the suffix entry, create this entry manually as described in Section 3.1.3.3, “Creating a Root Entry”.
- Stop the instance:
# dsctl instance_name stop
- Import the data from the LDIF file. For example, to import the
/var/lib/dirsrv/slapd-instance_name/ldif/example.ldif
file into theuserRoot
database:# dsctl instance_name ldif2db userroot /var/lib/dirsrv/slapd-instance_name/ldif/example.ldif OK group dirsrv exists OK user dirsrv exists [17/Jul/2018:13:42:42.015554231 +0200] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000 ... [17/Jul/2018:13:42:44.302630629 +0200] - INFO - import_main_offline - import userroot: Import complete. Processed 160 entries in 2 seconds. (80.00 entries/sec) ldif2db successful
Warning
If the database specified in the command does not correspond with the suffix contained in the LDIF file, all data contained in the database is deleted, and the import fails. - Start the instance:
# dsctl instance_name start
6.1.3. Importing Data Using the Web Console
- Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
- If the LDIF you want to import does not contain statements that add the suffix entry, create this entry manually as described in Section 3.1.3.3, “Creating a Root Entry”.
- Store the LDIF file you want to import in the
/var/lib/dirsrv/slapd-instance_name/ldif/
directory. - Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the suffix entry.
- Click Initialize Suffix., and select
- Select the LDIF file to import or enter the full path to the file.
- Select Yes, I am sure., and click to confirm.
6.2. Exporting Data
Note
cn=config
), schema information (cn=schema
), or monitoring information (cn=monitor
).
- Backing up the data in the database.
- Copying data to another Directory Server.
- Exporting data to another application.
- Repopulating databases after a change to the directory topology.For example, if a directory contains one database, and its contents should be split into two databases, then the two new databases receive their data by exporting the contents of the old databases and importing it into the two new databases, as illustrated in Figure 6.1, “Splitting a Database Contents into Two Databases”.
Figure 6.1. Splitting a Database Contents into Two Databases
Warning
dirsrv
user. Therefore, the permissions of the destination directory must allow this user to write the file.
6.2.1. Exporting Data into an LDIF File Using the Command Line
- Use one of the following methods if the instance is running:
- Use the
dsconf backend export
command. See Section 6.2.1.1.1, “Exporting a Databases Using thedsconf backend export
Command”. - Create a
cn=tasks
entry. See Section 6.2.1.1.2, “Exporting a Database Using acn=tasks
Entry”.
- If the instance is offline, use the
dsctl db2ldif
command. See Section 6.2.1.2, “Exporting a Database While the Server is Offline”.
Important
/tmp
or /var/tmp/
directories because of the following reasons:
- Directory Server uses
PrivateTmp
feature ofsystemd
by default. If you place LDIF files into the/tmp
or/var/tmp/
system directory, Directory Server does not see these LDIF files during import. For more information aboutPrivateTmp
, seesystemd.exec(5)
man page. - LDIF files often contain sensitive data, such as user passwords. Therefore, you must not use temporary system directories to store these files.
6.2.1.1. Exporting a Database While the Server is Running
6.2.1.1.1. Exporting a Databases Using the dsconf backend export
Command
dsconf backend export
command to automatically create a task that exports data to an LDIF file.
userRoot
database:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backend export userRoot The export task has finished successfully
dsconf
stores the export in a file called instance_name_database_name-time_stamp.ldif
in the /var/lib/dirsrv/slapd-instance_name/export/
directory. Alternatively, add the -l file_name
option to the command to specify a different location.
dsconf backend export
command supports additional options, for example, to exclude a specific suffix. To display all available options, enter:
# dsconf ldap://server.example.com backend export --help
6.2.1.1.2. Exporting a Database Using a cn=tasks
Entry
cn=tasks,cn=config
entry in the Directory Server configuration is a container entry for temporary entries the server uses to manage tasks. To initiate an export operation, create a task in the cn=export,cn=tasks,cn=config
entry.
cn
: Sets the unique name of the task.nsInstance
: Sets the name of the database to export.nsFilename
: Sets the name of the file into which the export should be stored.
userRoot
database into the /var/lib/dirsrv/slapd-instance_name/ldif/example.ldif
file:
# ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com -x dn: cn=example_export,cn=export,cn=tasks,cn=config changetype: add objectclass: extensibleObject cn: example_export nsInstance: userRoot nsFilename: /var/lib/dirsrv/slapd-instance_name/ldif/example.ldif
6.2.1.2. Exporting a Database While the Server is Offline
dsctl db2ldif
command:
- Stop the instance:
# dsctl instance_name stop
- Export the database into an LDIF file. For example to export the
userRoot
database into the/var/lib/dirsrv/slapd-instance_name/ldif/example.ldif
file:# dsctl instance_name db2ldif userroot /var/lib/dirsrv/slapd-instance_name/ldif/example.ldif OK group dirsrv exists OK user dirsrv exists ldiffile: /var/lib/dirsrv/slapd-instance_name/ldif/example.ldif [18/Jul/2018:10:46:03.353656777 +0200] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000 [18/Jul/2018:10:46:03.383101305 +0200] - INFO - ldbm_back_ldbm2ldif - export userroot: Processed 160 entries (100%). [18/Jul/2018:10:46:03.391553963 +0200] - INFO - dblayer_pre_close - All database threads now stopped db2ldif successful
- Start the instance:
# dsctl instance_name start
6.2.2. Exporting a Suffix to an LDIF File Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the suffix entry.
- Click Export Suffix., and select
- Enter the name of the LDIF file in which you want to store the export. Directory Server will store the file in the
/var/lib/dirsrv/slapd-instance_name/ldif/
directory using the specified file name. - Click.
6.2.3. Enabling Members of a Group to Export Data and Performing the Export as One of the Group Members
cn=Directory Manager
in your scripts. Additionally, you can easily grant and revoke the export permissions by modifying the group.
6.2.3.1. Enabling a Group to Export Data
cn=export_users,ou=groups,dc=example,dc=com
group and enable members of this group to create export tasks.
Procedure
- Create the
cn=export_users,ou=groups,dc=example,dc=com
group:# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" group create --cn export_users
- Add access control instructions (ACI) that allows members of the
cn=export_users,ou=groups,dc=example,dc=com
group to create export tasks:# ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com dn: cn=config changetype: modify add: aci aci: (target = "ldap:///cn=export,cn=tasks,cn=config")(targetattr="*") (version 3.0 ; acl "permission: Allow export_users group to export data" ; allow (add, read, search) groupdn = "ldap:///cn=export_users,ou=groups,dc=example,dc=com";) - add: aci aci: (target = "ldap:///cn=config")(targetattr = "objectclass || cn || nsslapd-suffix || nsslapd-ldifdir") (version 3.0 ; acl "permission: Allow export_users group to access ldifdir attribute" ; allow (read,search) groupdn = "ldap:///cn=export_users,ou=groups,dc=example,dc=com";)
- Create a user:
- Create a user account:
# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" user create --uid="example" --cn="example" --uidNumber="1000" --gidNumber="1000" --homeDirectory="/home/example/" --displayName="Example User"
- Set a password on the user account:
# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" account reset_password "uid=example,ou=People,dc=example,dc=com" "password"
- Add the
uid=example,ou=People,dc=example,dc=com
user to thecn=export_users,ou=groups,dc=example,dc=com
group:# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" group add_member export_users uid=example,ou=People,dc=example,dc=com
Verification
- Display the ACIs set on the
cn=config
:# ldapsearch -o ldif-wrap=no -LLLx -D "cn=Directory Manager" -W -H ldap://server.example.com -b cn=config aci=* aci -s base dn: cn=config aci: (target = "ldap:///cn=export,cn=tasks,cn=config")(targetattr="*")(version 3.0 ; acl "permission: Allow export_users group to export data" ; allow (add, read, search) groupdn = "ldap:///cn=export_users,ou=groups,dc=example,dc=com";) aci: (target = "ldap:///cn=config")(targetattr = "objectclass || cn || nsslapd-suffix || nsslapd-ldifdir")(version 3.0 ; acl "permission: Allow export_users group to access ldifdir attribute" ; allow (read,search) groupdn = "ldap:///cn=export_users,ou=groups,dc=example,dc=com";) ...
6.2.3.2. Performing an Export as a Regular User
cn=Directory Manager
.
Prerequisites
- You enabled members of the
cn=export_users,ou=groups,dc=example,dc=com
group to export data. See Section 6.2.3.1, “Enabling a Group to Export Data”. - The user you use to perform the export is a member of the
cn=export_users,ou=groups,dc=example,dc=com
group.
Procedure
- Create a export task using one of the following methods:
- Using the
dsconf backend export
command:# dsconf -D "uid=example,ou=People,dc=example,dc=com" ldap://server.example.com backend export userRoot
- By manually creating the task:
# ldapadd -D "uid=example,ou=People,dc=example,dc=com" -W -H ldap://server.example.com dn: cn=userRoot-2021_07_23_12:55_00,cn=export,cn=tasks,cn=config changetype: add objectClass: extensibleObject nsFilename: /var/lib/dirsrv/slapd-instance_name/ldif/None-userroot-2021_07_23_12:55_00.ldif nsInstance: userRoot cn: export-2021_07_23_12:55_00
Verification
- Verify that the backup was created:
# ls -l /var/lib/dirsrv/slapd-instance_name/ldif/*.ldif total 0 -rw-------. 1 dirsrv dirsrv 10306 Jul 23 12:55 None-userroot-2021_07_23_12_55_00.ldif ...
6.3. Backing up Directory Server
- All database files including the data stored within these databases
Note
Directory Server does not support backing up individual databases. - The transaction logs
- The Indices
Warning
dirsrv
user. Therefore, the permissions of the destination directory must allow this user to create files.
6.3.1. Backing up All Databases Using the Command Line
- Use one of the following methods if the instance is running:
- Use the
dsconf backup create
command. See Section 6.3.1.1.1, “Backing up All Databases Using thedsconf backup create
Command”. - Create a
cn=tasks
entry. See Section 6.3.1.1.2, “Backing up All Databases Using acn=tasks
entry”.
- If the instance is offline, use the
dsctl db2bak
command. See Section 6.3.1.2, “Backing up All Databases While the Server is Offline”.
Important
6.3.1.1. Backing up All Databases While the Server is Running
6.3.1.1.1. Backing up All Databases Using the dsconf backup create
Command
dsconf backup create
command to automatically create a task that backs up all databases.
Important
# dsconf -D "cn=Directory Manager" ldap://server.example.com backup create The backup create task has finished successfully
dsconf
stores the backup in a subdirectory called instance_name-time_stamp
in the /var/lib/dirsrv/slapd-instance_name/bak/
directory. To specify a different location, append a directory name to the command.
6.3.1.1.2. Backing up All Databases Using a cn=tasks
entry
cn=tasks,cn=config
entry in the Directory Server configuration is a container entry for temporary entries the server uses to manage tasks. To initiate a backup operation, create a task in the cn=backup,cn=tasks,cn=config
entry.
cn
: Sets the unique name of the task.nsDatabaseType
: Sets the type of the database to back up. Directory Server supports only theldbm database
value in this attribute.
/var/lib/dirsrv/slapd-instance_name/bak/
. For a complete list, see the cn=backup section in the Red Hat Directory Server Configuration, Command, and File Reference.
# ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com -x dn: cn=example_backup,cn=export,cn=tasks,cn=config changetype: add objectclass: extensibleObject cn: example_backup nsDatabaseType: ldbm database
nsArchiveDir
attribute, the server stores the backup in a subdirectory called instance_name-time_stamp
in the /var/lib/dirsrv/slapd-instance_name/bak/
directory.
6.3.1.2. Backing up All Databases While the Server is Offline
dsctl db2bak
command:
- Stop the instance:
# dsctl instance_name stop
- Backup the database:
# dsctl instance_name db2bak db2bak successful
Note
Thedsctl db2bak
command runs as the backup as thedirsrv
user. Therefore, the permissions of the destination directory must allow this user to create files and directories.If you not append a destination directory to the command, the server stores the backup in a subdirectory calledinstance_name-time_stamp
in the/var/lib/dirsrv/slapd-instance_name/bak/
directory. - Start the instance:
# dsctl instance_name start
6.3.2. Backup up all Databases Using the Web Console
Important
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Click the Manage Backup.button, and select
- Click.
- Enter a name for the backup, such as a time stamp to indicate the creation date and time of the backup.
- Click.
/var/lib/dirsrv/slapd-instance_name/bak/
directory.
6.3.3. Backing up Configuration Files, the Certificate Database, and Custom Schema Files
/etc/dirsrv/slapd-instance_name/
directory which are required to, for example, restore a instance on a different server after a hardware failure.
Note
Example 6.2. How to Back up the /etc/dirsrv/slapd-instance_name/
Directory
/etc/dirsrv/slapd-instance_name/
, you can copy the directory or store it into an archive file. For example, to store the content of the /etc/dirsrv/slapd-instance_name/
directory in the /root/config_slapd-instance_name_time_stamp.tar.gz
file:
# cd /etc/dirsrv/ # tar -zcvf /root/config_slapd-instance_name_$(date +%Y-%m-%d_%H-%M-%S).tar.gz slapd-instance_name/
Important
6.3.4. Enabling Members of a Group to Back up Directory Server and Performing the Backup as One of the Group Members
cn=Directory Manager
in your backup script or cron jobs. Additionally, you can easily grant and revoke the backup permissions by modifying the group.
6.3.4.1. Enabling a Group to Back up Directory Server
cn=backup_users,ou=groups,dc=example,dc=com
group and enable members of this group to create backup tasks.
Procedure
- Create the
cn=backup_users,ou=groups,dc=example,dc=com
group:# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" group create --cn backup_users
- Add access control instructions (ACI) that allows members of the
cn=backup_users,ou=groups,dc=example,dc=com
group to create backup tasks:# ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com dn: cn=config changetype: modify add: aci aci: (target = "ldap:///cn=backup,cn=tasks,cn=config")(targetattr="*") (version 3.0 ; acl "permission: Allow backup_users group to create backup tasks" ; allow (add, read, search) groupdn = "ldap:///cn=backup_users,ou=groups,dc=example,dc=com";) - add: aci aci: (target = "ldap:///cn=config")(targetattr = "nsslapd-bakdir || objectClass") (version 3.0 ; acl "permission: Allow backup_users group to access bakdir attribute" ; allow (read,search) groupdn = "ldap:///cn=backup_users,ou=groups,dc=example,dc=com";)
- Create a user:
- Create a user account:
# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" user create --uid="example" --cn="example" --uidNumber="1000" --gidNumber="1000" --homeDirectory="/home/example/" --displayName="Example User"
- Set a password on the user account:
# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" account reset_password "uid=example,ou=People,dc=example,dc=com" "password"
- Add the
uid=example,ou=People,dc=example,dc=com
user to thecn=backup_users,ou=groups,dc=example,dc=com
group:# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" group add_member backup_users uid=example,ou=People,dc=example,dc=com
Verification
- Display the ACIs set on the
cn=config
entry:# ldapsearch -o ldif-wrap=no -LLLx -D "cn=directory manager" -W -H ldap://server.example.com -b cn=config aci=* aci -s base dn: cn=config aci: (target = "ldap:///cn=backup,cn=tasks,cn=config")(targetattr="*")(version 3.0 ; acl "permission: Allow backup_users group to create backup tasks" ; allow (add, read, search) groupdn = "ldap:///cn=backup_users,ou=groups,dc=example,dc=com";) aci: (target = "ldap:///cn=config")(targetattr = "nsslapd-bakdir || objectClass")(version 3.0 ; acl "permission: Allow backup_users group to access bakdir attribute" ; allow (read,search) groupdn = "ldap:///cn=backup_users,ou=groups,dc=example,dc=com";) ...
6.3.4.2. Performing a Backup as a Regular User
cn=Directory Manager
.
Prerequisites
- You enabled members of the
cn=backup_users,ou=groups,dc=example,dc=com
group to perform backups. See Section 6.3.4.1, “Enabling a Group to Back up Directory Server”. - The user you use to perform the backup is a member of the
cn=backup_users,ou=groups,dc=example,dc=com
group.
Procedure
- Create a backup task using one of the following methods:
- Using the
dsconf backup create
command:# dsconf -D uid=example,ou=People,dc=example,dc=com ldap://server.example.com backup create
- By manually creating the task:
# ldapadd -D uid=example,ou=People,dc=example,dc=com -W -H ldap://server.example.com dn: cn=backup-2021_07_23_12:55_00,cn=backup,cn=tasks,cn=config changetype: add objectClass: extensibleObject nsarchivedir: /var/lib/dirsrv/slapd-instance_name/bak/backup-2021_07_23_12:55_00 nsdatabasetype: ldbm database cn: backup-2021_07_23_12:55_00
Verification
- Verify that the backup was created:
# ls -l /var/lib/dirsrv/slapd-instance_name/bak/ total 0 drwx------. 3 dirsrv dirsrv 108 Jul 23 12:55 backup-2021_07_23_12_55_00 ...
6.4. Restoring Directory Server
Note
dirsrv
user. Therefore, the permissions of the directory containing the backup must allow this user to read the files.
6.4.1. Restoring All Databases Using the Command Line
- Use one of the following methods if the instance is running:
- Use the
dsconf backup restore
command. See Section 6.4.1.1.1, “Restoring All Databases Using thedsconf backup restore
Command”. - Create a
cn=tasks
entry. See Section 6.4.1.1.2, “Restoring all Databases Using acn=tasks
entry”.
- If the instance is offline, use the
dsctl bak2db
command. See Section 6.4.1.2, “Restoring all Databases While the Server is Offline”.
6.4.1.1. Restoring All Databases While the Server is Running
6.4.1.1.1. Restoring All Databases Using the dsconf backup restore
Command
dsconf backup restore
command to automatically create a task that restores up all databases from a backup directory.
/var/lib/dirsrv/slapd-instance_name/bak/instance_name-time_stamp/
directory:
# dsconf -D "cn=Directory Manager" ldap://server.example.com backup restore /var/lib/dirsrv/slapd-instance_name/bak/instance_name-time_stamp/ The backup restore task has finished successfully
6.4.1.1.2. Restoring all Databases Using a cn=tasks
entry
cn=tasks,cn=config
entry in the Directory Server configuration is a container entry for temporary entries the server uses to manage tasks. To initiate a restore operation, create a task in the cn=restore,cn=tasks,cn=config
entry.
Warning
cn
: Sets the unique name of the task.nsArchiveDir
: Sets the path to the directory that contains the backup.nsDatabaseType
: Sets the type of the database to restore. Directory Server supports only theldbm database
value in this attribute.
/var/lib/dirsrv/slapd-instance_name/bak/instance_name-time_stamp/
directory:
# ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com -x dn: cn=example_restore,cn=import,cn=tasks,cn=config changetype: add objectclass: extensibleObject cn: example_restore nsArchiveDir: /var/lib/dirsrv/slapd-instance_name/bak/instance_name-time_stamp/ nsDatabaseType: ldbm database
6.4.1.2. Restoring all Databases While the Server is Offline
dsctl bak2db
command:
- Stop the instance:
# dsctl instance_name stop
- Restore the databases. For example, to add a task that restores all databases from the backup stored in the
/var/lib/dirsrv/slapd-instance_name/bak/instance_name-time_stamp/
directory:# dsctl instance_name bak2db /var/lib/dirsrv/slapd-instance_name/bak/instance_name-time_stamp/ bak2db successful
Note
Thedsctl bak2db
command runs as the restore as thedirsrv
user. Therefore, the permissions of the source directory must allow this user to read files and directories. - Start the instance:
# dsctl instance_name start
6.4.2. Restoring All Databases Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Click the Manage Backups.button, and selectThe displayed window lists the available backups in the
/var/lib/dirsrv/slapd-instance_name/bak/
directory. - Open the Actions menu next to the backup you want to restore, and select .
- Clickto confirm.
6.4.3. 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.8.3, “Initializing a Consumer”.
Example 6.3. Restoring a Directory Server Replication Topology
- Restore the first supplier. Use the
dsconf backend import
command to import the data. See Section 6.1.2, “Importing Using the Command Line”. - Online-initialize the remaining servers by using replication:
- Initialize the second supplier from the first one.
- Initialize the consumers from the supplier.
For details, see Section 15.8.3, “Initializing a Consumer”. - On each server, display the replication status to verify that replication works correctly. For details, see Section 15.22, “Displaying the Status of a Specific Replication Agreement”.
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
:
dsconf -D "cn=Directory Manager" ldap://server.example.com plugin attr-uniq add "Example" --attr-name uid
7.1.2. Configuring Attribute Uniqueness over Suffixes or Subtrees
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:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin attr-uniq enable "mail Attribute Uniqueness"
- 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:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin attr-uniq set "mail Attribute Uniqueness" --attr-name mail --subtree ou=Engineering,dc=example,dc=com ou=Sales,dc=example,dc=com
- Optionally, to configure uniqueness across all subtrees configured in this plug-in configuration record:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin attr-uniq set "mail Attribute Uniqueness" --across--all-subtrees=on
- Restart the instance:
# dsctl instance_name restart
7.1.2.2. Configuring Attribute Uniqueness over Suffixes or Subtrees Using the Web Console
mail
attributes are unique:
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the Attribute Uniqueness plug-in.
- Click.
- Fill the fields, and enable the config. For example:
Figure 7.1. Adding an Attribute Uniqueness Configuration
- Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.
7.1.3. Configuring Attribute Uniqueness over Object Classes
uniqueness-attribute-name
is unique in this subtree.
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:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin attr-uniq enable "mail Attribute Uniqueness"
- Configure that values stored in
mail
attributes must be unique under the entry that contains thensContainer
object class:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin attr-uniq set "mail Attribute 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:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin attr-uniq set "mail Attribute Uniqueness" --subtree-entries-oc=inetOrgPerson
- Restart the instance:
# dsctl instance_name restart
7.1.4. Attribute Uniqueness Plug-in Configuration Parameters
cn=attribute_uniqueness_configuration_record_name,cn=plugins,cn=config
entry.
Example 7.1. Attribute Uniqueness Plug-in Configuration Using Plug-in-specific Attributes
dn: cn=Example Attribute Uniqueness,cn=plugins,cn=config nsslapd-pluginEnabled: on uniqueness-attribute-name: attribute_name uniqueness-top-entry-oc: objectclass1 uniqueness-subtree-entries-oc: objectclass2
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.2, “Sample Pointer CoS”.
Figure 7.2. 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.3, “Sample Indirect CoS”.
Figure 7.3. 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.4. 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 from the Command Line
7.2.10.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.2, “An Example Pointer CoS Entry”.
Example 7.2. An Example Pointer CoS Entry
dn: cn=pointerCoS,dc=example,dc=com objectclass: top objectclass: cosSuperDefinition objectclass:cosPointerDefinition
cosTemplateDn
:DN_string cosAttribute:list_of_attributes qualifier cn: pointerCoS
cosIndirectDefinition
object class. This type of CoS identifies the template entry based on the value of one of the target entry's attributes, as specified in the cosIndirectSpecifier
attribute. This is illustrated in Example 7.3, “An Example Indirect CoS Entry”.
Example 7.3. An Example Indirect CoS Entry
dn: cn=indirectCoS,dc=example,dc=com objectclass: top objectclass: cosSuperDefinition objectclass:cosIndirectDefinition
cosIndirectSpecifier
:attribute_name cosAttribute:list_of_attributes qualifier cn: indirectCoS
cosClassicDefinition
object class. This identifies the template entry using both the template entry's DN (set in the cosTemplateDn
attribute) and the value of one of the target entry's attributes (set in the cosSpecifier
attribute). This is illustrated in Example 7.4, “An Example Classic CoS Entry”.
Example 7.4. An Example Classic CoS Entry
dn: cn=classicCoS,dc=example,dc=com objectclass: top objectclass: cosSuperDefinition objectclass:cosClassicDefinition
cosTemplateDn
:DN_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.10.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.10.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
:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=pointerCoS,dc=example,dc=com changetype: add objectclass: top objectclass: cosSuperDefinition objectclass: cosPointerDefinition cosTemplateDn: cn=exampleUS,ou=data,dc=example,dc=com cosAttribute: postalCode
- Create the template entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=exampleUS,ou=data,dc=example,dc=com changetype: add objectclass: top objectclass: extensibleObject objectclass: cosTemplate postalCode: 44438
cn=exampleUS,ou=data,dc=example,dc=com
) supplies the value stored in its postalCode
attribute to any entries located under the dc=example,dc=com
suffix. These entries are the target entries.
7.2.10.4. Example of an Indirect CoS
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
:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=indirectCoS,dc=example,dc=com changetype: add objectclass: top objectclass: cosSuperDefinition objectclass: cosIndirectDefinition cosIndirectSpecifier: manager cosAttribute: departmentNumber
departmentNumber
attribute, then no other attribute needs to be added to the manager entries. The definition entry looks in the target suffix (the entries under dc=example,dc=com
) for entries containing the manager
attribute because this attribute is specified in the cosIndirectSpecifier
attribute of the definition entry). It then checks the departmentNumber
value in the manager entry that is listed. The value of the departmentNumber
attribute will automatically be relayed to all of the manager's subordinates that have the manager
attribute. The value of departmentNumber
will vary depending on the department number listed in the different manager's entries.
7.2.10.5. Example of a Classic CoS
cosSpecifier
attribute.
- Add a new classic CoS definition entry to the
dc=example,dc=com
suffix usingldapmodify
:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=classicCoS,dc=example,dc=com changetype: add objectclass: top objectclass: cosSuperDefinition objectclass: cosClassicDefinition cosTemplateDn: cn=classicCoS,dc=example,dc=com cosSpecifier: businessCategory cosAttribute: postalCode override
- 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:# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=sales,cn=classicCoS,dc=example,dc=com changetype: add objectclass: top objectclass: extensibleObject objectclass: cosTemplate postalCode: 44438 - dn: cn=marketing,cn=classicCoS,dc=example,dc=com changetype: add objectclass: top objectclass: extensibleObject objectclass: cosTemplate postalCode: 99111
dc=example,dc=com
suffix. Depending upon the combination of the businessCategory
attribute found in the entry and the cosTemplateDn
, it can arrive at one of two templates. One, the sales template, provides a postal code specific to employees in the sales department. The marketing template provides a postal code specific to employees in the marketing department.
7.2.10.6. Searching for CoS Entries
ldapSubEntry
object class to the CoS definition entries. For example:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=pointerCoS,ou=People,dc=example,dc=com changetype: add objectclass: ldapSubEntry
(objectclass=ldapSubEntry)
filter with the ldapsearch
utility to search for entries containing the ldapSubEntry
object class. For example:
# ldapsearch -x -s sub -b ou=People,dc=example,dc=com "(|(objectclass=*)(objectclass=ldapSubEntry))"
ou=People,dc=example,dc=com
subtree.
7.2.10.7. The costargettree attribute
costargettree
attribute defines the subtrees to which the CoS schema applies. The values for costargettree
for the schema and for multiple CoS schema may overlap their target trees arbitrarily.
OID | 2.16.840.1.113730.3.1.552 |
Syntax | DirectoryString |
Multi or Single-Valued | Single-valued |
Defined in | Directory Server |
7.2.11. Creating Role-Based Attributes
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
Warning
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.5. Basic Linked Attribute Configuration
Note
Figure 7.6. 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-supplier 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.5. Example Linked Attributes Plug-in Instance Entry
dn: cn=Manager Link,cn=Linked Attributes,cn=plugins,cn=config objectClass: top objectClass: extensibleObject cn: Manager Link linkType: directReport managedType: manager linkScope: ou=people,dc=example,dc=com
7.3.3. Configuring Attribute Links
- If it is not already enabled, enable the Linked Attributes plug-in. For details, see Section 1.10.2, “Enabling and Disabling Plug-ins”.f
- Create the plug-in instance. Both the
--managed-type
and--link-type
parameters are required. The following example shows the plug-in instance created by usingdsconf
:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin linked-attr config "Manager Link" add --link-type=directReport --managed-type=manager
- Restart the instance:
# dsctl instance_name restart
7.3.4. Cleaning up Attribute Links
dsconf plugin linked-attr fixup
command or by launching a fix-up task.
7.3.4.1. Regenerating Linked Attributes
dsconf plugin linked-attr fixup
command 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.
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin linked-attr fixup
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin linked-attr fixup "cn=Manager Link,cn=Linked Attributes,cn=plugins,cn=config"
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.
dsconf plugin linked-attr fixup
command 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
:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x 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
....The DNA Plug-in only generates new, unique values. If an entry is added or modified to use a specific value for an attribute controlled by the DNA Plug-in, the specified number is used; the DNA Plug-in will not overwrite it.
7.4.1.3. Multiple Attributes in the Same Range
- 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.6. 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. Creating a New Instance of the DNA Plug-in
Note
- For example, to create a new instance of the plug-in:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin dna config "Account UIDs" add --type uidNumber --filter "(objectclass=posixAccount)" --scope ou=People,dc=example,dc=com --next-value 1 --max-value 1300 --shared-config-entry "cn=Account UIDs,ou=Ranges,dc=example,dc=com" --threshold 100 --range-request-timeout 60 --magic-regen magic
For details about the value you can set in the--magic-regen
parameter, see thednaMagicRegen
attribute description in the Configuration, Command and File Reference. - Enable the DNA plug-in. For details, see Section 1.10.2, “Enabling and Disabling Plug-ins”.
7.4.3.2. Configuring Unique Number Assignments Using the Command Line
Note
dnaNextvalue
is already taken, which requires an equality index on an integer attribute, with the proper ordering matching rule.
Note
- Create a new instance of the plug-in. See Section 7.4.3.1, “Creating a New Instance of the DNA Plug-in”.
- Create the shared container entry in the replicated subtree:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: ou=Ranges,dc=example,dc=com changetype: add objectclass: top objectclass: extensibleObject objectclass: organizationalUnit ou: Ranges - dn: cn=Account UIDs,ou=Ranges,dc=example,dc=com changetype: add objectclass: top objectclass: extensibleObject cn: Account UIDs
- Restart the instance:
# dsctl instance_name restart
7.4.3.3. Configuring Unique Number Assignments Using the Web Console
- Create a new instance of the plug-in. See Section 7.4.3.1, “Creating a New Instance of the DNA Plug-in”.
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select the DNA plug-in.
- Change the status to
ON
to enable the plug-in. - Click.
- Fill the fields, and enable the config.
- Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.
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. The Different Types of Groups
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
.
Type of Group | Group Object Classes | Member Attributes |
---|---|---|
Static | groupOfNames [a] | member |
groupOfUniqueNames [a] | uniqueMember | |
Dynamic | groupOfURLs | memberURL |
groupOfCertificates | memberCertificate | |
[a]
If this object class is used together with one of the dynamic object classes, the group becomes dynamic.
|
Example 8.1. A Static Group Entry
objectClass: top objectClass: groupOfUniqueNames cn: static group description: Example static group. uniqueMember: uid=mwhite,ou=People,dc=example,dc=com uniqueMember: uid=awhite,ou=People,dc=example,dc=com
Example 8.2. A Dynamic Group Entry
groupOfUniqueNames
, can explicitly list some group members along with the dynamic LDAP URL. For example:
objectClass: top objectClass: groupOfUniqueNames objectClass: groupOfURLs cn: dynamic group description: Example dynamic group. memberURL: ldap:///dc=example,dc=com??sub?(&(objectclass=person)(cn=*sen*))
Note
memberURL
attribute instead of listing the group members in an attribute, the memberOf plug-in does not add the memberOf
attribute to the user objects that match the filter.
8.1.2. Creating a Static Group
8.1.2.1. Creating a Static Group Using the Command Line
Creating a Static Group with the groupOfNames
Object Class
dsidm
utility creates static groups in the cn=Groups
entry in the specified base DN.
example_group
group with the groupOfNames
object class in the cn=Groups,dc=example,dc=com
entry
# dsidm -D "cn=Directory Manager" ldap://server.example.com -b "dc=example,dc=com" group create --cn "example_group"
Creating a Static Group with the groupOfUniqueNames
Object Class
groupOfUniqueNames
object class, use the ldapmodify
utility to add the entry.
example_group
group with the groupOfUniqueNames
object class in the cn=Groups,dc=example,dc=com
entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=example_group,cn=Groups,dc=example,dc=com changetype: add objectClass: top objectClass: groupOfUniqueNames cn: example_group description: Example static group with unique members
8.1.3. Creating a Dynamic Group
8.1.3.1. Creating a Dynamic Group Using the Command Line
Creating a Dynamic Group with the groupOfURLs
Object Class
example_group
group with the groupOfURLs
object class in the cn=Groups,dc=example,dc=com
entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=example_group,cn=Groups,dc=example,dc=com changetype: add objectClass: top objectClass: groupOfURLs cn: example_group description: Example dynamic group for user entries memberURL: ldap:///dc=example,dc=com??sub?(&(objectclass=person)(cn=*sen*))
Creating a Dynamic Group with the groupOfCertificates
Object Class
example_group
group with the groupOfCertificates
object class in the cn=Groups,dc=example,dc=com
entry:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=example_group,cn=Groups,dc=example,dc=com changetype: add objectClass: top objectClass: groupOfURLs cn: example_group description: Example dynamic group for certificate entries memberCertificate: ...
8.1.4. Listing Group Membership in User Entries
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 supplier 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 supplier servers in the topology. For this:- You must disable replication of the
memberOf
attribute to all write-enabled suppliers 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.5.2, “Configuring the MemberOf Plug-in on Each Server Using the Web Console”.
8.1.4.2. Required Object Classes by the memberOf
Plug-In
memberOf
plug-in By default, the memberOf
plug-in will add the MemberOf
object class to objects to provide the memberOf
attribute. This object class is safe to add to any object for this purpose, and no further action is required to enable this plug-in to operate correctly. Alternatively, you can create user objects that contain the inetUser
or inetAdmin,
object class. Both object classes support the memberOf
attribute as well.
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.3. 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. Enabling the MemberOf Plug-in
8.1.4.4.1. Enabling the MemberOf Plug-in Using the Command Line
- Use the
dsconf
utility to enable the plug-in:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof enable
- Restart the instance:
# dsctl instance_name restart
8.1.4.4.2. Enabling the MemberOf Plug-in Using the Web Console
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Select themenu.
- Select the MemberOf plug-in.
- Change the status to
ON
to enable the plug-in. - Restart the instance. See Section 1.5.2, “Starting and Stopping a Directory Server Instance Using the Web Console”.
8.1.4.5. Configuring the MemberOf Plug-in on Each Server
8.1.4.5.1. Configuring the MemberOf Plug-in on Each Server Using the Command Line
- Enable the plug-in. See Section 8.1.4.4.1, “Enabling the MemberOf Plug-in Using the Command Line”.
- To retrieve members of a group from a different attribute than
member
, which is the default, set thememberOfGroupAttr
parameter to the respective attribute name.For example, to read group members fromuniqueMember
attributes, replace the current value ofmemberOfGroupAttr
:- Optionally, display the attribute that is currently configured:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof show ... memberofgroupattr: member ...
The command displays that currently only themember
attribute is configured to retrieve members of a group. - Remove all attributes from the configuration that currently set:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --groupattr delete Successfully changed the cn=MemberOf Plugin,cn=plugins,cn=config
Note
It is not possible to remove a specific group attribute. - Add the
uniqueMember
attribute to the configuration:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --groupattr uniqueMember successfully added memberOfGroupAttr value "uniqueMember"
To set multiple attributes, pass them all to the--groupattr
parameter. For example:# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memberof set --groupattr member uniqueMember ...
- By default, the MemberOf plug-in adds the
memberOf
attribute to user entries. To use a different attribute, set the name of the attribute in thememberOfAttr
parameter.For example, to add thecustomMemberOf
attribute to user records, replace the current value ofmemberOfAttr
:- Optionally, display the attribute that is currently configured:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin memb