Managing the topology
The following sections describe common topology management operations.
When enabling or disabling replication within a topology that contains multiple product versions, you must run the dsreplication
tool from the server root location of a member of the topology that has the oldest product version.
Adding a server to the topology
Before you begin
You must:
-
Have an existing PingDirectory server topology.
-
Ensure that more than 50% of servers in the topology and the new server are online.
About this task
The commands are identical for initial enablement between two servers where one server contains data for the replication domain stored in the userRoot
backend. If database encryption is being used on the servers in the topology, the server being initialized must have a copy of the encryption-settings
backend from the source server.
Steps
-
To enable replication for the base distinguished name (DN), or base DNs, run
dsreplication enable
using an existing server ashost1
and the new server ashost2
.Example:
$ bin/dsreplication enable \ --host1 austin01.example.com --port1 1389 \ --bindDN1 "cn=Directory Manager" --bindPassword1 password \ --replicationPort1 8989 --host2 austin03.example.com --port2 1389 \ --bindDN2 "cn=Directory Manager" --bindPassword2 password \ --replicationPort2 8989 --baseDN dc=example,dc=com --adminUID admin \ --adminPassword password --no-prompt
-
Optional: To compare the configurations between the two hosts used in the
dsreplication enable
command, runconfig-diff
.Ensure settings are consistent across the topology and are also consistent with the new system.
Example:
$ bin/config-diff --sourceLocal \ --targetHost austin03.example.com \ --targetBindDN "cn=directory manager" \ --targetBindPassword pass --targetPort 1389
Disabling replication and removing a server from the topology
Before you begin
More than 50% of the servers not being removed from the topology must be online during the process.
About this task
When removing a server from the topology, the remaining servers need to be made aware of the change. If additional servers are offline and cannot be online while removing the server, you must distinguish between offline servers that are offline permanently and those that are offline temporarily.
If servers are offline permanently, use |
Steps
-
To remove a server from the topology:
Choose from:
-
To remove a server that is online, run
dsreplication disable
from any server.$ bin/dsreplication disable --hostname austin03.example.com --port 1389 \ --baseDN dc=example,dc=com --adminUID admin --adminPassword password \ --no-prompt
If the server to remove is online, only one invocation of
dsreplication disable
is necessary. -
To remove a server that is offline, run
remove-defunct-server
in the following locations:-
From any server not being removed from the topology
-
On the offline server to be removed
$ bin/remove-defunct-server --serverInstanceName austin01 \ --bindDN "cn=Directory Manager" --bindPassword password
To speed up the process of removing multiple servers, change the default 10-minute timeout for each server you are taking out of rotation by setting the Java virtual machine (JVM) property
com.unboundid.connectionutils.LdapResponseTimeoutMillis
before you runremove-defunct-server
.
-
-
-
To remove any topology references, run the
remove-defunct-server
tool on each server that is removed from the topology.Example:
$ bin/remove-defunct-server --performLocalCleanup --no-prompt
To remove the defunct server, you must include the
--no-prompt
parameter. If you exclude this parameter, the server won’t be removed from the topology. Additionally, the server might attempt to contact additional hosts in the topology, which could result in an error. These are known issues that only apply to--performLocalCleanup
and will be corrected in a future release.The
--ignore-online
option removes an online server cleanly from the topology.
Replacing the data for a replicating domain
About this task
In case the data for the entire replication domain, such as the backend, needs to be replaced, perform the following steps:
Steps
-
With all servers online, run
dsreplication pre-external-initialization
against any server in the topology.Example:
$ bin/dsreplication pre-external-initialization --hostname austin01.example.com \ --port 1389 --baseDN dc=example,dc=com --adminUID admin \ --adminPassword password --no-prompt
Result:
Replication is stopped for the domain. No writes are made by clients to any of the servers.
-
To replace the data for
dc=example,dc=com
, useimport-ldif
.-
Optional: To overwrite the existing data for the domain, use the
--overwriteExistingEntries
option. -
Optional: To ensure that the input LDIF is free of any replication attributes, use the
--excludeReplication
option.Example:
In this example, you perform the
import-ldif
with the server offline using the--excludeReplication
and--overwriteExistingEntries
options.$ bin/import-ldif --ldifFile new-data.ldif --backendID userRoot --excludeReplication --overwriteExistingEntries
-
-
To initialize the other servers in the topology, run
dsreplication initialize
using the server that has the new data as the source host.Example:
$ bin/dsreplication initialize --hostSource austin01.example.com --portSource 1389 \ --hostDestination budapest01.example.com --portDestination 1389 \ --adminUID admin --adminPassword password --baseDN dc=example,dc=com \ --no-prompt
-
From any server in the topology, run
dsreplication post-external-initialization
once.All servers in the topology must be online.
Example:
$ bin/dsreplication post-external-initialization --hostname austin01.example.com \ --port 1389 --baseDN dc=example,dc=com --adminUID admin \ --adminPassword password --no-prompt