Chapter 6   Migrating From Previous Versions


You can upgrade to iPlanet Directory Server 5.0 from Netscape Directory Server 4.0, 4.1, 4.11, or 4.12. This chapter describes how in the following sections:

• Migration Overview

• Migration Prerequisites

• Identifying Custom Schema

• Migration Procedure

• Migrating a Replicated Site

This chapter does not explain how to upgrade from Innosoft Distributed Directory Server 4.5.1. That process is described in the Innosoft Distributed Directory Server Transition Guide.

Migration Overview

---

Before you migrate your directory service to iPlanet Directory Server 5.0, you should become familiar with the new features offered in this release of the Directory Server.

The migration process is performed by running the migrateInstance5 script on the system where your legacy Directory Server is installed. You must shut down your directory service before running the migration script.

The migration script performs the following tasks in sequence:

• Checks the schema configuration files, and notifies you of any changes between the standard configuration files and the ones present on your system.

• Creates a database for each suffix stored in the legacy Directory Server. (In Directory Server 5.0 you can have multiple databases, but just one suffix per database).

• Migrates the server parameters and database parameters. (In Directory Server 5.0, these are stored as LDAP entries in the dse.ldif file.)

• Migrates user-defined schema objects.

• Migrates indexes.

• Migrates standard server plug-ins.

• Migrates the certificate database, and SSL parameters

The migration script shuts down your legacy Directory Server before performing the migration process. The migration script also backs up your current configuration.

Migration Prerequisites

---

This section lists the prerequisites that your system must meet before you can consider beginning the migration process.

• You must be using Directory Server 4.0, 4.1, 4.11, or 4.12. When you run the migration script, the legacy server process ns-slapd should be stopped.

• Your legacy Directory Server and your new Directory Server 5.0 must be installed on the same host; migration cannot occur over networked drives.

• If you want to continue to run your legacy Directory Server, when you install iPlanet Directory Server 5.0 choose different ports for LDAP traffic and for secured connections from the ones used by your legacy Directory Server.

  If you will not be running your legacy Directory Server, use the same port numbers to ensure that any directory clients that have static configuration information (including directory server port numbers) will continue to work.

• Your iPlanet Directory Server 5.0 must be running when you execute the migration script.

• Any custom schema that you created in your legacy Directory Server must be stored in the slapd.user_oc.conf and slapd.user_at.conf files. If it is not, refer to the procedure described in "Identifying Custom Schema" to move it to those files.

• On UNIX, set the following environment variables:

     PERL5LIB=/usr/iplanet/servers/bin/slapd/admin/bin
     PATH=/usr/iplanet/servers/bin/slapd/admin/bin:$PATH

• On NT, set the following environment variable:

     PERL5LIB=server5root\bin\slapd\admin\bin

  and add server5root/bin/slapd/admin/bin to the PATH environment variable. Replace server5root with the directory under which you installed the Directory Server.

Identifying Custom Schema

---

If you customized the schema in your legacy Directory Server by modifying slapd.at.conf or slapd.oc.conf directly, then the server migration process cannot migrate your custom schema for you. Instead, you are notified during migration that you have modified the standard schema and that you need to manually fix the problem. The migration process then saves a copy of your schema files and uses standard legacy schema files in their place.

While the migration will complete in this situation, you will probably find that you cannot modify your data in Directory Server 5.0. Therefore, you are strongly recommended to copy your custom schema into separate files before you perform the migration. You can use the standard slapd.user_oc.conf and slapd.user_at.conf files or any files declared in slapd.conf with the useroc and userat keywords respectively.

To separate your custom schema from your standard schema:

1. Examine your old slapd.at.conf and slapd.oc.conf files to discover all the schema additions that you made there.

   To ensure that you have properly identified all your changes to standard files, you can compare them with the standard files provided in the /bin/slapd/install/version4 directory. Alternatively, if you have already tried to run the migrateInstance5 script, use the notifications that it issues.

2. Move your custom schema elements to the following files:

   /usr/iplanet/servers/slapd-serverID/config/slapd.user_at.conf and /usr/iplanet/servers/slapd-serverID/config/slapd.user_oc.conf

   These file names are recommended because the 4.x schema configuration editor writes to them. However, you can use any file name you like.

   Note that if there are inheritance relationships between custom defined object classes, you must ensure that in the order in which they appear in the schema configuration file, the superior object class is defined before the others.

3. Include these files into your slapd.conf file using the userat and useroc directives. Place your new directives at the same place in the file as the include statements for other configuration files.

   The order in which the various configuration files are included is not important.

Then, if you added custom attributes to standard object classes in slapd.oc.conf, you must do the following:

4. In the slapd.user_oc.conf file (or your equivalent), create a new object class that includes your custom attributes.

5. Add this new object class to every entry in your directory that uses the custom attributes.

Migration Procedure

---

Before you migrate your server, copy your configuration files to a safe place. The following files contain important configuration information:

• slapd.conf

• dsgw.conf

• Custom schema files, if any.

Once you have backed up your critical configuration information, do the following to migrate a server to 5.0:

1. Stop your legacy Directory Server.

   
   

   ---

   Note	If you do not stop the legacy Directory Server, the migration script does it for you.

   ---

   
   

2. On the machine where your legacy Directory Server is installed, install a new 5.0 Directory Server.

   The installation process is described in Chapter 3 "Using Express and Typical Installation," or Chapter 4 "Silent Installation."

   Use a different port number from your legacy production server if you plan to continue to run your legacy Directory Server. Use the same port numbers as your legacy production server if you want to ensure that any directory clients that have static configuration information (including directory server port numbers) will continue to work.

