Apache Tomcat^®

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

Apache Tomcat 7 supports Java Servlet 3.0, JavaServer Pages 2.2, Expression Language 2.2 and WebSocket 1.1 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".

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.

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 not unpacked, regardless of the value of the Host's unpackWARs setting in versions 7.0.12 to 7.0.47 inclusive. Note that this unpacking is only supported in 7.0.48 onwards. See issue 51294.

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.

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 interface is intended for tools not humans) then all browser windows must be closed afterwards to terminate the session.

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 secureRandomAlgorithm 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.

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).

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.

If a cookie value or path contain characters that have to be quoted (per RFC2109 specification), the cookie will be automatically converted from "version 0" cookie into "version 1" cookie before sending it to the client and those values will be surrounded by double quotes. What characters need quoting is controlled by several System properties such as org.apache.tomcat.util.http.ServerCookie.FWD_SLASH_IS_SEPARATOR. It is known that Internet Explorer has problem processing "version 1" cookies. (Bug 57872).

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.

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.

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.

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.

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.

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.

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.

There have been a number of improvements to TLD processing. In addition to some internal refactoring to improve consistency and reduce duplication, there are a number of functional improvements. These are:

• EL processing within tag files is now consistent with the JSP version declared for the tag file.
• The requirements of section JSP.7.3.1 of the JSP specification are now enforced and TLD files are not permitted to be placed in WEB-INF/lib or WEB-INF/classes.

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.

Initialization parameter of JspServlet that controls one of performance optimizations has been renamed from genStrAsCharArray to genStringAsCharArray and is now consistent with the name of related attribute in Jasper task for Apache Ant.

The Tomcat developers aim for each patch release to be fully backwards compatible with the previous release. Occasionally, it is necessary to break backwards compatibility in order to fix a bug. In most cases, these changes will go unnoticed. This section lists changes that are not fully backwards compatible and might cause breakage when upgrading.

• In 7.0.51 onwards, the web application class loader is now a higher priority for loading classes than the system class loader.

• In 7.0.63 onwards, the meaning of value 0 for maxPostSize attribute on connectors was changed to mean a limit of zero rather than no limit to align it with maxSavePostSize and to be more intuitive.

  Reference: HTTP connector, AJP connector.

• In 7.0.100 onwards, the default listen address of the AJP Connector was changed to the loopback address rather than all addresses.

  Reference: AJP connector.

• In 7.0.100 onwards, the requiredSecret attribute of the AJP Connector was deprecated and replaced by the secret attribute.

  Reference: AJP connector.

• In 7.0.100 onwards, the secretRequired attribute was added to the AJP Connector. If set to true, the default, the AJP Connector will not start unless a secret has been specified.

  Reference: AJP connector.

• In 7.0.100 onwards, the allowedRequestAttributesPattern attribute was added to the AJP Connector. Requests with unrecognised attributes will now be blocked with a 403.

  Reference: AJP connector.

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.

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.

Note: If there are no differences you will see an error page.

You can also use a Git command similar to the following from within a working copy:

git diff 7.0.0 7.0.80 -- conf/