Sun Java(TM) System Directory Server 5.2 2005Q1 Administration Guide |
Chapter 4
Backing Up and Restoring DataThe 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:
- Restoring Data from Backups
Setting Suffix Read-Only ModeBefore 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.
To make a suffix read-only, follow the procedure described in Setting Access Permissions and Referrals. Alternatively, you may make the entire directory server unwritable, as described in Setting Global Read-Only Mode.
Importing DataDirectory Server provides two methods for importing data:
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:
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.
The full path of the command is:
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.ldifFor more information about using this command, see the Directory Server Man Page 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.
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
- 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.
To import LDIF with the server stopped:
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
For more information about using this command, see the Directory Server Man Page 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.
The command for this script is:
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.ldifThe following table describes the ldif2db-task options used in the example:
For more information about using this command, see the Directory Server Man Page Reference.
Exporting DataYou can export the contents of your directory using LDIF. Exporting data can be useful for the following:
The export operations do not export the configuration information (cn=config).
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:
- 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:
The following example exports two suffixes to a single LDIF file:
/usr/sbin/directoryserver -s example db2ldif \
-a /var/opt/mps/serverroot/slapd-example/output.ldif \
-s "dc=example,dc=com" -s "o=NetscapeRoot"The following table describes the db2ldif options used in this example:
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 the Directory Server Man Page Reference.
Backing Up DataBacking 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.
Note
You cannot use these backup methods to back up a chained suffix on a remote server. Separate servers must be backed up independently.
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.
To back up your server from the console:
- 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.
To back up your directory, use the following command:
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, see the Directory Server Man Page Reference. For information on designing a backup strategy for your deployment, see the Directory Server Deployment Planning Guide.
Backing Up the dse.ldif Configuration File
When restoring a server, the dse.ldif configuration file must contain the same configuration as when the server was backed up. To ensure this, back up a copy of your dse.ldif configuration file by saving it in a safe place whenever you make a backup of your server.
In addition, when you perform the following actions, Directory Server automatically backs up the dse.ldif configuration file in the directory ServerRoot/slapd-serverID/config.
- When you start Directory Server, it automatically creates a backup of the dse.ldif file in a file named dse.ldif.startOK.
- 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.
Restoring Data from BackupsThe 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.
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.
Restoring Replicated Suffixes
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.
When you restore a supplier or hub instance, the server configuration must be the same as it was when the backup was made. To ensure this, restore dse.ldif before restoring Directory Server data. See Restoring the dse.ldif Configuration File.
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.
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.
To restore your server from a previously created backup:
- 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
You can restore your server from the command line using the following scripts:
Using the bak2db Command
To restore your directory from the command line while the server is shut down:
The following example restores a backup from the default backup directory:
/usr/sbin/directoryserver -s example bak2db \
/var/opt/mps/serverroot/slapd-example/bak/2003_07_01_11_34_00For more information on the bak2db command, see the Directory Server Man Page Reference.
Using bak2db-task
To restore your directory from the command line while the server is running, use the following command:
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_00For more information, see the Directory Server Man Page Reference.
Restoring the dse.ldif Configuration File
The directory creates two backup copies of the dse.ldif file in the following directory:
ServerRoot/slapd-serverID/config
The dse.ldif.startOK file records a copy of the dse.ldif file at server start up. The dse.ldif.bak file contains a backup of the most recent changes to the dse.ldif file. Copy the file with the most recent changes to your directory.
To restore the dse.ldif configuration file:
- As root from the command line, stop the server with the following command:
- 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