Configuring Data Replication With dsreplication

You can set up replication automatically using the graphical setup utility when you first install Oracle Unified Directory, if you configure all of the directory servers in the same manner. You cannot use the setup command to configure replication in command-line mode. If you set up your directory servers by using the setup command, you must use the dsreplication command to configure replication between the servers.

dsreplication accesses the server configuration over SSL through the administration connector. For more information, see Managing Administration Traffic to the Server

In any topology, you should have two replication servers for availability, in case one replication server fails. Replication servers are responsible for keeping track of all changes in the environment. Each replication server contains a list of all other replication servers in the topology.

The examples in this section assume that you have already installed two directory servers and populated one with data. The directory servers can be installed on the same host machine, but if they are, they must have different port numbers.

To Enable Replication Between Two Servers

• To enable replication, use the dsreplication enable command.

  The following command enables replication of the data under "dc=example,dc=com" between two directory servers, host1 and host2. Both servers use the default administration port (4444). The command creates a replication server instance on host1, port 8989, and a second replication server instance on host2, port 8989.

  $ dsreplication enable \
    --host1 host1 --port1 4444 --bindDN1 "cn=Directory Manager" \
    --bindPassword1 password --replicationPort1 8989 \
    --host2 host2 --port2 4444 --bindDN2 "cn=Directory Manager" \
    --bindPassword2 password --replicationPort2 8989 \
    --adminUID admin --adminPassword password --baseDN "dc=example,dc=com" -X -n

  The --adminUID and --adminPassword options refer to the Global Administrator for the replication domain. For more information, see Managing Global Administrators. The -X option specifies that all server certificates should be trusted and the -n (--no-prompt) option specifies that the command should be run in non-interactive mode. For information about all the global options for the dsreplication command, type dsreplication –help at the command-line.

Controlling Where Replication Servers are Created

Using dsreplication enable between two servers automatically configures a replication server on each host. You might want to configure replication between two directory servers without creating a replication server on each host. Use the --noReplicationServer1 or --noReplicationServer2 options to add a directory server to a topology without creating an additional replication server. Remember that a replicated topology must contain at least two replication servers to avoid a single point of failure.

You can also enable replication between two servers and specify that one of the servers should only contain a replication server (not a directory server). Use the --onlyReplicationServer1 or --onlyReplicationServer2 options to achieve this. Specifying this option will configure a change log and replication port on the server the server will not contain replicated data.

To Initialize a Replicated Server

• To initialize a replicated server with the data from another replicated server, use the dsreplication initialize command.

  The following command initializes the base DN "dc=example,dc=com" on host2 with the data contained on host1:

  $ dsreplication initialize --baseDN "dc=example,dc=com" \
    --adminUID admin --adminPassword password \
    --hostSource host1 --portSource 4444 \
    --hostDestination host2 --portDestination 4444 -X -n

To Initialize an Entire Topology

• If there are more than two directory servers in the topology, use the dsreplication intialize-all command to initialize all replicas simultaneously.

  This command takes the details of the source host as arguments, and initializes all other servers for which replication is enabled.

  The following command initializes all servers on which replication is enabled, from the contents of the base DN "dc=example,dc=com" on host1:

  $ dsreplication initialize-all --hostname host1 --port 4444 \
    --baseDN "dc=example,dc=com" --adminUID admin --adminPassword password

To Test Replication

The easiest way to test that replication is working is to apply changes on one directory server and to check that those changes have been replicated on another directory server. To test the replication topology set up in the previous procedures, do the following:

1. Use ldapmodify to change an entry on host1.
2. Use ldapsearch to verify that the change was propagated to host2.

To Obtain the Status of a Replicated Topology

You can use the connection details of any directory server in the topology to obtain the status of the entire topology.

