Chapter 6. Populating Directory Databases

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

6.1. Importing Data

Directory Server can populate a database with data by:
  • Importing data
  • 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 the web console Local to the web 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 parameter, 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.

Example 6.1. How the nsslapd-entryusn-import-initval Parameter works

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=user_name,ou=people,dc=example,dc=com
entryusn: 1001
...
To set an initial value for entry USNs, add the nsslapd-entryusn-import-initval parameter to the server into which data are being imported or to the master server which will perform the initialization. For example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-entryusn-import-initval=next

Note

In multi-master replication, the nsslapd-entryusn-import-initval parameter 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 the Supplier1 host 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 the Supplier2 host 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 Supplier2 have a multi-master replication agreement between them.

6.1.2. Importing Using the Command Line

Directory Server supports importing data while the instance is running or while the instance is offline:

Warning

When you start an import operation, Directory Server first removes all existing data from the database and subsequently imports the data from the LDIF file. If the import fails, for example, because the LDIF file does not exist, the server has already removed the previous data from the database.
Note that the LDIF files used for import operations must use UTF-8 character set encoding. Import operations do not convert data from the local character set encoding to UTF-8. Additionally, all imported LDIF files must contain the root suffix entry.
Directory Server runs import operations as the dirsrv user. Therefore, the permissions of the LDIF file must allow this user to read the file.

6.1.2.1. Importing Data While the Server is Running

This section describes how you can import data while Directory Server is running.
6.1.2.1.1. Importing Using the dsconf backend import Command
Use the dsconf backend import command to automatically create a task that imports data from an LDIF file. For example, to import the /var/lib/dirsrv/slapd-instance_name/ldif/instance_name-database_name-time_stamp.ldif file into the userRoot database:
  1. Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
  2. If the LDIF you want to import does not contain statements that add the suffix entry, create this entry manually as described in Section 3.3.3, “Creating a Root Entry”.
  3. Import the LDIF file:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend import userRoot /var/lib/dirsrv/slapd-instance_name/ldif/instance_name-database_name-time_stamp.ldif
    The import task has finished successfully
    The dsconf backend import command supports additional options, for example, to exclude a specific suffix. To display all available options, enter:
    # dsconf ldap://server.example.com backend import --help
6.1.2.1.2. Importing Data Using a cn=tasks Entry
The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries the server uses to manage tasks. To initiate an import operation, create a task in the cn=import,cn=tasks,cn=config entry.
An import task entry requires the following attributes:
  • cn: Sets the unique name of the task.
  • nsFilename: Sets the name of the LDIF file to import.
  • nsInstance: Sets the name of the database into which the file should be imported.
Import tasks support additional parameters, for example, to exclude suffixes. For a complete list, see the cn=import section in the Red Hat Directory Server Configuration, Command, and File Reference.
For example, to add a task that imports the content of the /tmp/example.ldif file into the userRoot database:
  1. Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
  2. If the LDIF you want to import does not contain statements that add the suffix entry, create this entry manually as described in Section 3.3.3, “Creating a Root Entry”.
  3. Add the import task:
    # ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com -x
    
    dn: cn=example_import,cn=import,cn=tasks,cn=config
    changetype: add
    objectclass: extensibleObject
    cn: example_import
    nsFilename: /tmp/example.ldif
    nsInstance: userRoot
When the task is completed, the entry is removed from the directory configuration.

6.1.2.2. Importing Data While the Server is Offline

If the server is offline when you import data, use the dsctl ldif2db command:
  1. Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
  2. If the LDIF you want to import does not contain statements that add the suffix entry, create this entry manually as described in Section 3.3.3, “Creating a Root Entry”.
  3. Stop the instance:
    # dsctl instance_name stop
  4. Import the data from the LDIF file. For example, to import the /tmp/example.ldif file into the userRoot database:
    # dsctl instance_name ldif2db userroot /tmp/example.ldif 
    OK group dirsrv exists
    OK user dirsrv exists
    [17/Jul/2018:13:42:42.015554231 +0200] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000
    ...
    [17/Jul/2018:13:42:44.302630629 +0200] - INFO - import_main_offline - import userroot: Import complete.  Processed 160 entries in 2 seconds. (80.00 entries/sec)
    ldif2db successful

    Warning

    If the database specified in the command does not correspond with the suffix contained in the LDIF file, all data contained in the database is deleted, and the import fails.
  5. Start the instance:
    # dsctl instance_name start

6.1.3. Importing Data Using the Web Console

To import data from an LDIF file using the web console:
  1. Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
  2. If the LDIF you want to import does not contain statements that add the suffix entry, create this entry manually as described in Section 3.3.3, “Creating a Root Entry”.
  3. Store the LDIF file you want to import in the /var/lib/dirsrv/slapd-instance_name/ldif/ directory.
  4. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  5. Select the instance.
  6. Open the Database menu.
  7. Select the suffix entry.
  8. Click Suffix Tasks, and select Initialize Suffix.
  9. Select the LDIF file to import or enter the full path to the file.
  10. Select Yes, I am sure., and click Initialize Database to confirm.