6443N/A<?xml version="1.0" encoding="UTF-8"?>

6443N/A<chapter xml:id='chap-replication'

6443N/A xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'

6443N/A xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

7073N/A xsi:schemaLocation='http://docbook.org/ns/docbook

7089N/A xmlns:xlink='http://www.w3.org/1999/xlink'>

6443N/A <title>Managing Data Replication</title>

6443N/A

6443N/A <para>OpenDJ uses advanced data replication with automated conflict

6443N/A resolution to help ensure your directory services remain available in the

6443N/A event a server crashes or a network goes down, and also as you backup or

6443N/A upgrade your directory service. You can configure data replication as part

6443N/A of OpenDJ installation, and in many cases let replication do its work in

6443N/A the background.</para>

6443N/A

6443N/A <section xml:id="repl-quick-setup">

6443N/A <title>Replication Quick Setup</title>

6443N/A <indexterm>

6443N/A <primary>Replication</primary>

6443N/A <secondary>Quick setup</secondary>

6443N/A </indexterm>

6443N/A <indexterm>

6443N/A <primary>High availability</primary>

6443N/A <see>Replication</see>

6443N/A </indexterm>

6443N/A

6443N/A <para>You can set up replication during installation by choosing to

6443N/A configure replication through the setup wizard.</para>

6443N/A

6443N/A <para>In the Topology Options screen for the first server you set up, select

6443N/A This server will be part of a replication topology. If you also choose

6443N/A Configure as Secure, then replication traffic is protected by SSL.</para>

6443N/A

6443N/A <mediaobject xml:id="figure-repla-setup">

6443N/A <imageobject>

6443N/A <imagedata fileref="images/replA-setup.png" format="PNG" />

6443N/A </imageobject>

6443N/A <textobject>

6443N/A <para>QuickSetup makes it easy to configure replication.</para>

6443N/A </textobject>

6443N/A </mediaobject>

6443N/A

6443N/A <para>In the Topology Options screen for subsequent servers, also select

6443N/A There is already a server in the topology, providing the Host Name,

6443N/A Administration Connector Port number, Admin User, and Admin Password for

6443N/A the first replica you set up.</para>

6443N/A

6443N/A <mediaobject xml:id="figure-replb-setup">

6443N/A <imageobject>

6443N/A <imagedata fileref="images/replB-setup.png" format="PNG" />

6443N/A </imageobject>

6443N/A <textobject>

6443N/A <para>Subsequent servers can point to the first server at setup time.</para>

6443N/A </textobject>

6443N/A </mediaobject>

6443N/A

6443N/A <para>You also set up a global administrator account, stored under

6443N/A <literal>cn=admin data</literal> across replicas, used to manage replication

6443N/A in the topology.</para>

6443N/A

6443N/A <mediaobject xml:id="figure-replb-global-admin">

6443N/A <imageobject>

6443N/A <imagedata fileref="images/replB-global-admin.png" format="PNG" />

6443N/A </imageobject>

6443N/A <textobject>

6443N/A <para>The global administrator account exists on all servers in the

6443N/A replication topology.</para>

6443N/A </textobject>

6443N/A </mediaobject>

6443N/A

6443N/A <para>You further set up what to replicate.</para>

6443N/A

6443N/A <mediaobject xml:id="figure-replb-data-repl">

6443N/A <imageobject>

6443N/A <imagedata fileref="images/replB-data-repl.png" format="PNG" />

6443N/A </imageobject>

6443N/A <textobject>

6443N/A <para>You choose the user data to replicate. OpenDJ automatically replicates

6443N/A administrative data and directory schema.</para>

6443N/A </textobject>

6443N/A </mediaobject>

6443N/A

6443N/A <para>Once replication is set up, it works for all the replicas. You can

6443N/A monitor the replication connection and status through the OpenDJ Control

6443N/A Panel.</para>

6443N/A

6443N/A <mediaobject xml:id="figure-repla-monitor-repl">

6443N/A <imageobject>

6443N/A <imagedata fileref="images/replA-monitor-repl.png" format="PNG" />

6443N/A </imageobject>

6443N/A <textobject>

6443N/A <para>OpenDJ Control Panel indicates the status of data being

6443N/A replicated.</para>

6443N/A </textobject>

6443N/A </mediaobject>

6443N/A

6443N/A </section>

6443N/A

6443N/A <section xml:id="about-repl">

6443N/A <title>About Replication</title>

6443N/A <indexterm>

6443N/A <primary>Replication</primary>

6443N/A <secondary>Overview</secondary>

6443N/A </indexterm>

6443N/A

6443N/A <para>Before you take replication further than setting up replication

6443N/A in the setup wizard, read this section to learn more about how OpenDJ

6443N/A replication works.</para>

6443N/A

6443N/A <section xml:id="repl-what-it-is">

6443N/A <title>What Replication Is</title>

6443N/A

6443N/A <para>Replication is the process of copying updates between OpenDJ

6443N/A directory servers such that all servers converge on identical copies of

6443N/A directory data. Replication is designed to let convergence happen over

6443N/A time by default. <footnote><para>Assured replication can require, however,

6443N/A that the convergence happen before the client application is notified that

6443N/A the operation was successful.</para></footnote> Letting convergence

6443N/A happen over time means that different replicas can be momentarily out of

6443N/A sync, but it also means that if you lose an individual server or even an

6443N/A entire data center, your directory service can keep on running, and then

6443N/A get back in sync when the servers are restarted or the network is

6443N/A repaired.</para>

6443N/A

6443N/A <para>Replication is specific to the OpenDJ directory service. Replication

6443N/A uses a specific protocol that replays update operations quickly, storing

6443N/A enough historical information about the updates to resolve most conflicts

6443N/A automatically. For example, if two client applications separately update

6443N/A a user entry to change the phone number, replication can work out which

6443N/A was the latest change, and apply that change across servers. The historical

6443N/A information needed to resolve these issues is periodically purged to avoid

6443N/A growing larger and larger forever. As a directory administrator, you must

6443N/A ensure that you do not purge the historical information more often than you

6443N/A backup your directory data.</para>

6443N/A

6443N/A <para>Keep server clocks synchronized for your topology. You can use NTP for

6443N/A example. Keeping server clocks synchronized helps prevent issues with SSL

6443N/A connections and with replication itself. Keeping server clocks synchronized

6443N/A also makes it easier to compare timestamps from multiple servers.</para>

6443N/A </section>

6443N/A

6443N/A <section xml:id="repl-per-suffix">

6443N/A <title>Replication Per Suffix</title>

6443N/A

6443N/A <para>The primary unit of replication is the suffix, specified by a

6443N/A base DN such as <literal>dc=example,dc=com</literal>.<footnote><para>When

6443N/A you configure partial and fractional replication, however, you can replicate

6443N/A only part of a suffix, or only certain attributes on entries. Also,

6443N/A if you split your suffix across multiple backends, then you need to set up

6443N/A replication separately for each part of suffix in a different backend.</para>

6443N/A </footnote> Replication also depends on the directory schema, defined on

6443N/A <literal>cn=schema</literal>, and the <literal>cn=admin data</literal>

6443N/A suffix with administrative identities and certificates for protecting

6443N/A communications. Thus that content gets replicated as well.</para>

6443N/A

6443N/A <para>The set of OpenDJ servers replicating data for a given suffix is

6443N/A called a replication topology. You can have more than one replication

6443N/A topology. For example, one topology could be devoted to

6443N/A <literal>dc=example,dc=com</literal>, and another to

6443N/A <literal>dc=example,dc=org</literal>. OpenDJ servers are capable of

6443N/A serving more than one suffix. They are also capable of participating in

6443N/A more than one replication topology.</para>

6443N/A

6443N/A <mediaobject xml:id="figure-replication-topologies-right">

6443N/A <alt>Three replication topologies set up correctly</alt>

6443N/A <imageobject>

6443N/A <imagedata fileref="images/repl-topologies-right.png" format="PNG" />

6443N/A </imageobject>

6443N/A <textobject>

6443N/A <para>In this figure, all OpenDJ servers serve the replicated suffix

6443N/A <literal>dc=example,dc=com</literal>. Only servers A and B serve

6443N/A <literal>dc=example,dc=org</literal>. Only server C and D serve

6443N/A <literal>dc=example,dc=net</literal>.</para>

6443N/A </textobject>

6443N/A </mediaobject>

6443N/A

6443N/A <para>Within a replication topology, the suffixes being replicated are

