Sun Java System Directory Server Enterprise Edition 6.2 Migration Guide

Chapter 4 Migrating a Replicated Topology

Directory Server Enterprise Edition 6.2 does not provide a way to migrate an entire replicated topology automatically. Migrating a replicated topology involves migrating each server individually. Usually, however, you should be able to migrate your entire topology without any interruption in service.

This chapter describes the issues involved in migrating replicated servers, and covers the following topics:

Overview of Migrating Replicated Servers

Directory Server 6.2 supports an unlimited number of masters in a multi-master topology. This and other changes might mean that you redesign your topology rather than migrate to an identical topology with new servers. See Part III, Logical Design, in Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide before continuing.

When migrating replicated version 5 servers, you typically start with the consumers, continue with the hubs, and finish with the masters. This bottom-up approach involves interrupting only one server at a time, rather than interrupting an entire branch of the replication topology. The approach also helps you avoid potential custom schema synchronization issues between masters and consumers.

Issues Related to Migrating Replicated Servers

Depending on your replication topology, and on your migration strategy, certain issues might arise when you migrate replicated servers. These issues are described in the following sections.

Issues With the New Password Policy

If you are migrating a multi-master replicated topology, a situation will arise where a 6.2 master is replicating to a version 5 server. In this situation, an object class violation will occur if changes are made to the new password policy attributes on the 6.2 server, and replicated to the version 5 server. The password policy attributes are managed internally by the server but they might be updated in the event of a bind, a user password modify, or the addition of an entry with the userpassword attribute.

To avoid the object class violation, the 6.2 password policy schema file (00ds6pwp.ldif) must be copied to every version 5 server that will be supplied by a 6.2 master. When the password policy schema file has been copied, restart the version 5 server.

Migration of Replication Agreements

If possible, you should migrate replicated servers to the same host name and port number. If you must change the host name or port number of a replicated server, all replication agreements that point to that server must be updated manually to point to the new server. For example, if you migrate a consumer server from red.example.com:1389 to blue.example.com:1389, the replication agreements on all masters that point to red.example.com:1389 must be updated manually to point to blue.example.com:1389.

Replication agreements from the migrated master to consumers in the topology are managed by the dsmig migration tool. If your topology does not support automated migration, these replication agreements must also be updated manually.

Migration of Referrals

Referrals are also affected if you migrate a master replica to a new host or port. The details of each master in a topology are present in the Replica Update Vector (RUV) of all other servers in the topology. The RUV of each server is used to determine the referrals. When you change the host name or port number of a master server during migration, all referrals to that master from other servers in the topology become invalid. The easiest way to correct this is to use the following steps, in order, when performing the migration.

Before migrating a master server, verify that there are no pending changes to be replicated. You can use the insync tool to do this.
Demote the master server to a hub, as described in Promoting or Demoting Replicas in Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide.
Migrate the hub server, either using dsmig or the manual migration progress.
Promote the hub server to a master, as described in Promoting or Demoting Replicas in Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide. When you promote the hub, you must assign a replicaID to the new migrated master. This new replicaID must be different to the replicaID of the old server that is being migrated, and must be unique within the replicated topology.

Manual Reset of Replication Credentials

dsmig does not migrate the password of the default replication manager entry (cn=replication manager,cn=replication,cn=config). Instead, the replication manager password is deleted. Therefore, whether you are using manual or automatic migration, you must reset the replication manager password manually.

To reset the replication manager password, use the following command:

$ dsconf set-server-prop -h host -p port def-repl-manager-pwd-file:filename

In addition, dsmig does not migrate non-default replication manager entries. If a version 5 replica uses an entry other than the default replication manager, and if this entry is under cn=config, you must add the default replication manager manually. Please refer to the documentation to add a non-default replication manager entry manually. For information about adding a non-default replication manager, see Using a Non-Default Replication Manager in Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide.

Problems Related to Tombstone Purging

