Chapter 2. Configuring Directory Databases

The directory is made up of databases, and the directory tree is distributed across the databases. This chapter describes how to create suffixes, the branch points for the directory tree, and how to create the databases associated with each suffix. This chapter also describes how to create database links to reference databases on remote servers and how to use referrals to point clients to external sources of directory data.

2.1. Creating and Maintaining Suffixes

Different pieces of the directory tree can be stored in different databases, and then these databases can be distributed across multiple servers. The directory tree contains branch points called nodes. These nodes may be associated with databases. A suffix is a node of the directory tree associated with a particular database. The following is a simple directory tree:
A Directory Tree with One Root Suffix

Figure 2.1. A Directory Tree with One Root Suffix

The 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

A root suffix is the parent of a sub-suffix. It can be part of a larger tree designed for Directory Server. A sub-suffix is a branch underneath a root suffix. Both root and sub-suffixes are used to organize the contents of the directory tree. The data for root and sub-suffixes are stored in databases.

2.1.1.1. Creating a Root Suffix

A directory can contain more than one root suffix. For example, an internet service provider that hosts several websites, one for 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:
A Directory with Two Root Suffixes

Figure 2.2. A Directory with Two Root Suffixes

It is also possible to create root suffixes to exclude portions of the directory tree from search operations. For example, if the Example Corporation wants to exclude their European office from a search on the general Example Corporation directory. To implement this, the directory requires two root suffixes. One root suffix corresponds to the general Example Corporation directory tree, dc=example,dc=com, and one root suffix corresponds to the European branch of their directory tree, l=europe,dc=example,dc=com. From a client application's perspective, the directory tree looks as illustrated the following diagram:
A Directory with a Root Suffix Off Limits to Search Operations

Figure 2.3. A Directory with a Root Suffix Off Limits to Search Operations

Searches performed by client applications on the dc=example,dc=com branch of the directory will not return entries from the l=europe,dc=example,dc=com branch of the directory, as it is a separate root suffix.
2.1.1.1.1. Creating a Root Suffix Using the Command Line
Use the dsconf backend create command to create a new root suffix:
  1. 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.
  2. Create the ou=People,dc=example,dc=com root suffix in the example back end database: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend create \
     --suffix="dc=example,dc=com" --be-name="example"
2.1.1.1.2. Creating a Root Suffix Using the Web Console
To create a new root suffix 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. Click Create Suffix.
  5. Enter the suffix DN and back end name. For example:
  6. Select Create The Top Suffix Entry.
  7. Click Create Suffix.

2.1.1.2. Creating a Sub-suffix

In certain scenarios, administrators want to store a branch of the directory tree in a separate database. For example, if the administrator creates the l=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 l=europe,dc=example,dc=com and subentries - are stored also in a separate database.
A Directory Tree with a Sub Suffix

Figure 2.4. A Directory Tree with a Sub Suffix

2.1.1.2.1. Creating a Sub-suffix Using the Command Line
Use the 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:
  1. 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.
  2. Create the sub-suffix. For example, to create the ou=People,dc=example,dc=com sub-suffix along with the example 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
To create a new sub-suffix 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, under which you want to create the sub-suffix, click Suffix Tasks, and select Create Sub-Suffix.
  5. Enter the sub-suffix DN and back end name. For example:
  6. Select Create The Top Sub-Suffix Entry.
  7. Click Create Sub-Suffix.

2.1.2. Maintaining Suffixes

2.1.2.1. Viewing the Default Naming Context

A naming context is analogous to the suffix; it is the root structure for naming directory entries. There can be multiple naming contexts, depending on the directory and data structure. For example, a standard Directory Server configuration has a user suffix such as dc=example,dc=com and a configuration suffix in cn=config.
Many directory trees have multiple naming contexts to be used with different types of entries or with logical data divisions. Clients which access Directory Server may not know what naming context they need to use. The Directory Server has a server configuration attribute which signals to clients what the default naming context is, if they have no other naming context configuration known to them.
The default naming context is set in the 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

To maintain configuration consistency, do not remove the nsslapd-defaultnamingcontext attribute from the nsslapd-allowed-to-delete-attrs list.
By default, the 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.
If for some reason the 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

In certain situations, a suffix in the directory needs to be disabled. If a suffix is disabled, the content of the database related to the suffix is no longer accessible by clients.
2.1.2.2.1. Disabling a Suffix Using the Command Line
To disable a suffix using the command line, pass the back end database name to the dsconf backend suffix set --disable command. For example, to disable 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)
    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. 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

If a suffix is no longer required, the administrator can delete it from the database.

Warning

Deleting a suffix also deletes all database entries and replication information associated with that suffix.
2.1.2.3.1. Deleting a Suffix Using the Command Line
To delete a suffix using the command line, use the dsconf backend delete command. For example, to delete 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)
    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. 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
To delete a suffix 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, click Suffix Tasks, and select Delete Suffix.
  5. Click Yes to confirm.