Please read the 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 8.0.x and 8.5.x which may cause backwards compatibility problems when upgrading.
The Java blocking IO implementation (BIO) for both HTTP and AJP has been removed. Users are recommended to switch to the Java non-blocking IO implementation (NIO). As of Tomcat 8.5.17, if a BIO Connector is explicitly configured, rather than failing to start the Connector, Tomcat will automatically switch the Connector to use the NIO implementation and log a warning.
HTTP reason phrases have been removed by default, but can be re-enabled using the configuration attribute.
Comet support has been removed without a direct replacement. Applications using Comet are recommended to migrate to WebSockets.
HTTP/2 is supported for h2 (over TLS, negotiated via ALPN) and h2c (clear text, negotiated via HTTP/1.1 upgrade). HTTP/2 needs to be explicitly enabled for a connector. To enable it, insert inside the connector for which you wish to enable HTTP/2. Note that to enable HTTP/2 for a secure NIO or NIO2 connector, those connectors must be using the OpenSSL engine for TLS.
Tomcat 8.5 supports multiple TLS virtual hosts for a single connector with each virtual host able to support multiple certificates. Virtual host definitions are nested inside the Connector element with the default specified using the defaultSSLHostConfigName attribute on the Connector if more than one virtual host is specified. Certificate definitions are nested inside the virtual host.
The following example shows how to use this to configure a single APR/native connector for multiple TLS virtual hosts with each host having both an RSA and EC certificate.
Whilst the Tomcat 8.5 internal API is broadly compatible with Tomcat 8.0 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:
digest
attribute has been removed from the
Realm
. This must now be configured via a
CredentialHandler
.AuthenticatorBase
implementation has been changed to
call doAuthenticate()
rather than
authenticate()
on sub-classes.The JSR-77 implementation is incomplete and has been removed in 8.5.x. Specifically, the following methods that exposed to JMX have been removed.
StandardContext.getServlets()
StandardContext.isStateManageable()
StandardContext.getDeploymentDescriptor()
StandardWrapper.isStateManageable()
MessageDispatch15Interceptor
had been used to add the Java 5
features to MessageDispatchInterceptor.
MessageDispatch15Interceptor
has been removed in Tomcat 8.5.x
by merging the Java 5 features to MessageDispatchInterceptor
.
The support of InstanceListener has been removed in 8.5.x. Specifically, the following classes have been removed.
org.apache.catalina.InstanceListener
org.apache.catalina.InstanceEvent
org.apache.catalina.util.InstanceSupport
The following session manager attributes have been completely removed in 8.5.
distributable
maxInactiveInterval
sessionIdLength
The replacements are as follows:
distributable
attribute has been deprecated in 8.0
and specified value is ignored. This should be configured via the
Context. The value is inherited based on the presence or absence of
the <distributable />
element in
/WEB-INF/web.xml.
maxInactiveInterval
attribute has been deprecated in
8.0. If the value is specified, a warning log is issued. This should
be configured via the Context. The value is inherited based on the
value of the <session-timeout>
element in
/WEB-INF/web.xml
.sessionIdLength
attribute of Manager
has
been replaced by sessionIdLength
attribute of
SessionIdGenerator
.The default CookieProcessor
is now the
Rfc6265CookieProcessor
. The CookieProcessor
is
configurable per Context
and the
LegacyCookieProcessor
may be used to obtain the 8.0.x
behaviour.
The Manager and HostManager web applications are configured by default
with a RemoteAddrValve
that limits access to those
applications to connections from localhost.
The clearReferencesStatic
attribute has been removed in
8.5.x.
When upgrading instances of Apache Tomcat from one version of Tomcat 8 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 8.
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.
maxParameterCount
has been reduced from 10,000 to 1,000.
In 8.5.51 onwards, the default listen address of the AJP Connector was changed to the loopback address rather than all addresses.
Reference: AJP connector.
In 8.5.51 onwards, the requiredSecret attribute of the AJP Connector was deprecated and replaced by the secret attribute.
Reference: AJP connector.
In 8.5.51 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 8.5.51 onwards, the allowedRequestAttributesPattern attribute was added to the AJP Connector. Requests with unrecognised attributes will now be blocked with a 403.
Reference: AJP connector.
In 8.5.64 onwards, the semantics of the
HostConfig.check(String)
method have changed. Rather than
marking the application as serviced before calling the method, the
method will mark the application as serviced before checking
resources and then un-mark the application as being serviced after the
checks are complete. If the application is marked as serviced when the
method is called, the method will be a NO-OP.
In 8.5.70 onwards, Tomcat no longer adds an "Expires" HTTP response header when adding "Cache-Control: private" due to a CONFIDENTIAL transport-guarantee. This will likely cause a change in caching behavior for applications that do not explicitly set their own headers but rely on Tomcat's previous behavior. If you wish to disable caching, you will need to configure it explicitly in your application. See BZ 65513 for more information.
In 8.5.71 onwards, as a result of the updated fork of Commons
FileUpload now using java.nio.file.Files
, applications
using multi-part uploads need to ensure that the JVM is configured with
sufficient direct memory to store all in progress multi-part
uploads.
In 8.5.74 onwards, the system property
org.apache.juli.AsyncLoggerPollInterval
is no longer
used.
In 8.5.75 and onwards, the JmxRemoteLifecycleListener has been removed. Note that modern JVMs no longer need the features provided by JMXLifecycleListener.
In 8.5.75 and onwards, the maxSavePostSize
attribute
on the <Connector>
also applies to a request body
present when an HTTP/1.1 upgrade is being performed.
In 8.5.76 and onwards, Tomcat release builds are performed using Java 11 in "Java 7 mode". This should produce a fully-compatible release that should work under Java 7 or later. Any problems you experience such as class-file-version errors, method-mismatch errors, or JVM verifiers should be reported to the Tomcat team immediately.
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: