Fix OPENDJ-129: Consider adding manual pages for SDK tools, especially xxxr...

Mark Craig

24.27.2011 b20fcd8a1388bbc22db1d43e4b222617829a2eda

 opendj3/src/docbkx/dev-guide/man-modrate.xml

@@ -32,75 +32,340 @@
 xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <refmeta>
  <refentrytitle>modrate</refentrytitle><manvolnum>1</manvolnum>
  <refmiscinfo class="software">OpenDJ</refmiscinfo>
  <refmiscinfo class="version"><?eval ${project.version}?></refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>modrate</refname>
  <refpurpose>TODO one-line description</refpurpose>
  <refpurpose>measure modification throughput and response time</refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <cmdsynopsis>
   <command>modrate</command>
   <command><replaceable>subcommand</replaceable></command>
   <arg choice="opt">--options</arg>
   <arg choice="req">options</arg>
   <group choice="opt" rep="repeat">
    <arg>attribute</arg>
    <arg>:</arg>
    <arg>value format string</arg>
   </group>
  </cmdsynopsis>
 </refsynopsisdiv>
 <refsect1>
  <title>Description</title>
  <para>TODO description.</para>
  <para>This utility can be used to measure modify throughput and response time
  of a directory service using user-defined modifications.</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>-A, --asynchronous</option></term>
    <listitem>
     <para>TODO Description.</para>
     <para>Use asynchronous mode and don't wait for results before sending the
     next request</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-b, --baseDN {baseDN}</option></term>
    <listitem>
     <para>Base DN format string</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-c, --numConnections {numConnections}</option></term>
    <listitem>
     <para>Number of connections</para>
     <para>Default value: 1</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-e, --percentile {percentile}</option></term>
    <listitem>
     <para>Calculate max response time for a percentile of operations</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-f, --keepConnectionsOpen</option></term>
    <listitem>
     <para>Keep connections open</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-F, --noRebind</option></term>
    <listitem>
     <para>Keep connections open and don't rebind</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-g, --argument {generator function or static string}</option></term>
    <listitem>
     <para>Argument used to evaluate the Java style format strings in program
     parameters (Base DN, Search Filter). The set of all arguments provided
     form the the argument list in order. Besides static string arguments, they
     can be generated per iteration with the following functions:</para>
    <variablelist>
     <varlistentry>
      <term>"inc({filename})"</term>
      <listitem><para>Consecutive, incremental line from file</para></listitem>
     </varlistentry>
     <varlistentry>
      <term>"inc({min},{max})"</term>
      <listitem><para>Consecutive, incremental number</para></listitem>
     </varlistentry>
     <varlistentry>
      <term>"rand({filename})"</term>
      <listitem><para>Random line from file</para></listitem>
     </varlistentry>
     <varlistentry>
      <term>"rand({min},{max})"</term>
      <listitem><para>Random number</para></listitem>
     </varlistentry>
     <varlistentry>
      <term>"randStr({length},<replaceable>charSet</replaceable>)"</term>
      <listitem><para>Random string of specified length and optionally from
      characters in the charSet string. A range of character can be specified
      with [start-end] charSet notation. If no charSet is specified,
      the default charSet of [A-Z][a-z][0-9] will be used.</para></listitem>
     </varlistentry>
    </variablelist>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-i, --statInterval {statInterval}</option></term>
    <listitem>
     <para>Display results each specified number of seconds</para>
     <para>Default value: 5</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-m, --maxIterations {maxIterations}</option></term>
    <listitem>
     <para>Max iterations, 0 for unlimited</para>
     <para>Default value: 0</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-M, --targetThroughput {targetThroughput}</option></term>
    <listitem>
     <para>Target average throughput to achieve</para>
     <para>Default value: 0</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-S, --scriptFriendly</option></term>
    <listitem>
     <para>Use script-friendly mode</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-t, --numConcurrentTasks {numConcurrentTasks}</option></term>
    <listitem>
     <para>Number of concurrent tasks per connection</para>
     <para>Default value: 1</para>
    </listitem>
   </varlistentry>   
  </variablelist>
 </refsect1>
 <refsect1>
  <title>Subcommands</title>
  <para>The following subcommands are supported.</para>
  <refsect2>
   <para>TODO Description.</para>
   <cmdsynopsis>
    <command>modrate</command>
    <command>TODO</command>
    <arg choice="opt">--options</arg>
   </cmdsynopsis>
   <title>LDAP Connection Options</title>
   <variablelist>
    <varlistentry>
     <term><option>TODO</option></term>
     <term><option>-D, --bindDN {bindDN}</option></term>
     <listitem>
      <para>TODO description.</para>
      <para>DN to use to bind to the server</para>
      <para>Default value: cn=Directory Manager</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>-E, --reportAuthzID</option></term>
     <listitem>
      <para>Use the authorization identity control</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 port number</para>
      <para>Default value: 389</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>-P, --trustStorePath {trustStorePath}</option></term>
     <listitem>
      <para>Certificate trust store path</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>-q, --useStartTLS</option></term>
     <listitem>
      <para>Use StartTLS to secure communication with the server</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>--usePasswordPolicyControl</option></term>
     <listitem>
      <para>Use the password policy request control</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>
    <varlistentry>
     <term><option>-Z, --useSSL</option></term>
     <listitem>
      <para>Use SSL for secure communication with the server</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>
    <varlistentry>
     <term><option>-v, --verbose</option></term>
     <listitem>
      <para>Use verbose mode</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>89</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 demonstrates testing directory performance by
  using the modrate command to write random 16-character description values
  to all entries in a sample file.</para>
  <screen width="80">$ grep ^uid: /path/to/Example.ldif | sed -e "s/uid: //" &gt; names.txt
$ modrate -p 1389 -D cn=directory\ manager -w secret12 \
&gt; -b "uid=%s,ou=people,dc=example,dc=com" -g "rand(names.txt)" \
&gt;"description:%s" -g "randStr(16)" -A -F -c 4 -t 4
-----------------------------------------------------------------
     Throughput                            Response Time         
   (ops/second)                           (milliseconds)         
recent  average  recent  average  99.9%  99.99%  99.999%  err/sec
-----------------------------------------------------------------
 399.0    399.0   1.546    1.546  8.917  79.764   79.764      0.0
 541.6    470.5   1.109    1.294  8.917  181.808 181.808      0.0
 755.2    565.4   0.747    1.050  9.828  181.808 181.808      0.0
 786.9    620.8   0.718    0.945  10.175 114.424 181.808      0.0
1209.3    738.3   0.469    0.789  8.917  114.424 181.808      0.0
1255.8    824.5   0.474    0.709  8.365  79.764  181.808      0.0
1359.1    900.8   0.430    0.649  7.610  72.218  181.808      0.0
1294.5    950.0   0.463    0.618  7.589  81.093  181.808      0.0
1280.0    986.6   0.471    0.596  7.533  81.093  204.701      0.0
1301.9   1018.2   0.463    0.579  7.506  81.093  204.701      0.0
^C</screen>
 </refsect1>
</refentry>