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:

• Enabling and Disabling Read-Only Mode

• Importing Data

• Exporting Data

• Backing Up and Restoring Data

Enabling and Disabling Read-Only Mode

---

Before performing certain operations of export or backup on your iPlanet 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 iPlanet 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 iPlanet 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 iPlanet 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.

Importing Data

---

iPlanet Directory Server provides three methods for importing data:

• Import from the iPlanet Directory Server Console.

  You can use the iPlanet 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    Comparison of Importing Data Versus Initializing the Database

Domain of Comparison	Importing Data	Initializing 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 iPlanet 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 iPlanet Directory Server, and on remote databases to which your iPlanet 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 iPlanet Directory Server Console:

1. On the iPlanet 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 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=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 iPlanet Directory Server Console:

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

   /var/ds5/slapd-serverID/ldif

6. Click OK.

Importing From the Command Line

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

• Using /usr/sbin/directoryserver ldif2db

  This import method overwrites the contents of your database and requires the server to be stopped.

• Using /usr/sbin/directoryserver ldif2db-task

  This import method overwrites the contents of your database while the server is still running.

• Using /usr/sbin/directoryserver 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

The /usr/sbin/directoryserver ldif2db command overwrites the data in a database you specify. The command requires you to shut down the server before proceeding with the import.

By default, the command first saves and then merges any existing o=NetscapeRoot configuration information with the o=NetscapeRoot configuration information in the files being imported.

---

Caution

This command overwrites the data in your database.

---

To import LDIF with the server stopped:

1. As root from the command line, stop the server with the following command:

   # /usr/sbin/directoryserver stop

2. Use the ldif2db sub-command:

   # /usr/sbin/directoryserver ldif2db

The following example uses the command to import two LDIF files into a single database.

---

Caution

If you a specify a database in the -n option that does not correspond to the suffix contained in the LDIF file, all of the data contained in the database is deleted and the import fails. Make sure that you do not misspell the database name.

---

#!/bin/sh
/usr/sbin/directoryserver ldif2db -n Database1 \
 -i /usr/iplanet/servers/slapd-siroe/ldif/demo.ldif \
 -i /usr/iplanet/servers/slapd-siroe/ldif/demo2.ldif

Table 4-2    Description of ldif2db Options Used in the Example

Option	Description
-n	Specifies the name of the database into which you are importing the data.
-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.

Importing Using ldif2db-task Command

As above, /usr/sbin/directoryserver ldif2db-task overwrites the data in a database you specify. This command requires the server to be running in order to perform the import.

---

Caution

This command overwrites the data in your database.

---

The following example imports an LDIF file. You do not need root privileges to run the script, but you must authenticate as the directory manager.

#!/bin/sh
/usr/sbin/directoryserver ldif2db-task \
  -D "cn=Directory Manager" -w password -n Database1 \
  -i /usr/iplanet/servers/slapd-siroe/ldif/demo.ldif

Table 4-3    Description of ldif2db-task Options Used in the Example

Option	Description
-D	Specifies the DN of the directory manager.
-w	Specifies the password of the directory manager.
-n	Specifies the name of the database into which you are importing the data.
-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.

Importing Using the ldif2ldap Command

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

The following example performs an import. You do not need root privileges to run the command, but you must give credentials for the directory manager on the command line. The last parameter is the name of one or more LDIF files to import.

#!/bin/sh
/usr/sbin/directoryserver ldif2ldap "cn=Directory Manager" password \
  /usr/iplanet/servers/slapd-siroe/ldif/demo.ldif

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"

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 iPlanet Directory Server Console while the server is running:

1. On the iPlanet 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 following directory:

   /var/ds5/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 iPlanet 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 following directory:

   /var/ds5/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 /usr/sbin/directoryserver db2ldif command. This command exports all of your database contents or a part of their contents to an LDIF file, when the server is either running or stopped.

To export the contents of a database to an LDIF file, use the following command:

# /usr/sbin/directoryserver db2ldif

The following example exports the databases under two suffixes to a single LDIF file:

/usr/sbin/directoryserver db2ldif -n database1 -a output.ldif \
        -s "dc=siroe,dc=com" -s "o=NetscapeRoot"

The following table describes the options used in this example:

Table 4-4    Description of db2ldif Options Used in the Example

Option	Description
-n	Specifies the name of the database into which you are importing the data.
-a	Defines the name of the output file in which the server saves the exported LDIF. This file is stored by default in the /var/ds5/slapd-serverID directory.
-s	Specifies the suffix to include in the export. You may use multiple -s arguments to specify multiple suffixes.

Backing Up and Restoring Data

---

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

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 iPlanet 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 iPlanet 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 iPlanet Directory Server Console select the Tasks tab.

2. Click "Back Up Directory Server."

   The Backup Directory dialog box is displayed.

