Chapter 4   Populating Directory Databases


Databases contain the directory data managed by your directory server. This chapter describes the following procedures for populating your directory databases:

• Importing Data

• Exporting Data

• Backing Up and Restoring Data

• Enabling and Disabling Read-Only Mode

Importing Data

---

iPlanet 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	All LDIF files you import must use UTF-8 character set encoding.

  ---

  
  

The following table describes the differences between an import and initializing databases:

Table 4-1    Import Method Comparison

	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:

• "Performing an Import 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.

  ---

  
  

Performing an Import 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. On 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 file system of the machine running the console.

3. In the Options box, select one or more 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" check box.

   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.

Initializing a Database From the Console

You can overwrite the existing data in a database. The following section describe 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=siroe,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 all of your iPlanet servers.

---

To initialize a database using the Directory Server Console:

1. On 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: /usr/iplanet/servers/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.

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: /usr/iplanet/servers/slapd-serverID/

   where serverID is the name of your directory server.

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

   ---

   
   

Two examples of performing an import using ldif2db follow:

Windows NT batch file:

ldif2db.bat -n Database1  -i c:\iplanet\servers\slapd-dirserver\ldif\demo.ldif  -i c:\iplanet\servers\slapd-dirserver\ldif\demo2.ldif

UNIX shell script:

ldif2db -n Database1  -i /usr/iplanet/servers/slapd-dirserver/ldif/demo.ldif  -i /usr/iplanet/servers/slapd-dirserver/ldif/demo2.ldif

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

Option Name	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 iPlanet 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: /usr/iplanet/servers/slapd-serverID/

   where serverID is the name of your directory server.

2. Run the ldif2db.pl perl script.

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

Two examples of performing an import using ldif2db.pl follow:

Windows NT batch file:

..\bin\slapd\admin\bin\perl ldif2db.pl -D "cn=Directory Manager"
-w secretpwd -i c:\iPlanet\servers\slapd-dirserver\ldif\demo.ldif -n Database1

---

Caution

You need to run the script from the following directory on NT machines: ..\bin\slapd\admin\bin\perl. This path appears in the example.

---

UNIX shell script:

ldif2db.pl -D "cn=Directory Manager" -w secretpwd
 -i /usr/iplanet/servers/slapd-dirserver/ldif/demo.ldif  -n Database1

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

Option Name	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: /usr/iplanet/servers/slapd-serverID/

   where serverID is the name of your directory server.

2. Run the ldif2ldap command-line script.

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

Two examples of performing an import using ldif2ldap follow:

Windows NT batch file:

ldif2ldap "cn=Directory Manager" secret c:\iplanet\servers\slapd-dirserver\ldif\demo.ldif

UNIX shell script:

ldif2ldap "cn=Directory Manager" secret /usr/iplanet/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 file name 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

For example, suppose your directory is contained by one database and you decide to split its contents over two databases as follows:

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 iPlanet 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"

  
  

  ---

  Note	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. On 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 file name 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 the /usr/iplanet/servers/slapd-ServerID/ldif directory.

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. On 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 the /usr/iplanet/servers/slapd-ServerID/ldif directory.

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.

To export to LDIF from the command line:

1. From the command line, change to the following directory:
   /usr/iplanet/servers/slapd-serverID/

   where serverID is the name of your directory server.

2. Run the db2ldif command line script.

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

Windows NT batch file:

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

UNIX shell script:

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

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

Option Name	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 a Single Database"

• "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 the Server Console:

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

   /usr/iplanet/servers/slapd-serverID/bak/backup_directory

   where serverID is the name of your directory server. 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".

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

1. At the command prompt, change to the following directory: /usr/iplanet/servers/slapd-serverID

   where serverID is the name of your directory server.

2. Run the db2bak command-line script.

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

Two examples of performing an import using db2bak follow:

Windows NT batch file:

db2bak \usr\iplanet\servers\slapd-dirserver\bak\bak_20010701103056

UNIX shell script:

db2bak /usr/iplanet/servers/slapd-dirserver/bak/bak_20010701103056

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 a Single Database

To back up a single database:

1. At the command prompt, change to: /usr/iplanet/servers/slapd-serverID

   where serverID is the name of your directory server.

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

3. Change to the directory containing the database you want to back up:
   cd db/database_name

4. Copy all of the files in the directory to a backup directory you create. Do not use the /usr/iplanet/servers/slapd-serverID/bak/ directory, as the Directory Server Console assumes the backups contained by this directory are global.

   
   

   ---

   Note	You cannot use this backup method to back up the data contained by databases on remote servers (the databases chained to by the database links).

   ---

   
   

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 the /usr/iplanet/servers/slapd-serverID/config directory.

When you make modifications to the dse.ldif file, the file is first backed up to a file called dse.ldif.bak in the /usr/iplanet/servers/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. On 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, /usr/iplanet/servers/slapd-serverID/bak/backup_name

   where serverID is the name of your directory server and 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:
   /usr/iplanet/servers/slapd-serverID

   where serverID is the name of your directory server.

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 iPlanet Directory Server Configuration, Command, and File Reference.

Two examples of performing an import using bak2db follow:

Windows NT batch file:

bak2db.bat  \usr\iPlanet\servers\slapd-dirserver\bak\bak_20010701103056

UNIX shell script:

bak2db /usr/iplanet/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:
   /usr/iplanet/servers/slapd-serverID

   where serverID is the name of your directory server.

2. Run the bak2db.pl perl script.

   For more information on using this perl script, refer to iPlanet Directory Server Configuration, Command, and File Reference.

Two examples of performing an import using bak2db.pl follow:

Windows NT batch file:

..\bin\slapd\admin\bin\perl bak2db.pl -D "cn=Directory Manager"
 -w secret  -a \usr\iplanet\servers\slapd-dirserver\bak\mybak_20010701103056

---

Caution

You need to run perl scripts from the following directory on Windows NT: ..\bin\slapd\admin\bin\perl. This path appears in the example.

---

UNIX shell script:

bak2db.pl -D "cn=Directory Manager" -w secret  -a /usr/iplanet/servers/slapd-dirserver/bak/mybak_20010701103056

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

Option Name	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 /usr/iplanet/servers/slapd-serverID

   where serverID is the name of your directory server.

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

   ./stop-slapd

3. Change to the directory containing the backup you want to restore.

4. Copy all of the files to the directory containing the database you want to overwrite with your backup. For example, you might type the following:

   cp backup_file ../db/database_name

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 change log 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:

• Change log entries have not yet expired on the supplier server.

  If the supplier server change log 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 change log 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 iPlanet Directory Server Configuration, Command, and File Reference.

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

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

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

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

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" 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 the /usr/iplanet/servers/slapd-serverID/config directory. 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. On 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. On 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.