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/install-guide/chap-upgrade.xml | 316 +++++++++++++++++++++++++---------------------------
1 files changed, 150 insertions(+), 166 deletions(-)
diff --git a/opendj3/src/main/docbkx/install-guide/chap-upgrade.xml b/opendj3/src/main/docbkx/install-guide/chap-upgrade.xml
index 8048bc1..49dde97 100644
--- a/opendj3/src/main/docbkx/install-guide/chap-upgrade.xml
+++ b/opendj3/src/main/docbkx/install-guide/chap-upgrade.xml
@@ -20,7 +20,7 @@
!
! CCPL HEADER END
!
- ! Copyright 2011-2012 ForgeRock AS
+ ! Copyright 2011-2013 ForgeRock AS
!
-->
<chapter xml:id='chap-upgrade'
@@ -32,197 +32,181 @@
<title>Upgrading to OpenDJ <?eval ${docTargetVersion}?></title>
<indexterm><primary>Upgrading</primary></indexterm>
- <para>You can upgrade from an earlier version of OpenDJ either directly
- from within the Java WebStart installer, or on the command-line using the
- <command>upgrade</command> command.</para>
+ <para>This chapter covers upgrade from OpenDJ 2.4.5 and later versions.</para>
- <note>
- <para>Upgrade from OpenDS 2.2 or OpenDJ 2.4 has been tested most thoroughly
- on Solaris, Mac OS X, and Linux. On Windows systems, export directory data
- to LDIF, start with a fresh installation of the OpenDJ software, and then
- import your data from LDIF.</para>
- </note>
+ <para>For upgrades from earlier versions, upgrade first to OpenDJ
+ <?eval ${stableServerVersion}?>, and then follow the procedures in this
+ chapter. See <link xlink:show="new"
+ xlink:href="https://wikis.forgerock.org/confluence/display/OPENDJ/OpenDJ+Installation+Guide#OpenDJInstallationGuide-UpgradingOpenDJDirectoryServer"
+ >Upgrading OpenDJ Directory Server</link> in the OpenDJ Wiki for details on
+ upgrading to OpenDJ <?eval ${stableServerVersion}?> from earlier
+ versions.</para>
- <section xml:id="before-you-upgrade">
+ <procedure xml:id="before-you-upgrade">
<title>Before You Upgrade</title>
- <para>You must perform the upgrade procedure as the user who own the OpenDJ
- server. Make sure you have the credentials to run commands as the user who
- owns the server.</para>
+ <step>
+ <para>Prepare to perform the upgrade procedure as the user who owns the
+ OpenDJ server files. </para>
- <para>Do a full backup of your current OpenDJ installation.</para>
+ <para>Make sure you have the credentials to run commands as the user who
+ owns the server.</para>
+ </step>
- <para>When running a server version earlier than OpenDJ 2.4.1 fix the upgrade
- schema by following the appropriate steps depending on your platform.</para>
+ <step>
+ <xinclude:include href="../shared/itemizedlist-download.xml" />
+ </step>
- <para>(UNIX) Download and apply <link
- xlink:href='http://wikis.forgerock.org/confluence/download/attachments/11632664/opendj_patch4upgrade.sh'
- >opendj_patch4upgrade.sh</link> to your current server, by
- running the shell script from the directory where the server is installed.</para>
+ <step>
+ <para>In order to revert should the upgrade fail, make sure you perform a
+ full backup of your current OpenDJ installation.</para>
- <screen>$ cd /path/to/OpenDJ
-$ sh /downloads/opendj_patch4upgrade.sh
-/path/to/OpenDJ has been patched, you can proceed with the upgrade program now</screen>
+ <para>It might be most expedient to back up the file system directory where
+ the current OpenDJ server is installed as part of the upgrade process.</para>
- <para>The <filename>opendj_patch4upgrade.sh</filename> script fixes a schema
- issuethat prevents smooth upgrades from earlier server versions. You can
- apply the script while the server is running.</para>
+ <para>Alternatively, see <link xlink:href="admin-guide#chap-backup-restore"
+ xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
+ ><citetitle>Backing Up & Restoring Data</citetitle></link> for
+ instructions.</para>
+ </step>
+ </procedure>
- <para>(Windows) Follow these steps.</para>
- <orderedlist>
- <listitem>
- <para>With the <command>edit</command> command line tool, open and then save
- <filename>OpenDJ-old-version\config\upgrade\schema.ldif.<replaceable>####</replaceable></filename>
- where <replaceable>####</replaceable> represents four digits, such as 6677
- for 2.4.0.</para>
- <para>This step changes the line endings from UNIX to Windows format.</para>
- </listitem>
- <listitem>
- <para>Open the same file in Notepad.</para>
- </listitem>
- <listitem>
- <para>Add the following <literal>ldapSyntaxes</literal> definition verbatim,
- before the last blank line at the end of the file, leaving a blank line at
- the end of the file, and taking care not to add additional spaces at the end
- of the lines you add. <emphasis>If the result is not valid LDIF, your fix
- will fail.</emphasis></para>
- <literallayout class="monospaced">ldapSyntaxes: ( 1.3.6.1.4.1.26027.1.3.6 DESC '
- Collective Conflict Behavior' X-ENUM ( 'real-overrides-virtual' '
- virtual-overrides-real' 'merge-real-and-virtual' ) X-SCHEMA-FILE '
- 00-core.ldif' )</literallayout>
- <para>This fixes a schema issue that prevents upgrades from earlier
- server versions. You can make the change while the server is running.</para>
- </listitem>
- </orderedlist>
- </section>
+ <procedure xml:id="upgrade-zip">
+ <title>To Upgrade an OpenDJ Directory Server</title>
- <section xml:id="upgrade-servers">
- <title>Upgrading OpenDJ Servers</title>
+ <step>
+ <para>Login as the user who owns the current OpenDJ server.</para>
+ </step>
- <para>You can upgrade from the graphical installer, or from the command
- line.</para>
+ <step>
+ <para>Stop the current OpenDJ server.</para>
+ </step>
- <procedure xml:id="upgrade-gui">
- <title>To Upgrade From the Graphical Installer</title>
- <step>
- <para>Login to a session where you can use a GUI as the user who owns the
- current OpenDJ server.</para>
- </step>
+ <step performance="optional">
+ <para>If you have not already backed up the current OpenDJ server, make a
+ back up copy of the directory where OpenDJ is installed.</para>
+ </step>
- <step performance='optional'>
- <para><link xlink:href='http://www.forgerock.org/opendj.html'
- >Download OpenDJ</link>, and unzip the downloaded file.</para>
- </step>
+ <step performance="optional">
+ <para>If OpenDJ is currently installed in a directory such as
+ <filename>OpenDJ-2.4.6</filename>, you can change the directory name to
+ <filename>opendj</filename> to make it easier to unpack subsequent .zip
+ deliveries for future upgrades.</para>
+ </step>
- <step>
- <para>Start the installer.</para>
- <itemizedlist>
- <listitem>
- <para>(WebStart) <link>http://www.forgerock.org/downloads/opendj/<?eval
- ${docTargetVersion}?>/install/QuickSetup.jnlp</link></para>
- </listitem>
- <listitem>
- <para>(UNIX) Run <command>OpenDJ-<?eval
- ${docTargetVersion}?>/setup</command>.</para>
- </listitem>
- <listitem>
- <para>(Windows) Double-click <filename>OpenDJ-<?eval
- ${docTargetVersion}?>\setup.bat</filename></para>
- </listitem>
- </itemizedlist>
- </step>
+ <step>
+ <para>Unpack the new files from the .zip delivery over the current server
+ files.</para>
- <step>
- <para>In the OpenDJ QuickSetup Welcome screen, select Upgrade Existing
- Server Instance, and make sure Server to Upgrade points to the current
- OpenDJ server before clicking Next.</para>
- </step>
+ <para>If your directory is not named <filename>opendj</filename>, then
+ you can first unpack the files, then copy everything in the
+ <filename>opendj</filename> over the current server files.</para>
+ </step>
- <step>
- <para>Follow the instructions in the QuickSetup wizard to complete the
- upgrade.</para>
- </step>
+ <step>
+ <para>Run the <command>upgrade</command> command to bring OpenDJ
+ configuration and application data up to date with the new binary and
+ script files that you copied over the current server files.</para>
- <step>
- <para>If you upgraded from OpenDS 2.2, open the OpenDJ control panel,
- select Indexes > Rebuild Indexes..., and use the Rebuild Indexes dialog
- box to rebuild the <literal>dn2id</literal> index.</para>
- </step>
+ <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>
- <step>
- <para>If you upgraded from OpenDJ 2.4.4 or earlier, also rebuild the
- <literal>ds-sync-hist</literal> index before restarting OpenDJ.</para>
- </step>
- </procedure>
+ <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>
+ </step>
- <procedure xml:id="upgrade-cli">
- <title>To Upgrade On the Command Line</title>
+ <step>
+ <para>Start the upgraded OpenDJ server.</para>
- <step>
- <para>Login as the user who owns the current OpenDJ server.</para>
- </step>
+ <para>At this point the upgrade process is complete. See the resulting
+ <filename>upgrade.log</filename> file for a full list of operations
+ performed.</para>
+ </step>
+ </procedure>
- <step>
- <para>Download the OpenDJ .zip file.</para>
- <screen>$ cd /tmp
-$ wget http://www.forgerock.org/downloads/opendj/<?eval ${docTargetVersion}?>/OpenDJ-<?eval ${docTargetVersion}?>.zip</screen>
- </step>
- <step>
- <para>Change to the directory at the root of the server instance.</para>
- <screen>$ cd /path/to/OpenDJ</screen>
- </step>
- <step>
- <para>Pass the .zip file name to the <command>upgrade</command> command.</para>
- <screen>$ ./upgrade --file /tmp/OpenDJ-<?eval ${docTargetVersion}?>.zip
-See /var/....log for a detailed log of this operation.
+ <example xml:id="upgrade-zip-example"><?dbfo keep-together="auto"?>
+ <title>Upgrading From OpenDJ 2.4.6</title>
-Initializing Upgrade ..... Done.
-Calculating Schema Customizations ..... Done.
-Calculating Configuration Customizations ..... Done.
-Backing Up Files ..... Done.
-Upgrading Components ..... Done.
-Preparing Customizations ..... Done.
-Applying Schema Customizations ..... Done.
-Applying Configuration Customizations ..... Done.
-Verifying Upgrade ..... Done.
-Stopping Directory Server ..... 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:
-<replaceable>buildId</replaceable>).
+ <para>The following example upgrades an OpenDJ 2.4.6 directory server
+ installed in <filename>/path/to/OpenDJ-2.4.6</filename>, backing up the
+ current server directory in case the upgrade process fails, and changing
+ the directory name to <filename>/path/to/opendj</filename> to simplify
+ future upgrades.</para>
-See /var/....log for a detailed log of this operation.</screen>
- </step>
- <step>
- <para>If you upgraded from OpenDS 2.2, use the
- <command>rebuild-index</command> command to rebuild the
- <literal>dn2id</literal> index for your suffixes.</para>
+ <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
- <screen>$ ./bin/rebuild-index --index dn2id --baseDN "dc=example,dc=com"
-...Rebuild complete. Processed 160 entries in 0 seconds (average rate 401.0/sec)</screen>
- </step>
+>>>> OpenDJ Upgrade Utility
- <step>
- <para>If you upgraded from OpenDJ 2.4.4 or earlier, also rebuild the
- <literal>ds-sync-hist</literal> index before restarting OpenDJ.</para>
- </step>
- </procedure>
+ * 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
- <procedure xml:id="upgrade-repl">
- <title>To Upgrade Replicated Servers</title>
- <step>
- <para>Upgrade each server sequentially, as described above.</para>
- </step>
- </procedure>
+>>>> Preparing to upgrade
- <procedure xml:id="upgrade-dsml">
- <title>To Upgrade OpenDJ DSML Gateway</title>
- <step>
- <para>Replace the gateway web application with the newer version,
- as for a fresh installation.</para>
- </step>
- </procedure>
- </section>
+ 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>
+ </example>
+
+ <procedure xml:id="upgrade-repl">
+ <title>To Upgrade Replicated Servers</title>
+ <step>
+ <para>Upgrade each server sequentially, as described above.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="upgrade-dsml">
+ <title>To Upgrade OpenDJ DSML Gateway</title>
+ <step>
+ <para>Replace the gateway web application with the newer version,
+ as for a fresh installation.</para>
+ </step>
+ </procedure>
+
</chapter>
--
Gitblit v1.10.0