Import user information from an LDIF file

Importing Data

Directory Server provides three methods for importing data:

• Import from the Directory Server Console. Use the Directory Server Console to append data to all of the databases, including database links.
• Initialize databases. The Directory Server Console can import data to one database; this method overwrites any data contained by the database.
• Importing data from the command-line. Directory Server provides command-line utilities to import data.

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.

Table 4.1, “Import Method Comparison” describes the differences between an import and initializing databases.

Action	Import	Initialize Database
Overwrites database	No	Yes
LDAP operations	Add, modify, delete	Add only
Performance	More time-consuming	Fast
Partition speciality	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

Table 4.1. Import Method Comparison

The following sections describe importing data:

• Section 4.1.1, “Importing a Database from the Console”
• Section 4.1.2, “Initializing a Database from the Console”
• Section 4.1.3, “Importing from the Command-Line”

CAUTION

All imported LDIF files must also contain the root suffix.

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.
You must be logged in as the Directory Manager in order to perform an import.
To import data from the Directory Server Console, do the following:

1. In the Directory Server Console, select the Tasks tab. Scroll to the bottom of the screen, and selectImport Database.
   Alternatively, import by going to the Configuration tab and selecting Import from the Console menu.
2. In the Import Database dialog box, enter the full path to the LDIF file to import in the LDIF file field, or click Browseto select the file to import.
   If the Console is running on a machine remote to the directory, the field name appears asLDIF 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.
3. 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 checkbox.
   • Continue on Error. Select the Continue on error checkbox 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.
4. 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 Browse 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.
5. Click OK.

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.

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.

CAUTION

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, do the following:

1. Select the Configuration tab.
2. Expand the Data tree in the left navigation pane. Expand the suffix of the database to initialize, then click the database itself.
3. Right-click the database, and select Initialize Database.
   Alterntatively, select Initialize Database from the Object menu.
4. In the LDIF file field, enter the full path to the LDIF file to import, or click Browse.
5. If the Console is running from a machine local to the file being imported, click OK and 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 OK:
   • 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_name/ldif. ^[3]

Importing from the Command-Line

There are three 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; seeSection 4.1.3.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; seeSection 4.1.3.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 4.1.3.3, “Importing Using the ldif2ldap Command-Line Script”.

NOTE

To import a database that has been encrypted, use the -E option with the script. See Section 3.2.3.5, “Exporting and Importing an Encrypted Database” for more information.

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 theo=NetscapeRoot configuration information in the files being imported.

CAUTION

This script overwrites the data in the database.

To import LDIF, do the following:

1. Stop the server. ^[4]

   service dirsrv stop instance
   

2. Open the Directory Server instance directory.

   cd /usr/lib/dirsrv/slapd-instance_name
   

3. Run the ldif2db command-line script.

   ldif2db -n Database1 -i /var/lib/dirsrv/slapd-instance_name/ldif/demo.ldif
    -i /var/lib/dirsrv/slapd-instance_name/ldif/demo2.ldif
   

   For more information about using this script, see the Directory Server Configuration, Command, and File Reference.
   

   CAUTION

   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.

Option	Description
-i	Specifies the full path name of the LDIF files to be imported. This option is required. To import more than one LDIF file at a time, use multiple -i arguments. When multiple files are imported, the server imports the LDIF files in the order which they are specified from the command-line.
-n	Specifies the name of the database to which to import the data.

Table 4.2. ldif2db Parameters

For more information about using this script, see the Directory Server Configuration, Command, and File Reference.

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

CAUTION

This script overwrites the data in the database.

1. Open the Directory Server instance directory.

   cd /usr/lib/dirsrv/slapd-instance_name
   

2. Run the ldif2db script.

   ldif2db -D "cn=Directory Manager" -w secretpwd 
       -i /var/lib/dirsrv/slapd-instance_name/ldif/demo.ldif -n Database1
   

   For more information about using this script, see the 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.

Option	Description
-D	Specifies the DN of the administrative user.
-w	Specifies the password of the administrative user.
-i	Specifies the LDIF files to be imported. This option is required. To important multiple LDIF files at a time, use multiple -i arguments. When multiple files are imported, the server imports the LDIF files in the order they are specified in the command-line.
-n	Specifies the name of the database to which to import the data.

Table 4.3. ldif2db Options

4.1.3.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, do the following:

1. Open the Directory Server instance directory:

   cd /usr/lib/dirsrv/slapd-instance_name
   