6443N/A identified to the replication servers by their DN. As all the replication

6443N/A servers are fully connected in a topology, a consequence is that it is

6443N/A impossible to have multiple "sub-topologies" within the overall set of

6443N/A servers as illustrated in the following diagram.</para>

6443N/A

6443N/A <mediaobject xml:id="figure-replication-topologies-wrong">

6443N/A <alt>Two replication topologies, one of which does not work</alt>

6443N/A <imageobject>

6443N/A <imagedata fileref="images/repl-topologies-wrong.png" format="PNG" />

6443N/A </imageobject>

6443N/A <textobject>

6443N/A <para>You cannot have all servers replicating both

6443N/A <literal>dc=example,dc=com</literal> and also

6443N/A <literal>dc=example,dc=org</literal>, but with all servers connected for

6443N/A <literal>dc=example,dc=com</literal> and only some of the servers

6443N/A connected for <literal>dc=example,dc=org</literal>.</para>

6443N/A </textobject>

6443N/A </mediaobject>

6443N/A </section>

6443N/A

6443N/A <section xml:id="repl-connection-selection">

6443N/A <title>Replication Connection Selection</title>

6443N/A

6443N/A <para>In order to understand what happens when individual servers stop

6443N/A responding due to a network partition or a crash, know that OpenDJ can

6443N/A offer both directory service and also replication service, and the two

6443N/A services are not the same, even if they can run alongside each other in

6443N/A the same OpenDJ server in the same Java Virtual Machine.</para>

6443N/A

6443N/A <para>Replication relies on the replication service provided by OpenDJ

6443N/A replication servers, where OpenDJ directory servers publish changes made

6443N/A to their data, and subscribe to changes published by other OpenDJ directory

6443N/A servers. A replication server manages replication data only, handling

6443N/A replication traffic with directory servers and with other replication

6443N/A servers, receiving, sending, and storing only changes to directory data

6443N/A rather than directory data itself. Once a replication server is connected

6443N/A to a replication topology, it maintains connections to all other

6443N/A replication servers in that topology.</para>

6443N/A

6443N/A <para>A directory server handles directory data. It responds to requests,

6443N/A stores directory data and historical information. For each replicated

6443N/A suffix, such as <literal>dc=example,dc=com</literal>,

6443N/A <literal>cn=schema</literal> and <literal>cn=admin data</literal>, the

6443N/A directory server publishes changes to a replication server, and subscribes

6443N/A to changes from that replication server. (Directory servers do not publish

6443N/A changes to other directory servers.) A directory server also resolves any

6443N/A conflicts that arise when reconciling changes from other directory servers,

6443N/A using the historical information about changes to resolve the conflicts.

6443N/A (Conflict resolution is the responsibility of the directory server rather

6443N/A than the replication server.)</para>

6443N/A

6443N/A <para>Once a directory server is connected to a replication topology for a

6443N/A particular suffix, it connects to one replication server at a time for that

6443N/A suffix. The replication server provides the directory server with a list of

6443N/A all replication servers for that suffix. Given the list of possible

6443N/A replication servers to which it can connect, the directory server can

6443N/A determine which replication server to connect to when starting up, or when

6443N/A the current connection is lost or becomes unresponsive.</para>

6443N/A

6443N/A <orderedlist>

6443N/A <para>For each replicated suffix, a directory server prefers to connect to

6443N/A a replication server:</para>

6443N/A

6443N/A <listitem>

6443N/A <para>In the same group as the directory server</para>

6443N/A </listitem>

6443N/A

6443N/A <listitem>

6443N/A <para>Having the same initial data for the suffix as the directory

6443N/A server</para>

6443N/A </listitem>

6443N/A

6443N/A <listitem>

6443N/A <para>If initial data were the same, having all the latest changes from

6443N/A the directory server</para>

6443N/A </listitem>

6443N/A

6443N/A <listitem>

6443N/A <para>Running in the same Java Virtual Machine as the directory

6443N/A server</para>

6443N/A </listitem>

6443N/A

6443N/A <listitem>

6443N/A <para>Having the most available capacity relative to other eligible

6443N/A replication servers</para>

6443N/A

6443N/A <para>Available capacity depends on how many directory servers in the

6443N/A topology are already connected to a replication server, and what

6443N/A proportion of all directory servers in the topology ought to be connected

6443N/A to the replication server.</para>

6443N/A

6443N/A <para>To determine what proportion of the total number of directory

6443N/A servers should be connected to a replication server, OpenDJ uses

6443N/A replication server weight. When configuring a replication server, you

6443N/A can assign it a weight (default: 1). The weight property takes an integer

6443N/A that indicates capacity to provide replication service relative to other

6443N/A servers. For example, a weight of 2 would indicate a replication server

6443N/A that can handle twice as many connected servers as a replication server

6443N/A with weight 1.</para>

6443N/A

6443N/A <para>The proportion of directory servers in a topology that should be

6443N/A connected to a given replication server is equal to (replication server

6443N/A weight)/(sum of replication server weights). In other words, if there are

6443N/A 4 replication servers in a topology each with default weights, the

6443N/A proportion for each replication server is 1/4.</para>

6443N/A </listitem>

6443N/A </orderedlist>

6443N/A

6443N/A <para>Consider a situation where 7 directory servers are connected to

6443N/A replication servers A, B, C, and D for <literal>dc=example,dc=com</literal>

6443N/A data. Suppose 2 directory servers each are connected to A, B, and C, and 1

6443N/A directory server is connected to replication server D. Replication server D

6443N/A is therefore the server with the most available capacity relative to other

6443N/A replication servers in the topology. All other criteria being equal,

6443N/A replication server D is the server to connect to when an 8th directory

6443N/A server joins the topology.</para>

6443N/A

6443N/A <para>The directory server regularly updates the list of replication servers

6443N/A in case it must reconnect. As available capacity of replication servers for

6443N/A each replication topology can change dynamically, a directory server can

6443N/A potentially reconnect to another replication server to balance the

6443N/A replication load in the topology. For this reason the server can also end

6443N/A up connected to different replication servers for different suffixes.</para>

6443N/A </section>

6443N/A </section>

6443N/A

6443N/A <section xml:id="configure-repl">

6443N/A <title>Configuring Replication</title>

6443N/A <indexterm>

6443N/A <primary>Replication</primary>

6443N/A <secondary>Configuring</secondary>

6443N/A </indexterm>

6443N/A

7255N/A <para>

7255N/A This section shows how to configure replication with command-line tools,

7255N/A such as the

7255N/A <link

7255N/A xlink:show="new"

7321N/A xlink:href="reference#dsreplication-1"

7255N/A xlink:role="http://docbook.org/xlink/role/olink"

7255N/A ><command>dsreplication</command></link> command.

7255N/A </para>

6443N/A

6443N/A <section xml:id="enable-repl">

6443N/A <title>Enabling Replication</title>

6443N/A

6443N/A <para>You can start the replication process by using the

6443N/A <command>dsreplication enable</command> command.</para>

6443N/A

7097N/A <screen>$ <userinput>dsreplication \

7097N/A enable \

7097N/A --adminUID admin \

7097N/A --adminPassword password \

7097N/A --baseDN dc=example,dc=com \

7097N/A --host1 opendj.example.com \

7097N/A --port1 4444 \

7097N/A --bindDN1 "cn=Directory Manager" \

7097N/A --bindPassword1 password \

7097N/A --replicationPort1 8989 \

7097N/A --host2 opendj2.example.com \

7097N/A --port2 4444 \

7097N/A --bindDN2 "cn=Directory Manager" \

7097N/A --bindPassword2 password \

7097N/A --replicationPort2 8989 \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

6443N/A

7097N/A<computeroutput>Establishing connections ..... Done.

6443N/AChecking registration information ..... Done.

6443N/AUpdating remote references on server opendj.example.com:4444 ..... Done.

6443N/AConfiguring Replication port on server opendj2.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN dc=example,dc=com on server

6443N/A opendj.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN dc=example,dc=com on server

6443N/A opendj2.example.com:4444 ..... Done.

6443N/AUpdating registration configuration on server

6443N/A opendj.example.com:4444 ..... Done.

6443N/AUpdating registration configuration on server

6443N/A opendj2.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN cn=schema on server

6443N/A opendj.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN cn=schema on server

6443N/A opendj2.example.com:4444 ..... Done.

6443N/AInitializing registration information on server opendj2.example.com:4444 with

6443N/A the contents of server opendj.example.com:4444 ..... Done.