In some cases, after migrating a replicated topology you might experience problems related to tombstone purging. In some cases, tombstone entries are not purged when they should be. This problem can be resolved by re-indexing the objectclass attribute of the corresponding suffix.

New Replication Recommendations

Directory Server 6.2 does not limit the number of masters in a multi-master topology. A fully-meshed, multi-master topology with no hubs or consumers is recommended in most cases.

Advantages of an all-master topology include the following:

Availability. Write traffic is never disrupted if one of the servers goes down.
Simplicity. In an all-master topology, there is no need to set up referrals to route reads and writes to different servers.

There may be reasons that an all-master topology is not viable in a specific deployment. For example, fractional replication cannot be used in an all-master topology because fractional replication is only supported from masters to consumers.

Migration Scenarios

This section provides sample migration scenarios for a variety of replicated topologies.

Migrating a Replicated Topology to an Identical Topology

Before you start migrating replicated servers, determine whether your deployment might not be better served by changing the architecture of the topology. This section describes how to migrate if you want to keep your existing topology. Migrating a replicated topology to an identical topology, involves migrating the consumers, then the hubs, then the masters. The following sections demonstrate a sample migration of a simple multi-master topology.

Migrating the Consumers

For each consumer in the replicated topology:

Reroute clients to another consumer in the topology.
Disable any replication agreements to the consumer you want to migrate.
Stop the consumer.
Migrate the consumer according to the instructions under Chapter 1, Overview of the Migration Process for Directory Server.
Start the consumer.
Enable the replication agreements from the hubs to that consumer.
If you have migrated the data, check that replication is in sync.
If you have not migrated the data, reinitialize the consumer.
Reroute clients back to the consumer.

The following sequence of diagrams illustrate the migration of a consumer, as described above. The first diagram shows the version 5 topology before the migration.

Figure 4–1 Existing version 5 Topology

Figure shows basic multi-master topology

The first step involves rerouting clients and disabling replication agreements, effectively isolating the consumer from the topology.

Figure 4–2 Isolating the Consumer From the Topology

Figure shows consumer removed from topology

The next step involves migrating the version 5 consumer.

Figure 4–3 Migrating the version 5 Consumer

The next step involves enabling the replication agreements to the new consumer, initializing the consumer if necessary, and rerouting client applications to the new consumer.

Figure 4–4 Placing the 6.0 Consumer Into the Topology

Figure shows topology with one migrated consumer

Migrating the Hubs

For each hub in the replicated topology:

Disable replication agreements from the masters to the hub you want to migrate.
Disable replication agreements from the hub you want to migrate to the consumers.
Stop the hub.
Migrate the hub according to the instructions under Chapter 1, Overview of the Migration Process for Directory Server.
Start the hub.
Enable the replication agreements from the masters to that hub.
Enable the replication agreements from that hub to the consumers.
If you have migrated the data, check that replication is in sync.
If you have not migrated the data, reinitialize the hub.

The following sequence of diagrams illustrate the migration of a hub, as described above. The first diagram shows the topology before migrating the hubs.

Figure 4–5 Existing version 5 Topology With Migrated Consumers

Figure shows basic multi-master topology with migrated
consumers

The first migration step involves disabling replication agreements, effectively isolating the hub from the topology.

Figure 4–6 Isolating the Hub From the Topology

The next step involves migrating the version 5 hub.

Figure 4–7 Migrating the version 5 Hub

The next step involves enabling the replication agreements to the new hub and initializing the hub if necessary.

Figure 4–8 Placing the 6.0 Hub Into the Topology

Figure shows topology with migrated consumers and hub

Check that the replication on the consumers is in sync with the rest of the topology before migrating another hub. A server that has just been migrated does not have a change log, and can therefore not update consumer servers that are out of sync. Allow the topology to stabilize and all servers to synchronize before migrating the next supplier server.

Migrating the Masters

