Chapter 1. Managing replication topology

This chapter describes how to manage replication between servers in an Identity Management (IdM) domain.

Additional resources

1.1. Explaining replication agreements, topology suffixes and topology segments

When you create a replica, Identity Management (IdM) creates a replication agreement between the initial server and the replica. The data that is replicated is then stored in topology suffixes and when two replicas have a replication agreement between their suffixes, the suffixes form a topology segment. These concepts are explained in more detail in the following sections:

1.1.1. Replication agreements between IdM replicas

When an administrator creates a replica based on an existing server, Identity Management (IdM) creates a replication agreement between the initial server and the replica. The replication agreement ensures that the data and configuration is continuously replicated between the two servers.

IdM uses multiple read/write replica replication. In this configuration, all replicas joined in a replication agreement receive and provide updates, and are therefore considered suppliers and consumers. Replication agreements are always bilateral.

Figure 1.1. Server and replica agreements

An image of two servers with two sets of replication agreements between them: a data replication agreement that pertains to their Directory Server database and a certificate replication agreement that pertains to their Certificate System data

IdM uses two types of replication agreements:

Domain replication agreements
These agreements replicate the identity information.
Certificate replication agreements
These agreements replicate the certificate information.

Both replication channels are independent. Two servers can have one or both types of replication agreements configured between them. For example, when server A and server B have only domain replication agreement configured, only identity information is replicated between them, not the certificate information.

1.1.2. Topology suffixes

Topology suffixes store the data that is replicated. IdM supports two types of topology suffixes: domain and ca. Each suffix represents a separate server, a separate replication topology.

When a replication agreement is configured, it joins two topology suffixes of the same type on two different servers.

The domain suffix: dc=example,dc=com

The domain suffix contains all domain-related data.

When two replicas have a replication agreement between their domain suffixes, they share directory data, such as users, groups, and policies.

The ca suffix: o=ipaca

The ca suffix contains data for the Certificate System component. It is only present on servers with a certificate authority (CA) installed.

When two replicas have a replication agreement between their ca suffixes, they share certificate data.

Figure 1.2. Topology suffixes

topology suffix

An initial topology replication agreement is set up between two servers by the ipa-replica-install script when installing a new replica.

Example 1.1. Viewing topology suffixes

The ipa topologysuffix-find command displays a list of topology suffixes: 

$ ipa topologysuffix-find
---------------------------
2 topology suffixes matched
---------------------------
  Suffix name: ca
  Managed LDAP suffix DN: o=ipaca

  Suffix name: domain
  Managed LDAP suffix DN: dc=example,dc=com
----------------------------
Number of entries returned 2
----------------------------

1.1.3. Topology segments

When two replicas have a replication agreement between their suffixes, the suffixes form a topology segment. Each topology segment consists of a left node and a right node. The nodes represent the servers joined in the replication agreement.

Topology segments in IdM are always bidirectional. Each segment represents two replication agreements: from server A to server B, and from server B to server A. The data is therefore replicated in both directions.

Figure 1.3. Topology segments

topology segment

Example 1.2. Viewing topology segments

The ipa topologysegment-find command shows the current topology segments configured for the domain or CA suffixes. For example, for the domain suffix: 

$ ipa topologysegment-find
Suffix name: domain
-----------------
1 segment matched
-----------------
  Segment name: server1.example.com-to-server2.example.com
  Left node: server1.example.com
  Right node: server2.example.com
  Connectivity: both
----------------------------
Number of entries returned 1
----------------------------

In this example, domain-related data is only replicated between two servers: server1.example.com and server2.example.com.

To display details for a particular segment only, use the ipa topologysegment-show command: 

$ ipa topologysegment-show
Suffix name: domain
Segment name: server1.example.com-to-server2.example.com
  Segment name: server1.example.com-to-server2.example.com
  Left node: server1.example.com
  Right node: server2.example.com
  Connectivity: both

1.2. Using the topology graph to manage replication topology

The topology graph in the web UI shows the relationships between the servers in the domain. Using the Web UI, you can manipulate and transform the representation of the topology.

Accessing the topology graph

To access the topology graph:

  1. Select IPA Server → Topology → Topology Graph.
  2. If you make any changes to the topology that are not immediately reflected in the graph, click Refresh.

Interpreting the topology graph

Servers joined in a domain replication agreement are connected by an orange arrow. Servers joined in a CA replication agreement are connected by a blue arrow.

Topology graph example: recommended topology

The recommended topology example below shows one of the possible recommended topologies for four servers: each server is connected to at least two other servers, and more than one server is a CA server.

Figure 1.4. Recommended topology example

