Chapter 4

Populating Directory Databases

---

Databases contain the directory data managed by your Red Hat Directory Server (Directory Server). This chapter describes the following procedures for populating your directory databases:

• Importing Data (page 151)
• Exporting Data (page 158)
• Backing Up and Restoring Data (page 161)
• Enabling and Disabling Read-Only Mode (page 168)

Importing Data

Directory Server provides three methods for importing data:

• Import from the Directory Server Console - You can use the Directory Server Console to append data to all of your databases, including database links.
• Initialize databases - You can use the Directory Server Console to import data to one database. This method overwrites any data contained by the database.
• Importing data from the command-line - You can import data using the command-line utilities.

Note	The LDIF files you use for import operations must use UTF-8 characterset encoding. Import operations do not convert data from local characterset encoding to UTF-8 characterset encoding.

Table 4-1 describes the differences between an import and initializing databases.

Table 4-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 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

The following sections describe importing data:

• Importing a Database from the Console
• Initializing a Database from the Console
• Importing from the Command-Line

Caution

All imported LDIF files must also contain the root suffix.

Importing a Database from the Console

When you perform 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 your Directory Server and on remote databases to which your 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:

1. In the Directory Server Console, select the Tasks tab. Scroll to the bottom of the screen, and select Import Database.

You can also import by going to the Configuration tab and selecting "Import" from the Console menu.

The Import Database dialog box is displayed.

2. In the "LDIF file" field, enter the full path to the LDIF file you want to import, or click Browse to select the file you want to import.

If you are running the Console on a machine remote to the directory, the field name appears as "LDIF file (on the machine running the Console)." This reminds you that when you do a browse, you are not browsing your current directory. Instead, you are browsing 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. If you want the server to ignore operations other than add, select the "Add only" checkbox.
   • Continue on Error. Select the "Continue on error" checkbox if you want the server to continue with the import even if errors occur. For example, you might use this option if you are importing 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 you want the server to record all entries it cannot import, or click Browse to select the file which will contain the rejects.

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.

If you leave this field blank, 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

You can overwrite the existing data in a database. The following section describes using the Console to initialize databases.

