Importing and exporting data

Red Hat Directory Server 12

Procedures on how to populate and extract directory databases

Red Hat Customer Content Services

Abstract

Importing data into Directory Server enables you to populate a new Directory Server instance with data - regardless whether it is a stand-alone instance or if you populate an instance that you want to use as a replica. Exporting data enables you to extract the data of a Directory Server database.

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 simple comments on specific passages:

    1. Make sure you are viewing the documentation in the Multi-page HTML format. In addition, ensure you see the Feedback button in the upper right corner of the document.
    2. Use your mouse cursor to highlight the part of text that you want to comment on.
    3. Click the Add Feedback pop-up that appears below the highlighted text.
    4. Follow the displayed instructions.
  • For submitting more complex feedback, create a Bugzilla ticket:

    1. Go to the Bugzilla website.
    2. As the Component, use Documentation.
    3. Fill in the Description field with your suggestion for improvement. Include a link to the relevant part(s) of documentation.
    4. 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.

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.

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.

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

  1. 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 the nsslapd-entryusn-import-initval parameter. For example, to set USN for all imported values to 12345, enter:

    # dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-entryusn-import-initval=12345
  2. 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
  3. 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 the userRoot 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
  4. 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

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.

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

  1. 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 the nsslapd-entryusn-import-initval parameter. For example, to set USN for all imported values to 12345, enter:

    # dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-entryusn-import-initval=12345
  2. 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
  3. 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 the userRoot 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
  4. Search the /var/log/dirsrv/slapd-instance_name/errors log for problems during the import.
  5. 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

1.3. Importing data using the web console while the server is running

Directory Server supports importing data using the web console.

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. 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 the dirsrv_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

  1. In the web console, open the Database menu.
  2. Select the suffix entry.
  3. Click Suffix Tasks, and select Initialize Suffix.
  4. 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.
  5. Select Yes, I am sure, and click Initialize Database to confirm.
  6. To check the log for problems during the import, open the MonitoringLoggingErrors Log menu.

Verification

  1. 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

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.

Note

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

  1. 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 successfully

    By default, dsconf stores the export in a file called instance_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.

  2. Search the /var/log/dirsrv/slapd-instance_name/errors log for problems during the export.

Additional resources

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

  1. Use the dsctl db2ldif command to export data to an LDIF file. For example, to export the userRoot 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
  2. Search the /var/log/dirsrv/slapd-instance_name/errors log for problems during the export.
  3. Optional: Start the instance:

    # dsctl instance_name start

Additional resources

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

  1. Open the Database menu.
  2. Select the suffix entry.
  3. Click Suffix Tasks, and select Export Suffix.
  4. 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.
  5. Click Export Database.
  6. To check the log for problems during the export, open the MonitoringLoggingErrors 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

  1. 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
  2. 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";)
  3. Create a user:

    1. 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"
    2. 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"
  4. Add the uid=example,ou=People,dc=example,dc=com user to 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 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

Legal Notice

Copyright © 2022 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.