shadow man Administrator's Guide
Red Hat Directory Server
Previous      Contents      Index      DocHome      Next     

Chapter 3   Configuring Directory Databases


Your directory is made up of databases over which you can distribute your directory tree. This chapter describes how to create suffixes, the branch points for your 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.

This chapter includes the following sections:

For conceptual information on distributing your directory data, refer to the Red Hat Directory Server Deployment Guide.

Creating and Maintaining Suffixes

You can store different pieces of your directory tree in different databases and then distribute these databases across multiple servers. Your directory tree contains branch points called nodes. These nodes may be associated with databases. You create nodes using the Directory tab in the Directory Server Console, where you freely edit the entries that appear in your directory tree.

A suffix is a node of your directory tree associated with a particular database. You create these special nodes using the Database tab on the Directory Server Console. For example, a simple directory tree might appear as illustrated in Figure 3-1.

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 your Directory Server and associating them with databases. This section contains procedures for the following:

Creating Suffixes

You can create both root and subsuffixes to organize the contents of your directory tree. A root suffix is the parent of a sub suffix. It can be part of a larger tree you have designed for your Directory Server. A sub suffix is a branch underneath a root suffix. The data for root and subsuffixes are contained by databases.

Your 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. The directory tree appears as illustrated in Figure 3-2.

Figure 3-2    A Sample Directory Tree with Two Root Suffixes

You can also create root suffixes to exclude portions of your directory tree from search operations. For example, example.com Corporation might want to exclude their European office from a search on the general example.com Corporation directory. To do this, they create two root suffixes. One root suffix corresponds to the general example.com 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.

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.com 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.com Corporation decides that they want to include the entries in the European branch of their directory tree in general searches, they would make the European branch a sub suffix of the general branch. To do this, they create a root suffix example.com 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 would appear as illustrated in Figure 3-4.

Figure 3-4    A Sample Directory Tree with a Sub Suffix

This section describes creating root and subsuffixes for your directory using either the Directory Server Console or the command-line. This section contains the following procedures:

Creating a New Root Suffix Using the Console

The following procedure describes creating a suffix and associating it with a database:

  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. The "Create new root suffix" dialog box is displayed.
     
  3. Enter a unique suffix in the "New suffix" field.
    4. The suffix must be named according to dc naming conventions. For example, you might enter a new suffix name of dc=example,dc=com.
     
  4. Select the "Create associated database automatically" checkbox if you want a database to be created at the same time as the new root suffix.
    5. Deselect the checkbox if you want to create a database for the new root suffix later. You may want to do this if you want to be able to specify a directory where the database will be created. The new root suffix will be disabled until you create a database.
     
  5. If you selected the "Create associated database automatically" checkbox in step 4, enter a unique name for the new database in the "Database name" field.
    6. For the name, you can use a combination of alphanumeric, dash (-), and underscore (_) characters; no other characters are allowed. For example, you might name the new database example2.
     
  6. Click OK to create the new root suffix.
    7. The suffix appears automatically under the Data branch in the left navigation pane.
     

Creating a New Sub Suffix Using the Console

The following procedure describes creating a sub suffix under an already existing root or sub suffix:

  1. In the Directory Server Console, select the Configuration tab.
  2. Under the Data in the left navigation pane, select the suffix under which you want to add a new sub suffix. Right-click the suffix, and select New Sub Suffix from the pop-up menu.
    3. The "Create new sub suffix" dialog box is displayed.
     
  3. Enter a unique suffix name in the "New suffix" field.
    4. The suffix must be named according to dc naming conventions. For example, you might enter a new suffix name of ou=groups.
     
    The root suffix is automatically added to the name. For example, if you are creating the sub suffix ou=groups 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 if you want a database to be created at the same time as the new sub suffix.
    5. Deselect the checkbox if you want to create a database for the new sub suffix later. The new sub suffix will be disabled until you create a database.
     
  5. If you selected the "Create associated database automatically" checkbox in step 4, enter a unique name for the new database in the "Database name" field.
    6. For the name, you can use a combination of alphanumeric, dash (-), and underscore (_) characters; no other characters are allowed. For example, you might name the new database example3.
     
  6. Click OK to create the new sub suffix.
    7. The suffix appears automatically under its root suffix in the Data tree in the left navigation pane.
     

Creating Root and Sub Suffixes from the Command-Line

Use the ldapmodify command-line utility to add new suffixes to your 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 probably suffer.



For example, you want to add a new root suffix to the configuration file using the ldapmodify utility. First, type the following to change to the directory containing the utility:

cd serverRoot /shared/bin

Then, run ldapmodify, as follows:

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.

Next, you create the root suffix entry for example.com Corporation, as follows:

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

To create a sub suffix for groups under this root suffix, you would do an ldapmodify operation to add the following 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  

If you want to maintain your suffixes using the Directory Server Console, you will need to respect the same spacing you use to name the root and subsuffixes via the command-line.

For example, if you name a root suffix ou=groups  ,dc=example,dc=com (with two spaces after groups), any subsuffixes you create 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 3-1    Suffix Attributes  


Attribute Name

Value

dn

