From def05ed8de5b653d3fed997ca56444e4f60a4dca Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Tue, 21 Jun 2011 14:32:57 +0000
Subject: [PATCH] Draft tools ref complete for Admin and Dev guides
---
opendj3/src/main/docbkx/shared/man-upgrade.xml | 143 +++++++++++++++++++++++++++++++++++------------
1 files changed, 106 insertions(+), 37 deletions(-)
diff --git a/opendj3/src/main/docbkx/shared/man-upgrade.xml b/opendj3/src/main/docbkx/shared/man-upgrade.xml
index bbbcd4d..93cb3ad 100644
--- a/opendj3/src/main/docbkx/shared/man-upgrade.xml
+++ b/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>> 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>
--
Gitblit v1.10.0