2. Run the ldif2ldap command-line script.

   ldif2ldap "cn=Directory Manager" secretpwd /var/lib/dirsrv/slapd-instance_name/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 more information about using this script, see the Directory Server Configuration, Command, and File Reference.

configure a slave replica

Creating the Supplier Bind DN Entry

A critical part of setting up replication is to create the entry, called the replication manager or supplier bind DN entry, that the suppliers use to bind to the consumer servers to perform replication updates.
The supplier bind DN must meet the following criteria:

• It must be unique.
• It must be created on the consumer server (or hub) and not on the supplier server.
• It must correspond to an actual entry on the consumer server.
• It must be created on every server that receives updates from another server.
• It must not be part of the replicated database for security reasons.
• It must be defined in the replication agreement on the supplier server.

For example, the entry cn=Replication Manager,cn=config can be created under the cn=config tree on the consumer server. This would be the supplier bind DN that all supplier servers would use to bind to the consumer to perform replication operations.

NOTE

Avoid creating simple entries under the cn=config entry in the dse.ldif file. The cn=cn=config entry in the simple, flat dse.ldif configuration file is not stored in the same highly scalable database as regular entries. As a result, if many entries, and particularly entries that are likely to be updated frequently, are stored under cn=config, performance will suffer. However, although Red Hat recommends not storing simple user entries under cn=config for performance reasons, it can be useful to store special user entries such as the Directory Manager entry or replication manager (supplier bind DN) entry undercn=config since this centralizes configuration information.

On each server that acts as a consumer in replication agreements, create a special entry that the supplier will use to bind to the consumers. Make sure to create the entry with the attributes required by the authentication method specified in the replication agreement.

1. Stop the Directory Server. If the server is not stopped, the changes to the dse.ldif file will not be saved. SeeSection 1.3, “Starting and Stopping Servers” for more information on stopping the server.
2. Create a new entry, such as cn=replication manager,cn=config, in the dse.ldif file.
3. Specify a userPassword attribute-value pair.
4. If password expiration policy is enabled or ever will be enabled, disable it on the replication manager entry to prevent replication from failing due to passwords expiring. To disable the password expiration policy on theuserPassword attribute, add the passwordExpirationTime attribute with a value of 20380119031407Z, which means that the password will never expire.
5. Restart the Directory Server. See Section 1.3, “Starting and Stopping Servers” for more information on starting the server.

The final entry should resemble this example:

dn: cn=replication manager,cn=config 
objectClass: inetorgperson 
objectClass: person 
objectClass: top 
cn: replication manager 
sn: RM 
userPassword: password 
passwordExpirationTime: 20380119031407Z

When configuring a replica as a consumer, use the DN of this entry to define the supplier bind DN.

Configuring Single-Master Replication

To set up single-master replication such as the configuration shown in Figure 8.1, “Single-Master Replication”, between supplier server A, which holds a read-write replica, and the two consumers server B and server C, which each hold a read-only replica, there are two major steps:

• Section 8.4.1, “Configuring the Read-Write Replica on the Supplier Server”
• Section 8.4.2, “Configuring the Read-Only Replica on the Consumer”
• Section 8.4.3, “Create the Replication Agreement”

Configuring the Read-Write Replica on the Supplier Server

1. Specify the supplier settings for the server.
   1. In the Directory Server Console, select the Configuration tab.
   2. In the navigation tree, select the Replication folder.
   3. In the right-hand side of the window, select the Supplier Settings tab.
      

      
      
   4. Check the Enable Changelog checkbox.
      This activates all of the fields in the pane below that were previously grayed out.
   5. Specify a changelog by clicking the Use default button, or click the Browse button to display a file selector.
   6. Set the changelog parameters for the number and age of the log files.
      Clear the unlimited checkboxes to specify different values.
   7. Click Save.
2. Specify the replication settings required for a read-write replica.
   1. In the navigation tree on the Configuration tab, expand the Replication node, and highlight the database to replicate.
      The Replica Settings tab opens in the right-hand side of the window.
   2. Check the Enable Replica checkbox.
   3. In the Replica Role section, select the Single Master radio button.
   4. In the Common Settings section, specify a Replica ID, which is an integer between 1 and 65534, inclusive.
      The replica ID must be unique for a given suffix, different from any other ID used for read-write replicas on this server and on other servers.
   5. In the Common Settings section, specify a purge delay in the Purge delay field.
      The purge delay is how often the state information stored in the replicated entries is deleted.
   6. Click Save.

