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-verify-index.xml

@@ -35,72 +35,123 @@
 </refmeta>
 <refnamediv>
  <refname>verify-index</refname>
  <refpurpose>TODO one-line description</refpurpose>
  <refpurpose>check index for consistency or errors</refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <cmdsynopsis>
   <command>verify-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 ensure that index data is consistent
  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. Verification is
     performed on indexes within the scope of the given base DN.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-c, --clean</option></term>
    <listitem>
     <para>Specifies that a single index should be verified to ensure it is
     clean. An index is clean if each index value references only entries
     containing that value. Only one index at a time may be verified in this
     way.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>--countErrors</option></term>
    <listitem>
     <para>Count the number of errors found during the verification and return
     that value as the exit code (values &gt; 255 will be reduced to 255 due to
     exit code restrictions).</para>
    </listitem>
   </varlistentry>   
   <varlistentry>
    <term><option>-i, --index {index}</option></term>
    <listitem>
     <para>Name of an index to be verified. For an attribute index this is
     simply an attribute name. Multiple indexes may be verified for
     completeness, or all indexes if no indexes are specified.  An index is
     complete if each index value references all entries containing that
     value.</para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
 <refsect1>
  <title>Subcommands</title>
  <para>The following subcommands are supported.</para>
  <refsect2>
   <para>TODO Description.</para>
   <cmdsynopsis>
    <command>verify-index</command>
    <command>TODO</command>
    <arg choice="opt">--options</arg>
   </cmdsynopsis>
   <title>General Options</title>
   <variablelist>
    <varlistentry>
     <term><option>TODO</option></term>
     <term><option>-V, --version</option></term>
     <listitem>
      <para>TODO description.</para>
      <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>
    <varlistentry>
     <term>0-255</term>
     <listitem>
      <para>The number of errors in the index, as indicated for the
      <option>--countErrors</option> option.</para>
     </listitem>
    </varlistentry>
   </variablelist>
 </refsect1>
 <refsect1>
  <title>Examples</title>
  <para>TODO</para>
  <para>The following example verifies the <literal>cn</literal> (common
   name) index for completeness and for errors.</para>

   <screen width="80">$ verify-index -b dc=example,dc=com -i cn --clean --countErrors
[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
 msgID=9437595 msg=Local DB backend userRoot does not specify the number of
 lock tables: defaulting to 97
[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
 msgID=9437594 msg=Local DB backend userRoot does not specify the number of
 cleaner threads: defaulting to 24 threads
[07/Jun/2011:16:06:51 +0200] category=JEB severity=NOTICE msgID=8847461
 msg=Checked 1316 records and found 0 error(s) in 0 seconds
 (average rate 2506.7/sec)
[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
 msgID=8388710 msg=Number of records referencing more than one entry: 315
[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
 msgID=8388711 msg=Number of records that exceed the entry limit: 0
[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
 msgID=8388712 msg=Average number of entries referenced is 1.58/record
[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
 msgID=8388713 msg=Maximum number of entries referenced by any
 record is 32</screen>
 </refsect1>
</refentry>