PingDirectory

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

  1. To enable replication for the base distinguished name (DN), or base DNs, run dsreplication enable using an existing server as host1 and the new server as host2.

    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

  2. Optional: To compare the configurations between the two hosts used in the dsreplication enable command, run config-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

  • Remove a live server

  • Remove an offline server

Removing a live server

Steps

  • To remove a server that is online, run the dsreplication disable command 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.

Removing an offline server from the topology

Steps

  • To remove a defunct or misbehaving server from the topology while that server is offline, run remove-defunct-server from a live server in the topology. Doing this will remove configuration references to the offline server from the topology’s perspective. This is useful if the server is broken and cannot start. For example:

    $ bin/remove-defunct-server --serverInstanceName austin01 \
--bindDN "cn=Directory Manager" --bindPassword password

    After you have removed the server, you can delete it. However, if you want to keep the server as a standalone server, proceed to Cleaning up an offline defunct server.

    The --ignore-online option removes an online server cleanly from the topology.

    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 run remove-defunct-server.

Cleaning up an offline defunct server

About this task

If you have removed a defunct server and want to keep it as a standalone server, then you also need to run the remove-defunct-server --performLocalCleanup command on the defunct server while it is offline. This will remove all topology configuration references on the offline server, and make it a standalone server. This is useful if a server is temporarily misbehaving, but you want to add it back to the topology at a later time. The remove-defunct-server command will only accept the --performLocalCleanup argument if the server is offline.

Steps

  • Run the remove-defunct-server command on each server that is removed from the topology. For 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.

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

  1. 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.

  2. To replace the data for dc=example,dc=com, use import-ldif.

    1. Optional: To overwrite the existing data for the domain, use the --overwriteExistingEntries option.

    2. 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

  3. 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

  4. 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