From 052f70c810813d9f5533b3cd4c9138d2df0d15e6 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Fri, 17 May 2013 09:01:33 +0000
Subject: [PATCH] CR-1700 Fix for OPENDJ-865: Document new upgrade experience
---
opendj3/src/main/docbkx/shared/man-upgrade.xml | 208 +++++++++++++++++++++++++++++++++++++--------------
1 files changed, 149 insertions(+), 59 deletions(-)
diff --git a/opendj3/src/main/docbkx/shared/man-upgrade.xml b/opendj3/src/main/docbkx/shared/man-upgrade.xml
index ae5faf0..93847c1 100644
--- a/opendj3/src/main/docbkx/shared/man-upgrade.xml
+++ b/opendj3/src/main/docbkx/shared/man-upgrade.xml
@@ -20,7 +20,7 @@
!
! CCPL HEADER END
!
- ! Copyright 2011-2012 ForgeRock AS
+ ! Copyright 2011-2013 ForgeRock AS
!
-->
<refentry xml:id='upgrade-1'
@@ -30,7 +30,7 @@
xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
xmlns:xlink='http://www.w3.org/1999/xlink'
xmlns:xinclude='http://www.w3.org/2001/XInclude'>
- <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
<refmeta>
<refentrytitle>upgrade</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="software">OpenDJ</refmiscinfo>
@@ -38,7 +38,7 @@
</refmeta>
<refnamediv>
<refname>upgrade</refname>
- <refpurpose>upgrade OpenDJ directory server</refpurpose>
+ <refpurpose>upgrade OpenDJ configuration & application data</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
@@ -48,43 +48,78 @@
</refsynopsisdiv>
<refsect1>
<title>Description</title>
- <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/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>
+
+ <para>This utility upgrades OpenDJ configuration (schema, directory server
+ configuration, and other configuration files) and application data (primarily
+ directory data) so that it is compatible with the binary files and scripts
+ that are installed.</para>
+
+ <para>The <command>upgrade</command> command thus performs only part of the
+ upgrade process, which includes the following phases for a single
+ server.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Get and unpack a newer version of OpenDJ directory server
+ software.</para>
+ </listitem>
+ <listitem>
+ <para>Stop the current OpenDJ directory server.</para>
+ </listitem>
+ <listitem>
+ <para>Overwrite existing binary and script files with those of the
+ newer version, and then run this utility, the <command>upgrade</command>
+ command, before restarting OpenDJ.</para>
+ </listitem>
+ <listitem>
+ <para>Start the upgraded OpenDJ directory server.</para>
+ </listitem>
+ </orderedlist>
+
+ <important>
+ <para>The <command>upgrade</command> command <emphasis>does not back up
+ OpenDJ before you upgrade, nor does it restore OpenDJ if the
+ <command>upgrade</command> command fails</emphasis>. In order to revert a
+ failed upgrade, make sure you back up OpenDJ directory server before you
+ overwrite existing binary and script files.</para>
+ </important>
+
+ <para>By default, the <command>upgrade</command> command requests
+ confirmation before making important configuration changes. You can use
+ the <option>--no-prompt</option> option to run the command
+ non-interactively.</para>
+
+ <para>When using the <option>--no-prompt</option> option, if the
+ <command>upgrade</command> command cannot complete because it requires
+ confirmation for a potentially very long or critical task, then it exits
+ with an error and a message about how to finish making the changes. You can
+ add the <option>--force</option> option to force a non-interactive upgrade
+ to continue in this case, also performing long running and critical
+ tasks.</para>
+
+ <para>After upgrading, see the resulting <filename>upgrade.log</filename>
+ file for a full list of operations performed.</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>The following options are supported.</para>
<variablelist>
<varlistentry>
- <term><option>-a, --reversionArchive {directory}</option></term>
+ <term><option>--force</option></term>
<listitem>
- <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>
+ <para>Forces a non-interactive upgrade to continue even if it requires
+ user interaction. In particular, long running or critical upgrade tasks,
+ such as re-indexing, which require user confirmation will be skipped. This
+ option may only be used with the <option>--no-prompt</option> option.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>-f, --file {file}</option></term>
+ <term><option>--ignoreErrors</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>
+ <para>Ignores any errors which occur during the upgrade. This option
+ should be used with caution and may be useful in automated deployments
+ where potential errors are known in advance and resolved after the upgrade
+ has completed.</para>
</listitem>
</varlistentry>
</variablelist>
@@ -94,21 +129,20 @@
<varlistentry>
<term><option>-n, --no-prompt</option></term>
<listitem>
- <para>Use non-interactive mode. If data in the command is missing, the
- user is not prompted and the tool will fail</para>
+ <para>Use non-interactive mode. Prompt for any required information
+ rather than 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>
+ <para>Use quiet mode.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v, --verbose</option></term>
<listitem>
- <para>Use verbose mode</para>
+ <para>Use verbose mode.</para>
</listitem>
</varlistentry>
</variablelist>
@@ -119,13 +153,13 @@
<varlistentry>
<term><option>-V, --version</option></term>
<listitem>
- <para>Display version information</para>
+ <para>Display version information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-?, -H, --help</option></term>
<listitem>
- <para>Display usage information</para>
+ <para>Display usage information.</para>
</listitem>
</varlistentry>
</variablelist>
@@ -141,7 +175,15 @@
</listitem>
</varlistentry>
<varlistentry>
- <term>> 0</term>
+ <term>2</term>
+ <listitem>
+ <para>The command was run in non-interactive mode, but could not complete
+ because confirmation was required to run a long or critical task.</para>
+ <para>See the error message or the log for details.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Other</term>
<listitem>
<para>An error occurred.</para>
</listitem>
@@ -150,29 +192,77 @@
</refsect1>
<refsect1>
<title>Examples</title>
- <para>The following example demonstrates upgrade without interaction.</para>
- <screen>$ ./OpenDJ/upgrade -f ~/Downloads/OpenDJ-<?eval ${docTargetVersion}?>.zip -n
-See
-/var/.../opends-upgrade-5650414945123366149.log
- for a detailed log of this operation.
+ <para>The following example shows the upgrade process for OpenDJ directory
+ server installed from the cross-platform (.zip) delivery.</para>
-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 ${docTargetVersion}?> (Build ID:
-YYYYMMDDhhmmssZ).
+ <!--
+ Intentionally not using <?eval ${stableServerVersion}?> instead of 2.4.6:
-See /var/.../opends-upgrade-5650414945123366149.log
- for a detailed log of this operation.
-</screen>
+ Once the ${stableServerVersion} has moved to the new file name,
+ the directory names will change, so 2.4.6 is not a variable here,
+ but instead an example that should be common for the first release
+ with the new upgrade command.
+
+ Perhaps people will forgive details missing in this upgrade that happened
+ after the example was run.
+ -->
+
+ <screen>$ cd /path/to
+$ ls
+OpenDJ-2.4.6
+$ ./OpenDJ-2.4.6/bin/stop-ds --quiet
+... msg=The backend userRoot is now taken offline
+... msg=The Directory Server is now stopped
+$ zip -rq OpenDJ-backup.zip OpenDJ-2.4.6
+$ unzip -q ~/Downloads/OpenDJ-<?eval ${docTargetVersion}?>.zip
+$ cp -r opendj/* OpenDJ-2.4.6/
+$ rm -rf opendj
+$ mv OpenDJ-2.4.6 opendj
+$ ./opendj/upgrade --no-prompt
+
+>>>> OpenDJ Upgrade Utility
+
+ * OpenDJ will be upgraded from version 2.4.6.8102 to <?eval ${docTargetVersion}?>.<replaceable>revision</replaceable>
+ * See '/path/to/opendj/upgrade.log' for a detailed log of this operation
+
+>>>> Preparing to upgrade
+
+ OpenDJ <?eval ${docTargetVersion}?> modified the default configuration of the 'isMemberOf' virtual
+ attribute so that it is included with group entries. This was done in order
+ to make it easier for users to determine which groups a 'nested' group
+ belongs to.
+ Do you want to make this configuration change? (yes/no) yes
+
+ The upgrade is ready to proceed. Do you wish to continue? (yes/no) yes
+
+
+>>>> Performing upgrade
+
+ Fixing de-DE collation matching rule OID............................ 100%
+ Updating password policy configurations............................. 100%
+ Updating audit log publisher configuration.......................... 100%
+ Adding 'etag' virtual attribute schema.............................. 100%
+ Configuring 'etag' virtual attribute................................ 100%
+ Configuring 'ds-pwp-password-expiration-time' virtual attribute..... 100%
+ Updating certificate syntax configuration........................... 100%
+ Updating JPEG syntax configuration.................................. 100%
+ Updating country string syntax configuration........................ 100%
+ Modifying filter in 'isMemberOf' virtual attribute configuration.... 100%
+ Updating dictionary password validator configuration................ 100%
+ Updating attribute value password validator configuration........... 100%
+ Adding PBKDF2 password storage scheme configuration................. 100%
+ Replacing schema file '02-config.ldif'.............................. 100%
+ Archiving concatenated schema....................................... 100%
+
+>>>> OpenDJ was successfully upgraded from version 2.4.6.8102 to <?eval ${docTargetVersion}?>.<replaceable>revision</replaceable>
+
+ * See '/path/to/opendj/upgrade.log' for a detailed log of this operation
+$ ./opendj/bin/start-ds --quiet
+$ </screen>
+
+ <para>Native packages (.deb, .rpm) perform more of the upgrade process,
+ stopping OpenDJ if it is running, overwriting older files with newer files,
+ running this utility, and starting OpenDJ if it was running when you upgraded
+ the package(s).</para>
</refsect1>
</refentry>
--
Gitblit v1.10.0