This article has been archived and is no longer maintained by ForgeRock.
Before performing this upgrade, you should read the Release Notes and Upgrade Guide applicable to the new release to improve your understanding of the upgrade process. In particular, you should refer to these sections (links provided for OpenAM 13):
- OpenAM 13 Release Notes - Important Changes to Existing Functionality
- OpenAM 13 Upgrade Guide - Best Practices for Upgrades
- OpenAM 13 Supported Upgrades - Supported Upgrade Paths
If you are upgrading to OpenAM 13, you must ensure you are running the correct version of Java as per Java Requirements; OpenAM 13 does not function with Java 6.
You should also be aware of the following important changes that will occur as a result of this upgrade:
- The token store between OpenAM 10.x and later releases is not compatible. If session persistence is in use, these sessions will be lost and users will need to re-authenticate when they next access the service.
- There is a significant OpenDJ upgrade included. This upgrade occurs automatically during the first initialization of the new WAR file, not during the upgrade wizard.
This is the simplest and safest method of upgrading. Use when you are able to have a downtime maintenance window where the service is inoperable. For a more advanced procedure with higher availability, please see the related articles linked below.
Where the term 'load balancer' is used, this simply means whichever balancing mechanism is used in the particular deployment. For example, physical/virtual load balancers, DNS round robin, reverse proxy etc.
As per the Upgrade Guide, you will need to take a LDIF backup of the configuration data store in the directory servers as well as a file system backup.
You will need to take copies of:
- The OpenAM instance directory (default ~/openam) while OpenAM is not running.
- The web container with the deployed OpenAM, for example, /path/to/tomcat/webapps/openam for Apache Tomcat™.
- The $HOME/.openamcfg/ directory of the user running the web application container where OpenAM is deployed.
Since OpenAM needs to be stopped to take the instance directory backup, the best time to take this is just after bringing down the instance. This also ensures the configuration is as up to date as possible.
- Disable all OpenAM instances from the load balancer. You can optionally set to show maintenance placeholder page if desired.
- Shut down all OpenAM servers.
- Take a backup on the first OpenAM instance, replace the WAR file and start the instance.
- Run through the OpenAM upgrade wizard.
If you are upgrading from OpenAM 10.1.0 Xpress, you must update the Dashboard service LDAP schema to complete the upgrade. This is detailed in the OpenAM Upgrade Guide › Upgrading OpenAM Servers › To Complete Upgrade from OpenAM 10.1.0 Xpress.
- Restart OpenAM and check for any issues with normal/expected operation. You can optionally bring this OpenAM instance back online straight away via your load balancer and observe normal operations.
- Take a backup of subsequent OpenAM instances in turn, replace the WAR file and start each one.
- Check the normal operation and replication status of the new installation. You can optionally re-add instances to the load balancer as desired or wait until all instances are upgraded and checked before re-adding them all at once.