How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I use the Replica Remover tool in DS 5.x and 6.x to remove replication when the --unconfigureAll command has failed?

Last updated Apr 4, 2022

The purpose of this article is to provide information on using the Replica Remover tool in DS to remove replication when the 'dsreplication unconfigure --unconfigureAll' has failed to stop replication. This tool only works on Unix® and Linux® systems, and currently works to remove replication configuration on DS+RS instances.


1 reader recommends this article

Overview

Caution

You must only use the Replica Remover tool if the 'dsreplication unconfigure --unconfigureAll' command has failed to stop replication. Do not use this tool instead of using the native 'dsreplication unconfigure --unconfigureAll' command.

You can use the Replica Remover tool to remove the replication configuration of an individual replica or all replication configuration from an instance if the following occurs:

  • A replica was decommissioned before the 'dsreplication unconfigure --unconfigureAll' command was executed on it.
  • A replica's system is down and cannot be recovered.
  • If the 'dsreplication unconfigure --unconfigureAll' command failed because of an unexpected error, such as error code 53 (Unwilling to Perform).
  • If the 'dsreplication unconfigure --unconfigureAll' command succeeded on the localhost, but failed to remove the replica configuration from the remote hosts and dsreplication status throws the following exception: Error on ds1.example.com:5444: An error occurred connecting to the server. Details: javax.naming.CommunicationException: ds1.example.com:6444 [Root exception is java.net.ConnectException: Connection refused]

Using the Replica Remover tool

  1. Download the remove-replica.sh (18 kB) file and copy it to the /path/to/ds/bin directory.
  2. Change to the /path/to/ds/bin directory: $ cd /path/to/ds/bin
  3. Execute the replica-remover.sh tool to see its full usage: $ ./remove-replica.sh

The Replica Removal tool can be used for the following purposes, which are detailed below:

Removing a decommissioned instance's replication configuration from the surviving replicas

This process is used to remove the replica configuration of a decommissioned/offline instance from the surviving replicas. Replica Remover will create one to two LDIF files depending on the configuration found and display example ldapmodify commands.

This process automatically completes the following steps:

  1. Checks if the hostname+replication port to be removed is in the local config.ldif.
  2. Checks if the hostname+admin port to be removed is in the local admin-backend.ldif.
  3. Generates one to two LDIF files.
  4. Displays the relevant ldapmodify command to be used.
Note

The DS instance must be online for this operation.

Required parameters

-t [removal type] remove-replica
-h [hostname] The hostname of the server whose configuration you need removed.
-r [replication port] Replication port of the server whose configuration you need removed.
-a [admin port] Admin port of the server whose configuration you need removed.

Example command

$ ./remove-replica.sh -t remove-replica -h ds1.example.com -r 8989 -a 4444

Removing all replica data from a local server when --unconfigureAll fails

This process is used to remove all the replica configuration from the local instance. The results are similar to DS's dsreplication unconfigure --unconfigureAll command. Replica Remover will create one LDIF file and display example ldapmodify commands.

This process automatically completes the following steps:

  1. Checks if the hostname+replication port to be removed is in the local config.ldif.
  2. Checks if the hostname+admin port to be removed is in the local admin-backend.ldif.
  3. Generates a single LDIF file.
  4. Displays the relevant ldapmodify command to be used.
Note

The DS instance must be online for this operation.

Required parameters

-t [removal type] disable-replication

Example command

$ ./remove-replica.sh -t disable-replication

Example using the Replica Remover Tool

In this example, we have the following 3 External/Embedded DS servers in a replication topology:

Suffix DN     : Server                    : Entries : Replication enabled : DS ID : RS ID : RS Port (1) : M.C. (2) : A.O.M.C. (3) : Security (4) ------------------:---------------------------:---------:---------------------:-------:-------:-------------:----------:--------------:------------- dc=example,dc=com : ds1.example.com:4444      : 1002    : true                : 10000 : 10000 :  8989       : 0        :              : false dc=example,dc=com : ds1.example.com:5444      : 1002    : true                : 16361 :  9869 :  9989       : 0        :              : true dc=example,dc=com : ds1.example.com:6444      : 1002    : true                :   759 : 17391 : 10989       : 0        :              : true

