Show Table of Contents
Chapter 6. Populating Directory Databases
Databases contain the directory data managed by the Red Hat Directory Server.
6.1. Importing Data
Directory Server can populate a database with data in one of two ways: by importing data (either through the Directory Server Console or using the import tools) or by initializing a database for replication.
Table 6.1, “Import Method Comparison” 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 Console | Local to 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
attribute, 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.
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=jsmith,ou=people,dc=example,dc=com entryusn: 1001 ...
To set an initial value for entry USNs, simply add the
nsslapd-entryusn-import-initval
attribute to the server into which data are being imported or to the master server which will perform the initialization.
# ldapmodify -D "cn=Directory Manager" -W -x -D "cn=directory manager" -W -p 389 -h server.example.com -x dn: cn=config changetype: modify add: nsslapd-entryusn-import-initval nsslapd-entryusn-import-initval: next
Note
In multi-master replication, the
nsslapd-entryusn-import-initval
attribute 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 Supplier1 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 Supplier2 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 Supplier 2 have a multi-master replication agreement between them.
6.1.2. Importing a Database from the Console
When performing an import operation from the Directory Server Console, an
ldapmodify
operation is executed to append data, as well as to modify and delete entries. The operation is performed on all of the databases managed by the Directory Server and on remote databases to which the Directory Server has a configured database link.
Import operations can be run on a server instance that is local to the Directory Server Console or on a different host machine (a remote import operation).
You must be logged in as the Directory Manager in order to perform an import.
Note
The LDIF files used for import operations must use UTF-8 character set encoding. Import operations do not convert data from local character set encoding to UTF-8 characterset encoding.
Warning
All imported LDIF files must also contain the root suffix.
To import data from the Directory Server Console:
- Select the Tasks tab. Scroll to the bottom of the screen, and select Import Database.Alternatively, open the Configuration tab and select Import from the Console menu.
- In the Import Database dialog box, enter the full path to the LDIF file to import in the LDIF file field, or click to select the file to import.If the Console is running on a machine remote to the directory, the field name appears as LDIF file (on the machine running the Console). When browsing for a file, you are not browsing the current directory for the Directory Server host, but the filesystem of the machine running the Console.When importing a database through a remote Console, do not use a relative path to the database. For remote imports, the operation fails with the error Cannot write to file... if a relative path is given for the file. Always use an absolute path for remote import operations.
- In the Options box, select one or both of the following options:
- Add Only. The LDIF file may contain modify and delete instructions in addition to the default add instructions. For the server to ignore operations other than add, select the Add only check box.
- Continue on Error. Select the Continue on error check box for the server to continue with the import even if errors occur. For example, use this option to import an LDIF file that contains some entries that already exist in the database in addition to new ones. The server notes existing entries in the rejects file while adding all new entries.
- In the File for Rejects field, enter the full path to the file in which the server is to record all entries it cannot import, or click to select the file which will contain the rejects.A reject is an entry which cannot be imported into the database; for example, the server cannot import an entry that already exists in the database or an entry that has no parent object. The Console will write the error message sent by the server to the rejects file.Leaving this field blank means the server will not record rejected entries.
The server performs the import and also creates indexes.
Note
Trailing spaces are dropped during a remote Console import but are preserved during both local Console or
ldif2db
import operations.
6.1.3. Initializing a Database from the Console
The existing data in a database can be overwritten by initializing databases.
You must be logged in as the
Directory Manager
in order to initialize a database because an LDIF file that contains a root entry cannot be imported into a database except as the Directory Manager (root DN). Only the Directory Manager has access to the root entry, such as dc=example,dc=com
.
Warning
When initializing databases from an LDIF file, be careful not to overwrite the
o=NetscapeRoot
suffix unless you are restoring data. Otherwise, initializing the database deletes information and may require re-installing the Directory Server.
To initialize a database using the Directory Server Console:
- Select the Configuration tab.
- Expand the Data tree in the left navigation pane. Expand the suffix of the database to initialize, then click the database itself.
- Right-click the database, and select Initialize Database.Alternatively, select Initialize Database from the Object menu.
- In the LDIF file field, enter the full path to the LDIF file to import, or click .
- If the Console is running from a machine local to the file being imported, clickand proceed with the import immediately. If the Console is running from a machine remote to the server containing the LDIF file, select one of the following options, then click :
- From local machine. Indicates that the LDIF file is located on the local machine.
- From server machine. Indicates that the LDIF file is located on a remote server.
The default LDIF directory is/var/lib/dirsrv/slapd-instance/ldif
.
6.1.4. Importing from the Command Line
There are four methods for importing data through the command line:
- Using ldif2db. This import method overwrites the contents of the database and requires the server to be stopped; see Section 6.1.4.1, “Importing Using the ldif2db Command-Line Script”.
- Using ldif2db.pl. This import method overwrites the contents of the database while the server is still running; see Section 6.1.4.2, “Importing Using the ldif2db.pl Perl Script”.
- Using ldif2ldap. This method appends the LDIF file through LDAP. This method is useful to append data to all of the databases; see Section 6.1.4.3, “Importing Using the ldif2ldap Command-Line Script”.
- Creating a cn=tasks entry. This method creates a temporary task entry which automatically launches an import operation. This is functionally like running
ldif2db
. See Section 6.1.4.4, “Importing through the cn=tasks Entry”.
Note
The LDIF files used for import operations must use UTF-8 character set encoding. Import operations do not convert data from local character set encoding to UTF-8 characterset encoding.
Warning
All imported LDIF files must also contain the root suffix.
Note
To import a database that has been encrypted, use the
-E
option with the script. See Section 10.7, “Exporting and Importing an Encrypted Database” for more information.
6.1.4.1. Importing Using the ldif2db Command-Line Script
The
ldif2db
script overwrites the data in the specified database. Also, the script requires that the Directory Server be stopped when the import begins.
By default, the script first saves and then merges any existing
o=NetscapeRoot
configuration information with the o=NetscapeRoot
configuration information in the files being imported.
Warning
This script overwrites the data in the database.
To import an LDIF:
- Stop the server:
# systemctl stop dirsrv@instance
- Run the
ldif2db
command-line script:# ldif2db -Z instance_name -n Database1 -i /var/lib/dirsrv/slapd-instance/ldif/demo.ldif -i /var/lib/dirsrv/slapd-instance/ldif/demo2.ldif
For information about the parameters used in the example, see the description of theldif2db
script in the Red Hat Directory Server Configuration, Command, and File Reference.Warning
If the database specified in the-n
option does not correspond with the suffix contained by the LDIF file, all of the data contained by the database is deleted, and the import fails. Make sure that the database name is not misspelled. - Start the server:
# systemctl start dirsrv@instance
6.1.4.2. Importing Using the ldif2db.pl Perl Script
As with the
ldif2db
script, the ldif2db.pl
script overwrites the data in the specified database. This script requires the server to be running in order to perform the import.
Warning
This script overwrites the data in the database.
Run the
ldif2db.pl
script:
# ldif2db.pl -Z instance_name -D "cn=Directory Manager" -w secret -i /var/lib/dirsrv/slapd-instance/ldif/demo.ldif -n Database1
For information about the parameters used in the example, see the description of the
ldif2db.pl
script in the Red Hat Directory Server Configuration, Command, and File Reference.
Note
You do not need
root
privileges to run the script, but you must authenticate as the Directory Manager.
6.1.4.3. Importing Using the ldif2ldap Command-Line Script
The
ldif2ldap
script appends the LDIF file through LDAP. Using this script, data are imported to all directory databases at the same time. The server must be running in order to import using ldif2ldap
.
To import LDIF using
ldif2ldap
:
[root@server ~]# ldif2ldap -Z instance_name -D "cn=Directory Manager" -w secretpwd /var/lib/dirsrv/slapd-instance/ldif/demo.ldif
The
ldif2ldap
script requires the DN of the administrative user, the password of the administrative user, and the absolute path and filename of the LDIF files to be imported.
For information about the parameters used in the example, see the description of the
ldif2ldap
script in the Red Hat Directory Server Configuration, Command, and File Reference.
6.1.4.4. Importing through the cn=tasks Entry
The
cn=tasks,cn=config
entry in the Directory Server configuration is a container entry for temporary entries that the server uses to manage tasks. Several common directory tasks have container entries under cn=tasks,cn=config
. Temporary task entries can be created under cn=import,cn=tasks,cn=config
to initiate an import operation.
As with the
ldif2db
and ldif2db.pl
scripts, an import operation in cn=tasks
overwrites all of the information in the database.
This task entry requires three attributes:
- A unique name (
cn
) - The filename of the LDIF file to import (
nsFilename
) - The name of the database into which to import the file (
nsInstance
)
It is also possible to supply the DNs of suffixes to include or exclude from the import, analogous to the
-s
and -x
options, respectively, for the ldif2db
and ldif2db.pl
scripts.
The entry is simply added using
ldapmodify
, as described in Section 3.1.3.2, “Adding an Entry Using ldapmodify
”. For example:
# ldapmodify -a
-D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=example import,cn=import,cn=tasks,cn=config
changetype: add
objectclass: extensibleObject
cn: example import
nsFilename: /home/files/example.ldif
nsInstance: userRoot
nsIncludeSuffix: ou=People,dc=example,dc=com
nsExcludeSuffix: ou=Groups,dc=example,dc=com
As soon as the task is completed, the entry is removed from the directory configuration.
For details about the attributes used in the example and other attributes you can set in this entry, see the
cn=import,cn=tasks,cn=config
entry description in the Red Hat Directory Server Configuration, Command, and File Reference