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
Important
To import data, you must store the LDIF file that you want to import in the/var/lib/dirsrv/slapd-instance_name/ldif/
directory. Directory Server usesPrivateTmp
systemd directive by default. As a result, if you export LDIF files into the/tmp/
or/var/tmp/
system directories, Directory Server does not see these LDIF files during import. For more information aboutPrivateTmp
, seesystemd.exec(5)
man page. - Initializing a database for replication
The following table 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 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
Note
In multi-supplier 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-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 import
command. See Section 6.1.2.1.1, “Importing Using thedsconf backend import
Command”. - Create a
cn=tasks
entry. See Section 6.1.2.1.2, “Importing Data Using acn=tasks
Entry”.
- If the instance is offline, use the
dsctl ldif2db
command. See Section 6.1.2.2, “Importing Data While the Server 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:
- Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
- 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.1.3.3, “Creating a Root Entry”.
- 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
Thedsconf 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
/var/lib/dirsrv/slapd-instance_name/ldif/example.ldif
file into the userRoot
database:
- Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
- 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.1.3.3, “Creating a Root Entry”.
- 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.
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:
- Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
- 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.1.3.3, “Creating a Root Entry”.
- 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.ldif
file into theuserRoot
database:# 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
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. - 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:
- Create the suffix if it does not exist. For details, see Section 2.1.1, “Creating Suffixes”.
- 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.1.3.3, “Creating a Root Entry”.
- Store the LDIF file you want to import in the
/var/lib/dirsrv/slapd-instance_name/ldif/
directory. - 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.