Chapter 4 Backing Up and Restoring Data

The data managed by your directory server is often imported in bulk. Directory Server provides tools for importing and exporting entire suffixes. It also provides tools for making backups of all suffixes at once and for restoring all data from a backup.

You can backup and restore data using the plain-text LDAP Data Interchange Format (LDIF).

This chapter describes the following procedures for backing up and restoring directory data:

Setting Suffix Read-Only Mode

Importing Data

Exporting Data

Backing Up Data

Restoring Data from Backups



Note	If you are running more than one version of Directory Server, note that all examples in this chapter assume that Directory Server 5.2 is the default version. If this is not the case, you must either run the following command once to set 5.2 as the default version: # /usr/sbin/directoryserver -d 5.2 or include the -useversion option each time you run the directoryserver command to specify the version, for example: # /usr/sbin/directoryserver -useversion 5.2 ldif2db ...

Setting Suffix Read-Only Mode

Before performing certain export or backup operations on your Directory Server, you can enable read-only mode on any suffix to ensure you have a faithful image of the state of its contents at a given time. Also, before performing an import or restore operation, you must ensure that the suffixes affected by the operation are not in read-only mode.

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, you may enable read-only mode on one server, and your data will remain writable on the other masters.

Importing Data

Importing an LDIF file allows you to add, modify, and delete entries in bulk in any suffix of the directory.

Initializing a suffix from an LDIF file deletes the current data in the suffix and replaces it with the contents of the LDIF file.

Both methods are available through Directory Server Console and using the command-line utilities.

The following table shows the differences between an import and an initialization:


Note	All LDIF files you import must use UTF-8 character set encoding. When importing LDIF, parent entries must either exist in the directory or be added first from the file. When initializing a suffix, the LDIF file must contain the root entry and all directory tree nodes of the corresponding suffix.

Table 4-1 Comparison of Importing Data Versus Initializing a Suffix
Domain of Comparison	Importing Data	Initializing Suffixes
Overwrites content	No	Yes
LDAP operations	Add, modify, delete	Add only
Performance	Slower	Fast
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	On client machine	Local to client or local to server
Imports configuration information (cn=config)	Yes	No

Importing LDIF Files

When you perform an import operation, Directory Server Console performs an ldapmodify operation to add new entries to the directory. Entries are specified in an LDIF file which may also contain update statements to modify or delete existing entries as part of the import operation.

The imported entries may target any suffix managed by your Directory Server and any chained suffix or chained sub-suffix defined in your configuration. As with any other operation that adds entries, the server will index all new entries as they are imported.

Importing LDIF Using the Console

You must be logged in as the Directory Manager or an Administrator in order to perform an import:

On the top-level Tasks tab of Directory Server Console, scroll to the bottom of the tab and click the button beside “Import from LDIF.”

The Import LDIF dialog is displayed.

In the LDIF File field of the Import LDIF dialog, enter the full path to the LDIF file you want to import, or click Browse to select the file in the local file system.

If you are accessing a directory on a remote machine, the field name appears as “LDIF file (on console machine).” This label reminds you that you are browsing the local file system, not that of the remote directory server machine.

Set the following options as desired:

“Add only” - The LDIF file may contain modify and delete instructions in addition to the default add instructions. Select this checkbox if you want the console to perform only add instructions and ignore all others in the LDIF file.

“Continue on error” - Select this checkbox if you want the console 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 suffix. The console notes errors such as existing entries in the rejects file while performing the import operation.

When this checkbox is not selected, the import operation will stop after the first error it encounters. All prior entries in the LDIF file will have been successfully imported and will remain in the directory.

In the “File for rejects” field, enter the full path to the file in which you want the console to record all entries it cannot import, or click Browse to select the file in the local file system.

For example, the server cannot import an entry that already exists in the directory or an entry that has no parent object. The console will write the error message sent by the server in the rejects file.

If you leave this field blank, the server will not record rejected entries.

Click OK to begin the import operation.

Directory Server Console displays a dialog containing the status of the operation and the text of any errors that occur. If the “File for rejects” field is not blank, all error messages will also be written in the named file.

Importing LDIF From the Command Line

