Previous     Contents     Index     Next     
iPlanet Directory Server 5.1 Administrator's Guide



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

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.



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

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

    Solaris 9 platform

    /var/ds5/slapd-serverID/ldif

    Other platforms

    installDir/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 (directoryserver ldif2db on the Solaris 9 platform).

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

  • Using ldif2db.pl (directoryserver ldif2db-task on the Solaris 9 platform).

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

  • Using ldif2ldap (directoryserver ldif2ldap on the Solaris 9 platform).

    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 ldif2db command (directoryserver ldif2db on the Solaris 9 platform) 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. As root from the command line, stop the server with the following command:

    Solaris 9 platform

    # /usr/sbin/directoryserver stop

    Other platforms

    # installDir/slapd-serverID/stop-slapd

  2. Use the ldif2db command:

    Solaris 9 platform

    # /usr/sbin/directoryserver ldif2db

    Other platforms

    # installDir/slapd-serverID/ldif2db

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

The following examples use the ldif2db 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.



Windows NT batch file:

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

UNIX shell script:

# use 'directoryserver ldif2db' on Solaris 9 plaforms
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 Examples

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 the ldif2db.pl Perl Script

As with the ldif2db command, the ldif2db.pl script (directoryserver ldif2db-task on the Solaris 9 platform) 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.



The command for this script is platform-dependent:

Solaris 9 platform

# /usr/sbin/directoryserver ldif2db-task

Windows platforms

installDir> bin\slapd\admin\bin\perl slapd-serverID\ldif2db.pl

Other platforms

# installDir/slapd-serverID/ldif2db.pl

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

The following examples import an LDIF file using theldif2db.pl script. You do not need root privileges to run the script, but you must authenticate as the directory manager.

Windows NT batch file:

iPlanet\Servers\bin\slapd\admin\bin\perl.exe
  iPlanet\Servers\slapd-siroe\ldif2db.pl
    -
D "cn=Directory Manager" -w password -n Database1
    -
i iPlanet\Servers\slapd-siroe\ldif\demo.ldif

UNIX shell script:

# use 'directoryserver ldif2db-task' on Solaris 9 plaforms
ldif2db.pl \
  -D "cn=Directory Manager" -w password -n Database1 \
  -i /usr/iplanet/servers/slapd-siroe/ldif/demo.ldif

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


Table 4-3    Description of ldif2db.pl Options Used in the Examples

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 ldif2ldap command (directoryserver ldif2ldap on the Solaris 9 platform) 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, use the following command:

Solaris 9 platform

# /usr/sbin/directoryserver ldif2ldap

Other platforms

# installDir/slapd-serverID/ldif2ldap

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

The following examples perform an import using the ldif2ldap command. 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.

Windows NT batch file:

ldif2ldap.bat "cn=Directory Manager" password
  c:\iplanet\servers\slapd-siroe\ldif\demo.ldif

UNIX shell script:

# use 'directoryserver ldif2ldap' on Solaris 9 plaforms
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:

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

    Solaris 9 platform

    /var/ds5/slapd-serverID/ldif

    Other platforms

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

    Solaris 9 platform

    /var/ds5/slapd-serverID/ldif

    Other platforms

    /usr/iplanet/servers/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 (directoryserver db2ldif on the Solaris 9 platform). This script 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 datatbase to an LDIF file, use the following command:

Solaris 9 platform

# /usr/sbin/directoryserver db2ldif

Other platforms

# installDir/slapd-serverID/db2ldif

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

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

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

The following table describes the db2ldif 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 installDir/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 Directory Server Console or a command-line script.

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


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

    Solaris 9 platform

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

    Other platforms

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

    where serverID is the name of your directory server and the backupDir name is generated to contain the time and date the backup was created.

  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 (directoryserver db2bak on the Solaris 9 platform). This script 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:

Solaris 9 platform

# /usr/sbin/directoryserver db2bak backupDir

Other platforms

# installDir/slapd-serverID/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. For more information about using this script, refer to iPlanet Directory Server Configuration, Command, and File Reference.

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

# db2bak /usr/iplanet/servers/slapd-siroe/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:

    Solaris 9 platform

    # /usr/sbin/directoryserver stop

    Other platforms

    # installDir/slapd-serverID/stop-slapd

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

    Solaris 9 platform

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

    Other platforms

    # cd installDir/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 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:

Solaris 9 platform

/var/ds5/slapd-serverID/config

Other platforms

/usr/iplanet/servers/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 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 of the backups located in the default directory:

    Solaris 9 platform

    /var/ds5/slapd-serverID/bak

    Other platforms

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

  • Using the bak2db command (directoryserver bak2db on the Solaris 9 platform). This script requires the server to be shut down.

  • Using the bak2db.pl perl script (directoryserver bak2db-task on the Solaris 9 platform). 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. As root from the command line, stop the server with the following command:

    Solaris 9 platform

    # /usr/sbin/directoryserver stop

    Other platforms

    # installDir/slapd-serverID/stop-slapd

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

    Solaris 9 platform

    # /usr/sbin/directoryserver bak2db backupDir

    Other platforms

    # installDir/slapd-serverID/bak2db backupDir

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



    Caution

    Restoring your databases overwrites any existing database files.



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

# bak2db /usr/iplanet/servers/slapd-siroe/bak/2001_07_01_11_34_00


Using bak2db.pl Perl Script
To restore your directory from the command line while the server is running, use the following perl script:

Solaris 9 platform

# /usr/sbin/directoryserver bak2db-task

Windows platforms

installDir> bin\slapd\admin\bin\perl slapd-serverID\bak2db.pl

Other platforms

# installDir/slapd-serverID/bak2db.pl

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



Caution

Restoring your databases overwrites any existing database files.



The following examples import an LDIF file using theldif2db.pl script.

Windows NT batch file:

iPlanet\Servers\bin\slapd\admin\bin\perl.exe
  iPlanet\Servers\slapd-siroe\bak2db.pl
    -
D "cn=Directory Manager" -w password
    -a \iPlanet\Servers\slapd-siroe\bak\2001_07_01_11_34_00

UNIX shell script:

bak2db.pl -D "cn=Directory Manager" -w password \
  -a /usr/iplanet/servers/slapd-siroe/bak/checkpoint

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


Table 4-5    Description of bak2db.pl Options Used in the Examples

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:

    Solaris 9 platform

    # /usr/sbin/directoryserver stop

    Other platforms

    # installDir/slapd-serverID/stop-slapd

  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:

    Solaris 9 platform

    /var/ds5/slapd-serverID/db

    Other platforms

    installDir/slapd-serverID/db

    For example, you might type the following:

    cp backupDir/* /usr/iplanet/servers/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 317.

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:

Solaris 9 platform

/var/ds5/slapd-serverID/config

Other platforms

installDir/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.


Previous     Contents     Index     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated October 29, 2001