2.2. Creating and Maintaining Databases

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

2.2.1. Creating Databases

The directory tree can be distributed over multiple Directory Server databases. There are two ways to distribute data across multiple databases:
One database per suffix. The data for each suffix is contained in a separate database.
Three databases are added to store the data contained in separate suffixes:
This division of the tree units corresponds to three databases, for example:
In this example, DB1 contains the data for ou=people and the data for dc=example,dc=com, so that clients can conduct searches based at dc=example,dc=com. However, DB2 only contains the data for ou=groups, and DB3 only contains the data for ou=contractors:
Multiple databases for one suffix.
Suppose the number of entries in the ou=people branch of the directory tree is so large that two databases are needed to store them. In this case, the data contained by ou=people could be distributed across two databases:
DB1 contains people with names from A-K, and DB2 contains people with names from L-Z. DB3 contains the ou=groups data, and DB4 contains the ou=contractors data.
A custom plug-in distributes data from a single suffix across multiple databases. Contact Red Hat Consulting for information on how to create distribution logic for Directory Server.

2.2.1.1. Creating a New Database for an Existing Suffix Using the Console

  1. In the Directory Server Console, select the Configuration tab.
  2. In the left pane, expand Data, then click the suffix to which to add the new database.
  3. Right-click the suffix, and select New Database from the pop-up menu.
  4. Enter a unique name for the database, such as example2. The database name can be a combination of alphanumeric characters, dashes (-), and underscores (_).
    The Create database in field is automatically filled with the default database directory (/var/lib/dirsrv/slapd-instance/db) and the name of the new database. It is also possible to enter or browse for a different directory location.

2.2.1.2. Creating a New Database for a Single Suffix from the Command Line

Use the ldapmodify command-line utility to add a new database to the directory configuration file. The database configuration information is stored in the cn=ldbm database,cn=plugins,cn=config entry. For example, add a new database to the server example1:
  1. Run ldapmodify and create the entry for the new database.
    # ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    
    dn: cn=UserData,cn=ldbm database,cn=plugins,cn=config
    changetype: add
    objectclass: extensibleObject
    objectclass: nsBackendInstance
    nsslapd-suffix: ou=people,dc=example,dc=com
    The added entry corresponds to a database named UserData that contains the data for the root or sub suffix ou=people,dc=example,dc=com.
  2. Create a root or a sub-suffix, as described in Section 2.1.1.3, “Creating Root and Sub Suffixes using the Command Line”. The database name, given in the DN attribute, must correspond with the value in the nsslapd-backend attribute of the suffix entry.

2.2.1.3. Adding Multiple Databases for a Single Suffix

A single suffix can be distributed across multiple databases. However, to distribute the suffix, a custom distribution function has to be created to extend the directory. For more information on creating a custom distribution function, contact Red Hat Consulting.

Note

Once entries have been distributed, they cannot be redistributed. The following restrictions apply:
  • The distribution function cannot be changed once entry distribution has been deployed.
  • The LDAP modrdn operation cannot be used to rename entries if that would cause them to be distributed into a different database.
  • Distributed local databases cannot be replicated.
  • The ldapmodify operation cannot be used to change entries if that would cause them to be distributed into a different database.
Violating these restrictions prevents Directory Server from correctly locating and returning entries.
After creating a custom distribution logic plug-in, add it to the directory.
The distribution logic is a function declared in a suffix. This function is called for every operation reaching this suffix, including subtree search operations that start above the suffix. A distribution function can be inserted into a suffix using both the Console and the command line interface.
2.2.1.3.1. Adding the Custom Distribution Function to a Suffix Using the Directory Server Console
  1. In the Directory Server Console, select the Configuration tab.
  2. Expand Data in the left navigation pane. Select the suffix to which to apply the distribution function.
  3. Select the Databases tab in the right window.
  4. The databases associated with the suffix are already listed in the Databases tab. Click Add to associate additional databases with the suffix.
  5. Enter the path to the distribution library.
  6. Enter the name of the distribution function in the Function name field.
2.2.1.3.2. Adding the Custom Distribution Function to a Suffix Using the Command Line
  1. Run ldapmodify.
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
  2. Add the following attributes to the suffix entry itself, supplying the information about the custom distribution logic:
    dn: suffix
    changetype: modify
    add: nsslapd-backend
    nsslapd-backend: Database1
    -
    add: nsslapd-backend
    nsslapd-backend: Database2
    -
    add: nsslapd-backend
    nsslapd-backend: Database3
    -
    add: nsslapd-distribution-plugin
    nsslapd-distribution-plugin: /full/name/of/a/shared/library
    -
    add: nsslapd-distribution-funct
    nsslapd-distribution-funct: distribution-function-name
    The nsslapd-backend attribute specifies all databases associated with this suffix. The nsslapd-distribution-plugin attribute specifies the name of the library that the plug-in uses. The nsslapd-distribution-funct attribute provides the name of the distribution function itself.
