Migrate your configuration

This chapter covers the steps required to migrate your IDM configuration to IDM 8.

There is no automated way to migrate a customized configuration to IDM 8, so you must migrate customized configuration files manually. If you’re upgrading from IDM 7.5.x, there are three ways to do this:

Use the new IDM 8 configuration files as a base, and copy any customizations you have made to the new files.

This is the preferred option, particularly if you have used version control on your configuration and can determine the exact changes you have applied.
Use your existing configuration files as a base, and add any new IDM 8 configuration to your existing files.
Use your existing configuration as is with no IDM 8 changes.

Usually, a customized IDM 7.5.x configuration will work without further modification on IDM 8.

Migrate configuration files

For customized files in your project’s conf/ directory, check that the customizations are compatible with the changes outlined in Incompatible changes. If there are no incompatible changes, either copy your old configuration files to your IDM 8 installation, or copy any customization into the corresponding new configuration files.

If you create custom configuration files, don’t use spaces or special characters in the filenames, in accordance with the OSGi specification.

Migrate `boot.properties`

On the IDM 8 installation, edit the resolver/boot.properties file to match any customizations that you made on your IDM 7.5.x server. Specifically, check the following elements:

The HTTP, HTTPS, and mutual authentication ports.

If you changed the default ports in your IDM 7.5.x deployment, make those same changes in the new boot.properties file.
Check that the keystore and truststore passwords match the current passwords for the keystore and truststore of your existing IDM deployment.

Migrate security settings

Copy the contents of your IDM 7.5.x security/ folder to the IDM 8 installation.

If you don’t copy your old truststore and keystore files to your new instance, you cannot decrypt anything that was encrypted by your old instance of IDM.

Migrate custom scripts

Migrate any custom scripts or default scripts that you have modified to the script directory of your IDM 8 instance. In general, custom and customized scripts should be located in the openidm/script directory of your existing IDM deployment.

For custom scripts, review Incompatible changes. If you’re confident that the scripts will work as intended on IDM 8, copy these scripts to the new instance.

If you modified a default IDM script, compare the default versions of the IDM 7.5.x and IDM 8 scripts. If nothing has changed between the default versions, review your customizations against Incompatible changes. If a default script has changed since the IDM 7.5.x release, test that your customizations work with the new default script. If you are confident that your changes will work as intended on the new version, copy the customized scripts to the new script directory.

If you modify any shell scripts, such as startup.sh, you must migrate your changes manually to the new version of the script.

Migrate custom bundles

If your existing deployment includes any custom JAR files in the bundles directory, migrate these to the new deployment. Pay particular attention to any files that support JDBC database drivers.

Migrate provisioner files

Change any customized provisioner configurations in your existing deployment to point to the connectors that are provided with IDM 8. Specifically, make sure that the connectorRef properties reflect the new connector versions, where applicable. For example:

"connectorRef" : {
    "bundleName": "org.forgerock.openicf.connectors.ldap-connector",
    "bundleVersion": "[1.4.0.0,1.6.0.0)",
    "connectorName": "org.identityconnectors.ldap.LdapConnector"
},

Alternatively, copy the connector .jar files from your existing deployment into the openidm/connectors directory of the new installation.

Migrate UI customizations

If you have customized the admin UI, review any custom UI files from your IDM 7.5.x deployment (generally in the openidm/ui/admin/extension directory), and compare them against the corresponding IDM 8 files.

For each customized file, copy the corresponding default IDM 8 UI files to a openidm/ui/admin/extension directory on the new instance.

Apply your customizations to files in the new openidm/ui/admin/extension directory.

Migrate logging functionality

For customized logging behavior in your project, check that the customizations are compatible with the changes outlined in Server logs. Update your conf/logback.xml file with any necessary changes.

If you want to preserve the JUL style logs, learn more in pattern layout encoder.

Migrate Jetty configuration files

In IDM 8.0, jetty.xml is no longer supported.

When serving SSL requests, Jetty 12 checks that the incoming host header matches the server certificate’s subject and returns a 400 Bad Request error on a mismatch. If you’re upgrading to IDM 8.0, you must ensure your IDM server certificate subject matches the host name used by your deployment.

Learn more in Jetty 12 support.

If you haven’t modified your jetty.xml configuration file, you don’t need to make changes for Jetty 12 because the current configuration replicates the jetty.xml default settings. However, if you’ve made changes, you might need to adjust the webserver.listener-*json files as needed.

For example, the webserver.listener-mutualAuth.json file duplicates the 8444 port configuration in jetty.xml. You can enable mutual authentication on any listener by setting the secure and mutualAuth flags to true.

Learn more in Embedded Jetty configuration and in Secure network connections.

PingIDM