6443N/AInitializing schema on server opendj2.example.com:4444 with the contents of

6443N/A server opendj.example.com:4444 ..... Done.

6443N/A

6443N/AReplication has been successfully enabled. Note that for replication to

6443N/A work you must initialize the contents of the base DN's that are being

6443N/A replicated (use dsreplication initialize to do so).

6443N/A

6443N/ASee

6443N/A/var/.../opends-replication-7958637258600693490.log

7097N/Afor a detailed log of this operation.</computeroutput>

7097N/A </screen>

6443N/A

6443N/A <para>To enable secure connections for replication use the

6443N/A <option>--secureReplication1</option> and

6443N/A <option>--secureReplication2</option> options, which are equivalent to

6443N/A selecting Configure as Secure in the replication topology options screen of

6443N/A the setup wizard.</para>

6443N/A

6443N/A <para>As you see in the command output, replication is set up to function

6443N/A once enabled. You must however initialize replication in order to start

6443N/A the process.</para>

6443N/A

6443N/A <tip>

6443N/A <para>When scripting the configuration to set up multiple replicas in quick

6443N/A succession, use the same initial replication server each time you run the

6443N/A command. In other words, pass the same <option>--host1</option>,

6443N/A <option>--port1</option>, <option>--bindDN1</option>,

6443N/A <option>--bindPassword1</option>, and <option>--replicationPort1</option>

6443N/A options for each of the other replicas that you set up in your

6443N/A script.</para>

6443N/A </tip>

6443N/A

6443N/A <para>If you need to add another OpenDJ directory server to participate

6443N/A in replication, use the <command>dsreplication enable</command> with

6443N/A the new server as the second server.</para>

6443N/A </section>

6443N/A

6443N/A <section xml:id="init-repl">

6443N/A <title>Initializing Replicas</title>

6443N/A

6443N/A <para>You can initialize replication between servers by performing

6443N/A initialization over the network after you have enabled replication, or by

6443N/A importing the same LDIF data on all servers and then enabling replication.

6443N/A You can also add a new server by restoring a backup from an existing replica

6443N/A onto the new server and then enabling replication with an existing

6443N/A replica.</para>

6443N/A

6443N/A <itemizedlist>

6443N/A <para>The alternatives are described step-by-step in the following

6443N/A procedures.</para>

6443N/A

6443N/A <listitem><para><xref linkend="init-repl-online" /></para></listitem>

6443N/A <listitem><para><xref linkend="init-repl-ldif" /></para></listitem>

6443N/A <listitem><para><xref linkend="init-repl-backup" /></para></listitem>

6443N/A </itemizedlist>

6443N/A

6443N/A <procedure xml:id="init-repl-online">

6443N/A <title>To Initialize Replication Over the Network</title>

6443N/A

6443N/A <para>Initialization over the network while the server is online works well

6443N/A when you have no initial data, or when your network bandwidth is large

6443N/A compared to the initial amount of data to replicate.</para>

6443N/A

6443N/A <step>

6443N/A <para>Enable replication on all servers.</para>

6443N/A

6443N/A <para>See <xref linkend="enable-repl" /> for instructions.</para>

6443N/A </step>

6443N/A

6443N/A <step>

6443N/A <para>Start replication with the <command>dsreplication

6443N/A initialize-all</command> command.</para>

6443N/A

7097N/A <screen>

7097N/A$ <userinput>dsreplication \

7097N/A initialize-all \

7097N/A --adminUID admin \

7097N/A --adminPassword password \

7097N/A --baseDN dc=example,dc=com \

7097N/A --hostname opendj.example.com \

7097N/A --port 4444 \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

6443N/A

7097N/A<computeroutput>Initializing base DN dc=example,dc=com with the contents from

6443N/A opendj.example.com:4444: 160 entries processed (100 % complete).

6443N/ABase DN initialized successfully.

6443N/A

6443N/ASee

6443N/A/var/.../opends-replication-5020375834904394170.log

7097N/Afor a detailed log of this operation.</computeroutput>

7097N/A </screen>

6443N/A </step>

6443N/A </procedure>

6443N/A

6443N/A <procedure xml:id="init-repl-ldif">

6443N/A <title>To Initialize All Servers From the Same LDIF</title>

6443N/A

6443N/A <para>This procedure can be useful when you are starting with a large amount

6443N/A of directory data that is available locally to all directory servers.</para>

6443N/A

6443N/A <step>

6443N/A <para>Import the same LDIF on all servers as described in the procedure,

6443N/A <link xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"

6443N/A xlink:href="admin-guide#import-ldif"><citetitle>To Import LDIF

6443N/A Data</citetitle></link>.</para>

6443N/A

6443N/A <para>Do not yet accept updates to the directory data.

6443N/A <xref linkend="read-only-repl" /> shows how to prevent replicas from

6443N/A accepting updates from clients.</para>

6443N/A </step>

6443N/A

6443N/A <step>

6443N/A <para>Enable replication for all servers.</para>

6443N/A

6443N/A <para>See <xref linkend="enable-repl" /> for instructions.</para>

6443N/A </step>

6443N/A

6443N/A <step>

6443N/A <para>Allow updates to the directory data by setting

6443N/A <literal>writability-mode:enabled</literal> using a command like the

6443N/A one you found in <xref linkend="read-only-repl" />.</para>

6443N/A </step>

6443N/A </procedure>

6443N/A

6443N/A <procedure xml:id="init-repl-backup">

6443N/A <title>To Create a New Replica From Existing Backup</title>

6443N/A

6443N/A <para>You can create a new replica from a backup of a server in the existing

6443N/A topology.</para>

6443N/A

6443N/A <step>

6443N/A <para>Install a new server to use as the new replica.</para>

6443N/A </step>

6443N/A

6443N/A <step>

6443N/A <para>Backup the database on an existing server as described in

6443N/A <link xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"

6443N/A xlink:href="admin-guide#backup"><citetitle>Backing Up Directory

6443N/A Data</citetitle></link>.</para>

6443N/A

6443N/A <para>At this point, other servers in the topology can continue to process

6443N/A updates.</para>

6443N/A </step>

6443N/A

6443N/A <step>

6443N/A <para>Enable replication on the new replica.</para>

6443N/A

7097N/A <screen>

7097N/A$ <userinput>dsreplication \

7097N/A enable \

7097N/A --adminUID admin \

7097N/A --adminPassword password \

7097N/A --baseDN dc=example,dc=com \

7097N/A --host1 opendj.example.com \

7097N/A --port1 4444 \

7097N/A --bindDN1 "cn=Directory Manager" \

7097N/A --bindPassword1 password \

7097N/A --replicationPort1 8989 \

7097N/A --host2 opendj3.example.com \

7097N/A --port2 4444 \

7097N/A --bindDN2 "cn=Directory Manager" \

7097N/A --bindPassword2 password \

7097N/A --replicationPort2 8989 \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

6443N/A

7097N/A<computeroutput>Establishing connections ..... Done.

6443N/AChecking registration information ..... Done.

6443N/AUpdating remote references on server opendj.example.com:4444 ..... Done.

6443N/AConfiguring Replication port on server opendj3.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN dc=example,dc=com on server

6443N/A opendj.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN dc=example,dc=com on server

6443N/A opendj3.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN dc=example,dc=com on server

6443N/A opendj2.example.com:4444 ..... Done.

6443N/AUpdating remote references on server opendj2.example.com:4444 ..... Done.

6443N/AUpdating registration configuration on server

6443N/A opendj.example.com:4444 ..... Done.

6443N/AUpdating registration configuration on server

6443N/A opendj3.example.com:4444 ..... Done.

6443N/AUpdating registration configuration on server

6443N/A opendj2.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN cn=schema on server

6443N/A opendj.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN cn=schema on server

6443N/A opendj3.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN cn=schema on server

6443N/A opendj2.example.com:4444 ..... Done.

6443N/AInitializing registration information on server opendj3.example.com:4444 with

6443N/A the contents of server opendj.example.com:4444 ..... Done.

6443N/A

6443N/AReplication has been successfully enabled. Note that for replication to

6443N/A work you must initialize the contents of the base DN's that are being

6443N/A replicated (use dsreplication initialize to do so).

6443N/A

6443N/ASee

6443N/A/var/.../opends-replication-1672058070147419978.log

7097N/Afor a detailed log of this operation.</computeroutput>

7097N/A </screen>

6443N/A

6443N/A <para>Contrary to the message from the command, you do not need to use

6443N/A the <command>dsreplication initialize</command> command at this

