From 1f24b40e26e6087132d2001e8ce2ebdb832c0f03 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Fri, 10 Jun 2011 16:05:06 +0000
Subject: [PATCH] Draft repl chapter. This version is still missing the part concerning the change log, but the rest might be useful.
---
opendj3/src/main/docbkx/admin-guide/images/replB-data-repl.png | 0
opendj3/src/main/docbkx/admin-guide/images/replB-setup.png | 0
opendj3/src/main/docbkx/admin-guide/images/replB-global-admin.png | 0
opendj3/src/main/docbkx/admin-guide/chap-replication.xml | 704 +++++++++++++++++++++++++++++++++++++++++
opendj3/src/main/docbkx/admin-guide/images/replA-setup.png | 0
opendj3/src/main/docbkx/shared/man-dsreplication.xml | 301 ++++++++++++++++-
opendj3/src/main/docbkx/admin-guide/images/replA-monitor-repl.png | 0
7 files changed, 973 insertions(+), 32 deletions(-)
diff --git a/opendj3/src/main/docbkx/admin-guide/chap-replication.xml b/opendj3/src/main/docbkx/admin-guide/chap-replication.xml
index 9241fe2..cd01e53 100644
--- a/opendj3/src/main/docbkx/admin-guide/chap-replication.xml
+++ b/opendj3/src/main/docbkx/admin-guide/chap-replication.xml
@@ -37,11 +37,705 @@
upgrade your directory service. You can configure data replication as part
of OpenDJ installation, and in many cases let replication do its work in
the background.</para>
-
- <para>For some deployments you may choose not to accept the default
- replication configuration. This chapter shows how to configure replication
- with command-line tools, and covers other topics related to replicated
- directory environments.</para>
+ <section>
+ <title>Replication Quick Setup</title>
+
+ <para>The easiest way to set up replication for the first time involves
+ using the setup wizard.</para>
+
+ <para>In the Topology Options screen for the first server you set up, select
+ This server will be part of a replication topology. If you also choose
+ Configure as Secure, then replication traffic is protected by SSL.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/replA-setup.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+
+ <para>In the Topology Options screen for subsequent servers, also select
+ There is already a server in the topology, providing the Host Name,
+ Administration Connector Port number, Admin User, and Admin Password for
+ the first replica you set up.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/replB-setup.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+
+ <para>You also set up a global administrator account, stored under
+ <literal>cn=admin data</literal> across replicas, used to manage replication
+ in the topology.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/replB-global-admin.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+
+ <para>You further set up what to replicate.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/replB-data-repl.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Once replication is set up, it works for all the replicas. You can
+ monitor the replication connection and status through the OpenDJ Control
+ Panel.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/replA-monitor-repl.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+
+ </section>
+
+ <section>
+ <title>About Replication</title>
+
+ <para>Before you take replication further than setting up replication
+ in the setup wizard, read this section to learn more about how OpenDJ
+ replication works.</para>
+
+ <para>Replication is the process of copying updates between OpenDJ
+ directory servers such that all servers converge on identical copies of
+ directory data. Replication is designed to let convergence happen over
+ time by default. <footnote><para>Assured replication can require, however,
+ that the convergence happen before the client application is notified that
+ the operation was successful.</para></footnote> Letting convergence
+ happen over time means that different replicas can be momentarily out of
+ sync, but it also means that if you lose an individual server or even an
+ entire data center, your directory service can keep on running, and then
+ get back in sync when the servers are restarted or the network is
+ repaired.</para>
+
+ <para>Replication is specific to the OpenDJ directory service. Replication
+ uses a specific protocol that replays update operations quickly, storing
+ enough historical information about the updates to resolve most conflicts
+ automatically. For example, if two client applications separately update
+ a user entry to change the phone number, replication can work out which
+ was the latest change, and apply that change across servers. The historical
+ information needed to resolve these issues is periodically purged to avoid
+ growing larger and larger forever. As a directory administrator, you make
+ sure that you do not purge the historical information more often than you
+ backup your directory data.</para>
+
+ <para>The primary unit of replication is the suffix, specified by a
+ base DN such as <literal>dc=example,dc=com</literal>. <footnote><para>When
+ you configure partial and fractional replication, however, you can replicate
+ only part of a suffix, or only certain attributes on entries. Also,
+ if you split your suffix across multiple backends, then you need to set up
+ replication separately for each part of suffix in a different backend.</para>
+ </footnote> Replication also depends on the directory schema, defined on
+ <literal>cn=schema</literal>, and the <literal>cn=admin data</literal>
+ suffix with administrative identities and certificates for protecting
+ communications. Thus that content gets replicated as well.</para>
+
+ <para>The set of replicas sharing data in a given suffix is called
+ a replication topology. You can have more than one replication topology.
+ For example, one topology could be devoted to
+ <literal>dc=example,dc=com</literal>, and another to
+ <literal>dc=example,dc=org</literal>. Directory servers are capable of
+ serving more than one suffix. They are also capable of participating in
+ more than one replication topology.</para>
+ </section>
+
+ <section>
+ <title>Configuring Replication</title>
+
+ <para>For some deployments you choose not to configure replication using the
+ setup wizard. This section shows how to configure replication with
+ command-line tools.</para>
+
+ <section>
+ <title>Enabling Replication</title>
+
+ <para>You can start the replication process by using the
+ <command>dsreplication enable</command> command.</para>
+
+ <screen width="80">$ dsreplication enable -I admin -w password -X -n -b dc=example,dc=com \
+> --host1 `hostname` --port1 4444 --bindDN1 "cn=Directory Manager" \
+> --bindPassword1 password --replicationPort1 8989 \
+> --host2 `hostname` --port2 5444 --bindDN2 "cn=Directory Manager" \
+> --bindPassword2 password --replicationPort2 9989
+
+Establishing connections ..... Done.
+Checking registration information ..... Done.
+Updating remote references on server localhost:4444 ..... Done.
+Configuring Replication port on server localhost:5444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ localhost:4444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ localhost:5444 ..... Done.
+Updating registration configuration on server localhost:4444 ..... Done.
+Updating registration configuration on server localhost:5444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ localhost:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ localhost:5444 ..... Done.
+Initializing registration information on server localhost:5444 with the
+ contents of server localhost:4444 ..... Done.
+Initializing schema on server localhost:5444 with the contents of server
+ localhost:4444 ..... Done.
+
+Replication has been successfully enabled. Note that for replication to
+ work you must initialize the contents of the base DN's that are being
+ replicated (use dsreplication initialize to do so).
+
+See
+/var/.../opends-replication-7958637258600693490.log
+for a detailed log of this operation.</screen>
+
+ <para>As you see in the command output, replication is set up to function
+ once enabled. You must however initialize replication in order to start
+ the process, however.</para>
+
+ <para>If you need to add another OpenDJ directory server to participate
+ in replication, use the <command>dsreplication enable</command> with
+ the new server as the second server.</para>
+ </section>
+
+ <section>
+ <title>Initializing Replicas</title>
+
+ <para>Although you can enable replication before you have user data, you
+ must initialize replication after you enable it for the first time.</para>
+
+ <para>You can perform initialization either over the replication protocol,
+ by importing the same LDIF data on all server before performing
+ initialization when starting out, by importing data from LDIF that you
+ exported from another replica when adding a server to the topology, or by
+ restoring a backup from an existing replica onto a new server.</para>
+
+ <procedure>
+ <title>To Initialize Online</title>
+
+ <step>
+ <para>Make sure you have enabled servers you want to participate in
+ replication.</para>
+ </step>
+ <step>
+ <para>Start replication with the <command>dsreplication
+ initialize-all</command> command.</para>
+
+ <screen width="80">$ dsreplication initialize-all -I admin -w password -X -n -b dc=example,dc=com \
+> -h `hostname` -p 4444
+
+Initializing base DN dc=example,dc=com with the contents from localhost:4444:
+160 entries processed (100 % complete).
+Base DN initialized successfully.
+
+See
+/var/.../opends-replication-5020375834904394170.log
+for a detailed log of this operation.</screen>
+ </step>
+ </procedure>
+
+ <procedure>
+ <title>To Initialize All Servers From the Same LDIF</title>
+
+ <para>Follow these steps to prepare a replication topology starting from
+ directory data in LDIF.</para>
+
+ <step>
+ <para>Import the same LDIF on all servers you want to participate in
+ replication.</para>
+ </step>
+ <step>
+ <para>Make sure you have enabled servers you want to participate in
+ replication.</para>
+ </step>
+ <step>
+ <para>Start replication with the <command>dsreplication
+ initialize-all</command> command.</para>
+ <screen width="80">$ dsreplication initialize-all -I admin -w password -X -n -b dc=example,dc=com \
+> ;-h `hostname` -p 4444
+Initializing base DN dc=example,dc=com with the contents from localhost:4444:
+161 entries processed (100 % complete).
+Base DN initialized successfully.
+
+See
+/var/.../opends-replication-5745536041520679254.log
+for a detailed log of this operation.</screen>
+ </step>
+ </procedure>
+
+ <procedure>
+ <title>To Create a New Replica From Existing Backup</title>
+
+ <para>Follow these steps to add another server to the topology by
+ copying the database</para>
+
+ <step>
+ <para>Backup the database to replica on an existing server.</para>
+ </step>
+ <step>
+ <para>Install a new server.</para>
+ </step>
+ <step>
+ <para>Restore the new server database from the backup archive.</para>
+ </step>
+ <step>
+ <para>Enable replication on the new server.</para>
+ <screen width="80">
+$ dsreplication enable -I admin -w password -X -n -b dc=example,dc=com \
+> --host1 `hostname` --port1 4444 --bindDN1 "cn=Directory Manager" \
+> --bindPassword1 password --replicationPort1 8989 \
+> --host2 `hostname` --port2 6444 --bindDN2 "cn=Directory Manager" \
+> --bindPassword2 password --replicationPort2 10989
+
+Establishing connections ..... Done.
+Checking registration information ..... Done.
+Updating remote references on server localhost:4444 ..... Done.
+Configuring Replication port on server localhost:6444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ localhost:4444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ localhost:6444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ localhost:5444 ..... Done.
+Updating remote references on server localhost:5444 ..... Done.
+Updating registration configuration on server localhost:4444 ..... Done.
+Updating registration configuration on server localhost:6444 ..... Done.
+Updating registration configuration on server localhost:5444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ localhost:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ localhost:6444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ localhost:5444 ..... Done.
+Initializing registration information on server localhost:6444 with the
+ contents of server localhost:4444 ..... Done.
+
+Replication has been successfully enabled. Note that for replication to
+ work you must initialize the contents of the base DN's that are being
+ replicated (use dsreplication initialize to do so).
+
+See
+/var/.../opends-replication-1672058070147419978.log
+for a detailed log of this operation.</screen>
+ </step>
+ <step>
+ <para>Initialize replication on the new server with the
+ <command>dsreplication initialize</command> command.</para>
+ <screen width="80">$ dsreplication initialize -I admin -w password -X -n -b dc=example,dc=com \
+> -h `hostname` -p 6444
+Initializing base DN dc=example,dc=com with the contents from localhost:6444:
+161 entries processed (100 % complete).
+Base DN initialized successfully.
+
+See
+/var/.../opends-replication-4529243617755617341.log
+for a detailed log of this operation.</screen>
+ </step>
+ </procedure>
+ </section>
+
+ <section>
+ <title>Stopping Replication</title>
+
+ <para>How you stop replication depends on whether the change is meant to
+ be temporary, or meant to be permanent.</para>
+
+ <procedure>
+ <title>To Stop Replication Temporarily For a Replica</title>
+
+ <para>If you need to stop a server from replicating temporarily, you can
+ do so using <command>dsconfig</command> command. Do not update directory
+ data on the server while replication is interrupted.</para>
+
+ <step>
+ <para>Get the replication server property that identifies one of the
+ replication service host:port combinations that you need to restart
+ replication.</para>
+ <screen width="80">$ dsconfig -p 5444 -h `hostname` -D "cn=Directory Manager" -w password \
+> get-replication-server-prop --provider-name "Multimaster Synchronization" \
+> --property replication-server -X
+Property : Value(s)
+-------------------:-----------------------------------------------------------
+replication-server : localhost:8989,
+ : localhost:9989</screen>
+ </step>
+ <step>
+ <para>Reset the replication server property to the default (no
+ replication server) to pause replication.</para>
+ <screen width="80">$ dsconfig -p 5444 -h `hostname` -D "cn=Directory Manager" -w password \
+> set-replication-server-prop --provider-name "Multimaster Synchronization" \
+> --reset replication-server -X -n</screen>
+ <para>Do not modify the replica for which replication is paused.</para>
+ </step>
+ <step performance="optional">
+ <para>When you are ready to resume replication, set the replication server
+ property to the host:port combination of an active replication server.</para>
+ <screen width="80">$ dsconfig -p 5444 -h `hostname` -D "cn=Directory Manager" -w password \
+> set-replication-server-prop --provider-name "Multimaster Synchronization" \
+> --set replication-server:localhost:8989 -X -n</screen>
+ </step>
+ </procedure>
+
+ <procedure>
+ <title>To Stop Replication Permanently For a Replica</title>
+
+ <para>If you need to stop a server from replicating permanently, for
+ example in preparation to remove a server, you can do so with the
+ <command>dsreplication disable</command> command.</para>
+
+ <step>
+ <para>Stop replication using the <command>dsreplication disable</command>
+ command.</para>
+ <screen width="80">$ dsreplication disable -a -p 5444 -h `hostname` -D "cn=Directory Manager" \
+> -w password -X -n
+Establishing connections ..... Done.
+Disabling replication on base DN cn=admin data of server localhost:5444
+ ..... Done.
+Disabling replication on base DN dc=example,dc=com of server localhost:5444
+ ..... Done.
+Disabling replication on base DN cn=schema of server localhost:5444 ..... Done.
+Disabling replication port 9989 of server localhost:5444 ..... Done.
+Removing registration information ..... Done.
+Removing truststore information ..... Done.
+
+See
+/var/.../opends-replication-125248191132797765.log
+for a detailed log of this operation.</screen>
+ <para>The <command>dsreplication disable</command> as shown removes the
+ replication configuration information.</para>
+ </step>
+ <step performance="optional">
+ <para>If you want to restart replication for the server, you use the
+ <command>dsreplication enable</command> and <command>dsreplication
+ initialize</command> commands again.</para>
+ </step>
+ </procedure>
+ </section>
+
+ <section>
+ <title>Stand-alone Replication Servers</title>
+
+ <para>Replication in OpenDJ is designed to be both easy to implement in
+ environments with a few servers, and also scalable in environments with
+ many servers. You can enable the replication service on each OpenDJ
+ directory server in your deployment, for example, to limit the number
+ of servers you deploy. Yet in a large deployment, you can use stand-alone
+ replication servers — OpenDJ servers that do nothing but relay
+ replication messages — to configure (and troubleshoot) the replication
+ service separately from the directory service. You only need a few
+ stand-alone replication servers publishing changes to serve many directory
+ servers subscribed to the changes. Furthermore, replication is designed
+ such that you need only connect a directory server to the nearest
+ replication server for the directory server to replicate with all others
+ in your topology. Yet only the stand-alone replication servers participate
+ in fully-meshed replication.</para>
+
+
+ <procedure>
+ <title>To Set Up a Stand-alone Replication Server</title>
+
+ <para>This example sets up a stand-alone replication server to handle
+ the replication traffic between two directory servers that do not
+ handle replication themselves.</para>
+
+ <para>Here the replication server has admin port 6444. The directory
+ servers have admin ports 4444 and 5444.</para>
+
+ <para>In a real deployment, you would have more replication servers
+ to avoid a single point of failure.</para>
+
+ <step>
+ <para>Setup the replication server as a directory server that has
+ no database.</para>
+ </step>
+ <step>
+ <para>Setup the directory servers as stand-alone directory servers.</para>
+ </step>
+ <step>
+ <para>Enable replication with the appropriate
+ <option>--noReplicationServer</option> and
+ <option>--onlyReplicationServer</option> options.</para>
+ <screen width="80">$ dsreplication enable -I admin -w password -X -n -b dc=example,dc=com \
+> --host1 `hostname` --port1 4444 --bindDN1 "cn=Directory Manager" \
+> --bindPassword1 password --noReplicationServer1 \
+> --host2 `hostname` --port2 6444 --bindDN2 "cn=Directory Manager" \
+> --bindPassword2 password --replicationPort2 8989 --onlyReplicationServer2
+Establishing connections ..... Done.
+Only one replication server will be defined for the following base DN's:
+dc=example,dc=com
+It is recommended to have at least two replication servers (two changelogs) to
+avoid a single point of failure in the replication topology.
+
+Checking registration information ..... Done.
+Configuring Replication port on server localhost:6444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ localhost:4444 ..... Done.
+Updating registration configuration on server localhost:4444 ..... Done.
+Updating registration configuration on server localhost:6444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ localhost:4444 ..... Done.
+Initializing registration information on server localhost:6444 with the
+ contents of server localhost:4444 ..... Done.
+
+Replication has been successfully enabled. Note that for replication to work
+ you must initialize the contents of the base DN's that are being
+ replicated (use dsreplication initialize to do so).
+
+See
+/var/.../opends-replication-1720959352638609971.log
+for a detailed log of this operation.
+
+$ dsreplication enable -I admin -w password -X -n -b dc=example,dc=com \
+> --host1 `hostname` --port1 5444 --bindDN1 "cn=Directory Manager" \
+> --bindPassword1 password --noReplicationServer1 \
+> --host2 `hostname` --port2 6444 --bindDN2 "cn=Directory Manager" \
+> --bindPassword2 password --replicationPort2 8989 --onlyReplicationServer2
+
+Establishing connections ..... Done.
+Only one replication server will be defined for the following base DN's:
+dc=example,dc=com
+It is recommended to have at least two replication servers (two changelogs) to
+avoid a single point of failure in the replication topology.
+
+Checking registration information ..... Done.
+Updating remote references on server localhost:6444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ localhost:5444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ localhost:4444 ..... Done.
+Updating registration configuration on server localhost:5444 ..... Done.
+Updating registration configuration on server localhost:6444 ..... Done.
+Updating registration configuration on server localhost:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ localhost:5444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ localhost:4444 ..... Done.
+Initializing registration information on server localhost:5444 with the
+ contents of server localhost:6444 ..... Done.
+
+Replication has been successfully enabled. Note that for replication to work
+ you must initialize the contents of the base DN's that are being
+ replicated (use dsreplication initialize to do so).
+
+See
+/var/folders/.../opends-replication-5893037538856033562.log
+for a detailed log of this operation.</screen>
+ </step>
+ <step>
+ <para>Initialize replication from one of the directory servers.</para>
+ <screen width="80">$ dsreplication initialize-all -I admin -w password -X -n -b dc=example,dc=com \
+> -h `hostname` -p 4444
+
+Initializing base DN dc=example,dc=com with the contents from localhost:4444:
+160 entries processed (100 % complete).
+Base DN initialized successfully.
+
+See
+/var/.../opends-replication-7677303986403997574.log
+for a detailed log of this operation.</screen>
+ </step>
+ </procedure>
+ </section>
+
+ <section>
+ <title>Replication Groups</title>
+
+ <para>Replication lets you define groups so that replicas communicate
+ first with replication servers in the group before going to replication
+ servers outside the group. Groups are identified with unique numeric
+ group IDs.</para>
+
+ <procedure>
+ <title>To Set Up Replication Groups</title>
+
+ <para>For each group, set the appropriate group ID for the topology
+ on both the replication servers and the directory servers.</para>
+
+ <para>The example commands in this procedure set up two replication
+ groups, each with a replication server and a directory server. The
+ directory servers have admin ports 4444 and 5444. The replication servers
+ have admin ports 6444 and 7444. In a full-scale deployment, you would
+ have multiple servers of each type in each group, such as all the replicas
+ and replication servers in each data center being in the same group.</para>
+
+ <step>
+ <para>Pick a group ID for each group.</para>
+ <para>The default group ID is 1.</para>
+ </step>
+ <step>
+ <para>Set the group ID for each group by replication domain on the
+ directory servers.</para>
+ <screen width="80">$ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
+> set-replication-domain-prop --provider-name "MultimasterSynchronization" \
+> --domain-name "dc=example,dc=com" --set group-id:1 -X -n
+
+$ dsconfig -p 5444 -h `hostname` -D "cn=Directory Manager" -w password \
+> set-replication-domain-prop --provider-name "Multimaster Synchronization" \
+> --domain-name "dc=example,dc=com" --set group-id:2 -X -n</screen>
+ </step>
+ <step>
+ <para>Set the group ID for each group on the replication servers.</para>
+ <screen width="80">$ dsconfig -p 6444 -h `hostname` -D "cn=Directory Manager" -w password \
+> set-replication-server-prop --provider-name "Multimaster Synchronization" \
+> --set group-id:1 -X -n
+$ dsconfig -p 7444 -h `hostname` -D "cn=Directory Manager" -w password \
+> set-replication-server-prop --provider-name "Multimaster Synchronization" \
+> --set group-id:2 -X -n</screen>
+ </step>
+ </procedure>
+ </section>
+
+ <section>
+ <title>Read-Only Replicas</title>
+
+ <para>By default all directory servers in a replication topology are
+ read-write. You can however choose to make replicas take updates only
+ from the replication protocol, and refuse updates from client
+ applications.</para>
+
+ <screen width="80">$ dsconfig -p 5444 -h `hostname` -D "cn=Directory Manager" -w password \
+> set-global-configuration-prop --set writability-mode:internal-only -X -n</screen>
+ </section>
+
+ <section>
+ <title>Assured Replication</title>
+
+ <para>In standard replication, when a client requests an update operation
+ the directory server performs the update and, if the update is successful,
+ sends information about the update to the replication service, and sends
+ a result code to the client application right away. As a result, the
+ client application can conclude that the update was successful,
+ <emphasis>but only on the replica that handled the update</emphasis>.</para>
+
+ <para>Assured replication lets you force the replica performing the initial
+ update to wait for confirmation that the update has been received elsewhere
+ in the topology before sending a result code to the client application.
+ You can configure assured replication either to wait for one or more
+ replication servers to acknowledge having received the update, or to wait
+ for all directory servers to have replayed the update.</para>
+
+ <para>As you might imagine, assured replication is theoretically safer than
+ standard replication, yet it is also slower, potentially waiting for a
+ timeout before failing when the network or other servers are down.</para>
+
+ <procedure>
+ <title>To Ensure Updates Reach Replication Servers</title>
+
+ <para>Safe data mode requires the update be sent to
+ <literal>assured-sd-level</literal> replication servers before
+ acknowledgement is returned to the client application.</para>
+
+ <step>
+ <para>For each directory server, set safe data mode for the replication
+ domain, and also set the safe data level.</para>
+
+ <screen width="80">$ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
+> set-replication-domain-prop --provider-name "Multimaster Synchronization" \
+> --domain-name "dc=example,dc=com" \
+> --set assured-type:safe-data --set assured-sd-level:1 -X -n
+
+$ dsconfig -p 5444 -h `hostname` -D "cn=Directory Manager" -w password \
+> set-replication-domain-prop --provider-name "Multimaster Synchronization" \
+> --domain-name "dc=example,dc=com" \
+> --set assured-type:safe-data --set assured-sd-level:1 -X -n</screen>
+ </step>
+ </procedure>
+
+ <procedure>
+ <title>To Ensure Updates Are Replayed Everywhere</title>
+
+ <para>Safe read mode requires the update be replayed on all directory
+ servers before acknowledgement is returned to the client application.</para>
+
+ <step>
+ <para>For each directory server, set safe read mode for the replication
+ domain.</para>
+
+ <screen width="80">$ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
+> set-replication-domain-prop --provider-name "Multimaster Synchronization" \
+> --domain-name "dc=example,dc=com" --set assured-type:safe-read -X -n
+
+$ dsconfig -p 5444 -h `hostname` -D "cn=Directory Manager" -w password \
+> set-replication-domain-prop --provider-name "Multimaster Synchronization" \
+> --domain-name "dc=example,dc=com" --set assured-type:safe-read -X -n</screen>
+ </step>
+ </procedure>
+
+ <para>When working with assured replication, the replication server property
+ <literal>degraded-status-threshold</literal> (default: 5000), sets the
+ number of operations allowed to build up in the replication queue before
+ the server is assigned degraded status. When a replication server has
+ degraded status, assured replication ceases to have an effect.</para>
+ </section>
+
+ <section>
+ <title>Subtree Replication</title>
+
+ <para>OpenDJ lets you do subtree replication, for example replicating
+ <literal>ou=People,dc=example,dc=com</literal>, but not the rest of
+ <literal>dc=example,dc=com</literal>, by putting the subtree in a separate
+ backend from the rest of the suffix.</para>
+
+ <para>For example, in this case you might have a <literal>userRoot</literal>
+ backend containing everything in <literal>dc=example,dc=com</literal>
+ except <literal>ou=People,dc=example,dc=com</literal>, and a separate
+ <literal>peopleRoot</literal> backend for
+ <literal>ou=People,dc=example,dc=com</literal>. Then you replicate
+ <literal>ou=People,dc=example,dc=com</literal> in its own topology.</para>
+ </section>
+
+ <section>
+ <title>Fractional Replication</title>
+
+ <para>OpenDJ lets you do fractional replication, whereby you specify
+ the attributes to include in the replication process, or alternatively
+ specify the attributes to exclude.</para>
+
+ <para>You set fractional replication configuration as
+ <literal>fractional-include</literal> or
+ <literal>fractional-exclude</literal> properties for a replication
+ domain. When you include attributes, the attributes that must be kept on
+ the relevant object classes are also included, whether you specify them
+ or not. When you exclude attributes, the excluded attributes must be
+ optional attributes for the relevant object classes. Fractional
+ replica still respect schema definitions.</para>
+
+ <para>For example, you might configure an externally facing
+ fractional replica to include only some <literal>inetOrgPerson</literal>
+ attributes.</para>
+
+ <screen width="80">$ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
+> set-replication-domain-prop --provider-name "Multimaster Synchronization" \
+--domain-name "dc=example,dc=com" -X -n --set \
+fractional-include:inetorgperson:cn,givenname,mail,mobile,sn,telephonenumber</screen>
+
+ <para>As another example, you might exclude a custom attribute called
+ <literal>sessionToken</literal> from being replicated.</para>
+
+ <screen width="80">dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
+> set-replication-domain-prop --provider-name "Multimaster Synchronization" \
+--domain-name "dc=example,dc=com" --set fractional-exclude:*:sessionToken -X -n</screen>
+
+ <para>This last example only works if you first define a sessionToken
+ attribute in the directory server schema.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Change Notification For Your Applications</title>
+
+ <para>Some of your applications might require notification when directory
+ data updates occur. For example, the application might need to sync directory
+ data with another database, or the application might need to kick off other
+ processing when certain updates occur.</para>
+
+ <para>In addition to supporting peristent search operations, OpenDJ
+ provides a change log mechanism to allow applications to be notified of
+ changes to directory data.</para>
+
+ <para>TODO</para>
+ </section>
</chapter>
diff --git a/opendj3/src/main/docbkx/admin-guide/images/replA-monitor-repl.png b/opendj3/src/main/docbkx/admin-guide/images/replA-monitor-repl.png
new file mode 100644
index 0000000..6339e74
--- /dev/null
+++ b/opendj3/src/main/docbkx/admin-guide/images/replA-monitor-repl.png
Binary files differ
diff --git a/opendj3/src/main/docbkx/admin-guide/images/replA-setup.png b/opendj3/src/main/docbkx/admin-guide/images/replA-setup.png
new file mode 100644
index 0000000..0b4ef31
--- /dev/null
+++ b/opendj3/src/main/docbkx/admin-guide/images/replA-setup.png
Binary files differ
diff --git a/opendj3/src/main/docbkx/admin-guide/images/replB-data-repl.png b/opendj3/src/main/docbkx/admin-guide/images/replB-data-repl.png
new file mode 100644
index 0000000..238c432
--- /dev/null
+++ b/opendj3/src/main/docbkx/admin-guide/images/replB-data-repl.png
Binary files differ
diff --git a/opendj3/src/main/docbkx/admin-guide/images/replB-global-admin.png b/opendj3/src/main/docbkx/admin-guide/images/replB-global-admin.png
new file mode 100644
index 0000000..7f9cdc4
--- /dev/null
+++ b/opendj3/src/main/docbkx/admin-guide/images/replB-global-admin.png
Binary files differ
diff --git a/opendj3/src/main/docbkx/admin-guide/images/replB-setup.png b/opendj3/src/main/docbkx/admin-guide/images/replB-setup.png
new file mode 100644
index 0000000..e3a52d3
--- /dev/null
+++ b/opendj3/src/main/docbkx/admin-guide/images/replB-setup.png
Binary files differ
diff --git a/opendj3/src/main/docbkx/shared/man-dsreplication.xml b/opendj3/src/main/docbkx/shared/man-dsreplication.xml
index 7a3fb06..f55ff8b 100644
--- a/opendj3/src/main/docbkx/shared/man-dsreplication.xml
+++ b/opendj3/src/main/docbkx/shared/man-dsreplication.xml
@@ -35,66 +35,313 @@
</refmeta>
<refnamediv>
<refname>dsreplication</refname>
- <refpurpose>TODO one-line description</refpurpose>
+ <refpurpose>manage OpenDJ directory data replication</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>dsreplication</command>
<command><replaceable>subcommand</replaceable></command>
- <arg choice="opt">--options</arg>
+ <arg>options</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
- <para>TODO description.</para>
+ <para>This utility can be used to configure replication between servers so
+ that the data of the servers is synchronized. For replication to work you
+ must first enable replication using the <command>enable</command> subcommand
+ and then initialize the contents of one of the servers with the contents of
+ the other using the <command>initialize</command> subcommand.</para>
</refsect1>
<refsect1>
- <title>Global Options</title>
- <para>The following global options are supported.</para>
+ <title>Subcommands</title>
+ <para>The following subcommands are supported.</para>
<variablelist>
<varlistentry>
- <term><option>TODO</option></term>
+ <term><command>disable</command></term>
<listitem>
- <para>TODO Description.</para>
+ <para>Disable replication on the specified server for the provided base
+ DN and removes references in the other servers with which it is
+ replicating data.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>enable</command></term>
+ <listitem>
+ <para>Update the configuration of the servers to replicate the data
+ under the specified base DN. If one of the specified servers is already
+ replicating the data under the base DN with other servers, executing this
+ subcommand will update the configuration of all the servers. Thus it is
+ sufficient to execute the command line once for each server added to the
+ replication topology.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>initialize</command></term>
+ <listitem>
+ <para>Initialize the contents of the data under the specified base DN
+ on the destination server with the contents on the source server. This
+ operation is required after enabling replication in order replication to
+ work. <command>initialize-all</command> can also be used for this
+ purpose.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>initialize-all</command></term>
+ <listitem>
+ <para>Initialize the contents of the data under the specified base DN
+ on all the servers whose contents are being replicated with the contents
+ on the specified server. This operation is required after enabling
+ replication for replication to work. Run <command>initialize</command>
+ for each server to achieve the same effect.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>post-external-initialization</command></term>
+ <listitem>
+ <para>This subcommand must be called after initializing the contents of
+ all the replicated servers using the <command>import-ldif</command>
+ command, or by copying the database. You must specify the list of base DNs
+ that have been initialized, and you must provide the credentials of any
+ of the servers that are being replicated. See
+ <command>pre-external-initialization --help</command> for more
+ information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>pre-external-initialization</command></term>
+ <listitem>
+ <para>This subcommand must be called before initializing the contents
+ of all the replicated servers using the <command>import-ldif</command>
+ command, or by copying the database. You must specify the list of base DNs
+ that have been initialized, and you must provide the credentials of any
+ of the servers that are being replicated. After calling this subcommand,
+ initialize the contents of all the servers in the topology, either by
+ using the same LDIF file or by copying the database to each of the
+ servers, then call the <command>post-external-initialization</command>
+ subcommand.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>purge-historical</command></term>
+ <listitem>
+ <para>Launch a purge processing of the historical information stored
+ in the user entries by replication. Since this processing may take a
+ while, you must specify a maximum duration.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>status</command></term>
+ <listitem>
+ <para>Display a list with the basic replication configuration of the
+ base DNs of the servers defined in the registration information. If
+ no base DNs are specified as parameter, information for all base DNs
+ is displayed.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
- <title>Subcommands</title>
- <para>The following subcommands are supported.</para>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--advanced</option></term>
+ <listitem>
+ <para>Access advanced settings when running this command in interactive
+ mode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-b, --baseDN {baseDN}</option></term>
+ <listitem>
+ <para>Base DN of the data to be replicated, initialized or for which you
+ want to disable replication. Multiple base DNs can be provided by using
+ this option multiple times.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<refsect2>
- <para>TODO Description.</para>
- <cmdsynopsis>
- <command>dsreplication</command>
- <command>TODO</command>
- <arg choice="opt">--options</arg>
- </cmdsynopsis>
+ <title>LDAP Connection Options</title>
<variablelist>
<varlistentry>
- <term><option>TODO</option></term>
+ <term><option>--connectTimeout {timeout}</option></term>
<listitem>
- <para>TODO description.</para>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-I, --adminUID {adminUID}</option></term>
+ <listitem>
+ <para>User ID of the global administrator to use to bind to the server.
+ For the <command>enable</command> subcommand, if no global administrator
+ was defined previously for any servers, the global administrator will be
+ created using the UID provided.</para>
+ <para>Default value: admin</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --adminPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Global administrator password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server administration port number</para>
+ <para>Default value: 4444</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ <para>Default value: /path/to/OpenDJ/config/admin-truststore</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --adminPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password for the global administrator</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--commandFilePath {path}</option></term>
+ <listitem>
+ <para>The full path to the file where the equivalent non-interactive
+ commands will be written when this command is run in interactive
+ mode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--displayCommand</option></term>
+ <listitem>
+ <para>Display the equivalent non-interactive option on standard output
+ when this command is run in interactive mode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --no-prompt</option></term>
+ <listitem>
+ <para>Use non-interactive mode. If data in the command is missing, the
+ user is not prompted and the command exits with an error.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Q, --quiet</option></term>
+ <listitem>
+ <para>Do not write progress information to standard output</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
- <title>Files</title>
- <para>TODO if command has configuration file.</para>
- </refsect1>
- <refsect1>
- <title>Environment</title>
- <para>TODO if command reads environment variables.</para>
- </refsect1>
- <refsect1>
<title>Exit Codes</title>
<variablelist>
<varlistentry>
- <term>TODO exit code</term>
+ <term>0</term>
<listitem>
- <para>TODO description.</para>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
</listitem>
</varlistentry>
</variablelist>
--
Gitblit v1.10.0