chap-replication.xml revision 51607ea01068c9047391e4c8b46bc9dbd0edb7fd
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER START
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! This work is licensed under the Creative Commons
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! To view a copy of this license, visit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! or send a letter to Creative Commons, 444 Castro Street,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Suite 900, Mountain View, California, 94041, USA.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! You can also obtain a copy of the license at
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! See the License for the specific language governing permissions
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! and limitations under the License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! If applicable, add the following below this CCPL HEADER, with the fields
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! enclosed by brackets "[]" replaced with your own identifying information:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Portions Copyright [yyyy] [name of copyright owner]
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER END
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Copyright 2011-2013 ForgeRock AS
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ uses advanced data replication with automated conflict
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark resolution to help ensure your directory services remain available in the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark event a server crashes or a network goes down, and also as you backup or
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark upgrade your directory service. You can configure data replication as part
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark of OpenDJ installation, and in many cases let replication do its work in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the background.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can set up replication during installation by choosing to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark configure replication through the setup wizard.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In the Topology Options screen for the first server you set up, select
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark This server will be part of a replication topology. If you also choose
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Configure as Secure, then replication traffic is protected by SSL.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imagedata fileref="images/replA-setup.png" format="PNG" />
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>QuickSetup makes it easy to configure replication.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </mediaobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In the Topology Options screen for subsequent servers, also select
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark There is already a server in the topology, providing the Host Name,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Administration Connector Port number, Admin User, and Admin Password for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the first replica you set up.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imagedata fileref="images/replB-setup.png" format="PNG" />
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Subsequent servers can point to the first server at setup time.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </mediaobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You also set up a global administrator account, stored under
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>cn=admin data</literal> across replicas, used to manage replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in the topology.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imagedata fileref="images/replB-global-admin.png" format="PNG" />
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The global administrator account exists on all servers in the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication topology.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </mediaobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imagedata fileref="images/replB-data-repl.png" format="PNG" />
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You choose the user data to replicate. OpenDJ automatically replicates
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark administrative data and directory schema.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </mediaobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Once replication is set up, it works for all the replicas. You can
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark monitor the replication connection and status through the OpenDJ Control
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Panel.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imagedata fileref="images/replA-monitor-repl.png" format="PNG" />
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ Control Panel indicates the status of data being
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replicated.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </mediaobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Before you take replication further than setting up replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in the setup wizard, read this section to learn more about how OpenDJ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication works.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Replication is the process of copying updates between OpenDJ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory servers such that all servers converge on identical copies of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory data. Replication is designed to let convergence happen over
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark time by default. <footnote><para>Assured replication can require, however,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark that the convergence happen before the client application is notified that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the operation was successful.</para></footnote> Letting convergence
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark happen over time means that different replicas can be momentarily out of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark sync, but it also means that if you lose an individual server or even an
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark entire data center, your directory service can keep on running, and then
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark get back in sync when the servers are restarted or the network is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark repaired.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Replication is specific to the OpenDJ directory service. Replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark uses a specific protocol that replays update operations quickly, storing
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark enough historical information about the updates to resolve most conflicts
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark automatically. For example, if two client applications separately update
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a user entry to change the phone number, replication can work out which
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark was the latest change, and apply that change across servers. The historical
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark information needed to resolve these issues is periodically purged to avoid
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark growing larger and larger forever. As a directory administrator, you must
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ensure that you do not purge the historical information more often than you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark backup your directory data.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Keep server clocks synchronized for your topology. You can use NTP for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark example. Keeping server clocks synchronized helps prevent issues with SSL
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connections and with replication itself. Keeping server clocks synchronized
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark also makes it easier to compare timestamps from multiple servers.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The primary unit of replication is the suffix, specified by a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark base DN such as <literal>dc=example,dc=com</literal>.<footnote><para>When
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you configure partial and fractional replication, however, you can replicate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark only part of a suffix, or only certain attributes on entries. Also,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark if you split your suffix across multiple backends, then you need to set up
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication separately for each part of suffix in a different backend.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </footnote> Replication also depends on the directory schema, defined on
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>cn=schema</literal>, and the <literal>cn=admin data</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark suffix with administrative identities and certificates for protecting
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark communications. Thus that content gets replicated as well.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The set of OpenDJ servers replicating data for a given suffix is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark called a replication topology. You can have more than one replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark topology. For example, one topology could be devoted to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>dc=example,dc=org</literal>. OpenDJ servers are capable of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark serving more than one suffix. They are also capable of participating in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark more than one replication topology.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <mediaobject xml:id="figure-replication-topologies-right">
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <alt>Three replication topologies set up correctly</alt>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imagedata fileref="images/repl-topologies-right.png" format="PNG" />
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In this figure, all OpenDJ servers serve the replicated suffix
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>dc=example,dc=com</literal>. Only servers A and B serve
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>dc=example,dc=org</literal>. Only server C and D serve
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </mediaobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Within a replication topology, the suffixes being replicated are
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark identified to the replication servers by their DN. As all the replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers are fully connected in a topology, a consequence is that it is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark impossible to have multiple "sub-topologies" within the overall set of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers as illustrated in the following diagram.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <mediaobject xml:id="figure-replication-topologies-wrong">
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <alt>Two replication topologies, one of which does not work</alt>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imagedata fileref="images/repl-topologies-wrong.png" format="PNG" />
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You cannot have all servers replicating both
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>dc=example,dc=org</literal>, but with all servers connected for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>dc=example,dc=com</literal> and only some of the servers
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connected for <literal>dc=example,dc=org</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </mediaobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In order to understand what happens when individual servers stop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark responding due to a network partition or a crash, know that OpenDJ can
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark offer both directory service and also replication service, and the two
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark services are not the same, even if they can run alongside each other in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the same OpenDJ server in the same Java Virtual Machine.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Replication relies on the replication service provided by OpenDJ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication servers, where OpenDJ directory servers publish changes made
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to their data, and subscribe to changes published by other OpenDJ directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers. A replication server manages replication data only, handling
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication traffic with directory servers and with other replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers, receiving, sending, and storing only changes to directory data
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark rather than directory data itself. Once a replication server is connected
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to a replication topology, it maintains connections to all other
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication servers in that topology.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>A directory server handles directory data. It responds to requests,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark stores directory data and historical information. For each replicated
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>cn=schema</literal> and <literal>cn=admin data</literal>, the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory server publishes changes to a replication server, and subscribes
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to changes from that replication server. (Directory servers do not publish
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark changes to other directory servers.) A directory server also resolves any
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark conflicts that arise when reconciling changes from other directory servers,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark using the historical information about changes to resolve the conflicts.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark (Conflict resolution is the responsibility of the directory server rather
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark than the replication server.)</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Once a directory server is connected to a replication topology for a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark particular suffix, it connects to one replication server at a time for that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark suffix. The replication server provides the directory server with a list of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark all replication servers for that suffix. Given the list of possible
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication servers to which it can connect, the directory server can
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark determine which replication server to connect to when starting up, or when
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the current connection is lost or becomes unresponsive.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <orderedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For each replicated suffix, a directory server prefers to connect to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a replication server:</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Having the same initial data for the suffix as the directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark server</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If initial data were the same, having all the latest changes from
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the directory server</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Running in the same Java Virtual Machine as the directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark server</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Having the most available capacity relative to other eligible
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication servers</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Available capacity depends on how many directory servers in the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark topology are already connected to a replication server, and what
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark proportion of all directory servers in the topology ought to be connected
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to the replication server.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To determine what proportion of the total number of directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers should be connected to a replication server, OpenDJ uses
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication server weight. When configuring a replication server, you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark can assign it a weight (default: 1). The weight property takes an integer
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark that indicates capacity to provide replication service relative to other
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers. For example, a weight of 2 would indicate a replication server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark that can handle twice as many connected servers as a replication server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark with weight 1.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The proportion of directory servers in a topology that should be
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark connected to a given replication server is equal to (replication server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark weight)/(sum of replication server weights). In other words, if there are
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 4 replication servers in a topology each with default weights, the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark proportion for each replication server is 1/4.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </orderedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Consider a situation where 7 directory servers are connected to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication servers A, B, C, and D for <literal>dc=example,dc=com</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark data. Suppose 2 directory servers each are connected to A, B, and C, and 1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory server is connected to replication server D. Replication server D
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark is therefore the server with the most available capacity relative to other
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication servers in the topology. All other criteria being equal,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication server D is the server to connect to when an 8th directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark server joins the topology.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The directory server regularly updates the list of replication servers
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in case it must reconnect. As available capacity of replication servers for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark each replication topology can change dynamically, a directory server can
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark potentially reconnect to another replication server to balance the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication load in the topology. For this reason the server can also end
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark up connected to different replication servers for different suffixes.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This section shows how to configure replication with command-line
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark tools.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can start the replication process by using the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <command>dsreplication enable</command> command.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsreplication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminUID admin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port1 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN1 "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword1 password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --replicationPort1 8989
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port2 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN2 "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword2 password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --replicationPort2 8989
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkEstablishing connections ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkChecking registration information ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating remote references on server opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkConfiguring Replication port on server opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN dc=example,dc=com on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN dc=example,dc=com on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating registration configuration on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating registration configuration on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN cn=schema on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN cn=schema on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkInitializing registration information on server opendj2.example.com:4444 with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the contents of server opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkInitializing schema on server opendj2.example.com:4444 with the contents of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark server opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkReplication has been successfully enabled. Note that for replication to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark work you must initialize the contents of the base DN's that are being
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replicated (use dsreplication initialize to do so).
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkfor a detailed log of this operation.</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To enable secure connections for replication use the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <option>--secureReplication2</option> options, which are equivalent to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark selecting Configure as Secure in the replication topology options screen of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the setup wizard.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>As you see in the command output, replication is set up to function
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark once enabled. You must however initialize replication in order to start
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the process.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When scripting the configuration to set up multiple replicas in quick
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark succession, use the same initial replication server each time you run the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark command. In other words, pass the same <option>--host1</option>,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <option>--bindPassword1</option>, and <option>--replicationPort1</option>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark options for each of the other replicas that you set up in your
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark script.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you need to add another OpenDJ directory server to participate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in replication, use the <command>dsreplication enable</command> with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the new server as the second server.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can initialize replication between servers by performing
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark initialization over the network after you have enabled replication, or by
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark importing the same LDIF data on all servers and then enabling replication.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark You can also add a new server by restoring a backup from an existing replica
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark onto the new server and then enabling replication with an existing
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replica.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The alternatives are described step-by-step in the following
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark procedures.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem><para><xref linkend="init-repl-online" /></para></listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem><para><xref linkend="init-repl-ldif" /></para></listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <listitem><para><xref linkend="init-repl-backup" /></para></listitem>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Initialize Replication Over the Network</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Initialization over the network while the server is online works well
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark when you have no initial data, or when your network bandwidth is large
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark compared to the initial amount of data to replicate.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>See <xref linkend="enable-repl" /> for instructions.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Start replication with the <command>dsreplication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsreplication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark initialize-all
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminUID admin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkInitializing base DN dc=example,dc=com with the contents from
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj.example.com:4444: 160 entries processed (100 % complete).
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkBase DN initialized successfully.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkfor a detailed log of this operation.</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Initialize All Servers From the Same LDIF</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This procedure can be useful when you are starting with a large amount
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark of directory data that is available locally to all directory servers.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Import the same LDIF on all servers as described in the procedure,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <link xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href="admin-guide#import-ldif"><citetitle>To Import LDIF
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Do not yet accept updates to the directory data.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <xref linkend="read-only-repl" /> shows how to prevent replicas from
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark accepting updates from clients.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>See <xref linkend="enable-repl" /> for instructions.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Allow updates to the directory data by setting
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>writability-mode:enabled</literal> using a command like the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark one you found in <xref linkend="read-only-repl" />.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Create a New Replica From Existing Backup</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can create a new replica from a backup of a server in the existing
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark topology.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Install a new server to use as the new replica.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Backup the database on an existing server as described in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <link xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href="admin-guide#backup"><citetitle>Backing Up Directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>At this point, other servers in the topology can continue to process
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark updates.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsreplication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminUID admin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port1 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN1 "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword1 password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --replicationPort1 8989
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port2 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN2 "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword2 password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --replicationPort2 8989
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkEstablishing connections ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkChecking registration information ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating remote references on server opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkConfiguring Replication port on server opendj3.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN dc=example,dc=com on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN dc=example,dc=com on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj3.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN dc=example,dc=com on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating remote references on server opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating registration configuration on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating registration configuration on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj3.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating registration configuration on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN cn=schema on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN cn=schema on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj3.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN cn=schema on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkInitializing registration information on server opendj3.example.com:4444 with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the contents of server opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkReplication has been successfully enabled. Note that for replication to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark work you must initialize the contents of the base DN's that are being
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replicated (use dsreplication initialize to do so).
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkfor a detailed log of this operation.</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Contrary to the message from the command, you do not need to use
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the <command>dsreplication initialize</command> command at this
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark point.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>On the new server, restore the database from the backup
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark archive as described in the procedure, <link xlink:show="new"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href="admin-guide#restore-replica"><citetitle>To Restore a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>As long as you restore the database on the new replica before the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication purge delay runs out, updates processed by other servers after
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you created the backup are replicated to the new server after you restore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the data.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>How you stop replication depends on whether the change is meant to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark be temporary or permanent.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Stop Replication Temporarily For a Replica</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you need to stop a server from replicating temporarily, you can
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark do so using <command>dsconfig</command> command.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Do not allow modifications on the replica for which replication is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark disabled, as no record of such changes is kept, and the changes cause
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication to diverge.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </warning>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Disable the multimaster synchronization provider.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-synchronization-provider-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set enabled:false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When you are ready to resume replication, enable the multimaster
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark synchronization provider.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-synchronization-provider-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set enabled:true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Stop Replication Permanently For a Replica</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you need to stop a server from replicating permanently, for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark example in preparation to remove a server, you can do so with the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <command>dsreplication disable</command> command.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Stop replication using the <command>dsreplication disable</command>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark command.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsreplication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --disableAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkEstablishing connections ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkDisabling replication on base DN cn=admin data of server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkDisabling replication on base DN dc=example,dc=com of server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkDisabling replication on base DN cn=schema of server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkDisabling replication port 8989 of server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkRemoving registration information ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkRemoving truststore information ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkfor a detailed log of this operation.</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The <command>dsreplication disable</command> as shown completely
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark removes the replication configuration information from the server.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you want to restart replication for the server, you need to run
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the <command>dsreplication enable</command> and <command>dsreplication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Replication in OpenDJ is designed to be both easy to implement in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark environments with a few servers, and also scalable in environments with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark many servers. You can enable the replication service on each OpenDJ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory server in your deployment, for example, to limit the number
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark of servers you deploy. Yet in a large deployment, you can use stand-alone
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication servers — OpenDJ servers that do nothing but relay
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication messages — to configure (and troubleshoot) the replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark service separately from the directory service. You only need a few
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark stand-alone replication servers publishing changes to serve many directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers subscribed to the changes. Furthermore, replication is designed
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark such that you need only connect a directory server to the nearest
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication server for the directory server to replicate with all others
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in your topology. Yet only the stand-alone replication servers participate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in fully-meshed replication.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>All replication servers in a topology are connected to all other
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication servers. Directory servers are connected only to one replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark server at a time, and their connections should be to replication servers on
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the same LAN. Therefore the total number of replication connections,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Total<subscript>conn</subscript> is expressed as follows.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <equation>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <mathphrase>Total<subscript>conn</subscript> = (N<subscript>RS</subscript> *
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark N<subscript>RS</subscript>-1)/2 + N<subscript>DS</subscript></mathphrase>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </equation>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Here, N<subscript>RS</subscript> is the number of replication servers,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and N<subscript>DS</subscript> is the number of stand-alone directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers. In other words, if you have only 3 servers, then
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Total<subscript>conn</subscript> is 3 with no stand-alone servers.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark However, if you have two data centers, and need 12 directory servers, then
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark with no stand-alone directory servers Total<subscript>conn</subscript> is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark (12 * 11)/2 or 66. Yet, with 4 stand-alone replication servers, and 12
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark stand-alone directory servers, Total<subscript>conn</subscript> is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark (4 * 3)/2 + 12, or 18, with only four of those connections needing to go
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark over the WAN. (By running four directory servers that also run replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers and eight stand-alone directory servers, you reduce the number of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication connections to 14 for 12 replicas.)</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <alt>Dedicated servers versus consolidated instances</alt>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imagedata fileref="images/standalone-repl.png" format="PNG"/>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Dedicated servers are suited to environments with large numbers
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark of replicas.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </mediaobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If you set up OpenDJ directory server to replicate by using the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Quick Setup wizard, then the wizard activated the replication service for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark that server. You can turn off the replication service on OpenDJ directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark server, and then configure the server to work with a separate, stand-alone
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication server instead. Start by using the <command>dsreplication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark disable --disableReplicationServer</command> command to turn off the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication service on the server.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Set Up a Stand-alone Replication Server</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This example sets up a stand-alone replication server to handle
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the replication traffic between two directory servers that do not
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark handle replication themselves.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Here the replication server is <literal>rs.example.com</literal>. The
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory servers are <literal>opendj.example.com</literal> and
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In a real deployment, you would have more replication servers
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to avoid a single point of failure.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Setup the replication server as a directory server that has
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark no database.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Setup the directory servers as stand-alone directory servers.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Enable replication with the appropriate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <option>--onlyReplicationServer</option> options.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsreplication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminUID admin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port1 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN1 "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword1 password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --noReplicationServer1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port2 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN2 "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword2 password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --replicationPort2 8989
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --onlyReplicationServer2
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkEstablishing connections ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkOnly one replication server will be defined for the following base DN's:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkIt is recommended to have at least two replication servers (two changelogs) to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkavoid a single point of failure in the replication topology.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkChecking registration information ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkConfiguring Replication port on server rs.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN dc=example,dc=com on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating registration configuration on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating registration configuration on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark rs.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN cn=schema on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkInitializing registration information on server rs.example.com:4444 with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the contents of server opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkReplication has been successfully enabled. Note that for replication to work
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you must initialize the contents of the base DN's that are being
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replicated (use dsreplication initialize to do so).
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkfor a detailed log of this operation.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark$ dsreplication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminUID admin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port1 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN1 "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword1 password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --noReplicationServer1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port2 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN2 "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword2 password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --replicationPort2 8989
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --onlyReplicationServer2
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkEstablishing connections ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkOnly one replication server will be defined for the following base DN's:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkIt is recommended to have at least two replication servers (two changelogs) to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkavoid a single point of failure in the replication topology.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkChecking registration information ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating remote references on server rs.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN dc=example,dc=com on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN dc=example,dc=com on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating registration configuration on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating registration configuration on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark rs.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating registration configuration on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN cn=schema on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj2.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkUpdating replication configuration for baseDN cn=schema on server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkInitializing registration information on server opendj2.example.com:4444 with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the contents of server rs.example.com:4444 ..... Done.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkReplication has been successfully enabled. Note that for replication to work
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you must initialize the contents of the base DN's that are being
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replicated (use dsreplication initialize to do so).
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark/var/folders/.../opends-replication-5893037538856033562.log
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkfor a detailed log of this operation.</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Initialize replication from one of the directory servers.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsreplication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark initialize-all
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminUID admin
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --adminPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkInitializing base DN dc=example,dc=com with the contents from
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark opendj.example.com:4444: 160 entries processed (100 % complete).
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkBase DN initialized successfully.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkfor a detailed log of this operation.</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Replication lets you define groups so that replicas communicate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark first with replication servers in the group before going to replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers outside the group. Groups are identified with unique numeric
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark group IDs.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Replication groups are designed for deployments across multiple data
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark centers, where you aim to focus replication traffic on the LAN rather than
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the WAN. In multi-data center deployments, group nearby servers
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark together.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For each group, set the appropriate group ID for the topology
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark on both the replication servers and the directory servers.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The example commands in this procedure set up two replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark groups, each with a replication server and a directory server. The
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory servers are <literal>opendj.example.com</literal> and
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>opendj2.example.com</literal>. The replication servers
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>rs2.example.com</literal>. In a full-scale deployment, you would
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark have multiple servers of each type in each group, such as all the replicas
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and replication servers in each data center being in the same group.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Set the group ID for each group by replication domain on the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark directory servers.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-replication-domain-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --domain-name "dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set group-id:1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-replication-domain-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --domain-name "dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set group-id:2
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Set the group ID for each group on the replication servers.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-replication-server-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set group-id:1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-replication-server-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set group-id:2
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>By default all directory servers in a replication topology are
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark read-write. You can however choose to make replicas take updates only
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark from the replication protocol, and refuse updates from client
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark applications.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-global-configuration-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set writability-mode:internal-only
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In standard replication, when a client requests an update operation
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the directory server performs the update and, if the update is successful,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark sends information about the update to the replication service, and sends
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark a result code to the client application right away. As a result, the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark client application can conclude that the update was successful,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <emphasis>but only on the replica that handled the update</emphasis>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Assured replication lets you force the replica performing the initial
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark update to wait for confirmation that the update has been received elsewhere
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in the topology before sending a result code to the client application.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark You can configure assured replication either to wait for one or more
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication servers to acknowledge having received the update, or to wait
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark for all directory servers to have replayed the update.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>As you might imagine, assured replication is theoretically safer than
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark standard replication, yet it is also slower, potentially waiting for a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark timeout before failing when the network or other servers are down.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Ensure Updates Reach Replication Servers</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Safe data mode requires the update be sent to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>assured-sd-level</literal> replication servers before
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark acknowledgement is returned to the client application.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For each directory server, set safe data mode for the replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark domain, and also set the safe data level.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-replication-domain-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --domain-name "dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set assured-type:safe-data
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set assured-sd-level:1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-replication-domain-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --domain-name "dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set assured-type:safe-data
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set assured-sd-level:1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Ensure Updates Are Replayed Everywhere</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Safe read mode requires the update be replayed on all directory
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark servers before acknowledgement is returned to the client application.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For each directory server, set safe read mode for the replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark domain.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-replication-domain-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --domain-name "dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set assured-type:safe-read
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-replication-domain-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --domain-name "dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set assured-type:safe-read
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When working with assured replication, the replication server property
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>degraded-status-threshold</literal> (default: 5000), sets the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark number of operations allowed to build up in the replication queue before
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the server is assigned degraded status. When a replication server has
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark degraded status, assured replication ceases to have an effect.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ can perform subtree replication, for example replicating
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ou=People,dc=example,dc=com</literal>, but not the rest of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>dc=example,dc=com</literal>, by putting the subtree in a separate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark backend from the rest of the suffix.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For example, in this case you might have a <literal>userRoot</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark backend containing everything in <literal>dc=example,dc=com</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark except <literal>ou=People,dc=example,dc=com</literal>, and a separate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ou=People,dc=example,dc=com</literal>. Then you replicate
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>ou=People,dc=example,dc=com</literal> in its own topology.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ can perform fractional replication, whereby you specify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the attributes to include in or to exclude from the replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark process.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You set fractional replication configuration as
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>fractional-exclude</literal> properties for a replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark domain. When you include attributes, the attributes that are required on
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the relevant object classes are also included, whether you specify them
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark or not. When you exclude attributes, the excluded attributes must be
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark optional attributes for the relevant object classes. Fractional
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replicas still respect schema definitions.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Fractional replication works by filtering objects at the replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark server. Initialize replication as you would normally. Of course you cannot
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark create a full replica from a replica with only a subset of the data. If you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark must prevent data from being replicated across a national boundary, split
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the replication server handling the updates from the directory servers
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark receiving the updates as described in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For example, you might configure an externally facing
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark fractional replica to include only some <literal>inetOrgPerson</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attributes.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-replication-domain-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --domain-name "dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark fractional-include:inetorgperson:cn,givenname,mail,mobile,sn,telephonenumber</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>As another example, you might exclude a custom attribute called
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>sessionToken</literal> from being replicated.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-replication-domain-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --domain-name "dc=example,dc=com"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set fractional-exclude:*:sessionToken
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This last example only works if you first define a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>sessionToken</literal> attribute in the directory server
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark schema.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>Change Notification For Your Applications</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Some applications require notification when directory data updates
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark occur. For example, an application might need to sync directory data with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark another database, or the application might need to kick off other processing
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark when certain updates occur.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In addition to supporting persistent search operations, OpenDJ
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark provides an external change log mechanism to allow applications to be
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark notified of changes to directory data.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ directory servers without replication cannot expose an
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark external change log. The OpenDJ server that exposes the change log must
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark function both as a directory server, and also as a replication server for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the suffix whose changes you want logged.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Enable replication without using the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <option>--onlyReplicationServer</option> options.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>With replication enabled, the changelog data can be accessed under
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>cn=changelog</literal>. For example, the following search shows
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the publicly visible data available before any changes have been
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark made.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch --baseDN cn=changelog --port 1389 "(objectclass=*)" \* +
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=changelog
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: changelog
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: container
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksubschemaSubentry: cn=schema
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkhasSubordinates: false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkentryDN: cn=changelog
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You read the external change log over LDAP. In addition, when you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark poll the change log periodically, you can get the list of updates that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark happened since your last request.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The external change log mechanism uses an LDAP control with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark OID <literal>1.3.6.1.4.1.26027.1.5.4</literal> to allow the exchange
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark of cookies for the client application to bookmark the last changes seen,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and then start reading the next set of changes from where it left off on
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the previous request.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>This procedure shows the client reading the change log as
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>cn=Directory Manager</literal>. Make sure your client application
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark reads the changes with sufficient access to view all the changes it
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark needs to see.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Send an initial search request using the LDAP control with no
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark cookie value.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Notice the value of the <literal>changeLogCookie</literal> attribute
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark for the last of the two changes.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN cn=changelog
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --control "1.3.6.1.4.1.26027.1.5.4:false"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(objectclass=*)"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=changelog
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: changelog
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: container
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksubschemaSubentry: cn=schema
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkhasSubordinates: true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkentryDN: cn=changelog
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark# Public changelog exchange control(1.3.6.1.4.1.26027.1.5.4):
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark dc=example,dc=com:0000013087cbc28212d100000001;
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: replicationCSN=0000013087cbc28212d100000001,dc=example,dc=com,cn=changelog
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktargetDN: cn=arsene lupin,ou=special users,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangeNumber: 0
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchanges:: b2JqZWN0Q2xhc3M6IHBlcnNvbgpvYmplY3RDbGFzczogdG9wCmNuOiBBcnNlbmUgTHVwaW
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 4KdGVsZXBob25lTnVtYmVyOiArMzMgMSAyMyA0NSA2NyA4OQpzbjogTHVwaW4KZW50cnlVVUlEOiA5M
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark GM3MTRmNy00ODZiLTRkNDctOTQwOS1iNDRkMTlkZWEzMWUKY3JlYXRlVGltZXN0YW1wOiAyMDExMDYx
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark MzA2NTg1NVoKY3JlYXRvcnNOYW1lOiBjbj1EaXJlY3RvcnkgTWFuYWdlcixjbj1Sb290IEROcyxjbj1
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangeType: add
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangeTime: 20110613065855Z
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: changeLogEntry
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktargetEntryUUID: 90c714f7-486b-4d47-9409-b44d19dea31e
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplicationCSN: 0000013087cbc28212d100000001
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarknumSubordinates: 0
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplicaIdentifier: 4817
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangeLogCookie: dc=example,dc=com:0000013087cbc28212d100000001;
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangeInitiatorsName: cn=Directory Manager,cn=Root DNs,cn=config
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksubschemaSubentry: cn=schema
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkhasSubordinates: false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkentryDN: replicationCSN=0000013087cbc28212d100000001,dc=example,dc=com,cn=change
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark# Public changelog exchange control(1.3.6.1.4.1.26027.1.5.4):
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark dc=example,dc=com:0000013087cbc34a12d100000002;
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: replicationCSN=0000013087cbc34a12d100000002,dc=example,dc=com,cn=changelog
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktargetDN: cn=horace velmont,ou=special users,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangeNumber: 0
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchanges:: b2JqZWN0Q2xhc3M6IHBlcnNvbgpvYmplY3RDbGFzczogdG9wCmNuOiBIb3JhY2UgVmVsbW
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 9udAp0ZWxlcGhvbmVOdW1iZXI6ICszMyAxIDEyIDIzIDM0IDQ1CnNuOiBWZWxtb250CmVudHJ5VVVJR
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark DogNmIyMjQ0MGEtNzZkMC00MDMxLTk0YjctMzViMWQ4NmYwNjdlCmNyZWF0ZVRpbWVzdGFtcDogMjAx
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark MTA2MTMwNjU4NTVaCmNyZWF0b3JzTmFtZTogY249RGlyZWN0b3J5IE1hbmFnZXIsY249Um9vdCBETnM
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark sY249Y29uZmlnCg==
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangeType: add
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangeTime: 20110613065855Z
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: changeLogEntry
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktargetEntryUUID: 6b22440a-76d0-4031-94b7-35b1d86f067e
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplicationCSN: 0000013087cbc34a12d100000002
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarknumSubordinates: 0
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplicaIdentifier: 4817
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark<emphasis>changeLogCookie: dc=example,dc=com:0000013087cbc34a12d100000002;</emphasis>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangeInitiatorsName: cn=Directory Manager,cn=Root DNs,cn=config
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksubschemaSubentry: cn=schema
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkhasSubordinates: false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkentryDN: replicationCSN=0000013087cbc34a12d100000002,dc=example,dc=com,cn=change
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In this example, two new users were added to another replica
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark before the change log request was made.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Here the changes are base64 encoded, so you can decode them using
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ base64 decode --encodedData b2JqZW...ZmlnCg==
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: person
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Horace Velmont
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktelephoneNumber: +33 1 12 23 34 45
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksn: Velmont
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkentryUUID: 6b22440a-76d0-4031-94b7-35b1d86f067e
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcreateTimestamp: 20110613065855Z
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcreatorsName: cn=Directory Manager,cn=Root DNs,cn=config
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>For the next search, provide the cookie to start reading where
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you left off last time.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In this example, a description was added to Babs Jensen's entry.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ ldapsearch
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --baseDN cn=changelog
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 1389
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --control "1.3.6.1.4.1.26027.1.5.4:false:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark dc=example,dc=com:0000013087cbc34a12d100000002;"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark "(objectclass=*)"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: cn=changelog
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: changelog
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: container
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksubschemaSubentry: cn=schema
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkhasSubordinates: true
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkentryDN: cn=changelog
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark# Public changelog exchange control(1.3.6.1.4.1.26027.1.5.4):
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark dc=example,dc=com:0000013087d7e27f12d100000003;
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: replicationCSN=0000013087d7e27f12d100000003,dc=example,dc=com,cn=changelog
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktargetDN: uid=bjensen,ou=people,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangeNumber: 0
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchanges:: YWRkOiBkZXNjcmlwdGlvbgpkZXNjcmlwdGlvbjogQSB0aGlyZCBjaGFuZ2UKLQpyZXBsYW
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark NlOiBtb2RpZmllcnNOYW1lCm1vZGlmaWVyc05hbWU6IGNuPURpcmVjdG9yeSBNYW5hZ2VyLGNuPVJvb
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark 3QgRE5zLGNuPWNvbmZpZwotCnJlcGxhY2U6IG1vZGlmeVRpbWVzdGFtcAptb2RpZnlUaW1lc3RhbXA6
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark IDIwMTEwNjEzMDcxMjEwWgotCg==
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangeType: modify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangeTime: 20110613071210Z
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: top
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkobjectClass: changeLogEntry
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarktargetEntryUUID: fc252fd9-b982-3ed6-b42a-c76d2546312c
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplicationCSN: 0000013087d7e27f12d100000003
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarknumSubordinates: 0
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplicaIdentifier: 4817
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangeLogCookie: dc=example,dc=com:0000013087d7e27f12d100000003;
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkchangeInitiatorsName: cn=Directory Manager,cn=Root DNs,cn=config
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarksubschemaSubentry: cn=schema
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkhasSubordinates: false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkentryDN: replicationCSN=0000013087d7e27f12d100000003,dc=example,dc=com,cn=change
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If we base64-decode the changes, we see the following.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkadd: description
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdescription: A third change
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplace: modifiersName
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkmodifiersName: cn=Directory Manager,cn=Root DNs,cn=config
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkreplace: modifyTimestamp
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkmodifyTimestamp: 20110613071210Z
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If for some reason you lose the cookie, you can start over from
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the earliest available change by sending a search request with no
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark value for the cookie.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <title>To Include Unchanged Attributes in the External Change Log</title>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>As shown above, the changes returned from a search on the external
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark change log include only what was actually changed. If you have applications
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark that need additional attributes published with every change log entry,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark regardless of whether or not the attribute itself has changed, then specify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Set the attributes to include for all update operations with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-external-changelog-domain-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --domain-name dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set ecl-include:"@person"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Set the attributes to include for deletes with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-external-changelog-domain-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --domain-name dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --add ecl-include-for-deletes:"*"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --add ecl-include-for-deletes:"+"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can limit external change log content by disabling the domain
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark for a base DN. By default, <literal>cn=schema</literal> and
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>cn=admin data</literal> are not enabled.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Prevent OpenDJ from logging changes by disabling the domain.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <screen>$ dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-external-changelog-domain-prop
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --port 4444
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindDN "cn=Directory Manager"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --bindPassword password
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --provider-name "Multimaster Synchronization"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --domain-name dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --set enabled:false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --trustAll
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark --no-prompt</screen>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para xml:id="ecl-legacy-format">The external change log can also work for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark applications that follow the <link
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:href="http://tools.ietf.org/html/draft-good-ldap-changelog-04"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark >Internet-Draft: Definition of an Object Class to Hold LDAP Change
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Records</link>. Nothing special is required to get the objects specified for
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark this legacy format. Such applications cannot however use the change log
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark cookies that are shared across the replication topology, and therefore
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark can continue to be used after failover to another replica in a multi-master
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark replication environment.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>