You must be logged in as the Directory Manager in order to initialize a database. This is because you cannot import an LDIF file that contains a root entry unless you bind to the directory as the Directory Manager (Root DN). Only the Directory Manager has access to the root entry (for example, the root entry might be 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, you will delete information that will require the reinstallation of the Directory Server.

To initialize a database using the Directory Server Console:

1. In the Directory Server Console, select the Configuration tab.
2. Expand the Data tree in the left navigation pane. Expand the suffix of the database you want to initialize, then click the database itself.
3. Right-click the database, and select Initialize Database.

You can also select Initialize Database from the Object menu.

4. In the "LDIF file" field, enter the full path to the LDIF file you want to import, or click Browse to locate it on your machine.
5. If you are operating the Console from a machine local to the file being imported, skip to step 6. If you are operating the Console from a machine remote to the server containing the LDIF file, select one of the following options:
   • 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. By default, the Console looks for the file in the following directory:

serverRoot/slapd-serverID/ldif
 

6. Click OK.

Importing from the Command-Line

You can use three methods for importing data through the command-line:

• Using ldif2db - This import method overwrites the contents of your database and requires the server to be stopped.
• Using ldif2db.pl - This import method overwrites the contents of your database while the server is still running.
• Using ldif2ldap - This method appends your LDIF file through LDAP. You can use this method to append data to all of your databases.

Note	To import a database that has been encrypted, you must use the -E option with the script. See "Exporting and Importing an Encrypted Database," on page 102, for more information.

Importing Using the ldif2db Command-Line Script

The ldif2db script overwrites the data in a database you specify. The script requires you to shut down the server before proceeding with the import.

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.

Caution

This script overwrites the data in your database.

To import LDIF with the server stopped:

1. From the command-line, change to the following directory:

serverRoot/slapd-serverID/

2. Stop the server by typing the following:

./stop-slapd

3. Run the ldif2db command-line script.

For more information about using this script, refer to Red Hat Directory Server Configuration, Command, and File Reference.

Caution

If you a specify a database in the -n option that 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 you do not misspell the database name.

An example of performing an import using the ldif2db UNIX shell script follows:

ldif2db -n Database1 
 -i /opt/redhat-ds/servers/slapd-dirserver/ldif/demo.ldif 
 -i /opt/redhat-ds/servers/slapd-dirserver/ldif/demo2.ldif
 

The following table describes the ldif2db options used in the examples:

Option	Description
-i	Specifies the full path name of the LDIF file(s) to be imported. This option is required. You can use multiple -i arguments to import more than one LDIF file at a time. When you import multiple files, the server imports the LDIF files in the order in which you specify them from the command-line.
-n	Specifies the name of the database into which you are importing the data.

For more information about using this script, refer to the Red Hat Directory Server Configuration, Command, and File Reference.

Importing Using the ldif2db.pl Perl Script

As with the ldif2db script, the ldif2db.pl script overwrites the data in a database you specify. This script requires the server to be running in order to perform the import.

Caution

This script overwrites the data in your database.

1. From the command-line, change to the following directory:

serverRoot/slapd-serverID/
 

2. Run the ldif2db.pl perl script.

For more information about using this Perl script, refer to Red Hat Directory Server Configuration, Command, and File Reference.

The following example imports an LDIF file using the ldif2db.pl script. You do not need root privileges to run the script, but you must authenticate as the Directory Manager.

UNIX shell script:

ldif2db.pl -D "cn=Directory Manager" -w secretpwd

 -i /opt/redhat-ds/servers/slapd-dirserver/ldif/demo.ldif 
 -n Database1
 

The following table describes the ldif2db.pl options used in the examples:

Option	Description
-D	Specifies the DN of the administrative user.
-w	Specifies the password of the administrative user.
-i	Specifies the LDIF file(s) to be imported. This option is required. You can use multiple -i arguments to import more than one LDIF file at a time. When you import multiple files, the server imports the LDIF files in the order in which you specify them from the command-line.
-n	Specifies the name of the database into which you are importing the data.

Importing Using the ldif2ldap Command-Line Script

The ldif2ldap script appends the LDIF file through LDAP. Using this script, you import data to all directory databases at the same time. The server must be running in order to import using ldif2ldap.

To import LDIF using ldif2ldap:

1. From the command-line, change to the following directory:

serverRoot/slapd-serverID/
 

2. Run the ldif2ldap command-line script.

For more information about using this script, refer to Red Hat Directory Server Configuration, Command, and File Reference.

An example of performing an import using the ldif2ldap UNIX shell script follows:

ldif2ldap "cn=Directory Manager" secret 
/opt/redhat-ds/servers/slapd-dirserver/ldif/demo.ldif
 

The ldif2ldap script requires you to specify the DN of the administrative user, the password of the administrative user, and the absolute path and filename of the LDIF file(s) to be imported.

Exporting Data

You can use the LDAP Data Interchange Format (LDIF) to export database entries from your databases. LDIF is a standard format described in RFC 2849, "The LDAP Data Interchange Format (LDIF) - Technical Specification."

Exporting data can be useful for the following:

• Backing up the data in your database.
• Copying your data to another Directory Server.
• Exporting your data to another application.
• Repopulating databases after a change to your directory topology.

Suppose your directory is contained by one database, and you decide to split its contents over two databases, as illustrated in Figure 4-1.

Figure 4-1 Splitting a Database Contents into Two Databases

To populate the new databases requires exporting the contents of database one and importing it into the new databases one and two.

You can use the Directory Server Console or command-line utilities to export data. The following sections describe these methods in detail:

• Exporting Directory Data to LDIF Using the Console
• Exporting a Single Database to LDIF Using the Console
• Exporting to LDIF from the Command-Line

The export operations do not export the configuration information (cn=config).

Caution

Do not stop the server during an export operation.

Exporting Directory Data to LDIF Using the Console

You can export some or all of your directory data to LDIF, depending upon the location of the final exported file. When the LDIF file is on the server, you can export only the data contained by the databases local to the server. If the LDIF file is remote to the server, you can export all of the databases and database links.

To export directory data to LDIF from the Directory Server Console while the server is running:

1. In the Directory Server Console, select the Tasks tab. Scroll to the bottom of the screen, and click Export Database(s).

To export all of your databases, you can also select the Configuration tab and select Export from the Console menu.

The Export Database dialog box is displayed.

2. Enter the full path and filename of the LDIF file in the LDIF File field, or click Browse to locate the file.

Browse is not enabled if you are running the Console on a remote server. When the Browse button is not enabled, the file is stored by default in this directory:

serverRoot/slapd-serverID/ldif
 

3. If you are running the Console on a machine remote to the server, two radio buttons are displayed beneath the LDIF file field.
   • Select "To local machine" to indicate that you are exporting to an LDIF file in the machine from which you run the Console.
   • Select "To server machine" to indicate that you are exporting to an LDIF file located on the server's machine.
4. If you want to export the whole directory, select the "Entire database" radio button.

If you want to export only a single subtree of the suffix contained by the database, select the "Subtree" radio button, and then enter the name of the suffix in the Subtree text box. This option allows you to export a subtree that is contained by more than one database.

You can also click Browse to select a suffix or subtree.

5. Click OK to export the file.

Exporting a Single Database to LDIF Using the Console

To export one database to LDIF from the Directory Server Console while the server is running:

1. In the Directory Server Console, select the Configuration tab.
2. Expand the Data tree in the left navigation pane. Expand the suffix maintained by the database you want to export. Select the database under the suffix that you want to export.
3. Right-click the database, and select Export Database.

You can also select Export Database from the Object menu.

The Export Partition dialog box is displayed.

4. In the "LDIF file" field, enter the full path to the LDIF file, or click Browse to locate it on your machine.

When the Browse button is not enabled, by default the file is stored in this directory:

serverRoot/slapd-serverID/ldif
 

5. Click OK to export the file.

Exporting to LDIF from the Command-Line

You can export your database to LDIF using the db2ldif command-line script. This script exports all of your database contents or a part of their contents to LDIF when the server is running or stopped.

Note	To export a database that has been encrypted, you must use the -E option with the script. See "Exporting and Importing an Encrypted Database," on page 102, for more information.

To export to LDIF from the command-line:

1. From the command-line, change to the following directory:

serverRoot/slapd-serverID/
 

2. Run the db2ldif command-line script.

For more information about using this script, refer to Red Hat Directory Server Configuration, Command, and File Reference.

This example performs an import using the db2ldif UNIX shell script:

db2ldif -n database1 -a output.ldif -s "dc=example,dc=com" -s 
 "o=NetscapeRoot"
 

The following table describes the db2ldif options used in the examples:

Option	Description
-n	Specifies the name of the database from which the file is being exported.
-a	Defines the output file in which the server saves the exported LDIF. This file is stored by default in the directory where the command-line script resides.
-s	Specifies the suffix or suffixes to include in the export. You may use multiple -s arguments.

Backing Up and Restoring Data

You can back up and restore your databases using the Directory Server Console or a command-line script.

The following sections describe the procedures for backing up and restoring data:

• Backing Up All Databases
• Backing Up the dse.ldif Configuration File
• Restoring All Databases
• Restoring a Single Database
• Restoring Databases That Include Replicated Entries
• Restoring the dse.ldif Configuration File

Caution

Do not stop the server during a backup or restore operation.

Backing Up All Databases

The following procedures describe backing up all of the databases in your directory using the Directory Server Console and from the command-line.

Note	You cannot use these backup methods to back up the data contained by databases on a remote server that you chain to using database links.

Backing Up All Databases from the Server Console

When you back up your databases from the Directory Server Console, the server copies all of the database contents and associated index files to a backup location. You can perform a backup while the server is running.

To back up your databases from theDirectory Server Console:

1. In the Directory Server Console, select the Tasks tab.
2. Click Back Up Directory Server.

The Backup Directory dialog box is displayed.

3. Enter the full path of the directory where you want to store the backup file in the Directory text box, or click "Use default," and the server provides a name for the backup directory.

If you are running the Console on the same machine as the directory, you can also click Browse to locate a local directory.

If you choose to use the default, the backup files will be placed in the following location:

serverRoot/slapd-serverID/bak/backup_directory
 

The backup_directory variable names a directory using the name of the backup file. By default, the backup directory name contains the time and date the backup was created (YYYY_MM_DD_hhmmss).

4. Click OK to create the backup.

Backing Up All Databases from the Command-Line

You can back up your databases from the command-line using the db2bak command-line script. This script works when the server is running or when the server is stopped.

You cannot back up the configuration information using this backup method. For information on backing up the configuration information, refer to "Backing Up the dse.ldif Configuration File," on page 164.

To back up your directory from the command-line using the db2bak script:

1. At the command prompt, change to the following directory:

serverRoot/slapd-serverID
 

2. Run the db2bak command-line script.

For more information about using this script, refer to Red Hat Directory Server Configuration, Command, and File Reference.

This example performs an import using the db2bak UNIX shell script:

db2bak /opt/redhat-ds/servers/slapd-dirserver/bak/bak_2001070110
3056
 

You can specify the backup directory and output file where the server saves the exported LDIF file. If you do not specify a directory and output file, the directory will store the file by default in the directory where the command-line script resides. By default, the backup file is named according to the year-month-day-hour format (YYYY_MM_DD_hhmmss).

Backing Up the dse.ldif Configuration File

Directory Server automatically backs up the dse.ldif configuration file. When you start your Directory Server, the directory creates a backup of the dse.ldif file automatically in a file named dse.ldif.startOK in this directory:

serverRoot/slapd-serverID/config
 

When you make modifications to the dse.ldif file, the file is first backed up to a file called dse.ldif.bak in the serverRoot/slapd-serverID/config directory before the directory writes the modifications to the dse.ldif file.

Restoring All Databases

The following procedures describe restoring all of the databases in your directory using the Directory Server Console and from the command-line.

Note	While restoring databases, the server must be running. However, the databases will be unavailable for processing operations during the restore.

Restoring All Databases from the Console

If your databases become corrupted, you can restore data from a previously generated backup using the Directory Server Console. This process consists of stopping the server and then copying the databases and associated index files from the backup location to the database directory.

Caution

Restoring your databases overwrites any existing database files.

To restore your databases from a previously created backup:

1. In the Directory Server Console, select the Tasks tab.
2. Click Restore Directory Server.

The Restore Directory dialog box is displayed.

3. Select the backup from the Available Backups list, or enter the full path to a valid backup in the Directory text box.

The Available Backups list shows all backups located in the default directory:

serverRoot/slapd-serverID/bak/backup_name
 

where backup_name is the name of the backup file.

4. Click OK to restore your databases.

Restoring Your Database from the Command-Line

You can restore your databases from the command-line by using the following scripts:

• Using the bak2db command-line script. This script requires the server to be shut down.
• Using the bak2db.pl Perl script. This script works while the server is running.

Using the bak2db Command-Line Script

To restore your directory from the command-line while the server is shut down:

1. At the command prompt, change to the following directory:

serverRoot/slapd-serverID
 

2. If the server is running, type the following to stop it:

./stop-slapd

3. Run the bak2db command-line script.

For more information about using this script, refer to Red Hat Directory Server Configuration, Command, and File Reference.

This example performs an import using the bak2db UNIX shell script:

bak2db 
/opt/redhat-ds/servers/slapd-dirserver/bak/bak_20010701103056
 

The bak2db script requires that you define the full path and name of the input file.

Using bak2db.pl Perl Script

To restore your directory from the command-line while the server is running:

1. At the command prompt, change to the following directory:

serverRoot/slapd-serverID
 

2. Run the bak2db.pl Perl script.

For more information on using this Perl script, refer to Red Hat Directory Server Configuration, Command, and File Reference.

This example performs an import using the bak2db.pl UNIX shell script:

bak2db.pl -D "cn=Directory Manager" -w secret 
 -a /opt/redhat-ds/servers/slapd-dirserver/bak/mybak_2001070110
3056
 

The following table describes the bak2db.pl options used in the examples:

Option	Description
-a	Defines the full path and name of the input file.
-D	Specifies the DN of the administrative user.
-w	Specifies the password of the administrative user.

Restoring a Single Database

To restore a single database:

1. At the command prompt, change to the following directory:

cd serverRoot/slapd-serverID
 

2. Stop the Directory Server if it is running by typing the following:

./stop-slapd

3. Restore the backend from your /bak archives with the bak2db script, using the -n parameter to specify the backend instance name. For example:

./bak2db /redhat/servers/slapd-serverID/bak/backup_file -n 
userRoot
 

4. Restart the Directory Server by typing the following:

./start-slapd

Restoring Databases That Include Replicated Entries

If you are restoring a database that is supplying entries to other servers, then you must reinitialize all of the servers that receive updates from the restored database (for example, consumer servers, hub servers, and, in multi-master replication environments, other supplier servers). The changelog associated with the restored database will be erased during the restore operation. A message will be logged to the supplier servers' log files indicating that reinitialization is required.If you are restoring a database containing data received from a supplier server, then one of two situations can occur:

• Changelog entries have not yet expired on the supplier server.

If the supplier server changelog has not expired since the database backup was taken, then you can restore the local consumer and continue with normal operations. This situation occurs only if the backup was taken within a period of time that is shorter than the value you have set for the maximum changelog age attribute. This attribute is called nsslapd-changelogmaxage and can be found in the cn=changelog5,cn=config entry. For more information about this option, refer to the Red Hat Directory Server Configuration, Command, and File Reference.

Directory Server automatically detects the compatibility between the replica and its changelog. If a mismatch is detected, the server removes the old changelog file and creates a new, empty one.

• Changelog entries have expired on the supplier server since the time of the local backup.

If changelog entries have expired, you need to initiate consumer reinitialization. For more information on reinitializing consumers, refer to "Initializing Consumers," on page 350.

For information on managing replication, see "Managing Replication," on page 307.

Restoring the dse.ldif Configuration File

To restore the dse.ldif configuration file, stop the server, then use the procedure outlined in "Restoring a Single Database," on page 166, to copy the backup copy of the dse.ldif file into your directory. Once you have copied the data, restart your server.

The directory creates two backup copies of the dse.ldif file in this directory:

serverRoot/slapd-serverID/config
 

The dse.ldif.startOK file records a copy of the dse.ldif file at server start up. The dse.ldif.bak file contains a backup of the most recent changes to the dse.ldif file. Copy the file with the most recent changes to your directory.

Enabling and Disabling Read-Only Mode

Before performing certain operations of export or backup on your Directory Server, you can enable read-only mode on any of the databases to ensure you have a faithful image of the state of these databases at a given time.

The Directory Server Console and the command-line utilities do not automatically put the directory in read-only mode before export or backup operations because this would make your directory unavailable for updates. However, if you have a multi-master configuration, this might not be a problem for you.

Enabling Read-Only Mode

1. In the Directory Server Console, select the Configuration tab, and expand the Data folder in the navigation tree.
2. Select the database that you want to place in read-only mode, and click the Database Settings tab in the right pane.
3. Select the "Database is Read-Only" checkbox.
4. Click Save.

Your change takes effect immediately.

Before performing an import or restore operation, you should ensure that the databases affected by the operation are not in read-only mode. If they are, use the following procedure to make them available for updates.

Disabling Read-Only Mode

1. In the Directory Server Console, select the Configuration tab, and expand the Data tree.
2. Select the database that you want to make available for updates, and click the Database Settings tab in the right pane.
3. Clear the "Database is Read-only" checkbox.
4. Click Save.

Your change takes effect immediately.