• Use the dsreplication status command to display a list of the directory servers in the topology, along with any missing changes between those servers.

  The following command displays the status of the topology set up in the previous procedures:

  $ dsreplication status --adminUID admin --adminPassword password -X \
   --hostname host1 --port 4444
  
  dc=example,dc=com - Replication Enabled
  =======================================
  Server     :Entries:M.C.[1]:A.O.M.C.[2]:Port[3]:Encryption[4]:Trust[5]:U.C.[6]:Status[7]
  -----------:-------:-------:-----------:-------:-------------:--------:-------:---------
  host1:4444 :2003   :0      :N/A        :8989   :Disabled     :Trusted :N/A    :Normal
  host2:4444 :2003   :0      :N/A        :8989   :Disabled     :Trusted :N/A    :Normal
  
  [1] The number of changes that are still missing on this server (and that have been applied
      to at least one other server).
  [2] Age of oldest missing change: the age (in seconds) of the oldest change that has not yet
      arrived on this server.
  [3] The port used to communicate between the servers whose contents are being replicated.
  [4] Whether the replication communication through the replication port is encrypted or not.
  [5] Whether this directory server is trusted or not. Updates coming from an untrusted server
      are discarded and not propagated.
  [6] The number of untrusted changes. These are changes generated on this server while it is
      untrusted.
      Those changes are not propagated to the rest of the topology but are effective on the 
      untrusted server.
  [7] The status of the replication domain on this directory server.

To Merge Two Existing Replicated Topologies

You can merge two replicated topologies by enabling replication between one server of each topology.

Note the following limitations:

• All of the servers in both topologies must be up and running when you perform the merge.

  If a server its offline, dsreplication cannot update its configuration. If a server is offline when a merge is done, that server will not include the references to the replication servers in the other topology when it comes back online.

• The merge cannot be performed if there are conflicting domain IDs or replication server IDs between the two topologies.

  That is, a server in topology A cannot have the same replication server ID or domain ID as a server in topology B.

  If there are conflicting IDs, the ID of the first server (--host1) is used to resolve the conflict. You must then re-initialize any servers that are out of date, using a server from the same topology as --host1 as the source.

• Both replication topologies must have the same global administrators defined.

1. To merge two replicated topologies, use the dsreplication enable command.

   For example, if you have a replicated topology (topology A) that includes host1, host2 and host3 and a replicated topology (topology B) that includes host4, host5, and host6, the following command effectively merges the two topologies:

   $ dsreplication enable \
     --host1 host1 --port1 4444 --bindDN1 "cn=Directory Manager" \
     --bindPassword1 password --replicationPort1 8989 \
     --host2 host4 --port2 4444 --bindDN2 "cn=Directory Manager" \
     --bindPassword2 password  --replicationPort2 8989 \
     --adminUID admin --adminPassword password --baseDN "dc=example,dc=com" -X -n

   ---

   Note - This example assumes that both the hosts (host1 and host4) include a directory server and a replication server. If they do not, a directory server or replication server is automatically configured.

   ---

2. (Optional) To ensure high availability, you must perform the following steps on all servers that were offline or unavailable during a merge:
   1. Initialize the contents of the suffix cn=admin data by using dsreplication enable

      You can initialize the servers individually, using one of the servers that was available during the merge, or you can use dsreplication initialize-all.

   2. Use the dsconfig command to update the list of replication servers.

To Disable Replication For a Specific Replication Domain

1. To disable replication on a specific domain, use the dsreplication disable command.

   The following command disables replication of the data under "dc=example,dc=com".

   $ dsreplication disable --hostname host1 --port 4444 --adminUID admin \
     --adminPassword password --baseDN "dc=example,dc=com" -X -n

   This command removes the replication configuration from the directory server for that domain. If the domain that is disabled is the only replicated domain on this directory server instance, the command also disables the replication server on that instance. If the replication server is disabled, other directory servers that were connected to that replication server are disconnected and automatically reconnect to another replication server in the topology.

2. To disable the replication server itself (including the change log and the replication port) use the following command:

   $ dsreplication disable --hostname host1 --port 4444 -X -n \
     --adminUID admin --adminPassword password --baseDN "dc=example,dc=com" \
     --disableReplicationServer

   When the replication server is disabled, other directory servers that were connected to that replication server are disconnected and automatically reconnect to another replication server in the topology.

Notes About Disabling the Replication Server

Disabling a replication server deletes the replication configuration but does not delete the replication server databases. You can therefore retrieve replication changes in the event that the replication server was disabled in error. If you have no requirement for re-enabling replication on this suffix, remove the replication server databases manually, for example: $ rm changelogDB/*.

If replication is disabled, and then re-enabled, any changes made on that server in the interim are not replicated. You must therefore either forbid changes on the server on which replication is disabled (for the period that replication is disabled) or resynchronize the rest of the topology from that server in the event that changes have occurred.