Apache Tomcat upgrade troubleshooting

Authors: UpgradeTroubleshootingTeam
Build basis: CLM 3.x and later

This page is the starting point for information and techniques to help diagnose and troubleshoot Apache Tomcat upgrade issues.

Before upgrading

• Review the Known Issues from the Apache Tomcat documentation, and evaluate them for impact in your environment
• Review the System Requirements to ensure you are upgrading to a supported version of Tomcat Application Server by CLM.
• Perform the upgrade in a test environment prior to upgrading your production environment

Performing the upgrade

Technote 1448666: How to upgrade Tomcat bundle with Rational Jazz Team Server describes the necessary steps required to perform the upgrade of Apache Tomcat application server for use with CLM applications.

Upgrading the JRE contained in Tomcat

Technote 1655852: How to update the JRE of CLM 4.0.5 Tomcat Deployments describes the necessary steps required to perform a JRE upgrade within Apache Tomcat.

Upgrade Verification

To verify the upgrade was successful, follow steps 10-12 on Technote 1448666: How to upgrade Tomcat bundle with Rational Jazz Team Server.

If you are unable to perform any of the steps listed, review your catalina.log file located in ../tomcat/logs for related errors.

Issues during verification testing after upgrade

Windows Service fails to start Tomcat

You will need to reconfigure the service for your new instance of Tomcat. See Configuring Apache Tomcat Server to run as a Windows Service.

Application will not start

• Check that the application WAR file has correctly deployed.

In the ../tomcat/webapps directory, you should see your application WAR files, such as 'ccm.war'. During startup, this should have extracted into a 'ccm' folder. If this folder does not exist, the WAR file may not have deployed.

• Check that you have enough disk space for the WAR file to deploy, and the user running the startup has permissions to write to this directory

Users unable to login

Symptom: After upgrading your CLM install, users are unable to login to CLM. The following error may occur

 This user was not found in the directory service. This user will not be able to login unless they have an account in the directory service.ID CRJAZ1532I 

Environment: CLM deployed on Apache Tomcat, using local file based authentication (tomcat-users.xml)
Cause: The file write behaviour for the tomcat-users.xml file was changed between Tomcat 5.5 (RTC 3.x) and Tomcat 7 (RTC 4.x)
Resolution: See Technote 1614661: Tomcat-users.xml is file not updated after Upgrade

Where do I go from here?

If you are unable to resolve your issue using the available online resources, open a service request with IBM Rational Support. Refer to Additional troubleshooting resources for further details.

Related topics: None

External links:

• None

Additional contributors: StephanieBagot