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 Netscape 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 can either be associated with databases or not. 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 sub suffixes 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 sub suffixes 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 netscape.com. The ISP would create two root suffixes, one corresponding to the dc=example,dc=com naming context and one corresponding to the dc=netscape,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 sub suffixes 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:

In the Directory Server Console, select the Configuration tab.
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.
Enter a unique suffix in the "New suffix" field.

The suffix must be named according to dc naming conventions. For example, you might enter a new suffix name of dc=example,dc=com.
Select the "Create associated database automatically" checkbox if you want a database to be created at the same time as the new root suffix.

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.
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.

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.
Click OK to create the new root suffix.

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:

In the Directory Server Console, select the Configuration tab.
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.

The "Create new sub suffix" dialog box is displayed.
Enter a unique suffix name in the "New suffix" field.

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.
Select the "Create associated database automatically" checkbox if you want a database to be created at the same time as the new sub suffix.

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.
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.

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.
Click OK to create the new sub suffix.

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.

However, although we recommend you do not store simple user entries under cn=config for performance reasons, it can be useful to store special user entries such as the Directory Manager entry or Replication Manager (supplier bind DN) entry under cn=config, as this allows you to centralize configuration information.

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 sub suffixes via the command-line.

For example, if you name a root suffix ou=groups ,dc=example,dc=com (with two spaces after groups), any sub suffixes 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 Netscape Directory Server Deployment Guide.

To set referrals in a suffix:

In the Directory Server Console, select the Configuration tab.
Under Data in the left pane, select the suffix for which you want to add a referral.
Click the Suffix Settings tab, and select the "Return Referrals for all Operations" radio button.
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, see Appendix C, "LDAP URLs."
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.
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:

In the Directory Server Console, select the Configuration tab.
Under Data in the left pane, click the suffix for which you want to add a referral.
Click the Suffix Settings tab, and select the "Return Referrals for Update Operations" radio button.
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 Appendix C, "LDAP URLs."
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.
Click Save.

Disabling a Suffix

Sometime, 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:

In the Directory Server Console, select the Configuration tab.
Under Data in the left navigation pane, click the suffix you want to disable.
Click the Suffix Setting tab, and deselect the "Enable this suffix" checkbox.

A red dot appears on the Suffix Setting tab to alert you to changes that need to be saved.
Click Save.

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.

In the Directory Server Console, select the Configuration tab.
Under Data in the left navigation pane, select the suffix you want to delete.
Select Delete from the Object menu.

You can also right-click the suffix and select Delete from the pop-up menu.
Select "Delete this suffix and all of its sub suffixes" if you want to remove all the suffix and every suffix below it.

Select "Delete this suffix only" if you want to remove only this particular suffix, not its sub suffixes.
Click OK to delete the suffix.

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:

One database per suffix.

The data for each suffix is contained in a separate database. For example, your directory tree appears as follows:

You add three databases to store the data contained in your separate suffixes as follows:

This division of the tree corresponds to three databases as follows:

Database one contains the data for ou=people plus the data for dc=example,dc=com, so that clients can conduct searches based at dc=example,dc=com. Database two contains the data for ou=groups, and database three contains the data for ou=contractors.

Multiple databases for one suffix.

Suppose the number of entries in the ou=people branch of your directory tree is so large that you need two databases to store them. In this case, the data contained by ou=people could be distributed across two databases. This is illustrated as follows:

Database one contains people with names from A-K, and database two contains people with names from L-Z. Database three contains the ou=groups data, and database four contains the ou=contractors data.

You need to use the custom distribution plug-in to distribute data from a single suffix across multiple databases. Contact Netscape Professional Services for information on how to create distribution logic for your Directory Server.

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:

In the Directory Server Console, select the Configuration tab.
In the left pane, expand Data, then click the suffix to which you want to add the new database.
Right-click the suffix, and select New Database from the pop-up menu.

The "Create New Database" dialog box is displayed.
In the "Create New Database" dialog box, enter a unique name for the database.

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.
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.

By default, the directory stores the new database in this directory:

