Draft tools ref complete for Admin and Dev guides

Mark Craig

21.32.2011 def05ed8de5b653d3fed997ca56444e4f60a4dca

 opendj3/src/main/docbkx/shared/man-encode-password.xml

@@ -35,72 +35,151 @@
 </refmeta>
 <refnamediv>
  <refname>encode-password</refname>
  <refpurpose>TODO one-line description</refpurpose>
  <refpurpose>encode a password with an OpenDJ storage scheme</refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <cmdsynopsis>
   <command>encode-password</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 encode user passwords with a specified
  storage scheme, or to determine whether a given clear-text value matches a
  provided encoded password.</para>
 </refsect1>
 <refsect1>
  <title>Global Options</title>
  <title>Options</title>
  <para>The following global options are supported.</para>
  <variablelist>
   <varlistentry>
    <term><option>TODO</option></term>
    <term><option>-a, --authPasswordSyntax</option></term>
    <listitem>
     <para>TODO Description.</para>
     <para>Use the authentication password syntax rather than the user
     password syntax.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-c, --clearPassword {clearPW}</option></term>
    <listitem>
     <para>Clear-text password to encode or to compare against an encoded
     password.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-e, --encodedPassword {encodedPW}</option></term>
    <listitem>
     <para>Encoded password to compare against the clear-text password.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-E, --encodedPasswordFile {file}</option></term>
    <listitem>
     <para>Encoded password file.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-f, --clearPasswordFile {file}</option></term>
    <listitem>
     <para>Clear-text password file.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-i, --interactivePassword</option></term>
    <listitem>
     <para>The password to encode or to compare against an encoded password is
     interactively asked to the user.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-l, --listSchemes</option></term>
    <listitem>
     <para>List available password storage schemes.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-r, --useCompareResultCode</option></term>
    <listitem>
     <para>Use the LDAP compare result as an exit code for the password
     comparison.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-s, --storageScheme {scheme}</option></term>
    <listitem>
     <para>Scheme to use for the encoded password.</para>
    </listitem>
   </varlistentry>
   <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>
 </refsect1>
 <refsect1>
  <title>Subcommands</title>
  <para>The following subcommands are supported.</para>
  <refsect2>
   <para>TODO Description.</para>
   <cmdsynopsis>
    <command>encode-password</command>
    <command>TODO</command>
    <arg choice="opt">--options</arg>
   </cmdsynopsis>
   <variablelist>
    <varlistentry>
     <term><option>TODO</option></term>
     <listitem>
      <para>TODO description.</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>5</term>
     <listitem>
      <para>The <option>-r</option> option was used, and the compare did not
      match.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>6</term>
     <listitem>
      <para>The <option>-r</option> option was used, and the compare did
      match.</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>other</term>
     <listitem>
      <para>An error occurred.</para>
     </listitem>
    </varlistentry>
   </variablelist>
 </refsect1>
 <refsect1>
  <title>Examples</title>
  <para>TODO</para>
  <para>The following example encodes a password, and also shows comparison
  of a password with the encoded value.</para>
  <screen width="80">$ encode-password -l
3DES
AES
BASE64
BLOWFISH
CLEAR
CRYPT
MD5
RC4
SHA
SMD5
SSHA
SSHA256
SSHA384
SSHA512
$ encode-password -c secret12 -s CRYPT
Encoded Password:  "{CRYPT}ZulJ6Dy3TFnrE"
$ encode-password -c secret12 -s CRYPT -e "{CRYPT}ZulJ6Dy3TFnrE" -r
The provided clear-text and encoded passwords match
$ echo $?
6</screen>
 </refsect1>
</refentry>