Modifying the Replication Topology

This section explains these aspects of managing an existing replication topology:

• Changing the Replication Manager

• Managing Replication Agreements

• Promoting or Demoting Replicas

• Disabling a Replicated Suffix

• Keeping Replicated Suffixes Synchronized

Changing the Replication Manager

You can edit a replication agreement to change the replication manager identity that is used to bind to the consumer server. To avoid any interruption of the replication, you should define the new replication manager entry or certificate entry on the consumer before modifying the replication agreement. However, if replication is interrupted due to a bind failure, the replication mechanism will automatically send all the necessary updates when you correct the error, within the limits of the replication recovery settings. For the procedure, see Using a Non-Default Replication Manager.

Managing Replication Agreements

You can disable, enable, or delete a replication agreement.

Disabling a Replication Agreement

When a replication agreement is disabled, the master stops sending updates to the designated consumer. Replication to that server is stopped, but all settings in the agreement are preserved. You may resume replication by re-enabling the agreement at a later time. See Enabling a Replication Agreement for information about resuming the replication mechanism after an interruption.

To Disable a Replication Agreement

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

• Disable a replication agreement.

  $ dsconf disable-repl-agmt -h host -p port suffix-DN consumer-host:consumer-port

  For example:

  $ dsconf disable-repl-agmt -h host2 -p 1389 dc=example,dc=com host1:1389

Enabling a Replication Agreement

Enabling a replication agreement resumes replication with the designated consumer. However, if replication has been interrupted longer than the replication recovery settings allow and the consumer was not updated by another supplier, you must reinitialize the consumer. The replication recovery settings are the maximum size and age of this supplier’s change log and the purge delay of the consumer (see To Perform Advanced Consumer Configuration).

When the interruption is short and replication can recover, the master will update the consumer automatically when the agreement is re-enabled.

To Enable a Replication Agreement

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

• Enable a replication agreement.

  $ dsconf enable-repl-agmt -h host -p port suffix-DN consumer-host:consumer-port

  For example:

  $ dsconf enable-repl-agmt -h host2 -p 1389 dc=example,dc=com host1:1389

Deleting a Replication Agreement

Deleting a replication agreement stops the replication to the corresponding consumer and removes all configuration information about the agreement. If you want to resume replication at a later date, disable the agreement instead, as described in Disabling a Replication Agreement.

To Delete a Replication Agreement

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

• Delete a replication agreement.

  $ dsconf delete-repl-agmt -h host -p port suffix-DN consumer-host:consumer-port

  For example:

  $ dsconf delete-repl-agmt -h host2 -p 1389 dc=example,dc=com host1:1389

Promoting or Demoting Replicas

Promoting or demoting a replica changes its role in the replication topology. Dedicated consumers can be promoted to hubs, and hubs can be promoted to masters. Masters can be demoted to hubs, and hubs can also be demoted to dedicated consumers. However, masters cannot be demoted directly to consumers, just as consumers cannot be promoted directly to masters.

The allowed promotions and demotions within the multimaster replication mechanism make the topology very flexible. A site that was formerly served by a consumer replica might grow and require a hub with several replicas to handle the load. If the load includes many modifications to the replica contents, the hub can become a master to allow faster local changes that can then be replicated to other masters at other sites.

When promoting or demoting replicas, be aware of the following:

• If you promote a consumer, it becomes a hub. If you promote a hub, it becomes a master. You cannot promote a server directly from consumer to master. You must first promote the consumer to a hub, then promote the hub to a master. Likewise, when demoting a master to a consumer, you must demote the master to a hub before demoting from a hub to a consumer.

• When demoting a master to a hub, the replica will become read-only and be configured for sending referrals to the remaining masters. The new hub will retain all of its consumers, whether hubs or dedicated consumers.

• Demoting a single master to a hub will create a topology without a master replica. Directory Server will allow you to do this under the assumption that you will define a new master. However, it is better to add a new master as a multimaster and allow it to be initialized before demoting the other master.