serverRoot/slapd-serverID/db
Click OK. Click Yes in the confirmation dialog to create the new database.

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 Netscape 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 Netscape 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 Netscape Professional Services.

Adding Custom Distribution Using the Console

In the Directory Server Console, select the Configuration tab.
Expand Data in the left navigation pane. Select the suffix to which you want to apply your distribution function.
Select the Databases tab in the right window.
Click Add to associate additional databases with the suffix.

The "Database List" dialog box is displayed. Select a database from the list, and click OK.
Enter the path to your distribution library in the "Distribution library" field, or click Browse to locate a distribution library on your local machine.
Enter the name of your distribution function in the "Function name" field.
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:

In the Directory Server Console, select the Configuration tab.
Expand Data in the left pane. Expand the suffix containing the database you want to put in read-only mode.
Select the database you want to put into read-only mode.
Select the Database Settings tab in the right pane.
Select the "Database is read-only" checkbox.
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.

In the Directory Server Console, select the Configuration tab.
In the left navigation pane, locate the database you want to delete, and select it.
From the Object menu, select Delete.

You can also right-click the database and select Delete from the pop-up menu.

The Deleting Database confirmation dialog box is displayed.
Click Yes to confirm that you want to delete the database.

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

The 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, if a copy of the server's database files should fall into the hands of an unauthorized person, they could potentially extract sensitive information from those files. Because information in a database is stored in plain text, some sensitive information, such as government identification numbers or passwords, may not be protected enough by standard access control measures.

For highly sensitive information, this potential for information loss could present a significant security risk. In order to remove that security risk, Directory Server allows portions of its database to be encrypted. Once encrypted, the data are safe even in the event that an attacker has a copy of the server's database files.

Database encryption allows attributes to be encrypted in the database. Both encryption and the encryption cipher are configurable per attribute per backend. When configured, every instance of a particular attribute, even index data, is encrypted for every entry stored in that database.

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.

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.

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 effect on server performance for searches that make use of an encrypted index, but the effect is not serious enough that it is no longer worthwhile to use an index.

Encryption Keys

In order to use database encryption, the server must be configured for SSL and have SSL enabled because database encryption uses the server's SSL encryption key and the same PIN input methods 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 private 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 used for wrapping. 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.

Encryption Ciphers
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.

The following ciphers are supported:

Advanced Encryption Standard (AES)
Triple Data Encryption Standard (3DES)

All ciphers are used in Cipher Block Chaining mode.

Once the encryption cipher is set, it should not be changed without exporting and re-importing the data.

Configuring Database Encryption from the Console

In the Console, open the Directory Server.
Open the “Configuration” tab, and select the “Data” node.
In the “Data” node, select the backend you want to edit, such as dc=ecample,dc=com.
Next, select the root you want to edit, such as o=userRoot.
Select the “Attribute Encryption” tab.
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.
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.
Before you save, you can undo any changes and return to the previous configuration by pressing the “Reset” button.
For existing attribute entries to be encrypted, the information must be exported, then re-imported. See Exporting and Importing an Encrypted Database.

Configuring Database Encryption Using the Command-Line

Using the ldapmodify command to add database encryption with the AES cipher to the telephoneNumber attribute, add a configuration entry like this:

dn: cn=telephoneNumber,cn=encrypted attributes,cn=Database1,cn=ldbm database, cn=plugins,cn=config

objectclass: top
objectclass: nsAttributeEncryption
cn: telephoneNumber
nsEncryptionAlgorithm: AES
For existing attribute entries to be encrypted, the information must be exported, then re-imported. See Exporting and Importing an Encrypted Database.

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 Netscape 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.

Export the data using the db2ldif script, as follows:

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.
Make any configuration changes.
Re-import the data using the ldif2db script, as follows:

ldif2db -n Database1 -E -i /usr/netscape/servers/slapd-dirserver/ldif/output.ldif

See Importing from the Command-Line for more information.

Note

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