Defines the DN for the suffix. The DN is contained in quotes. The value you enter takes the following 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. Refer to "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 you have specified more than one database in the nsslapd-backend attribute.

Refer to "Creating and Maintaining Databases", for more information about the custom distribution function.

nsslapd-distribution-funct

Specifies the name of your custom distribution function. This attribute is required only when you specify more than one database in the nsslapd-backend attribute.

Refer to "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, you want to create a sub suffix o=sales,dc=example,dc=com under the root suffix dc=example,dc=com. Add the following value to the nsslapd-parent-suffix attribute of the sub suffix:

nsslapd-parent-suffix: "dc=example,dc=com"



Maintaining Suffixes

This section describes the following procedures:

Using Referrals in a Suffix

Referrals can be used to point a client application temporarily to a different server. For example, you might add a referral to a suffix so that the suffix points to a different server when the database associated with the suffix is taken off-line for maintenance.

For more information on referrals in general, refer to Red Hat Directory Server Deployment Guide.

To set referrals in a suffix:

  1. In the Directory Server Console, select the Configuration tab.
  2. Under Data in the left pane, select the suffix for which you want 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.
    5. For more information about the structure of LDAP URLs, see Appendix C, "LDAP URLs."
     
  5. Click Add to add the referral to the list.
    6. You can enter multiple referrals. The directory will return the entire list of referrals in response to requests from client applications.
     
  6. Click Save.

Enabling Referrals Only During Update Operations

You may want to configure your directory to redirect update and write requests made by client applications to a read-only database.

For example, you can enable referrals for update operations when you have a local copy of the directory data that you do not own. You want the data to be available for searches but not for updates. You do this by enabling referrals only during update requests. 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:

  1. In the Directory Server Console, select the Configuration tab.
  2. Under Data in the left pane, click the suffix for which you want 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.
    5. For more information about the structure of LDAP URLs, refer to Appendix C, "LDAP URLs."
     
  5. Click Add to add the referral to the list.
    6. You can enter multiple referrals. The directory will return the entire list of referrals in response to requests from client applications.
     
  6. Click Save.

Disabling a Suffix

Sometimes, you may need to take down a database for maintenance, but the data the database contains is not replicated. Rather than returning a referral, you can disable the suffix responsible for the database.

Once you disable a suffix, 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 you want to disable.
  3. Click the Suffix Setting tab, and deselect the "Enable this suffix" checkbox.
    4. A red dot appears on the Suffix Setting tab to alert you to changes that need to be saved.
     
  4. Click Save.
    5. The suffix is no longer enabled.
     

Deleting a Suffix

The following procedure describes deleting a suffix:

Caution  

When you delete a suffix, you also delete 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 you want to delete.
  3. Select Delete from the Object menu.
    4. You can also right-click the suffix and select Delete from the pop-up menu.
     
  4. Select "Delete this suffix and all of its subsuffixes" if you want to remove all the suffix and every suffix below it.
    5. Select "Delete this suffix only" if you want to remove only this particular suffix, not its subsuffixes.
     
  5. Click OK to delete the suffix.
    6. A progress dialog box is displayed that tells you the steps being completed by the Console.
     

Creating and Maintaining Databases

After you create suffixes for organizing your directory data, you create databases to contain your directory data. Databases are used to store your directory data.

This section contains information about creating databases to contain your directory data, deleting databases, using database encryption, and making databases temporarily read-only.

Creating Databases

Directory Server supports the use of multiple databases over which you can distribute your directory tree. There are two ways you can distribute your data across multiple databases:

Creating a New Database for an Existing Suffix Using the Console

