<?xml version="1.0" encoding="UTF-8"?>
|
<!--
|
! CCPL HEADER START
|
!
|
! This work is licensed under the Creative Commons
|
! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
|
! To view a copy of this license, visit
|
! http://creativecommons.org/licenses/by-nc-nd/3.0/
|
! or send a letter to Creative Commons, 444 Castro Street,
|
! Suite 900, Mountain View, California, 94041, USA.
|
!
|
! You can also obtain a copy of the license at
|
! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
|
! See the License for the specific language governing permissions
|
! and limitations under the License.
|
!
|
! If applicable, add the following below this CCPL HEADER, with the fields
|
! enclosed by brackets "[]" replaced with your own identifying information:
|
! Portions Copyright [yyyy] [name of copyright owner]
|
!
|
! CCPL HEADER END
|
!
|
! Copyright 2011 ForgeRock AS
|
!
|
-->
|
<chapter xml:id='chap-replication'
|
xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
|
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
|
xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
|
xmlns:xlink='http://www.w3.org/1999/xlink'
|
xmlns:xinclude='http://www.w3.org/2001/XInclude'>
|
<title>Managing Data Replication</title>
|
|
<para>OpenDJ uses advanced data replication with automated conflict
|
resolution to help ensure your directory services remain available in the
|
event a server crashes or a network goes down, and also as you backup or
|
upgrade your directory service. You can configure data replication as part
|
of OpenDJ installation, and in many cases let replication do its work in
|
the background.</para>
|
|
<section>
|
<title>Replication Quick Setup</title>
|
|
<para>The easiest way to set up replication for the first time involves
|
using the setup wizard.</para>
|
|
<para>In the Topology Options screen for the first server you set up, select
|
This server will be part of a replication topology. If you also choose
|
Configure as Secure, then replication traffic is protected by SSL.</para>
|
|
<mediaobject>
|
<imageobject>
|
<imagedata fileref="images/replA-setup.png" format="PNG" />
|
</imageobject>
|
</mediaobject>
|
|
<para>In the Topology Options screen for subsequent servers, also select
|
There is already a server in the topology, providing the Host Name,
|
Administration Connector Port number, Admin User, and Admin Password for
|
the first replica you set up.</para>
|
|
<mediaobject>
|
<imageobject>
|
<imagedata fileref="images/replB-setup.png" format="PNG" />
|
</imageobject>
|
</mediaobject>
|
|
<para>You also set up a global administrator account, stored under
|
<literal>cn=admin data</literal> across replicas, used to manage replication
|
in the topology.</para>
|
|
<mediaobject>
|
<imageobject>
|
<imagedata fileref="images/replB-global-admin.png" format="PNG" />
|
</imageobject>
|
</mediaobject>
|
|
<para>You further set up what to replicate.</para>
|
|
<mediaobject>
|
<imageobject>
|
<imagedata fileref="images/replB-data-repl.png" format="PNG" />
|
</imageobject>
|
</mediaobject>
|
|
<para>Once replication is set up, it works for all the replicas. You can
|
monitor the replication connection and status through the OpenDJ Control
|
Panel.</para>
|
|
<mediaobject>
|
<imageobject>
|
<imagedata fileref="images/replA-monitor-repl.png" format="PNG" />
|
</imageobject>
|
</mediaobject>
|
|
</section>
|
|
<section>
|
<title>About Replication</title>
|
|
<para>Before you take replication further than setting up replication
|
in the setup wizard, read this section to learn more about how OpenDJ
|
replication works.</para>
|
|
<para>Replication is the process of copying updates between OpenDJ
|
directory servers such that all servers converge on identical copies of
|
directory data. Replication is designed to let convergence happen over
|
time by default. <footnote><para>Assured replication can require, however,
|
that the convergence happen before the client application is notified that
|
the operation was successful.</para></footnote> Letting convergence
|
happen over time means that different replicas can be momentarily out of
|
sync, but it also means that if you lose an individual server or even an
|
entire data center, your directory service can keep on running, and then
|
get back in sync when the servers are restarted or the network is
|
repaired.</para>
|
|
<para>Replication is specific to the OpenDJ directory service. Replication
|
uses a specific protocol that replays update operations quickly, storing
|
enough historical information about the updates to resolve most conflicts
|
automatically. For example, if two client applications separately update
|
a user entry to change the phone number, replication can work out which
|
was the latest change, and apply that change across servers. The historical
|
information needed to resolve these issues is periodically purged to avoid
|
growing larger and larger forever. As a directory administrator, you make
|
sure that you do not purge the historical information more often than you
|
backup your directory data.</para>
|
|
<para>The primary unit of replication is the suffix, specified by a
|
base DN such as <literal>dc=example,dc=com</literal>. <footnote><para>When
|
you configure partial and fractional replication, however, you can replicate
|
only part of a suffix, or only certain attributes on entries. Also,
|
if you split your suffix across multiple backends, then you need to set up
|
replication separately for each part of suffix in a different backend.</para>
|
</footnote> Replication also depends on the directory schema, defined on
|
<literal>cn=schema</literal>, and the <literal>cn=admin data</literal>
|
suffix with administrative identities and certificates for protecting
|
communications. Thus that content gets replicated as well.</para>
|
|
<para>The set of replicas sharing data in a given suffix is called
|
a replication topology. You can have more than one replication topology.
|
For example, one topology could be devoted to
|
<literal>dc=example,dc=com</literal>, and another to
|
<literal>dc=example,dc=org</literal>. Directory servers are capable of
|
serving more than one suffix. They are also capable of participating in
|
more than one replication topology.</para>
|
</section>
|
|
<section>
|
<title>Configuring Replication</title>
|
|
<para>For some deployments you choose not to configure replication using the
|
setup wizard. This section shows how to configure replication with
|
command-line tools.</para>
|
|
<section>
|
<title>Enabling Replication</title>
|
|
<para>You can start the replication process by using the
|
<command>dsreplication enable</command> command.</para>
|
|
<screen width="80">$ dsreplication enable -I admin -w password -X -n -b dc=example,dc=com \
|
> --host1 `hostname` --port1 4444 --bindDN1 "cn=Directory Manager" \
|
> --bindPassword1 password --replicationPort1 8989 \
|
> --host2 `hostname` --port2 5444 --bindDN2 "cn=Directory Manager" \
|
> --bindPassword2 password --replicationPort2 9989
|
|
Establishing connections ..... Done.
|
Checking registration information ..... Done.
|
Updating remote references on server localhost:4444 ..... Done.
|
Configuring Replication port on server localhost:5444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
localhost:4444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
localhost:5444 ..... Done.
|
Updating registration configuration on server localhost:4444 ..... Done.
|
Updating registration configuration on server localhost:5444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
localhost:4444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
localhost:5444 ..... Done.
|
Initializing registration information on server localhost:5444 with the
|
contents of server localhost:4444 ..... Done.
|
Initializing schema on server localhost:5444 with the contents of server
|
localhost:4444 ..... Done.
|
|
Replication has been successfully enabled. Note that for replication to
|
work you must initialize the contents of the base DN's that are being
|
replicated (use dsreplication initialize to do so).
|
|
See
|
/var/.../opends-replication-7958637258600693490.log
|
for a detailed log of this operation.</screen>
|
|
<para>As you see in the command output, replication is set up to function
|
once enabled. You must however initialize replication in order to start
|
the process, however.</para>
|
|
<para>If you need to add another OpenDJ directory server to participate
|
in replication, use the <command>dsreplication enable</command> with
|
the new server as the second server.</para>
|
</section>
|
|
<section>
|
<title>Initializing Replicas</title>
|
|
<para>Although you can enable replication before you have user data, you
|
must initialize replication after you enable it for the first time.</para>
|
|
<para>You can perform initialization either over the replication protocol,
|
by importing the same LDIF data on all server before performing
|
initialization when starting out, by importing data from LDIF that you
|
exported from another replica when adding a server to the topology, or by
|
restoring a backup from an existing replica onto a new server.</para>
|
|
<procedure>
|
<title>To Initialize Online</title>
|
|
<step>
|
<para>Make sure you have enabled servers you want to participate in
|
replication.</para>
|
</step>
|
<step>
|
<para>Start replication with the <command>dsreplication
|
initialize-all</command> command.</para>
|
|
<screen width="80">$ dsreplication initialize-all -I admin -w password -X -n -b dc=example,dc=com \
|
> -h `hostname` -p 4444
|
|
Initializing base DN dc=example,dc=com with the contents from localhost:4444:
|
160 entries processed (100 % complete).
|
Base DN initialized successfully.
|
|
See
|
/var/.../opends-replication-5020375834904394170.log
|
for a detailed log of this operation.</screen>
|
</step>
|
</procedure>
|
|
<procedure>
|
<title>To Initialize All Servers From the Same LDIF</title>
|
|
<para>Follow these steps to prepare a replication topology starting from
|
directory data in LDIF.</para>
|
|
<step>
|
<para>Import the same LDIF on all servers you want to participate in
|
replication.</para>
|
</step>
|
<step>
|
<para>Make sure you have enabled servers you want to participate in
|
replication.</para>
|
</step>
|
<step>
|
<para>Start replication with the <command>dsreplication
|
initialize-all</command> command.</para>
|
<screen width="80">$ dsreplication initialize-all -I admin -w password -X -n -b dc=example,dc=com \
|
> ;-h `hostname` -p 4444
|
Initializing base DN dc=example,dc=com with the contents from localhost:4444:
|
161 entries processed (100 % complete).
|
Base DN initialized successfully.
|
|
See
|
/var/.../opends-replication-5745536041520679254.log
|
for a detailed log of this operation.</screen>
|
</step>
|
</procedure>
|
|
<procedure>
|
<title>To Create a New Replica From Existing Backup</title>
|
|
<para>You can create a new replica from a backup of an existing replica.
|
The <command>dsreplication</command> commands use differ slightly from
|
the other cases, as you must reset the generation ID on the new replica,
|
such that replication can proceed from the proper starting point.
|
Follow these steps to add another server to the topology by restoring
|
from a backup copy of an existing server.</para>
|
|
<step>
|
<para>Install a new server to serve as the new replica.</para>
|
</step>
|
<step>
|
<para>Backup the database to replica on an existing server.</para>
|
</step>
|
<step>
|
<para>Enable replication on the new replica.</para>
|
<screen width="80">
|
$ dsreplication enable -I admin -w password -X -n -b dc=example,dc=com \
|
> --host1 `hostname` --port1 4444 --bindDN1 "cn=Directory Manager" \
|
> --bindPassword1 password --replicationPort1 8989 \
|
> --host2 `hostname` --port2 6444 --bindDN2 "cn=Directory Manager" \
|
> --bindPassword2 password --replicationPort2 10989
|
|
Establishing connections ..... Done.
|
Checking registration information ..... Done.
|
Updating remote references on server localhost:4444 ..... Done.
|
Configuring Replication port on server localhost:6444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
localhost:4444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
localhost:6444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
localhost:5444 ..... Done.
|
Updating remote references on server localhost:5444 ..... Done.
|
Updating registration configuration on server localhost:4444 ..... Done.
|
Updating registration configuration on server localhost:6444 ..... Done.
|
Updating registration configuration on server localhost:5444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
localhost:4444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
localhost:6444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
localhost:5444 ..... Done.
|
Initializing registration information on server localhost:6444 with the
|
contents of server localhost:4444 ..... Done.
|
|
Replication has been successfully enabled. Note that for replication to
|
work you must initialize the contents of the base DN's that are being
|
replicated (use dsreplication initialize to do so).
|
|
See
|
/var/.../opends-replication-1672058070147419978.log
|
for a detailed log of this operation.</screen>
|
</step>
|
<step>
|
<para>Prepare the new replica for initialization.</para>
|
<screen width="80">$ dsreplication pre-external-initialization -I admin -w password -X -n -p 6444 \
|
> -b dc=example,dc=com
|
|
Preparing base DN dc=example,dc=com to be initialized externally ..... Done.
|
|
Now you can proceed to the initialization of the contents of the base DN's on all the replicated servers. You can use the command import-ldif or the binary copy to do so. You must use the same LDIF file or binary copy on each server.
|
|
When the initialization is completed you must use the subcommand 'post-external-initialization' for replication to work with the new base DN's contents.</screen>
|
</step>
|
<step>
|
<para>Restore the new server database from the backup archive.</para>
|
</step>
|
<step>
|
<para>Initialize replication on the new replica.</para>
|
<screen width="80">$ dsreplication post-external-initialization -I admin -w password -X -n \
|
> -p 6444 -b dc=example,dc=com
|
|
Updating replication information on base DN dc=example,dc=com ..... Done.
|
|
Post initialization procedure completed successfully.</screen>
|
</step>
|
</procedure>
|
</section>
|
|
<section>
|
<title>Stopping Replication</title>
|
|
<para>How you stop replication depends on whether the change is meant to
|
be temporary, or meant to be permanent.</para>
|
|
<procedure>
|
<title>To Stop Replication Temporarily For a Replica</title>
|
|
<para>If you need to stop a server from replicating temporarily, you can
|
do so using <command>dsconfig</command> command. Do not update directory
|
data on the server while replication is interrupted.</para>
|
|
<step>
|
<para>Get the replication server property that identifies one of the
|
replication service host:port combinations that you need to restart
|
replication.</para>
|
<screen width="80">$ dsconfig -p 5444 -h `hostname` -D "cn=Directory Manager" -w password \
|
> get-replication-server-prop --provider-name "Multimaster Synchronization" \
|
> --property replication-server -X
|
Property : Value(s)
|
-------------------:-----------------------------------------------------------
|
replication-server : localhost:8989,
|
: localhost:9989</screen>
|
</step>
|
<step>
|
<para>Reset the replication server property to the default (no
|
replication server) to pause replication.</para>
|
<screen width="80">$ dsconfig -p 5444 -h `hostname` -D "cn=Directory Manager" -w password \
|
> set-replication-server-prop --provider-name "Multimaster Synchronization" \
|
> --reset replication-server -X -n</screen>
|
<para>Do not modify the replica for which replication is paused.</para>
|
</step>
|
<step performance="optional">
|
<para>When you are ready to resume replication, set the replication server
|
property to the host:port combination of an active replication server.</para>
|
<screen width="80">$ dsconfig -p 5444 -h `hostname` -D "cn=Directory Manager" -w password \
|
> set-replication-server-prop --provider-name "Multimaster Synchronization" \
|
> --set replication-server:localhost:8989 -X -n</screen>
|
</step>
|
</procedure>
|
|
<procedure>
|
<title>To Stop Replication Permanently For a Replica</title>
|
|
<para>If you need to stop a server from replicating permanently, for
|
example in preparation to remove a server, you can do so with the
|
<command>dsreplication disable</command> command.</para>
|
|
<step>
|
<para>Stop replication using the <command>dsreplication disable</command>
|
command.</para>
|
<screen width="80">$ dsreplication disable -a -p 5444 -h `hostname` -D "cn=Directory Manager" \
|
> -w password -X -n
|
Establishing connections ..... Done.
|
Disabling replication on base DN cn=admin data of server localhost:5444
|
..... Done.
|
Disabling replication on base DN dc=example,dc=com of server localhost:5444
|
..... Done.
|
Disabling replication on base DN cn=schema of server localhost:5444 ..... Done.
|
Disabling replication port 9989 of server localhost:5444 ..... Done.
|
Removing registration information ..... Done.
|
Removing truststore information ..... Done.
|
|
See
|
/var/.../opends-replication-125248191132797765.log
|
for a detailed log of this operation.</screen>
|
<para>The <command>dsreplication disable</command> as shown removes the
|
replication configuration information.</para>
|
</step>
|
<step performance="optional">
|
<para>If you want to restart replication for the server, you use the
|
<command>dsreplication enable</command> and <command>dsreplication
|
initialize</command> commands again.</para>
|
</step>
|
</procedure>
|
</section>
|
|
<section>
|
<title>Stand-alone Replication Servers</title>
|
|
<para>Replication in OpenDJ is designed to be both easy to implement in
|
environments with a few servers, and also scalable in environments with
|
many servers. You can enable the replication service on each OpenDJ
|
directory server in your deployment, for example, to limit the number
|
of servers you deploy. Yet in a large deployment, you can use stand-alone
|
replication servers — OpenDJ servers that do nothing but relay
|
replication messages — to configure (and troubleshoot) the replication
|
service separately from the directory service. You only need a few
|
stand-alone replication servers publishing changes to serve many directory
|
servers subscribed to the changes. Furthermore, replication is designed
|
such that you need only connect a directory server to the nearest
|
replication server for the directory server to replicate with all others
|
in your topology. Yet only the stand-alone replication servers participate
|
in fully-meshed replication.</para>
|
|
|
<procedure>
|
<title>To Set Up a Stand-alone Replication Server</title>
|
|
<para>This example sets up a stand-alone replication server to handle
|
the replication traffic between two directory servers that do not
|
handle replication themselves.</para>
|
|
<para>Here the replication server has admin port 6444. The directory
|
servers have admin ports 4444 and 5444.</para>
|
|
<para>In a real deployment, you would have more replication servers
|
to avoid a single point of failure.</para>
|
|
<step>
|
<para>Setup the replication server as a directory server that has
|
no database.</para>
|
</step>
|
<step>
|
<para>Setup the directory servers as stand-alone directory servers.</para>
|
</step>
|
<step>
|
<para>Enable replication with the appropriate
|
<option>--noReplicationServer</option> and
|
<option>--onlyReplicationServer</option> options.</para>
|
<screen width="80">$ dsreplication enable -I admin -w password -X -n -b dc=example,dc=com \
|
> --host1 `hostname` --port1 4444 --bindDN1 "cn=Directory Manager" \
|
> --bindPassword1 password --noReplicationServer1 \
|
> --host2 `hostname` --port2 6444 --bindDN2 "cn=Directory Manager" \
|
> --bindPassword2 password --replicationPort2 8989 --onlyReplicationServer2
|
Establishing connections ..... Done.
|
Only one replication server will be defined for the following base DN's:
|
dc=example,dc=com
|
It is recommended to have at least two replication servers (two changelogs) to
|
avoid a single point of failure in the replication topology.
|
|
Checking registration information ..... Done.
|
Configuring Replication port on server localhost:6444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
localhost:4444 ..... Done.
|
Updating registration configuration on server localhost:4444 ..... Done.
|
Updating registration configuration on server localhost:6444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
localhost:4444 ..... Done.
|
Initializing registration information on server localhost:6444 with the
|
contents of server localhost:4444 ..... Done.
|
|
Replication has been successfully enabled. Note that for replication to work
|
you must initialize the contents of the base DN's that are being
|
replicated (use dsreplication initialize to do so).
|
|
See
|
/var/.../opends-replication-1720959352638609971.log
|
for a detailed log of this operation.
|
|
$ dsreplication enable -I admin -w password -X -n -b dc=example,dc=com \
|
> --host1 `hostname` --port1 5444 --bindDN1 "cn=Directory Manager" \
|
> --bindPassword1 password --noReplicationServer1 \
|
> --host2 `hostname` --port2 6444 --bindDN2 "cn=Directory Manager" \
|
> --bindPassword2 password --replicationPort2 8989 --onlyReplicationServer2
|
|
Establishing connections ..... Done.
|
Only one replication server will be defined for the following base DN's:
|
dc=example,dc=com
|
It is recommended to have at least two replication servers (two changelogs) to
|
avoid a single point of failure in the replication topology.
|
|
Checking registration information ..... Done.
|
Updating remote references on server localhost:6444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
localhost:5444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
localhost:4444 ..... Done.
|
Updating registration configuration on server localhost:5444 ..... Done.
|
Updating registration configuration on server localhost:6444 ..... Done.
|
Updating registration configuration on server localhost:4444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
localhost:5444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
localhost:4444 ..... Done.
|
Initializing registration information on server localhost:5444 with the
|
contents of server localhost:6444 ..... Done.
|
|
Replication has been successfully enabled. Note that for replication to work
|
you must initialize the contents of the base DN's that are being
|
replicated (use dsreplication initialize to do so).
|
|
See
|
/var/folders/.../opends-replication-5893037538856033562.log
|
for a detailed log of this operation.</screen>
|
</step>
|
<step>
|
<para>Initialize replication from one of the directory servers.</para>
|
<screen width="80">$ dsreplication initialize-all -I admin -w password -X -n -b dc=example,dc=com \
|
> -h `hostname` -p 4444
|
|
Initializing base DN dc=example,dc=com with the contents from localhost:4444:
|
160 entries processed (100 % complete).
|
Base DN initialized successfully.
|
|
See
|
/var/.../opends-replication-7677303986403997574.log
|
for a detailed log of this operation.</screen>
|
</step>
|
</procedure>
|
</section>
|
|
<section>
|
<title>Replication Groups</title>
|
|
<para>Replication lets you define groups so that replicas communicate
|
first with replication servers in the group before going to replication
|
servers outside the group. Groups are identified with unique numeric
|
group IDs.</para>
|
|
<procedure>
|
<title>To Set Up Replication Groups</title>
|
|
<para>For each group, set the appropriate group ID for the topology
|
on both the replication servers and the directory servers.</para>
|
|
<para>The example commands in this procedure set up two replication
|
groups, each with a replication server and a directory server. The
|
directory servers have admin ports 4444 and 5444. The replication servers
|
have admin ports 6444 and 7444. In a full-scale deployment, you would
|
have multiple servers of each type in each group, such as all the replicas
|
and replication servers in each data center being in the same group.</para>
|
|
<step>
|
<para>Pick a group ID for each group.</para>
|
<para>The default group ID is 1.</para>
|
</step>
|
<step>
|
<para>Set the group ID for each group by replication domain on the
|
directory servers.</para>
|
<screen width="80">$ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
|
> set-replication-domain-prop --provider-name "MultimasterSynchronization" \
|
> --domain-name "dc=example,dc=com" --set group-id:1 -X -n
|
|
$ dsconfig -p 5444 -h `hostname` -D "cn=Directory Manager" -w password \
|
> set-replication-domain-prop --provider-name "Multimaster Synchronization" \
|
> --domain-name "dc=example,dc=com" --set group-id:2 -X -n</screen>
|
</step>
|
<step>
|
<para>Set the group ID for each group on the replication servers.</para>
|
<screen width="80">$ dsconfig -p 6444 -h `hostname` -D "cn=Directory Manager" -w password \
|
> set-replication-server-prop --provider-name "Multimaster Synchronization" \
|
> --set group-id:1 -X -n
|
$ dsconfig -p 7444 -h `hostname` -D "cn=Directory Manager" -w password \
|
> set-replication-server-prop --provider-name "Multimaster Synchronization" \
|
> --set group-id:2 -X -n</screen>
|
</step>
|
</procedure>
|
</section>
|
|
<section>
|
<title>Read-Only Replicas</title>
|
|
<para>By default all directory servers in a replication topology are
|
read-write. You can however choose to make replicas take updates only
|
from the replication protocol, and refuse updates from client
|
applications.</para>
|
|
<screen width="80">$ dsconfig -p 5444 -h `hostname` -D "cn=Directory Manager" -w password \
|
> set-global-configuration-prop --set writability-mode:internal-only -X -n</screen>
|
</section>
|
|
<section>
|
<title>Assured Replication</title>
|
|
<para>In standard replication, when a client requests an update operation
|
the directory server performs the update and, if the update is successful,
|
sends information about the update to the replication service, and sends
|
a result code to the client application right away. As a result, the
|
client application can conclude that the update was successful,
|
<emphasis>but only on the replica that handled the update</emphasis>.</para>
|
|
<para>Assured replication lets you force the replica performing the initial
|
update to wait for confirmation that the update has been received elsewhere
|
in the topology before sending a result code to the client application.
|
You can configure assured replication either to wait for one or more
|
replication servers to acknowledge having received the update, or to wait
|
for all directory servers to have replayed the update.</para>
|
|
<para>As you might imagine, assured replication is theoretically safer than
|
standard replication, yet it is also slower, potentially waiting for a
|
timeout before failing when the network or other servers are down.</para>
|
|
<procedure>
|
<title>To Ensure Updates Reach Replication Servers</title>
|
|
<para>Safe data mode requires the update be sent to
|
<literal>assured-sd-level</literal> replication servers before
|
acknowledgement is returned to the client application.</para>
|
|
<step>
|
<para>For each directory server, set safe data mode for the replication
|
domain, and also set the safe data level.</para>
|
|
<screen width="80">$ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
|
> set-replication-domain-prop --provider-name "Multimaster Synchronization" \
|
> --domain-name "dc=example,dc=com" \
|
> --set assured-type:safe-data --set assured-sd-level:1 -X -n
|
|
$ dsconfig -p 5444 -h `hostname` -D "cn=Directory Manager" -w password \
|
> set-replication-domain-prop --provider-name "Multimaster Synchronization" \
|
> --domain-name "dc=example,dc=com" \
|
> --set assured-type:safe-data --set assured-sd-level:1 -X -n</screen>
|
</step>
|
</procedure>
|
|
<procedure>
|
<title>To Ensure Updates Are Replayed Everywhere</title>
|
|
<para>Safe read mode requires the update be replayed on all directory
|
servers before acknowledgement is returned to the client application.</para>
|
|
<step>
|
<para>For each directory server, set safe read mode for the replication
|
domain.</para>
|
|
<screen width="80">$ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
|
> set-replication-domain-prop --provider-name "Multimaster Synchronization" \
|
> --domain-name "dc=example,dc=com" --set assured-type:safe-read -X -n
|
|
$ dsconfig -p 5444 -h `hostname` -D "cn=Directory Manager" -w password \
|
> set-replication-domain-prop --provider-name "Multimaster Synchronization" \
|
> --domain-name "dc=example,dc=com" --set assured-type:safe-read -X -n</screen>
|
</step>
|
</procedure>
|
|
<para>When working with assured replication, the replication server property
|
<literal>degraded-status-threshold</literal> (default: 5000), sets the
|
number of operations allowed to build up in the replication queue before
|
the server is assigned degraded status. When a replication server has
|
degraded status, assured replication ceases to have an effect.</para>
|
</section>
|
|
<section>
|
<title>Subtree Replication</title>
|
|
<para>OpenDJ lets you do subtree replication, for example replicating
|
<literal>ou=People,dc=example,dc=com</literal>, but not the rest of
|
<literal>dc=example,dc=com</literal>, by putting the subtree in a separate
|
backend from the rest of the suffix.</para>
|
|
<para>For example, in this case you might have a <literal>userRoot</literal>
|
backend containing everything in <literal>dc=example,dc=com</literal>
|
except <literal>ou=People,dc=example,dc=com</literal>, and a separate
|
<literal>peopleRoot</literal> backend for
|
<literal>ou=People,dc=example,dc=com</literal>. Then you replicate
|
<literal>ou=People,dc=example,dc=com</literal> in its own topology.</para>
|
</section>
|
|
<section>
|
<title>Fractional Replication</title>
|
|
<para>OpenDJ lets you do fractional replication, whereby you specify
|
the attributes to include in the replication process, or alternatively
|
specify the attributes to exclude.</para>
|
|
<para>You set fractional replication configuration as
|
<literal>fractional-include</literal> or
|
<literal>fractional-exclude</literal> properties for a replication
|
domain. When you include attributes, the attributes that must be kept on
|
the relevant object classes are also included, whether you specify them
|
or not. When you exclude attributes, the excluded attributes must be
|
optional attributes for the relevant object classes. Fractional
|
replica still respect schema definitions.</para>
|
|
<para>For example, you might configure an externally facing
|
fractional replica to include only some <literal>inetOrgPerson</literal>
|
attributes.</para>
|
|
<screen width="80">$ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
|
> set-replication-domain-prop --provider-name "Multimaster Synchronization" \
|
--domain-name "dc=example,dc=com" -X -n --set \
|
fractional-include:inetorgperson:cn,givenname,mail,mobile,sn,telephonenumber</screen>
|
|
<para>As another example, you might exclude a custom attribute called
|
<literal>sessionToken</literal> from being replicated.</para>
|
|
<screen width="80">dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
|
> set-replication-domain-prop --provider-name "Multimaster Synchronization" \
|
--domain-name "dc=example,dc=com" --set fractional-exclude:*:sessionToken -X -n</screen>
|
|
<para>This last example only works if you first define a sessionToken
|
attribute in the directory server schema.</para>
|
</section>
|
</section>
|
|
<section>
|
<title>Change Notification For Your Applications</title>
|
|
<para>Some applications require notification when directory data updates
|
occur. For example, an application might need to sync directory data with
|
another database, or the application might need to kick off other processing
|
when certain updates occur.</para>
|
|
<para>In addition to supporting peristent search operations, OpenDJ
|
provides an external change log mechanism to allow applications to be
|
notified of changes to directory data.</para>
|
|
<procedure>
|
<title>To Enable the External Change Log</title>
|
|
<para>OpenDJ directory servers not using replication cannnot expose an
|
external change log. The OpenDJ server that exposes the change log must
|
function both as a directory server, and also as a replication server for
|
the suffix whose changes you want logged.</para>
|
|
<step>
|
<para>Enable replication without using the <option>--</option> or
|
<option>--</option> options.</para>
|
|
<para>With replication enabled, the changelog data can be accessed under
|
<literal>cn=changelog</literal>. For example, the following search shows
|
the publicly visible data available before any changes have been
|
made.</para>
|
|
<screen width="80">$ ldapsearch -b cn=changelog -p 1389 "(objectclass=*)" \* +
|
dn: cn=changelog
|
cn: changelog
|
objectClass: top
|
objectClass: container
|
subschemaSubentry: cn=schema
|
hasSubordinates: false
|
entryDN: cn=changelog
|
</screen>
|
</step>
|
</procedure>
|
|
<procedure>
|
<title>To Use the External Change Log</title>
|
|
<para>You read the external change log over protocol. In addition, when you
|
poll the change log periodically, you can get the list of updates that
|
happened since your last request.</para>
|
|
<para>The external change log mechanism uses an LDAP control with
|
OID <literal>1.3.6.1.4.1.26027.1.5.4</literal> to allow the exchange
|
of cookies for the client application to bookmark the last changes seen,
|
and then start reading the next set of changes from where it left off on
|
the previous request.</para>
|
|
<para>This procedure shows the client reading the change log as
|
<literal>cn=Directory Manager</literal>. Make sure your client application
|
reads the changes with sufficient access to view all the changes it
|
needs to see.</para>
|
|
<step>
|
<para>Send an initial search request using the LDAP control with no
|
cookie value.</para>
|
|
<para>Notice the value of the <literal>changeLogCookie</literal> attribute
|
for the last of the two changes.</para>
|
|
<screen width="80">$ ldapsearch -b cn=changelog -p 1389 -D "cn=Directory Manager" -w password \
|
> -J "1.3.6.1.4.1.26027.1.5.4:false" "(objectclass=*)" \* +
|
dn: cn=changelog
|
cn: changelog
|
objectClass: top
|
objectClass: container
|
subschemaSubentry: cn=schema
|
hasSubordinates: true
|
entryDN: cn=changelog
|
|
# Public changelog exchange control(1.3.6.1.4.1.26027.1.5.4):
|
dc=example,dc=com:0000013087cbc28212d100000001;
|
dn: replicationCSN=0000013087cbc28212d100000001,dc=example,dc=com,cn=changelog
|
targetDN: cn=arsene lupin,ou=special users,dc=example,dc=com
|
changeNumber: 0
|
changes:: b2JqZWN0Q2xhc3M6IHBlcnNvbgpvYmplY3RDbGFzczogdG9wCmNuOiBBcnNlbmUgTHVwaW
|
4KdGVsZXBob25lTnVtYmVyOiArMzMgMSAyMyA0NSA2NyA4OQpzbjogTHVwaW4KZW50cnlVVUlEOiA5M
|
GM3MTRmNy00ODZiLTRkNDctOTQwOS1iNDRkMTlkZWEzMWUKY3JlYXRlVGltZXN0YW1wOiAyMDExMDYx
|
MzA2NTg1NVoKY3JlYXRvcnNOYW1lOiBjbj1EaXJlY3RvcnkgTWFuYWdlcixjbj1Sb290IEROcyxjbj1
|
jb25maWcK
|
changeType: add
|
changeTime: 20110613065855Z
|
objectClass: top
|
objectClass: changeLogEntry
|
targetEntryUUID: 90c714f7-486b-4d47-9409-b44d19dea31e
|
replicationCSN: 0000013087cbc28212d100000001
|
numSubordinates: 0
|
replicaIdentifier: 4817
|
changeLogCookie: dc=example,dc=com:0000013087cbc28212d100000001;
|
changeInitiatorsName: cn=Directory Manager,cn=Root DNs,cn=config
|
subschemaSubentry: cn=schema
|
hasSubordinates: false
|
entryDN: replicationCSN=0000013087cbc28212d100000001,dc=example,dc=com,cn=change
|
log
|
|
# Public changelog exchange control(1.3.6.1.4.1.26027.1.5.4):
|
dc=example,dc=com:0000013087cbc34a12d100000002;
|
dn: replicationCSN=0000013087cbc34a12d100000002,dc=example,dc=com,cn=changelog
|
targetDN: cn=horace velmont,ou=special users,dc=example,dc=com
|
changeNumber: 0
|
changes:: b2JqZWN0Q2xhc3M6IHBlcnNvbgpvYmplY3RDbGFzczogdG9wCmNuOiBIb3JhY2UgVmVsbW
|
9udAp0ZWxlcGhvbmVOdW1iZXI6ICszMyAxIDEyIDIzIDM0IDQ1CnNuOiBWZWxtb250CmVudHJ5VVVJR
|
DogNmIyMjQ0MGEtNzZkMC00MDMxLTk0YjctMzViMWQ4NmYwNjdlCmNyZWF0ZVRpbWVzdGFtcDogMjAx
|
MTA2MTMwNjU4NTVaCmNyZWF0b3JzTmFtZTogY249RGlyZWN0b3J5IE1hbmFnZXIsY249Um9vdCBETnM
|
sY249Y29uZmlnCg==
|
changeType: add
|
changeTime: 20110613065855Z
|
objectClass: top
|
objectClass: changeLogEntry
|
targetEntryUUID: 6b22440a-76d0-4031-94b7-35b1d86f067e
|
replicationCSN: 0000013087cbc34a12d100000002
|
numSubordinates: 0
|
replicaIdentifier: 4817
|
<emphasis>changeLogCookie: dc=example,dc=com:0000013087cbc34a12d100000002;</emphasis>
|
changeInitiatorsName: cn=Directory Manager,cn=Root DNs,cn=config
|
subschemaSubentry: cn=schema
|
hasSubordinates: false
|
entryDN: replicationCSN=0000013087cbc34a12d100000002,dc=example,dc=com,cn=change
|
log
|
</screen>
|
|
<para>In this example, two new users were added to another replica
|
before the change log request was made.</para>
|
|
<para>Here the changes are base64 encoded, so you can decode them using
|
the <command>base64</command> command.</para>
|
|
<screen>$ base64 decode -d b2JqZW...ZmlnCg==
|
objectClass: person
|
objectClass: top
|
cn: Horace Velmont
|
telephoneNumber: +33 1 12 23 34 45
|
sn: Velmont
|
entryUUID: 6b22440a-76d0-4031-94b7-35b1d86f067e
|
createTimestamp: 20110613065855Z
|
creatorsName: cn=Directory Manager,cn=Root DNs,cn=config
|
</screen>
|
</step>
|
|
<step>
|
<para>For the next search, provide the cookie to start reading where
|
you left off last time.</para>
|
|
<para>In this example, a description was added to Babs Jensen's entry.</para>
|
|
<screen width="80">$ ldapsearch -b cn=changelog -p 1389 -D "cn=Directory Manager" -w password \
|
> -J "1.3.6.1.4.1.26027.1.5.4:false:\
|
> dc=example,dc=com:0000013087cbc34a12d100000002;" "(objectclass=*)" \* +
|
dn: cn=changelog
|
cn: changelog
|
objectClass: top
|
objectClass: container
|
subschemaSubentry: cn=schema
|
hasSubordinates: true
|
entryDN: cn=changelog
|
|
# Public changelog exchange control(1.3.6.1.4.1.26027.1.5.4):
|
dc=example,dc=com:0000013087d7e27f12d100000003;
|
dn: replicationCSN=0000013087d7e27f12d100000003,dc=example,dc=com,cn=changelog
|
targetDN: uid=bjensen,ou=people,dc=example,dc=com
|
changeNumber: 0
|
changes:: YWRkOiBkZXNjcmlwdGlvbgpkZXNjcmlwdGlvbjogQSB0aGlyZCBjaGFuZ2UKLQpyZXBsYW
|
NlOiBtb2RpZmllcnNOYW1lCm1vZGlmaWVyc05hbWU6IGNuPURpcmVjdG9yeSBNYW5hZ2VyLGNuPVJvb
|
3QgRE5zLGNuPWNvbmZpZwotCnJlcGxhY2U6IG1vZGlmeVRpbWVzdGFtcAptb2RpZnlUaW1lc3RhbXA6
|
IDIwMTEwNjEzMDcxMjEwWgotCg==
|
changeType: modify
|
changeTime: 20110613071210Z
|
objectClass: top
|
objectClass: changeLogEntry
|
targetEntryUUID: fc252fd9-b982-3ed6-b42a-c76d2546312c
|
replicationCSN: 0000013087d7e27f12d100000003
|
numSubordinates: 0
|
replicaIdentifier: 4817
|
changeLogCookie: dc=example,dc=com:0000013087d7e27f12d100000003;
|
changeInitiatorsName: cn=Directory Manager,cn=Root DNs,cn=config
|
subschemaSubentry: cn=schema
|
hasSubordinates: false
|
entryDN: replicationCSN=0000013087d7e27f12d100000003,dc=example,dc=com,cn=change
|
log
|
</screen>
|
|
<para>If we base64-decode the changes, we see the following.</para>
|
|
<screen width="80">$ base64 decode -d YWRkO...gotCg==
|
add: description
|
description: A third change
|
-
|
replace: modifiersName
|
modifiersName: cn=Directory Manager,cn=Root DNs,cn=config
|
-
|
replace: modifyTimestamp
|
modifyTimestamp: 20110613071210Z
|
-
|
</screen>
|
</step>
|
<step>
|
<para>If for some reason you lose the cookie, you can start over from
|
the earliest available change by sending a search request with no
|
value for the cookie.</para>
|
</step>
|
</procedure>
|
|
<para>The external change log can also operate in a mode compatible with the
|
<link xlink:href="http://tools.ietf.org/html/draft-good-ldap-changelog-04"
|
>Internet-Draft: Definition of an Object Class to Hold LDAP Change
|
Records</link>. Thus, you can use the change log with legacy applications
|
that require this format without using cookies that facilitate retrieving
|
updates in a multi-master replication environment.</para>
|
</section>
|
</chapter>
|