The directoryserver ldif2ldap command will import an LDIF file through LDAP and perform all operations it contains. Using this command you import data to all directory suffixes at the same time. The server must be running in order to import using ldif2ldap.

	# /usr/sbin/directoryserver -s serverID ldif2ldap

The following example performs an import using the ldif2ldap command. You do not need root privileges to run this command, but you must authenticate as a user with root permissions, such as Directory Manager. The last parameter specifies the name of the LDIF file to import.

# /usr/sbin/directoryserver -s example ldif2ldap \
-D "cn=Directory Manager" -w password \
-f /var/opt/mps/serverroot/slapd-example/ldif/demo.ldif

For more information about using this command, see “ldif2ldap” in Chapter 1 of the Directory Server Administration Reference.

Initializing a Suffix

Initializing a suffix overwrites the existing data in a suffix with the contents of an LDIF file which contains only entries for addition.


Caution	If the server you are managing is a Configuration Directory Server, be careful not to overwrite the o=NetscapeRoot suffix when initializing suffixes from an LDIF file, unless you are restoring data. Otherwise, you will delete information that will require the reinstallation of all your Sun Java System servers.

You must be authenticated as the Directory Manager or Administrator to initialize a suffix. For security reasons only the Directory Manager and Administrators have access to the root entry of a suffix, for example dc=example,dc=com.Therefore, only these identities may import an LDIF file that contains a root entry.

Initializing a Suffix From the Console


Caution	This procedure overwrites the data in your suffix.

On the top-level Configuration tab of Directory Server Console, expand the Data node to display the suffix you wish to initialize.

Right-click the suffix node and select Initialize from the pop-up menu. Alternatively, you may select the suffix node and then choose Initialize from the Object menu. The Initialize Suffix dialog is displayed.

In the “LDIF file” field, enter the full path to the LDIF file you want to use for initialization, or click Browse to locate it on your machine.

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:

on console. Indicates that the LDIF file is located on the machine on which you are running the console. In this case, you can browse for the file.

on server. Indicates that the LDIF file is located on a remote server. In this case, the Browse button is disabled. By default, the console looks for the file in the following directory:

ServerRoot/slapd-serverID/ldif

Click OK.

Confirm that you wish to overwrite the data in your suffix. The suffix initialization will proceed and any errors will be reported in a dialog.

Initializing a Suffix Using the ldif2db Command

The directoryserver ldif2db command initializes a suffix and overwrites the existing data. This 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 suffix.

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


	# /usr/sbin/directoryserver -s serverID stop

Run the import command:


	# /usr/sbin/directoryserver -s serverID ldif2db ...

Start the server as follows:


	# /usr/sbin/directoryserver -s serverID start

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

/usr/sbin/directoryserver -s example ldif2db -n Database1 \
-i /var/opt/mps/serverroot/slapd-example/ldif/demo.ldif \
-i /var/opt/mps/serverroot/slapd-example/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. CAUTION: If you specify a database 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.
-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 specified on the command line.

For more information about using this command, see “ldif2db” in Chapter 1 of the Directory Server Administration Reference.

Initializing a Suffix Using ldif2db-task

As with the ldif2db command, the directoryserver ldif2db-task command overwrites the data in a specified suffix. This script requires the server to be running in order to perform the import.

	# /usr/sbin/directoryserver -s serverID ldif2db-task ...

The following example imports an LDIF file using ldif2db-task. You do not need root privileges to run the command, but you must authenticate as a user with root permissions, such as Directory Manager.

/usr/sbin/directoryserver -s example ldif2db-task \
-D "cn=Directory Manager" -w password -n Database1 \
-i /var/opt/mps/serverroot/slapd-example/ldif/demo.ldif

Table 4-3 Description of ldif2db-task Options Used in the Example
Option	Description
-D	Specifies a user DN with root permissions, such as Directory Manager.
-w	Specifies the password of the user.
-n	Specifies the name of the database into which you are importing the data. CAUTION: If you specify a database 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.
-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 specified on the command line.

For more information about using this command, see “ldif2db-task” in Chapter 1 of the Directory Server Administration Reference.

Exporting Data

