This chapter covers common aspects of upgrading an OpenAM deployment, whether you are moving to a new maintenance release, upgrading to a new major release, or migrating from a legacy release to a newer OpenAM release.
Release levels, and how much change to expect in a maintenance, minor, or major release, are defined in the Administration Guide section, ForgeRock Product Release Levels. Release levels are identified by version number.
How much you must do to upgrade OpenAM software depends on the magnitude of the differences between the version you currently use and the new version.
Maintenance releases have a limited effect on current functionality but contain necessary bug and security fixes. You should keep up to date with maintenance releases as the fixes are important and the risk of affecting service is minimal.
When upgrading to a new major or minor release, always plan and test the changes before carrying out the upgrade in production. Make sure you read release notes for intervening versions with care, identifying any changes likely to affect your deployment, and then plan accordingly.
These suggestions are true both for OpenAM server components, and also for policy agents.
To upgrade from OpenAM server 9.5 and later you can use the Upgrade Wizard. The OpenAM server Upgrade Wizard, added in OpenAM 10.0.0, appears when you replace a deployed OpenAM server .war with a newer version and browse to the deployment URL. The Upgrade Wizard brings the OpenAM configuration, including the version number, up to date with the new version. The CLI counterpart of the Upgrade Wizard is , which you install as described in To Set Up Configuration Tools.
For legacy releases, meaning OpenAM server version 9.0 and earlier including Sun Access Manager and OpenSSO releases, you must reinstall and configure OpenAM server rather than upgrade. Moving to a new release from a legacy release is therefore a migration, rather than a simple upgrade.
Be prepared before you begin an upgrade, even if the upgrade is for a maintenance release.
Upgrading servers takes at least one of your OpenAM sites down while the server configurations are being brought up to date with the newer version. Plan for this site to be down, routing client applications to another site until the upgrade process is complete and you have validated the result. Make sure client application owners are well aware of the change, and let them know what to expect.
If you only have a single OpenAM site, make sure the downtime happens in a low usage window, and make sure you let client application owners plan accordingly.
During an upgrade you must restrict access to OpenAM Console: The Upgrade Wizard page does not require authorization; any user with access to OpenAM Console immediately after you deploy the new .war can therefore initiate the upgrade process.
Always back up your deployment before you upgrade, as you must be able to roll back should something go wrong during the upgrade process.
Backing up your configuration as described in Backing Up and Restoring OpenAM Configurations is good for production environments.
In preparation for upgrading OpenAM servers and their configurations, also take LDIF backups of the configuration store data in the directory servers. If possible, stop servers before upgrading and take a file system backup of the deployed servers and also of their configuration directories as well. This can make it easier to roll back from a failed upgrade.
For example, if you deploy OpenAM server in Apache Tomcat under
/openam, you might take a file system backup of the
following directories for each OpenAM server.
/path/to/tomcat/webapps/openam/
~/openam/
~/.openamcfg/
When upgrading web policy agents, take a file system backup of the policy agent installation and configuration directories.
When upgrading Java EE policy agents, it can be easier to uninstall the new version and reinstall the old version than to restore from file system backup.
When upgrading tools, keep copies of any tools scripts that you have edited for your deployment. Also back up any trust stores used to connect securely.
Before you upgrade OpenAM servers, prepare a .war file that contains any customizations you require.
Customizations include any changes you have made to the OpenAM server installation, such as the following.
Plugin and extensions such as custom authentication modules, response providers, post authentication plugins, SAML 2.0 attribute mappers, and OAuth 2.0 scope implementations
These are described in the Developer's Guide.
Customized JSPs, redesigned login or service pages, additional CSS and visual content, and modified authentication module callback files
These are described in the Installation Guide.
Any changes to OpenAM classes
Any changes or additional Java class libraries (such as .jar files
in WEB-INF/lib
Sometimes even a well-planned upgrade operation fails to go smoothly. In such cases, you need a plan to roll back smoothly to the pre-upgrade version.
For OpenAM servers, you can roll back by restoring from file system backup. If you use an external configuration directory service, restore the old configuration from LDIF before restarting the old servers.
For web policy agents, you can roll back by restoring from file system backup. If you used configuration only available to newer agents, restore the pre-upgrade configuration before restarting the old agents.
For Java EE policy agents, uninstall the newer agents and reinstall the older agents, including the old configurations.