Draft chapter on indexing for the admin guide, plus a couple of correspondi...

Mark Craig

07.18.2011 a8f036a3b2103e1f73f446458d2da3814060ea8f

 opendj3/src/main/docbkx/shared/man-rebuild-index.xml

@@ -35,72 +35,271 @@
 </refmeta>
 <refnamediv>
  <refname>rebuild-index</refname>
  <refpurpose>TODO one-line description</refpurpose>
  <refpurpose>rebuild index after configuration change</refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <cmdsynopsis>
   <command>rebuild-index</command>
   <command><replaceable>subcommand</replaceable></command>
   <arg choice="opt">--options</arg>
   <arg choice="req">options</arg>
  </cmdsynopsis>
 </refsynopsisdiv>
 <refsect1>
  <title>Description</title>
  <para>TODO description.</para>
  <para>This utility can be used to rebuild index data within a backend based
  on the Berkeley DB Java Edition.</para>
 </refsect1>
 <refsect1>
  <title>Global Options</title>
  <para>The following global options are supported.</para>
  <title>Options</title>
  <para>The following options are supported.</para>
  <variablelist>
   <varlistentry>
    <term><option>TODO</option></term>
    <term><option>-b, --baseDN {baseDN}</option></term>
    <listitem>
     <para>TODO Description.</para>
     <para>Base DN of a backend supporting indexing. Rebuild is performed on
     indexes within the scope of the given base DN.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-i, --index {index}</option></term>
    <listitem>
     <para>Names of index(es) to rebuild. For an attribute index this is
     simply an attribute name. At least one index must be specified for
     rebuild. Cannot be used with the <option>--rebuildAll</option>
     option.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--rebuildAll</option></term>
    <listitem>
     <para>Rebuild all indexes, including any DN2ID, DN2URI, VLV and
     extensible indexes. Cannot be used with the <option>--index</option>
     option.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--tmpdirectory {directory}</option></term>
    <listitem>
     <para>Path to temporary directory for index scratch files during index
     rebuilding.</para>
     <para>Default value: import-tmp</para>
    </listitem>
   </varlistentry>   
  </variablelist>
 </refsect1>
 <refsect1>
  <title>Subcommands</title>
  <para>The following subcommands are supported.</para>
  <refsect2>
   <para>TODO Description.</para>
   <cmdsynopsis>
    <command>rebuild-index</command>
    <command>TODO</command>
    <arg choice="opt">--options</arg>
   </cmdsynopsis>
   <title>Task Backend 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>-D, --bindDN {bindDN}</option></term>
     <listitem>
      <para>DN to use to bind to the server</para>
      <para>Default value: cn=Directory Manager</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>-j, --bindPasswordFile {bindPasswordFile}</option></term>
     <listitem>
      <para>Bind 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>
     </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, --bindPassword {bindPassword}</option></term>
     <listitem>
      <para>Password to use to bind to the server</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>Task Scheduling Options</title>
   <variablelist>
    <varlistentry>
     <term><option>--completionNotify {emailAddress}</option></term>
     <listitem>
      <para>Email address of a recipient to be notified when the task
      completes. This option may be specified more than once.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>--dependency {taskID}</option></term>
     <listitem>
      <para>ID of a task upon which this task depends. A task will not start
      execution until all its dependencies have completed execution.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>--errorNotify {emailAddress}</option></term>
     <listitem>
      <para>Email address of a recipient to be notified if an error occurs
      when this task executes. This option may be specified more than
      once.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>--failedDependencyAction {action}</option></term>
     <listitem>
      <para>Action this task will take should one if its dependent tasks fail.
      The value must be one of PROCESS, CANCEL, DISABLE. If not specified
      defaults to CANCEL.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>--recurringTask {schedulePattern}</option></term>
     <listitem>
      <para>Indicates the task is recurring and will be scheduled according
      to the value argument expressed in crontab(5) compatible time/date
      pattern.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>-t, --start {startTime}</option></term>
     <listitem>
      <para>Indicates the date/time at which this operation will start when
      scheduled as a server task expressed in YYYYMMDDhhmmssZ format for UTC
      time or YYYYMMDDhhmmss for local time. A value of '0' will cause the
      task to be scheduled for immediate execution. When this option is
      specified the operation will be scheduled to start at the specified
      time after which this utility will exit immediately.</para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect2>
  <refsect2>
   <title>Utility Input/Output Options</title>
   <variablelist>
    <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>
   </variablelist>
  </refsect2>
  <refsect2>
   <title>General Options</title>
   <variablelist>
    <varlistentry>
     <term><option>-V, --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>1</term>
     <listitem>
      <para>An error occurred while parsing the command-line arguments.</para>
     </listitem>
    </varlistentry>
   </variablelist>
 </refsect1>
 <refsect1>
  <title>Examples</title>
  <para>TODO</para>
  <para>The following example schedules a task to start immediately that
  rebuilds the <literal>cn</literal> (common name) index.</para>
  
  <screen width="80">$ rebuild-index -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
&gt; -b dc=example,dc=com -i cn -t 0
Rebuild Index task 20110607160349596 scheduled to start Jun 7, 2011 4:03:49 PM</screen>
 </refsect1>
</refentry>