Configuring the Read-Only Replica on the Consumer

1. Create the database for the read-only replica if it does not exist. See Section 3.1.1, “Creating Suffixes” for instructions on creating suffixes.
2.  Create the entry for the supplier bind DN on the consumer server if it does not exist. The supplier bind DN is the special entry that the supplier will use to bind to the consumer. This is described in Section 8.3, “Creating the Supplier Bind DN Entry”.
3. Specify the replication settings required for a read-only replica.
   1. In the Directory Server Console, select the Configuration tab.
   2. In the navigation tree, expand the Replication folder, and highlight the replica database.
      The Replica Settings tab for that database opens in the right-hand side of the window.
      
      
   3. Check the Enable Replica checkbox.
   4. In the Replica Role section, select the Dedicated Consumer radio button.
   5. In the Common Settings section, specify a purge delay in the Purge delay field.
      This option indicates how often the state information stored in the replicated entries is purged.
   6. In the Update Settings section, specify the bind DN that the supplier will use to bind to the replica. Enter the supplier bind DN in the Enter a new Supplier DN field, and click Add. The supplier bind DN appears in the Current Supplier DNs list.
      The supplier bind DN should be the entry created in step 2. The supplier bind DN is a privileged user because it is not subject to access control.
      

      NOTE

      There can be multiple supplier bind DNs per consumer but only one supplier DN per replication agreement.
   7. Specify the URL for any supplier servers to which to refer updates.
      By default, all updates are first referred to the supplier servers that are specified here. If no suppliers are set here, updates are referred to the supplier servers that have a replication agreement that includes the current replica.
      Automatic referrals assume that clients bind over a regular connection; this has a URL in the formldap://hostname:port. For clients to bind to the supplier using SSL, use this field to specify a referral of the form ldaps://hostname:port, where the s in ldaps indicates a secure connection.
4. Click Save.

Repeat these steps for every consumer server in the replication configuration.

8.4.3. Create the Replication Agreement

Create one replication agreement for each read-only replica. For example, in the scenario illustrated in Figure 8.1, “Single-Master Replication”, server A has two replication agreements, one for server B and one for server C.

1. In the navigation tree of the Configuration tab, right-click the database to replicate, and selectNew Replication Agreement.
   Alternatively, highlight the database, and select New Replication Agreement from the Object menu to start theReplication Agreement Wizard.
2. In the first screen, fill in a name and description for the replication agreement, and hit Next.
3. In the Source and Destination screen, fill in the URL for the consumer and the supplier bind DN and password on that consumer. If the target server is not available, hit in other to fill in the information manually.
   
   • Unless there is more than one instance of Directory Server configured, by default, there are no consumers available in the drop-down menu.
   • The port listed is the non-SSL port, even if the Directory Server instance is configured to run over SSL. This port number is used only for identification of the Directory Server instance in the Console; it does not specify the actual port number or protocol that is used for replication.
   • If SSL is enabled on the servers, it is possible to select the Using encrypted SSL connection radio button for SSL client authentication. Otherwise, fill in the supplier bind DN and password.

     NOTE

     If attribute encryption is enabled, a secure connection must be used for the encrypted attributes to be replicated.
   Hit Next.
4. Fractional replication controls which entry attributes are replicated between servers. By default, all attributes are replicated. To select attributes that will not be replicated to the consumer, check the Enable Fractional Replicationcheckbox. Then, highlight the attribute (or attributes) in the Included column on the right, and click Remove. All attributes that will not be replicated are listed in the Excluded column on the left, as well as in the summary the replication agreement is complete.
   

   NOTE

   To safeguard against potential integrity problems, the consumer in fractional replication must be a dedicated consumer, not a multi-master supplier or hub. This is not enforced at the time the replication agreement is made, but replication will fail if the consumer is not a read-only replica.
5. Set the schedule for when replication runs. By default, replication runs continually.
   
   Hit Next.
6. Set when the consumer is initialized. Initializing a consumer manually copies all data over from the supplier to the consumer. The default is to create an initialization file (an LDIF of all supplier data) so that the consumer can be initialized later. It is also possible to initialize the consumer as soon as the replication agreement is completed or not at all. For information on initializing consumers, see Section 8.10, “Initializing Consumers”.
   

   NOTE

   Replication will not begin until the consumer is initialized.
   Hit Next.
7. The final screen shows the settings for the replication agreement, as it will be included in the dse.ldif file. HitDone to save the agreement.