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.
For a discussion of concepts about distributing directory data, see the Directory Server Deployment Guide.

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. For example, a simple directory tree might appear as illustrated in Figure 2.1, “A Directory Tree with One Root Suffix”.
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 on another database, and the ou=contractors suffix on yet another database.

2.1.1. Creating Suffixes

Both root and sub suffixes can be created to organize the contents of the directory tree. A root suffix is the parent of a sub suffix. It can be part of a larger tree designed for the Directory Server. A sub suffix is a branch underneath a root suffix. The data for root and sub suffixes are contained by databases.
A directory might contain more than one root suffix. For example, an ISP might host several websites, one for example.com and one for redhat.com. The ISP would create two root suffixes, one corresponding to the dc=example,dc=com naming context and one corresponding to the dc=redhat,dc=com naming context, as shown in Figure 2.2, “A Directory Tree with Two Root Suffixes”.
A Directory Tree with Two Root Suffixes

Figure 2.2. A Directory Tree with Two Root Suffixes

It is also possible to create root suffixes to exclude portions of the directory tree from search operations. For example, Example Corporation wants to exclude their European office from a search on the general Example Corporation directory. To do this, they create 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 in Figure 2.3, “A Directory Tree with a Root Suffix Off Limits to Search Operations”.
A Directory Tree with a Root Suffix Off Limits to Search Operations

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

Searches performed by client applications on the dc=example,dc=com branch of Example Corporation's directory will not return entries from the l=europe,dc=example,dc=com branch of the directory, as it is a separate root suffix.
If Example Corporation decides to include the entries in the European branch of their directory tree in general searches, they make the European branch a sub suffix of the general branch. To do this, they create a root suffix for Example Corporation, dc=example,dc=com, and then create a sub suffix beneath it for their European directory entries, l=europe,dc=example,dc=com. From a client application's perspective, the directory tree appears as illustrated in Figure 2.4, “A Directory Tree with a Sub Suffix”.
A Directory Tree with a Sub Suffix

Figure 2.4. A Directory Tree with a Sub Suffix

This section describes creating root and sub suffixes for the directory using either the Directory Server Console or the command line.

2.1.1.1. Creating a New Root Suffix Using the Console

  1. In the Directory Server Console, select the Configuration tab.
  2. Right-click Data in the left navigation pane, and select New Root Suffix from the pop-up menu.
  3. Enter a unique suffix in the New suffix field.
    The suffix must be named with dc naming conventions, such as dc=example,dc=com.
  4. Select the Create associated database automatically to create a database at the same time as the new root suffix, and enter a unique name for the new database in the Database name field, such as example2. The name can be a combination of alphanumeric characters, dashes (-), and underscores (_). No other characters are allowed.
    Deselect the check box to create a database for the new root suffix later. This option specifies a directory where the database will be created. The new root suffix will be disabled until a database is created.
The new root suffix is listed under the Data folder.

2.1.1.2. Creating a New Sub Suffix Using the Console

  1. In the Directory Server Console, select the Configuration tab.
  2. Under the Data in the left navigation pane, select the suffix under which to add a new sub suffix. Right-click the suffix, and select New Sub Suffix from the pop-up menu.
    The Create new sub suffix dialog box is displayed.
  3. Enter a unique suffix name in the New suffix field. The suffix must be named in line with dc naming conventions, such as ou=groups.
    The root suffix is automatically added to the name. For example, it the sub suffix ou=groups is created under the dc=example,dc=com suffix, the Console automatically names it ou=groups,dc=example,dc=com.
  4. Select the Create associated database automatically check box to create a database at the same time as the new sub suffix, and enter a unique name for the new database in the Database name field, such as example2. The name can be a combination of alphanumeric characters, dashes (-), and underscores (_). No other characters are allowed.
    If the check box is not selected, than the database for the new sub suffix must be created later. The new sub suffix is disabled until a database is created.
The suffix appears automatically under its root suffix in the Data tree in the left navigation pane.

2.1.1.3. Creating Root and Sub Suffixes from the Command Line

Use the ldapmodify command-line utility to add new suffixes to the directory configuration file. The suffix configuration information is stored in the cn=mapping tree,cn=config entry.

Note

Avoid creating entries under the cn=config entry in the dse.ldif file. The cn=config entry in the simple, flat dse.ldif configuration file is not stored in the same highly scalable database as regular entries. As a result, if many entries, particularly entries that are likely to be updated frequently, are stored under cn=config, performance will suffer.
  1. Add a new root suffix to the configuration file using the ldapmodify utility.

    Example 2.1. Example Root Suffix Entry

    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=dc=example\,dc=com,cn=mapping tree,cn=config
