How to upgrade Apache Tomcat version used by Jira

Still need help?

The Atlassian Community is here for you.

Ask the community

Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.

Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

The information in this page relates to customizations in Jira. Consequently, Atlassian Support cannot guarantee to provide any support for the steps described on this page as customizations are not covered under Atlassian Support Offerings. Please be aware that this material is provided for your information only and that you use it at your own risk.

Also, please be aware that customizations done by directly modifying files are not included in the upgrade process. These modifications will need to be reapplied manually on the upgraded instance.

Jira 8.20.x, 9.4.x and 9.12.x (tested versions) are NOT compatible with Tomcat 10.0.x or newer.

Jira is also tested and supported only in the bundled versions of Tomcat with each release: Bundled Tomcat and Java versions. I.e. Jira 8 is not supported on Tomcat 9 and Jira 9 is not supported on Tomcat 8.

This KB is valid for Jira 8 and Jira 9 branches. It was not tested for previous Jira versions.


Summary

This article is exclusively for users who are using the latest Jira version and encounter security vulnerabilities in Apache Tomcat.

If you are not using the latest Jira version, we recommend upgrading Jira to the latest version before considering the steps below.

Environment

Any installation of Jira Software or Jira Service Management, Data Center or Server on the latest release available.

Solution

It is strongly recommended to validate the process below in a Jira test environment, and make sure everything is working and stable before applying it to production.

  1. Take a backup of your Jira environment.
  2. Shut down Jira.

  3. Download the desired Apache Tomcat version's zip file to a location of your choosing and unpack it. 
    • If you're using 64-bit Windows, please ensure that you download the "windows-x64" zip, and if you're using 32-bit Windows please download the "windows-x86" zip. This will ensure that you have the correct Windows binaries.
  4. Copy everything from tomcat/bin to jira-install/bin, but do not replace any *.sh or *.bat files - we want to make sure these stay the same.
  5. Copy everything from tomcat/lib to jira-install/lib and replace any files that exist - we want to ensure that we have the latest and compatible libraries that are shipped with Tomcat.
  6. If going to Tomcat 8.5.32 or newer, perform the server.xml change described in Changing server.xml to handle requests with special characters
  7. Start Jira, and confirm from System Information that Jira is running the desired Apache Tomcat version.

If upgrading to Tomcat 8.5.51 or higher and using an AJP connector, you need to include the secret attribute in the AJP connector configuration or disable this requirement by specifying secretRequired="false" (not recommended), as instructed in the Tomcat changelog. Failing to do this will prevent Tomcat from starting with the error below:

 The AJP Connector is configured with secretRequired="true" but the secret attribute is either null or "". This combination is not valid.

 If anything goes wrong with the above process, please use the backup taken in Step 1 to revert the changes made.



DescriptionThis article is mainly for users who are using the latest JIRA version and encounter security vulnerability from Apache Tomcat. If you are not using our latest JIRA version, please upgrade JIRA to have the latest fix instead of referring to the steps here.
ProductJira
PlatformServer
Last modified on Mar 25, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.