How do I upgrade Apache Tomcat for an existing AM (All versions) install?

Last updated May 10, 2022

The purpose of this article is to provide information on migrating an existing AM install to a new Apache Tomcat® version.

Background information

AM's configuration is located in the $HOME directory of the user running the web application container by default, which means it is separate to the Tomcat installation directory unless it's configured otherwise. However, any customizations you’ve made are located in the AM deployment path within the Tomcat directory /path/to/tomcat/webapps/openam (typically in the WEB-INF and XUI directories). The /openam directory referred to here and subsequent references to openam.war are based on a default installation; your directories and war file may have a different name if configured otherwise.

By default, there are two directories created in the user's home directory: the configuration is stored in the ~/openam/ directory and there is a hidden directory named ~/.openamcfg/. The hidden directory contains a file that represents the path to the directory where the openam.war file is deployed and is used when AM starts up to locate its configuration. For example, if your openam.war file is deployed in /opt/tomcat/webapps/openam, the file would be called AMConfig_opt_tomcat_webapps_openam_ This file contains the path to your configuration directory.

Caution

Depending on your version of Tomcat, the trailing underscore (_) at the end of the filename may or may not be needed. Versions 8.0.0 to 8.0.21 do not need the trailing underscore, whereas it is required in Tomcat 8.0.22 and later. See Bug 57556 (getServletContext().getRealPath("/") returns path not ending with /) for further information.

Supported versions

You should ensure the Tomcat version you are upgrading to is a supported container for your AM version:

Upgrading Tomcat

The recommended way to upgrade Tomcat for an existing install is as follows:

Install the new Tomcat version to create an upgraded Tomcat instance. See Apache Tomcat for further information.
Stop the Tomcat instance in which AM is currently running.
Copy the openam.war file and the /path/to/tomcat/webapps/openam directory from your existing deployment to the new Tomcat instance.
Navigate to the ~/.openamcfg/ directory: $ cd ~/.openamcfg/
Create a new AMconfig_ file using a filename that represents the path to the new location of the openam.war file. For example, if the new location is: /opt/newTomcat/webapps/openam, then you would name the file as follows: AMConfig_opt_newTomcat_webapps_openam_
Edit the new AMConfig_ file and add the path to your existing ~/openam configuration directory, for example: /home/userName/openam
Start the new Tomcat instance. Your existing AM install should now be available on the upgraded Tomcat.

Note

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.

Related Training

N/A

Related Issue Tracker IDs

N/A