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

Mark Craig

07.18.2011 a8f036a3b2103e1f73f446458d2da3814060ea8f

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

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

@@ -31,9 +31,460 @@
 xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <title>Indexing Attribute Values</title>

 <para>OpenDJ provides several indexing schemes to speed up searches.
 This chapter describes how to index attribute values, and lists the
 default indexing configuration for the directory server.</para>
 <para>OpenDJ provides several indexing schemes to speed up searches.</para>

 <para>When a client requests a directory search operation, the client sends
 the server a filter expression such as
 <literal>(&amp;(uid=*jensen*)(l=Stavanger))</literal>. The server then uses
 applicable indexes to find entries with attribute values likely to match
 the search. If no indexes are applicable, then the server potentially has
 to go through all entries to look for candidate matches.</para>
 
 <para>Looking through all entries is resource-intensive for large directories.
 For this reason, the <literal>unindexed-search</literal> privilege, allowing
 users to request searches for which no applicable index exists, is reserved
 for the directory root user by default.</para>
 
 <para>Rather than granting the <literal>unindexed-search</literal> privilege
 to more users and client applications, you configure indexes to correspond
 to the searches that clients need to perform.</para>
 
 <para>This chapter first describes index types, then demonstrates how to
 index attribute values. This chapter also lists the default indexing
 configuration for OpenDJ directory server.</para>
 
 <section>
  <title>Index Types &amp; What Each Does</title>
  
  <para>OpenDJ provides several different index types, each corresponding
  to a different type of search.</para>
  
  <section>
   <title>Approximate Index</title>
   
   <para>An approximate index is used to match values that "sound like" those
   provided in the filter. An approximate index on <literal>cn</literal>
   allows clients to find people even when they misspell names as in the
   following example.</para>
   
   <screen width="80">$ ldapsearch -b dc=example,dc=com "(cn~=Babs Jansen)" cn
dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen</screen>
  </section>
  
  <section>
   <title>Equality Index</title>
   
   <para>An equality index is used to match values that correspond exactly
   (though generally without case sensitivity) to the value provided in
   the search filter. An equality index requires clients to match values
   without wildcards or misspellings.</para>
   
   <screen width="80">$ ldapsearch -b dc=example,dc=com "(uid=bjensen)" mail
dn: uid=bjensen,ou=People,dc=example,dc=com
mail: bjensen@example.com</screen>
  </section>
  
  <section>
   <title>Ordering Index</title>
   
   <para>An ordering index is used to match values for a filter that
   specifies a range. The <literal>ds-sync-hist</literal> has an ordering
   index by default because searches on that attribute often seek entries
   with changes more recent than the last time a search was performed.</para>
   
   <para>The following example shows a search that specifies ranges.</para>
   
   <screen width="80">$ ldapsearch -b dc=example,dc=com \
&gt; "(&amp;(uidNumber>=1120)(roomNumber>=4500))" uid
dn: uid=charvey,ou=People,dc=example,dc=com
uid: charvey

dn: uid=eward,ou=People,dc=example,dc=com
uid: eward

dn: uid=mvaughan,ou=People,dc=example,dc=com
uid: mvaughan

dn: uid=pchassin,ou=People,dc=example,dc=com
uid: pchassin</screen>
  </section>
  
  <section>
   <title>Presence Index</title>
   
   <para>A presence index is used to match the fact that an attribute is
   present on the entry, regardless of the value. The <literal>aci</literal>
   attribute is indexed for presence by default to allow quick retrieval
   of entries with ACIs.</para>
   
   <screen width="80">$ ldapsearch -b dc=example,dc=com "(aci=*)" -
dn: dc=example,dc=com

dn: ou=People,dc=example,dc=com</screen>
  </section>
  
  <section>
   <title>Substring Index</title>
   
   <para>A substring index is used to match values specified with wildcards
   in the filter. Substring indexes can be expensive to maintain, especially
   for large attribute values.</para>
   
   <screen width="80">$ ldapsearch -b dc=example,dc=com "(cn=Barb*)" cn
dn: uid=bfrancis,ou=People,dc=example,dc=com
cn: Barbara Francis

