3.2. Creating and Maintaining Databases

After creating suffixes to organizing the directory data, create databases to contain that directory data. Databases are used to store directory data.

3.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 corresponds to three databases.
    Database one contains the data for ou=people plus the data for dc=example,dc=com, so that clients can conduct searches based at dc=example,dc=com. Database two contains the data for ou=groups, and database three 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.
    Custom distribution plug-in distributes data from a single suffix across multiple databases. Contact Red Hat Professional Services for information on how to create distribution logic for Directory Server. 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.
    The Create New Database dialog box is displayed.
  4. In the Create New Database dialog box, enter a unique name for the database, such as example2. The database name can be a combination of alphanumeric characters, dashes (-), and underscores (_). No other characters are allowed.
  5. In the Create database in field, enter the path to the directory to store the new database. Alternatively, click Browse to locate a directory on the local machine.
    By default, the directory stores the new database in the /var/lib/dirsrv/slapd-instance_name/db directory.
  6. Click OK. Click Yes in the confirmation dialog to create the new database. 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:[2]
    ldapmodify -a -h example1 -p 389 -D "cn=directory manager" -w secret
    The ldapmodify utility binds to the server and prepares it to add an entry to the configuration file.
  2. Create the entry for the new database.
    dn: cn=UserData,cn=ldbm database,cn=plugins,cn=config
    objectclass: extensibleObject
    objectclass: nsBackendInstance
    nsslapd-suffix: ou=people,dc=example,dc=com
    The entry added corresponds to a database named UserData that contains the data for the root or sub suffix ou=people,dc=example,dc=com.
  3. Create a root or sub suffix, as described in Section, “Creating Root and Sub Suffixes from 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. 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 Professional Services.


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. 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. Click Add to associate additional databases with the suffix.
    The Database List dialog box is displayed. Select a database from the list, and click OK.
  5. Enter the path to the distribution library in the Distribution library field, or click Browse to locate a distribution library on the local machine.
  6. Enter the name of the distribution function in the Function name field.
  7. Click Save. Adding the Custom Distribution Function to a Suffix Using the Command Line
  1. Run ldapmodify.[2]
    ldapmodify -p 389 -D "cn=directory manager" -w secret -h us.example.com
  2. Add the following attributes to the suffix entry itself, supplying the information about the custom distribution logic:
    nsslapd-backend: Database1 
    nsslapd-backend: Database2 
    nsslapd-backend: Database3 
    nsslapd-distribution-plugin: /full/name/of/a/shared/library 
    The nsslapd-backend attribute specifies all of the 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 2.2.4, “Adding and Modifying Entries Using ldapmodify”.