|
| Sun ONE Directory Server Administration Guide |
Chapter 4 Populating Directory Contents
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.
This chapter describes the following procedures for populating your directory:
- Setting Suffix Read-Only Mode
- Importing Data
- Exporting Data
- Backing Up Data
- Restoring Data from Backups
Setting Suffix Read-Only Mode
Before performing certain export or backup operations on your Directory Server, you can enable read-only mode on any given 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.
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, 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 Data
Sun ONE Directory Server provides two methods for 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 the 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, the 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 Adminstrator in order to perform an import:
- On the top-level Tasks tab of the 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 perfoming 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.
The 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" is not blank, all error messages will also be written in the named file.
Importing LDIF From the Command Line
The ldif2ldap command (directoryserver ldif2ldap in the Solaris Packages) will import an LDIF file through LDAP and perform all operations it contains. Using this script 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:
Solaris Packages
# /usr/sbin/directoryserver ldif2ldap
Other Installations
# ServerRoot/slapd-serverID/ldif2ldap
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.
UNIX shell script:
# in Solaris Packages installations
/var/Sun/mps/slapd-example/ldif2ldap \
"cn=Directory Manager" password \
/var/Sun/mps/slapd-example//ldif/demo.ldifWindows batch file:
"cn=Directory Manager" password
C:\Program Files\Sun\MPS\slapd-example\ldif\demo.ldifFor more information about using this script, see "ldif2ldap" in Chapter 2 of the Sun ONE Directory Server Reference Manual.
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 in order 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 the 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:
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:
- 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 ldif2db command (directoryserver ldif2db in the Solaris Packages) initializes a suffix and overwrites the existing data. 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 suffix.
To import LDIF with the server stopped:
- As root from the command line, stop the server with the following command:
Solaris Packages
# /usr/sbin/directoryserver stop
Other Installations
# ServerRoot/slapd-serverID/stop-slapd
- Run the command located in:
Solaris Packages
# /usr/sbin/directoryserver ldif2db
Other Installations
# ServerRoot/slapd-serverID/ldif2db
- Start the server with the appropriate command:
Solaris Packages
# /usr/sbin/directoryserver start
Other Installations
# ServerRoot/slapd-serverID/start-slapd
The following examples use the ldif2db command to import two LDIF files into a single suffix.
UNIX shell script:
# on Solaris Packages installations
/var/Sun/mps/slapd-example/ldif2db -n Database1 \
-i /var/Sun/mps/slapd-example/ldif/demo.ldif \
-i /var/Sun/mps/slapd-example/ldif/demo2.ldifWindows batch file:
-i C:\Program Files\Sun\MPS\slapd-example\ldif\demo.ldif
-i C:\Program Files\Sun\MPS\slapd-example\ldif\demo2.ldif
For more information about using this command, see "ldif2db" in Chapter 2 of the Sun ONE Directory Server Reference Manual.
Initializing a Suffix Using the ldif2db.pl Perl Script
As with the ldif2db command, the ldif2db.pl script (directoryserver ldif2db-task in the Solaris Packages) overwrites the data in a suffix you specify. This script requires the server to be running in order to perform the import.
Caution
This script overwrites the data in your suffix.
The command for this script is platform-dependent:
Solaris Packages
# /usr/sbin/directoryserver ldif2db-task
Windows Platforms
cd ServerRoot
bin\slapd\admin\bin\perl slapd-serverID\ldif2db.plOther Installations
# ServerRoot/slapd-serverID/ldif2db.pl
The following examples import an LDIF file using the ldif2db.pl script. You do not need root privileges to run the script, but you must authenticate as the directory manager.
UNIX shell script:
# on Solaris Packages installations
/var/Sun/mps/slapd-example/ldif2db.pl \
-D "cn=Directory Manager" -w password -n Database1 \
-i /var/Sun/mps/slapd-example/ldif/demo.ldifWindows batch file:
C:\Program Files\Sun\MPS\slapd-example\ldif2db.pl
-D "cn=Directory Manager" -w password -n Database1
-i C:\Program Files\Sun\MPS\slapd-example\ldif\demo.ldifThe following table describes the ldif2db.pl options used in the examples:
For more information about using this perl script, see "ldif2db.pl" in Chapter 2 of the Sun ONE Directory Server Reference Manual.
Exporting Data
You can export the contents of your directory using the plain-text LDAP Data Interchange Format (LDIF). LDIF is a textual representation of entries, attributes and their values. LDIF is a standard format described in RFC 2849 (http://www.ietf.org/rfc/rfc2849.txt).
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.
The export operations do not export the configuration information (cn=config).
Caution
Do not stop the server during an export operation.
Exporting the Entire Directory 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 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 the Directory Server console while the server is running:
- On the top-level Tasks tab of the Directory Server console, scroll to the bottom of the tab and click the button beside "Export to LDIF."
The Export dialog is displayed.
- 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:
- 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.
- 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 the Directory Server console while the server is running:
- On the top-level Configuration tab of the 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:
- 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 db2ldif command (directoryserver db2ldif in the Solaris Packages). 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 datatbase to an LDIF file, use the following command:
Solaris Packages
# /usr/sbin/directoryserver db2ldif
Other Installations
# ServerRoot/slapd-serverID/db2ldif
The following example exports two suffixes to a single LDIF file:
-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 "db2lidf" in Chapter 2 of the Sun ONE Directory Server Reference Manual.
Backing Up Data
Backing up your data saves a snapshot of the contents or your directory in case the database files later become corrupted or deleted. You can back up your suffixes using the Directory Server console or a command-line script.
Caution
Never stop the server during a backup operation.
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 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 server from the Server Console:
- On the top-level Tasks tab of the Directory Server console, click the button beside "Back Up Directory Server".
The Backup Directory 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:
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 db2bak command (directoryserver db2bak in the Solaris Packages). 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 Packages
# /usr/sbin/directoryserver db2bak backupDir
Other Installations
# ServerRoot/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 "db2bak" in Chapter 2 of the Sun ONE Directory Server Reference Manual.
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:
When you make modifications to the cn=config branch, 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 Data from Backups
The following procedures describe how to restore suffixes in your directory using the 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 back up.
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. 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 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 will be 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 to not 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 only applies to 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 to not restore a backup but to reinitialize the hub from one of the master replicas. This insures 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 only applies to 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 to not restore a backup but to reinitialize the consumer from one of its suppliers, either a master or a hub replica. This insures 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 hub with all modifications that have been processed since the backup was saved.
Restoring Your Server Using the Console
If your directory data become corrupted, you can restore data from a previously generated backup using the Directory Server console. In order to restore your server using the console, the 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 the 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:
- Click OK to restore your server.
Restoring Your Server from the Command Line
You can restore your server from the command line by using the following scripts:
- Using the bak2db command (directoryserver bak2db in the Solaris Packages). This script requires the server to be shut down.
- Using the bak2db.pl perl script (directoryserver bak2db-task in the Solaris Packages). This script requires the server to be running.
Using the bak2db Command-Line Script
To restore your directory from the command line while the server is shut down:
- As root from the command line, stop the server with the following command:
Solaris Packages
# /usr/sbin/directoryserver stop
Other Installations
# ServerRoot/slapd-serverID/stop-slapd
- Use the bak2db command with the full path of the backup directory:
Solaris Packages
# /usr/sbin/directoryserver bak2db backupDir
Other Installations
# ServerRoot/slapd-serverID/bak2db backupDir
- Start the server with the appropriate command:
Solaris Packages
# /usr/sbin/directoryserver start
Other Installations
# ServerRoot/slapd-serverID/start-slapd
The following example restores a backup from the default backup directory:
For more information, refer to "bak2db" in Chapter 2 of the Sun ONE Directory Server Reference Manual.
Using bak2db.pl Perl Script
To restore your directory from the command line while the server is running, use the following perl script:
Solaris Packages
# /usr/sbin/directoryserver bak2db-task
Windows platforms
cd ServerRoot
bin\slapd\admin\bin\perl slapd-serverID\bak2db.plOther Installations
# ServerRoot/slapd-serverID/bak2db.pl
The following examples import an LDIF file using the ldif2db.pl script. The -a option gives the full path of the backup directory.
UNIX shell script:
# on Solaris Packages installations
/var/Sun/mps/slapd-example/bak2db.pl \
-D "cn=Directory Manager" -w password \
-a /var/Sun/mps/slapd-example/bak/checkpointWindows batch file:
C:\Program Files\Sun\MPS\slapd-example\bak2db.pl
-D "cn=Directory Manager" -w password
-a C:\Program Files\Sun\MPS\slapd-example\bak\2001_07_01_11_34_00For more information, refer to "bak2db.pl" in Chapter 2 of the Sun ONE Directory Server Reference Manual.
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.
To restore the dse.ldif configuration file:
- As root from the command line, stop the server with the following command:
Solaris Packages
# /usr/sbin/directoryserver stop
Other Installations
# ServerRoot/slapd-serverID/stop-slapd
- Change to the directory containing the configuration files.
- Overwrite the dse.ldif file with a backup configuration file known to be good. For example, you might type the following:
- Start the server with the appropriate command:
Solaris Packages
# /usr/sbin/directoryserver start
Other Installations
# ServerRoot/slapd-serverID/start-slapd