Taking into account doc review comments from Danny Turner. Several things s...

Mark Craig

19.16.2011 c20ae9106367a265b7aa27fd9bda650d55bd6d66

Taking into account doc review comments from Danny Turner.
Several things still to do in a later update.

 opendj3/src/main/docbkx/admin-guide/chap-replication.xml

@@ -49,8 +49,8 @@
   <see>Replication</see>
  </indexterm>
  
  <para>The easiest way to set up replication for the first time involves
  using the setup wizard.</para>
  <para>You can set up replication during installation by choosing to
  configure replication through 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
@@ -133,8 +133,8 @@
  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
  growing larger and larger forever. As a directory administrator, you must
  ensure that you do not purge the historical information more often than you
  backup your directory data.</para>
  
  <para>The primary unit of replication is the suffix, specified by a
@@ -164,9 +164,8 @@
   <secondary>Configuring</secondary>
  </indexterm>
  
  <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>
  <para>This section shows how to configure replication with command-line
  tools.</para>
  
  <section xml:id="enable-repl">
   <title>Enabling Replication</title>
@@ -177,7 +176,7 @@
   <screen>$ dsreplication
 enable
 --adminUID admin
 --bindPassword password
 --adminPassword password
 --baseDN dc=example,dc=com
 --host1 `hostname`
 --port1 4444
@@ -219,9 +218,13 @@
/var/.../opends-replication-7958637258600693490.log
for a detailed log of this operation.</screen>
   
   <para>To enable secure connections for replication use the
   <option>--secureReplication1</option> and
   <option>--secureReplication2</option> options.</para>
   
   <para>As you see in the command output, replication is set up to function
   once enabled. You must however initialize replication in order to start
   the process, however.</para>
   the process.</para>
   
   <para>If you need to add another OpenDJ directory server to participate
   in replication, use the <command>dsreplication enable</command> with
@@ -232,7 +235,7 @@
   <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>
   must initialize each replica to activate the replication process.</para>
   
   <para>You can perform initialization either over the replication protocol,
   by importing the same LDIF data on all server before performing
@@ -243,6 +246,10 @@
   <procedure xml:id="init-repl-online">
    <title>To Initialize Online</title>
    
    <para>Online initialization is straightforward, and works well if
    your network bandwidth is large compared to the amount of data to
    replicate.</para>
    
    <step>
     <para>Make sure you have enabled servers you want to participate in
     replication.</para>
@@ -254,7 +261,7 @@
     <screen>$ dsreplication
 initialize-all
 --adminUID admin
 --bindPassword password
 --adminPassword password
 --baseDN dc=example,dc=com
 --hostname `hostname`
 --port 4444
@@ -277,6 +284,11 @@
    <para>Follow these steps to prepare a replication topology starting from
    directory data in LDIF.</para>
    
    <para>Depending on the size of the data and your network bandwidth, you
    might find it quicker to initialize all replica as described in
    <xref linkend="init-repl-online" />, and then import the LDIF on a single
    replica.</para>
    
    <step>
     <para>Import the same LDIF on all servers you want to participate in
     replication.</para>
@@ -291,7 +303,7 @@
     <screen>$ dsreplication
 initialize-all
 --adminUID admin
 --bindPassword password
 --adminPassword password
 --baseDN dc=example,dc=com
 --hostname `hostname`
 --port 4444
