3.2. Creating and Maintaining Databases

3.2. Creating and Maintaining Databases

After creating suffixes to organizing the directory data, create databases to contain that directory data. Databases are used to store directory data.

3.2.1. Creating Databases

The directory tree can be distributed over multiple Directory Server databases. There are two ways to distribute data across multiple databases:

  • One database per suffix. The data for each suffix is contained in a separate database.

    Three databases are added to store the data contained in separate suffixes.

    This division of the tree corresponds to three databases.

    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 the directory tree is so large that two databases are needed to store them. In this case, the data contained by ou=people could be distributed across two databases.

    DB1 contains people with names from A-K, and DB2 contains people with names from L-Z. DB3 contains the ou=groups data, and DB4 contains the ou=contractors data.

    Custom distribution plug-in distributes data from a single suffix across multiple databases. Contact Red Hat Professional Services for information on how to create distribution logic for Directory Server.

3.2.1.1. Creating a New Database for an Existing Suffix Using the Console

  1. In the Directory Server Console, select the Configuration tab.

  2. In the left pane, expand Data, then click the suffix to which to add the new database.

  3. Right-click the suffix, and select New Database from the pop-up menu.

    The Create New Database dialog box is displayed.

  4. In the Create New Database dialog box, enter a unique name for the database, such as example2. The database name can be a combination of alphanumeric characters, dashes (-), and underscores (_). No other characters are allowed.

  5. In the Create database in field, enter the path to the directory to store the new database. Alternatively, click Browse to locate a directory on the local machine.

    By default, the directory stores the new database in the /var/lib/dirsrv/slapd-instance_name/db directory.

  6. Click OK. Click Yes in the confirmation dialog to create the new database.

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

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

For example, add a new database to the server example1:

  1. Run ldapmodify:[2] 

    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.

  2. Create the entry for the new database. 

    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.

  3. Create a root or sub suffix, as described in Section 3.1.1.3, “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.

3.2.1.3. Adding Multiple Databases for a Single Suffix

A single suffix can be distributed across multiple databases. However, to distribute the suffix, a custom distribution function has to be created to extend the directory. For more information on creating a custom distribution function, contact Red Hat Professional Services.

NOTE

Once entries have been distributed, they cannot be redistributed. The following restrictions apply:

  • The distribution function cannot be changed once entry distribution has been deployed.

  • The LDAP modrdn operation cannot be used to rename entries if that would cause them to be distributed into a different database.

  • Distributed local databases cannot be replicated.

  • The ldapmodify operation cannot be used 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.

After creating a custom distribution logic plug-in, add it to the directory.

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

3.2.1.3.1. Adding the Custom Distribution Function to a Suffix Using the Directory Server Console

  1. In the Directory Server Console, select the Configuration tab.

  2. Expand Data in the left navigation pane. Select the suffix to which to apply the distribution function.

  3. Select the Databases tab in the right window.

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

  5. Enter the path to the distribution library in the Distribution library field, or click Browse to locate a distribution library on the local machine.

  6. Enter the name of the distribution function in the Function name field.

  7. Click Save.

3.2.1.3.2. Adding the Custom Distribution Function to a Suffix Using the Command-Line

  1. Run ldapmodify.[2] 

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

  2. Add the following attributes to the suffix entry itself, supplying the information about the custom distribution logic: 

    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 the 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, see Section 2.2.4, “Adding and Modifying Entries Using ldapmodify”.

3.2.2. Maintaining Directory Databases

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

3.2.2.1. Placing a Database in Read-Only Mode

When a database is in read-only mode, you cannot create, modify, or delete any entries. One of the situations when read-only mode is useful is for manually initializing a consumer or before backing up or exporting data from the Directory Server. Read-only mode ensures a faithful image of the state of these databases at a given time.

The Directory Server Console and the command-line utilities do not automatically put the directory in read-only mode before export or backup operations because this would make your directory unavailable for updates. However, with multi-master replication, this might not be a problem.