mng top rec
Topology graph example: discouraged topology

In the discouraged topology example below, server1 is a single point of failure. All the other servers have replication agreements with this server, but not with any of the other servers. Therefore, if server1 fails, all the other servers will become isolated.

Avoid creating topologies like this.

Figure 1.5. Discouraged topology example: Single Point of Failure

mng top single

Customizing the topology view

You can move individual topology nodes by dragging the mouse:

Figure 1.6. Moving topology graph nodes

customize graph 1

You can zoom in and zoom out the topology graph using the mouse wheel:

Figure 1.7. Zooming the topology graph

customize graph 2

You can move the canvas of the topology graph by holding the left mouse button:

Figure 1.8. Moving the topology graph canvas

customize graph 3

1.3. Setting up replication between two servers using the Web UI

Using the Web interface of Identity Management (IdM) you can choose two servers and create new replication agreement between them.

Prerequisites

  • You have the IdM administrator credentials.

Procedure

  1. In the topology graph, hover your mouse over one of the server nodes.

    Figure 1.9. Domain or CA options

    mng top domain ca
  2. Click on the domain or the ca part of the circle depending on what type of topology segment you want to create.

  3. A new arrow representing the new replication agreement appears under your mouse pointer. Move your mouse to the other server node, and click on it.

    Figure 1.10. Creating a new segment

    mng top drag
  4. In the Add topology segment window, click Add to confirm the properties of the new segment.

The new topology segment between the two servers joins them in a replication agreement. The topology graph now shows the updated replication topology:

Figure 1.11. New segment created

mng top three

1.4. Stopping replication between two servers using the Web UI

Using the web interface of Identity Management (IdM) you can remove a replication agreement from servers.

Prerequisites

  • You have the IdM administrator credentials.

Procedure

  1. Click on an arrow representing the replication agreement you want to remove. This highlights the arrow.

    Figure 1.12. Topology segment highlighted

    mng top highlight
  2. Click Delete.
  3. In the Confirmation window, click OK.

IdM removes the topology segment between the two servers, which deletes their replication agreement. The topology graph now shows the updated replication topology:

Figure 1.13. Topology segment deleted

mng top delete segment

1.5. Setting up replication between two servers using the CLI

You can configure replication agreements between two servers using the ipa topologysegment-add command.

Prerequisites

  • You have the IdM administrator credentials.

Procedure

  1. Use the ipa topologysegment-add command to create a topology segment for the two servers. When prompted, provide:

    • the required topology suffix: domain or ca
    • the left node and the right node, representing the two servers

    • optionally, a custom name for the segment

      For example: 

      $ ipa topologysegment-add
Suffix name: domain
Left node: server1.example.com
Right node: server2.example.com
Segment name [server1.example.com-to-server2.example.com]: new_segment
---------------------------
Added segment "new_segment"
---------------------------
  Segment name: new_segment
  Left node: server1.example.com
  Right node: server2.example.com
  Connectivity: both

      Adding the new segment joins the servers in a replication agreement.

  2. Optional. Use the ipa topologysegment-show command to verify that the new segment is configured. 

    $ ipa topologysegment-show
Suffix name: domain
Segment name: new_segment
  Segment name: new_segment
  Left node: server1.example.com
  Right node: server2.example.com
  Connectivity: both

1.6. Stopping replication between two servers using the CLI

You can terminate replication agreements from command line using the ipa topology segment-del command.

Prerequisites

  • You have the IdM administrator credentials.

Procedure

  1. To stop replication, you must delete the corresponding replication segment between the servers. To do that, you need to know the segment name.

    If you do not know the name, use the ipa topologysegment-find command to display all segments, and locate the required segment in the output. When prompted, provide the required topology suffix: domain or ca. For example: 

    $ ipa topologysegment-find
Suffix name: domain
------------------
8 segments matched
------------------
  Segment name: new_segment
  Left node: server1.example.com
  Right node: server2.example.com
  Connectivity: both

...

----------------------------
Number of entries returned 8
----------------------------

  2. Use the ipa topologysegment-del command to remove the topology segment joining the two servers. 

    $ ipa topologysegment-del
Suffix name: domain
Segment name: new_segment
-----------------------------
Deleted segment "new_segment"
-----------------------------

    Deleting the segment removes the replication agreement.

  3. Optional. Use the ipa topologysegment-find command to verify that the segment is no longer listed. 

    $ ipa topologysegment-find
Suffix name: domain
------------------
7 segments matched
------------------
  Segment name: server2.example.com-to-server3.example.com
  Left node: server2.example.com
  Right node: server3.example.com
  Connectivity: both