The following procedure describes adding a database to a suffix you have already created:

  1. In the Directory Server Console, select the Configuration tab.
  2. In the left pane, expand Data, then click the suffix to which you want to add the new database.
  3. Right-click the suffix, and select New Database from the pop-up menu.
    4. The "Create New Database" dialog box is displayed.
     
  4. In the "Create New Database" dialog box, enter a unique name for the database.
    5. This value cannot contain commas, tabs, an equals sign (=), asterisk (*), backslash (\), forward slash (/), plus sign (+), quote (`), double quote ("), or a question mark (?). It can contain numbers; for instance, you might name the new database example2.
     
  5. In the "Create database in" field, enter the path to the directory where you want to store the new database. You can also click Browse to locate a directory on your local machine.
    6. By default, the directory stores the new database in this directory:
     
    serverRoot /slapd-serverID /db
     
  6. Click OK. Click Yes in the confirmation dialog to create the new database.

    7. Note  

    To see the new suffix in the Directory tab, you first need to create a root entry associated with the suffix. Refer to "Creating Directory Entries".



Creating a New Database for a Single Suffix from the Command-Line

Use the ldapmodify command-line utility to add a new database to your directory configuration file. The database configuration information is stored in the cn=ldbm database,cn=plugins,cn=config entry.

For example, you want to add a new database to the server example1. First, type the following to change to the directory containing the ldapmodify utility:

cd serverRoot /shared/bin

Add a new entry to the configuration file by performing an ldapmodify, as follows:

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.

Next, you create the entry for the new database, as follows:

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.

To create a root or sub suffix from the command-line, refer to "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

You can distribute a single suffix across multiple databases. However, to distribute the suffix, you need to create a custom distribution function to extend the directory. For more information on creating a custom distribution function, contact Red Hat Professional Services.

Note  

Once you have distributed entries, you cannot redistribute them. The following restrictions apply:

  • You cannot change your distribution function once you have deployed entry distribution.
  • You cannot use the LDAP modrdn operation to rename entries if that would cause them to be distributed into a different database.
  • You cannot replicate distributed local databases.
  • You cannot use the ldapmodify operation 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.



Once Red Hat Professional Services has helped you create a custom distribution logic plug-in, you need to add it to your directory. The following procedures describe adding distribution logic to a suffix in your directory.

Adding the Custom Distribution Function to a Suffix

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. You can insert a distribution function into a suffix using both the Console and the command-line.

For information about creating your own custom distribution logic, contact Red Hat Professional Services.

Adding Custom Distribution Using the Console

  1. In the Directory Server Console, select the Configuration tab.
  2. Expand Data in the left navigation pane. Select the suffix to which you want to apply your distribution function.
  3. Select the Databases tab in the right window.
  4. Click Add to associate additional databases with the suffix.
    5. The "Database List" dialog box is displayed. Select a database from the list, and click OK.
     
  5. Enter the path to your distribution library in the "Distribution library" field, or click Browse to locate a distribution library on your local machine.
  6. Enter the name of your distribution function in the "Function name" field.
  7. Click Save to save your changes.

Adding Custom Distribution from the Command-Line

Use the ldapmodify command-line utility to add the following attributes to the suffix entry itself:

nsslapd-backend: Database1
nsslapd-backend: Database2
nsslapd-backend: Database3
nsslapd-distribution-plugin: /full/name/of/a/shared/library 
nsslapd-distribution-funct: distribution-function-name

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 your 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, refer to "Adding and Modifying Entries Using ldapmodify".

Maintaining Directory Databases

This section describes jobs associated with maintaining your directory databases. It includes the following procedures:

Placing a Database in Read-Only Mode

When a database is in read-only mode, you cannot create, modify, or delete any entries. For example, you must put a database in read-only mode if you are manually initializing a consumer.

If your Directory Server manages multiple databases, you can place all of them into read-only mode at the same time by placing your entire server in read-only mode. For more information, see "Placing the Entire Directory Server in Read-Only Mode".

This section includes procedures for the following:

Making a Database Read-Only Using the Console

To place a database in read-only mode from the Directory Server Console:

  1. In the Directory Server Console, select the Configuration tab.
  2. Expand Data in the left pane. Expand the suffix containing the database you want to put in read-only mode.
  3. Select the database you want to put into read-only mode.
  4. Select the Database Settings tab in the right pane.
  5. Select the "Database is read-only" checkbox.
  6. Click Save.

Making a Database Read-Only from the Command-Line

If you want to manually place a database into read-only mode, you must change the read-only attribute, nsslapd-readonly, to on. To do so, use the ldapmodify command-line utility. The nsslapd-readonly attribute for a particular database is located in the cn=database_name ,cn=ldbm database,cn=plugins,cn=config entry (where database_name is the name of the database).

Note  

By default, the name of the database created at installation time is userRoot.



Deleting a Database

The following procedure describes deleting a directory database using the Directory Server Console. Deleting a database deletes the configuration information and entries for that database only, not the physical database itself.

  1. In the Directory Server Console, select the Configuration tab.
  2. In the left navigation pane, locate the database you want to delete, and select it.
  3. From the Object menu, select Delete.
    4. You can also right-click the database and select Delete from the pop-up menu.
     
    The Deleting Database confirmation dialog box is displayed.
     
  4. Click Yes to confirm that you want to delete the database.
    5. A progress dialog box appears telling you the steps the Directory Server completes during the deletion.
     
    Once deleted, the database no longer appears in the right pane.
     

Configuring Transaction Logs for Frequent Database Updates

When the server is going to be asked to perform frequent database updates (LDAP adds, modifies, replication), the database transaction log files should be configured to be on a different disk than the primary database files.

This is done with a dse.ldif change. Use the nsslapd-db-logdirectory directive, like this:

nsslapd-db-logdirectory: /home3/exampledb-slapd-01-txnlogs

This directive goes on the same entry that has the dbcache size. Storing these files on a separate physical disk improves performance because the disk heads don't thrash moving between the log files and the data files.

Database Encryption

Directory Server offers a number of mechanisms to secure access to sensitive data, such as access control rules to prevent unauthorized users from reading certain entries or attributes within entries and SSL to protect data from eavesdropping and tampering on untrusted networks. However, an unauthorized person could potentially extract sensitive information from directory database files from copies of files or old hard drives because information in a database is stored in plain text. Thus, sensitive information such as government identification numbers may not be protected enough by standard access control measures.

Since this potential information loss can present a significant security risk, Directory Server can encrypt selected portions of its database. Once encrypted, the data are safe even in the event that an attacker has a copy of the server's database files.

Database encryption encrypts attributes as they are stored within the database. When configured, every instance of a particular attribute, even index data, is encrypted for every entry stored in that database. Encryption and the encryption cipher are configured per attribute per backend.

Indexed attributes may be encrypted, and database encryption is fully compatible with indexing. The contents of the index files that are normally derived from attribute values are also encrypted to prevent an attacker from recovering part or all of the encrypted data from an analysis of the indexes.

Since the server pre-encrypts all index keys before looking up an index for an encrypted attribute, there is some hit to server performance for searches that make use of an encrypted index, but the effect is not serious enough to offset the benefits of indexing entries.

Encryption Keys

In order to use database encryption, the server must be configured for SSL because database encryption uses the server's SSL encryption key and the same PIN as SSL. The PIN must either be entered manually upon server startup or a PIN file must be used.

Randomly generated symmetric cipher keys are used to encrypt and decrypt attribute data. A separate key is used for each configured cipher. These keys are "wrapped" using the public key from the server's SSL certificate, and the resulting wrapped key is stored within the server's configuration files. The effective strength of the database encryption is never higher than the strength of the server's SSL key. Without access to the server's private key, it is not possible to recover the symmetric keys from the wrapped copies.

Caution  

There is no mechanism for recovering a lost key. Therefore, it is especially important to backup the server's certificate database safely. If the server's certificate were lost, it would not be possible to decrypt any encrypted data stored in its database.



Caution  

If the SSL certificate is going to expire and needs to be renewed, export the encrypted backend instance before renewing the certificate. After the certificate is renewed, re-import the exported LDIF file.



Encryption Ciphers

The following ciphers are supported for database encryption:

All ciphers are used in Cipher Block Chaining mode.

The encryption cipher is configurable on a per-attribute basis and must be selected by the administrator at the time encryption is enabled for an attribute. Configuration can be done through the Console or through the command-line. Once the encryption cipher is set, it should not be changed without exporting and re-importing the data.

Encrypting Pre-existing Data

To enable database encryption on an attribute with existing stored data, you have to export the database to LDIF first, then make the configuration change, then re-import the data to the database. See "Exporting and Importing an Encrypted Database". The server does not enforce consistency between encryption configuration and stored data; therefore, pay careful attention that all existing data are exported before enabling or disabling encryption.

When enabling encryption for data that is already present in the the database, several additional security concerns arise:

Configuring Database Encryption from the Console

Note  

To enable database encryption on an attribute with existing stored data, you have to export the database to LDIF first, then make the configuration change, then re-import the data to the database. See "Exporting and Importing an Encrypted Database". The server does not enforce consistency between encryption configuration and stored data; therefore, pay careful attention that all existing data are exported before enabling or disabling encryption.



  1. In the Console, open the Directory Server.
  2. Open the "Configuration" tab, and select the "Data" node.
  3. In the "Data" node, select the root you want to edit, such as dc=example,dc=com.
  4. Next, select the backend you want to edit, such as userRoot.
  5. Select the "Attribute Encryption" tab.
  6. Hit the "Add Attribute" button, and a list of attributes will appear. Select the attribute you want encrypted. A list will appear; select which encryption cipher you wish to use.
  7. Repeat step 6 for every attribute you want encrypted. Then hit "Save" to save your changes.

To delete attributes, select them from the list of encrypted attributes in the Attribute Encryption table, and hit the "Delete" button. When you hit "Save," a dialog box will appear asking if you want to delete the selected attributes. Click on "yes" to continue with the deletion. Any deleted attributes have to be manually re-added after you save.

Configuring Database Encryption Using the Command-Line

To configure database encryption from the command-line, use the ldapmodify command to add a configuration entry. This example encrypts the telephoneNumber attribute with the AES cipher:

ldapmodify -a -p 389 -h localhost -D "cn=directory manager" -w password33

dn: cn=telephoneNumber,cn=encrypted attributes,cn=Database1,cn=ldbm database, cn=plugins,cn=config
objectclass: top
objectclass: nsAttributeEncryption
cn: telephoneNumber
nsEncryptionAlgorithm: AES

Note  

To enable database encryption on an attribute with existing stored data, you have to export the database to LDIF first, then make the configuration change, then re-import the data to the database. See "Exporting and Importing an Encrypted Database". The server does not enforce consistency between encryption configuration and stored data; therefore, pay careful attention that all existing data are exported before enabling or disabling encryption.



For more information on database encryption configuration schema, refer to "Database Attributes under cn=attributeName,cn=encrypted attributes,cn=database_name,cn= ldbm database,cn=plugins,cn=config" in the Red Hat Directory Server Configuration, Command, and File Reference.

Exporting and Importing an Encrypted Database

Exporting and importing encrypted databases is a similar process to exporting and importing regular databases. However, the encrypted information must be decrypted when it is exported to LDIF, then re-encrypted when it is imported to the database. Using the -E option when running the db2ldif and ldif2db scripts will decrypt the data on export and re-encrypt it on import.

  1. Export the data using the db2ldif script, as follows:

    2. db2ldif -n Database1 -E -a output.ldif -s "dc=example,dc=com" -s  "o=userRoot"

    See "Exporting to LDIF from the Command-Line", for more information.
     
  2. Make any configuration changes.
  3. Re-import the data using the ldif2db script, as follows:

    4. ldif2db -n Database1 -E  -i /opt/redhat-ds/servers/slapd-dirserver/ldif/output.ldif

    See "Importing from the Command-Line", for more information.
     

Creating and Maintaining Database Links

Chaining is a method by which a server contacts other servers on behalf of a client application and then returns the combined results. This method is implemented through the database link. A database link points to data stored remotely. When a client application requests data from a database link, the database link retrieves the data from the remote database and returns it to the client.

The following sections describe how to create and configure a database link. For more general information about chaining, refer to chapter 5, "Designing the Directory Topology," in the Red Hat Directory Server Deployment Guide.

You can create and configure a database link using Directory Server Console or the command-line. The following sections describe the procedures for creating and maintaining a database link:

For information about monitoring the activity of your database links, refer to "Monitoring Database Link Activity".

Configuring the Chaining Policy

These procedures describe configuring how your Directory Server chains requests made by client applications to Directory Servers that contain database links. This chaining policy applies to all database links you create on your Directory Server.

Chaining Component Operations

A component is any functional unit in the server that uses internal operations. For example, plug-ins are considered to be components, as are functions in the front-end. However, a plug-in may actually be comprised of multiple components (for example, the ACI Plug-in).

Some components send internal LDAP requests to the server, expecting to access local data only. For such components, you need to control the chaining policy so that the components can complete their operations successfully. One example is the certificate verification function. If you chain the LDAP request made by the function to check certificates, it implies that you trust the remote server. If the remote server is not trusted, then you have a security problem.

By default, all internal operations are not chained. However, you can override this default by specifying components that you want to chain using the Console or the command-line. By default, no components are allowed to chain.

You must also create an ACI on the remote server to allow the plug-in you specify to perform its operations on the remote server. You create the ACI in the suffix assigned to the database link.

The following table lists component names, the potential side-effects of allowing them to chain internal operations, and the permissions they need in the ACI you create on the remote server:


Table 3-2    Components Allowed to Chain  


Component Name

Description

Permissions

ACI Plug-in

This plug-in implements the access control feature. Operations used to retrieve and update ACI attributes are not chained because it is not safe to mix local and remote ACI attributes. However, requests used to retrieve user entries may be chained. Specify the following value in nsActiveChainingComponents attribute:

nsActiveChainingComponents: cn=ACI Plugin,cn=plugins,cn=config

Read, search, and compare

4.0 plug-ins

This component name represents all Directory Server 4.0 plug-ins. The 4.0 plug-ins share the same chaining policy. Specify the following in the nsActiveChainingComponents attribute:

nsActiveChainingComponents: cn=old plugin,cn=plugins,cn=config

Depends upon the 4.0 plug-in you are allowing to chain

Resource limit component

This component sets server limits depending on the user bind DN. You can apply resource limits on remote users if the resource limitation component is allowed to chain. To chain this component's operations, specify the following:

nsActiveChainingComponents: cn=resource limits,cn=components,cn=config

Read, search, and compare

Certificate-based authentication checking component

This component is used when the SASL-external bind method is used. It retrieves the user certificate from the database on the remote server. If you allow this component to chain, certificate-based authentication can work with a database link. To chain this component's operations, specify the following:

nsActiveChainingComponents: cn=certificate-based authentication,cn=components,cn=config

Read, search, and compare

Referential Integrity Plug-in

This plug-in ensures that updates made to attributes containing DNs are propagated to all entries that contain pointers to the attribute. For example, if you delete an entry that is a member of a group, the entry is automatically removed from the group. Using this plug-in with chaining helps simplify the management of static groups when the group members are remote to the static group definition.

To chain this component's operations, specify the following:

nsActiveChainingComponents: cn=referential integrity postoperation,cn=plugins,cn=config

Read, write, search, and compare

Attribute Uniqueness Plug-in

This plug-in checks that all the values for a specified uid attribute are unique (no duplicates). If you allow this plug-in to chain, it confirms that the uid attribute values are unique even on attributes changed through a database link. To chain this component's operations, specify the following:

nsActiveChainingComponents: cn=attribute uniqueness,cn=plugins,cn=config

Read, search, and compare



Note  

You cannot chain the following components:

  • Roles plug-in
  • Password policy component
  • Replication plug-ins

When enabling the Referential Integrity Plug-in on servers issuing chaining requests, be sure to analyze your performance resource and time needs as well as your integrity needs. Integrity checks can be time-consuming and draining on memory/CPU.

For further information on the limitations surrounding ACIs and chaining, see "ACI Limitations".



Once you have modified the component you allow to chain, you must restart the server in order for the modification to take effect.

The following sections describe how to specify components you want to allow to chain using the Console and from the command-line.

Chaining Component Operations Using the Console

  1. In the Directory Server Console, select the Configuration tab.
  2. Expand Data in the left pane, and click Database Link Settings.
  3. Select the Settings tab in the right window. To add a component to the "Components allowed to chain" list, click Add.
    4. The "Select Components to Add" dialog box displays. Select a component from the list, and click OK.
     
  4. To delete a component from the list, select it, and click Delete.
    5. After making modifications to the components list, a red dot appears on the tab, and the field name turns gray.
     
  5. Click Save to save your changes.
  6. Restart the server in order for the change to take effect.

After allowing the component to chain, you must create an ACI in the suffix on the remote server to which the operation will be chained. For example, you would create the following ACI for the Referential Integrity Plug-in:

aci: (targetattr  "*")(target="ldap:///ou=customers,l=us,dc=example,dc=com")
 (version 3.0; acl "RefInt Access for chaining"; allow
 (read,write,search,compare) userdn = "ldap:///cn=referential
 integrity postoperation,cn=plugins,cn=config";)

Chaining Component Operations from the Command-Line

You can specify components you want to include in chaining using the nsActiveChainingComponents attribute in the cn=config,cn=chaining database,cn=plugins,cn=config entry of the configuration file.

For example, if you want to allow the referential integrity component to chain operations, you add the following to your database link configuration file:

nsActiveChainingComponents: cn=referential integrity postoperation,
 cn=components,cn=config

Refer to Table 3-2, for a list of the components you can allow to chain.

Once you have modified the nsActiveChainingComponents attribute, you must restart the server for your change to take effect.

After allowing the component to chain, you must create an ACI in the suffix on the remote server to which the operation will be chained. For example, you would create the following ACI for the referential integrity component:

aci: (targetattr  "*")(target="ldap:///ou=customers,l=us,dc=example,dc=com")
 (version 3.0; acl "RefInt Access for chaining"; allow
 (read,write,search,compare) userdn = "ldap:///cn=referential
 integrity postoperation,cn=plugins,cn=config";)

Chaining LDAP Controls

You can choose not to chain operation requests made by LDAP controls. By default, requests made by the following controls are forwarded to the remote server by the database link:

The following sections describe how to alter the controls that the database link forwards using the Console and from the command-line.

Chaining LDAP Controls Using the Console

  1. In the Directory Server Console, select the Configuration tab.
  2. Expand the Data folder in the left pane, and click Database Link Settings.
  3. Select the Settings tab in the right window. To add an LDAP control to the list, click Add.
    4. The "Select control OIDs to add" dialog box displays. Select the OID of a control you want to add to the list, and click OK.
     
  4. To delete a control from the list, select it from the "LDAP controls forwarded to the remote server" list, and click Delete.
  5. After making modifications to the components list, a red dot appears on the tab, and the components field name turns gray. Click Save to save your changes.

Chaining LDAP Controls from the Command-Line

You can alter the controls that the database link forwards by changing the nsTransmittedControls attribute of the cn=config,cn=chaining database, cn=plugins,cn=config entry. For example, to forward the virtual list view control, you add the following to your database link entry in the configuration file:

nsTransmittedControls: 2.16.840.1.113730.3.4.9

In addition, if clients of your Directory Server create their own controls and you want their operations to be chained to remote servers, you need to add the OID of the custom control to the nsTransmittedControls attribute.

The LDAP controls you can chain and their OIDs are listed in the following table:


Table 3-3    LDAP Controls and Their OIDs  


Control Name

OID

Virtual list view (VLV)

2.16.840.1.113730.3.4.9

Server side sorting

1.2.840.113556.1.4.473

Managed DSA

2.16.840.1.113730.3.4.2

Loop detection

1.3.6.1.4.1.1466.29539.12



For more information about LDAP controls, refer to the LDAP C-SDK documentation at http://www.mozilla.org/directory.

Creating a New Database Link

The basic configuration of your database link involves providing the following information:

The following sections describe creating a new database link from the Directory Server Console as well as the command-line.

Creating a New Database Link Using the Console

To create a new database link using the Directory Server 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 or New Sub Suffix from the pop-up menu.
    3. A "Create New Suffix" dialog box is displayed.
     
  3. Enter the name of the suffix on the remote server to which you want to chain in the "New suffix" field.
    4. The suffix must be named according to dc naming conventions. For example, you might enter a new suffix name of dc=example,dc=com.
     
  4. Deselect the "Create associated database automatically" checkbox.
    5. You deselect the checkbox because you cannot add a database link to a suffix that is associated with a database. This suffix is used only by the database link.
     
  5. Click OK to create the new suffix.
    6. The suffix appears automatically under the Data branch in the left navigation pane.
     
  6. In the left pane, right-click the suffix you just created, and select "New Database Link" from the pop-up menu.
    7. The Create New Database Link dialog box is displayed.
     
  7. Enter the name of the new database link in the "Database link name" field.
    8. Use only ASCII (7-bit) characters for naming the database link. This value cannot contain commas, tabs, an equals sign (=), asterisk (*), backslash (\), forward slash (/), plus sign (+), quote (`), double quote ("), or a question mark (?). For example, you might name the new database link examplelink1.
     
  8. Enter the DN used by the database link to bind to the remote server in the "Bind DN" field.
    9. For example, you might enter cn=dblink in the "Bind DN" field.
     
  9. Enter the password used by the database link to bind to the remote server in the "Password" field.
  10. Select the "Use a secure LDAP connection between servers" checkbox if you want the database link to use SSL to communicate to the remote server.
  11. Enter the name of the remote server in the "Remote server" field. Enter the server port number used for the bind in the "Remote server port" field. The default port number is 389.
  12. Enter the name of a failover server in the "Failover Server(s)" field, and specify a port number in the "Port" field. The default port number is 389. Click Add to add the failover server to the list.
    13. You can specify multiple failover servers. If the primary remote server fails, the database link contacts the first server in the Failover Servers list. If it fails, it contacts the next in the list, and so on.
     
  13. Click OK to create the new database link. Click OK to dismiss the success dialog box that appears after the database link has been created.
    14. Your new database link appears under the suffix in the left navigation pane.
     

    Tip  

    The Console provides you with a checklist of information that needs to be present on the remote server for your database link to bind successfully. To view this checklist, click your new database link, and click the Authentication tab. The checklist appears in the "Remote server checklist" box.



Creating a Database Link from the Command-Line

Use the ldapmodify command-line utility to create a new database link from the command-line.

Your new instance must be located in the cn=chaining database,cn=plugins, cn=config entry.

Default configuration attributes are contained in the cn=default config, cn=chaining database,cn=plugins,cn=config entry. These configuration attributes apply to all database links at creation time. Changes to the default configuration only affect new database links. You cannot change the default configuration attributes on existing database links.

Each database link contains its own specific configuration information, which is stored with the database link entry itself, cn=database_link_name ,cn=chaining database,cn=plugins,cn=config. For more information about configuration attributes, refer to the Red Hat Directory Server Configuration, Command, and File Reference.

This section contains the following procedures for configuring a database link from the command-line:

Providing Suffix Information

Use the nsslapd-suffix attribute to define the suffix managed by your database link. For example, if you want your database link to point to the people information for a remote site of your company, you would enter the following suffix information:

nsslapd-suffix: l=Zanzibar,ou=people,dc=example,dc=com

The suffix information is stored in the cn=database_link_name ,cn=chaining database,cn=plugins,cn=config entry.

Note  

After creation time, any alterations you make to the nsslapd-suffix attribute occur only after you have restarted the server containing the database link.



Providing Bind Credentials

For a request from a client application to be chained to a remote server, you can provide special bind credentials for the client application. This gives the remote server the proxied authorization rights needed to chain operations. If you do not specify bind credentials, the database link binds to the remote server as anonymous.

Providing bind credentials involves the following steps:

  1. On the remote server, you need to do the following:
    1. Create an administrative user for the database link.
      2. For information on adding entries, see "Creating Directory Entries".
       
    2. Provide proxy access rights for the administrative user created in step 1 on the subtree chained to by the database link.
      3. For more information on configuring ACIs, refer to "Managing Access Control".
       
  2. On the server containing the database like, you need to do the following:
    1. Use ldapmodify to provide a user DN for the database link in the nsMultiplexorBindDN attribute of the cn=database_link_name ,cn=chaining database,cn=plugins,cn=config entry.

      2. Caution  

      The nsMultiplexorBindDN cannot be that of the Directory Manager.



    2. Use ldapmodify to provide a user password for the database link in the nsMultiplexorCredentials attribute of the cn=database_link_name ,cn=chaining database,cn=plugins,cn=config entry.

For example, a client application sends a request to server A. Server A contains a database link that chains the request to a database on server B.





The database link on server A binds to server B using a special user as defined in the nsMultiplexorBindDN attribute and a user password as defined in the nsMultiplexorCredentials attribute. In this example, server A uses the following bind credentials:

nsMultiplexorBindDN: cn=proxy admin,cn=config
nsMultiplexorCredentials: secret





Server B must contain a user entry corresponding to the nsMultiplexorBindDN, and you must set the proxy authentication rights for this user. To set the proxy authorization correctly, you need to set the "proxy" ACI as you would any other ACI.

Caution  

Carefully examine access controls when enabling chaining to avoid giving access to restricted areas of your directory. For example, if you create a default proxy ACI on a branch, the users that connect via the database link will be able to see all entries below the branch. There may be cases when you do not want all of the subtrees to be viewed by a user. To avoid a security hole, you may need to create an additional ACI to restrict access to the subtree.



For more information on ACIs, refer to "Managing Access Control". For more information about the proxy authentication control, refer to the C-SDK documentation at http://www.redhat.com/docs/manuals/dir-server/.

Note  

When a database link is used by a client application to create or modify entries, the attributes creatorsName and modifiersName do not reflect the real creator or modifier of the entries. These attributes contain the name of the administrative user granted proxied authorization rights on the remote data server.



Providing an LDAP URL

On the server containing your database link, you have to identify the remote server that the database link connects with using an LDAP URL. Unlike the standard LDAP URL format, the URL of the remote server does not specify a suffix. It takes the following form:

ldap://hostname : portnumber

You specify the URL of the remote server using the nsFarmServerURL attribute in the cn=database_link_name ,cn=chaining database,cn=plugins,cn=config entry of the configuration file. For example, the nsFarmServerURL might appear as follows:

nsFarmServerURL: ldap://example.com:389/

Do not forget to use the trailing slash (/) at the end of the URL.

If you want the database link to connect to the remote server using LDAP over SSL, the LDAP URL of the remote server takes the following form:

ldaps://hostname : portnumber

For more information about chaining and SSL, refer to "Chaining Using SSL".

Providing a List of Failover Servers

You can include additional LDAP URLs for servers to use in the case of failure. To do so, add alternate servers to the nsFarmServerURL attribute, separated by spaces. For example, you might enter the following:

nsFarmServerURL: ldap://example.com us.example.com:389  africa.example.com:1000/

In this sample LDAP URL, the database link first contacts the server example.com on the standard port to service an operation. If it does not respond, the database link then contacts the server us.example.com on port 389. If this server fails, it then contacts africa.example.com on port 1000.

Summary of Database Link Configuration Attributes

The following table lists the attributes available for configuring a database link. Some of these attributes were discussed in the earlier sections.

Attributes marked with an asterisk (*) can be both global or instance attributes. All instance attributes are defined in the cn=database_link_name ,cn=chaining database,cn=plugins,cn=config entry.

The two global configuration attributes are located in the cn=config,cn=chaining database,cn=plugins,cn=config entry. The global attributes are dynamic, meaning any changes you make to them will automatically take effect on all instances of the database link within your directory.

Values defined for a specific database link take precedence over the global attribute value.


Table 3-4    Database Link Configuration Attributes  


Attributes

Value

*nsTransmittedControls

Gives the OID of LDAP controls forwarded by the database link to the remote data server.

nsslapd-suffix

The suffix managed by the database link. Any changes you make to this attribute after the entry has been created take effect only after you restart the server containing the database link.

nsslapd-timelimit

Default search time limit for the database link, given in seconds. The default value is 3600 seconds.

nsslapd-sizelimit

Default size limit for the database link, given in number of entries. The default value is 2000 entries.

nsFarmServerURL

Gives the LDAP URL of the remote server (or farm server) that contains the data. This attribute can contain optional servers for failover, separated by spaces. If using cascading chaining, this URL can point to another database link.

nsMultiplexorBindDN

DN of the administrative entry used to communicate with the remote server. The term multiplexor in the name of the attribute means the server which contains the database link and communicates with the remote server.

This bind DN cannot be the Directory Manager. If this attribute is not specified, the database link binds as anonymous.

nsMultiplexorCredentials

Password for the administrative user, given in plain text. If no password is provided, it means that users can bind as anonymous. The password is encrypted in the configuration file.

nsCheckLocalACI

Reserved for advanced use only. Controls whether ACIs are evaluated on the database link as well as the remote data server. Takes the values on or off.

Changes to this attribute occur only after the server has been restarted. The default value is off.

nsProxiedAuthorization

Reserved for advanced use only. Allows you to disable proxied authorization. A value of off means proxied authorization is disabled. The default value is on.

*nsActiveChainingComponents

Lists the components using chaining. A component is any functional unit in the server. The value of this attribute in the database link instance overrides the value in the global configuration attribute. To disable chaining on a particular database instance, use the value none.

The default policy is not to allow chaining. Refer to "Chaining Component Operations", for more information.

nsReferralOnScopedSearch

Controls whether referrals are returned by scoped searches. This attribute is for optimizing your directory because returning referrals in response to scoped searches is more efficient. Takes the values on or off. The default value is off.

nsHopLimit

Maximum number of times a request can be forwarded from one database link to another. The default value is 10.



Database Link Configuration Example

Suppose you have a server within the us.example.com domain that contains the subtree l=Walla Walla,ou=people,dc=example,dc=com on a database and that you want to chain operation requests for l=Zanzibar,ou=people,dc=example,dc=com to a different server in the africa.example.com domain. This operation is illustrated in the following diagram:





First, use the ldapmodify command-line utility to add a database link to server A. Type the following to change to the directory containing the utility:

cd serverRoot /shared/bin

Run the script, as follows:

ldapmodify -a -p 389 -D "cn=directory manager" -w secret -h  us.example.com

Then specify the configuration information for the database link:

dn: cn=DBLink1,cn=chaining database,cn=plugins,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsBackendInstance
nsslapd-suffix: l=Zanzibar,ou=people,dc=example,dc=com
nsfarmserverurl: ldap://africa.example.com:389/
nsmultiplexorbinddn: cn=proxy admin,cn=config
nsmultiplexorcredentials: secret
cn: DBLink1

dn: cn="l=Zanzibar,ou=people,dc=example,dc=com",cn=mapping  tree,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: DBLink1
nsslapd-parent-suffix: "ou=people,dc=example,dc=com"
cn: l=Zanzibar,ou=people,dc=example,dc=com

In the first section, the nsslapd-suffix attribute contains the suffix on server B to which you want to chain from server A. The nsFarmServerURL attribute contains the LDAP URL of server B.

The second section creates a new suffix, allowing the server to route requests made to the new database link. The cn attribute contains the same suffix specified in the nssalpd-suffix attribute of the database link. The nsslapd-backend attribute contains the name of the database link. The nsslapd-parent-suffix attribute specifies the parent of this new suffix, ou=people,dc=example,dc=com.

Next, you create an administrative user on server B, as follows:

dn: cn=proxy admin,cn=config
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: proxy admin
sn: proxy admin
userPassword: secret
description: Entry for use by database links