dn: uid=bhal2,ou=People,dc=example,dc=com
cn: Barbara Hall

dn: uid=bjablons,ou=People,dc=example,dc=com
cn: Barbara Jablonski

dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen

dn: uid=bmaddox,ou=People,dc=example,dc=com
cn: Barbara Maddox</screen>
  </section>
  
  <section>
   <title>Virtual List View (Browsing) Index</title>
   
   <para>A VLV or browsing index are designed to help the server respond to
   client applications that need virtual list view results, for example to
   browse through a long list in a GUI. They also help the server respond
   to clients that request server-side sorting of the search results.</para>
   
   <para>VLV indexes correspond to particular searches. Configure your
   VLV indexes using the Control Panel, and copy the command-line
   equivalent from the Details pane for the operation, if necessary.</para>
  </section>
 </section>
 
 <section>
  <title>Configuring &amp; Rebuilding Indexes</title>
  
  <para>You modify index configurations using the <command>dsconfig</command>
  command. The configuration changes then take effect after you rebuild the
  index according to the new configuration, using the
  <command>rebuild-index</command>.</para>
  
  <section>
   <title>Configuring a Standard Index</title>
   
   <para>You can configure standard indexes from the Control Panel, and also
   on the command line using the <command>dsconfig</command> command. After
   you finish configuring the index, you must rebuild the index for the changes
   to take effect.</para>
   
   <example>
    <title>Create a New Index</title>
    
    <para>The following example creates a new substring index for
    <literal>description</literal>.</para>
    
    <screen width="80">$ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
&gt; create-local-db-index --backend-name userRoot --index-name description 
&gt; --set index-type:substring -n</screen>
   </example>
   
   <example>
    <title>Configure an Approximate Index</title>
    
    <para>The following example configures and approximate index for
    <literal>cn</literal> (common name).</para>
    
    <screen width="80">$ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
&gt; set-local-db-index-prop --backend-name userRoot --index-name cn \
&gt; --set index-type:approximate -n</screen>
   </example>
  </section>
  
  <section>
   <title>Configuring a Virtual List View Index</title>
   
   <para>In the OpenDJ Control Panel, select Manage Indexes &gt;
   New VLV Index..., and then set up your VLV index using the New VLV
   Index window.</para>
  
   <mediaobject>
    <imageobject>
     <imagedata fileref="images/create-vlv-index.png" format="PNG" />
    </imageobject>
   </mediaobject>  

   <para>After you finish configuring your index and click OK, the Control
   Panel prompts you to make the additional changes necessary to complete the
   VLV index configuration, and then to build the index.</para>
  </section>

  <section>
   <title>Rebuilding Indexes</title>
   
   <para>After you change an index configuration, or when you find that
   an index is corrupt, you can rebuild the index. If you rebuild the index
   while the server is online, then you must schedule the rebuild process
   as a task.</para>
   
   <example>
    <title>Rebuild Index</title>

    <para>The following example rebuilds the <literal>cn</literal> index
    immediately with the server online.</para>
    
    <screen>$ 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 20110607171639867 scheduled to start Jun 7, 2011 5:16:39 PM</screen>
   </example>
  </section>

  <section>
   <title>Changing Index Entry Limits</title>
   
   <para>Indexing data makes sense when maintaining the index is quicker and
   cheaper than searching through all entries.</para>
   
   <para>As the number of entries in your directory grows, it can make sense
   not to maintain indexes for particular values. For example, every entry
   in the directory has the value <literal>top</literal> for the
   <literal>objectClass</literal> attribute, so maintaining a list of entries
   that match the filter <literal>(objectClass=top)</literal> is not a
   reasonable use of resources. In a very, very large directory, the same can
   be true for <literal>(givenName=John)</literal> and
   <literal>(sn=Smith)</literal>.</para>
   
   <para>In an index, each index key points to a list of entries that
   are candidates to match. For the <literal>objectClass</literal> index key
   that corresponds to <literal>=top</literal>, the list of entries can
   include every entry in the directory.</para>
   
   <para>OpenDJ directory server therefore defines an index entry limit. When
   the number of entries that an index key points to exceeds the index entry
   limit, OpenDJ stops maintaining the list of entries for that index key.</para>
   
   <para>The default index entry limit value is 4000. 4000 is usually plenty
   large for all index keys, except for <literal>objectClass</literal> indexes.
   If you have clients performing searches with filters such as
   <literal>(objectClass=person)</literal>, you might suggest that they adjust
   the search to be more specific, such as
   <literal>(&amp;(mail=username@maildomain.net)(objectClass=person))</literal>,
   so that the server can use an index, in this case equality for mail, to
   limit the number of candidate entries to check for matches.</para>

   <para>You can change the index entry limit on a per index basis.</para>
   
   <example>
    <title>Change Index Entry Limit</title>
    
    <para>The following example changes the index entry limit for the
    <literal>objectClass</literal> index, and then rebuilds the index for the
    configuration change to take effect.</para>
    
    <screen width="80">$ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
