Product SiteDocumentation Site

Chapter 3. Configuring Directory Databases

3.1. Creating and Maintaining Suffixes
3.1.1. Creating Suffixes
3.1.2. Maintaining Suffixes
3.2. Creating and Maintaining Databases
3.2.1. Creating Databases
3.2.2. Maintaining Directory Databases
3.2.3. Database Encryption
3.3. Creating and Maintaining Database Links
3.3.1. Configuring the Chaining Policy
3.3.2. Creating a New Database Link
3.3.3. Chaining Using SSL
3.3.4. Maintaining Database Links
3.3.5. Database Links and Access Control Evaluation
3.3.6. Advanced Feature: Tuning Database Link Performance
3.3.7. Advanced Feature: Configuring Cascading Chaining
3.4. Using Referrals
3.4.1. Starting the Server in Referral Mode
3.4.2. Setting Default Referrals
3.4.3. Creating Smart Referrals
3.4.4. Creating Suffix Referrals
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.

3.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 3.1, “A Sample Directory Tree with One Root Suffix”.
A Sample Directory Tree with One Root Suffix
Figure 3.1. A Sample 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.
This section describes creating suffixes on Directory Server and associating them with databases.

3.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 3.2, “A Sample Directory Tree with Two Root Suffixes”.
A Sample Directory Tree with Two Root Suffixes
Figure 3.2. A Sample 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 3.3, “A Sample Directory Tree with a Root Suffix Off Limits to Search Operations”.
A Sample Directory Tree with a Root Suffix Off Limits to Search Operations
Figure 3.3. A Sample 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 3.4, “A Sample Directory Tree with a Sub Suffix”.
A Sample Directory Tree with a Sub Suffix
Figure 3.4. A Sample 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.

3.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.
    The Create new root suffix dialog box is displayed.
  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, an 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 checkbox 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.
  5. Click OK.
    The suffix appears automatically under the Data tree in the left navigation pane.
  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 checkbox 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.
    Deselect the checkbox to create a database for the new sub suffix later. The new sub suffix will be disabled until a database is created.
  5. Click OK.
    The suffix appears automatically under its root suffix in the Data tree in the left navigation pane.
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. [2] 
    ldapmodify -a -h example1 -p 389 -D "cn=directory manager" -w secret
    ldapmodify binds to the server and prepares it to add an entry to the configuration file.
  2. Create the root suffix entry. 
    dn: cn="dc=example,dc=com",cn=mapping tree,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: UserData
cn: dc=example,dc=com
    Example 3.1. Example Root Suffix Entry

  3. 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
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:
Attribute Name Value
dn Defines the DN for the suffix. The DN is contained in quotes. The value entered takes the form cn="dc=domain,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 backend (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 3.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 3.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 3.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.
Table 3.1. Suffix Attributes

This section describes the following procedures:

3.1.2.1. Using Referrals in a Suffix

Referrals can be used to point a client application temporarily to a different server. For example, adding a referral to a suffix so that the suffix points to a different server allows the database associated with the suffix is taken off-line for maintenance without affecting the users of the Directory Server database.
To set referrals in a suffix, do the following:
  1. In the Directory Server Console, select the Configuration tab.
  2. Under Data in the left pane, select the suffix for which to add a referral.
  3. Click the Suffix Settings tab, and select the Return Referrals for all Operations radio button.
  4. Click the Referrals tab. Enter an LDAP URL in the Enter a new referral field, or click Construct to be guided through the creation of an LDAP URL. Appendix C, LDAP URLs has more information about the structure of LDAP URLs.
  5. Click Add to add the referral to the list.
    You can enter multiple referrals. The directory will return the entire list of referrals in response to requests from client applications.
  6. Click Save.

3.1.2.2. Enabling Referrals Only During Update Operations

It is possible to configure the directory to redirect update and write requests made by client applications to a read-only database. For example, there may be a local copy of directory data, and that data should be available company-wide for searches but not for updates. Enabling referrals for that Directory Server only for update requests means that when a client application asks to update an entry, the client is referred to the server that owns the data, where the modification request can proceed.
To enable referrals only during update operations, do the following:
  1. In the Directory Server Console, select the Configuration tab.
  2. Under Data in the left pane, click the suffix to which to add a referral.
  3. Click the Suffix Settings tab, and select the Return Referrals for Update Operations radio button.
  4. Click the Referrals tab. Enter an LDAP URL in the Enter a new referral field, or click Construct to be guided through the creation of an LDAP URL.
    For more information about the structure of LDAP URLs, refer to the Appendix.
  5. Click Add to add the referral to the list.
    You can enter multiple referrals. The directory will return the entire list of referrals in response to requests from client applications.
  6. Click Save.
Sometimes, a database may need taken down for maintenance, but the data the database contains is 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, do the following:
  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 checkbox.
  4. Click Save.
    The suffix is no longer enabled.

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. Select Delete from the Object menu.
    Alternatively, right-click the suffix and select Delete from the pop-up menu.
  4. Select Delete this suffix and all of its sub suffixes to remove all the suffix and every suffix below it.
    Select Delete this suffix only to remove only this particular suffix, not its sub suffixes.
  5. Click OK.

[2] The LDAP tools referenced in this guide are Mozilla LDAP, installed with Directory Server in the /usr/lib/mozldap directory on Red Hat Enterprise Linux 5 (32-bit); directories for other platforms are listed in Section 1.2, “LDAP Tool Locations”. However, Red Hat Enterprise Linux systems also include LDAP tools from OpenLDAP. It is possible to use the OpenLDAP commands as shown in the examples, but you must use the -x argument to disable SASL and allow simple authentication.