Apache Tomcat

• General
• Migrating from 6.0.x to 7.0.x
  1. Java 6 required
  2. Servlet 3.0 API
  3. Regular expressions
  4. Deployment
  5. Manager application
  6. Host Manager application
  7. Session manager configuration
  8. Session cookie configuration
  9. Cookies
  10. Request attributes
  11. Comet
  12. XML validation
  13. System properties
  14. Processing of conf/web.xml file
  15. Welcome files processing
  16. Annotation scanning
  17. Internal APIs
• Upgrading 7.0.x
  1. Tomcat 7.0.x configuration file differences

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

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

Java 6 required

Apache Tomcat 7.0.x requires Java 6 or later. Apache Tomcat 6.0.x required Java 5.

Servlet 3.0 API

Apache Tomcat 7 supports Java Servlet 3.0, JavaServer Pages 2.2 and Expression Language 2.2 specifications. The changes between versions of specifications may be found in the Changes appendix in each of specification documents. In JSP pages that use wildcard import syntax the new classes added in Servlet API may conflict with ones in web applications. For example, if package "a" contains class Part, the following JSP page will cease to compile in Tomcat 7: <%@page import="a.*"%> <% Part page = new Part(); %> That happens because implicit import of javax.servlet.http.* and explicit import of a.* will provide conflicting definitions of class Part that was added in Servlet 3.0. The solution is to use explicit import, import="a.Part".

Regular expressions

All configuration options that use regular expression now require a single regular expression (using java.util.regex) rather than a list of comma-separated or semi-colon-separated expressions. This concerns the following: allow and deny attributes in RemoteAddrFilter, RemoteHostFilter filters and in RemoteAddrValve, RemoteHostValve valves; internalProxies, trustedProxies attributes in RemoteIpFilter, RemoteIpValve; filter attribute in ReplicationValve; restrictedUserAgents, noCompressionUserAgents attributes in HTTP connectors. Note that separate regular expressions can be concatenated using the "|" operator (or). Using "|" works both in this and in earlier Tomcat versions.

Deployment

XML context descriptors (META-INF/context.xml files) are no longer copied from deployed WARs and directories to the host's xmlBase. The default Tomcat 6 behavior can be enabled by setting the copyXML attribute of the Host element to true. The WARs outside of the host's appBase are no longer unpacked, regardless of the value of the Host's unpackWARs setting. See issue 51294.

Manager application

The Manager application has been re-structured for Tomcat 7 onwards and some URLs have changed. All URLs used to access the Manager application should now start with one of the following options: <ContextPath>/html for the HTML GUI <ContextPath>/text for the text interface <ContextPath>/jmxproxy for the JMX proxy <ContextPath>/status for the status pages Note that the URL for the text interface has changed from "<ContextPath>" to "<ContextPath>/text". The roles required to use the Manager application were changed from the single manager role to the following four roles. You will need to assign the role(s) required for the functionality you wish to access. manager-gui - allows access to the HTML GUI and the status pages manager-script - allows access to the text interface and the status pages manager-jmx - allows access to the JMX proxy and the status pages manager-status - allows access to the status pages only The HTML interface is protected against CSRF but the text and JMX interfaces are not. To maintain the CSRF protection: users with the manager-gui role should not be granted either the manager-script or manager-jmx roles. if the Manager application is accessed through a browser by a user who has manager-script or manager-jmx roles (e.g. for testing the text or jmx interfaces since these interfaces are intended for tools not humans) then all browser windows must be closed afterwards to terminate the session. The roles command has been removed from the Manager application since it did not work with the default configuration and most Realms do not support providing a list of roles.

Host Manager application

The Host Manager application has been re-structured for Tomcat 7 onwards and some URLs have changed. All URLs used to access the Host Manager application should now start with one of the following options: <ContextPath>/html for the HTML GUI <ContextPath>/text for the text interface Note that the URL for the text interface has changed from "<ContextPath>" to "<ContextPath>/text". The roles required to use the Host Manager application were changed from the single admin role to the following two roles. You will need to assign the role(s) required for the functionality you wish to access. admin-gui - allows access to the HTML GUI and the status pages admin-script - allows access to the text interface and the status pages The HTML interface is protected against CSRF but the text interface is not. To maintain the CSRF protection: users with the admin-gui role should not be granted the admin-script role. if the Host Manager application is accessed through a browser by a user who has admin-script role (e.g. for testing the text interface since this inteface is intended for tools not humans) then all browser windows must be closed afterwards to terminate the session.