6443N/A point.</para>

6443N/A </step>

6443N/A

6443N/A <step>

6443N/A <para>On the new server, restore the database from the backup

6443N/A archive as described in the procedure, <link xlink:show="new"

6443N/A xlink:role="http://docbook.org/xlink/role/olink"

6443N/A xlink:href="admin-guide#restore-replica"><citetitle>To Restore a

6443N/A Replica</citetitle></link>.</para>

6443N/A

6443N/A <para>As long as you restore the database on the new replica before the

6443N/A replication purge delay runs out, updates processed by other servers after

6443N/A you created the backup are replicated to the new server after you restore

6443N/A the data.</para>

6443N/A </step>

6443N/A </procedure>

6443N/A </section>

6443N/A

6443N/A <section xml:id="stop-repl">

6443N/A <title>Stopping Replication</title>

6443N/A <indexterm>

6443N/A <primary>Replication</primary>

6443N/A <secondary>Stopping</secondary>

6443N/A </indexterm>

6443N/A

6443N/A <para>How you stop replication depends on whether the change is meant to

6443N/A be temporary or permanent.</para>

6443N/A

6443N/A <procedure xml:id="stop-repl-tmp">

6443N/A <title>To Stop Replication Temporarily For a Replica</title>

6443N/A

7255N/A <para>

7255N/A If you must stop a server from replicating temporarily,

7255N/A you can do so by using the

7255N/A <link

7255N/A xlink:show="new"

7321N/A xlink:href="reference#dsconfig-1"

7255N/A xlink:role="http://docbook.org/xlink/role/olink"

7255N/A ><command>dsconfig</command></link> command.

7255N/A </para>

6443N/A

6443N/A <warning>

6443N/A <para>Do not allow modifications on the replica for which replication is

6443N/A disabled, as no record of such changes is kept, and the changes cause

6443N/A replication to diverge.</para>

6443N/A </warning>

6443N/A

6443N/A <step>

6443N/A <para>Disable the multimaster synchronization provider.</para>

7097N/A

7097N/A <screen>

7097N/A$ <userinput>dsconfig \

7097N/A set-synchronization-provider-prop \

7097N/A --port 4444 \

7097N/A --hostname opendj2.example.com \

7097N/A --bindDN "cn=Directory Manager" \

7097N/A --bindPassword password \

7097N/A --provider-name "Multimaster Synchronization" \

7097N/A --set enabled:false \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

7097N/A </screen>

6443N/A </step>

7097N/A

6443N/A <step performance="optional">

6443N/A <para>When you are ready to resume replication, enable the multimaster

6443N/A synchronization provider.</para>

7097N/A

7097N/A <screen>

7097N/A$ <userinput>dsconfig \

7097N/A set-synchronization-provider-prop \

7097N/A --port 4444 \

7097N/A --hostname opendj2.example.com \

7097N/A --bindDN "cn=Directory Manager" \

7097N/A --bindPassword password \

7097N/A --provider-name "Multimaster Synchronization" \

7097N/A --set enabled:true \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

7097N/A </screen>

6443N/A </step>

6443N/A </procedure>

6443N/A

6443N/A <procedure xml:id="stop-repl-permanent">

6443N/A <title>To Stop Replication Permanently For a Replica</title>

6443N/A

6443N/A <para>If you need to stop a server from replicating permanently, for

6443N/A example in preparation to remove a server, you can do so with the

6443N/A <command>dsreplication disable</command> command.</para>

6443N/A

6443N/A <step>

6443N/A <para>Stop replication using the <command>dsreplication disable</command>

6443N/A command.</para>

7097N/A

7097N/A <screen>

7097N/A$ <userinput>dsreplication \

7097N/A disable \

7097N/A --disableAll \

7097N/A --port 4444 \

7097N/A --hostname opendj2.example.com \

7097N/A --bindDN "cn=Directory Manager" \

7097N/A --adminPassword password \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

7097N/A<computeroutput>Establishing connections ..... Done.

6443N/ADisabling replication on base DN cn=admin data of server

6443N/A opendj2.example.com:4444 ..... Done.

6443N/ADisabling replication on base DN dc=example,dc=com of server

6443N/A opendj2.example.com:4444 ..... Done.

6443N/ADisabling replication on base DN cn=schema of server

6443N/A opendj2.example.com:4444 ..... Done.

6443N/ADisabling replication port 8989 of server

6443N/A opendj2.example.com:4444 ..... Done.

6443N/ARemoving registration information ..... Done.

6443N/ARemoving truststore information ..... Done.

6443N/A

6443N/ASee

6443N/A/var/.../opends-replication-125248191132797765.log

7097N/Afor a detailed log of this operation.</computeroutput>

7097N/A </screen>

7097N/A

6443N/A <para>The <command>dsreplication disable</command> as shown completely

6443N/A removes the replication configuration information from the server.</para>

6443N/A </step>

7097N/A

6443N/A <step performance="optional">

6443N/A <para>If you want to restart replication for the server, you need to run

6443N/A the <command>dsreplication enable</command> and <command>dsreplication

6443N/A initialize</command> commands again.</para>

6443N/A </step>

6443N/A </procedure>

6443N/A </section>

6443N/A

6443N/A <section xml:id="repl-dedicated-servers">

6443N/A <title>Stand-alone Replication Servers</title>

6443N/A <indexterm>

6443N/A <primary>Replication</primary>

6443N/A <secondary>Dedicated servers</secondary>

6443N/A </indexterm>

6443N/A

6443N/A <para>Replication in OpenDJ is designed to be both easy to implement in

6443N/A environments with a few servers, and also scalable in environments with

6443N/A many servers. You can enable the replication service on each OpenDJ

6443N/A directory server in your deployment, for example, to limit the number

6443N/A of servers you deploy. Yet in a large deployment, you can use stand-alone

6443N/A replication servers &#8212; OpenDJ servers that do nothing but relay

6443N/A replication messages &#8212; to configure (and troubleshoot) the replication

6443N/A service separately from the directory service. You only need a few

6443N/A stand-alone replication servers publishing changes to serve many directory

6443N/A servers subscribed to the changes. Furthermore, replication is designed

6443N/A such that you need only connect a directory server to the nearest

6443N/A replication server for the directory server to replicate with all others

6443N/A in your topology. Yet only the stand-alone replication servers participate

6443N/A in fully-meshed replication.</para>

6443N/A

6443N/A

6443N/A <para>All replication servers in a topology are connected to all other

6443N/A replication servers. Directory servers are connected only to one replication

6443N/A server at a time, and their connections should be to replication servers on

6443N/A the same LAN. Therefore the total number of replication connections,

6443N/A Total<subscript>conn</subscript> is expressed as follows.</para>

6443N/A

6443N/A <equation>

6443N/A <mathphrase>Total<subscript>conn</subscript> = (N<subscript>RS</subscript> *

6443N/A N<subscript>RS</subscript>-1)/2 + N<subscript>DS</subscript></mathphrase>

6443N/A </equation>

6443N/A

6443N/A <para>Here, N<subscript>RS</subscript> is the number of replication servers,

6443N/A and N<subscript>DS</subscript> is the number of stand-alone directory

6443N/A servers. In other words, if you have only 3 servers, then

6443N/A Total<subscript>conn</subscript> is 3 with no stand-alone servers.

6443N/A However, if you have two data centers, and need 12 directory servers, then

6443N/A with no stand-alone directory servers Total<subscript>conn</subscript> is

6443N/A (12 * 11)/2 or 66. Yet, with 4 stand-alone replication servers, and 12

6443N/A stand-alone directory servers, Total<subscript>conn</subscript> is

6443N/A (4 * 3)/2 + 12, or 18, with only four of those connections needing to go

6443N/A over the WAN. (By running four directory servers that also run replication

6443N/A servers and eight stand-alone directory servers, you reduce the number of

6443N/A replication connections to 14 for 12 replicas.)</para>

7073N/A

7073N/A <figure xml:id="figure-standalone-repl">

7073N/A <title>Deployment For Multiple Data Centers</title>

7089N/A <mediaobject xml:id="figure-standalone-repl-image">

7073N/A <alt>Dedicated servers versus consolidated instances</alt>

7073N/A <imageobject>

7073N/A <imagedata fileref="images/standalone-repl.png" format="PNG"/>

7073N/A </imageobject>

7073N/A <textobject>

7073N/A <para>Dedicated servers are suited to environments with large numbers

7073N/A of replicas.</para>

