FAQ: Upgrading AM
The purpose of this FAQ is to provide answers to commonly asked questions regarding upgrading AM.
3 readers recommend this article
Frequently asked questions
- Q. How can I find everything that has been fixed in a release?
- Q. Where can I find end of support life (EOSL) dates for AM?
- Q. Where can I find AM upgrade instructions and best practices?
- Q. How do I debug issues when I am upgrading AM?
- Q. How do I find the hardware and software requirements for the new release?
- Q. Does upgrading the Apache Tomcat™ web application container affect my AM deployment?
- Q. Do I need to upgrade the embedded DS when I upgrade AM?
- Q. Do I need to upgrade Amster when I upgrade AM?
- Q. Do I need to upgrade the ssoadm administration tool when I upgrade AM?
- Q. How can I retain AM customizations when I upgrade?
- Q. What is the best approach to upgrading if I am using Site configuration?
- Q. How can I upgrade AM without using the AM admin UI?
Q. How can I find everything that has been fixed in a release?
A. The release notes list all the key fixes that have been included as well as any known issues that are still outstanding at the time of the release:
- AM 7.2 Release notes
- AM 7.1 Release Notes
- AM 7 Release Notes
- AM 6.5 Release Notes
- AM 6 Release Notes
Q. Where can I find end of support life (EOSL) dates for AM?
A. The release dates and end of support life dates for AM are available from: ForgeRock End of Service Life (EOSL) Policy and EOSL Dates | AM, DS and IDM
Q. Where can I find AM upgrade instructions and best practices?
A. The Upgrade documentation provides planning, best practices and instructions for performing your upgrade and covers common aspects of upgrading an AM 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 AM release.
You should also consult the following articles / specific sections for further information on planning and best practices for upgrades:
Q. How do I debug issues when I am upgrading AM?
A. There are a couple of files that are useful for debugging the upgrade process:
- The Upgrade report (called upgradereport.yyyymmddhhmmss) logs the upgrade details shown in the browser during the upgrade process and is located in the /path/to/am/upgrade directory.
- The amUpgrade debug log is generated if any errors are encountered during the upgrade process and is located in the /path/to/am/var/debug directory (AM 7 and later) or the /path/to/am/debug directory (AM 6.x).
You can also enable Message level debugging in the web application container as described in How do I enable message level debugging for install and upgrade issues with AM (All versions)?
Q. How do I find the hardware and software requirements for the new release?
A. Before upgrading, you should read the Before You Install section in the release notes applicable to the release you are upgrading to.
See Before You Install for further information on AM 7.2.
Q. Does upgrading the Apache Tomcat web application container affect my AM deployment?
A. No, it is possible to upgrade Tomcat and retain your existing AM deployment. See How do I upgrade Apache Tomcat for an existing AM (All versions) install? for further information.
Tomcat 8.5 and later enforces stricter checking for valid cookie domain values; this change prevents the login page loading and causes ssoadm to fail. The necessary steps to resolve this are documented in the following Solution article: Login page does not load or ssoadm fails in AM (All versions) running on Apache Tomcat 8.5 or 9
Q. Do I need to upgrade the embedded DS when I upgrade AM?
Q. Do I need to upgrade Amster when I upgrade AM?
A. Yes, you should always upgrade Amster to the corresponding version when you upgrade AM.
Q. Do I need to upgrade the ssoadm administration tool when I upgrade AM?
A. Yes you do; you must ensure you are running the compatible version of the ssoadm administration tool. The ssoadm administration tool is not automatically upgraded when you upgrade AM and must be done separately.
See Set up administration tools for further information.
Q. How can I retain AM customizations when I upgrade?
A. You can retain customizations by preparing a war file containing any customizations you require as described in Customize before upgrading.
Alternatively, you can use the Maven overlay functionality, which enables you to replace standard implementations with your customizations during the build process.
See Maven war plugin - overlays for further information.
Q. What is the best approach to upgrading if I am using Site configuration?
A. If you are using a Site configuration with multiple servers, it is recommended that you upgrade as follows:
- AM 7 and later - Route client application traffic to another site during the upgrade. See Upgrade from a supported version for further information.
- AM 6.x - Temporarily split your site into two prior to upgrading and then upgrade per the steps in How do I upgrade AM 6.x if I am using a site configuration?
Q. How can I upgrade AM without using the AM admin UI?
A. You can use the upgrade.jar tool (openam-upgrade-tool-18.104.22.168.jar for AM 7.2) to upgrade AM using a configuration file. This tool allows you to easily perform a silent, unattended upgrade and can be included in scripts to automate the upgrade process if required.
The upgrade.jar tool is included in AM but is not installed by default.
See Set up the configuration tools for an overview of the process. The most important part is creating a valid config.file as this is used for the actual upgrade. A sampleupgrade file is included when you install the configuration tools, which you should use as the basis of your configuration file; the properties that can be set within this file are described in upgrade.jar.
If you want to make configuration changes to your upgraded server, you can do this using the configurator.jar tool, which is described in more detail in FAQ: Configuring AM
You cannot import a Service configuration that was created in a different version of AM using ssoadm. This is possible with Amster; for example, you can export a configuration from AM 6.5 and import it into AM 7.
How do I upgrade AM (All versions) with minimal downtime when replication is used?
FAQ: AM compatibility with third-party products
FAQ: AM performance and tuning