The following two scenarios demonstrate how and why you would use the Replica Removal tool.

Scenario #1: Removing a decommissioned instances replication configuration from the surviving replicas

  1. Check the dsreplication status; in this example it fails with a javax.naming.CommunicationException because it cannot contact that node (Master 3): $ ./dsreplication status --adminUID admin --adminPassword password --hostname ds1.example.com --port 4444 --trustAll   Thu Jun 30 13:40:47 MDT 2021 The displayed information might not be complete because the following errors were encountered reading the configuration of the existing servers: Error on ds1.example.com:6444: An error occurred connecting to the server. Details: javax.naming.CommunicationException: ds1.example.com:6444 [Root exception is java.net.ConnectException: Connection refused] Suffix DN         : Server                    : Entries : Replication enabled : DS ID : RS ID : RS Port (1) : M.C. (2) : A.O.M.C. (3) : Security (4) ------------------:---------------------------:---------:---------------------:-------:-------:-------------:----------:--------------:------------- dc=example,dc=com : ds1.example.com:4444      : 1002    : true                : 10000 : 10000 :  8989       : 0        :              : false dc=example,dc=com : ds1.example.com:5444      : 1002    : true                : 16361 :  9869 :  9989       : 0        :              : true
  2. Use the Replica Remover tool to delete the associated replication data for Master 3 (which was offline) from Master 1 and 2: $ ./remove-replica.sh -t remove-replica -h ds1.example.com -r 10989 -a 6444   ------------------------------------------------------------------------------ DS Replica Remover v 2.0.3 ------------------------------------------------------------------------------  - Checking Replica Server information for ds1.example.com:10989.  - Replica information found. Continuing  - Checking Admin Server information for ds1.example.com:6444.  - Admin Server information found. Continuing  - Generating ldif files  - Operations complete    Please run the following commands in this order:    1. Remove replica information from cn=admin data   ./ldapmodify --hostname localhost --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --continueOnError --fileName ./remove-ds1.example.com-admin-6444.ldif 2. Remove replica information from cn=config   ./ldapmodify --hostname localhost --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --continueOnError --fileName ./remove-ds1.example.com-replica-10989.ldif    Notes:  - Executing 1. above will remove the Replica Configuration from all servers.     Modifications made with 1. will be replicated to all other servers. Only run this one time.  - Executing 2. above will remove the Replica Configuration from this server only.     Modifications made with 2. will not be replicated to all other servers. You must run this against all surviving replicas.
  3. Run the first command: $ ./ldapmodify --hostname localhost --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --continueOnError --fileName ./remove-ds1.example.com-admin-6444.ldif   Processing MODIFY request for cn=all-servers,cn=Server Groups,cn=admin data MODIFY operation successful for DN cn=all-servers,cn=Server Groups,cn=admin data Processing DELETE request for cn=ds1.example.com:6444,cn=Servers,cn=admin data DELETE operation successful for DN cn=ds1.example.com:6444,cn=Servers,cn=admin data
  4. Run the second command: $ ./ldapmodify --hostname localhost --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --continueOnError --fileName ./remove-ds1.example.com-replica-10989.ldif   Processing MODIFY request for cn=cn=admin data,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config MODIFY operation successful for DN cn=cn=admin data,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config Processing MODIFY request for cn=cn=schema,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config MODIFY operation successful for DN cn=cn=schema,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config Processing MODIFY request for cn=dc=example\,dc=com,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config MODIFY operation successful for DN cn=dc=example\,dc=com,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config Processing MODIFY request for cn=replication server,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config MODIFY operation successful for DN cn=replication server,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config
  5. Check the replication status again to verify there are no connection exceptions: $ ./dsreplication status --adminUID admin --adminPassword password --hostname ds1.example.com --port 5444 --trustAll   Thu Jun 30 13:42:55 MDT 2021 Suffix DN         : Server                    : Entries : Replication enabled : DS ID : RS ID : RS Port (1) : M.C. (2) : A.O.M.C. (3) : Security (4) ------------------:---------------------------:---------:---------------------:-------:-------:-------------:----------:--------------:------------- dc=example,dc=com : ds1.example.com:4444      : 1002    : true                : 10000 : 10000 :  8989       : 0        :              : false dc=example,dc=com : ds1.example.com:5444      : 1002    : true                : 16361 :  9869 :  9989       : 0        :              : true