It is possible for old, unencrypted data to persist in the server’s database page pool backing file, even after a successful re-import with encryption. To remove this data, stop the server and delete the file named db/guardian and then re-start the server. This will force recovery, a side-effect of which is the deletion of the backing file. However, it is possible that the data from the deleted file could still be recovered from the hard drive unless steps are taken to overwrite the disk blocks that it occupied.
After enabling encryption and importing data, be sure to delete the ldif file because it contains plaintext values for the now encrypted data. Again, steps should be taken to ensure that the disk blocks that it occupied are overwritten.
The unencrypted data previously stored in the server's database may persist on disk after a successful re-import with encryption. This is because the old database files are deleted as part of the import process. Steps should be taken to ensure that the disk blocks that those files occupied are overwritten.
Data stored in the server’s replication log database is never encrypted; therefore, care should be taken to protect those files if replication is used.

The server does not attempt to protect unencrypted data stored in memory. This data may be copied into a system page file by the operating system. For this reason, steps should be taken to ensure that any page or swap files are adequately protected.

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 Netscape 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

In the Directory Server Console, select the Configuration tab.
Expand Data in the left pane and click Database Link Settings.
Select the Settings tab in the right window. To add a component to the "Components allowed to chain" list, click Add.

The "Select Components to Add" dialog box displays. Select a component from the list and click OK.
To delete a component from the list, select it, and click Delete.

After making modifications to the components list, a red dot appears on the tab, and the field name turns gray.
Click Save to save your changes.
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.

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:

Virtual list view (VLV) -- This control provides lists of parts of entries rather than returning all entry information.
Server side sorting -- This control sorts entries according to their attribute values.
Managed DSA -- This controls returns smart referrals as entries rather than following the referral. This allows you to change or delete the smart referral itself.
Loop detection -- This control keeps track of the number of times the server chains with another server. When the count reaches a number you configure, a loop is detected, and the client application is notified. For more information about using this control, refer to Detecting Loops.


Note	Server side sorting and VLV controls are supported only when a client application request is made to a single database. Database links cannot support these controls when a client application makes a request to multiple databases.

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

In the Directory Server Console, select the Configuration tab.
Expand the Data folder in the left pane, and click Database Link Settings.
Select the Settings tab in the right window. To add an LDAP control to the list, click Add.

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.
To delete a control from the list, select it from the "LDAP controls forwarded to the remote server" list, and click Delete.
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 on http://enterprise.netscape.com/docs.

Creating a New Database Link

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

Suffix information. You create a suffix in your directory tree that is managed by the database link, not a regular database. This suffix corresponds to the suffix on the remote server that contains the data.
Bind credentials. When the database link binds to a remote server, it impersonates a user. You need to specify the DN and the credentials you want each database link to use to bind with remote servers.
LDAP URL. You provide the LDAP URL of the remote server to which the database link connects.
List of failover servers. You can provide a list of alternative servers for the database link to contact in the event of a failure. This configuration item is optional.

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:

In the Directory Server Console, select the Configuration tab.
Right-click Data in the left navigation pane, and select New Root Suffix or New Sub Suffix from the pop-up menu.

A "Create New Suffix" dialog box is displayed.
Enter the name of the suffix on the remote server to which you want to chain in the "New suffix" field.

The suffix must be named according to dc naming conventions. For example, you might enter a new suffix name of dc=example,dc=com.
Deselect the "Create associated database automatically" checkbox.

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.
Click OK to create the new suffix.

The suffix appears automatically under the Data branch in the left navigation pane.
In the left pane, right-click the suffix you just created, and select "New Database Link" from the pop-up menu.

The Create New Database Link dialog box is displayed.
Enter the name of the new database link in the "Database link name" field.

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.
Enter the DN used by the database link to bind to the remote server in the "Bind DN" field.

For example, you might enter cn=dblink in the "Bind DN" field.
Enter the password used by the database link to bind to the remote server in the "Password" field.
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.
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.
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.

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.
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.

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 Netscape 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:

On the remote server, you need to do the following:
1. Create an administrative user for the database link.
  
  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.
  
  For more information on configuring ACIs, refer to Managing Access Control.

On the server containing the database like, you need to do the following:

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.

Caution

The nsMultiplexorBindDN cannot be that of the Directory Manager.

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://enterprise.netscape.com/docs.

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 to 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