Content

Table of Contents

General

Please read the general Migration Guide page first, for common considerations that apply to migration or upgrade between versions of Apache Tomcat®.

Migrating from 5.5.x to 6.0.x

This section lists all the known changes between 5.5.x and 6.0.x which may cause backwards compatibility problems when upgrading.

Java 5 required

Apache Tomcat 6.0.x requires Java 5 or later, unlike Apache Tomcat 5.5.x which could use a compatibility package to run on JRE 1.4.

Modified directory structure

Shared libraries

Apache Tomcat 5.5.x used, by default, a directory structure including common, shared and server subdirectories. Apache Tomcat 6.0.x uses a single lib directory.

The lib directory is the direct replacement for both common/lib and common/classes subdirectories: it accepts both JARs and exploded class hierarchies.

The conf/catalina.properties file can be used to modify the directory structure.

Starting with version 6.0.21, Apache Tomcat supports both the $CATALINA_BASE/lib and $CATALINA_HOME/lib directories. The jars and classes in $CATALINA_BASE/lib are earlier on the class path and thus take precedence.

Endorsed libraries

The $CATALINA_HOME/common/endorsed subdirectory is replaced by the $CATALINA_HOME/endorsed directory. This directory is absent by default.

The JAVA_ENDORSED_DIRS environment variable can be used with setenv.bat|sh scripts to provide alternative location of this directory.

Default web applications

The Manager and Host Manager web applications are no longer in server/webapps. All of the default web applications are now located in the webapps directory.

Note, that if deployOnStartup or autoDeploy options on the Host are enabled, the META-INF/context.xml files of manager and host-manager applications will be copied into the $CATALINA_BASE/conf/[engine_name]/[host_name] directory when Tomcat starts for the first time.

When using a shared webhosting environment, it is recommended to forbid the use of context.xml inside the web applications (using the deployXML attribute of the Host element). (This option is also available in Tomcat 5.5).

Modified classloading

As a result of the modification of the directory structure, the common, shared and server classloaders have been merged into one. Effectively, the shared and server classloaders are not configured by default and the common classloader is mapped to the lib directory, as described above.

This behavior and structure can be modified using the conf/catalina.properties file.

Internal Logging API package renaming

Apache Tomcat 5.5.x relied on the Apache Commons Logging library for its internal logging. Apache Tomcat 6.0.x and later no more uses the library directly, but uses a private copy of it. The classes are in the org.apache.juli.logging package.

The rationale behind this change is that so that application logging can be as independent as possible from the container, while still having the possibility of being unified.

By default only a subset of Apache Commons Logging classes that are needed to perform logging to java.util.logging is included with Tomcat. If you want to configure Tomcat to redirect its logging into Log4J, or any other logging framework supported by the full Apache Commons Logging library, you will have to replace one of Tomcat JARs with the full implementation. The JAR is available as an extras component. See the logging and extras documentation for more details.

commons-logging.jar

As Apache Tomcat no longer directly uses the Apache Commons Logging library, the commons-logging-api.jar library is no longer provided for the web applications. The web applications that use Apache Commons Logging have to provide their own copy of that library. It is recommended to put it into their WEB-INF/lib directory, like any other JAR.

SSLEnabled attribute on Connector

For all SSL enabled connectors, the SSLEnabled flag must be set to true to enable encryption. Tomcat no longer relies on using the protocol and other parameters to determine if the transport should be encrypted, to give maximum flexibility in proxied scenarios.

Connector thread pools

The Connector thread pools have been simplified. They now grow to the maximum size specified but never shrink. The attributes associated with shrinking the thread pool (e.g. minSpareThreads) will be ignored. If you require a thread pool that grows and shrinks with demand you'll need to configure an Executor and then configure your Connector to use it.

Clustering configuration changes

Clustering configuration was refactored. See the clustering documentation for more details.

Upgrading 6.0.x

When upgrading instances of Apache Tomcat from one version of Tomcat 6 to another, particularly when using separate locations for $CATALINA_HOME and $CATALINA_BASE, it is necessary to ensure that any changes in the configuration files such as new attributes and changes to defaults are applied as part of the upgrade. To assist with the identification of these changes, the form below may be used to view the differences between the configuration files in different versions of Tomcat 6.

Tomcat 6.0.x configuration file differences

Select a configuration file, old version and new version from the boxes below and then click "View differences" to see the differences. The differences will be shown in a new tab/window.

You can also use Subversion command similar to the following (all on one line):

svn diff
  --old=http://svn.apache.org/repos/asf/tomcat/archive/tc6.0.x/tags/TOMCAT_6_0_36/conf/
  --new=http://svn.apache.org/repos/asf/tomcat/archive/tc6.0.x/tags/TOMCAT_6_0_37/conf/