Session manager configuration

A number of changes have been made to the session manager to improve the performance of session generation and destruction including changes to session ID generation. The session ID generation changes take advantages of improvements in java.secure.SecureRandom since the session ID generation was first written. The configuration changes are: randomClass attribute of Manager has changed to secureRandomClass and the provided class must extend java.secure.SecureRandom Two new properties secureRandomAlgoithm and secureRandomProvider have been added to enable the selection of a SecureRandom implementation. The algorithm attribute has been removed The entropy attribute has been removed One known issue with java.secure.SecureRandom is that it initialization requires some random data from an entropy source. With some entropy source implementations it may require some time to gather enough random data. If initialization of session id generator takes noticeable time (more than 100ms), a diagnostic message will be logged. E.g.: DATE org.apache.catalina.util.SessionIdGenerator createSecureRandom INFO: Creation of SecureRandom instance for session ID generation using [SHA1PRNG] took [406] milliseconds. It is possible to change the entropy source used by JRE by defining a system property. E.g.: -Djava.security.egd=file:/dev/./urandom The "/./" characters in the above value are to workaround JRE issue #6202721.

Session cookie configuration

With the addition of SessionCookieConfig in the Servlet 3.0 specification, a number of session cookie configuration options have been removed to reduce configuration and code complexity. Connector.emptySessionPath: This has been removed. An equivalent effect can be obtained by configuring sessionCookiePath="/" in the global context.xml (in CATALINA_BASE/conf/context.xml). org.apache.catalina.SESSION_COOKIE_NAME system property: This has been removed. An equivalent effect can be obtained by configuring the sessionCookieName attribute for the global context.xml (in CATALINA_BASE/conf/context.xml). org.apache.catalina.SESSION_PARAMETER_NAME system property: This has been removed. An equivalent effect can be obtained by configuring the sessionCookieName attribute for the global context.xml (in CATALINA_BASE/conf/context.xml). Context.disableURLRewriting: This has been removed. An equivalent effect can be obtained by configuring the session-config/tracking-mode elements in a web application or in the global CATALINA_BASE/conf/web.xml file. The session and SSO cookies in Tomcat 7 are being sent with HttpOnly flag by default, to instruct browsers to prevent access to those cookies from JavaScript. This is considered more secure, but it will prevent JavaScripts from accessing the value of the cookie. This feature can be controlled by useHttpOnly attribute on the Context element. (This feature is also implemented in latest versions of Tomcat 6.0 but is off by default. It can be enabled by setting useHttpOnly="true" on Context element in a web application or in the global CATALINA_BASE/conf/context.xml file).

Cookies

Tomcat no longer accepts non-specification compliant name-only cookies by default. However, a new system property has been added, org.apache.tomcat.util.http.ServerCookie.ALLOW_NAME_ONLY, that can be used to accept name-only cookies.

Request attributes

The custom request attribute javax.servlet.request.ssl_session provided to access the SSL session ID has been deprecated in favour of the new standard request attribute that is defined in the Servlet specification, javax.servlet.request.ssl_session_id. Support for the custom attribute will be removed in Tomcat 8.

Comet

To enable Comet to work correctly when running under a security manager, the Comet classes have been moved from the org.apache.catalina package to the org.apache.catalina.comet package. Code that uses Comet will need to be updated and recompiled to reflect the new package name.

XML validation

The configuration of XML validation has been simplified. The xmlValidation and xmlNamespaceAware attributes have been removed from the Host element. These attributes, along with tldValidation and tldNamespaceAware, are now set per Context element. The defaults (false for each attribute) have not been changed. However, in line with the requirements of the Servlet specification, if the org.apache.catalina.STRICT_SERVLET_COMPLIANCE system property is set to true, XML validation and namespace awareness will be enabled by default.

System properties

