D.3. Managing Replicas and Replication Agreements

This chapter provides details on replication agreements and describes how to manage them.

Note

For guidelines on setting up additional replication agreements, see Section 4.2.2, “Replica Topology Recommendations”.

D.3.1. Explaining Replication Agreements

Replicas are joined in a replication agreement that copies data between them. Replication agreements are bilateral: the data is replicated from the first replica to the other one as well as from the other replica to the first one.

Note

An initial replication agreement is set up between two replicas by the ipa-replica-install script. See Chapter 4, Installing and Uninstalling Identity Management Replicas for details on installing the initial replica.

Types of Replication Agreements

Identity Management supports the following three types of replication agreements:
  • Replication agreements to replicate directory data, such as users, groups, and policies. You can manage these agreements using the ipa-replica-manage utility.
  • Replication agreements to replicate certificate server data. You can manage these agreements using the ipa-csreplica-manage utility.
  • Synchronization agreements to replicate user information with an Active Directory server. These agreements are not described in this guide. For documentation on synchronizing IdM and Active Directory, see the Windows Integration Guide.
The ipa-replica-manage and ipa-csreplica-manage utilities use the same format and arguments. The following sections of this chapter describe the most notable replication management operations performed using these utilities. For detailed information about the utilities, see the ipa-replica-manage(1) and ipa-csreplica-manage(1) man pages.

D.3.2. Listing Replication Agreements

To list the directory data replication agreements currently configured for a replica, use the ipa-replica-manage list command:
  1. Run ipa-replica-manage list without any arguments to list all replicas in the replication topology. In the output, locate the required replica: 
    $ ipa-replica-manage list
server1.example.com: master
server2.example.com: master
server3.example.com: master
server4.example.com: master
  2. Add the replica's host name to ipa-replica-manage list to list the replication agreements. 
    $ ipa-replica-manage list server1.example.com
server2.example.com: replica
server3.example.com: replica
    The output displays the replicas to which server1.example.com sends updates.
To list certificate server replication agreements, use the ipa-csreplica-manage list command.

D.3.3. Creating and Removing Replication Agreements

Creating Replication Agreements

To create a new replication agreement, use the ipa-replica-manage connect command: 
$ ipa-replica-manage connect server1.example.com server2.example.com
The command creates a new bilateral replication agreement going from server1.example.com to server2.example.com and from server2.example.com to server1.example.com.
If you only specify one server with ipa-replica-manage connect, IdM creates a replication agreement between the local host and the specified server.
To create a new certificate server replication agreement, use the ipa-csreplica-manage connect command.

Removing Replication Agreements

To remove a replication agreement, use the ipa-replica-manage disconnect command: 
$ ipa-replica-manage disconnect server1.example.com server4.example.com
This command disables replication from server1.example.com to server4.example.com and from server4.example.com to server1.example.com.
The ipa-replica-manage disconnect command only removes the replication agreement. It leaves both servers in the Identity Management replication topology. To remove all replication agreements and data related to a replica, use the ipa-replica-manage del command, which removes the replica entirely from the Identity Management domain. 
$ ipa-replica-manage del server2.example.com
To remove a certificate server replication agreement, use the ipa-csreplica-manage disconnect command. Similarly, to remove all certificate replication agreements and data between two servers, use the ipa-csreplica-manage del command.

D.3.4. Initiating a Manual Replication Update

Data changes between replicas with direct replication agreements between each other are replicated almost instantaneously. However, replicas that are not joined in a direct replication agreement do not receive updates as quickly.
In some situations, it might be necessary to manually initiate an unplanned replication update. For example, before taking a replica offline for maintenance, all the queued changes waiting for the planned update must be sent to one or more other replicas. In this situation, you can initiate a manual replication update before taking the replica offline.
To manually initiate a replication update, use the ipa-replica-manage force-sync command. The local host on which you run the command is the replica that receives the update. To specify the replica that sends the update, use the --from option. 
$ ipa-replica-manage force-sync --from server1.example.com
To initiate a replication update for certificate server data, use the ipa-csreplica-manage force-sync command.

D.3.5. Re-initializing a Replica

If a replica has been offline for a long period of time or its database has been corrupted, you can re-initialize it. Re-initialization is analogous to initialization, which is described in Section 4.5, “Creating the Replica: Introduction”. Re-initialization refreshes the replica with an updated set of data. Re-initialization can, for example, be used if an authoritative restore from backup is required.

Note

Waiting for a regular replication update or initiating a manual replication update will not help in this situation. During these replication updates, replicas only send changed entries to each other. Unlike re-initialization, replication updates do not refresh the whole database.
To re-initialize a data replication agreement on a replica, use the ipa-replica-manage re-initialize command. The local host on which you run the command is the re-initialized replica. To specify the replica from which the data is obtained, use the --from option: 
$ ipa-replica-manage re-initialize --from server1.example.com
To re-initialize a certificate server replication agreement, use the ipa-csreplica-manage re-initialize command.

D.3.6. Removing a Replica

Deleting or demoting a replica removes the IdM replica from the topology so that it no longer processes IdM requests. It also removes the host machine itself from the IdM domain.
To delete a replica, perform these steps on the replica:
  1. List all replication agreements for the IdM domain. In the output, note the host name of the replica. 
    $ ipa-replica-manage list
server1.example.com: master
server2.example.com: master
server3.example.com: master
server4.example.com: master
  2. Use the ipa-replica-manage del command to remove all agreements configured for the replica as well as all data about the replica. 
    $ ipa-replica-manage del server3.example.com
  3. If the replica was configured with its own CA, then also use the ipa-csreplica-manage del command to remove all certificate server replication agreements. 
    $ ipa-csreplica-manage del server3.example.com

    Note

    This step is only required if the replica itself was configured with an IdM CA. It is not required if only the master server or other replicas were configured with a CA.
  4. Uninstall the IdM server package. 
    $ ipa-server-install --uninstall -U