changetype: add
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: UserData
cn: dc=example,dc=com
  2. Create a sub suffix for groups under this root suffix using ldapmodify to add the sub suffix entry: 
    dn: cn=ou=groups\,dc=example\,dc=com,cn=mapping tree,cn=config
changetype: add
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: GroupData
nsslapd-parent-suffix: dc=example,dc=com
cn: ou=groups,dc=example,dc=com

Note

To maintain suffixes using the Directory Server Console, respect the same spacing used to name the root and sub suffixes in the command line. For example, if a root suffix is named ou=groups ,dc=example,dc=com, with two spaces after groups, any sub suffixes created under this root will need to specify two spaces after ou=groups, as well.
The following table describes the attributes used to configure a suffix entry:

Table 2.1. Suffix Attributes

Attribute Name Value
dn Defines the DN for the suffix. The DN is contained in quotes. The value entered takes the form cn="dc=example,dc=com",cn=mapping tree,cn=config. This attribute is required.
cn Defines the relative DN (RDN) of the entry. This attribute is required.
objectclass Tells the server that the entry is root or sub suffix entry. It always takes the value nsMappingTree. This attribute is required.
nsslapd-state Determines how the suffix handles operations. This attribute takes the following values:
  • backend: The back end (database) is used to process all operations.
  • disabled: The database is not available for processing operations. The server returns a No such search object error in response to requests made by client applications.
  • referral: A referral is returned for requests made to this suffix.
  • referral on update: The database is used for all operations except update requests, which receive a referral.
The default value is disabled.
nsslapd-referral Defines the LDAP URL of the referral to be returned by the suffix. This attribute can be multi-valued, with one referral per value. This attribute is required when the value of the nsslapd-state attribute is referral or referral on update.
nsslapd-backend Gives the name of the database or database link used to process requests. This attribute can be multi-valued, with one database or database link per value. See Section 2.3, “Creating and Maintaining Database Links” for more information about database links. This attribute is required when the value of the nsslapd-state attribute is set to backend or referral on update.
nsslapd-distribution-plugin Specifies the shared library to be used with the custom distribution function. This attribute is required only when more than one database is specified in the nsslapd-backend attribute. See Section 2.2, “Creating and Maintaining Databases” for more information about the custom distribution function.
nsslapd-distribution-funct Specifies the name of the custom distribution function. This attribute is required only when more than one database is specified in the nsslapd-backend attribute. See Section 2.2, “Creating and Maintaining Databases” for more information about the custom distribution function.
nsslapd-parent-suffix Provides the DN of the parent entry for a sub suffix. By default, this attribute is not present, which means that the suffix is regarded as a root suffix. For example, to create a sub suffix names o=sales,dc=example,dc=com under the root suffix dc=example,dc=com, add nsslapd-parent-suffix: dc=example,dc=com to the 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, a configuration suffix in cn=config, and an administrative configuration suffix in o=netscaperoot.
Many directory trees have multiple naming contexts to be used with different types of entries or with logical data divisions. Clients which access the 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 and can be queried by clients anonymously by checking the defaultnamingcontext attribute in the root DSE.
For example: 
[root@server ~]# 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

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 updates 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.
To maintain configuration consistency, do not remove the nsslapd-defaultnamingcontext attribute from the nsslapd-allowed-to-delete-attrs list.

2.1.2.2. Disabling a Suffix

Sometimes, a database may need taken down for maintenance, but the data the database contains are not replicated. Rather than returning a referral, disable the suffix responsible for the database.
Once a suffix is disabled, the contents of the database related to the suffix are invisible to client applications when they perform LDAP operations such as search, add, and modify.
To disable a suffix:
  1. In the Directory Server Console, select the Configuration tab.
  2. Under Data in the left navigation pane, click the suffix to disable.
  3. Click the Suffix Setting tab, and deselect the Enable this suffix check box.

2.1.2.3. Deleting a Suffix

Warning

Deleting a suffix also deletes all database entries and replication information associated with that suffix.
  1. In the Directory Server Console, select the Configuration tab.
  2. Under Data in the left navigation pane, select the suffix to delete.
  3. Right-click the suffix, and select Delete from the menu.
  4. Select either Delete this suffix and all of its sub suffixes or Delete this suffix only.