Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

2.2. Creating and Maintaining Databases

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

Note

If you used the dsconf utility or the web console to create the suffix, Directory Server created the database automatically.

2.2.1. Creating Databases

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

2.2.1.1. Creating a New Database for a Single Suffix Using the Command Line

Use the ldapmodify command-line utility to add a new database to the directory configuration file. The database configuration information is stored in the cn=ldbm database,cn=plugins,cn=config entry. To add a new database:
  1. Run ldapmodify and create the entry for the new database. 
    # ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=UserData,cn=ldbm database,cn=plugins,cn=config
changetype: add
objectclass: extensibleObject
objectclass: nsBackendInstance
nsslapd-suffix: ou=people,dc=example,dc=com
    The added entry corresponds to a database named UserData that contains the data for the root or sub-suffix ou=people,dc=example,dc=com.
  2. Create a root or a sub-suffix, as described in Section 2.1.1.1.1, “Creating a Root Suffix Using the Command Line” and Section 2.1.1.2.1, “Creating a Sub-suffix Using the Command Line”. The database name, given in the DN attribute, must correspond with the value in the nsslapd-backend attribute of the suffix entry.

2.2.1.2. Adding Multiple Databases for a Single Suffix

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

Note

Once entries have been distributed, they cannot be redistributed. The following restrictions apply:
  • The distribution function cannot be changed once entry distribution has been deployed.
  • The LDAP modrdn operation cannot be used to rename entries if that would cause them to be distributed into a different database.
  • Distributed local databases cannot be replicated.
  • The ldapmodify operation cannot be used to change entries if that would cause them to be distributed into a different database.
Violating these restrictions prevents Directory Server from correctly locating and returning entries.
After creating a custom distribution logic plug-in, add it to the directory.
The distribution logic is a function declared in a suffix. This function is called for every operation reaching this suffix, including subtree search operations that start above the suffix. A distribution function can be inserted into a suffix using both the web console and the command line interface.
To add a custom distribution function to a suffix:
  1. Run ldapmodify. 
    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
  2. Add the following attributes to the suffix entry itself, supplying the information about the custom distribution logic: 
    dn: suffix
changetype: modify
add: nsslapd-backend
nsslapd-backend: Database1
-
add: nsslapd-backend
nsslapd-backend: Database2
-
add: nsslapd-backend
nsslapd-backend: Database3
-
add: nsslapd-distribution-plugin
nsslapd-distribution-plugin: /full/name/of/a/shared/library
-
add: nsslapd-distribution-funct
nsslapd-distribution-funct: distribution-function-name
    The nsslapd-backend attribute specifies all databases associated with this suffix. The nsslapd-distribution-plugin attribute specifies the name of the library that the plug-in uses. The nsslapd-distribution-funct attribute provides the name of the distribution function itself.

2.2.2. Maintaining Directory Databases

2.2.2.1. Setting a Database in Read-Only Mode

When a database is in read-only mode, you cannot create, modify, or delete any entries. One of the situations when read-only mode is useful is for manually initializing a consumer or before backing up or exporting data from Directory Server. Read-only mode ensures a faithful image of the state of these databases at a given time.
The command-line utilities and the web console do not automatically put the directory in read-only mode before export or backup operations because this would make your directory unavailable for updates. However, with multi-supplier replication, this might not be a problem.
2.2.2.1.1. Setting a Database in Read-only Mode Using the Command Line
To set a database in read-only mode, use the dsconf backend suffix set command. For example, to set the database of the o=test suffix in read-only mode:
  1. Display the suffixes and their corresponding back end: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list
dc=example,dc=com (userroot)
o=test (test_database)
    This command displays the name of the back end database next to each suffix. You require the suffix's database name in the next step.
  2. Set the database in read-only mode: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix set --enable-readonly "test_database"
2.2.2.1.2. Setting a Database in Read-only Mode Using the Web Console
To set a database in read-only mode:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Database menu.
  4. Select the suffix entry.
  5. Select Database Read-Only Mode.
  6. Click Save Configuration.

2.2.2.2. Placing the Entire Directory Server in Read-Only Mode

If Directory Server maintains more than one database and all databases need to be placed in read-only mode, this can be done in a single operation.

Warning

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

Note

If Directory Server contains replicas, do not use read-only mode because it will disable replication.
2.2.2.2.1. Placing the Entire Directory Server in Read-Only Mode Using the Command Line
To enable the read-only mode for Directory Server:
  1. Set the nsslapd-readonly parameter to on: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-readonly=on
  2. Restart the instance: 
    # dsctl instance_name restart
2.2.2.2.2. Placing the Entire Directory Server in Read-Only Mode Using the Web Console
To enable the read-only mode for Directory Server:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Server Settings menu, and select the Server Settings entry.
  4. On the Advanced Settings tab, select Server Read-Only.
  5. Click Save.

2.2.2.3. Deleting a Database

If a suffix is no longer required, you can delete the database that stores the suffix.
2.2.2.3.1. Deleting a Database Using the Command Line
To delete a database use the dsconf backend delete command. For example, to delete the database of the o=test suffix:
  1. Display the suffixes and their corresponding back end: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix list
dc=example,dc=com (userroot)
o=test (test_database)
    You require the name of the back end database, which is displayed next to the suffix, in the next step.
  2. Delete the database: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend delete "test_database"
2.2.2.3.2. Deleting a Database Using the Web Console
To delete a database using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Database menu.
  4. Select the suffix to delete, click Suffix Tasks, and select Delete Suffix.
  5. Click Yes to confirm.

2.2.2.4. Changing the Transaction Log Directory

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

Note

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

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.