Previous     Contents     Index     DocHome     Next     
iPlanet Directory Server 5.1 Installation Guide



Chapter 6   Migrating From Previous Versions


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

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.1, 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 and 5.1 you can have multiple databases, but just one suffix per database).

  • Migrates the server parameters and database parameters. (In Directory Server 5.0 and 5.1, 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

  • Migrates database links

  • Migrates replication entries (replicas, replication agreement entries, bind dn entries, change log)

  • Migrates the SNMP configuration

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, 4.12, 4.13, or 5.0. 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.1 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.1 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.1 must be running when you execute the migration script.

  • Any custom schema that you created in a legacy 4.x Directory Server must be stored in the default files or included using an include statement in the slapd.conf file. The default files for custom schema are slapd.user_oc.conf and slapd.user_at.conf files in Directory Server 4.x. If you have custom schema that is not stored in those files, refer to the procedure described in "Identifying Custom Schema" to move it to those files.

  • Any custom schema that you created in a 5.0 Directory Server must be stored in an LDIF file in the /usr/iplanet/servers/slapd-serverID/config/schema directory.

  • 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.1. 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:

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

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



Migration Procedure

The migration script will automatically back up your Directory Server configuration.

If you are migrating from Directory Server 4.x, all the files in the /usr/netscape/server4/slapd-serverID/config directory are backed up to /usr/netscape/server4/slapd-serverID/config_backup.

If you are upgrading from Directory Server 5.0, all the files in the /usr/iplanet/servers/slapd-serverID/config directory are backed up to /usr/iplanet/servers/slapd-serverID/config_backup.

If your configuration files are stored in non-default locations, before you migrate your server, copy them to a safe place.

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

  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.1 Directory Server.

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

    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 oldServerPath -n newServerPath

    or:

    migrateInstance5 -D rootDN -j passwdFile -p port -o oldServerPath -n newServerPath

    ON NT:

    perl migrateInstance5 -D rootDN -w passwd -p port -o oldServerPath -n newServerPath

    or:

    perl migrateInstance5 -D rootDN -j passwdFile -p port -o oldServerPath -n newServerPath

    where:

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

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

    • passwdFile is the file containing the password for Directory Manager in Directory Server 5.1

    • port is the LDAP port number in Directory Server 5.1

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

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

    The following is an example of a command you would use on a UNIX machine to migrate a 4.11 Directory Server to Directory Server 5.1:

    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 the same command on an NT machine:

    perl 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 a command you would use on a UNIX machine to migrate a 5.0 Directory Server to Directory Server 5.1:

    migrateInstance5 -D "cn=Directory Manager" -w secret -p 1389 -o /usr/iPlanet/DS50/slapd-migrate -n /usr/iPlanet/DS51/slapd-migrate

    The following is an example of the same command on an NT machine:

    perl migrateInstance5 -D "cn=Directory Manager" -w secret -p 1389 -o /usr/iPlanet/DS50/slapd-migrate -n /usr/iPlanet/DS51/slapd-migrate

  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...

    The following is an extract of the script's output when migrating a 5.0 Directory Server to a 5.1 Directory Server:

    Shutting down server slapd-migrate . . .

    Backup /usr/iplanet/DS51/slapd-migrate/config on /usr/iplanet/DS51/slapd-migrate/config_backup ...

    Migrate the schema...

    Connected to 5.1 LDAP server

    Parse the old DSE ldif file: /usr/iplanet/DS50/slapd-migrate/config/dse.ldif

    Migrate DSE entries...

    Migrate LDBM backend instances...

    Migrate default indexes...

    Migrate indexes...

    Migrate replicas...

    Migrate replication agreements...

    Migrate key/cert databases...

    Migrate Certmap.conf...

    ***** Close the LDAP connection to the 5.1 Directory Server instance *****

    Shutting down server slapd-migrate . . .

    ***** Migrate ReplicaBindDN entries...

    ***** Migrate MultiplexorBindDN entries...

    ****** End of migration ******

Your legacy Directory Server is then migrated. As a result of this migration, a new Directory Server 5.1 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


If you are upgrading from Directory Server 5.0 to Directory Server 5.1, your replication configuration is automatically migrated when you run the migrateInstance5 script.

The manual procedure described in this section explains the migration path that you can follow to migrate a replication topology of 4.x servers to a replication topology of 5.1 directory servers.

You can migrate instances of Directory Server 4.0, 4.1, 4.11, 4.12, and 4.13 because these releases of the Directory Server can replicate to a Directory Server 5.1 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.x Directory Server must be a consumer of a 4.x Directory Server.

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

  • The replication agreement between the 4.x supplier server and the 5.x 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.1 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.1 Directory Server.

  3. Upgrade 4.x consumer servers to Directory Server 5.1, and change their supplier server to be the Directory Server 5.1 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.1 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.1 does not support consumer-initiated replication.


To migrate this topology, follow these steps:

  1. Install iPlanet Directory Server 5.1 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.1, 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.1, 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.1 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.


Previous     Contents     Index     DocHome     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated October 29, 2001