@@ -310,25 +322,24 @@
   <procedure xml:id="init-repl-backup">
    <title>To Create a New Replica From Existing Backup</title>
    
    <para>You can create a new replica from a backup of an existing replica.
    The <command>dsreplication</command> commands use differ slightly from
    the other cases, as you must reset the generation ID on the new replica,
    such that replication can proceed from the proper starting point.
    Follow these steps to add another server to the topology by restoring
    from a backup copy of an existing server.</para>
    <para>You can create a new replica from a backup of a server in the existing
    topology. The <command>dsreplication</command> commands use differ slightly
    from the other cases, as you must reset the generation ID on the new
    replica, such that replication can proceed from the proper starting point.
    Follow these steps to add another server to the topology.</para>
    
    <step>
     <para>Install a new server to serve as the new replica.</para>
    </step>
    <step>
     <para>Backup the database to replica on an existing server.</para>
     <para>Backup the database to replicate from an existing server.</para>
    </step>
    <step>
     <para>Enable replication on the new replica.</para>
     <screen>$ dsreplication
 enable
 --adminUID admin
 --bindPassword password
 --adminPassword password
 --baseDN dc=example,dc=com
 --host1 `hostname`
 --port1 4444
@@ -379,7 +390,7 @@
     <screen>$ dsreplication
 pre-external-initialization
 --adminUID admin
 --bindPassword password
 --adminPassword password
 --port 6444
 --baseDN dc=example,dc=com
 --trustAll
@@ -397,14 +408,15 @@
 new base DN's contents.</screen>
    </step>
    <step>
     <para>Restore the new server database from the backup archive.</para>
     <para>On the new server, restore the database from the backup
     archive.</para>
    </step>
    <step>
     <para>Initialize replication on the new replica.</para>
     <screen>$ dsreplication
 post-external-initialization
 --adminUID admin
 --bindPassword password
 --adminPassword password
 --port 6444
 --baseDN dc=example,dc=com
 --trustAll
@@ -425,14 +437,19 @@
   </indexterm>
   
   <para>How you stop replication depends on whether the change is meant to
   be temporary, or meant to be permanent.</para>
   be temporary or permanent.</para>
   
   <procedure xml:id="stop-repl-tmp">
    <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>
    do so using <command>dsconfig</command> command.</para>
    
    <warning>
     <para>Do not allow modifications on the replica for which replication is
     disabled, as no record of such changes is kept, and the changes cause
     replication to diverge.</para>
    </warning>

    <step>
     <para>Disable the multimaster synchronization provider.</para>
@@ -446,9 +463,6 @@
 --set enabled:false
 --trustAll
 --no-prompt</screen>
     <para>Do NOT allow modifications on the replica for which replication is
     paused, as no record of such changes is kept, and the changes cause
     replication to diverge.</para>
    </step>
    <step performance="optional">
     <para>When you are ready to resume replication, enable the multimaster
@@ -482,7 +496,7 @@
 --port 5444
 --hostname `hostname`
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --adminPassword password
 --trustAll
 --no-prompt
Establishing connections ..... Done.
@@ -498,12 +512,12 @@
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>
     <para>The <command>dsreplication disable</command> as shown completely
     removes the replication configuration information from the server.</para>
    </step>
    <step performance="optional">
     <para>If you want to restart replication for the server, you use the
     <command>dsreplication enable</command> and <command>dsreplication
     <para>If you want to restart replication for the server, you need to run
     the <command>dsreplication enable</command> and <command>dsreplication
     initialize</command> commands again.</para>
    </step>
   </procedure>
@@ -531,6 +545,16 @@
   in your topology. Yet only the stand-alone replication servers participate
   in fully-meshed replication.</para>
   

   <tip>
    <para>If you set up OpenDJ directory server to replicate by using the
    Quick Setup wizard, then the wizard activated the replication service for
    that server. You can turn off the replication service on OpenDJ directory
    server, and then configure the server to work with a separate, stand-alone
    replication server instead. Start by using the <command>dsreplication
    disable --disableReplicationServer</command> command to turn off the
    replication service on the server.</para>
   </tip>
   
   <procedure xml:id="repl-setup-dedicated-server">
    <title>To Set Up a Stand-alone Replication Server</title>
@@ -559,7 +583,7 @@
     <screen>$ dsreplication
 enable
 --adminUID admin
 --bindPassword password
 --adminPassword password
 --baseDN dc=example,dc=com
 --host1 `hostname`
 --port1 4444
