The Apache Tomcat Servlet/JSP Container
Apache Tomcat 7
Version 7.0.103, Mar 16 2020 Apache Logo

Links

Docs Home
FAQ
User Comments

User Guide

1) Introduction
2) Setup
3) First webapp
4) Deployer
5) Manager
6) Host Manager
7) Realms and AAA
8) Security Manager
9) JNDI Resources
10) JDBC DataSources
11) Classloading
12) JSPs
13) SSL/TLS
14) SSI
15) CGI
16) Proxy Support
17) MBeans Descriptors
18) Default Servlet
19) Clustering
20) Load Balancer
21) Connectors
22) Monitoring and Management
23) Logging
24) APR/Native
25) Virtual Hosting
26) Advanced IO
27) Additional Components
28) Mavenized
29) Security Considerations
30) Windows Service
31) Windows Authentication
32) Tomcat's JDBC Pool
33) WebSocket

Reference

Release Notes
Configuration
Tomcat Javadocs
Servlet Javadocs
JSP 2.2 Javadocs
EL 2.2 Javadocs
WebSocket 1.1 Javadocs
Common Annotations 1.1 Javadocs
JK 1.2 Documentation

Apache Tomcat Development

Building
Changelog
Status
Developers
Architecture
Functional Specs.
Tribes

Security Considerations
Table of Contents

    Introduction
    Non-Tomcat settings
        JMX
    Default web applications
        General
        ROOT
        Documentation
        Examples
        Manager
        Host Manager
        Securing Management Applications
    Security manager
    server.xml
        General
        Server
        Listeners
        Connectors
        Host
        Context
        Valves
        Realms
        Manager
        Cluster
    System Properties
    web.xml
    General

Introduction

Tomcat is configured to be reasonably secure for most use cases by default. Some environments may require more, or less, secure configurations. This page is to provide a single point of reference for configuration options that may impact security and to offer some commentary on the expected impact of changing those options. The intention is to provide a list of configuration options that should be considered when assessing the security of a Tomcat installation.

Note: Reading this page is not a substitute for reading and understanding the detailed configuration documentation. Fuller descriptions of these attributes may be found in the relevant documentation pages.

Non-Tomcat settings

Tomcat configuration should not be the only line of defense. The other components in the system (operating system, network, database, etc.) should also be secured.

Tomcat should not be run under the root user. Create a dedicated user for the Tomcat process and provide that user with the minimum necessary permissions for the operating system. For example, it should not be possible to log on remotely using the Tomcat user.

File permissions should also be suitably restricted. In the .tar.gz distribution, files and directories are not world readable and the group does not have write access. On Unix like operating systems, Tomcat runs with a default umask of 0027 to maintain these permissions for files created while Tomcat is running (e.g. log files, expanded WARs, etc.).

Taking the Tomcat instances at the ASF as an example (where auto-deployment is disabled and web applications are deployed as exploded directories), the standard configuration is to have all Tomcat files owned by root with group Tomcat and whilst owner has read/write privileges, group only has read and world has no permissions. The exceptions are the logs, temp and work directory that are owned by the Tomcat user rather than root. This means that even if an attacker compromises the Tomcat process, they can't change the Tomcat configuration, deploy new web applications or modify existing web applications. The Tomcat process runs with a umask of 007 to maintain these permissions.

At the network level, consider using a firewall to limit both incoming and outgoing connections to only those connections you expect to be present.
JMX

    The security of the JMX connection is dependent on the implementation provided by the JRE and therefore falls outside the control of Tomcat.

    Typically, access control is very limited (either read-only to everything or read-write to everything). Tomcat exposes a large amount of internal information and control via JMX to aid debugging, monitoring and management. Given the limited access control available, JMX access should be treated as equivalent to local root/admin access and restricted accordingly.

    The JMX access control provided by most (all?) JRE vendors does not log failed authentication attempts, nor does it provide an account lock-out feature after repeated failed authentications. This makes a brute force attack easy to mount and difficult to detect.

    Given all of the above, care should be taken to ensure that, if used, the JMX interface is appropriately secured. Options you may wish to consider to secure the JMX interface include:

        configuring a strong password for all JMX users;
        binding the JMX listener only to an internal network;
        limiting network access to the JMX port to trusted clients; and
        providing an application specific health page for use by external monitoring systems.

Default web applications

General

    Tomcat ships with a number of web applications that are enabled by default. Vulnerabilities have been discovered in these applications in the past. Applications that are not required should be removed so the system will not be at risk if another vulnerability is discovered.

ROOT

    The ROOT web application presents a very low security risk but it does include the version of Tomcat that is being used. The ROOT web application should normally be removed from a publicly accessible Tomcat instance, not for security reasons, but so that a more appropriate default page is shown to users.

Documentation

    The documentation web application presents a very low security risk but it does identify the version of Tomcat that is being used. It should normally be removed from a publicly accessible Tomcat instance.

Examples

    The examples web application should always be removed from any security sensitive installation. While the examples web application does not contain any known vulnerabilities, it is known to contain features (particularly the cookie examples that display the contents of all received and allow new cookies to be set) that may be used by an attacker in conjunction with a vulnerability in another application deployed on the Tomcat instance to obtain additional information that would otherwise be unavailable.

Manager

    The Manager application allows the remote deployment of web applications and is frequently targeted by attackers due to the widespread use of weak passwords and publicly accessible Tomcat instances with the Manager application enabled. The Manager application is not accessible by default as no users are configured with the necessary access. If the Manager application is enabled then guidance in the section Securing Management Applications section should be followed.

Host Manager

    The Host Manager application allows the creation and management of virtual hosts - including the enabling of the Manager application for a virtual host. The Host Manager application is not accessible by default as no users are configured with the necessary access. If the Host Manager application is enabled then guidance in the section Securing Management Applications section should be followed.

