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
ImportantTo import data, you must store the LDIF file that you want to import in the
- Initializing a database for replication
The following table describes the differences between an import and initializing databases:
Table 6.1. Import Method Comparison
|LDAP operations||Add, modify, delete||Add only|
|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 (||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-initvalparameter, which sets a starting USN for all imported entries.
There are two possible values for
- 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.
nsslapd-entryusn-import-initvalis 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
1000before the import or initialization operation, and the
next, then every imported entry is assigned a USN of
# 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-initvalparameter to the server into which data are being imported or to the supplier server which will perform the initialization. For example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-entryusn-import-initval=next
In multi-supplier replication, the
nsslapd-entryusn-import-initvalparameter 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
nsslapd-entryusn-import-initvalset to next and is used to initialize a replica, then the entry USNs for imported entries have the highest value plus one. If the
Supplier2host does not have
nsslapd-entryusn-import-initvalset and is used to initialize a replica, then all entry USNs for imported entries begin at zero — even if
Supplier2have a multi-supplier 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:
- Use one of the following methods if the instance is running:
- Use the
dsconf backend importcommand. See Section 184.108.40.206.1, “Importing Using the
dsconf backend importCommand”.
- Create a
cn=tasksentry. See Section 220.127.116.11.2, “Importing Data Using a
- If the instance is offline, use the
dsctl ldif2dbcommand. See Section 18.104.22.168, “Importing Data While the Server is Offline”.
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-8character 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
dirsrvuser. Therefore, the permissions of the LDIF file must allow this user to read the file.
22.214.171.124. Importing Data While the Server is Running
This section describes how you can import data while Directory Server is running.
126.96.36.199.1. Importing Using the
dsconf backend import Command
dsconf backend importcommand 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.ldiffile into the
- 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 successfullyThe
dsconf backend importcommand supports additional options, for example, to exclude a specific suffix. To display all available options, enter:
# dsconf ldap://server.example.com backend import --help
188.8.131.52.2. Importing Data Using a
cn=tasks,cn=configentry 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
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
/var/lib/dirsrv/slapd-instance_name/ldif/example.ldiffile into the
- 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: /var/lib/dirsrv/slapd-instance_name/ldif/example.ldif nsInstance: userRoot
When the task is completed, the entry is removed from the directory configuration.
184.108.40.206. Importing Data While the Server is Offline
If the server is offline when you import data, use the
- Stop the instance:
# dsctl instance_name stop
- Import the data from the LDIF file. For example, to import the
/var/lib/dirsrv/slapd-instance_name/ldif/example.ldiffile into the
# dsctl instance_name ldif2db userroot /var/lib/dirsrv/slapd-instance_name/ldif/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
WarningIf 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.
- 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:
- Store the LDIF file you want to import in the
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open the Database menu.
- Select the suffix entry.
- Click Suffix Tasks, and select Initialize Suffix.
- Select the LDIF file to import or enter the full path to the file.
- Select Yes, I am sure., and click Initialize Database to confirm.