Upgrading to OpenDJ 4.9

This chapter covers upgrade from previous versions.

If the OpenDJ directory server version is older than 2.6.0, you must upgrade your deployment to use at least OpenDJ directory server 2.6.0 before following the procedures in this chapter.

With the migration of OpenDJ project code from Subversion to Git, the upgrade code has changed to no longer rely on Subversion revision numbers.

As a result, upgrade from a nightly build is not guaranteed to work. Upgrade from one release to another works fine, as does upgrade from a release to a nightly build.

As a workaround, rather than upgrading from a nightly build, install a new server alongside the existing server and use replication to bring the new server up to date before retiring the older server.

This chapter includes the following procedures and examples:

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. (Optional) If OpenDJ directory server runs with Java 6, move to a newer version, at least Java 8, before continuing the upgrade process.

    To move to a newer version, edit the default.java-home setting in the opendj/config/java.properties file, and then run the dsjavaproperties command.

  3. Download the latest release from the GitHub site.

  4. (Optional) If you are upgrading OpenDJ directory server on Windows, and OpenDJ is registered as a Windows service, disable OpenDJ as a Windows service before upgrade, as in the following example:

    C:\path\to\opendj\bat> windows-service.bat --disableService

    After upgrade, you can enable OpenDJ as a Windows service again.

  5. Make sure you perform a full backup of your current OpenDJ installation to revert if the upgrade fails.

    Due to changes to the backup archive format, make sure you stop OpenDJ directory server and back up the file system directory where the current OpenDJ directory server is installed rather than creating a backup archive with the backup command.

To Upgrade to OpenDJ 4.9

Before starting this procedure, follow the steps in "Before You Upgrade".

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

OpenDJ directory server backend storage options have changed since OpenDJ 2.6. The underlying implementation is based on an extensible architecture, allowing you to choose the backend storage type when you create a persistent backend for directory data.

This procedure applies when you upgrade from OpenDJ 2.6, retaining the same underlying backend storage. The configuration changes from a Local DB backend to a JE Backend, and the upgrade procedure migrates the underlying backend database. There is no need to export data to LDIF when following this procedure.

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

  1. Log in as the user who owns the current OpenDJ server.

  2. Stop the current OpenDJ server.

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

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

  5. Run the upgrade command, described in upgrade(1) in the Reference, 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. For some potentially long-duration tasks, such as rebuilding indexes, the default choice is to defer the tasks until after upgrade. Tasks that are not performed during upgrade must generally be performed after upgrade but before you restart the server.

    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.

  6. 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.

    When you upgrade to OpenDJ 4.9 from an OpenDJ 3 or earlier, the upgrade procedure leaves the HTTP connection handler disabled. The newer configuration supports inheritance and subsresources, but is not compatible with the previous configuration. You must rewrite your configuration to the version described in "REST to LDAP Configuration" in the Reference, and then reconfigure the server to use the new configuration. For details, see "RESTful Client Access Over HTTP" in the Administration Guide.

  7. (Optional) If you are upgrading OpenDJ directory server on Windows, and you disabled OpenDJ as a Windows service in order to upgrade, enable OpenDJ as a Windows service again as in the following example:

    C:\path\to\opendj\bat> windows-service.bat --enableService
Upgrading to OpenDJ 4.9

The following example upgrades an OpenDJ 2.6.3 directory server, backing up the current server directory in case the upgrade process fails. In this example, the server properties are updated to use Java 8, and the Local DB backend is migrated to a JE backend:

$ cd /path/to/
$ sed -e "s/default.java-home=.*/default.java-home=\/path\/to\/jdk1.8/" \
 opendj/config/java.properties \
 > opendj/config/java.properties.new ; \
 mv opendj/config/java.properties.new opendj/config/java.properties
$ /path/to/opendj/bin/dsjavaproperties
$ /path/to/opendj/bin/stop-ds --quiet
... msg=The Directory Server is now stopped
$ zip -rq OpenDJ-backup.zip opendj/
$ unzip -o ~/Downloads/opendj-4.9.2.zip
$ /path/to/opendj/upgrade --acceptLicense

>>>> OpenDJ Upgrade Utility

 * OpenDJ will be upgraded from version 2.6.3.12667 to
 4.9.2.build-hash
 * See '/path/to/opendj/upgrade.log' for a detailed log of this operation

