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

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

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

In the Directory Server Console, select the Configuration tab.
In the left pane, expand Data, then click the suffix to which to add the new database.
Right-click the suffix, and select New Database from the pop-up menu.
Enter a unique name for the database, such as example2. The database name can be a combination of alphanumeric characters, dashes (-), and underscores (_).
The Create database in field is automatically filled with the default database directory (/var/lib/dirsrv/slapd-instance_name/db) and the name of the new database. It is also possible to enter or browse for a different directory location.

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

Run ldapmodify and create the entry for the new database.

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

dn: cn=UserData,cn=ldbm database,cn=plugins,cn=config
changetype: add
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.

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

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

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

In the Directory Server Console, select the Configuration tab.
Expand Data in the left navigation pane. Select the suffix to which to apply the distribution function.
Select the Databases tab in the right window.
The databases associated with the suffix are already listed in the Databases tab. Click Add to associate additional databases with the suffix.
Enter the path to the distribution library.
Enter the name of the distribution function in the Function name field.

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

Run ldapmodify.

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

Add the following attributes to the suffix entry itself, supplying the information about the custom distribution logic:
```
dn: suffix
changetype: modify
add: nsslapd-backend
nsslapd-backend: Database1 
-
add: nsslapd-backend
nsslapd-backend: Database2 
-
add: nsslapd-backend
nsslapd-backend: Database3 
-
add: nsslapd-distribution-plugin
nsslapd-distribution-plugin: /full/name/of/a/shared/library 
-
add: nsslapd-distribution-funct
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 3.2.4, “Adding and Modifying Entries Using ldapmodify”.

2.2.2. Maintaining Directory Databases

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

2.2.2.1.1. Making a Database Read-Only Using the Console

In the Directory Server Console, select the Configuration tab.
Expand Data in the left pane. Expand the suffix containing the database to put in read-only mode.
Select the database to put into read-only mode.
Select the Database Settings tab in the right pane.
Select the database is read-only check box.

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

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

To manually place a database into read-only mode:

Run ldapmodify.

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

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.

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

In the Directory Server Console, select the Configuration tab, and then select the top entry in the navigation tree in the left pane.
Select the Settings tab in the right pane.
Select the Make Entire Server Read-Only check box.
Click Save, and then restart the server.

2.2.2.2. Deleting a Database

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.
Expand the Data folder, and then select the suffix.
Select the database to delete.
Right-click the database and select Delete from the pop-up menu.
Confirm that the database should be deleted in the Delete Database dialog box.

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

Storing the transaction log files on a separate physical disk improves performance because the disk heads do not thrash moving between the log files and the data files.

Stop the Directory Server instance.
```
service dirsrv stop example
```
Create the new directory, if necessary, where the transaction logs will be located.
```
mkdir /home/exampledb-txnlogs
```
Set the appropriate file permissions on the directory so that the Directory Server user can access it; the default Directory Server user and group is nobody:nobody. However, Red Hat strongly recommends to use a different user and group name such as dirsrv during the installation.
```
chown nobody:nobody /home/exampledb-txnlogs
```
Open the dse.ldif file in the Directory Server instance's configuration directory.
```
[root@server ~]# vim /etc/dirsrv/slapd-instance_name/dse.ldif
```
Change the nsslapd-db-logdirectory directive for the new log file path:
```
nsslapd-db-logdirectory: /home/exampledb-txnlogs
```
This attribute goes on the same entry that has the nsslapd-dbcachesize attribute.

Open the database directory.

[root@server ~]# cd /var/lib/dirsrv/slapd-instance_name/db

Remove all of the __db.* files.
Move the log.* files to the new location.

Start the Directory Server instance again.

[root@server ~]# service dirsrv start example

2.2.3. Configuring Attribute 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 back end. When configured, every instance of a particular attribute, even index data, is encrypted for every entry stored in that database.

Note

There is one exception to encrypted data: any value which is used as the RDN for an entry is not encrypted within the entry DN. For example, if the uid attribute is encrypted, the value is encrypted in the entry but is displayed in the DN:

# entry-id: 16
dn: uid=jsmith1234,ou=People,dc=example,dc=com
nsUniqueId: ee91ea82-1dd111b2-9f36e9bc-39fb8550
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
givenName: John
sn: Smith
uid:: Sf04P9nJWGU1qiW9JJCGRg==

That would allow someone to discover the encrypted value.

Any attribute used within the entry DN cannot be effectively encrypted, since it will always be displayed in the DN. Be aware of what attributes are used to build the DN and design the attribute encryption model accordingly.

Indexed attributes may be encrypted, and attribute 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.

2.2.3.1. Encryption Keys

In order to use attribute encryption, the server must be configured for SSL and have SSL enabled because attribute 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 attribute 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.

Warning

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.

Warning

If the SSL certificate is expiring and needs to be renewed, export the encrypted back end instance before the renewal. Update the certificate, then re-import the exported LDIF file.

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

2.2.3.3. Configuring Attribute Encryption from the Console

In the Configuration tab, select the Data node.
Expand the suffix, and select the database to edit.
Select the Attribute Encryption tab.
Click the Add Attribute button to open the list of attributes. Select the attribute to encrypt.
Note
For existing attribute values to be encrypted, the information must be exported from the database, then re-imported. See Section 2.2.3.6, “Exporting and Importing an Encrypted Database”.
Select which encryption cipher to use.

Note

The encryption cipher to use is set separately for each attribute, so attribute encryption is applied to each attribute one at a time.

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

2.2.3.4. Configuring Attribute Encryption Using the Command Line

Run the ldapmodify command:

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

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
changetype: add
objectclass: top
objectclass: nsAttributeEncryption
cn: telephoneNumber
nsEncryptionAlgorithm: AES

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

For more information on attribute encryption configuration schema, see "Database Attributes under cn=attributeName,cn=encrypted attributes,cn=database_name,cn=ldbm database,cn=plugins,cn=config" in the Directory Server Configuration and Command-Line Tool Reference.

2.2.3.5. Enabling Attribute Encryption for Existing Attribute Values

To enable attribute 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.

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

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.
Make any configuration changes.
Re-import the data using the ldif2db script, as follows:
```
ldif2db -n Database1 -E -i /path/to/output.ldif
```

See Section 4.1.6, “Importing from the Command Line” for more information.

Note

When enabling encryption for data that is already present in 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.

2.2.3.7. Updating Attribute Encryption Keys for New SSL/TLS Certificates

When SSL is first configured, there is no problem with attribute encryption. However, if the SSL certificate is changed, then attribute encryption fails, with messages like these:

Apr  4 13:00:35 smtp1 logger: [04/Apr/2017:13:00:34 -0700] - attrcrypt_unwrap_key: failed to unwrap key for cipher AES
Apr  4 13:00:35 smtp1 logger: [04/Apr/2017:13:00:34 -0700] - Failed to retrieve key for cipher AES in attrcrypt_cipher_init
Apr  4 13:00:35 smtp1 logger: [04/Apr/2017:13:00:34 -0700] - Failed to initialize cipher AES in attrcrypt_init
Apr  4 13:00:35 smtp1 logger: [04/Apr/2017:13:00:34 -0700] - attrcrypt_unwrap_key: failed to unwrap key for cipher AES
Apr  4 13:00:35 smtp1 logger: [04/Apr/2017:13:00:34 -0700] - Failed to retrieve key for cipher AES in attrcrypt_cipher_init
Apr  4 13:00:35 smtp1 logger: [04/Apr/2017:13:00:34 -0700] - Failed to initialize cipher AES in attrcrypt_init

This is because the previously-generated keys do not work with the new server certificate. To correct these errors, force the server to generate new keys for attribute encryption:

Stop the server.
```
service dirsrv stop
```
Open the dse.ldif file.
```
vim /etc/dirsrv/dse.ldif
```

There are special encryption key entries for the encryption ciphers used for attribute encryption under the database configuration. For example:

dn: cn=AES,cn=encrypted attribute keys,cn=userRoot,cn=ldbm database,cn=plugins,cn=config
objectClass: top
objectClass: extensibleObject
cn: AES
nssymmetrickey:: mSLm/RlCLvPZrSdARHPowedF9zKx+kjVTww5ARE4w0lbl2YlYvrI3bNg=

Delete these entries.

Start the server again.
```
service dirsrv start
```

Where did the comment section go?

Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.