Show Table of Contents
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:
- 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
- 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 whichserver1.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:
- 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
- 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
- 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. - Uninstall the IdM server package.
$ ipa-server-install --uninstall -U