>>>> Preparing to upgrade

  OpenDJ 4.9.2 introduced changes to the JE backend configuration and database
  format. The upgrade will update all JE backend configurations, but will only
  migrate JE backend databases which are associated with *enabled* JE
  backends. It is very strongly recommended that any existing data has been
  backed up and that you have read the upgrade documentation before
  proceeding. Do you want to proceed with the upgrade? (yes/no) [no]: yes

  OpenDJ 4.9.2 changed the matching rule implementations. All indexes have to
  be rebuilt. This could take a long time to proceed. Do you want to launch
  this process automatically at the end of the upgrade? (yes/no) [no]: yes

  OpenDJ 4.9.2 improved the replication changelog storage format. As a
  consequence, the old changelog content of the current replication server
  will be erased by the upgrade. The new changelog content will be
  automatically reconstructed from the changelog of other replication servers
  in the topology. After the upgrade, dsreplication reset-change-number can be
  used to reset the changelog change-number of the current replication server
  to match another replication server. Do you want to proceed with the
  upgrade? (yes/no) [no]: yes

  The upgrade is ready to proceed. Do you wish to continue? (yes/no) [yes]:


>>>> Performing upgrade

  Changing matching rule for 'userCertificate' and 'caCertificate' to
  CertificateExactMatch...............................................   100%
  Configuring 'CertificateExactMatch' matching rule...................   100%
  Replacing schema file '03-pwpolicyextension.ldif'...................   100%
  Removing 'dc=replicationchanges' backend............................   100%
  Removing ACI for 'dc=replicationchanges'............................   100%
  Adding default privilege 'changelog-read' to all root DNs...........   100%
  Adding PKCS5S2 password storage scheme configuration................   100%
  Rerunning dsjavaproperties..........................................   100%
  Updating ds-cfg-java-class attribute in File-Based Debug Logger.....   100%
  Deleting ds-cfg-default-debug-level attribute in File-Based Debug
  Logger..............................................................   100%
  Updating ds-cfg-default-severity attribute in File-Based Error
  Logger..............................................................   100%
  Updating ds-cfg-override-severity attribute in Replication Repair
  Logger..............................................................   100%
  Removing config for 'Network Groups'................................   100%
  Removing config for 'Workflows'.....................................   100%
  Removing config for 'Workflow Elements'.............................   100%
  Removing config for 'Network Group Plugin'..........................   100%
  Removing config for 'Extensions'....................................   100%
  Removing config for 'File System Entry Cache'.......................   100%
  Removing config for 'Entry Cache Preload'...........................   100%
  Removing file '/path/to/opendj/bin/dsframework'.....................   100%
  Removing file '/path/to/opendj/bat/dsframework.bat'.................   100%
  Migrating JE backend 'userRoot'.....................................   100%
  Convert local DB backends to JE backends............................   100%
  Convert local DB indexes to backend indexes.........................   100%
  Convert local DB VLV indexes to backend VLV indexes.................   100%
  Removing file '/path/to/opendj/bin/dbtest'..........................   100%
  Removing file '/path/to/opendj/bat/dbtest.bat'......................   100%
  Removing content of changelog in '/path/to/opendj/./changelogDb'
  directory...........................................................   100%
  Enable log file based replication changelog storage.................   100%
  Replacing schema file '02-config.ldif'..............................   100%
  Archiving concatenated schema.......................................   100%

>>>> OpenDJ was successfully upgraded from version 2.6.3.12667 to
4.9.1.build-hash


>>>> Performing post upgrade tasks

...

>>>> Post upgrade tasks complete

 * See '/path/to/opendj/upgrade.log' for a detailed log of this operation

$ /path/to/opendj/bin/start-ds --quiet
$
To Upgrade Replicated Servers

The OpenDJ directory server upgrade process is designed to support a rolling (sequential) upgrade of replicated servers.

Do not upgrade all replicated servers at once in parallel, as this removes all replication changelog data simultaneously, breaking replication.

For each server in the replication topology, follow these steps:

  1. Direct client application traffic away from the server to upgrade.

  2. Upgrade the server as described above.

  3. Direct client application traffic back to the upgraded server.

To Add a New Replica to an Existing Topology

Newer OpenDJ servers have updates to LDAP schema that enable support for some new features. The newer schemas are not all compatible with older servers.

When adding a new server to a replication topology with older servers and following the instructions in "Enabling Replication" in the Administration Guide, also follow these recommendations:

  1. Enable replication using the dsreplication command delivered with the new server.

  2. Use the --noSchemaReplication or the --useSecondServerAsSchemaSource option to avoid copying the newer schema to the older server.

    It is acceptable to copy the older schema to the newer server, though it prevents use of new features that depend on newer schema.

  3. If some applications depend on Internet-Draft change numbers, see "To Align Draft Change Numbers" in the Administration Guide.

To Upgrade OpenDJ REST to LDAP Gateway

  1. Rewrite your configuration to work with the new formats described in "REST to LDAP Configuration" in the Reference.

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

To Upgrade OpenDJ DSML Gateway

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