Chapter 6. Populating Directory Databases
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 uses PrivateTmp 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 about PrivateTmp , see systemd.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. , 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 , then every imported entry is assigned a USN of 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: 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 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 the dsconf backend import Command" . Create a cn=tasks entry. See Section 6.1.2.1.2, "Importing Data Using a cn=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 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: The dsconf backend import command supports additional options, for example, to exclude a specific suffix. To display all available options, enter: 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: 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: Import the data from the LDIF file. For example, to import the /var/lib/dirsrv/slapd- instance_name /ldif/example.ldif file into the userRoot database: 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: 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.
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 dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-entryusn-import-initval= next 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 dsconf ldap://server.example.com backend import --help 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 dsctl instance_name stop 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 dsctl instance_name start