mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git
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>