You can export the contents of your directory using LDIF. Exporting data can be useful for the following:

Backing up the data in your server.

Copying your data to another directory server.

Exporting your data to another application.

Repopulating suffixes after a change to your directory topology.

Exporting the Entire Directory to LDIF Using the Console

You can export some or all of your directory data to LDIF, depending on the location of the final exported file. When the LDIF file is on the server, you can export only the data contained in the local suffixes on the server. If the LDIF file is remote to the server, you can export all of the suffixes and chained suffixes.

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


Caution	Do not stop the server while an export operation is in progress.

On the top-level Tasks tab of Directory Server Console, scroll to the bottom of the tab and click the button beside “Export to LDIF.”

The Export dialog is displayed.

If you are running the console on a machine remote to the server, two radio buttons are displayed beneath the LDIF file field. Select “on console machine” to indicate that you are exporting to an LDIF file in the machine from which you run the console. Select “on server machine” to indicate that you are exporting to an LDIF file located on the server’s machine.

Enter the full path and file name of the LDIF file in the “LDIF file” field, or click Browse to locate the file.

If you have selected “on server machine”, the Browse button is disabled. When the Browse button is not enabled, the file is stored by default in the following directory:

ServerRoot/slapd-serverID/ldif

If you want to export the whole directory, select the “All suffixes” radio button.

If you want to export only a subtree of the directory, select the “Subtree” radio button and then enter the DN at the base of the subtree in the text box.

You can also click Browse to select a subtree.

Click OK to export the directory contents to the file.

Exporting a Single Suffix to LDIF Using the Console

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

On the top-level Configuration tab of Directory Server Console, expand the Data node to display the suffix you wish to export.

Right-click the suffix node and select Export from the pop-up menu. Alternatively, you may select the suffix node and then choose Export from the Object menu.

The Export Suffix dialog is displayed.

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:

ServerRoot/slapd-serverID/ldif

If the suffix is replicated you may select the checkbox to Export Replication Information. This feature is only necessary if you will use the exported LDIF to initialize another replica of this suffix.

If attribute encryption is enabled for this suffix, you may select the checkbox to Decrypt attributes. In order to do so, you must provide the password that protects the server’s certificate database. Select the option to enter the password or to enter the name of a file containing the password. If you cannot provide the password to decrypt attribute values, the encrypted values will appear in the LDIF output.

Click OK to export the contents of the suffix to the file.

Exporting to LDIF From the Command Line

You can export any suffix or subtree of the directory to LDIF using the directoryserver db2ldif command. This script exports all of your suffix 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 -s serverID db2ldif ...

/usr/sbin/directoryserver -s example db2ldif \
-a /var/opt/mps/serverroot/slapd-example/output.ldif \
-s "dc=example,dc=com" -s "o=NetscapeRoot"

Table 4-4 Description of db2ldif Options Used in the Example
Option	Description
-a	Defines the name of the output file in which the server saves the exported LDIF. This file is stored by default in the ServerRoot/slapd-serverID directory.
-s	Specifies the suffix or subtree to include in the export. You may use multiple -s arguments to specify multiple suffixes or subtrees.

The db2ldif command may also be used with the -r option to export replicated suffixes to an LDIF file. The resulting LDIF will contain attribute subtypes that are used by the replication mechanism. This LDIF file can then be imported on the consumer server to initialize the consumer replica, as described in Initializing Replicas.

The server must not be running when using the db2ldif command with the -r option. You must stop the server first and start it afterwards, or use the db2ldif.pl script with the -r option that does not require the server to be stopped.

For more information about using this script, see “db2lidf” in Chapter 1 of the Directory Server Administration Reference.

Backing Up Data

Backing up data saves a snapshot of the contents of your directory in case the database files later become corrupted or deleted. You can back up suffixes using Directory Server Console or a command-line script.

All backup procedures described here store a copy of the server files on the same host by default. You should then copy and store your backups on a different machine or file system for greater security.

Backing Up Your Server Using the Console

When you back up your server from 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.


Caution	Never stop the server during a backup operation.


Note	You cannot use these backup methods to back up a chained suffix on a remote server. Separate servers must be backed up independently.