3.2.2.1.1. Making a Database Read-Only Using the Console

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

  1. In the Directory Server Console, select the Configuration tab.

  2. Expand Data in the left pane. Expand the suffix containing the database to put in read-only mode.

  3. Select the database 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.

The change takes effect immediately.

Before importing or restoring the database, ensure that the databases affected by the operation are not in read-only mode.

To disable read-only mode, open the database up in the Directory Server Console again and uncheck the database is read-only checkbox.

3.2.2.1.2. Making a Database Read-Only from the Command Line

To manually place a database into read-only mode, do the following:

  1. Run ldapmodify.[2] 

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

  2. Change the read-only attribute to on 

    dn: cn=database_name,cn=ldbm database,cn=plugins,cn=config
changetype: modify
replace: nsslapd-readonly
nsslapd-readonly: on

NOTE

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

3.2.2.1.3. Placing the Entire Directory Server in Read-Only Mode

If the Directory Server maintains more than one database and all databases need to be placed in read-only mode, this can be done in a single operation.

WARNING

This operation also makes the Directory Server configuration read-only; therefore, you cannot update the server configuration, enable or disable plug-ins, or even restart the Directory Server while it is in read-only mode. Once read-only mode is enabled, it cannot cannot be undone from the Console; you must modify the configuration files.

NOTE

If Directory Server contains replicas, do not use read-only mode because it will disable replication.

To put the Directory Server in read-only mode, do the following:

  1. In the Directory Server Console, select the Configuration tab, and then select the top entry in the navigation tree in the left pane.

  2. Select the Settings tab in the right pane.

  3. Select the Make Entire Server Read-Only checkbox.

  4. Click Save, and then restart the server.

3.2.2.2. Deleting a Database

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 to delete, and select it.

  3. From the Object menu, select Delete.

    Alternatively, 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 the deletion.

    Once deleted, the database no longer appears in the right pane.

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

  1. Open the configuration directory. 

    cd /etc/dirsrv/slapd-instance_name

  2. Edit the dse.ldif file, and change the nsslapd-db-logdirectory directive for the new log file path: 

    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.

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

3.2.3.1. 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 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 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 back up 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 expiring and needs to be renewed, export the encrypted backend instance before the renewal. Update the certificate, then re-import the exported LDIF file.

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

3.2.3.3. Configuring Database Encryption from the Console

  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 backend to edit, such as dc=example,dc=com.

  4. Next, select the root to edit, such as o=userRoot.

  5. Select the Attribute Encryption tab.

  6. Hit the Add Attribute button, and a list of attributes will appear. Select the attribute to encrypt.

    NOTE

    For existing attribute entries to be encrypted, the information must be exported, then re-imported. See Section 3.2.3.5, “Exporting and Importing an Encrypted Database”.

  7. Select which encryption cipher to use.

  8. Repeat steps 6 and 7 for every attribute to encrypt. Then hit Save.

To remove encryption from attributes, select them from the list of encrypted attributes in the Attribute Encryption table, and hit the Delete button, then hit Save to apply the changes. Any deleted attributes have to be manually re-added after saving.

3.2.3.4. Configuring Database Encryption Using the Command-Line

  1. Run the ldapmodify command[2]: 

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

  2. Add an encryption entry for the attribute being encrypted. For example, this entry encrypts the telephoneNumber attribute with the AES cipher: 

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

  3. For existing attributes in entries to be encrypted, the information must be exported, then re-imported. See Section 3.2.3.5, “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 Directory Server Configuration, Command, and File Reference.

3.2.3.5. Exporting and Importing an Encrypted Database

Exporting and importing encrypted databases is similar 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: 

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

    See Section 4.2.3, “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: 

    ldif2db -n Database1 -E -i /path/to/output.ldif

See Section 4.1.3, “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 db/guardian file, then re-start the server. This will force recovery, a side-effect of which is deleting 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 plain text values for the now-encrypted data. 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. 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, ensure that any page or swap files are adequately protected.