Chapter 4. Populating Directory Databases

Databases contain the directory data managed by the Red Hat Directory Server.

4.1. Importing Data

Directory Server can populate a database with data in one of two ways: by importing data (either through the Directory Server Console or using the import tools) or by initializing a database for replication.
Table 4.1, “Import Method Comparison” describes the differences between an import and initializing databases.

Table 4.1. Import Method Comparison

Action Import Initialize Database
Overwrites database No Yes
LDAP operations Add, modify, delete Add only
Performance More time-consuming Fast
Partition specialty Works on all partitions Local partitions only
Response to server failure Best effort (all changes made up to the point of the failure remain) Atomic (all changes are lost after a failure)
LDIF file location Local to Console Local to Console or local to server
Imports configuration information (cn=config) Yes No

4.1.1. Importing Entries with Large Attributes

The nsslapd-cachememsize attribute defines the size allowed for the entry cache.
The import buffer is automatically set to 80% of the cache memory size setting. If the memory cache is 1GB, for example, then the import buffer is 800MB.
When importing a very large database or entries with large attributes (often with values like binary data like certificate chains, CRLs, or images), then set the nsslapd-cachememsize attribute high enough so that the import buffer has enough memory to process the entries.

4.1.2. Importing a Database from the Console

When performing an import operation from the Directory Server Console, an ldapmodify operation is executed to append data, as well as to modify and delete entries. The operation is performed on all of the databases managed by the Directory Server and on remote databases to which the Directory Server has a configured database link.
Import operations can be run on a server instance that is local to the Directory Server Console or on a different host machine (a remote import operation).
You must be logged in as the Directory Manager in order to perform an import.

NOTE

The LDIF files used for import operations must use UTF-8 character set encoding. Import operations do not convert data from local character set encoding to UTF-8 characterset encoding.

WARNING

All imported LDIF files must also contain the root suffix.
To import data from the Directory Server Console:
  1. Select the Tasks tab. Scroll to the bottom of the screen, and select Import Database.
    Alternatively, open the Configuration tab and select Import from the Console menu.
  2. In the Import Database dialog box, enter the full path to the LDIF file to import in the LDIF file field, or click Browse to select the file to import.
    If the Console is running on a machine remote to the directory, the field name appears as LDIF file (on the machine running the Console). When browsing for a file, you are not browsing the current directory for the Directory Server host, but the filesystem of the machine running the Console.
    When importing a database through a remote Console, do not use a relative path to the database. For remote imports, the operation fails with the error Cannot write to file... if a relative path is given for the file. Always use an absolute path for remote import operations.
  3. In the Options box, select one or both of the following options:
    • Add Only. The LDIF file may contain modify and delete instructions in addition to the default add instructions. For the server to ignore operations other than add, select the Add only checkbox.
    • Continue on Error. Select the Continue on error checkbox for the server to continue with the import even if errors occur. For example, use this option to import an LDIF file that contains some entries that already exist in the database in addition to new ones. The server notes existing entries in the rejects file while adding all new entries.
  4. In the File for Rejects field, enter the full path to the file in which the server is to record all entries it cannot import, or click Browse to select the file which will contain the rejects.
    A reject is an entry which cannot be imported into the database; for example, the server cannot import an entry that already exists in the database or an entry that has no parent object. The Console will write the error message sent by the server to the rejects file.
    Leaving this field blank means the server will not record rejected entries.
The server performs the import and also creates indexes.

NOTE

Trailing spaces are dropped during a remote Console import but are preserved during both local Console or ldif2db import operations.

4.1.3. Initializing a Database from the Console

The existing data in a database can be overwritten by initializing databases.
You must be logged in as the Directory Manager in order to initialize a database because an LDIF file that contains a root entry cannot be imported into a database except as the Directory Manager (root DN). Only the Directory Manager has access to the root entry, such as dc=example,dc=com.

WARNING

When initializing databases from an LDIF file, be careful not to overwrite the o=NetscapeRoot suffix unless you are restoring data. Otherwise, initializing the database deletes information and may require re-installing the Directory Server.
To initialize a database using the Directory Server Console:
  1. Select the Configuration tab.
  2. Expand the Data tree in the left navigation pane. Expand the suffix of the database to initialize, then click the database itself.
  3. Right-click the database, and select Initialize Database.
    Alternatively, select Initialize Database from the Object menu.
  4. In the LDIF file field, enter the full path to the LDIF file to import, or click Browse.
  5. If the Console is running from a machine local to the file being imported, click OK and proceed with the import immediately. If the Console is running from a machine remote to the server containing the LDIF file, select one of the following options, then click OK:
    • From local machine. Indicates that the LDIF file is located on the local machine.
    • From server machine. Indicates that the LDIF file is located on a remote server.
    The default LDIF directory is /var/lib/dirsrv/slapd-instance_name/ldif.

4.1.4. Importing from the Command Line

There are four methods for importing data through the command line:

NOTE