7073N/A </textobject>

7073N/A </mediaobject>

7073N/A </figure>

6443N/A

6443N/A <tip>

6443N/A <para>If you set up OpenDJ directory server to replicate by using the

6443N/A Quick Setup wizard, then the wizard activated the replication service for

6443N/A that server. You can turn off the replication service on OpenDJ directory

6443N/A server, and then configure the server to work with a separate, stand-alone

6443N/A replication server instead. Start by using the <command>dsreplication

6443N/A disable --disableReplicationServer</command> command to turn off the

6443N/A replication service on the server.</para>

6443N/A </tip>

6443N/A

6443N/A <procedure xml:id="repl-setup-dedicated-server">

6443N/A <title>To Set Up a Stand-alone Replication Server</title>

6443N/A

6443N/A <para>This example sets up a stand-alone replication server to handle

6443N/A the replication traffic between two directory servers that do not

6443N/A handle replication themselves.</para>

6443N/A

6443N/A <para>Here the replication server is <literal>rs.example.com</literal>. The

6443N/A directory servers are <literal>opendj.example.com</literal> and

6443N/A <literal>opendj2.example.com</literal>.</para>

6443N/A

6443N/A <para>In a real deployment, you would have more replication servers

6443N/A to avoid a single point of failure.</para>

6443N/A

6443N/A <step>

6443N/A <para>Setup the replication server as a directory server that has

6443N/A no database.</para>

6443N/A </step>

6443N/A <step>

6443N/A <para>Setup the directory servers as stand-alone directory servers.</para>

6443N/A </step>

6443N/A <step>

6443N/A <para>Enable replication with the appropriate

6443N/A <option>--noReplicationServer</option> and

6443N/A <option>--onlyReplicationServer</option> options.</para>

7097N/A

7097N/A <screen>

7097N/A$ <userinput>dsreplication \

7097N/A enable \

7097N/A --adminUID admin \

7097N/A --adminPassword password \

7097N/A --baseDN dc=example,dc=com \

7097N/A --host1 opendj.example.com \

7097N/A --port1 4444 \

7097N/A --bindDN1 "cn=Directory Manager" \

7097N/A --bindPassword1 password \

7097N/A --noReplicationServer1 \

7097N/A --host2 rs.example.com \

7097N/A --port2 4444 \

7097N/A --bindDN2 "cn=Directory Manager" \

7097N/A --bindPassword2 password \

7097N/A --replicationPort2 8989 \

7097N/A --onlyReplicationServer2 \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

7097N/A<computeroutput>Establishing connections ..... Done.

6443N/AOnly one replication server will be defined for the following base DN's:

6443N/Adc=example,dc=com

6443N/AIt is recommended to have at least two replication servers (two changelogs) to

6443N/Aavoid a single point of failure in the replication topology.

6443N/A

6443N/AChecking registration information ..... Done.

6443N/AConfiguring Replication port on server rs.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN dc=example,dc=com on server

6443N/A opendj.example.com:4444 ..... Done.

6443N/AUpdating registration configuration on server

6443N/A opendj.example.com:4444 ..... Done.

6443N/AUpdating registration configuration on server

6443N/A rs.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN cn=schema on server

6443N/A opendj.example.com:4444 ..... Done.

6443N/AInitializing registration information on server rs.example.com:4444 with

6443N/A the contents of server opendj.example.com:4444 ..... Done.

6443N/A

6443N/AReplication has been successfully enabled. Note that for replication to work

6443N/A you must initialize the contents of the base DN's that are being

6443N/A replicated (use dsreplication initialize to do so).

6443N/A

6443N/ASee

6443N/A/var/.../opends-replication-1720959352638609971.log

7097N/Afor a detailed log of this operation.</computeroutput>

6443N/A

7097N/A$ <userinput>dsreplication \

7097N/A enable \

7097N/A --adminUID admin \

7097N/A --adminPassword password \

7097N/A --baseDN dc=example,dc=com \

7097N/A --host1 opendj2.example.com \

7097N/A --port1 4444 \

7097N/A --bindDN1 "cn=Directory Manager" \

7097N/A --bindPassword1 password \

7097N/A --noReplicationServer1 \

7097N/A --host2 rs.example.com \

7097N/A --port2 4444 \

7097N/A --bindDN2 "cn=Directory Manager" \

7097N/A --bindPassword2 password \

7097N/A --replicationPort2 8989 \

7097N/A --onlyReplicationServer2 \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

6443N/A

7097N/A<computeroutput>Establishing connections ..... Done.

6443N/AOnly one replication server will be defined for the following base DN's:

6443N/Adc=example,dc=com

6443N/AIt is recommended to have at least two replication servers (two changelogs) to

6443N/Aavoid a single point of failure in the replication topology.

6443N/A

6443N/AChecking registration information ..... Done.

6443N/AUpdating remote references on server rs.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN dc=example,dc=com on server

6443N/A opendj2.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN dc=example,dc=com on server

6443N/A opendj.example.com:4444 ..... Done.

6443N/AUpdating registration configuration on server

6443N/A opendj2.example.com:4444 ..... Done.

6443N/AUpdating registration configuration on server

6443N/A rs.example.com:4444 ..... Done.

6443N/AUpdating registration configuration on server

6443N/A opendj.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN cn=schema on server

6443N/A opendj2.example.com:4444 ..... Done.

6443N/AUpdating replication configuration for baseDN cn=schema on server

6443N/A opendj.example.com:4444 ..... Done.

6443N/AInitializing registration information on server opendj2.example.com:4444 with

6443N/A the contents of server rs.example.com:4444 ..... Done.

6443N/A

6443N/AReplication has been successfully enabled. Note that for replication to work

6443N/A you must initialize the contents of the base DN's that are being

6443N/A replicated (use dsreplication initialize to do so).

6443N/A

6443N/ASee

6443N/A/var/folders/.../opends-replication-5893037538856033562.log

7097N/Afor a detailed log of this operation.</computeroutput>

7097N/A </screen>

6443N/A </step>

7097N/A

6443N/A <step>

6443N/A <para>Initialize replication from one of the directory servers.</para>

6443N/A

7097N/A <screen>

7097N/A$ <userinput>dsreplication \

7097N/A initialize-all \

7097N/A --adminUID admin \

7097N/A --adminPassword password \

7097N/A --baseDN dc=example,dc=com \

7097N/A --hostname opendj.example.com \

7097N/A --port 4444 \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

7097N/A

7097N/A<computeroutput>Initializing base DN dc=example,dc=com with the contents from

6443N/A opendj.example.com:4444: 160 entries processed (100 % complete).

6443N/ABase DN initialized successfully.

6443N/A

6443N/ASee

6443N/A/var/.../opends-replication-7677303986403997574.log

7097N/Afor a detailed log of this operation.</computeroutput>

7097N/A </screen>

6443N/A </step>

6443N/A </procedure>

6443N/A </section>

7073N/A

7073N/A <section xml:id="repl-dedicated-replica">

7073N/A <title>Stand-alone Directory Server Replicas</title>

7073N/A <indexterm>

7073N/A <primary>Replication</primary>

7073N/A <secondary>Dedicated servers</secondary>

7073N/A </indexterm>

7073N/A

7073N/A <para>

7073N/A When you configure replication for an OpenDJ directory server,

7073N/A you can give the directory server the capability

7073N/A to handle replication traffic as well.

7073N/A As described in <xref linkend="repl-dedicated-servers" />,

7073N/A OpenDJ servers can also be configured to handle only replication traffic.

7073N/A </para>

7073N/A

7073N/A <para>

7073N/A Alternatively you can configure an OpenDJ directory server

7073N/A to connect to a remote replication server of either variety,

7073N/A but to remain only a directory server itself.

7073N/A This sort of stand-alone directory server replica is shown

7073N/A in <xref linkend="figure-standalone-repl" />.

7073N/A </para>

7073N/A

7073N/A <para>

7073N/A Furthermore, you can make this stand-alone directory server replica

7073N/A read-only for client applications, accepting only replication updates.

7073N/A </para>

7073N/A

7073N/A <procedure xml:id="repl-setup-dedicated-replica">

7073N/A <title>To Set Up a Stand-alone Directory Server Replica</title>

7073N/A

7073N/A <para>

7073N/A The following steps show how to configure the server

7073N/A as a stand-alone, directory server only replica

7073N/A of an existing replicated directory server.

7073N/A </para>

7073N/A

7073N/A <step>

7073N/A <para>

7073N/A Set up replication between other servers.