• Before demoting a hub to a consumer, you must disable or delete all replication agreements to and from the hub. If you do not do this, the demote operation will fail with this error: LDAP_OPERATIONS_ERROR “Unable to demote a hub to a read-only replica if some agreements are enabled”.

  If the hub’s consumers were not updated by other hubs or masters, they will no longer be updated. You should create new agreements on the remaining hubs or masters to update these consumers.

• When promoting a consumer to a hub, its change log is enabled, and you may define new agreements with consumers.

• When promoting a hub to a master, the replica will accept modification requests, and you may define new agreements with other masters, hubs, or dedicated consumers.

To Promote or Demote a Replica

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

• Promote or demote a replica by using one of the commands:

  dsconf promote-repl [-d REPL_ID] SUFFIX_DN [SUFFIX_DN...]

  $ dsconf promote-repl -h host -p port [-d REPL_ID] SUFFIX_DN [SUFFIX_DN...]

  $ dsconf demote-repl -h host -p port SUFFIX_DN [SUFFIX_DN...]

Disabling a Replicated Suffix

Disabling a replicated suffix removes it from the replication topology. It will no longer be updated or send updates, depending on its role as a master, hub, or consumer. Disabling a suffix on a supplier server deletes all replication agreements, and they will have to be recreated if the replica is enabled again.

To Disable a Replicated Suffix

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

• Disable a replicated suffix.

  $ dsconf disable-repl -h host -p port suffix-DN

  For example:

  $ dsconf disable-repl -h host2 -p 1389 dc=example,dc=com

Keeping Replicated Suffixes Synchronized

After you stop a Directory Server involved in replication for regular maintenance, when it comes back online, you need to ensure that it gets updated through replication immediately. In the case of a master in a multimaster environment, the directory information needs to be updated by another master in the multimaster set. In other cases, after a hub server or a dedicated consumer server is taken offline for maintenance, when they come back online, they need to be updated by the master server.

This section describes the replication retry algorithm and explains how to force replication updates to occur without waiting for the next retry.

Replication Retry Algorithm

When a source replica is unsuccessful in replicating to a destination, it retries periodically in incremental time intervals. The retry intervals depend on the error type.

Note that even if you have configured replication agreements to always keep the source replica and the destination replica synchronized, this is not sufficient to immediately update a replica that has been offline for over five minutes.

To Force Replication Updates

If replication has stopped, you can force replication updates to the destination suffixes.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

• On the source server, restart replication updates to the destination server.

  $ dsconf update-repl-dest-now -h host -p port suffix-DN destination-host:destination-port

  For example:

  $ dsconf update-repl-dest-now -h host2 -p 1389 dc=example,dc=com host1:1389

Moving a Master Replica to a New Machine

In some situations, it might be necessary to move a master replica to a different machine. If you do not need to use the same host name and port number, use dsconf change-repl-dest to change the host name and port number of the remote replica. For more information, see To Change the Destination of a Replication Agreement.

If you need to retain the same host name and port number, you must remove the master from the existing topology, and then re-add the master to the topology.

It is much easier to use DSCC to perform these tasks, because DSCC takes care of any impacted replication agreements. If you use DSCC, however, you cannot specify the same replica ID that the master originally had in the topology. To use the same replica ID, you must use the command line to perform these tasks, as follows.

To Remove a Master From an Existing Replication Topology

Before You Begin

Make sure that all changes from the master have already been replicated.

1. If you can, back up the master using binary copy so that you do not lose any changes.
2. Demote the master replica to a hub replica.

   See Promoting or Demoting Replicas.

3. Wait for the hub to start replicating to other servers.

   When the hub opens a replication session to the other servers in the topology, it remains in the RUV but is no longer used in referrals.

4. Stop the hub.

   See Starting, Stopping, and Restarting a Directory Server Instance.

5. Remove the hub from the topology.

   See Disabling a Replicated Suffix.

To Add a Master to an Existing Replication Topology

1. Add the master replica, using the same replica ID.

   See Enabling Replication on a Master Replica.

2. Recreate the replication agreements from that master to the other replicas in the topology.
3. Initialize the new master.
   1. If you were able to back up the master, initialize the master from this backup.
   2. If you were not able to back up the master (in the event of a machine crash), initialize the master from another master in the topology.