For more information about using the ldapmodify command-line utility, see Section 3.1, “Managing Entries Using the Command Line”.

2.2.2. Maintaining Directory Databases

2.2.2.1. Placing a Database in Read-Only Mode

When a database is in read-only mode, you cannot create, modify, or delete any entries. One of the situations when read-only mode is useful is for manually initializing a consumer or before backing up or exporting data from the Directory Server. Read-only mode ensures a faithful image of the state of these databases at a given time.
The Directory Server Console and the command-line utilities do not automatically put the directory in read-only mode before export or backup operations because this would make your directory unavailable for updates. However, with multi-master replication, this might not be a problem.
2.2.2.1.1. Making a Database Read-Only Using the Console
  1. In the Directory Server Console, select the Configuration tab.
  2. Expand Data in the left pane. Expand the suffix containing the database to put in read-only mode.
  3. Select the database to put into read-only mode.
  4. Select the Database Settings tab in the right pane.
  5. Select the database is read-only check box.
The change takes effect immediately.
Before importing or restoring the database, ensure that the databases affected by the operation are not in read-only mode.
To disable read-only mode, open the database up in the Directory Server Console again and uncheck the database is read-only check box.
2.2.2.1.2. Making a Database Read-Only from the Command Line
To manually place a database into read-only mode:
  1. Run ldapmodify.
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
  2. Change the read-only attribute to on
    dn: cn=database_name,cn=ldbm database,cn=plugins,cn=config
    changetype: modify
    replace: nsslapd-readonly
    nsslapd-readonly: on

Note

By default, the name of the database created at installation time is userRoot.
2.2.2.1.3. Placing the Entire Directory Server in Read-Only Mode
If the Directory Server maintains more than one database and all databases need to be placed in read-only mode, this can be done in a single operation.

Warning

This operation also makes the Directory Server configuration read-only; therefore, you cannot update the server configuration, enable or disable plug-ins, or even restart the Directory Server while it is in read-only mode. Once read-only mode is enabled, it cannot cannot be undone from the Console; you must modify the configuration files.

Note

If Directory Server contains replicas, do not use read-only mode because it will disable replication.
To put the Directory Server in read-only mode:
  1. In the Directory Server Console, select the Configuration tab, and then select the top entry in the navigation tree in the left pane.
  2. Select the Settings tab in the right pane.
  3. Select the Make Entire Server Read-Only check box.
  4. Click Save, and then restart the server.

2.2.2.2. Deleting a Database

Deleting a database deletes the configuration information and entries for that database only, not the physical database itself.
  1. In the Directory Server Console, select the Configuration tab.
  2. Expand the Data folder, and then select the suffix.
  3. Select the database to delete.
  4. Right-click the database and select Delete from the pop-up menu.
  5. Confirm that the database should be deleted in the Delete Database dialog box.

2.2.2.3. Changing the Transaction Log Directory

The transaction log enables Directory Server to recover the database, after an instance shut down unexpectedly. In certain situations, administrators want to change the path to the transaction logs. For example, to store them on a different physical disk than the Directory Server database.

Note

To achieve higher performance, mount a faster disk to the directory that contains the transaction logs, instead of changing the location. For details, see the corresponding section in the Red Hat Directory Server Performance Tuning Guide.
To change the location of the transaction log directory:
  1. Stop the Directory Server instance:
    # systemctl stop dirsrv@instance_name
  2. Create a new location for the transaction logs. For example:
    # mkdir -p /srv/dirsrv/instance_name/db/
  3. Set permissions to enable only Directory Server to access the directory:
    # chown dirsrv:dirsrv /srv/dirsrv/instance_name/db/
    # chmod 770 /srv/dirsrv/instance_name/db/
  4. Remove all __db.* files from the previous transaction log directory. For example:
    # rm /var/lib/dirsrv/slapd-instance_name/db/__db.*
  5. Move all log.* files from the previous to the new transaction log directory. For example:
    # mv /var/lib/dirsrv/slapd-instance_name/db/log.* \
         /srv/dirsrv/instance_name/db/
  6. If SELinux is running in enforcing mode, set the dirsrv_var_lib_t context on the directory:
    # semanage fcontext -a -t dirsrv_var_lib_t /srv/dirsrv/instance_name/db/
    # restorecon -Rv /srv/dirsrv/instance_name/db/
  7. Edit the /etc/dirsrv/slapd-instance_name/dse.ldif file, and update the nsslapd-db-logdirectory parameter under the cn=config,cn=ldbm database,cn=plugins,cn=config entry. For example:
    dn: cn=config,cn=ldbm database,cn=plugins,cn=config
    ...
    nsslapd-db-logdirectory: /srv/dirsrv/instance_name/db/
  8. Start the instance:
    # systemctl start dirsrv@instance_name