3. In the Directory text box, enter the full path of the directory where you want to store the backup. If you are running the console on the same machine as the directory, click Browse to find a local directory.

   Or click "Use default" to store the backup in the following directory:

   /var/ds5/slapd-serverID/bak/YYYY_MM_DD_hh_mm_ss

   where serverID is the name of your directory server.

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/usr/sbin/directoryserver db2bak command. This command works whether or not the server is running.

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

# /usr/sbin/directoryserver db2bak backupDir

The backupDir parameter specifies the directory where the backup should be stored. The default backup directory name is generated from the current date: YYYY_MM_DD_hh_mm_ss.

The following example backs up all databases to the specified directory:

# /usr/sbin/directoryserver db2bak /var/ds5/slapd-sv/bak/checkpoint

Backing Up a Single Database

You can use the method described in this section if the following conditions are satisfied:

• The directory server is stopped.

• The backup you make will be used to restore the database on the same server.

  
  

  ---

  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); nor can you use the backup data to initialize a consumer or hub replica.

  ---

  
  

To back up a single database:

1. As root from the command line, stop the server with the following command:

   # /usr/sbin/directoryserver stop

2. Change to the directory containing the database you want to back up:

   # cd /var/ds5/slapd-serverID/db

3. Copy all of the files in the directory to a backup directory you create. Do not create directories under slapd-serverID/bak/ because the iPlanet Directory Server Console assumes the backups contained by this directory are global.

Backing Up the dse.ldif Configuration File

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

/var/ds5/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 config directory before the server writes the modifications to the dse.ldif file. Make copies of either of these files if you need to save your configuration.

Restoring All Databases

The following procedures describe restoring all of the databases in your directory using the iPlanet 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 iPlanet 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 iPlanet 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 of the backups located in the default directory:

   /var/ds5/slapd-serverID/bak

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 commands:

• Using the /usr/sbin/directoryserver bak2db command. This command requires the server to be shut down.

• Using the /usr/sbin/directoryserver bak2db-task command. This command works while the server is running.

Using the bak2db Command
To restore your directory from the command line while the server is shut down:

1. As root from the command line, stop the server with the following command:

   # /usr/sbin/directoryserver stop

2. Use the bak2db command with the full path of the backup directory:

   # /usr/sbin/directoryserver bak2db backupDir

   
   

   ---

   Caution

   Restoring your databases overwrites any existing database files.

   ---

   
   

The following example restores a backup from the default backup directory:

# /usr/sbin/directoryserver bak2db /var/ds5/slapd-sv/bak/2001_07_01_11_34_00

Using the bak2db-task Command
To restore your directory from the command line while the server is running, use the following command:

/usr/sbin/directoryserver bak2db-task

---

Caution

Restoring your databases overwrites any existing database files.

---

The following example imports an LDIF file.

#!/bin/sh
/usr/sbin/directoryserver bak2db-task -D "cn=Directory Manager" \
   -w password -a /usr/iplanet/servers/slapd-siroe/bak/checkpoint

Table 4-5    Description of bak2db-task Options Used in the Example

Option	Description
-D	Specifies the DN of the directory manager.
-w	Specifies the password of the directory manager.
-a	Defines the full path of the backup directory.

Restoring a Single Database

You can use the method described in this section if the following conditions are satisfied:

• The directory server is stopped.

• You are restoring a database from a backup file previously created for the same database on the same server.

To restore a single database:

1. As root from the command line, stop the server with the following command:

   # /usr/sbin/directoryserver stop

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

3. Copy all of the files to the directory containing the database you want to overwrite with your backup. Database directories are located in:

   /var/ds5/slapd-serverID/db

   For example, you might type the following:

   cp backupDir/* /var/ds5/slap-siroe/db/databaseDir

Restoring Databases that Include Replicated Entries

This section explains how to restore databases on supplier servers and on consumer servers, and how to ensure that the suppliers and consumers are synchronized after the operation.

Restoring a Supplier Replica

If you are restoring a database that is supplying entries to other servers (a supplier replica), then you must reinitialize all of the consumer replicas that receive updates from the restored database: on consumer servers, hub servers, and, in multi-master replication environments, on 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.

For information on initializing consumers, refer to Chapter 8, "Managing Replication."

Restoring a Consumer Replica

If you are restoring a database containing data received from a supplier server, then one of the following situations can occur:

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

  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.

  You can restore the local consumer and continue with normal operations. However, the consumer server must be stopped while you restore the consumer replica. The replication process will produce many errors if replication continues while the consumer replica is being restored.

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

  You need to reinitialize the consumer. For more information on reinitializing consumers, refer to "Initializing Consumers," on page 316.

For information on managing replication, see Chapter 8, "Managing Replication.

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 following directory:

/var/ds5/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.