On the top-level Tasks tab of Directory Server Console, click the button beside “Back up Directory Server”.

The Backup Directory Server dialog box is displayed.

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:

ServerRoot/slapd-serverID/bak/YYYY_MM_DD_hh_mm_ss

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

Click OK to create the backup.

Backing Up Your Server From the Command Line

You can back up your server from the command line using the directoryserver db2bak command. This command works whether or not the server is running.

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

	# /usr/sbin/directoryserver -s 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 command, refer to “db2bak” in Chapter 1 of the Directory Server Administration Reference. For information on designing a backup strategy for your deployment, see “Planning a Backup Strategy,“ in Chapter 9 of the Directory Server Deployment Planning Guide.

Backing Up the dse.ldif Configuration File

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

When you make modifications to the cn=config branch, the file is first backed up to a file named 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 Data from Backups

The following procedures describe how to restore suffixes in your directory using Directory Server Console or the command line. Your server must have been backed up using the procedures described in Backing Up Data. Before restoring suffixes involved in replication agreements, please read Restoring Replicated Suffixes.

Restoring Replicated Suffixes


Caution	Do not stop the server during a backup or restore operation. Restoring your server overwrites any existing database files and thus loses any modifications of the data since the backup.

Suffixes that are replicated between supplier servers and consumer servers require special consideration before being restored. If possible, you should update the suffix through the replication mechanism instead of restoring it from a backup. This section explains how and when to restore a replica, and how to ensure that it is synchronized with other replicas after the operation. For further information on using backup and restore to initialize a replica, see Initializing Replicas.

Restoring the Supplier in a Single-Master Scenario

A suffix that is a single-master supplier contains the authoritative data for the entire replication topology. Therefore, restoring this suffix is equivalent to reinitializing all data in the entire topology. You should restore a single master only if you want to reinitialize all data from the contents of the backup to be restored.

If the single master data is not recoverable due to an error, you may consider using the data on one of the consumers because it may contain updates that are more recent than a backup. In this case, you need to export the data from the consumer replica to an LDIF file, and reinitialize the master from the LDIF file.

Whether you restore a backup or import an LDIF file on a master replica, you must then reinitialize all of the hubs and consumer replicas that receive updates from this replica. A message is logged to the supplier servers’ log files to remind you that reinitialization of the consumers is required.

Restoring a Supplier in a Multi-Master Scenario

In multi-master replication, the other masters each contain an authoritative copy of the replicated data. You cannot restore an old backup which may be out of date with the current replica contents. If possible you should allow the replication mechanism to bring the master up to date from the contents of the other masters.

If that is not possible, you should only restore a multi-master replica in one of the following ways:

The simplest way is not to restore a backup, but to reinitialize the intended master from one of the other masters. This insures that the latest data is sent to the intended master and that the data will be ready for replication. See Initializing a Replica Using the Console or Initializing a Replica From the Command Line.

For replicas with millions of entries, it can be faster to use the new binary copy feature to restore a more recent backup taken from one of the other masters. See Initializing a Replica Using Binary Copy.

If you have a backup of your master that is not older than the maximum age of the change log contents on any of the other masters, then it may be used to restore this master. See Advanced Multi-Master Configuration, for a description of change log age. When the old backup is restored, the other masters will use their change logs to update this master with all modifications that have been processed since the backup was saved.

Regardless of how you restore or reinitialize, the master replica will remain in read-only mode after the initialization. This behavior allows the replica to synchronize with the other masters, after which time you may allow write operations, as described in Convergence After Multi-Master Initialization.

The advantage of allowing all replicas to converge before allowing write operations on the restored or reinitialized master is that none of the hub or consumer servers will require reinitialization.

Restoring a Hub

This section applies only in situations where the replication mechanism cannot automatically bring a hub replica up to date, for example if the database files become corrupted or if replication has been interrupted for too long. In these cases, you will need to restore or reinitialize the hub replica in one of the following ways:

The simplest way is not to restore a backup, but to reinitialize the hub from one of the master replicas. This ensures that the latest data is sent to the hub and that the data will be ready for replication. See Initializing a Replica Using the Console or Initializing a Replica From the Command Line.

