<?xml version="1.0" encoding="UTF-8"?>
<document>
  <properties>
    <author>Apache Tomcat Project</author>
    <title>Upgrading Apache Tomcat</title>
  </properties>

<body>
  <section name="Overview">
    Upgrading Apache Tomcat<sup>&#174;</sup> can be straightforward or complicated, depending
    upon the complexity of your environment. This document explains some of the
    basics of upgrading Apache Tomcat and can be used as a starting point for
    you to establish your own environment-specific upgrade plans and procedures.
  </section>

  <section name="Table of Contents">
    <toc/>
  </section>

  <section name="Not Covered">
    <p>
      There are some topics <i>not</i> covered by this basic upgrade guide.
    </p>

    <subsection name="Patches">
      <p>
        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.
      </p>
    </subsection>

    <subsection name="Embdded Tomcat">
      <p>
        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.
      </p>
    </subsection>
  </section>

  <section name="Upgrade Types">
    <p>
      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.
    </p>

    <section name="Versioning">
      Apache Tomcat version numbers are of the form X.Y.Z where X.Y is the
      "major" version number, and the Z is the revision-number within the major
      version. Upgrading between Tomcat 10.1 and 11.0 is considered a "major
      upgrade" while upgrading from 10.1.20 to 10.1.21 is considered a "minor
      upgrade".
    </section>
  </section>

  <section name="Major Upgrades">
    <p>
      When upgrading between major versions of Tomcat (e.g. 9.0 to 10.1), 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.
    </p>

    <subsection name="Read the Migration Guide">
      <p>
        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.1, you should read the "Tomcat 10.1 Migration
        Guide" which covers everything that applies for upgrading from the
        previous version.
      </p>
      <p> 
        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".
      </p>
    </subsection>

    <subsection name="Migrating your server.xml file">
      <p>
        Probably the most important configuration file you will have to migrate
        is your <code>conf/server.xml</code> file.
      </p>
      <p>
        One way to quickly determine what kinds of changes might be necessary
        for your <code>server.xml</code> file is to use the <code>diff</code>
        program to compare your existing old-Tomcat-version file with the stock
        configuation file that came with your old version of Apache Tomcat.
      </p>
      <p>
        For example:
      </p>
      <source>$ diff /path/to/stock/tomcat/conf/server.xml /path/to/your/tomcat/conf/server.xml</source>

      <p>
        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.
      </p>
    </subsection>

    <subsection name="Other Important Files">
      <p>
        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.
      </p>
      <ul>
        <li>conf/web.xml</li>
        <li>conf/context.xml</li>
        <li>conf/tomcat-users.xml</li>
        <li>conf/logging.properties</li>
        <li>bin/setenv.sh (if it exists)</li>
        <li>conf/catalina.properties</li>
        <li>conf/catalina.policy</li>
        <li>conf/jaspic-providers.xml</li>
      </ul>
      <p>
        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.
      </p>
    </subsection>
  </section>

  <section name="Minor Upgrades">
    <p>
      Often, minor upgrades are very simple and you can use the same
      configuration files as the previous version with no changes.
    </p>

    <subsection name="Read the Migration Guide">
      <p>
        It is still important to read the <a href="migration.html">Migration
        Guide</a> for the major version you are using, specifically the
        "upgrading" section.
      </p>
      <p>
        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).
      </p>
      <p>
        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".
      </p>
    </subsection>
  </section>

  <section name="Split Configurations">
    <p>
      In <code>RUNNING.txt</code>, there is a section titled <i>Advanced
      Configuration - Multiple Tomcat Instances</i>. 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
      upgrades.
    </p>
    <p>
      There is a presentation available which will walk you through the process
      of splitting your installation, and then describes how to perform an
      upgrade.
    </p>
    <p>
      <a href="presentations.html#latest-split-installation"><i>Split your Tomcat Installation for Easier Upgrades</i></a>
    </p>
  </section>
</body>
</document>
