28.5. Managing Replication Agreements Between IdM Servers

Information is shared between the IdM servers and replicas using multi-master replication. What this means is that servers and replicas all receive updates and, therefore, are data masters. The domain information is copied between the servers and replicas using replication.
As replicas are added to the domain, mutual replication agreements are automatically created between the replica and the server it is based on. Additional replication agreements can be created between other replicas and servers or the configuration of the replication agreement can be changed using the ipa-replica-manage command.
When a replica is created, the replica install script creates two replication agreements: one going from the master server to the replica and one going from the replica to the master server.
Server and Replica Agreements

Figure 28.1. Server and Replica Agreements

As more replicas and servers are added to the domain, there can be replicas and servers that have replication agreements to other servers and replicas but not between each other. For example, the first IdM server is Server A. Then, the admin creates Replica B, and the install script creates a Server A => Replica B replication agreement and a Replica B => Server A replication agreement. Next, the admin creates Replica C based on Server A. The install script creates a Server A => Replica C replication agreement and a Replica C => Server A replication agreement. Replica B and Replica C both have replication agreements with Server A — but they do not have agreements with each other. For data availability, consistency, failover tolerance, and performance, it can be beneficial to create a pair of replication agreements between Replica B and Replica C, even though their data will eventually be replicated over to each other through replication with Server A.

28.5.1. Listing Replication Agreements

The ipa-replica-manage command can list all of the servers and replicas in the replication topology, using the list command:
[root@server ~]# ipa-replica-manage list
srv1.example.com
srv2.example.com
srv3.example.com
srv4.example.com
After getting the server/replica list, then it is possible to list the replication agreements for the server. These are the other servers/replicas to which the specified server sends updates.
[root@server ~]# ipa-replica-manage list srv1.example.com
srv2.example.com
srv3.example.com

28.5.2. Creating and Removing Replication Agreements

Replication agreements are created by connecting one server to another server.
ipa-replica-manage connect server1 server2
If only one server is given, the replication agreements are created between the local host and the specified server.
For example:
[root@server ~]# ipa-replica-manage connect srv2.example.com srv4.example.com
Replication occurs over standard LDAP; to enable SSL, then include the CA certificate for the local host (or the specified server1). The CA certificate is then installed in the remote server's certificate database to enable TLS/SSL connections. For example:
[root@server ~]# ipa-replica-manage connect --cacert=/etc/ipa/ca.crt srv2.example.com srv4.example.com
To remove a replication agreement between specific servers/replicas, use the disconnect command:
[root@server ~]# ipa-replica-manage disconnect srv2.example.com srv4.example.com
Using the disconnect command removes that one replication agreement but leaves both the server/replica instances in the overall replication topology. To remove a server entirely from the IdM replication topology, with all its data, (and, functionally, removing it from the IdM domain as a server), use the del command:
[root@server ~]# ipa-replica-manage del srv2.example.com

28.5.3. Forcing Replication

Replication between servers and replicas occurs on a schedule. Although replication is frequent, there can be times when it is necessary to initiate the replication operation manually. For example, if a server is being taken offline for maintenance, it is necessary to flush all of the queued replication changes out of its changelog before taking it down.
To initiate a replication update manually, use the force-sync command. The server which receives the update is the local server; the server which sends the updates is specified in the --from option.
[root@server ~]# ipa-replica-manage force-sync --from srv1.example.com

28.5.4. Reinitializing IdM Servers

When a replica is first created, the database of the master server is copied, completely, over to the replica database. This process is called initialization. If a server/replica is offline for a long period of time or there is some kind of corruption in its database, then the server can be re-initialized, with a fresh and updated set of data.
This is done using the re-initialize command. The target server being initialized is the local host. The server or replica from which to pull the data to initialize the local database is specified in the --from option:
[root@server ~]# ipa-replica-manage re-initialize --from srv1.example.com

28.5.5. Resolving Replication Conflicts

