Table of Contents
There are some topics not covered by this basic upgrade guide.
The Apache Tomcat project does not provide patches. If a feature, bug-fix, or security patch is announced in a specific version of Tomcat, then you must upgrade to that version. You may be able to get patches from your OS vendor or other technical-support organization, but the Apache Tomcat project will not supply such patches.
Upgrading Apache Tomcat being used in an embdded environment is not covered in this documentation. It is assumed that if you are using Apache Tomcat in an embdded environment, then you have the knowledge necessary to perform an upgrade without introductory documentation as is provided, here.
Upgrades can be separated into two different kinds of upgrades: upgrades between major versions (e.g. from 9.0 to 10.0) – known as a "major upgrade", and upgrades within a single version (e.g. 9.0.45 to 9.0.85) – known as a "minor upgrade". The steps to follow are different for each type of upgrade.
When upgrading between major versions of Tomcat (e.g. 9.0 to 10.0), it is best to start with a stock installation of Tomcat, then and adapt the new configuration files to meet your needs, add your applications, etc.
Read the Migration Guide
You should read the migration guide(s) that are relevant to your particular upgrade page. If you are upgrading from Apache Tomcat 9.0 to Apache Tomcat 10.0, you should read the "Tomcat 10.0 Migration Guide" which covers everything that applies for upgrading from the previous version.
If you are upgrading past several versions at once, you should read all the migration guides in between. For example, if you are upgrading from Tomcat 8.5 to Tomcat 10.1, you should read the "Tomcat 9.0 Migration Guide", the "Tomcat 10.0 Migration Guide", and the "Tomcat 10.1 Migration Guide".
Migrating your server.xml file
Probably the most important configuration file you will have to migrate
One way to quickly determine what kinds of changes might be necessary
server.xml file is to use the
program to compare your existing old-Tomcat-version file with the stock
configuation file that came with your old version of Apache Tomcat.
$ diff /path/to/stock/tomcat/conf/server.xml /path/to/your/tomcat/conf/server.xml
This will display the changes made to the original file that are unique to your environment. You can adapt these changes to the new installation of your new Apache Tomcat version.
Other Important Files
There are some other configuration files you may want to copy or adapt from your previous installation. Here is a list of those other files you may have customized in your old installation.
- bin/setenv.sh (if it exists)
If you are unsure, you can use the same technique shown above to check for any differences between your installation and a stock Apache Tomcat configuration file.
Often, minor upgrades are very simple and you can use the same configuration files as the previous version with no changes.
Read the Migration Guide
It is still important to read the Migration Guide for the major version you are using, specifically the "upgrading" section.
The Migration Guide also contains an "Noteable Changes" section which includes changes within the major version – that is, a minor version within a major version's revision numbers – which contains a very important change. These kinds of changes include the the introduction of new defaults, new requirements (usually for security), or breaking changes from previous versions (also usually for security).
Finally, the Migration Guide has a section that allows you to compare the stock configuration files between minor versions to see if any important changes have been made between those versions. It's easy to use: simply choose your old-version and new-version from the drop-down boxes on the Migration Guide page and then "View Differences".
RUNNING.txt, there is a section titled Advanced
Configuration - Multiple Tomcat Instances. It is intended to describe
how a single Apache Tomcat installation can be used to run multiple
separate server instances. This technique can be used to help simplify
There is a presentation available which will walk you through the process of splitting your installation, and then describes how to perform an upgrade.