Draft tools ref complete for Admin and Dev guides

Mark Craig

21.32.2011 def05ed8de5b653d3fed997ca56444e4f60a4dca

 opendj3/src/main/docbkx/shared/man-upgrade.xml

@@ -35,72 +35,141 @@
 </refmeta>
 <refnamediv>
  <refname>upgrade</refname>
  <refpurpose>TODO one-line description</refpurpose>
  <refpurpose>upgrade OpenDJ directory server</refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <cmdsynopsis>
   <command>upgrade</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 upgrade the directory server to a newer
  version or revert to a previous version.</para>
  <para>When using this tool to upgrade the server you should first downloaded
  an OpenDJ install package (.zip) file and specify its location using the
  -f/--file option.  You can also upgrade your server using the Java Web Start
  version of this tool by visiting the OpenDJ web site at
  www.forgerock.org/downloads-opendj.html.</para>
  <para>When using the tool to revert to a previous version you must either
  indicate that you want to revert to the version before the most recent
  upgrade using the -r/--revertMostRecent option or specify the location of a
  reversion archive using the -a/--reversionArchive option.</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, --reversionArchive {directory}</option></term>
    <listitem>
     <para>TODO Description.</para>
     <para>Directory where reversion files are stored.  This should be one of
     the child directories of the 'history' directory that is created when the
     upgrade tool is run.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-f, --file {file}</option></term>
    <listitem>
     <para>Specifies an existing server package (.zip) file to which the
     current build will be upgraded using the command line version of this
     tool</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-r, --revertMostRecent</option></term>
    <listitem>
     <para>The installation will be reverted to the state before the most
     recent upgrade</para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
 <refsect1>
  <title>Subcommands</title>
  <para>The following subcommands are supported.</para>
  <refsect2>
   <para>TODO Description.</para>
   <cmdsynopsis>
    <command>upgrade</command>
    <command>TODO</command>
    <arg choice="opt">--options</arg>
   </cmdsynopsis>
   <title>Utility Input/Output Options</title>
   <variablelist>
    <varlistentry>
     <term><option>TODO</option></term>
     <term><option>-n, --no-prompt</option></term>
     <listitem>
      <para>TODO description.</para>
      <para>Use non-interactive mode.  If data in the command is missing, the
      user is not prompted and the tool will fail</para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><option>-Q, --quiet</option></term>
     <listitem>
      <para>Run setup in quiet mode.  Quiet mode will not output progress
      information to standard output</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>
     <listitem>
      <para>TODO description.</para>
     </listitem>
    </varlistentry>
   </variablelist>
  <variablelist>
   <varlistentry>
    <term>0</term>
    <listitem>
     <para>The command completed successfully.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>&gt; 0</term>
    <listitem>
     <para>An error occurred.</para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
 <refsect1>
  <title>Examples</title>
  <para>TODO</para>
  <para>The following example demonstrates upgrade without interaction.</para>
  <screen width="80">$ ./OpenDJ/upgrade -f ~/Downloads/OpenDJ-<?eval ${project.version}?>.zip -n
See
/var/.../opends-upgrade-5650414945123366149.log
 for a detailed log of this operation.

Initializing Upgrade ..... Done.
Calculating Schema Customizations ..... Done.
Calculating Configuration Customizations ..... Done.
Backing Up Files ..... Done.
Upgrading Components ..... Done.
Preparing Customizations ..... Done.
Applying Configuration Customizations ..... Done.
Verifying Upgrade ..... Done.
Cleaning Up ..... Done.
Recording Upgrade History ..... Done.
See /path/to/OpenDJ/history/log for a detailed installation history.
QuickUpgrade Completed Successfully.  The OpenDJ installation at
/path/to/OpenDJ has now been upgraded to version OpenDJ <?eval ${project.version}?> (Build ID:
YYYYMMDDhhmmssZ).

See /var/.../opends-upgrade-5650414945123366149.log
 for a detailed log of this operation.
</screen>
 </refsect1>
</refentry>