--- title: Replication best practices description: Best practices for PingDirectory replication, including purging obsolete replicas and using the dsreplication command-line utility. component: pingdirectory version: 10.3 page_id: pingdirectory:pingdirectory_server_administration_guide:pd_ds_replication_best_practices canonical_url: https://docs.pingidentity.com/pingdirectory/11.1/pingdirectory_server_administration_guide/pd_ds_replication_best_practices.html llms_txt: https://docs.pingidentity.com/pingdirectory/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2026-08-17T00:00:00Z page_aliases: ["pd_ds_purge_obsolete_replicas.adoc", "pd_ds_dsreplication_command_line_utility.adoc"] superseded_by: https://docs.pingidentity.com/pingdirectory/11.1/pingdirectory_server_administration_guide/pd_ds_replication_best_practices.html section_ids: purge_obsolete_replicas: Purging obsolete replicas steps: Steps example: Example: replication_cli: About the dsreplication command-line utility developing-scripts: Developing Scripts concurrent-use: Concurrent Use status: Status topology-tasks: Topology Tasks --- # Replication best practices This section covers the best practices for replication based on our observations in production environments. ## Purging obsolete replicas A replicated topology can accumulate obsolete replicas, such as those left behind when you remove a server from the topology. Retaining obsolete replicas can increase the complexity of replication and negatively impact reliability. The `replication-purge-obsolete-replicas` global configuration property controls whether the PingDirectory server automatically purges these obsolete replicas. As of PingDirectory version 10.2, new installations set this property to `true` by default. Servers upgraded from an earlier version retain their existing value for this property. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | As of PingDirectory version 10.2, obsolete replicas no longer put a topology at risk of a `replication-missing-changes` alert or a server lockdown. Learn more in [Discovering obsolete replicas](pd_ds_troubleshoot_replication.html#discover_obsolete_replicas). | As a best practice, keep `replication-purge-obsolete-replicas` consistent across every server in the topology, including new servers as you add them, so that all servers behave the same way when purging obsolete replicas. ### Steps * To set `replication-purge-obsolete-replicas` to `true`, run `dsconfig set-global-configuration-prop`, as in the following example: #### Example: ``` bin/dsconfig set-global-configuration-prop \ --set replication-purge-obsolete-replicas:true ``` ## About the `dsreplication` command-line utility The following points involve some security practices that apply to replication. For specific questions, contact your authorized support provider. ### Developing Scripts The `dsreplication` utility maintains the history of executed `dsreplication` commands with the full command-line arguments in the `logs/tools/dsreplication.history` file. Use the recorded commands to develop scripts to set up and configure replication. You can find details about `dsreplication` logs in [Replication subcommand logs and exit codes](pd_ds_replication_subcommand_logs.html). Scripts invoking the `dsreplication` utility in non-interactive mode check the return code from the `dsreplication` process. A non-zero return code indicates a failure. To exclude output messages from the `dsreplication` utility, use the `--quiet` option to suppress them. By default, the utility fails if one or more warnings are issued during the command execution. To suppress warnings, use the `--ignoreWarnings` option. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This option is required when using `dsreplication` with non-fully-qualified host names, such as localhost. Otherwise `dsreplication` fails. However, you should avoid using this flag in production environments. | ### Concurrent Use With the exception of using the `dsreplication` utility with the `status` subcommand, the `dsreplication` subcommands cannot execute concurrently. The command-line utility locks the replication topology at one or more servers to prevent accidental configuration changes caused by multiple `dsreplication` subcommands running at the same time. For best practices, avoid making concurrent configuration changes. ### Status Using the `dsreplication` utility with the `status` subcommand requires the Replication Servers to provide monitoring information. This can lead to a delay before the output of `dsreplication` `status` displays. By default, `dsreplication` displays the status for all replicated domains with the exception of the special domains of the schema and the server registry. Select a particular base distinguished name (DN) for `dsreplication` `status` if multiple base DNs are configured for replication. Avoid invoking `dsreplication` `status` too often, such as more than once every 15 seconds or from multiple locations at the same time. Some of the information displayed by `dsreplication` `status` is based on monitor information that does not refresh every time the monitor is queried. Do not use the `status` subcommand for collecting performance metrics. It is best to use the Periodic Stats Logger plugin for replication-related information. ### Topology Tasks The `dsreplication` tool allows specifying more than one server in a topology to act as the host for other servers for the enable and initialize actions. Use the `--topologyFilePath` option to specify a file with a series of hosts and ports in the topology. For example, when the hosts file is used for an enable or initialize action, the servers in the file are tried sequentially until the new server is successfully enabled or added. The rest of the servers in the file are ignored. This ensures that a host server is always available. This file is generated with the `manage-topology export` command.