The LDIF files used for import operations must use UTF-8 character set encoding. Import operations do not convert data from local character set encoding to UTF-8 characterset encoding.

WARNING

All imported LDIF files must also contain the root suffix.

NOTE

To import a database that has been encrypted, use the -E option with the script. See Section 2.2.3.5, “Exporting and Importing an Encrypted Database” for more information.

4.1.4.1. Importing Using the ldif2db Command-Line Script

The ldif2db script overwrites the data in the specified database. Also, the script requires that the Directory Server be stopped when the import begins.
By default, the script first saves and then merges any existing o=NetscapeRoot configuration information with the o=NetscapeRoot configuration information in the files being imported.

WARNING

This script overwrites the data in the database.
To import LDIF:
  1. Stop the server.
    service dirsrv stop instance
  2. Open the Directory Server instance directory.
    cd /etc/dirsrv/slapd-instance_name
  3. Run the ldif2db command-line script.
    ldif2db -n Database1 -i /var/lib/dirsrv/slapd-instance_name/ldif/demo.ldif
     -i /var/lib/dirsrv/slapd-instance_name/ldif/demo2.ldif
    For more information about using this script, see the Directory Server Configuration and Command-Line Tool Reference.

    WARNING

    If the database specified in the -n option does not correspond with the suffix contained by the LDIF file, all of the data contained by the database is deleted, and the import fails. Make sure that the database name is not misspelled.

Table 4.2. ldif2db Parameters

Option Description
-i Specifies the full path name of the LDIF files to be imported. This option is required. To import more than one LDIF file at a time, use multiple -i arguments. When multiple files are imported, the server imports the LDIF files in the order which they are specified from the command line.
-n Specifies the name of the database to which to import the data.

For more information about using this script, see the Directory Server Configuration and Command-Line Tool Reference.

4.1.4.2. Importing Using the ldif2db.pl Perl Script

As with the ldif2db script, the ldif2db.pl script overwrites the data in the specified database. This script requires the server to be running in order to perform the import.

WARNING

This script overwrites the data in the database.
  1. Open the Directory Server instance directory.
    cd /etc/dirsrv/slapd-instance_name
  2. Run the ldif2db script.
    ldif2db -D "cn=Directory Manager" -w secret -i /var/lib/dirsrv/slapd-instance_name/ldif/demo.ldif -n Database1
    For more information about using this script, see the Directory Server Configuration and Command-Line Tool Reference.

    NOTE

    You do not need root privileges to run the script, but you must authenticate as the Directory Manager.

Table 4.3. ldif2db Options

Option Description
-D Specifies the DN of the administrative user.
-w Specifies the password of the administrative user.
-i Specifies the LDIF files to be imported. This option is required. To important multiple LDIF files at a time, use multiple -i arguments. When multiple files are imported, the server imports the LDIF files in the order they are specified in the command line.
-n Specifies the name of the database to which to import the data.

4.1.4.3. Importing Using the ldif2ldap Command-Line Script

The ldif2ldap script appends the LDIF file through LDAP. Using this script, data are imported to all directory databases at the same time. The server must be running in order to import using ldif2ldap.
To import LDIF using ldif2ldap:
  1. Open the Directory Server instance directory:
    cd /etc/dirsrv/slapd-instance_name
  2. Run the ldif2ldap command-line script.
    ldif2ldap "cn=Directory Manager" secretpwd /var/lib/dirsrv/slapd-instance_name/ldif/demo.ldif
    The ldif2ldap script requires the DN of the administrative user, the password of the administrative user, and the absolute path and filename of the LDIF files to be imported.
    For more information about using this script, see the Directory Server Configuration and Command-Line Tool Reference.

4.1.4.4. Importing through the cn=tasks Entry

The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries that the server uses to manage tasks. Several common directory tasks have container entries under cn=tasks,cn=config. Temporary task entries can be created under cn=import,cn=tasks,cn=config to initiate an import operation.
As with the ldif2db and ldif2db.pl scripts, an import operation in cn=tasks overwrites all of the information in the database.
This task entry requires three attributes:
  • A unique name (cn)
  • The filename of the LDIF file to import (nsFilename)
  • The name of the database into which to import the file (nsInstance)
It is also possible to supply the DNs of suffixes to include or exclude from the import, analogous to the -s and -x options, respectively, for the ldif2db and ldif2db.pl scripts.
The entry is simply added using ldapmodify, as described in Section 3.2.4, “Adding and Modifying Entries Using ldapmodify”. For example:
/usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com

dn: cn=example import,cn=import,cn=tasks,cn=config
objectclass: extensibleObject
cn: example import
nsFilename: /home/files/example.ldif
nsInstance: userRoot
nsIncludeSuffix: ou=People,dc=example,dc=com
nsExcludeSuffix: ou=Groups,dc=example,dc=com
As soon as the task is completed, the entry is removed from the directory configuration.
The Directory Server Configuration and Command-Line Tool Reference has more information on the available attributes for running Directory Server import tasks under the cn=tasks entries.