...

----------------------------
Number of entries returned 7
----------------------------

1.7. Removing server from topology using the Web UI

You can use Identity Management (IdM) web interface to remove a server from the topology.

Prerequisites

  • You have the IdM administrator credentials.
  • The server you want to remove is not the only server connecting other servers with the rest of the topology; this would cause the other servers to become isolated, which is not allowed.
  • The server you want to remove is not your last CA or DNS server.
Warning

Removing a server is an irreversible action. If you remove a server, the only way to introduce it back into the topology is to install a new replica on the machine.

Procedure

To remove a server from the topology without uninstalling the server components from the machine:

  1. Select IPA Server → Topology → IPA Servers.

  2. Click on the name of the server you want to delete.

    Figure 1.14. Selecting a server

    mng top delete
  3. Click Delete Server.

1.8. Removing server from topology using the CLI

You can use the command line interface to remove a server from the topology.

Prerequisites

  • You have the IdM administrator credentials.
  • The server you want to remove is not the only server connecting other servers with the rest of the topology; this would cause the other servers to become isolated, which is not allowed
  • The server you want to remove is not your last CA or DNS server.
Important

Removing a server is an irreversible action. If you remove a server, the only way to introduce it back into the topology is to install a new replica on the machine.

Procedure

To remove server1.example.com:

  1. On another server, run the ipa server-del command to remove server1.example.com. The command removes all topology segments pointing to the server: 

    [user@server2 ~]$ ipa server-del
Server name: server1.example.com
Removing server1.example.com from replication topology, please wait...
----------------------------------------------------------
Deleted IPA server "server1.example.com"
----------------------------------------------------------

  2. Optional: on server1.example.com, run the ipa server-install --uninstall command to uninstall the server components from the machine. 

    [root@server1 ~]# ipa server-install --uninstall

1.9. Viewing server roles on an IdM server using the Web UI

Based on the services installed on an IdM server, it can perform various server roles. For example:

  • CA server
  • DNS server
  • Key recovery authority (KRA) server.

For a complete list of the supported server roles, see IPA Server → Topology → Server Roles.

Note
  • Role status absent means that no server in the topology is performing the role.
  • Role status enabled means that one or more servers in the topology are performing the role.

Figure 1.15. Server roles in the web UI

server role absent

1.10. Viewing server roles on an IdM server using the CLI

Based on the services installed on an IdM server, it can perform various server roles. For example:

  • CA server
  • DNS server
  • Key recovery authority (KRA) server.

You can view which servers perform which roles in the topology using the following commands.

  • The ipa config-show command displays all CA servers and the current CA renewal server: 
$ ipa config-show
  ...
  IPA masters: server1.example.com, server2.example.com, server3.example.com
  IPA CA servers: server1.example.com, server2.example.com
  IPA CA renewal master: server1.example.com
  • The ipa server-show command displays a list of roles enabled on a particular server. For example, for a list of roles enabled on server.example.com: 
$ ipa server-show
Server name: server.example.com
  ...
  Enabled server roles: CA server, DNS server, KRA server
  • The ipa server-find --servrole searches for all servers with a particular server role enabled. For example, to search for all CA servers: 
$ ipa server-find --servrole "CA server"
---------------------
2 IPA servers matched
---------------------
  Server name: server1.example.com
  ...

  Server name: server2.example.com
  ...
----------------------------
Number of entries returned 2
----------------------------

1.11. Promoting a replica to a CA renewal server and CRL publisher server

If your IdM deployment uses an embedded certificate authority (CA), one of the IdM CA servers acts as the CA renewal server, a server that manages the renewal of CA subsystem certificates. One of the IdM CA servers also acts as the IdM CRL publisher server, a server that generates certificate revocation lists. By default, the CA renewal server and CRL publisher server roles are installed on the first server on which the system administrator installed the CA role using the ipa-server-install or ipa-ca-install command.

Prerequisites

  • You have the IdM administrator credentials.

1.12. Demoting or promoting hidden replicas

Procedure

After a replica has been installed, you can configure whether the replica is hidden or visible.

For details about hidden replicas, see The hidden replica mode.

If the replica is a CA renewal server, move the service to another replica before making this replica hidden.

For details, see

Procedure

  • To hide the replica, enter: 

    # ipa server-state replica.idm.example.com --state=hidden

    Alternatively, you can make the replica visible with the following command: 

    # ipa server-state replica.idm.example.com --state=enabled

    To view a list of all the hidden replicas in your topology, enter: 

    # ipa config-show

    If all of your replicas are enabled, the command output does not mention hidden replicas