7073N/A </para>

7073N/A </step>

7073N/A

7073N/A <step>

7073N/A <para>

7073N/A Install the directory server without configuring replication,

7073N/A but creating at least the base entry to be replicated.

7073N/A </para>

7073N/A </step>

7073N/A

7073N/A <step>

7073N/A <para>

7073N/A Enable replication with the appropriate

7073N/A <option>--noReplicationServer</option> option.

7073N/A </para>

7073N/A

7097N/A <screen>

7097N/A$ <userinput>dsreplication \

7097N/A enable \

7097N/A --adminUID admin \

7097N/A --adminPassword password \

7097N/A --baseDN dc=example,dc=com \

7097N/A --host1 master.example.com \

7170N/A --port1 4444 \

7170N/A --bindDN1 "cn=Directory Manager" \

7097N/A --bindPassword1 password \

7097N/A --host2 ds-only.example.com \

7097N/A --port2 4444 \

7097N/A --bindDN2 "cn=Directory Manager" \

7097N/A --bindPassword2 password \

7097N/A --noReplicationServer2 \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

7073N/A

7097N/A<computeroutput>Establishing connections ..... Done.

7073N/AChecking registration information ..... Done.

7073N/AUpdating remote references on server master.example.com:4444 ..... Done.

7073N/AUpdating replication configuration for baseDN dc=example,dc=com

7073N/A on server master.example.com:4444 ..... Done.

7073N/AUpdating replication configuration for baseDN dc=example,dc=com

7073N/A on server ds-only.example.com:4444 ..... Done.

7073N/AUpdating replication configuration for baseDN dc=example,dc=com

7073N/A on server master2.example.com:4444 ..... Done.

7073N/AUpdating remote references on server master2.example.com:4444 ..... Done.

7073N/AUpdating registration configuration

7073N/A on server master.example.com:4444 ..... Done.

7073N/AUpdating registration configuration

7073N/A on server ds-only.example.com:4444 ..... Done.

7073N/AUpdating registration configuration

7073N/A on server master2.example.com:4444 ..... Done.

7073N/AUpdating replication configuration for baseDN cn=schema

7073N/A on server master.example.com:4444 ..... Done.

7073N/AUpdating replication configuration for baseDN cn=schema

7073N/A on server ds-only.example.com:4444 ..... Done.

7073N/AUpdating replication configuration for baseDN cn=schema

7073N/A on server master2.example.com:4444 ..... Done.

7073N/AInitializing registration information on server ds-only.example.com:4444

7073N/A with the contents of server master.example.com:4444 ..... Done.

7073N/AInitializing schema on server ds-only.example.com:4444

7073N/A with the contents of server master.example.com:4444 ..... Done.

7073N/A

7073N/AReplication has been successfully enabled. Note that for replication to work

7073N/A you must initialize the contents of the base DNs that are being replicated

7073N/A (use dsreplication initialize to do so).

7073N/A

7073N/ASee

7073N/A/var/.../opendj-replication-859181866587327450.log

7097N/Afor a detailed log of this operation.</computeroutput>

7097N/A </screen>

7073N/A

7073N/A <para>

7073N/A Here the existing server is both directory server and replication server.

7073N/A If the existing server is a stand-alone replication server,

7073N/A then also use the appropriate

7073N/A <option>--onlyReplicationServer</option> option.

7073N/A </para>

7073N/A </step>

7073N/A

7073N/A <step>

7073N/A <para>

7073N/A Initialize data on the new directory server replica.

7073N/A </para>

7073N/A

7097N/A <screen>

7097N/A$ <userinput>dsreplication \

7097N/A initialize \

7097N/A --adminUID admin \

7097N/A --adminPassword password \

7097N/A --baseDN dc=example,dc=com \

7097N/A --hostSource master.example.com \

7097N/A --portSource 4444 \

7097N/A --hostDestination ds-only.example.com \

7097N/A --portDestination 4444 \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

7073N/A

7097N/A<computeroutput>Initializing base DN dc=example,dc=com with the contents

7073N/A from master.example.com:4444:

7073N/A0 entries processed (0 % complete).

7073N/A176 entries processed (100 % complete).

7073N/ABase DN initialized successfully.

7073N/A

7073N/ASee

7073N/A/var/.../opendj-replication-4326340645155418876.log

7097N/Afor a detailed log of this operation.</computeroutput>

7097N/A </screen>

7073N/A </step>

7073N/A

7073N/A <step>

7073N/A <para>

7073N/A If you want to make the directory server replica

7073N/A read-only for client application traffic,

7073N/A see <xref linkend="read-only-repl" />.

7073N/A </para>

7073N/A </step>

7073N/A </procedure>

7073N/A </section>

6443N/A

6443N/A <section xml:id="repl-groups">

6443N/A <title>Replication Groups</title>

6443N/A <indexterm>

6443N/A <primary>Replication</primary>

6443N/A <secondary>Grouping servers</secondary>

6443N/A </indexterm>

6443N/A

6443N/A <para>Replication lets you define groups so that replicas communicate

6443N/A first with replication servers in the group before going to replication

6443N/A servers outside the group. Groups are identified with unique numeric

6443N/A group IDs.</para>

6443N/A

6443N/A <para>Replication groups are designed for deployments across multiple data

6443N/A centers, where you aim to focus replication traffic on the LAN rather than

6443N/A the WAN. In multi-data center deployments, group nearby servers

6443N/A together.</para>

6443N/A

6443N/A <procedure xml:id="define-repl-groups">

6443N/A <title>To Set Up Replication Groups</title>

6443N/A

6443N/A <para>For each group, set the appropriate group ID for the topology

6443N/A on both the replication servers and the directory servers.</para>

6443N/A

6443N/A <para>The example commands in this procedure set up two replication

6443N/A groups, each with a replication server and a directory server. The

6443N/A directory servers are <literal>opendj.example.com</literal> and

6443N/A <literal>opendj2.example.com</literal>. The replication servers

6443N/A are <literal>rs.example.com</literal> and

6443N/A <literal>rs2.example.com</literal>. In a full-scale deployment, you would

6443N/A have multiple servers of each type in each group, such as all the replicas

6443N/A and replication servers in each data center being in the same group.</para>

6443N/A

6443N/A <step>

6443N/A <para>Pick a group ID for each group.</para>

6443N/A <para>The default group ID is 1.</para>

6443N/A </step>

6443N/A <step>

6443N/A <para>Set the group ID for each group by replication domain on the

6443N/A directory servers.</para>

7097N/A

7097N/A <screen>

7097N/A$ <userinput>dsconfig \

7097N/A set-replication-domain-prop \

7097N/A --port 4444 \

7097N/A --hostname opendj.example.com \

7097N/A --bindDN "cn=Directory Manager" \

7097N/A --bindPassword password \

7097N/A --provider-name "Multimaster Synchronization" \

7097N/A --domain-name "dc=example,dc=com" \

7097N/A --set group-id:1 \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

6443N/A

7097N/A$ <userinput>dsconfig \

7097N/A set-replication-domain-prop \

7097N/A --port 4444 \

7097N/A --hostname opendj2.example.com \

7097N/A --bindDN "cn=Directory Manager" \

7097N/A --bindPassword password \

7097N/A --provider-name "Multimaster Synchronization" \

7097N/A --domain-name "dc=example,dc=com" \

7097N/A --set group-id:2 \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

7097N/A </screen>

6443N/A </step>

7097N/A

6443N/A <step>

6443N/A <para>Set the group ID for each group on the replication servers.</para>

7097N/A

7097N/A <screen>

7097N/A$ <userinput>dsconfig \

7097N/A set-replication-server-prop \

7097N/A --port 4444 \

7097N/A --hostname rs.example.com \

7097N/A --bindDN "cn=Directory Manager" \

7097N/A --bindPassword password \

7097N/A --provider-name "Multimaster Synchronization" \

7097N/A --set group-id:1 \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

7097N/A

7097N/A$ <userinput>dsconfig \

7097N/A set-replication-server-prop \

7097N/A --port 4444 \

7097N/A --hostname rs2.example.com \

7097N/A --bindDN "cn=Directory Manager" \

7097N/A --bindPassword password \

7097N/A --provider-name "Multimaster Synchronization" \

7097N/A --set group-id:2 \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

7097N/A </screen>

6443N/A </step>

6443N/A </procedure>

6443N/A </section>

6443N/A

6443N/A <section xml:id="read-only-repl">

6443N/A <title>Read-Only Replicas</title>