@@ -602,7 +626,7 @@
$ dsreplication
 enable
 --adminUID admin
 --bindPassword password
 --adminPassword password
 --baseDN dc=example,dc=com
 --host1 `hostname`
 --port1 5444
@@ -653,7 +677,7 @@
     <screen>$ dsreplication
 initialize-all
 --adminUID admin
 --bindPassword password
 --adminPassword password
 --baseDN dc=example,dc=com
 --hostname `hostname`
 --port 4444
@@ -683,6 +707,11 @@
   servers outside the group. Groups are identified with unique numeric
   group IDs.</para>
   
   <para>Replication groups are designed for deployments across multiple data
   centers, where you aim to focus replication traffic on the LAN rather than
   the WAN. In multi-data center deployments, group nearby servers
   together.</para>
   
   <procedure xml:id="define-repl-groups">
    <title>To Set Up Replication Groups</title>
    
@@ -751,16 +780,6 @@
 --no-prompt</screen>
    </step>
   </procedure>

   <tip>
    <para>If you set up OpenDJ directory server to replicate by using the
    Quick Setup wizard, then the wizard activated the replication service for
    that server. You can turn off the replication service on OpenDJ directory
    server, and then configure the server to work with a separate, stand-alone
    replication server instead. Start by using the <command>dsreplication
    disable --disableReplicationServer</command> command to turn off the
    replication service on the server.</para>   
   </tip>
  </section>

  <section xml:id="read-only-repl">
@@ -900,7 +919,7 @@
    <secondary>Subtree</secondary>
   </indexterm>
   
   <para>OpenDJ lets you do subtree replication, for example replicating
   <para>OpenDJ can perform subtree replication, for example replicating
   <literal>ou=People,dc=example,dc=com</literal>, but not the rest of
   <literal>dc=example,dc=com</literal>, by putting the subtree in a separate
   backend from the rest of the suffix.</para>
@@ -920,18 +939,26 @@
    <secondary>Fractional</secondary>
   </indexterm>
   
   <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>OpenDJ can perform fractional replication, whereby you specify
   the attributes to include in or to exclude from the replication
   process.</para>
   
   <para>You set fractional replication configuration as
   <literal>fractional-include</literal> or
   <literal>fractional-exclude</literal> properties for a replication
   domain. When you include attributes, the attributes that must be kept on
   domain. When you include attributes, the attributes that are required on
   the relevant object classes are also included, whether you specify them
   or not. When you exclude attributes, the excluded attributes must be
   optional attributes for the relevant object classes. Fractional
   replica still respect schema definitions.</para>
   replicas still respect schema definitions.</para>
   
   <para>Fractional replication works by filtering objects at the replication
   server. Initialize replication as you would normally. Of course you cannot
   create a full replica from a replica with only a subset of the data. If you
   must prevent data from being replicated across a national boundary, split
   the replication server handling the updates from the directory servers
   receiving the updates as described in
   <xref linkend="repl-setup-dedicated-server" />.</para>
   
   <para>For example, you might configure an externally facing
   fractional replica to include only some <literal>inetOrgPerson</literal>
@@ -986,14 +1013,14 @@
  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
  <para>In addition to supporting persistent search operations, OpenDJ
  provides an external change log mechanism to allow applications to be
  notified of changes to directory data.</para>
  
  <procedure xml:id="enable-ecl">
   <title>To Enable the External Change Log</title>

   <para>OpenDJ directory servers not using replication cannot expose an
   <para>OpenDJ directory servers without replication cannot expose an
   external change log. The OpenDJ server that exposes the change log must
   function both as a directory server, and also as a replication server for
   the suffix whose changes you want logged.</para>
@@ -1023,7 +1050,7 @@
  <procedure xml:id="use-ecl">
   <title>To Use the External Change Log</title>
   
   <para>You read the external change log over protocol. In addition, when you
   <para>You read the external change log over LDAP. In addition, when you
   poll the change log periodically, you can get the list of updates that
   happened since your last request.</para>