Importing and exporting data
Procedures on how to populate and extract directory databases
Abstract
Providing feedback on Red Hat documentation
We appreciate your input on our documentation. Please let us know how we could make it better. To do so:
For submitting feedback through Jira (account required):
- Log in to the Jira website.
- Click Create in the top navigation bar
- Enter a descriptive title in the Summary field.
- Enter your suggestion for improvement in the Description field. Include links to the relevant parts of the documentation.
- Click Create at the bottom of the dialogue.
For submitting feedback through Bugzilla (account required):
- Go to the Bugzilla website.
- As the Component, use Documentation.
- Fill in the Description field with your suggestion for improvement. Include a link to the relevant part(s) of documentation.
- Click Submit Bug.
Chapter 1. Importing data to Directory Server
Import data from an LDIF file to a Directory Server database using the command line or the web console.
To import data, you must store the LDIF file that you want to import in the /var/lib/dirsrv/slapd-instance_name/ldif/
directory.
1.1. Importing data using the command line while the server is running
To import data while the Directory Server instance is running, use the dsconf backend import
command.
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. Therefore, if the import fails, the server returns no entries or a partial set of entries.
Prerequisites
-
The LDIF file permissions allow the
dirsrv
user to read the file. - The LDIF file to import contains the root suffix entry.
- The suffix and its database, to which you want to import data, exists in the directory.
- The Directory Server instance is running.
- The LDIF file to import uses UTF-8 character set encoding.
Procedure
Optional: By default, Directory Server sets the entry update sequence numbers (USNs) of all imported entries to
0
. To set an alternative initial USN value, set thensslapd-entryusn-import-initval
parameter. For example, to set USN for all imported values to12345
, enter:#
dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-entryusn-import-initval=12345
If you copied the file you want to import to
/var/lib/dirsrv/slapd-instance_name/ldif/
, reset the SELinux context on that file:#
restorecon -Rv /var/lib/dirsrv/slapd-instance_name/ldif/example.ldif
Use the
dsconf backend import
command to import data from an LDIF file.For example, to import the
/var/lib/dirsrv/slapd-instance_name/ldif/example.ldif
file into theuserRoot
database:#
dsconf -D "cn=Directory Manager" ldap://server.example.com backend import userRoot /var/lib/dirsrv/slapd-instance_name/ldif/example.ldif
The import task has finished successfully-
Search the
/var/log/dirsrv/slapd-instance_name/errors
log for problems during the import.
Verification
Search for entries under the imported suffix, for example
dc=example,dc=com
:#
ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com -b "dc=example,dc=com" -s sub -x
Additional resources
1.2. Importing data using the command line while the server is offline
If the Directory Server instance is offline, use the dsctl ldif2db
command to import data.
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. Therefore, if the import fails, the server returns no entries or a partial set of entries.
Prerequisites
-
The LDIF file permissions allow the
dirsrv
user to read the file. - The LDIF file to import contains the root suffix entry.
- The suffix and its database, to which you want to import data, exists in the directory.
- The Directory Server instance is not running.
- The LDIF file to import uses UTF-8 character set encoding.
Procedure
Optional: By default, Directory Server sets the entry update sequence numbers (USNs) of all imported entries to
0
. To set an alternative initial USN value, set thensslapd-entryusn-import-initval
parameter. For example, to set USN for all imported values to12345
, enter:#
dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-entryusn-import-initval=12345
If you copied the file you want to import to
/var/lib/dirsrv/slapd-instance_name/ldif/
, reset the SELinux context on that file:#
restorecon -Rv /var/lib/dirsrv/slapd-instance_name/ldif/example.ldif
Use the
dsctl ldif2db
command to import data from an 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/2021:13:42:42.015554231 +0200] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000 ... [17/Jul/2021: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-
Search the
/var/log/dirsrv/slapd-instance_name/errors
log for problems during the import. Optional: Start the instance:
#
dsctl instance_name start
Verification
Search for entries under the imported suffix, for example
dc=example,dc=com
:#
ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com -b "dc=example,dc=com" -s sub -x
Additional resources
- Storing suffixes in separate databases
- nsslapd-entryusn-import-initval
-
To display all additional settings that you can use to import data, see the output of the
dsctl ldif2db --help
command.
1.3. Importing data using the web console while the server is running
Directory Server supports importing data using the web console.
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. Therefore, if the import fails, the server returns no entries or a partial set of entries.
Prerequisites
-
The LDIF file permissions allow the
dirsrv
user to read the file. - The LDIF file to import contains the root suffix entry.
- The suffix and its database, to which you want to import data, exists in the directory.
-
The LDIF file is stored in the
/var/lib/dirsrv/slapd-instance_name/ldif/
directory and has thedirsrv_var_lib_t
SELinux context set. - The Directory Server instance is running.
- You are logged in to the instance in the web console.
- The LDIF file to import uses UTF-8 character set encoding.
Procedure
- In the web console, open the Database menu.
- Select the suffix entry.
-
Click Suffix Tasks, and select
Initialize Suffix
. -
Click the Import button next to the LDIF file you want to import. If the LDIF file is stored in a directory different than
/var/lib/dirsrv/slapd-instance_name/ldif/
, enter the full path to the file and click the Import button. -
Select
Yes, I am sure
, and click Initialize Database to confirm. - To check the log for problems during the import, open the Monitoring → Logging → Errors Log menu.
Verification
Search for entries under the imported suffix, for example
dc=example,dc=com
:#
ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com -b "dc=example,dc=com" -s sub -x
Additional resources
Chapter 2. Exporting data from Directory Server
Export data from the Directory Server database to an LDIF file using the command line or the web console.
The export operations include only directory data. Export does not include the configuration information (cn=config
), schema information (cn=schema
), and monitoring information (cn=monitor
).
Use the export feature to:
- Copy data to another Directory Server.
- Export data to another application.
- Repopulate databases after a change to the directory topology.
- Split the database.
2.1. Exporting data using the command line while the server is running
To export data while the Directory Server instance is running, use the dsconf backend export
command.
Prerequisites
-
The
dirsrv
user has write permissions in the destination directory. - The Directory Server instance is running.
Procedure
Use the
dsconf backend export
command to export data to an LDIF file.For example, to export the
userRoot
database:#
dsconf -D "cn=Directory Manager" ldap://server.example.com backend export userRoot
The export task has finished successfullyBy default,
dsconf
stores the export in a file calledinstance_name_database_name-time_stamp.ldif
in the/var/lib/dirsrv/slapd-instance_name/export/
directory. Alternatively, add the-l file_name
option to the command to specify a different location.-
Search the
/var/log/dirsrv/slapd-instance_name/errors
log for problems during the export.
Additional resources
-
To display all additional settings that you can use to export data, see the output of the
dsconf ldap://server.example.com backend export --help
command. - Importing data using the command line while the server is running
- Backing up Directory Server
2.2. Exporting data using the command line while the server is offline
If the Directory Server instance is offline, use the dsctl db2ldif
command to export data.
Prerequisites
-
The
dirsrv
user has write permissions in the destination directory. - The Directory Server instance is not running.
Procedure
Use the
dsctl db2ldif
command to export data to an LDIF file. For example, to export theuserRoot
database to the/var/lib/dirsrv/slapd-instance_name/example.ldif
file:#
dsctl instance_name db2ldif userRoot /var/lib/dirsrv/slapd-instance_name/example.ldif
OK group dirsrv exists OK user dirsrv exists ldiffile: /var/lib/dirsrv/slapd-instance_name/example.ldif [18/Jul/2021:10:46:03.353656777 +0200] - INFO - ldbm_instance_config_cachememsize_set - force a minimal value 512000 [18/Jul/2021:10:46:03.383101305 +0200] - INFO - ldbm_back_ldbm2ldif - export userRoot: Processed 160 entries (100%). [18/Jul/2021:10:46:03.391553963 +0200] - INFO - dblayer_pre_close - All database threads now stopped db2ldif successful-
Search the
/var/log/dirsrv/slapd-instance_name/errors
log for problems during the export. Optional: Start the instance:
#
dsctl instance_name start
Additional resources
-
To display all additional settings that you can use to import data, see the output of the
dsctl db2ldif --help
command. - Importing data using the command line while the server is offline
- Backing up Directory Server
2.3. Exporting data using the web console while the server is running
Directory Server supports exporting data using the web console.
Prerequisites
-
The
dirsrv
user has write permissions in the destination directory. - The Directory Server instance is running.
- You are logged in to the instance in the web console.
Procedure
- Open the Database menu.
- Select the suffix entry.
-
Click Suffix Tasks, and select
Export Suffix
. -
Enter the name of the LDIF file in which you want to store the export. Directory Server will store the file in the
/var/lib/dirsrv/slapd-instance_name/ldif/
directory using the specified file name. - Click Export Database.
- To check the log for problems during the export, open the Monitoring → Logging → Errors Log menu.
2.4. Additional resources
Chapter 3. Enabling members of a group to export data and performing the export as one of the group members
You can configure that members of a group have permissions to export data. This increases the security because you no longer need to set the credentials of cn=Directory Manager
in your scripts. Additionally, you can easily grant and revoke the export permissions by modifying the group.
3.1. Enabling a group to export data
Use this procedure to add the cn=export_users,ou=groups,dc=example,dc=com
group and enable members of this group to create export tasks.
Procedure
Create the
cn=export_users,ou=groups,dc=example,dc=com
group:#
dsidm -D "cn=Directory manager" ldap://server.example.com -b "dc=example,dc=com" group create --cn export_users
Add an access control instruction (ACI) that allows members of the
cn=export_users,ou=groups,dc=example,dc=com
group to create export tasks:#
ldapadd -D "cn=Directory Manager" -W -H ldap://server.example.com
dn: cn=config changetype: modify add: aci aci: (target = "ldap:///cn=export,cn=tasks,cn=config") (targetattr="*") (version 3.0 ; acl "permission: Allow export_users group to export data" ; allow (add, read, search) groupdn = "ldap:///cn=export_users,ou=groups,dc=example,dc=com";) - add: aci aci: (target = "ldap:///cn=config")(targetattr = "objectclass || cn || nsslapd-suffix || nsslapd-ldifdir") (version 3.0 ; acl "permission: Allow export_users group to access ldifdir attribute" ; allow (read,search) groupdn = "ldap:///cn=export_users,ou=groups,dc=example,dc=com";)Create a user:
Create a user account:
#
dsidm -D "cn=Directory manager" ldap://server.example.com -b "dc=example,dc=com" user create --uid="example" --cn="example" --uidNumber="1000" --gidNumber="1000" --homeDirectory="/home/example/" --displayName="Example User"
Set a password on the user account:
#
dsidm -D "cn=Directory manager" ldap://server.example.com -b "dc=example,dc=com" account reset_password "uid=example,ou=People,dc=example,dc=com" "password"
Add the
uid=example,ou=People,dc=example,dc=com
user to thecn=export_users,ou=groups,dc=example,dc=com
group:#
dsidm -D "cn=Directory manager" ldap://server.example.com -b "dc=example,dc=com" group add_member export_users uid=example,ou=People,dc=example,dc=com
Verification
Display the ACIs set on the
cn=config
entry:#
ldapsearch -o ldif-wrap=no -LLLx -D "cn=directory manager" -W -H ldap://server.example.com -b cn=config aci=* aci -s base
dn: cn=config aci: (target = "ldap:///cn=export,cn=tasks,cn=config")(targetattr="*")(version 3.0 ; acl "permission: Allow export_users group to export data" ; allow (add, read, search) groupdn = "ldap:///cn=export_users,ou=groups,dc=example,dc=com";) aci: (target = "ldap:///cn=config")(targetattr = "objectclass || cn || nsslapd-suffix || nsslapd-ldifdir")(version 3.0 ; acl "permission: Allow export_users group to access ldifdir attribute" ; allow (read,search) groupdn = "ldap:///cn=export_users,ou=groups,dc=example,dc=com";) ...
3.2. Performing an export as a regular user
You can perform exports as a regular user instead of cn=Directory Manager
.
Prerequisites
-
You enabled members of the
cn=export_users,ou=groups,dc=example,dc=com
group to export data. -
The user you use to perform the export is a member of the
cn=export_users,ou=groups,dc=example,dc=com
group.
Procedure
Create a export task using one of the following methods:
Using the
dsconf backend export
command:#
dsconf -D "uid=example,ou=People,dc=example,dc=com" ldap://server.example.com backend export userRoot
By manually creating the task:
#
ldapadd -D "uid=example,ou=People,dc=example,dc=com" -W -H ldap://server.example.com
dn: cn=userRoot-2021_07_23_12:55_00,cn=export,cn=tasks,cn=config changetype: add objectClass: extensibleObject nsFilename: /var/lib/dirsrv/slapd-instance_name/ldif/None-userroot-2021_07_23_12:55_00.ldif nsInstance: userRoot cn: export-2021_07_23_12:55_00
Verification
Verify that the backup was created:
#
ls -l /var/lib/dirsrv/slapd-instance_name/ldif/*.ldif
total 0 -rw-------. 1 dirsrv dirsrv 10306 Jul 23 12:55 None-userroot-2021_07_23_12_55_00.ldif ...
Additional resources