Importing Data
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
|
The LDIF files
you use for import
operations must use UTF-8 character set encoding. Import operations do
not convert data from local character set encoding to UTF-8 character
set encoding.
|
|
Table
4-1 describes the differences between an import and initializing
databases.
Table 4-1
Import Method Comparison
|
Action
|
Import
|
Initialize
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:
|
|
Note
|
All imported
LDIF files must also contain the root suffix.
|
|
Importing a
Database 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:
- In 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.
- 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.
- In the Options box,
select one or both
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.
- 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.
- Click OK.
The server performs the import and also
creates indexes.
|
|
Note
|
Trailing spaces are dropped during a remote
Console import but are preserved during both local Console or ldif2db
import operations.
|
|
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=example,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
Netscape servers.
|
|
To initialize a
database using the
Directory Server Console:
- In the Directory Server Console,
select the Configuration tab.
- Expand the Data tree
in the left navigation pane. Expand the suffix of the database you want
to initialize, then click the database itself.
- Right-click the
database, and select
Initialize Database.
You can also select Initialize Database
from the Object menu.
- 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.
- 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:
serverRoot/slapd-serverID/ldif
- Click OK.
Importing
from the Command-Line
You can use three
methods for importing data through the command-line:
- Using
ldif2db -- This import method overwrites the contents of your
database and requires the server to be stopped.
- Using ldif2db.pl
-- This import method overwrites the contents of your database while
the server is still running.
- Using
ldif2ldap -- This method appends your LDIF file through LDAP.
You can use this method to append data to all of your databases.
Importing Using
the ldif2db Command-Line Script
The ldif2db
script 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:
- From the command-line, change to the
following directory:
serverRoot/slapd-serverID/
- Stop the server by
typing the following:
./stop-slapd
- Run the
ldif2db command-line script.
For more information about using this
script, refer to Netscape
Directory
Server Configuration, Command, and File Reference.
|
|
Caution
|
If you a specify
a database in the
-n
option that does not correspond with the suffix contained by the LDIF
file, all of the data contained by the database is deleted, and the
import fails. Make sure that you do not misspell the database name.
|
|
Two examples of
performing an import using ldif2db
follow:
Windows batch file:
ldif2db.bat -n
Database1 -i c:\netscape\servers\slapd-dirserver\ldif\demo.ldif -i
c:\netscape\servers\slapd-dirserver\ldif\demo2.ldif
UNIX shell script:
ldif2db -n
Database1 -i /usr/netscape/servers/slapd-dirserver/ldif/demo.ldif -i
/usr/netscape/servers/slapd-dirserver/ldif/demo2.ldif
The following table describes the ldif2db
options used in the examples:
|
Option
|
Description
|
|
-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.
|
|
-n
|
Specifies the
name of the database into which you are importing the data.
|
For more information about using this
script, refer to the Netscape
Directory
Server Configuration, Command, and File Reference.
Importing Using
the ldif2db.pl Perl Script
As with the ldif2db
script, the ldif2db.pl
script 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 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.
Windows batch file (as shown in the
example, you need to run the script from the
..\bin\slapd\admin\bin\perl directory):
..\bin\slapd\admin\bin\perl
ldif2db.pl -
D "cn=Directory Manager"
-w secretpwd
-
i c:\netscape\servers\slapd-dirserver\ldif\demo.ldif -n Database1
UNIX shell script:
ldif2db.pl -D
"cn=Directory Manager" -w secretpwd
-i
/usr/netscape/servers/slapd-dirserver/ldif/demo.ldif -n Database1
The following table describes the
ldif2db.pl options used in the examples:
|
Option
|
Description
|
|
-D
|
Specifies the DN
of the administrative user.
|
|
-w
|
Specifies the
password of the administrative user.
|
|
-i
|
Specifies 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.
|
|
-n
|
Specifies the
name of the database into which you are importing the data.
|
Importing Using the ldif2ldap
Command-Line Script
The
ldif2ldap script 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:
Two examples of performing an import using ldif2ldap
follow:
Windows batch file:
ldif2ldap
"cn=Directory Manager" secret
c:\netscape\servers\slapd-dirserver\ldif\demo.ldif
UNIX shell script:
ldif2ldap
"cn=Directory Manager" secret
/usr/netscape/servers/slapd-dirserver/ldif/demo.ldif
The ldif2ldap
script requires you to specify the DN of the administrative user, the
password of the administrative user, and the absolute path and file
name of the LDIF file(s) to be imported.
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.
Suppose your directory is contained by one
database, and you decide to split its contents over two databases, as
illustrated in Figure 4-1.
Figure 4-1
Splitting a Database Contents into Two Databases
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 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).
|
|
Note
|
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:
- In 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.
- 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 this directory:
serverRoot/slapd-serverID/ldif
- 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 "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.
- 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:
- In the Directory Server Console,
select the Configuration tab.
- 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.
- 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.
- 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 this directory:
serverRoot/slapd-serverID/ldif
- Click OK to export the
file.
Exporting to
LDIF from the Command-Line
You can export
your database to LDIF using the
db2ldif command-line script. This script exports all of your
database contents or a part of their contents to LDIF when the server
is running or stopped.
To export to LDIF from the command-line:
Two examples of performing an import using
db2ldif follow:
Windows batch file:
db2ldif -n
database1 -a output.ldif -s "dc=example,dc=com" -s "o=NetscapeRoot"
UNIX shell script:
db2ldif -n
database1 -a output.ldif -s "dc=example,dc=com" -s "o=NetscapeRoot"
The following table describes the db2ldif
options used in the examples:
|
Option
|
Description
|
|
-n
|
Specifies the
name of the database from which the file is being exported.
|
|
-a
|
Defines the
output file in which the server saves the exported LDIF. This file is
stored by default in the directory where the command-line script
resides.
|
|
-s
|
Specifies the
suffix or suffixes to include in the export. You may use multiple
-s arguments.
|
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:
|
|
Caution
|
Do not stop the
server during a backup or restore operation.
|
|
Backing Up
All Databases
The following procedures describe backing up
all of the databases in your directory using the 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 theDirectory
Server Console:
- In the Directory Server Console,
select the Tasks tab.
- Click Back Up
Directory Server.
The Backup Directory dialog box is
displayed.
- Enter the full path of
the directory where you want to store the backup file in the Directory
text box, or click "Use default," and the server provides a name for
the backup directory.
If you are running the Console on the
same machine as the directory, you can also click Browse to locate a
local directory.
If you choose to use the default, the backup files will be placed in the following
location:
serverRoot/slapd-serverID/bak/backup_directory
The
backup_directory variable names a directory using the name of the
backup file. By default, the backup directory name contains the time
and date the backup was created (YYYY_MM_DD_hhmmss).
- 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-line script. This script works when the server is running or
when the server is stopped.
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 from the
command-line using the
db2bak script:
Two examples of performing an import using db2bak
follow:
Windows batch file:
db2bak
\usr\netscape\servers\slapd-dirserver\bak\bak_20010701103056
UNIX shell script:
db2bak
/usr/netscape/servers/slapd-dirserver/bak/bak_20010701103056
You can specify the backup directory and
output file where the server saves the exported LDIF file. If you do
not specify a directory and output file, the directory will store the
file by default in the directory where the command-line script resides.
By default, the backup file is named according to the
year-month-day-hour format (YYYY_MM_DD_hhmmss).
Backing Up a
Single Database
To back up a single
database:
- At the command prompt, change to:
serverRoot/slapd-serverID
- If the server is
running, type the following to stop it:
./stop-slapd
- Change to the
directory containing the database you want to back up:
cd db/database_name
- Copy all of the files
in the directory to a backup directory you create. Do not use the serverRoot/slapd-serverID/bak/ directory, as the Directory Server Console
assumes the backups contained by this directory are global.
|
|
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).
|
|
Backing Up
the dse.ldif Configuration File
Directory Server automatically backs up the dse.ldif
configuration file. When you start your Directory Server, the directory
creates a backup of the
dse.ldif file automatically in a file named
dse.ldif.startOK in this directory:
serverRoot/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 serverRoot/slapd-serverID/config
directory before the directory writes the modifications to the dse.ldif
file.
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:
- In the Directory Server Console,
select the Tasks tab.
- Click 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
backups located in the default directory:
serverRoot/slapd-serverID/bak/backup_name
where
backup_name is the name of the backup file.
- 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-line script. This script requires the server to
be shut down.
- Using the bak2db.pl
Perl script. 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:
Two examples of performing an import
using bak2db
follow:
Windows batch file:
bak2db.bat
\usr\netscape\servers\slapd-dirserver\bak\bak_20010701103056
UNIX shell script:
bak2db
/usr/netscape/servers/slapd-dirserver/bak/bak_20010701103056
The bak2db
script requires that you define the full path and name of the input
file.
Using
bak2db.pl Perl Script
To restore your directory from the
command-line while the server is running:
Two examples of performing an import using bak2db.pl
follow (as shown in the example, you need to run the script from the
..\bin\slapd\admin\bin\perl directory):
Windows batch file:
..\bin\slapd\admin\bin\perl
bak2db.pl -D "cn=Directory Manager"
-w secret -a
\usr\netscape\servers\slapd-dirserver\bak\mybak_20010701103056
UNIX shell script:
bak2db.pl -D
"cn=Directory Manager" -w secret -a
/usr/netscape/servers/slapd-dirserver/bak/mybak_20010701103056
The following table describes the bak2db.pl
options used in the examples:
|
Option
|
Description
|
|
-a
|
Defines the full
path and name of the input file.
|
|
-D
|
Specifies the DN
of the administrative user.
|
|
-w
|
Specifies the
password of the administrative user.
|
Restoring
a Single Database
To restore a single database:
- At the command prompt, change to the
following directory:
cd serverRoot/slapd-serverID
- If the server is
running, type the following to shut it down:
./stop-slapd
- Change to the
directory containing the backup you want to restore.
- Copy all of the
files to the directory
containing the database you want to overwrite with your backup. For
example, you might type the following:
cp
backup_file../db/database_name
Restoring
Databases that Include Replicated Entries
If you are restoring a database that is
supplying entries to other servers, then you must reinitialize all of
the servers that receive updates from the restored database (for
example, consumer servers, hub servers, and, in multi-master
replication environments, 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.If you are restoring a
database containing data received from a supplier server, then
one of two situations can occur:
- Change log entries
have not yet expired
on the supplier server.
If the supplier server change log has not
expired since the database backup was taken, then you can restore the
local consumer and
continue with normal operations. 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 Netscape
Directory
Server Configuration, Command, and File Reference.
Directory Server automatically detects
the compatibility between the replica and its change log. If a mismatch
is detected, the server removes the old change log file and creates a
new, empty one.
- Change log entries
have expired on the
supplier server since the time of the local backup.
If change log entries have expired, you
need to initiate consumer reinitialization. For more information on
reinitializing consumers, refer to Initializing Consumers.
For information on managing replication,
see 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 this 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.
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
- In the Directory Server Console,
select the Configuration tab, and expand the Data folder in the
navigation tree.
- Select the database
that you want to place in read-only mode, and click the Database
Settings tab in the right pane.
- Select the "Database
is Read-Only"
checkbox.
- 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