3. Run the migration script. As root user (UNIX), or administrator (on NT), change directory to /usr/iplanet/servers/bin/slapd/admin/bin. Then enter the following command:

   On UNIX:

   migrateInstance5 -D rootDN -w passwd -p port -o server4ID -n server5ID

   ON NT:

   perl migrateInstance5 -D rootDN -w passwd -p port -o server4ID -n server5ID

   where:

   • rootDN is the DN for Directory Manager in Directory Server 5.0

   • passwd is the password for Directory Manager in Directory Server 5.0

   • port is the LDAP port number in Directory Server 5.0

   • server4ID is the path to the legacy Directory Server directory (for example, /usr/netscape/server4/slapd-serverID)

   • server5ID is the path to the Directory Server 5.0 directory (for example, /usr/iplanet/servers/slapd-serverID)

   The following is an example of an actual command on UNIX:

   migrateInstance5 -D "cn=Directory Manager" -w secret -p 1389 -o /usr/netscape/server4/slapd-coolwave -n /usr/iplanet/servers/slapd-coolwave

   The following is an example of an actual command on NT:

   perl migrateInstance5 -D "cn=Directory Manager" -w secret -p 1389 -o /usr/netscape/server4/slapd-coolwave -n /usr/iplanet/servers/slapd-coolwave

4. Provide a path and filename for your backup directory, or accept the default.

   The following is an extract of the script's output:

   Parse the configuration file: /space/iPlanet/server4_11/slapd-coolwave/config/slapd.conf...

   Suffix o=France.Sun.COM doesn't exist

   Backend: MigratedDB_0 has been created !!!

   Suffix dc=coolwave,dc=France,dc=Sun,dc=COM doesn't exist

   Backend: MigratedDB_1 has been created !!!

   For the suffix o=NetscapeRoot, we do nothing

   Suffix dc=radius.fr doesn't exist

   Backend: MigratedDB_2 has been created !!!

   Update general server parameters...

   Update successfully passwordHistory

   Update global LDBM parameters...

   Update successfully nsslapd-mode

   Update specific backend parameters...

   Migrate DSE entries...

   Migrate attributes...

   Migrate objectclasses...

   Migrate indexes...

   Migrate plugin's...

Your legacy Directory Server is then migrated. As a result of this migration, a new Directory Server 5.0 instance is installed using the configuration information obtained from your legacy Directory Server. In addition, the data from your old server is migrated to the new server and the new server is started.

Migrating a Replicated Site

---

This section describes the migration path that you can follow to migrate a replication topology of 4.x servers to a replication topology of 5.0 directory servers.

You can migrate instances of Directory Server 4.0, 4.1, 4.11, and 4.12 because these releases of the Directory Server can replicate to a Directory Server 5.0 configured as a consumer.

The constraints, approach, and a summary of the steps involved in migrating a replicated environment are provided below.

Constraints

The following constraints must be observed in order to successfully complete the migration of a replicated environment:

• The replication topology of legacy servers must be a valid topology.

• The new 5.0 Directory Server must be a consumer of a 4.x Directory Server.

• The 5.0 Directory Server must be configured as a legacy consumer.

• The replication agreement between the 4.x supplier server and the 5.0 consumer server must be a 4.x supplier-initiated replication agreement.

Approach

Given the constraints, the approach to migrating a replication topology of 4.x servers is to:

1. Install the 5.0 Directory Server, configure it both:
   • As a read-write replica that logs changes (the role the server will fulfill once the migration process is completed)

   • As a legacy consumer, (the role the server must play during the migration process)

2. Configure the 4.x supplier to send updates to the 5.0 Directory Server.

3. Upgrade 4.x consumer servers to Directory Server 5.0, and change their supplier server to be the Directory Server 5.0 that you configured in Step 1.

   This Directory Server now acts as a hub supplier.

4. Retire the 4.x supplier.

   The Directory Server 5.0 that you configured in Step 1 is now the only supplier in the topology.

Example: Detail of Steps

Consider a fairly simple replication topology:

• One supplier Server A

• Two consumer servers Server B and Server C

• Server A has a supplier-initiated replication agreement to Server B and to Server C

• Servers A, B, and C are 4.0, 4.1, 4.11, or 4.12 directory servers.

  
  

  ---

  Note	You can migrate a topology where Server B and Server C have CIR replication agreements with Server A. However, you cannot have CIR agreements in the new replication environment because Directory Server 5.0 does not support consumer-initiated replication.

  ---

  
  

To migrate this topology, follow these steps:

1. Install iPlanet Directory Server 5.0 on a new server, Server D.

2. Configure Server D for the role it will fulfill in the migrated replication topology, that is as a read-write replica that logs changes.

   This procedure is explained in the Replication chapter in the iPlanet Directory Server Administrator's Guide.

3. Then configure Server D to be a legacy consumer.

   This procedure is explained in the Replication chapter in the iPlanet Directory Server Administrator's Guide.

4. Upgrade Server B to iPlanet Directory Server 5.0, following the instructions given in the iPlanet Directory Server Installation Guide.

5. Make Server B a read-only replica of Server D.

   This means that Server D is now a hub supplier: it receives updates from Server A, and in turn updates Server B.

6. Upgrade Server C to iPlanet Directory Server 5.0, and make it a read-only replica of Server D.

7. Retire Server A. Disable legacy consumer settings on server D.

   This leaves Server D as the single supplier for consumer servers B and C.

When you have completed the migration of your replication topology, you can evolve it to use multi-master replication. To do this, you must add a new iPlanet Directory Server 5.0 that acts as a master to your replication topology. You cannot change one of the read-only replicas to become a read-write replica.

For more information on multi-master replication topologies, refer to the iPlanet Directory Server Administrator's Guide.