6443N/A <indexterm>

6443N/A <primary>Replication</primary>

6443N/A <secondary>Read-only servers</secondary>

6443N/A </indexterm>

6443N/A

6443N/A <para>By default all directory servers in a replication topology are

6443N/A read-write. You can however choose to make replicas take updates only

6443N/A from the replication protocol, and refuse updates from client

6443N/A applications.</para>

6443N/A

7097N/A <screen>

7097N/A$ <userinput>dsconfig \

7097N/A set-global-configuration-prop \

7097N/A --port 4444 \

7097N/A --hostname opendj2.example.com \

7097N/A --bindDN "cn=Directory Manager" \

7097N/A --bindPassword password \

7097N/A --set writability-mode:internal-only \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

7097N/A </screen>

6443N/A </section>

6443N/A

6443N/A <section xml:id="repl-assured">

6443N/A <title>Assured Replication</title>

6443N/A <indexterm>

6443N/A <primary>Replication</primary>

6443N/A <secondary>Assured</secondary>

6443N/A </indexterm>

6443N/A

6443N/A <para>In standard replication, when a client requests an update operation

6443N/A the directory server performs the update and, if the update is successful,

6443N/A sends information about the update to the replication service, and sends

6443N/A a result code to the client application right away. As a result, the

6443N/A client application can conclude that the update was successful,

6443N/A <emphasis>but only on the replica that handled the update</emphasis>.</para>

6443N/A

6443N/A <para>Assured replication lets you force the replica performing the initial

6443N/A update to wait for confirmation that the update has been received elsewhere

6443N/A in the topology before sending a result code to the client application.

6443N/A You can configure assured replication either to wait for one or more

6443N/A replication servers to acknowledge having received the update, or to wait

6443N/A for all directory servers to have replayed the update.</para>

6443N/A

6443N/A <para>As you might imagine, assured replication is theoretically safer than

6443N/A standard replication, yet it is also slower, potentially waiting for a

6443N/A timeout before failing when the network or other servers are down.</para>

6443N/A

6443N/A <procedure xml:id="repl-safe-data">

6443N/A <title>To Ensure Updates Reach Replication Servers</title>

6443N/A

6443N/A <para>Safe data mode requires the update be sent to

6443N/A <literal>assured-sd-level</literal> replication servers before

6443N/A acknowledgement is returned to the client application.</para>

6443N/A

6443N/A <step>

6443N/A <para>For each directory server, set safe data mode for the replication

6443N/A domain, and also set the safe data level.</para>

6443N/A

7097N/A <screen>

7097N/A$ <userinput>dsconfig \

7097N/A set-replication-domain-prop \

7097N/A --port 4444 \

7097N/A --hostname opendj.example.com \

7097N/A --bindDN "cn=Directory Manager" \

7097N/A --bindPassword password \

7097N/A --provider-name "Multimaster Synchronization" \

7097N/A --domain-name "dc=example,dc=com" \

7097N/A --set assured-type:safe-data \

7097N/A --set assured-sd-level:1 \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

6443N/A

7097N/A$ <userinput>dsconfig \

7097N/A set-replication-domain-prop \

7097N/A --port 4444 \

7097N/A --hostname opendj2.example.com \

7097N/A --bindDN "cn=Directory Manager" \

7097N/A --bindPassword password \

7097N/A --provider-name "Multimaster Synchronization" \

7097N/A --domain-name "dc=example,dc=com" \

7097N/A --set assured-type:safe-data \

7097N/A --set assured-sd-level:1 \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

7097N/A </screen>

6443N/A </step>

6443N/A </procedure>

6443N/A

6443N/A <procedure xml:id="repl-safe-read">

6443N/A <title>To Ensure Updates Are Replayed Everywhere</title>

6443N/A

6443N/A <para>Safe read mode requires the update be replayed on all directory

6443N/A servers before acknowledgement is returned to the client application.</para>

6443N/A

6443N/A <step>

6443N/A <para>For each directory server, set safe read mode for the replication

6443N/A domain.</para>

6443N/A

7097N/A <screen>

7097N/A$ <userinput>dsconfig \

7097N/A set-replication-domain-prop \

7097N/A --port 4444 \

7097N/A --hostname opendj.example.com \

7097N/A --bindDN "cn=Directory Manager" \

7097N/A --bindPassword password \

7097N/A --provider-name "Multimaster Synchronization" \

7097N/A --domain-name "dc=example,dc=com" \

7097N/A --set assured-type:safe-read \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

6443N/A

7097N/A$ <userinput>dsconfig \

7097N/A set-replication-domain-prop \

7097N/A --port 4444 \

7097N/A --hostname opendj2.example.com \

7097N/A --bindDN "cn=Directory Manager" \

7097N/A --bindPassword password \

7097N/A --provider-name "Multimaster Synchronization" \

7097N/A --domain-name "dc=example,dc=com" \

7097N/A --set assured-type:safe-read \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

7097N/A </screen>

6443N/A </step>

6443N/A </procedure>

6443N/A

6443N/A <para>When working with assured replication, the replication server property

6443N/A <literal>degraded-status-threshold</literal> (default: 5000), sets the

6443N/A number of operations allowed to build up in the replication queue before

6443N/A the server is assigned degraded status. When a replication server has

6443N/A degraded status, assured replication ceases to have an effect.</para>

6443N/A </section>

6443N/A

6443N/A <section xml:id="repl-subtree">

6443N/A <title>Subtree Replication</title>

6443N/A <indexterm>

6443N/A <primary>Replication</primary>

6443N/A <secondary>Subtree</secondary>

6443N/A </indexterm>

6443N/A

6443N/A <para>OpenDJ can perform subtree replication, for example replicating

6443N/A <literal>ou=People,dc=example,dc=com</literal>, but not the rest of

6443N/A <literal>dc=example,dc=com</literal>, by putting the subtree in a separate

6443N/A backend from the rest of the suffix.</para>

6443N/A

6443N/A <para>For example, in this case you might have a <literal>userRoot</literal>

6443N/A backend containing everything in <literal>dc=example,dc=com</literal>

6443N/A except <literal>ou=People,dc=example,dc=com</literal>, and a separate

6443N/A <literal>peopleRoot</literal> backend for

6443N/A <literal>ou=People,dc=example,dc=com</literal>. Then you replicate

6443N/A <literal>ou=People,dc=example,dc=com</literal> in its own topology.</para>

6443N/A </section>

6443N/A

6443N/A <section xml:id="repl-fractional">

6443N/A <title>Fractional Replication</title>

6443N/A <indexterm>

6443N/A <primary>Replication</primary>

6443N/A <secondary>Fractional</secondary>

6443N/A </indexterm>

6443N/A

6443N/A <para>OpenDJ can perform fractional replication, whereby you specify

6443N/A the attributes to include in or to exclude from the replication

6443N/A process.</para>

6443N/A

6443N/A <para>You set fractional replication configuration as

6443N/A <literal>fractional-include</literal> or

6443N/A <literal>fractional-exclude</literal> properties for a replication

6443N/A domain. When you include attributes, the attributes that are required on

6443N/A the relevant object classes are also included, whether you specify them

6443N/A or not. When you exclude attributes, the excluded attributes must be

6443N/A optional attributes for the relevant object classes. Fractional

6443N/A replicas still respect schema definitions.</para>

6443N/A

6443N/A <para>Fractional replication works by filtering objects at the replication

6443N/A server. Initialize replication as you would normally. Of course you cannot

6443N/A create a full replica from a replica with only a subset of the data. If you

6443N/A must prevent data from being replicated across a national boundary, split

6443N/A the replication server handling the updates from the directory servers

6443N/A receiving the updates as described in

6443N/A <xref linkend="repl-setup-dedicated-server" />.</para>

6443N/A

6443N/A <para>For example, you might configure an externally facing

6443N/A fractional replica to include only some <literal>inetOrgPerson</literal>

6443N/A attributes.</para>

6443N/A

7097N/A <screen>

7097N/A$ <userinput>dsconfig \

7097N/A set-replication-domain-prop \

7097N/A --port 4444 \

7097N/A --hostname opendj.example.com \

7097N/A --bindDN "cn=Directory Manager" \

7097N/A --bindPassword password \

7097N/A --provider-name "Multimaster Synchronization" \

7097N/A --domain-name "dc=example,dc=com" \

7097N/A --trustAll \

7097N/A --no-prompt \

7097N/A --set \

