How do I upgrade from OpenIDM 2.x to OpenIDM 3.x?

Last updated Jan 5, 2021

The purpose of this article is to provide information on upgrading from OpenIDM 2.x to OpenIDM 3.x directly, without needing to do a two stage upgrade (OpenIDM 2.x to 3.0, then OpenIDM 3.0 to 3.x).

Archived

This article has been archived and is no longer maintained by ForgeRock.

Upgrading from OpenIDM 2.x to OpenIDM 3.x

To upgrade from OpenIDM 2.x to OpenIDM 3.x directly, you need to ensure you have taken account of all the changes that have occurred in OpenIDM 3.0 and OpenIDM 3.x, as outlined in the install guides:

Note

Prior to upgrading OpenIDM, you should also read the OpenIDM Release Notes relevant to the target release and all interim releases. In particular, you should check the relevant OpenIDM Compatibility section to ascertain if your existing customizations will continue to work; this is especially important for any script changes you have made.

The general process for upgrading from OpenIDM 2.x to OpenIDM 3.x is as follows, but you should consult the install guides for further information as needed, as your upgrade is likely to be more complex if you have many customizations to migrate:

Download the OpenIDM 3.x zip file from BackStage and extract the file.
Stop the OpenIDM 2.x server if it is running.
Back up your OpenIDM 2.x deployment by zipping up the entire openidm/ directory.
Update the boot.properties file on the OpenIDM 3.x server (located in the /path/to/openidm3.x/conf/boot directory) to include any customizations you made to the same file on the OpenIDM 2.x server. Specifically you should check the following:
- Ensure the HTTP, HTTPS and mutual authentication ports are specified in the boot.properties file if you changed the default ports in your 2.x deployment; these ports were specified in the jetty.xml file (located in the /path/to/openidm2.x/conf directory) in OpenIDM 2.x but moved to the boot.properties file in OpenIDM 3.x.
- Check that the keystore and truststore passwords match the current passwords for the keystore and truststore of your OpenIDM 2.x deployment.
- Set the following properties if your new OpenIDM 3.x deployment is going to run in a cluster; certain cluster properties are now specified in the boot.properties file: openidm.node.id openidm.instance.type openidm.scheduler.execute.persistent.schedules
Update the new cluster.json file (located in the /path/to/openidm3.x/conf directory) if your new OpenIDM 3.x deployment is going to run in a cluster; the timeout and checkin settings that were previously defined in the scheduler.json file (located in the /path/to/openidm2.x/conf directory) are now defined in the new cluster.json file.
Copy the contents of your /path/to/openidm2.x/security folder to your new OpenIDM 3.x deployment. You will also need to update the boot.properties file to point to the relative location of your keystore.jceks and truststore security files.
Merge all customizations from OpenIDM 2.x to 3.x. The affected files will vary according to the customizations you have made, but you should specifically check the following files in the /path/to/openidm/conf directory:
- all provisioner configuration files
- managed.json
- repo.jdbc.json
- sync.json
Migrate any modified or custom scripts (contained in the /path/to/openidm/script directory) from OpenIDM 2.x to 3.x.
Migrate all your required data; this includes internal user data, managed objects, and reconciliation and audit data.
Update the allowedAuthenticationIdPatterns for the CLIENT_CERT authentication module in authentication.json as follows if you are using the OpenDJ self-signed certificate in your truststore: { "name" : "CLIENT_CERT", "properties" : { "queryOnResource" : "security/truststore", "defaultUserRoles" : [ "openidm-cert" ], "allowedAuthenticationIdPatterns" : [ "CN=localhost, O=OpenDJ Self-Signed Certificate" ] }, "enabled" : true } You will need to change this value if you are using a certificate that has been issued by a Certificate Authority.

Related Training

N/A

Related Issue Tracker IDs

N/A

Archived

Upgrading from OpenIDM 2.x to OpenIDM 3.x

Note

See Also

Related Training

Related Issue Tracker IDs