For each master in the replicated topology:

If you have client applications that write to the master you want to migrate, reroute these applications to write to another master in the topology.
Ensure that the master is no longer receiving write requests. You can do this by enabling read-only mode on the master.
Check that replication is synchronized between the master and all its consumers.

Migration of the change log is not supported if you are migrating manually, so the preceding two steps are mandatory in this case. Although automatic migration does migrate the change log, you should still perform the above steps to avoid the risk of losing changes.
Disable any replication agreements to and from the master you want to migrate.
Stop the master.
Migrate the master according to the instructions under Chapter 1, Overview of the Migration Process for Directory Server.
Start the master.
Enable the replication agreements from the master to the hubs and other masters in the topology.
If you have migrated the data, check that replication is in sync.
If you have not migrated the data, reinitialize the master from another master in the topology.
If you rerouted client applications (Step 2), you can now route the applications to write to the migrated master.

The following sequence of diagrams illustrate the migration of a master, as described above. The first diagram shows the version 5 topology before the migration of the masters.

Figure 4–9 Existing version 5 Topology With Consumers and Hubs Migrated

Figure shows basic multi-master topology with 6.0 consumers
and hubs

The first step in migrating a master involves disabling replication agreements, effectively isolating the master from the topology.

Figure 4–10 Isolating the Master From the Topology

Figure shows master removed from topology

The next step involves migrating the version 5 master.

Figure 4–11 Migrating the version 5 Master

The next step involves enabling the replication agreements to and from the new master and initializing the master if necessary.

Figure 4–12 Placing the 6.0 Master Into the Topology

Figure shows topology with one migrated master

Check that the replication on all hubs and consumers is in sync with the rest of the topology before migrating another master. A server that has just been migrated does not have a change log, and can therefore not update servers that are out of sync. Allow the topology to stabilize and all servers to synchronize before migrating the next supplier server.

Migrating a Replicated Topology to a New Topology

Before you start migrating replicated servers, determine whether your deployment might not be better served by changing the architecture of the topology. This section describes how to migrate a basic version 5 topology to a new all-master topology. Migrating to an all-master topology involves migrating the consumers, hubs, and masters, then promoting the hubs to masters and the consumers to hubs, then to masters. The following sections demonstrate a sample migration of a simple multi-master topology to a new all-master topology.

The following figure shows the existing version 5 topology.

Figure 4–13 Existing version 5 Topology

Figure shows existing version 5 topology

Migrating All the Servers

The first step is to migrate all the servers individually, as described in Migrating a Replicated Topology to an Identical Topology. The resulting topology is illustrated in the following figure.

Figure 4–14 Existing Topology With Migrated Servers

Figure shows existing topology with 6.0 servers

Promoting the Hubs

The next step involves promoting the hubs to masters, and creating a fully-meshed topology between the masters. To promote the hubs, follow the instructions in Promoting or Demoting Replicas in Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide.

The following diagram illustrates the topology when the hubs have been promoted.

Figure 4–15 Migrated Topology With Promoted Hub Replicas

Figure shows migrated topology with four masters and
two consumers

Promoting the Consumers

The next step involves promoting the consumers to hubs, and then to masters, and creating a fully-meshed topology between the masters. To promote the consumers, follow the instructions in Promoting or Demoting Replicas in Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide.

The following diagram illustrates the topology when the consumers have been promoted.

Figure 4–16 New Fully-Meshed All-Master Topology

Figure shows new migrated topology with six fully-meshed
masters

Migrating Over Multiple Data Centers

Migrating servers over multiple data centers involves migrating each server in each data center individually. Before you start migrating replicated servers, determine whether your deployment might not be better served by changing the architecture of the topology. If you want to keep your existing topology, follow the examples in Migrating a Replicated Topology to an Identical Topology for each data center. To migrate to a new topology, follow the examples in Migrating a Replicated Topology to a New Topology for each data center.