Chapter 6. Populating Directory Databases

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

6.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 6.1, “Import Method Comparison” describes the differences between an import and initializing databases.

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

6.1.1. Setting EntryUSN Initial Values During Import

Entry update sequence numbers (USNs) are not preserved when entries are exported from one server and imported into another. As Section 4.1, “Tracking Modifications to the Database through Update Sequence Numbers” explains, entry USNs are assigned for operations that happen on a local server, so it does not make sense to import those USNs onto another server.
However, it is possible to configure an initial entry USN value for entries when importing a database or initializing a database (such as when a replica is initialized for replication). This is done by setting the nsslapd-entryusn-import-initval attribute, which sets a starting USN for all imported entries.
There are two possible values for nsslapd-entryusn-import-initval:
  • An integer, which is the explicit start number used for every imported entry.
  • next, which means that every imported entry uses whatever the highest entry USN value was on the server before the import operation, incremented by one.
If nsslapd-entryusn-import-initval is not set, then all entry USNs begin at zero.
For example, if the highest value on the server is 1000 before the import or initialization operation, and the nsslapd-entryusn-import-initval value is next, then every imported entry is assigned a USN of 1001: 
# ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com -x "(cn=*)" entryusn

dn: dc=example,dc=com
entryusn: 1001
dn: ou=Accounting,dc=example,dc=com
entryusn: 1001
dn: ou=Product Development,dc=example,dc=com
entryusn: 1001
...
dn: uid=jsmith,ou=people,dc=example,dc=com
entryusn: 1001
...
To set an initial value for entry USNs, simply add the nsslapd-entryusn-import-initval attribute to the server into which data are being imported or to the master server which will perform the initialization. 
# ldapmodify -D "cn=Directory Manager" -W -x -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=config
changetype: modify
add: nsslapd-entryusn-import-initval
nsslapd-entryusn-import-initval: next

Note

In multi-master replication, the nsslapd-entryusn-import-initval attribute is not replicated between servers. This means that the value must be set specifically on whichever supplier server is being used to initialize a replica.
For example, if Supplier1 has nsslapd-entryusn-import-initval set to next and is used to initialize a replica, then the entry USNs for imported entries have the highest value plus one. If Supplier2 does not have nsslapd-entryusn-import-initval set and is used to initialize a replica, then all entry USNs for imported entries begin at zero — even if Supplier1 and Supplier 2 have a multi-master replication agreement between them.

6.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 check box.
    • Continue on Error. Select the Continue on error check box 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.

6.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/ldif.

6.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 10.7, “Exporting and Importing an Encrypted Database” for more information.

6.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 an LDIF:
  1. Stop the server: 
    # systemctl stop dirsrv@instance
  2. Run the ldif2db command-line script: 
    # ldif2db -Z instance_name -n Database1 -i /var/lib/dirsrv/slapd-instance/ldif/demo.ldif -i /var/lib/dirsrv/slapd-instance/ldif/demo2.ldif
    For information about the parameters used in the example, see the description of the ldif2db script in the Red Hat 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.
  3. Start the server: 
    # systemctl start dirsrv@instance

6.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.
Run the ldif2db.pl script: 
# ldif2db.pl -Z instance_name -D "cn=Directory Manager" -w secret -i /var/lib/dirsrv/slapd-instance/ldif/demo.ldif -n Database1
For information about the parameters used in the example, see the description of the ldif2db.pl script in the Red Hat 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.

6.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: 
[root@server ~]# ldif2ldap -Z instance_name -D "cn=Directory Manager" -w secretpwd /var/lib/dirsrv/slapd-instance/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 information about the parameters used in the example, see the description of the ldif2ldap script in the Red Hat Directory Server Configuration, Command, and File Reference.

6.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.1.3.2, “Adding an Entry Using ldapmodify”. For example: 
# ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=example import,cn=import,cn=tasks,cn=config
changetype: add
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.
For details about the attributes used in the example and other attributes you can set in this entry, see the cn=import,cn=tasks,cn=config entry description in the Red Hat Directory Server Configuration, Command, and File Reference