Chapter 4. Populating Directory Databases

4.1. Importing Data

Directory Server provides three methods for importing data:

Import from the Directory Server Console. Use the Directory Server Console to append data to all of the databases, including database links.
Initialize databases. The Directory Server Console can import data to one database; this method overwrites any data contained by the database.
Importing data from the command-line. Directory Server provides command-line utilities to import data.

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.

Table 4.1, “Import Method Comparison” describes the differences between an import and initializing databases.

Action	Import	Initialize Database
Overwrites database	No	Yes
LDAP operations	Add, modify, delete	Add only
Performance	More time-consuming	Fast
Partition speciality	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

Table 4.1. Import Method Comparison

The following sections describe importing data:

WARNING

All imported LDIF files must also contain the root suffix.

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

You must be logged in as the Directory Manager in order to perform an import.

To import data from the Directory Server Console, do the following:

In the Directory Server Console, select the Tasks tab. Scroll to the bottom of the screen, and select Import Database.
Alternatively, import by going to the Configuration tab and selecting Import from the Console menu.
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.
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.
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.
Click OK.

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.2. 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, do the following:

Select the Configuration tab.

Expand the Data tree in the left navigation pane. Expand the suffix of the database to initialize, then click the database itself.

Right-click the database, and select Initialize Database.

Alterntatively, select Initialize Database from the Object menu.

In the LDIF file field, enter the full path to the LDIF file to import, or click Browse.

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. ^[3]

4.1.3. Importing from the Command-Line

There are three methods for importing data through the command-line:

Using ldif2db. This import method overwrites the contents of the database and requires the server to be stopped; see Section 4.1.3.1, “Importing Using the ldif2db Command-Line Script”.
Using ldif2db.pl. This import method overwrites the contents of the database while the server is still running; see Section 4.1.3.2, “Importing Using the ldif2db.pl Perl Script”.
Using ldif2ldap. This method appends the LDIF file through LDAP. This method is useful to append data to all of the databases; see Section 4.1.3.3, “Importing Using the ldif2ldap Command-Line Script”.

NOTE

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

4.1.3.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, do the following:

Stop the server. ^[4]
```
service dirsrv stop instance
```
Open the Directory Server instance directory.
```
cd /usr/lib/dirsrv/slapd-instance_name
```
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, Command, and File 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.

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.

Table 4.2. ldif2db Parameters

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

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

Open the Directory Server instance directory.
```
cd /usr/lib/dirsrv/slapd-instance_name
```
Run the ldif2db script.
```
ldif2db -D "cn=Directory Manager" -w secretpwd 
    -i /var/lib/dirsrv/slapd-instance_name/ldif/demo.ldif -n Database1
```
For more information about using this script, see the Directory Server Configuration, Command, and File Reference.
NOTE
You do not need root privileges to run the script, but you must authenticate as the Directory Manager.

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.

Table 4.3. ldif2db Options

4.1.3.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, do the following:

Open the Directory Server instance directory:
```
cd /usr/lib/dirsrv/slapd-instance_name
```
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, Command, and File Reference.

^[3] This is the location for Red Hat Enterprise Linux 5 (32-bit). File locations for other platforms are listed in Section 1.1, “Directory Server File Locations”.

^[4] The command to start and stop the Directory Server on platforms other than Red Hat Enterprise Linux 5 (32-bit) is described in Section 1.3, “Starting and Stopping Servers”.