Scenario #2: Removing all replica data from a local server when --unconfigureAll fails

  1. Use the Replica Remover tool to disable replication fully on Master 2 (replica port 9989, admin port 5444). $ ./remove-replica.sh -t disable-replication ------------------------------------------------------------------------------ DS Replica Remover v 2.0.3 ------------------------------------------------------------------------------ - Generating ldif files  - Operations complete    Please run the following command: ./ldapmodify --hostname localhost --port 2389 --bindDN "cn=Directory Manager" --bindPassword password --continueOnError --fileName ./disable-replication-on-ds1.example.com:5444.ldif    Notes:  - Executing the above will remove the Replica Configuration from this server only, unless replication is operating normally.
  2. Run the suggested command: $ ./ldapmodify --hostname localhost --port 2389 --bindDN "cn=Directory Manager" --bindPassword password --continueOnError --fileName ./disable-replication-on-ds1.example.com:5444.ldif   Processing MODIFY request for cn=all-servers,cn=Server Groups,cn=admin data MODIFY operation successful for DN cn=all-servers,cn=Server Groups,cn=admin data Processing DELETE request for cn=ds1.example.com:5444,cn=Servers,cn=admin data DELETE operation successful for DN cn=ds1.example.com:5444,cn=Servers,cn=admin data Processing DELETE request for cn=replication server,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config DELETE operation successful for DN cn=replication server,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config Processing DELETE request for cn=external changelog,cn=dc=example\,dc=com,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config DELETE operation successful for DN cn=external changelog,cn=dc=example\,dc=com,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config Processing DELETE request for cn=external changelog,cn=cn=schema,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config DELETE operation successful for DN cn=external changelog,cn=cn=schema,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config Processing DELETE request for cn=external changelog,cn=cn=admin data,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config DELETE operation successful for DN cn=external changelog,cn=cn=admin data,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config Processing DELETE request for cn=dc=example\,dc=com,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config DELETE operation successful for DN cn=dc=example\,dc=com,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config Processing DELETE request for cn=cn=schema,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config DELETE operation successful for DN cn=cn=schema,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config Processing DELETE request for cn=cn=admin data,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config DELETE operation successful for DN cn=cn=admin data,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config Processing MODIFY request for cn=all-servers,cn=Server Groups,cn=admin data MODIFY operation successful for DN cn=all-servers,cn=Server Groups,cn=admin data Processing DELETE request for cn=ds1.example.com:6444,cn=Servers,cn=admin data DELETE operation successful for DN cn=ds1.example.comm:6444,cn=Servers,cn=admin data Processing DELETE request for cn=ds1.example.com:4444,cn=Servers,cn=admin data DELETE operation successful for DN cn=ds1.example.com:4444,cn=Servers,cn=admin data
  3. Check the replication status from Master 2 to verify that the replication topology has been successfully removed: $ ./dsreplication status --adminUID admin --adminPassword password --hostname ds1.example.com --port 5444 --trustAll   Thu Jun 30 15:01:36 MDT 2021    No replication information found.
  4. Check the replication status from Master 1 to verify the replication topology is still correct: $ ./dsreplication status --adminUID admin --adminPassword password --hostname ds1.example.com --port 4444 --trustAll   Thu Jun 30 15:11:25 MDT 2021 Suffix DN         : Server                    : Entries : Replication enabled : DS ID : RS ID : RS Port (1) : M.C. (2) : A.O.M.C. (3) : Security (4) ------------------:---------------------------:---------:---------------------:-------:-------:-------------:----------:--------------:------------- dc=example,dc=com : ds1.example.com:4444      : 1002    : true                : 10000 : 10000 :  8989       : 0        :              : false dc=example,dc=com : ds1.example.com:6444      : 1002    : true                :   759 : 17391 : 10989       : 0        :              : true

See Also

How do I repair replication configuration in DS 5.x or 6.x when dsreplication has failed?

How do I delete an AM 5.x or 6.x instance from a site along with the replicated embedded DS server?

Stopping Replication

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2022 ForgeRock, all rights reserved.