&gt; set-local-db-index-prop --backend-name userRoot --index-name objectClass \
&gt; --set index-entry-limit:5000 -n
$ rebuild-index -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \
&gt; -b dc=example,dc=com -i objectclass -t 0
Rebuild Index task 20110607160349596 scheduled to start Jun 7, 2011 4:03:49 PM</screen>    
   </example>
  </section>
 </section>

 <section>
  <title>Verifying Indexes</title>
  
  <para>You can verify that indexes correspond to current directory data,
  and that indexes do not contain errors using the
  <command>verify-index</command> command.</para>
  
  <example>
   <title>Verify Index</title>
   
   <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>
  </example>
 </section>
 
 <section>
  <title>Default Indexes</title>
  
  <para>When you first install OpenDJ directory server and import your
  data from LDIF, the following indexes are configured.</para>
  
  <table frame="topbot" rowheader="firstcol">
   <title>Default Indexes</title>
   <tgroup cols="7" rowsep="1">
   <colspec colnum="2" colname="c2" />
   <colspec colnum="7" colname="c7" />
    <thead>
     <row>
      <entry>Index</entry>
      <entry>Approximate</entry>
      <entry>Equality</entry>
      <entry>Ordering</entry>
      <entry>Presence</entry>
      <entry>Substring</entry>
      <entry>Entry Limit</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry><literal>aci</literal></entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>-</entry>
      <entry>4000</entry>
     </row>
     <row>
      <entry><literal>cn</literal></entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>4000</entry>
     </row>
     <row>
      <entry><literal>dn2id</literal></entry>
      <entry namest="c2" nameend="c7" align="center">Non-configurable
      internal index</entry>
     </row>
     <row>
      <entry><literal>ds-sync-conflict</literal></entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>4000</entry>
     </row>
     <row>
      <entry><literal>ds-sync-hist</literal></entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>4000</entry>
     </row>
     <row>
      <entry><literal>entryUUID</literal></entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>4000</entry>
     </row>
     <row>
      <entry><literal>givenName</literal></entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>4000</entry>
     </row>
     <row>
      <entry><literal>id2children</literal></entry>
      <entry namest="c2" nameend="c7" align="center">Non-configurable
      internal index</entry>
     </row>
     <row>
      <entry><literal>id2subtree</literal></entry>
      <entry namest="c2" nameend="c7" align="center">Non-configurable
      internal index</entry>
     </row>
     <row>
      <entry><literal>mail</literal></entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>4000</entry>
     </row>
     <row>
      <entry><literal>member</literal></entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>4000</entry>
     </row>
     <row>
      <entry><literal>objectClass</literal></entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>4000</entry>
     </row>
     <row>
      <entry><literal>sn</literal></entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>4000</entry>
     </row>
     <row>
      <entry><literal>telephoneNumber</literal></entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>4000</entry>
     </row>
     <row>
      <entry><literal>uid</literal></entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>4000</entry>
     </row>
     <row>
      <entry><literal>uniqueMember</literal></entry>
      <entry>-</entry>
      <entry>Yes</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>-</entry>
      <entry>4000</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
 </section>
</chapter>


 opendj3/src/main/docbkx/admin-guide/images/create-vlv-index.png

 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>

 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>