Securing Management Applications

    When deploying a web application that provides management functions for the Tomcat instance, the following guidelines should be followed:

        Ensure that any users permitted to access the management application have strong passwords.
        Do not remove the use of the LockOutRealm which prevents brute force attacks against user passwords.
        Uncomment the RemoteAddrValve in /META-INF/context.xml which limits access to localhost. If remote access is required, limit it to specific IP addresses using this valve.

Security manager

Enabling the security manager causes web applications to be run in a sandbox, significantly limiting a web application's ability to perform malicious actions such as calling System.exit(), establishing network connections or accessing the file system outside of the web application's root and temporary directories. However, it should be noted that there are some malicious actions, such as triggering high CPU consumption via an infinite loop, that the security manager cannot prevent.

Enabling the security manager is usually done to limit the potential impact, should an attacker find a way to compromise a trusted web application . A security manager may also be used to reduce the risks of running untrusted web applications (e.g. in hosting environments) but it should be noted that the security manager only reduces the risks of running untrusted web applications, it does not eliminate them. If running multiple untrusted web applications, it is recommended that each web application is deployed to a separate Tomcat instance (and ideally separate hosts) to reduce the ability of a malicious web application impacting the availability of other applications.

Tomcat is tested with the security manager enabled; but the majority of Tomcat users do not run with a security manager, so Tomcat is not as well user-tested in this configuration. There have been, and continue to be, bugs reported that are triggered by running under a security manager.

The restrictions imposed by a security manager are likely to break most applications if the security manager is enabled. The security manager should not be used without extensive testing. Ideally, the use of a security manager should be introduced at the start of the development cycle as it can be time-consuming to track down and fix issues caused by enabling a security manager for a mature application.

Enabling the security manager changes the defaults for the following settings:

    The default value for the deployXML attribute of the Host element is changed to false.

server.xml

General

    The default server.xml contains a large number of comments, including some example component definitions that are commented out. Removing these comments makes it considerably easier to read and comprehend server.xml.

    If a component type is not listed, then there are no settings for that type that directly impact security.

Server

    Setting the port attribute to -1 disables the shutdown port.

    If the shutdown port is not disabled, a strong password should be configured for shutdown.

Listeners

    The APR Lifecycle Listener is not stable if compiled on Solaris using gcc. If using the APR/native connector on Solaris, compile it with the Sun Studio compiler.

    The JNI Library Loading Listener may be used to load native code. It should only be used to load trusted libraries.

    The Security Lifecycle Listener should be enabled and configured as appropriate.

Connectors

    By default, a non-TLS, HTTP/1.1 connector is configured on port 8080. Connectors that will not be used should be removed from server.xml.

    The address attribute may be used to control which IP address a connector listens on for connections. By default, a connector listens on all configured IP addresses.

    The allowTrace attribute may be used to enable TRACE requests which can be useful for debugging. Due to the way some browsers handle the response from a TRACE request (which exposes the browser to an XSS attack), support for TRACE requests is disabled by default.

    The discardFacades attribute set to true will cause a new facade object to be created for each request. This reduces the chances of a bug in an application exposing data from one request to another.

    The maxPostSize attribute controls the maximum size of a POST request that will be parsed for parameters. The parameters are cached for the duration of the request so this is limited to 2MB by default to reduce exposure to a DOS attack.

    The maxSavePostSize attribute controls the saving of POST requests during FORM and CLIENT-CERT authentication. The parameters are cached for the duration of the authentication (which may be many minutes) so this is limited to 4KB by default to reduce exposure to a DOS attack.

    The maxParameterCount attribute controls the maximum number of parameter and value pairs (GET plus POST) that can be parsed and stored in the request. Excessive parameters are ignored. If you want to reject such requests, configure a FailedRequestFilter.

    The xpoweredBy attribute controls whether or not the X-Powered-By HTTP header is sent with each request. If sent, the value of the header contains the Servlet and JSP specification versions, the full Tomcat version (e.g. Apache Tomcat/7.0), the name of the JVM vendor and the version of the JVM. This header is disabled by default. This header can provide useful information to both legitimate clients and attackers.

    The server attribute controls the value of the Server HTTP header. The default value of this header for Tomcat 4.1.x to 8.0.x is Apache-Coyote/1.1. From 8.5.x onwards this header is not set by default. This header can provide limited information to both legitimate clients and attackers.

    The SSLEnabled, scheme and secure attributes may all be independently set. These are normally used when Tomcat is located behind a reverse proxy and the proxy is connecting to Tomcat via HTTP or HTTPS. They allow Tomcat to see the SSL attributes of the connections between the client and the proxy rather than the proxy and Tomcat. For example, the client may connect to the proxy over HTTPS but the proxy connects to Tomcat using HTTP. If it is necessary for Tomcat to be able to distinguish between secure and non-secure connections received by a proxy, the proxy must use separate connectors to pass secure and non-secure requests to Tomcat. If the proxy uses AJP then the SSL attributes of the client connection are passed via the AJP protocol and separate connectors are not needed.

    The tomcatAuthentication and tomcatAuthorization attributes are used with the AJP connectors to determine if Tomcat should handle all authentication and authorisation or if authentication should be delegated to the reverse proxy (the authenticated user name is passed to Tomcat as part of the AJP protocol) with the option for Tomcat to still perform authorization.

    The allowUnsafeLegacyRenegotiation attribute provides a workaround for CVE-2009-3555, a TLS man in the middle attack. This workaround applies to the BIO connector. It is only necessary if the underlying SSL implementation is vulnerable to CVE-2009-3555. For more information on the current state of this vulnerability and the work-arounds available see the Tomcat 7 security page.

    The