Draft repl chapter. This version is still missing the part concerning the c...

Mark Craig

10.05.2011 1f24b40e26e6087132d2001e8ce2ebdb832c0f03

 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>&gt; 0</term>
     <listitem>
      <para>An error occurred.</para>
     </listitem>
    </varlistentry>
   </variablelist>