Changes — both for IdM domain data and for certificate and key data — are replicated between IdM servers and replicas (and, in similar paths, between IdM and Active Directory servers).
Even though replication operations are run continuously, there is a chance that changes can be made on one IdM server at the same time different changes are made to the same entry on a different IdM server. When replication begins to process those entries, the changes collide — this is a replication conflict.
Every single directory modify operation is assigned a server-specific change state number (CSN) to track how those modifications are propagated during replication. The CSN also contains a modify timestamp. When there is a replication conflict, the timestamp is checked and the last change wins.
Simply accepting the most recent change is effective for resolving conflicts with attribute values. That method is too blunt for some types of operations, however, which affect the directory tree. Some operations, like modrdn, DN changes, or adding or removing parent and child entries, require administrator review before the conflict is resolved.

Note

Replication conflicts are resolved by editing the entries directory in the LDAP database.
When there is a replication conflict, both entries are added to the directory and are assigned a nsds5ReplConflict attribute. This makes it easy to search for entries with a conflict:
ldapsearch -x -D "cn=directory manager" -w password -b "dc=example,dc=com" "nsds5ReplConflict=*" \* nsds5ReplConflict

28.5.5.1. Solving Naming Conflicts

When two entries are added to the IdM domain with the same DN, both entries are added to the directory, but they are renamed to use the nsuniqueid attribute as a naming attribute. For example:
nsuniqueid=0a950601-435311e0-86a2f5bd-3cd26022+uid=jsmith,cn=users,cn=accounts,dc=example,dc=com
Those entries can be searched for and displayed in the IdM CLI, but they cannot be edited or deleted until the conflict is resolved and the DN is updated.
To resolve the conflict:
  1. Rename the entry using a different naming attribute, and keep the old RDN. For example:
    ldapmodify -x -D "cn=directory manager" -w secret -h ipaserver.example.com -p 389
      dn: nsuniqueid=66446001-1dd211b2+uid=jsmith,cn=users,cn=accounts,dc=example,dc=com 
      changetype: modrdn 
      newrdn: cn=TempValue
      deleteoldrdn: 0
  2. Remove the old RDN value of the naming attribute and the conflict marker attribute. For example:
    ldapmodify -x -D "cn=directory manager" -w secret -h ipaserver.example.com -p 389
      dn: cn=TempValue,cn=users,cn=accounts,dc=example,dc=com 
      changetype: modify 
      delete: uid 
      uid: jsmith 
      - 
      delete: nsds5ReplConflict 
      -

    Note

    The unique identifier attribute nsuniqueid cannot be deleted.
  3. Rename the entry with the intended attribute-value pair. For example:
    ldapmodify -x -D "cn=directory manager" -w secret -h ipaserver.example.com -p 389
      dn: cn=TempValue,dc=example,dc=com 
      changetype: modrdn 
      newrdn: uid=jsmith
      deleteoldrdn: 1
    Setting the value of the deleteoldrdn attribute to 1 deletes the temporary attribute-value pair cn=TempValue. To keep this attribute, set the value of the deleteoldrdn attribute to 0.

28.5.5.2. Solving Orphan Entry Conflicts

When a delete operation is replicated and the consumer server finds that the entry to be deleted has child entries, the conflict resolution procedure creates a glue entry to avoid having orphaned entries in the directory.
In the same way, when an add operation is replicated and the consumer server cannot find the parent entry, the conflict resolution procedure creates a glue entry representing the parent so that the new entry is not an orphan entry.
Glue entries are temporary entries that include the object classes glue and extensibleObject. Glue entries can be created in several ways:
  • If the conflict resolution procedure finds a deleted entry with a matching unique identifier, the glue entry is a resurrection of that entry, with the addition of the glue object class and the nsds5ReplConflict attribute.
    In such cases, either modify the glue entry to remove the glue object class and the nsds5ReplConflict attribute to keep the entry as a normal entry or delete the glue entry and its child entries.
  • The server creates a minimalistic entry with the glue and extensibleObject object classes.
In such cases, modify the entry to turn it into a meaningful entry or delete it and all of its child entries.