The org.apache.catalina.STRICT_SERVLET_COMPLIANCE system property has been modified to provide greater control over its effects. Each behavioural change is now controlled by a dedicated system property. The default behaviour is unchanged. The org.apache.catalina.STRICT_SERVLET_COMPLIANCE system property now controls whether or not specification compliant defaults are used for the other system properties. Even if org.apache.catalina.STRICT_SERVLET_COMPLIANCE is true, setting the individual system properties will always take priority. The org.apache.coyote.MAX_TRAILER_SIZE has been removed and is replaced by the maxTrailerSize attribute of the Connector.

Processing of conf/web.xml file

Servlet 3.0 specification defines how web.xml file of an application can be combined from web fragments and annotations. Processing of the global conf/web.xml file that defines server-wide defaults was changed as a result of implementing those rules. One noticeable difference is that Filters defined in the global conf/web.xml now follow the ones defined in a web application, instead of preceding them. See issues 51754 and 52138 for clarifications.

Welcome files processing

The welcome file processing was changed to follow clarifications in the Servlet 3.0 specification. If your list of welcome files includes ones that are processed by a servlet (such as *.jsp), you may observe the change in behaviour. See the resourceOnlyServlets option on Context.

Annotation scanning

The annotation scanning required by the Servlet 3.0 specification may have impact on the startup time of your web application, as well as increase requirements on the memory needed to load scanned classes. Note, that upon clarification from the Servlet EG, even applications using Servlet 2.4 and older versions of specification are being scanned. See issue 53619 and related discussions on the users mailing list. There are several ways to deal with this issue. The recommended way is to mark those applications that do not require annotation scanning as such. It can be done in the WEB-INF/web.xml of your application by the following steps: Update the web-app element to indicate that the web application is using specification version 3.0. You may copy the values for the version, xsi:schemaLocation, xmlns and xmlns:xsi attributes from the default conf/web.xml file. Add metadata-complete="true" attribute to the web-app element. Add an empty <absolute-ordering /> element. The metadata-complete attribute is supported starting with Servlet 2.5 specification. The absolute-ordering element requires Servlet 3.0. The second way is to configure JarScanner component to ignore certain JAR files according to their names. This is usually configured in the conf/catalina.properties file. See documentation on the jarsToSkip properties in the System properties chapter of the Configuration Reference for details. Starting with Tomcat 7.0.30 it is possible to separately configure which JARs are skipped for Servlet 3.0 scanning (scanning for annotations and web application fragments), TLD scanning (tag libraries) or both. Further versions of Tomcat may provide better ways to control this feature.

Internal APIs

Whilst the Tomcat 7 internal API is broadly compatible with Tomcat 6 there have been many changes at the detail level and they are not binary compatible. Developers of custom components that interact with Tomcat's internals should review the JavaDoc for the relevant API. Of particular note are: A standard implementation of the Lifecycle interface that all components extend. Use of generics. The use of Context name rather than Context path as the unique identifier for a Context within a Host.

When upgrading instances of Apache Tomcat from one version of Tomcat 7 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 7.

Tomcat 7.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. Configuration file: catalina.policy catalina.properties context.xml logging.properties server.xml tomcat-users.xml web.xml Old version: 7.0.0 7.0.2 7.0.4 7.0.5 7.0.6 7.0.8 7.0.10 7.0.11 7.0.12 7.0.14 7.0.16 7.0.19 7.0.20 7.0.21 7.0.22 7.0.23 7.0.25 7.0.26 7.0.27 7.0.28 7.0.29 7.0.30 7.0.32 7.0.34 7.0.35 7.0.37 7.0.39 7.0.40 , new version: 7.0.0 7.0.2 7.0.4 7.0.5 7.0.6 7.0.8 7.0.10 7.0.11 7.0.12 7.0.14 7.0.16 7.0.19 7.0.20 7.0.21 7.0.22 7.0.23 7.0.25 7.0.26 7.0.27 7.0.28 7.0.29 7.0.30 7.0.32 7.0.33 7.0.34 7.0.35 7.0.37 7.0.39 7.0.40 trunk (unreleased) You can also use Subversion command similar to the following (all on one line): svn diff --old=http://svn.apache.org/repos/asf/tomcat/tc7.0.x/tags/TOMCAT_7_0_27/conf/ --new=http://svn.apache.org/repos/asf/tomcat/tc7.0.x/tags/TOMCAT_7_0_28/conf/