Chapter 4 Upgrading and Migrating Data for a Single Directory Server Installation

This chapter describes the full upgrade process for converting a single existing server installation to the current version. Follow the instructions in the procedures described here only if you must perform full upgrade, as opposed to patch upgrade.



Note	If an existing 4.x server uses custom schema, ensure the migration script can find the custom schema before migrating any data. Read (From 4.x) Handling Custom Schema for details. If the migration script does not recognize the custom schema, it does not migrate the schema, but instead applies standard schema files after migrating the data to the new server. Applying the standard schema to entries that conform to custom schema may render modifications impossible, thereby making the upgraded directory read-only.

Installing the New Server

(From 4.x) Handling Custom Schema

Migrating Existing Data

(From 4.x) Creating Replication Agreements

(Optional) Reusing the Existing Port Number

Installing the New Server


Note	Ensure you have a current backup of the existing server before installing the new server.

The new server must reside in a different installation location than the existing server. It must also be identified by a different serverID.

Although you may choose to reuse most of the configuration information supplied for the original installation, do not reuse the existing port number. Instead, you may change the port number of the new server after migrating existing data.

(From 4.x) Handling Custom Schema

The script provided for migrating data recognizes only those custom schema either placed in the standard slapd.user_oc.conf and slapd.user_at.conf files, or placed in other files and included in slapd.conf using useroc and userat directives. If, for example, custom schema are included directly in slapd.at.conf or slapd.oc.conf, the migration script does not recognize them.

Compare slapd.at.conf or slapd.oc.conf with the standard files provided under ServerRoot/bin/slapd/install/version4/ of the new server, transcribing custom schema elements to slapd.user_oc.conf and slapd.user_at.conf files.

If the custom object classes have inheritance relationships, ensure that superior object classes precede others in the schema configuration file.

If custom attributes were added to standard object classes in slapd.oc.conf, create a new object class including the attributes in slapd.user_oc.conf, and add the new object class to every entry in the existing directory that uses the custom attributes.

Include the slapd.user_oc.conf and slapd.user_at.conf files in the slapd.conf file for the existing server using the useroc and userat directives, placing the new directives adjacent to include statements for other files.

At this point, all custom schema used by the existing server should reside in slapd.user_oc.conf or slapd.user_at.conf, and slapd.conf should include the files using the useroc and userat directives.

Migrating Existing Data

After handling custom schema, perform the following steps to migrate existing data to a new server.

If you intend to initialize replication on the new Directory Server offline from files, obtain the files before proceeding.

Refer to the Directory Server Administration Guide for instructions on exporting Directory Server data.

Ensure the new Directory Server is running.

Work as a user having the right to start, stop, and run database export and import on both the old and new servers.

For example, become super user.

Set environment variables as shown in Table 4-1.

Table 4-1 Environment Variables for Migration
Variable	Value
PATH	ServerRoot/bin/slapd/admin/bin:$PATH
PERL5LIB	ServerRoot/bin/slapd/admin/bin

Run the migration script under the new server instance:

# cd ServerRoot/bin/slapd/admin/bin
# perl migrateInstance5 -p port52 -D "cn=directory manager" -w password -o oldServ -n newServ

Here, oldServ represents the full path to the old server instance, such as /usr/iplanet/servers/slapd-ldap or /usr/iplanet/ds5/slapd-ldap, and newServ represents the full path to the new server instance, such as /var/opt/mps/serverroot/slapd-dirserv.

The script generates output as it proceeds. You may choose to redirect this output to a file for review after migration completes.

(From 4.x) Creating Replication Agreements

If an existing 4.x server is involved in replication, upgrading involves recreating replication agreements after migrating data. Read Chapter 5, "Migrating a Replicated 4.x Topology" before proceeding with the upgrade process.

(Optional) Reusing the Existing Port Number

After migrating data from the old server to the new, you may choose to retire the old server and have the new server listen on the same port as the old. Using the same port may allow client applications to continue operating without changing their configurations.

Refer to the Directory Server Administration Guide for instructions on changing the server port. Be sure to stop the old server before the new server starts to listen on the old port.

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