<?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 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-2015 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'>
|
<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 xml:id="repl-quick-setup">
|
<title>Replication Quick Setup</title>
|
<indexterm>
|
<primary>Replication</primary>
|
<secondary>Quick setup</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>High availability</primary>
|
<see>Replication</see>
|
</indexterm>
|
|
<itemizedlist>
|
<para>
|
You can set up replication during installation by using the setup wizard,
|
starting with the Topology Options screen.
|
</para>
|
|
<listitem>
|
<para>
|
In the Topology Options screen for the first server you set up,
|
select This server will be part of a replication topology.
|
</para>
|
|
<para>
|
If you also choose Configure as Secure,
|
then replication traffic is protected by Transport Layer Security.
|
</para>
|
</listitem>
|
|
<listitem>
|
<para>
|
In the Topology Options screen for subsequent servers,
|
select There is already a server in the topology.
|
</para>
|
|
<para>
|
Provide the Host Name, Administration Connector Port number,
|
global Admin User identifier, and Admin Password for the first server.
|
</para>
|
</listitem>
|
|
<listitem>
|
<para>
|
When presented with the Create Global Administrator screen,
|
provide a Global Administrator ID and Global Administrator Password.
|
</para>
|
|
<para>
|
The Global Administrator account exists on all servers
|
in the replication topology.
|
The account is stored under <literal>cn=admin data</literal>.
|
It provides an account to administer replication
|
with the same credentials on every server in the topology.
|
</para>
|
</listitem>
|
|
<listitem>
|
<para>
|
In the Data Replication screen,
|
select the user and application data base DN(s) to replicate.
|
</para>
|
|
<para>
|
OpenDJ directory server automatically replicates
|
configuration data and directory schema.
|
</para>
|
</listitem>
|
</itemizedlist>
|
|
<para>
|
Once replication is set up, it works for all the replicas.
|
You can monitor replication status through OpenDJ Control Panel.
|
</para>
|
</section>
|
|
<section xml:id="about-repl">
|
<title>About Replication</title>
|
<indexterm>
|
<primary>Replication</primary>
|
<secondary>Overview</secondary>
|
</indexterm>
|
|
<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>
|
|
<section xml:id="repl-what-it-is">
|
<title>What Replication Is</title>
|
|
<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 must
|
ensure that you do not purge the historical information more often than you
|
backup your directory data.</para>
|
|
<para>Keep server clocks synchronized for your topology. You can use NTP for
|
example. Keeping server clocks synchronized helps prevent issues with SSL
|
connections and with replication itself. Keeping server clocks synchronized
|
also makes it easier to compare timestamps from multiple servers.</para>
|
</section>
|
|
<section xml:id="repl-per-suffix">
|
<title>Replication Per Suffix</title>
|
|
<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 OpenDJ servers replicating data for 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>. OpenDJ servers are capable of
|
serving more than one suffix. They are also capable of participating in
|
more than one replication topology.</para>
|
|
<mediaobject xml:id="figure-replication-topologies-right">
|
<alt>Three replication topologies set up correctly</alt>
|
<imageobject>
|
<imagedata fileref="images/repl-topologies-right.png" format="PNG" />
|
</imageobject>
|
<textobject>
|
<para>In this figure, all OpenDJ servers serve the replicated suffix
|
<literal>dc=example,dc=com</literal>. Only servers A and B serve
|
<literal>dc=example,dc=org</literal>. Only server C and D serve
|
<literal>dc=example,dc=net</literal>.</para>
|
</textobject>
|
</mediaobject>
|
|
<para>
|
Within a replication topology,
|
the suffixes being replicated are identified to the replication servers by their DNs.
|
All the replication servers are fully connected in a topology.
|
Consequently it is impossible to have multiple separate, independent topologies
|
for data under the same DN within the overall set of servers.
|
This is illustrated in the following diagram.
|
</para>
|
|
<mediaobject xml:id="figure-replication-topologies-wrong">
|
<alt>Two replication topologies, one of which does not work</alt>
|
<imageobject>
|
<imagedata fileref="images/repl-topologies-wrong.png" format="PNG" />
|
</imageobject>
|
<textobject>
|
<para>You cannot have all servers replicating both
|
<literal>dc=example,dc=com</literal> and also
|
<literal>dc=example,dc=org</literal>, but with all servers connected for
|
<literal>dc=example,dc=com</literal> and only some of the servers
|
connected for <literal>dc=example,dc=org</literal>.</para>
|
</textobject>
|
</mediaobject>
|
</section>
|
|
<section xml:id="repl-connection-selection">
|
<title>Replication Connection Selection</title>
|
|
<para>In order to understand what happens when individual servers stop
|
responding due to a network partition or a crash, know that OpenDJ can
|
offer both directory service and also replication service, and the two
|
services are not the same, even if they can run alongside each other in
|
the same OpenDJ server in the same Java Virtual Machine.</para>
|
|
<para>Replication relies on the replication service provided by OpenDJ
|
replication servers, where OpenDJ directory servers publish changes made
|
to their data, and subscribe to changes published by other OpenDJ directory
|
servers. A replication server manages replication data only, handling
|
replication traffic with directory servers and with other replication
|
servers, receiving, sending, and storing only changes to directory data
|
rather than directory data itself. Once a replication server is connected
|
to a replication topology, it maintains connections to all other
|
replication servers in that topology.</para>
|
|
<para>A directory server handles directory data. It responds to requests,
|
stores directory data and historical information. For each replicated
|
suffix, such as <literal>dc=example,dc=com</literal>,
|
<literal>cn=schema</literal> and <literal>cn=admin data</literal>, the
|
directory server publishes changes to a replication server, and subscribes
|
to changes from that replication server. (Directory servers do not publish
|
changes to other directory servers.) A directory server also resolves any
|
conflicts that arise when reconciling changes from other directory servers,
|
using the historical information about changes to resolve the conflicts.
|
(Conflict resolution is the responsibility of the directory server rather
|
than the replication server.)</para>
|
|
<para>Once a directory server is connected to a replication topology for a
|
particular suffix, it connects to one replication server at a time for that
|
suffix. The replication server provides the directory server with a list of
|
all replication servers for that suffix. Given the list of possible
|
replication servers to which it can connect, the directory server can
|
determine which replication server to connect to when starting up, or when
|
the current connection is lost or becomes unresponsive.</para>
|
|
<orderedlist>
|
<para>For each replicated suffix, a directory server prefers to connect to
|
a replication server:</para>
|
|
<listitem>
|
<para>In the same group as the directory server</para>
|
</listitem>
|
|
<listitem>
|
<para>Having the same initial data for the suffix as the directory
|
server</para>
|
</listitem>
|
|
<listitem>
|
<para>If initial data were the same, having all the latest changes from
|
the directory server</para>
|
</listitem>
|
|
<listitem>
|
<para>Running in the same Java Virtual Machine as the directory
|
server</para>
|
</listitem>
|
|
<listitem>
|
<para>Having the most available capacity relative to other eligible
|
replication servers</para>
|
|
<para>Available capacity depends on how many directory servers in the
|
topology are already connected to a replication server, and what
|
proportion of all directory servers in the topology ought to be connected
|
to the replication server.</para>
|
|
<para>To determine what proportion of the total number of directory
|
servers should be connected to a replication server, OpenDJ uses
|
replication server weight. When configuring a replication server, you
|
can assign it a weight (default: 1). The weight property takes an integer
|
that indicates capacity to provide replication service relative to other
|
servers. For example, a weight of 2 would indicate a replication server
|
that can handle twice as many connected servers as a replication server
|
with weight 1.</para>
|
|
<para>The proportion of directory servers in a topology that should be
|
connected to a given replication server is equal to (replication server
|
weight)/(sum of replication server weights). In other words, if there are
|
4 replication servers in a topology each with default weights, the
|
proportion for each replication server is 1/4.</para>
|
</listitem>
|
</orderedlist>
|
|
<para>Consider a situation where 7 directory servers are connected to
|
replication servers A, B, C, and D for <literal>dc=example,dc=com</literal>
|
data. Suppose 2 directory servers each are connected to A, B, and C, and 1
|
directory server is connected to replication server D. Replication server D
|
is therefore the server with the most available capacity relative to other
|
replication servers in the topology. All other criteria being equal,
|
replication server D is the server to connect to when an 8th directory
|
server joins the topology.</para>
|
|
<para>The directory server regularly updates the list of replication servers
|
in case it must reconnect. As available capacity of replication servers for
|
each replication topology can change dynamically, a directory server can
|
potentially reconnect to another replication server to balance the
|
replication load in the topology. For this reason the server can also end
|
up connected to different replication servers for different suffixes.</para>
|
</section>
|
</section>
|
|
<section xml:id="configure-repl">
|
<title>Configuring Replication</title>
|
<indexterm>
|
<primary>Replication</primary>
|
<secondary>Configuring</secondary>
|
</indexterm>
|
|
<para>
|
This section shows how to configure replication with command-line tools,
|
such as the
|
<link
|
xlink:show="new"
|
xlink:href="reference#dsreplication-1"
|
xlink:role="http://docbook.org/xlink/role/olink"
|
><command>dsreplication</command></link> command.
|
</para>
|
|
<section xml:id="enable-repl">
|
<title>Enabling Replication</title>
|
|
<para>You can start the replication process by using the
|
<command>dsreplication enable</command> command.</para>
|
|
<screen>$ <userinput>dsreplication \
|
enable \
|
--adminUID admin \
|
--adminPassword password \
|
--baseDN dc=example,dc=com \
|
--host1 opendj.example.com \
|
--port1 4444 \
|
--bindDN1 "cn=Directory Manager" \
|
--bindPassword1 password \
|
--replicationPort1 8989 \
|
--host2 opendj2.example.com \
|
--port2 4444 \
|
--bindDN2 "cn=Directory Manager" \
|
--bindPassword2 password \
|
--replicationPort2 8989 \
|
--trustAll \
|
--no-prompt</userinput>
|
|
<computeroutput>Establishing connections ..... Done.
|
Checking registration information ..... Done.
|
Updating remote references on server opendj.example.com:4444 ..... Done.
|
Configuring Replication port on server opendj2.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
opendj.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
opendj2.example.com:4444 ..... Done.
|
Updating registration configuration on server
|
opendj.example.com:4444 ..... Done.
|
Updating registration configuration on server
|
opendj2.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
opendj.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
opendj2.example.com:4444 ..... Done.
|
Initializing registration information on server opendj2.example.com:4444 with
|
the contents of server opendj.example.com:4444 ..... Done.
|
Initializing schema on server opendj2.example.com:4444 with the contents of
|
server opendj.example.com: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.</computeroutput>
|
</screen>
|
|
<para>To enable secure connections for replication use the
|
<option>--secureReplication1</option> and
|
<option>--secureReplication2</option> options, which are equivalent to
|
selecting Configure as Secure in the replication topology options screen of
|
the setup wizard.</para>
|
|
<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.</para>
|
|
<tip>
|
<para>When scripting the configuration to set up multiple replicas in quick
|
succession, use the same initial replication server each time you run the
|
command. In other words, pass the same <option>--host1</option>,
|
<option>--port1</option>, <option>--bindDN1</option>,
|
<option>--bindPassword1</option>, and <option>--replicationPort1</option>
|
options for each of the other replicas that you set up in your
|
script.</para>
|
</tip>
|
|
<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 xml:id="init-repl">
|
<title>Initializing Replicas</title>
|
|
<para>You can initialize replication between servers by performing
|
initialization over the network after you have enabled replication, or by
|
importing the same LDIF data on all servers and then enabling replication.
|
You can also add a new server by restoring a backup from an existing replica
|
onto the new server and then enabling replication with an existing
|
replica.</para>
|
|
<itemizedlist>
|
<para>The alternatives are described step-by-step in the following
|
procedures.</para>
|
|
<listitem><para><xref linkend="init-repl-online" /></para></listitem>
|
<listitem><para><xref linkend="init-repl-ldif" /></para></listitem>
|
<listitem><para><xref linkend="init-repl-backup" /></para></listitem>
|
<listitem><para><xref linkend="reinit-repl" /></para></listitem>
|
</itemizedlist>
|
|
<procedure xml:id="init-repl-online">
|
<title>To Initialize Replication Over the Network</title>
|
|
<para>Initialization over the network while the server is online works well
|
when you have no initial data, or when your network bandwidth is large
|
compared to the initial amount of data to replicate.</para>
|
|
<step>
|
<para>Enable replication on all servers.</para>
|
|
<para>See <xref linkend="enable-repl" /> for instructions.</para>
|
</step>
|
|
<step>
|
<para>Start replication with the <command>dsreplication
|
initialize-all</command> command.</para>
|
|
<screen>
|
$ <userinput>dsreplication \
|
initialize-all \
|
--adminUID admin \
|
--adminPassword password \
|
--baseDN dc=example,dc=com \
|
--hostname opendj.example.com \
|
--port 4444 \
|
--trustAll \
|
--no-prompt</userinput>
|
|
<computeroutput>Initializing base DN dc=example,dc=com with the contents from
|
opendj.example.com:4444: 160 entries processed (100 % complete).
|
Base DN initialized successfully.
|
|
See
|
/var/.../opends-replication-5020375834904394170.log
|
for a detailed log of this operation.</computeroutput>
|
</screen>
|
</step>
|
</procedure>
|
|
<procedure xml:id="init-repl-ldif">
|
<title>To Initialize All Servers From the Same LDIF</title>
|
|
<para>This procedure can be useful when you are starting with a large amount
|
of directory data that is available locally to all directory servers.</para>
|
|
<step>
|
<para>Import the same LDIF on all servers as described in the procedure,
|
<link xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
|
xlink:href="admin-guide#import-ldif"><citetitle>To Import LDIF
|
Data</citetitle></link>.</para>
|
|
<para>Do not yet accept updates to the directory data.
|
<xref linkend="read-only-repl" /> shows how to prevent replicas from
|
accepting updates from clients.</para>
|
</step>
|
|
<step>
|
<para>Enable replication for all servers.</para>
|
|
<para>See <xref linkend="enable-repl" /> for instructions.</para>
|
</step>
|
|
<step>
|
<para>Allow updates to the directory data by setting
|
<literal>writability-mode:enabled</literal> using a command like the
|
one you found in <xref linkend="read-only-repl" />.</para>
|
</step>
|
</procedure>
|
|
<procedure xml:id="init-repl-backup">
|
<title>To Create a New Replica From Existing Backup</title>
|
|
<para>You can create a new replica from a backup of a server in the existing
|
topology.</para>
|
|
<step>
|
<para>Install a new server to use as the new replica.</para>
|
</step>
|
|
<step>
|
<para>Backup the database on an existing server as described in
|
<link xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
|
xlink:href="admin-guide#backup"><citetitle>Backing Up Directory
|
Data</citetitle></link>.</para>
|
|
<para>At this point, other servers in the topology can continue to process
|
updates.</para>
|
</step>
|
|
<step>
|
<para>Enable replication on the new replica.</para>
|
|
<screen>
|
$ <userinput>dsreplication \
|
enable \
|
--adminUID admin \
|
--adminPassword password \
|
--baseDN dc=example,dc=com \
|
--host1 opendj.example.com \
|
--port1 4444 \
|
--bindDN1 "cn=Directory Manager" \
|
--bindPassword1 password \
|
--replicationPort1 8989 \
|
--host2 opendj3.example.com \
|
--port2 4444 \
|
--bindDN2 "cn=Directory Manager" \
|
--bindPassword2 password \
|
--replicationPort2 8989 \
|
--trustAll \
|
--no-prompt</userinput>
|
|
<computeroutput>Establishing connections ..... Done.
|
Checking registration information ..... Done.
|
Updating remote references on server opendj.example.com:4444 ..... Done.
|
Configuring Replication port on server opendj3.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
opendj.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
opendj3.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
opendj2.example.com:4444 ..... Done.
|
Updating remote references on server opendj2.example.com:4444 ..... Done.
|
Updating registration configuration on server
|
opendj.example.com:4444 ..... Done.
|
Updating registration configuration on server
|
opendj3.example.com:4444 ..... Done.
|
Updating registration configuration on server
|
opendj2.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
opendj.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
opendj3.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
opendj2.example.com:4444 ..... Done.
|
Initializing registration information on server opendj3.example.com:4444 with
|
the contents of server opendj.example.com: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.</computeroutput>
|
</screen>
|
|
<para>Contrary to the message from the command, you do not need to use
|
the <command>dsreplication initialize</command> command at this
|
point.</para>
|
</step>
|
|
<step>
|
<para>On the new server, restore the database from the backup
|
archive as described in the procedure, <link xlink:show="new"
|
xlink:role="http://docbook.org/xlink/role/olink"
|
xlink:href="admin-guide#restore-replica"><citetitle>To Restore a
|
Replica</citetitle></link>.</para>
|
|
<para>As long as you restore the database on the new replica before the
|
replication purge delay runs out, updates processed by other servers after
|
you created the backup are replicated to the new server after you restore
|
the data.</para>
|
</step>
|
</procedure>
|
|
<procedure xml:id="reinit-repl">
|
<title>To Restore All Replicas to a Known State</title>
|
|
<para>
|
OpenDJ replication is designed to make directory data converge
|
across all replicas in a topology.
|
Directory replication mechanically applies new changes
|
to ensure that replicated data is the same everywhere,
|
with newer changes taking precedence over older changes.
|
</para>
|
|
<para>
|
When you restore older backup data, for example,
|
directory replication applies newer changes to the older data.
|
This behavior is a good thing when the newer changes are correct.
|
</para>
|
|
<itemizedlist>
|
<para>
|
This behavior can be problematic in the following cases:
|
</para>
|
|
<listitem>
|
<para>
|
A bug or serious user error results in unwanted new changes
|
that are hard to fix.
|
</para>
|
</listitem>
|
|
<listitem>
|
<para>
|
The data in a test or proof-of-concept environment
|
must regularly be reinitialized to a known state.
|
</para>
|
</listitem>
|
</itemizedlist>
|
|
<itemizedlist>
|
<para>
|
The <command>dsreplication</command> command has the following subcommands
|
that let you reinitialize directory data,
|
preventing replication from replaying changes
|
that occurred before reinitialization:
|
</para>
|
|
<listitem>
|
<para>
|
The <command>dsreplication pre-external-initialization</command> command
|
removes the setting for the <firstterm>generation ID</firstterm>
|
across the topology for a specified base DN.
|
The generation ID is an internal-use identifier
|
that replication uses to determine what changes to apply.
|
This has the effect of halting replication.
|
</para>
|
</listitem>
|
|
<listitem>
|
<para>
|
The <command>dsreplication post-external-initialization</command> command
|
sets a new generation ID across the topology,
|
effectively resuming replication.
|
</para>
|
</listitem>
|
</itemizedlist>
|
|
<caution>
|
<para>
|
The steps in this procedure reinitialize the replication changelog,
|
eliminating the history of changes
|
that occurred before replication resumed.
|
The replication changelog is described in
|
<xref linkend="repl-change-notification" />.
|
Applications that depend on the changelog for change notifications
|
must be reinitialized after this procedure is completed.
|
</para>
|
</caution>
|
|
<step performance="optional">
|
<para>
|
Prevent changes to the affected data during the procedure,
|
as such changes are lost for the purposes of replication.
|
</para>
|
|
<para>
|
For example, make each replica read-only as described in
|
<xref linkend="read-only-repl" />.
|
</para>
|
</step>
|
|
<step>
|
<para>
|
On a single server in the topology,
|
run the <command>dsreplication pre-external-initialization</command> command
|
for the base DN holding the relevant data,
|
as shown in the following example:
|
</para>
|
|
<screen>
|
$ <userinput>dsreplication \
|
pre-external-initialization \
|
--adminUID admin \
|
--adminPassword password \
|
--baseDN dc=example,dc=com \
|
--hostname opendj.example.com \
|
--port 4444 \
|
--trustAll \
|
--no-prompt</userinput>
|
<computeroutput>
|
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 DNs 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 DNs
|
contents.</computeroutput>
|
</screen>
|
|
<para>
|
Replication halts as the command takes effect.
|
</para>
|
|
<para>
|
<emphasis>Changes made at this time are not replicated,
|
even after replication resumes.</emphasis>
|
</para>
|
</step>
|
|
<step>
|
<itemizedlist>
|
<para>
|
On each server in the topology,
|
restore the data in the topology to the known state
|
in one of the following ways:
|
</para>
|
|
<listitem>
|
<para>
|
Import the data from LDIF as described in
|
<link
|
xlink:href="admin-guide#import-ldif"
|
xlink:role="http://docbook.org/xlink/role/olink"
|
xlink:show="new"
|
><citetitle>To Import LDIF Data</citetitle></link>.
|
</para>
|
</listitem>
|
|
<listitem>
|
<para>
|
Restore the data from backup as described in
|
<link
|
xlink:href="admin-guide#restore-standalone-server"
|
xlink:role="http://docbook.org/xlink/role/olink"
|
xlink:show="new"
|
><citetitle>To Restore a Stand-alone Server</citetitle></link>.
|
</para>
|
</listitem>
|
</itemizedlist>
|
</step>
|
|
<step>
|
<para>
|
On a single server in the topology,
|
run the <command>dsreplication post-external-initialization</command> command
|
for the base DN holding the relevant data,
|
as shown in the following example:
|
</para>
|
|
<screen>
|
$ <userinput>dsreplication \
|
post-external-initialization \
|
--adminUID admin \
|
--adminPassword password \
|
--baseDN dc=example,dc=com \
|
--hostname opendj.example.com \
|
--port 4444 \
|
--trustAll \
|
--no-prompt</userinput>
|
<computeroutput>
|
Updating replication information on base DN dc=example,dc=com ..... Done.
|
|
|
Post initialization procedure completed successfully.
|
</computeroutput>
|
</screen>
|
|
<para>
|
Replication resumes as the command takes effect.
|
</para>
|
</step>
|
|
<step performance="optional">
|
<para>
|
If you made replicas read-only, make them read-write again by setting
|
<literal>writability-mode:enabled</literal>.
|
</para>
|
</step>
|
</procedure>
|
</section>
|
|
<section xml:id="stop-repl">
|
<title>Stopping Replication</title>
|
<indexterm>
|
<primary>Replication</primary>
|
<secondary>Stopping</secondary>
|
</indexterm>
|
|
<para>How you stop replication depends on whether the change is meant to
|
be temporary or permanent.</para>
|
|
<procedure xml:id="stop-repl-tmp">
|
<title>To Stop Replication Temporarily For a Replica</title>
|
|
<para>
|
If you must stop a server from replicating temporarily,
|
you can do so by using the
|
<link
|
xlink:show="new"
|
xlink:href="reference#dsconfig-1"
|
xlink:role="http://docbook.org/xlink/role/olink"
|
><command>dsconfig</command></link> command.
|
</para>
|
|
<warning>
|
<para>Do not allow modifications on the replica for which replication is
|
disabled, as no record of such changes is kept, and the changes cause
|
replication to diverge.</para>
|
</warning>
|
|
<step>
|
<para>Disable the multimaster synchronization provider.</para>
|
|
<screen>
|
$ <userinput>dsconfig \
|
set-synchronization-provider-prop \
|
--port 4444 \
|
--hostname opendj2.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--set enabled:false \
|
--trustAll \
|
--no-prompt</userinput>
|
</screen>
|
</step>
|
|
<step performance="optional">
|
<para>When you are ready to resume replication, enable the multimaster
|
synchronization provider.</para>
|
|
<screen>
|
$ <userinput>dsconfig \
|
set-synchronization-provider-prop \
|
--port 4444 \
|
--hostname opendj2.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--set enabled:true \
|
--trustAll \
|
--no-prompt</userinput>
|
</screen>
|
</step>
|
</procedure>
|
|
<procedure xml:id="stop-repl-permanent">
|
<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>
|
$ <userinput>dsreplication \
|
disable \
|
--disableAll \
|
--port 4444 \
|
--hostname opendj2.example.com \
|
--bindDN "cn=Directory Manager" \
|
--adminPassword password \
|
--trustAll \
|
--no-prompt</userinput>
|
<computeroutput>Establishing connections ..... Done.
|
Disabling replication on base DN cn=admin data of server
|
opendj2.example.com:4444 ..... Done.
|
Disabling replication on base DN dc=example,dc=com of server
|
opendj2.example.com:4444 ..... Done.
|
Disabling replication on base DN cn=schema of server
|
opendj2.example.com:4444 ..... Done.
|
Disabling replication port 8989 of server
|
opendj2.example.com:4444 ..... Done.
|
Removing registration information ..... Done.
|
Removing truststore information ..... Done.
|
|
See
|
/var/.../opends-replication-125248191132797765.log
|
for a detailed log of this operation.</computeroutput>
|
</screen>
|
|
<para>The <command>dsreplication disable</command> as shown completely
|
removes the replication configuration information from the server.</para>
|
</step>
|
|
<step performance="optional">
|
<para>If you want to restart replication for the server, you need to run
|
the <command>dsreplication enable</command> and <command>dsreplication
|
initialize</command> commands again.</para>
|
</step>
|
</procedure>
|
</section>
|
|
<section xml:id="repl-dedicated-servers">
|
<title>Stand-alone Replication Servers</title>
|
<indexterm>
|
<primary>Replication</primary>
|
<secondary>Dedicated servers</secondary>
|
</indexterm>
|
|
<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>
|
|
|
<para>All replication servers in a topology are connected to all other
|
replication servers. Directory servers are connected only to one replication
|
server at a time, and their connections should be to replication servers on
|
the same LAN. Therefore the total number of replication connections,
|
Total<subscript>conn</subscript> is expressed as follows.</para>
|
|
<equation>
|
<mathphrase>Total<subscript>conn</subscript> = (N<subscript>RS</subscript> *
|
N<subscript>RS</subscript>-1)/2 + N<subscript>DS</subscript></mathphrase>
|
</equation>
|
|
<para>Here, N<subscript>RS</subscript> is the number of replication servers,
|
and N<subscript>DS</subscript> is the number of stand-alone directory
|
servers. In other words, if you have only 3 servers, then
|
Total<subscript>conn</subscript> is 3 with no stand-alone servers.
|
However, if you have two data centers, and need 12 directory servers, then
|
with no stand-alone directory servers Total<subscript>conn</subscript> is
|
(12 * 11)/2 or 66. Yet, with 4 stand-alone replication servers, and 12
|
stand-alone directory servers, Total<subscript>conn</subscript> is
|
(4 * 3)/2 + 12, or 18, with only four of those connections needing to go
|
over the WAN. (By running four directory servers that also run replication
|
servers and eight stand-alone directory servers, you reduce the number of
|
replication connections to 14 for 12 replicas.)</para>
|
|
<figure xml:id="figure-standalone-repl">
|
<title>Deployment For Multiple Data Centers</title>
|
<mediaobject xml:id="figure-standalone-repl-image">
|
<alt>Dedicated servers versus consolidated instances</alt>
|
<imageobject>
|
<imagedata fileref="images/standalone-repl.png" format="PNG"/>
|
</imageobject>
|
<textobject>
|
<para>Dedicated servers are suited to environments with large numbers
|
of replicas.</para>
|
</textobject>
|
</mediaobject>
|
</figure>
|
|
<tip>
|
<para>If you set up OpenDJ directory server to replicate by using the
|
Quick Setup wizard, then the wizard activated the replication service for
|
that server. You can turn off the replication service on OpenDJ directory
|
server, and then configure the server to work with a separate, stand-alone
|
replication server instead. Start by using the <command>dsreplication
|
disable --disableReplicationServer</command> command to turn off the
|
replication service on the server.</para>
|
</tip>
|
|
<procedure xml:id="repl-setup-dedicated-server">
|
<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 is <literal>rs.example.com</literal>. The
|
directory servers are <literal>opendj.example.com</literal> and
|
<literal>opendj2.example.com</literal>.</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>
|
$ <userinput>dsreplication \
|
enable \
|
--adminUID admin \
|
--adminPassword password \
|
--baseDN dc=example,dc=com \
|
--host1 opendj.example.com \
|
--port1 4444 \
|
--bindDN1 "cn=Directory Manager" \
|
--bindPassword1 password \
|
--noReplicationServer1 \
|
--host2 rs.example.com \
|
--port2 4444 \
|
--bindDN2 "cn=Directory Manager" \
|
--bindPassword2 password \
|
--replicationPort2 8989 \
|
--onlyReplicationServer2 \
|
--trustAll \
|
--no-prompt</userinput>
|
<computeroutput>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 rs.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
opendj.example.com:4444 ..... Done.
|
Updating registration configuration on server
|
opendj.example.com:4444 ..... Done.
|
Updating registration configuration on server
|
rs.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
opendj.example.com:4444 ..... Done.
|
Initializing registration information on server rs.example.com:4444 with
|
the contents of server opendj.example.com: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.</computeroutput>
|
|
$ <userinput>dsreplication \
|
enable \
|
--adminUID admin \
|
--adminPassword password \
|
--baseDN dc=example,dc=com \
|
--host1 opendj2.example.com \
|
--port1 4444 \
|
--bindDN1 "cn=Directory Manager" \
|
--bindPassword1 password \
|
--noReplicationServer1 \
|
--host2 rs.example.com \
|
--port2 4444 \
|
--bindDN2 "cn=Directory Manager" \
|
--bindPassword2 password \
|
--replicationPort2 8989 \
|
--onlyReplicationServer2 \
|
--trustAll \
|
--no-prompt</userinput>
|
|
<computeroutput>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 rs.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
opendj2.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com on server
|
opendj.example.com:4444 ..... Done.
|
Updating registration configuration on server
|
opendj2.example.com:4444 ..... Done.
|
Updating registration configuration on server
|
rs.example.com:4444 ..... Done.
|
Updating registration configuration on server
|
opendj.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
opendj2.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN cn=schema on server
|
opendj.example.com:4444 ..... Done.
|
Initializing registration information on server opendj2.example.com:4444 with
|
the contents of server rs.example.com: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/folders/.../opends-replication-5893037538856033562.log
|
for a detailed log of this operation.</computeroutput>
|
</screen>
|
</step>
|
|
<step>
|
<para>Initialize replication from one of the directory servers.</para>
|
|
<screen>
|
$ <userinput>dsreplication \
|
initialize-all \
|
--adminUID admin \
|
--adminPassword password \
|
--baseDN dc=example,dc=com \
|
--hostname opendj.example.com \
|
--port 4444 \
|
--trustAll \
|
--no-prompt</userinput>
|
|
<computeroutput>Initializing base DN dc=example,dc=com with the contents from
|
opendj.example.com:4444: 160 entries processed (100 % complete).
|
Base DN initialized successfully.
|
|
See
|
/var/.../opends-replication-7677303986403997574.log
|
for a detailed log of this operation.</computeroutput>
|
</screen>
|
</step>
|
</procedure>
|
</section>
|
|
<section xml:id="repl-dedicated-replica">
|
<title>Stand-alone Directory Server Replicas</title>
|
<indexterm>
|
<primary>Replication</primary>
|
<secondary>Dedicated servers</secondary>
|
</indexterm>
|
|
<para>
|
When you configure replication for an OpenDJ directory server,
|
you can give the directory server the capability
|
to handle replication traffic as well.
|
As described in <xref linkend="repl-dedicated-servers" />,
|
OpenDJ servers can also be configured to handle only replication traffic.
|
</para>
|
|
<para>
|
Alternatively you can configure an OpenDJ directory server
|
to connect to a remote replication server of either variety,
|
but to remain only a directory server itself.
|
This sort of stand-alone directory server replica is shown
|
in <xref linkend="figure-standalone-repl" />.
|
</para>
|
|
<para>
|
Furthermore, you can make this stand-alone directory server replica
|
read-only for client applications, accepting only replication updates.
|
</para>
|
|
<procedure xml:id="repl-setup-dedicated-replica">
|
<title>To Set Up a Stand-alone Directory Server Replica</title>
|
|
<para>
|
The following steps show how to configure the server
|
as a stand-alone, directory server only replica
|
of an existing replicated directory server.
|
</para>
|
|
<step>
|
<para>
|
Set up replication between other servers.
|
</para>
|
</step>
|
|
<step>
|
<para>
|
Install the directory server without configuring replication,
|
but creating at least the base entry to be replicated.
|
</para>
|
</step>
|
|
<step>
|
<para>
|
Enable replication with the appropriate
|
<option>--noReplicationServer</option> option.
|
</para>
|
|
<screen>
|
$ <userinput>dsreplication \
|
enable \
|
--adminUID admin \
|
--adminPassword password \
|
--baseDN dc=example,dc=com \
|
--host1 master.example.com \
|
--port1 4444 \
|
--bindDN1 "cn=Directory Manager" \
|
--bindPassword1 password \
|
--host2 ds-only.example.com \
|
--port2 4444 \
|
--bindDN2 "cn=Directory Manager" \
|
--bindPassword2 password \
|
--noReplicationServer2 \
|
--trustAll \
|
--no-prompt</userinput>
|
|
<computeroutput>Establishing connections ..... Done.
|
Checking registration information ..... Done.
|
Updating remote references on server master.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com
|
on server master.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com
|
on server ds-only.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN dc=example,dc=com
|
on server master2.example.com:4444 ..... Done.
|
Updating remote references on server master2.example.com:4444 ..... Done.
|
Updating registration configuration
|
on server master.example.com:4444 ..... Done.
|
Updating registration configuration
|
on server ds-only.example.com:4444 ..... Done.
|
Updating registration configuration
|
on server master2.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN cn=schema
|
on server master.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN cn=schema
|
on server ds-only.example.com:4444 ..... Done.
|
Updating replication configuration for baseDN cn=schema
|
on server master2.example.com:4444 ..... Done.
|
Initializing registration information on server ds-only.example.com:4444
|
with the contents of server master.example.com:4444 ..... Done.
|
Initializing schema on server ds-only.example.com:4444
|
with the contents of server master.example.com:4444 ..... Done.
|
|
Replication has been successfully enabled. Note that for replication to work
|
you must initialize the contents of the base DNs that are being replicated
|
(use dsreplication initialize to do so).
|
|
See
|
/var/.../opendj-replication-859181866587327450.log
|
for a detailed log of this operation.</computeroutput>
|
</screen>
|
|
<para>
|
Here the existing server is both directory server and replication server.
|
If the existing server is a stand-alone replication server,
|
then also use the appropriate
|
<option>--onlyReplicationServer</option> option.
|
</para>
|
</step>
|
|
<step>
|
<para>
|
Initialize data on the new directory server replica.
|
</para>
|
|
<screen>
|
$ <userinput>dsreplication \
|
initialize \
|
--adminUID admin \
|
--adminPassword password \
|
--baseDN dc=example,dc=com \
|
--hostSource master.example.com \
|
--portSource 4444 \
|
--hostDestination ds-only.example.com \
|
--portDestination 4444 \
|
--trustAll \
|
--no-prompt</userinput>
|
|
<computeroutput>Initializing base DN dc=example,dc=com with the contents
|
from master.example.com:4444:
|
0 entries processed (0 % complete).
|
176 entries processed (100 % complete).
|
Base DN initialized successfully.
|
|
See
|
/var/.../opendj-replication-4326340645155418876.log
|
for a detailed log of this operation.</computeroutput>
|
</screen>
|
</step>
|
|
<step>
|
<para>
|
If you want to make the directory server replica
|
read-only for client application traffic,
|
see <xref linkend="read-only-repl" />.
|
</para>
|
</step>
|
</procedure>
|
</section>
|
|
<section xml:id="repl-groups">
|
<title>Replication Groups</title>
|
<indexterm>
|
<primary>Replication</primary>
|
<secondary>Grouping servers</secondary>
|
</indexterm>
|
|
<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>
|
|
<para>Replication groups are designed for deployments across multiple data
|
centers, where you aim to focus replication traffic on the LAN rather than
|
the WAN. In multi-data center deployments, group nearby servers
|
together.</para>
|
|
<procedure xml:id="define-repl-groups">
|
<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 are <literal>opendj.example.com</literal> and
|
<literal>opendj2.example.com</literal>. The replication servers
|
are <literal>rs.example.com</literal> and
|
<literal>rs2.example.com</literal>. 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>
|
$ <userinput>dsconfig \
|
set-replication-domain-prop \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--domain-name "dc=example,dc=com" \
|
--set group-id:1 \
|
--trustAll \
|
--no-prompt</userinput>
|
|
$ <userinput>dsconfig \
|
set-replication-domain-prop \
|
--port 4444 \
|
--hostname opendj2.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--domain-name "dc=example,dc=com" \
|
--set group-id:2 \
|
--trustAll \
|
--no-prompt</userinput>
|
</screen>
|
</step>
|
|
<step>
|
<para>Set the group ID for each group on the replication servers.</para>
|
|
<screen>
|
$ <userinput>dsconfig \
|
set-replication-server-prop \
|
--port 4444 \
|
--hostname rs.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--set group-id:1 \
|
--trustAll \
|
--no-prompt</userinput>
|
|
$ <userinput>dsconfig \
|
set-replication-server-prop \
|
--port 4444 \
|
--hostname rs2.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--set group-id:2 \
|
--trustAll \
|
--no-prompt</userinput>
|
</screen>
|
</step>
|
</procedure>
|
</section>
|
|
<section xml:id="read-only-repl">
|
<title>Read-Only Replicas</title>
|
<indexterm>
|
<primary>Replication</primary>
|
<secondary>Read-only servers</secondary>
|
</indexterm>
|
|
<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>
|
$ <userinput>dsconfig \
|
set-global-configuration-prop \
|
--port 4444 \
|
--hostname opendj2.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--set writability-mode:internal-only \
|
--trustAll \
|
--no-prompt</userinput>
|
</screen>
|
</section>
|
|
<section xml:id="repl-assured">
|
<title>Assured Replication</title>
|
<indexterm>
|
<primary>Replication</primary>
|
<secondary>Assured</secondary>
|
</indexterm>
|
|
<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 xml:id="repl-safe-data">
|
<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>
|
$ <userinput>dsconfig \
|
set-replication-domain-prop \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--domain-name "dc=example,dc=com" \
|
--set assured-type:safe-data \
|
--set assured-sd-level:1 \
|
--trustAll \
|
--no-prompt</userinput>
|
|
$ <userinput>dsconfig \
|
set-replication-domain-prop \
|
--port 4444 \
|
--hostname opendj2.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--domain-name "dc=example,dc=com" \
|
--set assured-type:safe-data \
|
--set assured-sd-level:1 \
|
--trustAll \
|
--no-prompt</userinput>
|
</screen>
|
</step>
|
</procedure>
|
|
<procedure xml:id="repl-safe-read">
|
<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>
|
$ <userinput>dsconfig \
|
set-replication-domain-prop \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--domain-name "dc=example,dc=com" \
|
--set assured-type:safe-read \
|
--trustAll \
|
--no-prompt</userinput>
|
|
$ <userinput>dsconfig \
|
set-replication-domain-prop \
|
--port 4444 \
|
--hostname opendj2.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--domain-name "dc=example,dc=com" \
|
--set assured-type:safe-read \
|
--trustAll \
|
--no-prompt</userinput>
|
</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 xml:id="repl-subtree">
|
<title>Subtree Replication</title>
|
<indexterm>
|
<primary>Replication</primary>
|
<secondary>Subtree</secondary>
|
</indexterm>
|
|
<para>OpenDJ can perform 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 xml:id="repl-fractional">
|
<title>Fractional Replication</title>
|
<indexterm>
|
<primary>Replication</primary>
|
<secondary>Fractional</secondary>
|
</indexterm>
|
|
<para>OpenDJ can perform fractional replication, whereby you specify
|
the attributes to include in or to exclude from the replication
|
process.</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 are required 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
|
replicas still respect schema definitions.</para>
|
|
<para>Fractional replication works by filtering objects at the replication
|
server. Initialize replication as you would normally. Of course you cannot
|
create a full replica from a replica with only a subset of the data. If you
|
must prevent data from being replicated across a national boundary, split
|
the replication server handling the updates from the directory servers
|
receiving the updates as described in
|
<xref linkend="repl-setup-dedicated-server" />.</para>
|
|
<para>For example, you might configure an externally facing
|
fractional replica to include only some <literal>inetOrgPerson</literal>
|
attributes.</para>
|
|
<screen>
|
$ <userinput>dsconfig \
|
set-replication-domain-prop \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--domain-name "dc=example,dc=com" \
|
--trustAll \
|
--no-prompt \
|
--set \
|
fractional-include:inetorgperson:cn,givenname,mail,mobile,sn,telephonenumber</userinput>
|
</screen>
|
|
<para>As another example, you might exclude a custom attribute called
|
<literal>sessionToken</literal> from being replicated.</para>
|
|
<screen>
|
$ <userinput>dsconfig \
|
set-replication-domain-prop \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--domain-name "dc=example,dc=com" \
|
--set fractional-exclude:*:sessionToken \
|
--trustAll \
|
--no-prompt</userinput>
|
</screen>
|
|
<para>This last example only works if you first define a
|
<literal>sessionToken</literal> attribute in the directory server
|
schema.</para>
|
</section>
|
|
<section xml:id="repl-break-into-ds-and-rs">
|
<title>Breaking a Multi-role Server Into Stand-alone Components</title>
|
|
<para>
|
As described in <xref linkend="about-repl" />,
|
a replication topology is made up of
|
servers playing the role of directory server,
|
and servers playing the role of replication server.
|
By default, each replicated OpenDJ server plays both roles.
|
Some deployments call for stand-alone directory servers
|
and stand-alone replication servers, however.<footnote>
|
<para>
|
In practice, "stand-alone" technically usually refers only to the role
|
with respect to replication of user data.
|
In fact stand-alone servers generally continue
|
to play both roles for server configuration data
|
under <literal>cn=admin data</literal> and <literal>cn=schema</literal>.
|
The update traffic to these suffixes is however
|
generally orders of magnitude lower than update traffic for user data.
|
</para>
|
</footnote>
|
</para>
|
|
<para>
|
If possible avoid breaking apart an existing multi-role server.
|
Instead, set up stand-alone servers as described in
|
<xref linkend="repl-dedicated-servers" />
|
and <xref linkend="repl-dedicated-replica" />.
|
</para>
|
|
<para>
|
The following procedure breaks a multi-role server
|
into two stand-alone servers
|
while preserving existing data.
|
It does require disk space initially to hold copies of existing data.
|
</para>
|
|
<procedure xml:id="repl-split-multi-role-server">
|
<title>To Break a Multi-role Server Into Stand-alone Components</title>
|
|
<para>
|
The following steps show how to break a multi-role OpenDJ server
|
into a stand-alone directory server and a stand-alone replication server.
|
</para>
|
|
<para>
|
While you carry out this procedure, do not allow any client traffic
|
to the servers you modify.
|
</para>
|
|
<step>
|
<para>
|
Make sure you have already set up
|
at least a couple of OpenDJ servers that replicate user data.
|
</para>
|
|
<itemizedlist>
|
<para>
|
This example starts with the following multi-role servers.
|
</para>
|
|
<listitem>
|
<para>
|
<filename>/path/to/dsrs1</filename>
|
(ports: 1389, 1636, 4444, 8989;
|
replicating user data for <literal>dc=example,dc=com</literal>)
|
</para>
|
</listitem>
|
|
<listitem>
|
<para>
|
<filename>/path/to/dsrs2</filename>
|
(ports: 2389, 2636, 5444, 9989;
|
replicating user data for <literal>dc=example,dc=com</literal>)
|
</para>
|
</listitem>
|
</itemizedlist>
|
|
<para>
|
<filename>/path/to/dsrs1</filename> is the target server
|
to be broken into stand-alone components.
|
</para>
|
|
<para>
|
When you begin, the target server has
|
both directory server and replication server components.
|
</para>
|
|
<itemizedlist>
|
<para>
|
Before you proceed:
|
</para>
|
|
<listitem>
|
<para>
|
Read the rest of the procedure, and make sure you understand the steps.
|
</para>
|
</listitem>
|
|
<listitem>
|
<para>
|
Direct client traffic away from the target server.
|
</para>
|
</listitem>
|
|
<listitem>
|
<para>
|
Back up the target server.
|
</para>
|
</listitem>
|
</itemizedlist>
|
</step>
|
|
<step xml:id="repl-id-status">
|
<para>
|
Run the <command>dsreplication status</command> command
|
before making changes.
|
</para>
|
|
<screen>
|
$ <userinput>dsreplication \
|
status \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--adminUID admin \
|
--adminPassword password \
|
--baseDN "cn=admin data" \
|
--baseDN cn=schema \
|
--baseDN dc=example,dc=com \
|
--trustAll \
|
--no-prompt</userinput>
|
<computeroutput>
|
Suffix DN :...: DS ID : RS ID :...
|
------------------:...:-------:-------:...
|
cn=admin data :...: 29388 : 32560 :...
|
cn=admin data :...: 7044 : 29137 :...
|
cn=schema :...: 24612 : 32560 :...
|
cn=schema :...: 22295 : 29137 :...
|
dc=example,dc=com :...: 20360 : 32560 :...
|
dc=example,dc=com :...: 12164 : 29137 :...
|
...</computeroutput>
|
</screen>
|
|
<para>
|
Keep the output of the command for the IDs shown.
|
The information is used later in this procedure.
|
</para>
|
</step>
|
|
<step>
|
<para>
|
Temporarily disable the multimaster synchronization provider
|
on the target server.
|
</para>
|
|
<screen>
|
$ <userinput>dsconfig \
|
set-synchronization-provider-prop \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--set enabled:false \
|
--trustAll \
|
--no-prompt</userinput>
|
</screen>
|
|
<para>
|
This step is also shown in <xref linkend="stop-repl-tmp" />.
|
</para>
|
</step>
|
|
<step>
|
<para>
|
Temporarily disable the backend holding the replicated data.
|
</para>
|
|
<screen>
|
$ <userinput>dsconfig \
|
set-backend-prop \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--backend-name userRoot \
|
--set enabled:false \
|
--trustAll \
|
--no-prompt</userinput>
|
</screen>
|
</step>
|
|
<step>
|
<para>
|
Stop the target server.
|
</para>
|
|
<screen>
|
$ <userinput>stop-ds</userinput>
|
<computeroutput>Stopping Server...
|
... msg=The Directory Server is now stopped</computeroutput>
|
</screen>
|
</step>
|
|
<step>
|
<para>
|
Make two copies of the server files.
|
</para>
|
|
<screen>
|
$ <userinput>cd /path/to/</userinput>
|
</screen>
|
|
<para>
|
One copy is to become the stand-alone directory server.
|
</para>
|
|
<screen>
|
$ <userinput>cp -r dsrs1 ds</userinput>
|
</screen>
|
|
<para>
|
The other copy is to become the stand-alone replication server.
|
</para>
|
|
<screen>
|
$ <userinput>cp -r dsrs1 rs</userinput>
|
</screen>
|
</step>
|
|
<step>
|
<para>
|
Start the copy that is to become the stand-alone directory server,
|
remove the replication server and changelog configuration,
|
enable the user data backend,
|
and then enable the multimaster synchronization provider
|
on the directory server.
|
</para>
|
|
<programlisting language="shell">
|
# The following command removes the replication server configuration.
|
|
dsconfig \
|
delete-replication-server \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--trustAll \
|
--no-prompt
|
|
# The following command disables the changelog for the user data
|
# in dc=example,dc=com.
|
|
dsconfig \
|
set-external-changelog-domain-prop \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--domain-name dc=example,dc=com
|
--set enabled:false
|
--trustAll \
|
--no-prompt
|
|
# The following command enables the user data backend.
|
|
dsconfig \
|
set-backend-prop \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--backend-name userRoot \
|
--set enabled:true \
|
--trustAll \
|
--no-prompt
|
|
# The following command enables the multimaster synchronization provider.
|
|
dsconfig \
|
set-synchronization-provider-prop \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--set enabled:true \
|
--trustAll \
|
--no-prompt
|
</programlisting>
|
|
<para>
|
You can then remove the files for the changelog on the directory server.
|
</para>
|
|
<screen>
|
$ <userinput>rm /path/to/ds/changelogDb/*</userinput>
|
</screen>
|
</step>
|
|
<step>
|
<para>
|
If the replication server is on the same host as the directory server,
|
carefully change the connection handler port numbers
|
and the administration port number in the configuration file
|
before starting the replication server.
|
Before making any changes, make sure that the new port numbers you use
|
are available, and not in use by any other services on the system.
|
</para>
|
|
<para>
|
Change the port numbers for the LDAP and LDAPS connection handlers
|
as described in the procedure
|
<link
|
xlink:show="new"
|
xlink:href="admin-guide#change-ldap-port"
|
xlink:role="http://docbook.org/xlink/role/olink"
|
><citetitle>To Change the LDAP Port Number</citetitle></link>.
|
</para>
|
|
<para>
|
The following example changes the administration port to 6444.
|
After this command succeeds, you must restart the server
|
in order to use the <command>dsconfig</command> command again.
|
</para>
|
|
<screen>
|
$ <userinput>dsconfig \
|
set-administration-connector-prop \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--set listen-port:6444 \
|
--trustAll \
|
--no-prompt</userinput>
|
</screen>
|
|
<para>
|
Restart the server to be able to connect on the new administration port.
|
</para>
|
|
<screen>
|
$ <userinput>stop-ds --restart</userinput>
|
<computeroutput>Stopping Server...
|
...
|
...The Directory Server has started successfully</computeroutput>
|
</screen>
|
</step>
|
|
<step>
|
<para>
|
Change the server ID values for the
|
<literal>cn=admin data</literal> and <literal>cn=schema</literal>
|
replication domains
|
on the copy that is to become the stand-alone replication server.
|
</para>
|
|
<para>
|
Replication uses unique server IDs
|
to distinguish between different directory server replicas.
|
When you make identical copies of the original multi-role server,
|
the server IDs on the new stand-alone directory server
|
and on the new stand-alone replication server are identical.
|
</para>
|
|
<para>
|
For the user data replication domains,
|
such as <literal>dc=example,dc=com</literal>,
|
you are going to fix the duplicate server ID problem
|
as part of this procedure.
|
When you remove the replication domain configuration information
|
from the new stand-alone replication server for user data,
|
part of the configuration information that you remove is the server ID.
|
For the administrative data and directory schema, however,
|
the new stand-alone replication server
|
must maintain its administrative and schema data
|
in sync with other servers,
|
so it still holds that data like any other directory server.
|
The server IDs for the
|
<literal>cn=admin data</literal> and <literal>cn=schema</literal>
|
replication domains
|
must therefore be changed
|
so as not to conflict with other existing server IDs.
|
</para>
|
|
<para>
|
If you try to edit server IDs
|
by using the <command>dsconfig</command> command,
|
you encounter an error:
|
</para>
|
|
<literallayout class="monospaced">
|
The Replication Domain property "server-id" is read-only and cannot be
|
modified
|
</literallayout>
|
|
<para>
|
You must instead edit the server ID values
|
directly in the configuration file
|
while the new stand-alone replication server is stopped.
|
</para>
|
|
<para>
|
Before editing the configuration file,
|
refer to the information you gather in <xref linkend="repl-id-status" />
|
for the list of IDs that are in use in the replication topology.
|
You must choose server ID values that are unique,
|
and that are between 0 and 65535 inclusive.
|
</para>
|
|
<para>
|
After choosing two valid, unused server ID values,
|
carefully edit the configuration file,
|
<filename>/path/to/rs/config/config.ldif</filename>,
|
to change the <literal>ds-cfg-server-id</literal> values
|
for the entries with DNs
|
<literal>cn=cn=admin data,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config</literal>
|
and
|
<literal>cn=cn=schema,cn=domains,cn=Multimaster Synchronization,cn=Synchronization Providers,cn=config</literal>.
|
</para>
|
|
<para>
|
For example if the duplicate server IDs were 29388 and 24612,
|
and you edited the configuration file to use 12345 and 23456 instead,
|
the result might appear as follows:
|
</para>
|
|
<screen>
|
$ <userinput>grep -B 1 ds-cfg-server-id /path/to/rs/config/config.ldif</userinput>
|
<computeroutput>cn: cn=admin data
|
#ds-cfg-server-id: 29388
|
ds-cfg-server-id: 12345
|
--
|
cn: cn=schema
|
#ds-cfg-server-id: 24612
|
ds-cfg-server-id: 23456</computeroutput>
|
</screen>
|
</step>
|
|
<step>
|
<para>
|
Start the copy that is to become the stand-alone replication server,
|
remove the user data backend configuration,
|
remove the replication domain for the user data,
|
and then enable the multimaster synchronization provider on the directory server.
|
</para>
|
|
<programlisting language="shell">
|
# The following command removes the user data backend configuration.
|
|
dsconfig \
|
delete-backend \
|
--port 6444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--backend-name userRoot \
|
--trustAll \
|
--no-prompt
|
|
# The following command removes the replication domain for the user data.
|
|
dsconfig \
|
delete-replication-domain \
|
--port 6444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--domain-name dc=example,dc=com \
|
--trustAll \
|
--no-prompt
|
|
# The following command enables the multimaster synchronization provider.
|
|
dsconfig \
|
set-synchronization-provider-prop \
|
--port 6444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--set enabled:true \
|
--trustAll \
|
--no-prompt
|
</programlisting>
|
|
<para>
|
You can then remove the files for the user data backend
|
on the replication server.
|
</para>
|
|
<screen>
|
$ <userinput>rm -rf /path/to/rs/db/userRoot</userinput>
|
</screen>
|
</step>
|
|
<step>
|
<para>
|
If you have moved servers with secure ports configured,
|
the host names in the server certificates might no longer correspond
|
to the new host names.
|
</para>
|
|
<para>
|
For details, see the chapter,
|
<link
|
xlink:show="new"
|
xlink:href="admin-guide#chap-change-certs"
|
xlink:role="http://docbook.org/xlink/role/olink"
|
><citetitle>Changing Server Certificates</citetitle></link>.
|
</para>
|
</step>
|
|
<step>
|
<para>
|
After testing that everything is working to your satisfaction,
|
you can allow normal client traffic to the new directory server,
|
and retire the old multi-role server
|
(<command>rm -rf /path/to/dsrs1</command> in this example).
|
</para>
|
</step>
|
</procedure>
|
</section>
|
</section>
|
|
<section xml:id="repl-change-notification">
|
<title>Change Notification For Your Applications</title>
|
<indexterm>
|
<primary>Replication</primary>
|
<secondary>Change notification</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>External change log</primary>
|
</indexterm>
|
|
<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 persistent search operations, OpenDJ
|
provides an external change log mechanism to allow applications to be
|
notified of changes to directory data.</para>
|
|
<procedure xml:id="enable-ecl">
|
<title>To Enable the External Change Log</title>
|
|
<para>OpenDJ directory servers without replication cannot 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>--noReplicationServer</option> or
|
<option>--onlyReplicationServer</option> options.</para>
|
|
<para>
|
With replication enabled, the data is under <literal>cn=changelog</literal>.
|
The user reading the changelog must however
|
have access to read and search the changelog
|
and must have the <literal>changelog-read</literal> privilege.
|
By default, Directory Manager has this privilege.
|
</para>
|
|
<screen>
|
$ <userinput>ldapsearch \
|
--hostname opendj.example.com \
|
--port 1389 \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--baseDN cn=changelog \
|
"(objectclass=*)" \
|
\* +</userinput>
|
<computeroutput>dn: cn=changelog
|
cn: changelog
|
objectClass: top
|
objectClass: container
|
subschemaSubentry: cn=schema
|
hasSubordinates: false
|
entryDN: cn=changelog</computeroutput>
|
</screen>
|
|
<para>
|
To allow other users to read the changelog,
|
add the <literal>changelog-read</literal> privilege to their entries.
|
For details on how to add a privilege, see the section,
|
<link
|
xlink:href="admin-guide#configure-privileges"
|
xlink:show="new"
|
xlink:role="http://docbook.org/xlink/role/olink"
|
><citetitle>Configuring Privileges</citetitle></link>.
|
</para>
|
</step>
|
</procedure>
|
|
<procedure xml:id="use-ecl">
|
<title>To Use the External Change Log</title>
|
|
<para>You read the external change log over LDAP. 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 and privileges 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>
|
$ <userinput>ldapsearch \
|
--baseDN cn=changelog \
|
--port 1389 \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--control "1.3.6.1.4.1.26027.1.5.4:false" \
|
"(objectclass=*)" \
|
\* +</userinput>
|
<computeroutput>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
|
changeLogCookie: dc=example,dc=com:0000013087cbc34a12d100000002;
|
changeInitiatorsName: cn=Directory Manager,cn=Root DNs,cn=config
|
subschemaSubentry: cn=schema
|
hasSubordinates: false
|
entryDN: replicationCSN=0000013087cbc34a12d100000002,dc=example,dc=com,cn=change
|
log</computeroutput>
|
</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>
|
$ <userinput>base64 decode --encodedData b2JqZW...ZmlnCg==</userinput>
|
<computeroutput>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</computeroutput>
|
</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>
|
$ <userinput>ldapsearch \
|
--baseDN cn=changelog \
|
--port 1389 \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--control "1.3.6.1.4.1.26027.1.5.4:false:dc=example, \
|
dc=com:0000013087cbc34a12d100000002;" \
|
"(objectclass=*)" \
|
\* +</userinput>
|
<computeroutput>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</computeroutput>
|
</screen>
|
|
<para>If we base64-decode the changes, we see the following.</para>
|
|
<screen>
|
$ <userinput>base64 decode --encodedData YWRkO...gotCg==</userinput>
|
<computeroutput>add: description
|
description: A third change
|
-
|
replace: modifiersName
|
modifiersName: cn=Directory Manager,cn=Root DNs,cn=config
|
-
|
replace: modifyTimestamp
|
modifyTimestamp: 20110613071210Z
|
-</computeroutput>
|
</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>
|
|
<procedure xml:id="ecl-add-attributes">
|
<title>To Include Unchanged Attributes in the External Change Log</title>
|
|
<para>As shown above, the changes returned from a search on the external
|
change log include only what was actually changed. If you have applications
|
that need additional attributes published with every change log entry,
|
regardless of whether or not the attribute itself has changed, then specify
|
those using <literal>ecl-include</literal> and
|
<literal>ecl-include-for-deletes</literal>.</para>
|
|
<step>
|
<para>Set the attributes to include for all update operations with
|
<literal>ecl-include</literal>.</para>
|
|
<screen>
|
$ <userinput>dsconfig \
|
set-external-changelog-domain-prop \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--domain-name dc=example,dc=com \
|
--set ecl-include:"@person" \
|
--trustAll \
|
--no-prompt</userinput>
|
</screen>
|
</step>
|
|
<step>
|
<para>Set the attributes to include for deletes with
|
<literal>ecl-include-for-deletes</literal>.</para>
|
|
<screen>
|
$ <userinput>dsconfig \
|
set-external-changelog-domain-prop \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--domain-name dc=example,dc=com \
|
--add ecl-include-for-deletes:"*" \
|
--add ecl-include-for-deletes:"+" \
|
--trustAll \
|
--no-prompt</userinput>
|
</screen>
|
</step>
|
</procedure>
|
|
<procedure xml:id="ecl-limit-content">
|
<title>To Limit External Change Log Content</title>
|
|
<para>You can limit external change log content by disabling the domain
|
for a base DN. By default, <literal>cn=schema</literal> and
|
<literal>cn=admin data</literal> are not enabled.</para>
|
|
<step>
|
<para>Prevent OpenDJ from logging changes by disabling the domain.</para>
|
|
<screen>
|
$ <userinput>dsconfig \
|
set-external-changelog-domain-prop \
|
--port 4444 \
|
--hostname opendj.example.com \
|
--bindDN "cn=Directory Manager" \
|
--bindPassword password \
|
--provider-name "Multimaster Synchronization" \
|
--domain-name dc=example,dc=com \
|
--set enabled:false \
|
--trustAll \
|
--no-prompt</userinput>
|
</screen>
|
</step>
|
</procedure>
|
|
<para xml:id="ecl-legacy-format">The external change log can also work for
|
applications that follow 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>. Nothing special is required to get the objects specified for
|
this legacy format. Such applications cannot however use the change log
|
cookies that are shared across the replication topology, and therefore
|
can continue to be used after failover to another replica in a multi-master
|
replication environment.</para>
|
<indexterm>
|
<primary>External change log</primary>
|
<secondary>Legacy format</secondary>
|
</indexterm>
|
</section>
|
|
<section xml:id="recover-from-user-error">
|
<title>Recovering from User Error</title>
|
|
<para>
|
Changes to a replicated OpenDJ directory service
|
are similar to those made with the Unix <command>rm</command> command,
|
but with a twist.
|
With the <command>rm</command> command,
|
if you make a mistake you can restore your files from backup,
|
and lose only the work done since the last backup.
|
If you make a mistake with a update to the directory service however,
|
then after you restore a server from backup,
|
replication efficiently replays your mistake to the server you restored.
|
</para>
|
|
<indexterm>
|
<primary>Backup</primary>
|
<secondary>Recovery from user error</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Replication</primary>
|
<secondary>Recovery from user error</secondary>
|
</indexterm>
|
<indexterm>
|
<primary>Troubleshooting</primary>
|
<secondary>Recovery from user error</secondary>
|
</indexterm>
|
|
<para>
|
There is more than one way to recover from user error.
|
None of the ways involve simply changing OpenDJ settings.
|
All of the ways instead involve manually fixing mistakes.
|
</para>
|
|
<itemizedlist>
|
<para>
|
Consider these alternatives.
|
</para>
|
|
<listitem>
|
<para>
|
Encourage client applications to provide end users
|
with "undo" capability if necessary.
|
In this case, client applications take responsibility for
|
keeping an "undo" history.
|
</para>
|
</listitem>
|
|
<listitem>
|
<para>
|
Maintain a record of each update to the service,
|
so that you can manually "undo" mistakes.
|
</para>
|
|
<para>
|
You can use the external change log.
|
A primary advantage to the external change log is
|
that the change log is enabled with replication,
|
and so it does not use additional space.
|
</para>
|
|
<para>
|
See <xref linkend="repl-change-notification" /> for instructions
|
on enabling, using, and configuring the external change log.
|
In particular, see <xref linkend="ecl-add-attributes" />
|
for instructions on saving not only what is changed,
|
but also all attributes when an entry is deleted.
|
</para>
|
|
<para>
|
OpenDJ also provides a file-based audit log,
|
but the audit log does not help with a general solution in this case.
|
The OpenDJ audit log records changes to the data.
|
When you delete an entry however,
|
the audit log does not record the entry before deletion.
|
The following example shows the audit log records of some changes
|
made to Barbara Jensen's entry.
|
</para>
|
|
<programlisting language="ldif">
|
# 30/Apr/2014:16:23:29 +0200; conn=7; op=10
|
dn: uid=bjensen,ou=People,dc=example,dc=com
|
changetype: modify
|
replace: description
|
description: This is the description I want.
|
-
|
replace: modifiersName
|
modifiersName: cn=Directory Manager,cn=Root DNs,cn=config
|
-
|
replace: modifyTimestamp
|
modifyTimestamp: 20140430142329Z
|
|
# 30/Apr/2014:16:23:46 +0200; conn=7; op=14
|
dn: uid=bjensen,ou=People,dc=example,dc=com
|
changetype: modify
|
replace: description
|
description: I never should have changed this!
|
-
|
replace: modifiersName
|
modifiersName: cn=Directory Manager,cn=Root DNs,cn=config
|
-
|
replace: modifyTimestamp
|
modifyTimestamp: 20140430142346Z
|
|
# 30/Apr/2014:16:24:53 +0200; conn=7; op=27
|
dn: uid=bjensen,ou=People,dc=example,dc=com
|
changetype: delete
|
|
</programlisting>
|
|
<para>
|
You can use these records to fix the mistaken update to the description,
|
but the audit log lacks the information needed to restore
|
Barbara Jensen's deleted entry.
|
</para>
|
</listitem>
|
|
<listitem>
|
<para>
|
For administrative errors that involve directory data,
|
if you have properly configured the external change log, then use it.
|
</para>
|
|
<para>
|
If not, an alternative technique consists of restoring backup
|
to a separate server not connected to the replication topology.
|
(Do not connect the server to the topology
|
as replication replays mistakes, too.)
|
Compare data on the separate restored server
|
to the live servers in the topology,
|
and then fix the mistakes manually.
|
</para>
|
|
<para>
|
An more drastic alternative consists of
|
rebuilding the entire service from backup,
|
by disabling replication and restoring all servers from backup
|
(or restoring one server and initializing all servers from that one).
|
This alternative is only recommended in the case of a major error
|
where you have a very fresh backup (taken immediately before the error),
|
and no client applications are affected.
|
</para>
|
</listitem>
|
|
<listitem>
|
<para>
|
For administrative configuration errors that prevent servers from starting,
|
know that OpenDJ keeps a copy of the last configuration
|
that OpenDJ could use to start the server in the file
|
<filename>/path/to/opendj/config/config.ldif.startok</filename>.
|
</para>
|
|
<para>
|
OpenDJ also backs up earlier versions of the configuration under
|
<filename>/path/to/opendj/config/archived-configs/</filename>.
|
</para>
|
|
<para>
|
You can therefore compare the current configuration
|
with the earlier configurations,
|
and repair mistakes manually
|
(avoiding trailing white space at the end of LDIF lines)
|
while the server is down.
|
</para>
|
</listitem>
|
</itemizedlist>
|
|
</section>
|
</chapter>
|