For replicas with millions of entries, it can be faster to use the new binary copy feature to restore a more recent backup taken from another hub replica. See Initializing a Replica Using Binary Copy. If there is no other hub replica to copy, you must reinitialize the hub as described in the previous paragraph or restore it as described in the next paragraph, if possible.

If you have a backup of your hub that is not older than the maximum age of the change log contents on any of its suppliers, either hub or master replicas, then it may be used to restore this hub. See Advanced Multi-Master Configuration, for a description of change log age. When the old backup is restored, its suppliers will use their change logs to update this hub with all modifications that have been processed since the backup was saved.



Note	Regardless of how you restore or reinitialize the hub replica, you must then reinitialize all consumers of this hub, including any other levels of hubs.

Restoring a Dedicated Consumer

This section applies only in situations where the replication mechanism cannot automatically bring a dedicated consumer replica up to date, for example if the database files become corrupted or if replication has been interrupted for too long. In these cases, you will need to restore or reinitialize the consumer in one of the following ways:

The simplest way is not to restore a backup, but to reinitialize the consumer from one of its suppliers, either a master or a hub replica. This ensures that the latest data is sent to the consumer and that the data will be ready for replication. See Initializing a Replica Using the Console or Initializing a Replica From the Command Line.

For replicas with millions of entries, it can be faster to use the new binary copy feature to restore a more recent backup taken from another consumer replica. See Initializing a Replica Using Binary Copy. If there is no other consumer to copy, you must reinitialize the replica as described in the previous paragraph or restore it as described in the next paragraph, if possible.

If the backup of your consumer is not older than the maximum age of change log contents on any of its suppliers, either hub or master replicas, then it may be used to restore the consumer. See Advanced Multi-Master Configuration, for a description of change log age. When the old backup is restored, its suppliers will use their change logs to update this consumer with all modifications that have been processed since the backup was saved.

Restoring Your Server Using the Console

You can restore corrupted directory data from a previously generated backup using Directory Server Console. To restore data using the console, Directory Server must be running. However, the corresponding suffixes will be unavailable for processing operations during the restore.

On the top-level Tasks tab of Directory Server Console, click the button beside “Restore Directory Server”.

The Restore Directory dialog box is displayed.

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:

ServerRoot/slapd-serverID/bak

Click OK to restore your server.

Restoring Your Server from the Command Line

Using the directoryserver bak2db command. This command requires the server to be shut down.

Using the directoryserver bak2db-task command . This command requires the server to be running.

Using the bak2db Command

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


	# /usr/sbin/directoryserver -s serverID stop

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


	# /usr/sbin/directoryserver -s serverID bak2db backupDir

Start the server as follows:


	# /usr/sbin/directoryserver -s serverID start

/usr/sbin/directoryserver -s example bak2db \
/var/opt/mps/serverroot/slapd-example/bak/2003_07_01_11_34_00

For more information, refer to “bak2db” in Chapter 1 of the Directory Server Administration Reference.

Using bak2db-task

To restore your directory from the command line while the server is running, use the following command:

	# /usr/sbin/directoryserver -s serverID bak2db-task ...

The following example restores a backup using the bak2db-task command. The -a option gives the full path of the backup directory.

/usr/sbin/directoryserver -s example bak2db-task\
-D "cn=Directory Manager" -w password \
-a /var/opt/mps/serverroot/slapd-example/bak/2003_07_01_11_34_00

For more information, refer to “bak2db-task” in Chapter 1 of the Directory Server Administration Reference.

Restoring the dse.ldif Configuration File

The directory creates two backup copies of the dse.ldif file in the following 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.

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


	# /usr/sbin/directoryserver -s serverID stop

Change to the directory containing the configuration files, for example:

# cd /var/mps/serverrot/slapd-serverID/config

Overwrite the dse.ldif file with a backup configuration file known to be good. For example, you might type the following:

cp dse.ldif.startOK dse.ldif

Start the server with the following command:


	# /usr/sbin/directoryserver -s serverID start

Previous Contents Index Next
Sun Java(TM) System Directory Server 5 2004Q2 Administration Guide