7097N/A fractional-include:inetorgperson:cn,givenname,mail,mobile,sn,telephonenumber</userinput>

7097N/A </screen>

6443N/A

6443N/A <para>As another example, you might exclude a custom attribute called

6443N/A <literal>sessionToken</literal> from being replicated.</para>

6443N/A

7097N/A <screen>

7097N/A$ <userinput>dsconfig \

7097N/A set-replication-domain-prop \

7097N/A --port 4444 \

7097N/A --hostname opendj.example.com \

7097N/A --bindDN "cn=Directory Manager" \

7097N/A --bindPassword password \

7097N/A --provider-name "Multimaster Synchronization" \

7097N/A --domain-name "dc=example,dc=com" \

7097N/A --set fractional-exclude:*:sessionToken \

7097N/A --trustAll \

7097N/A --no-prompt</userinput>

7097N/A </screen>

6443N/A

6443N/A <para>This last example only works if you first define a

6443N/A <literal>sessionToken</literal> attribute in the directory server

6443N/A schema.</para>

6443N/A </section>

7181N/A

7181N/A <section xml:id="repl-break-into-ds-and-rs">

7181N/A <title>Breaking a Multi-role Server Into Stand-alone Components</title>

7181N/A

7181N/A <para>

7181N/A As described in <xref linkend="about-repl" />,

7181N/A a replication topology is made up of

7181N/A servers playing the role of directory server,

7181N/A and servers playing the role of replication server.

7181N/A By default, each replicated OpenDJ server plays both roles.

7181N/A Some deployments call for stand-alone directory servers

7181N/A and stand-alone replication servers, however.<footnote>

7181N/A <para>

7181N/A In practice, "stand-alone" technically usually refers only to the role

7181N/A with respect to replication of user data.

7181N/A In fact stand-alone servers generally continue

7181N/A to play both roles for server configuration data

7181N/A under <literal>cn=admin data</literal> and <literal>cn=schema</literal>.

7181N/A The update traffic to these suffixes is however

7181N/A generally orders of magnitude lower than update traffic for user data.

7181N/A </para>

7181N/A </footnote>

7181N/A </para>

7181N/A

7181N/A <para>

7181N/A If possible avoid breaking apart an existing multi-role server.

7181N/A Instead, set up stand-alone servers as described in

7181N/A <xref linkend="repl-dedicated-servers" />

7181N/A and <xref linkend="repl-dedicated-replica" />.

7181N/A </para>

7181N/A

7181N/A <para>

7181N/A The following procedure breaks a multi-role server

7181N/A into two stand-alone servers

7181N/A while preserving existing data.

7181N/A It does require disk space initially to hold copies of existing data.

7181N/A </para>

7181N/A

7181N/A <procedure xml:id="repl-split-multi-role-server">

7181N/A <title>To Break a Multi-role Server Into Stand-alone Components</title>

7181N/A

7181N/A <para>

7181N/A The following steps show how to break a multi-role OpenDJ server

7181N/A into a stand-alone directory server and a stand-alone replication server.

7181N/A </para>

7181N/A

7181N/A <para>

7181N/A While you carry out this procedure, do not allow any client traffic

7181N/A to the servers you modify.

7181N/A </para>

7181N/A

7181N/A <step>

7181N/A <para>

7181N/A Make sure you have already set up

7181N/A at least a couple of OpenDJ servers that replicate user data.

7181N/A </para>

7181N/A

7181N/A <itemizedlist>

7181N/A <para>

7181N/A This example starts with the following multi-role servers.

7181N/A </para>

7181N/A

7181N/A <listitem>

7181N/A <para>

7181N/A <filename>/path/to/dsrs1</filename>

7181N/A (ports: 1389, 1636, 4444, 8989;

7181N/A replicating user data for <literal>dc=example,dc=com</literal>)

7181N/A </para>

7181N/A </listitem>

7181N/A

7181N/A <listitem>

7181N/A <para>

7181N/A <filename>/path/to/dsrs2</filename>

7181N/A (ports: 2389, 2636, 5444, 9989;

7181N/A replicating user data for <literal>dc=example,dc=com</literal>)

7181N/A </para>

7181N/A </listitem>

7181N/A </itemizedlist>

7181N/A

7181N/A <para>

7181N/A <filename>/path/to/dsrs1</filename> is the target server

7181N/A to be broken into stand-alone components.

7181N/A </para>

7181N/A

7181N/A <para>

7181N/A When you begin, the target server has

7181N/A both directory server and replication server components.

7181N/A </para>

7181N/A

7181N/A <itemizedlist>

7181N/A <para>

7181N/A Before you proceed:

7181N/A </para>

7181N/A

7181N/A <listitem>

7181N/A <para>

7181N/A Read the rest of the procedure, and make sure you understand the steps.

7181N/A </para>

7181N/A </listitem>

7181N/A

7181N/A <listitem>

7181N/A <para>

7181N/A Direct client traffic away from the target server.

7181N/A </para>

7181N/A </listitem>

7181N/A

7181N/A <listitem>

7181N/A <para>

7181N/A Back up the target server.

7181N/A </para>

7181N/A </listitem>

7181N/A </itemizedlist>

7181N/A </step>

7181N/A

7181N/A <step xml:id="repl-id-status">

7181N/A <para>

7181N/A Run the <command>dsreplication status</command> command

7181N/A before making changes.

7181N/A </para>

7181N/A

7181N/A <screen>

7181N/A$ <userinput>dsreplication \

7181N/A status \

7181N/A --port 4444 \

7181N/A --hostname opendj.example.com \

7181N/A --adminUID admin \

7181N/A --adminPassword password \

7181N/A --baseDN "cn=admin data" \

7181N/A --baseDN cn=schema \

7181N/A --baseDN dc=example,dc=com \

7181N/A --trustAll \

7181N/A --no-prompt</userinput>

7181N/A<computeroutput>

7181N/ASuffix DN :...: DS ID : RS ID :...

7181N/A------------------:...:-------:-------:...

7181N/Acn=admin data :...: 29388 : 32560 :...

7181N/Acn=admin data :...: 7044 : 29137 :...

7181N/Acn=schema :...: 24612 : 32560 :...

7181N/Acn=schema :...: 22295 : 29137 :...

7181N/Adc=example,dc=com :...: 20360 : 32560 :...

7181N/Adc=example,dc=com :...: 12164 : 29137 :...

7181N/A...</computeroutput>

7181N/A </screen>

7181N/A

7181N/A <para>

7181N/A Keep the output of the command for the IDs shown.

7181N/A The information is used later in this procedure.

7181N/A </para>

7181N/A </step>

7181N/A

7181N/A <step>

7181N/A <para>

7181N/A Temporarily disable the multimaster synchronization provider

7181N/A on the target server.

7181N/A </para>

7181N/A

7181N/A <screen>

7181N/A$ <userinput>dsconfig \

7181N/A set-synchronization-provider-prop \

7181N/A --port 4444 \

7181N/A --hostname opendj.example.com \

7181N/A --bindDN "cn=Directory Manager" \

7181N/A --bindPassword password \

7181N/A --provider-name "Multimaster Synchronization" \

7181N/A --set enabled:false \

7181N/A --trustAll \

7181N/A --no-prompt</userinput>

7181N/A </screen>

7181N/A

7181N/A <para>

7181N/A This step is also shown in <xref linkend="stop-repl-tmp" />.

7181N/A </para>

7181N/A </step>

7181N/A

7181N/A <step>

7181N/A <para>

7181N/A Temporarily disable the backend holding the replicated data.

7181N/A </para>

7181N/A

7181N/A <screen>

7181N/A$ <userinput>dsconfig \

7181N/A set-backend-prop \

7181N/A --port 4444 \

7181N/A --hostname opendj.example.com \

7181N/A --bindDN "cn=Directory Manager" \

7181N/A --bindPassword password \

7181N/A --backend-name userRoot \

7181N/A --set enabled:false \

7181N/A --trustAll \

7181N/A --no-prompt</userinput>

7181N/A </screen>

7181N/A </step>

7181N/A

7181N/A <step>

7181N/A <para>

7181N/A Stop the target server.

7181N/A </para>

7181N/A

7181N/A <screen>

7181N/A$ <userinput>stop-ds</userinput>

7181N/A<computeroutput>Stopping Server...

7181N/A... msg=The Directory Server is now stopped</computeroutput>

7181N/A </screen>

7181N/A </step>

7181N/A

7181N/A <step>

7181N/A <para>

7181N/A Make two copies of the server files.

7181N/A </para>