Chapter 4. Upgrading to OpenDJ 4.8.1-SNAPSHOT

This chapter covers upgrade from OpenDJ 2.4.5 and later versions.

For upgrades from earlier versions, upgrade first to at least OpenDJ 2.4.5, and then follow the procedures in this chapter. See Upgrading OpenDJ Directory Server in the OpenDJ Wiki for details on upgrading to OpenDJ 2.4.5 from earlier versions.

Procedure 4.1. Before You Upgrade

  1. Prepare to perform the upgrade procedure as the user who owns the OpenDJ server files.

    Make sure you have the credentials to run commands as the user who owns the server.

  2. Download OpenDJ software from one of the following locations.

    • The ForgeRock Enterprise Downloads page has the latest stable, supported release of OpenDJ and the other products in the ForgeRock identity stack.

    • The Nightly Builds page posts links to the latest nightly builds of OpenDJ software. Note that these builds are the working version from the trunk and are not for use in a production environment.

    • The Community Archives page includes stable community builds for previous releases of OpenDJ software.

  3. In order to revert if the upgrade fails, make sure you perform a full backup of your current OpenDJ installation.

    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.

    Alternatively, see Backing Up & Restoring Data for instructions.

Procedure 4.2. To Upgrade an OpenDJ Directory Server

To upgrade OpenDJ directory server installed from native packages (.deb, .rpm), use the command-line package management tools provided by the system.

The following steps describe how to upgrade OpenDJ directory server installed from the cross-platform (.zip) delivery.

  1. Login as the user who owns the current OpenDJ server.

  2. Stop the current OpenDJ server.

  3. If you have not already backed up the current OpenDJ server, make a back up copy of the directory where OpenDJ is installed.

  4. If OpenDJ is currently installed in a directory such as OpenDJ-2.4.5, you can change the directory name to opendj to make it easier to unpack subsequent .zip deliveries for future upgrades.

  5. Unpack the new files from the .zip delivery over the current server files.

    If your directory is not named opendj, then you can first unpack the files, then copy everything in the opendj over the current server files.

  6. Run the upgrade 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.

    By default, the upgrade command requests confirmation before making important configuration changes. You can use the --no-prompt option to run the command non-interactively, with the --acceptLicense option to accept the license terms non-interactively.

    When using the --no-prompt option, if the upgrade 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 --force option to force a non-interactive upgrade to continue in this case, also performing long running and critical tasks.

  7. When you upgrade from OpenDJ 2.5.0-Xpress1, you must rebuild the ds-sync-hist ordering index before you restart the server, as indicated in the message from the upgrade tool. 

      OpenDJ 2.5.0-Xpress1 introduced a regression in the ds-sync-hist ordering
  index. This index must be rebuilt after the upgrade has completed and before
  restarting OpenDJ. Do you wish to continue? (yes/no) [no]: yes

    To rebuild the index, use the rebuild-index command after upgrade but before starting the server as in the following example. 

    $ ./opendj/bin/rebuild-index --baseDN dc=example,dc=com --index ds-sync-hist
... msg=Rebuild of index(es) ds-sync-hist started ...
... msg=Rebuild complete. Processed XXX entries in YYY seconds...

  8. Start the upgraded OpenDJ server.

    At this point the upgrade process is complete. See the resulting upgrade.log file for a full list of operations performed.

Example 4.1. Upgrading From OpenDJ 2.4.5

The following example upgrades an OpenDJ 2.4.5 directory server installed in /path/to/OpenDJ-2.4.5, backing up the current server directory in case the upgrade process fails, and changing the directory name to /path/to/opendj to simplify future upgrades. 

$ cd /path/to
$ ls
OpenDJ-2.4.5
$ ./OpenDJ-2.4.5/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.5
$ unzip -q ~/Downloads/OpenDJ-2.6.0.zip
$ cp -r opendj/* OpenDJ-2.4.5/
$ rm -rf opendj
$ mv OpenDJ-2.4.5 opendj
$ ./opendj/upgrade --no-prompt --acceptLicense

>>>> OpenDJ Upgrade Utility

 * OpenDJ will be upgraded from version 2.4.5.7743 to 2.6.0.9086
 * See '/path/to/opendj/upgrade.log' for a detailed log of this operation

READ THIS SOFTWARE LICENSE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING
THE FORGEROCK SOFTWARE, YOU, ON BEHALF OF YOURSELF AND YOUR COMPANY, AGREE TO
BE BOUND BY THIS SOFTWARE LICENSE AGREEMENT. IF YOU DO NOT AGREE TO THESE
TERMS, DO NOT DOWNLOAD OR INSTALL THE FORGEROCK SOFTWARE.

 ...

Please read the License Agreement above.
You must accept the terms of the agreement before continuing with the
installation
Do you accept the License Agreement? yes

>>>> Preparing to upgrade

  OpenDJ 2.5.0 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%
  Rename SNMP security config file....................................   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%
  Adding 'http-config.json' configuration file........................   100%
  Adding HTTP connection handler configuration........................   100%
  Adding file-based HTTP access logger................................   100%
  Adding 'emailAddress' attribute.....................................   100%
  Updating subject attribute to user attribute configuration..........   100%
  Replacing schema file '02-config.ldif'..............................   100%
  Archiving concatenated schema.......................................   100%

>>>> OpenDJ was successfully upgraded from version 2.4.5.7743 to 2.6.0.9086

 * See '/path/to/opendj/upgrade.log' for a detailed log of this operation
$ ./opendj/bin/start-ds --quiet
$

Procedure 4.3. To Upgrade Replicated Servers

  • Upgrade each server sequentially, as described above.

Procedure 4.4. To Upgrade OpenDJ DSML Gateway

  • Replace the gateway web application with the newer version, as for a fresh installation.