Apache Tomcat Hardening Tutorial

Tomcat is secure enough for typical uses, there are no known security exploits or weaknesses. However, the Internet is a wild place. These are the best practices for hardening Tomcat.

1. The tools

  • Java JDK
  • Apache Tomcat

2. Introduction

In this example we are going to illustrate the best practices for hardening the Apache Tomcat installation.

3. Prerequisites

  • JDK installed

4. Run Tomcat as Unprivileged User

By default, Tomcat runs on port 8080 and therefore does not require root to run. It’s important not to run as root. Create a special user, e.g. named “tomcat”, which owns everything under ${tomcat_home}, and change to that user in order to run Tomcat. This special user will need read/write access to ${tomcat_home} and its subdirectories, and read access to your data directories. Don’t give the tomcat user any rights in any other directories. If your operating system allows it (e.g. Unix, Linux), you might also not allow the tomcat user to log in, requiring instead that you log in as yourself, then switch to the tomcat user.

4.1 Unix/Linux

This line of advice applies to most web server platforms. Web-related services should not be run by user accounts with a high level of administrative access. In Tomcat’s case, a user with the minimum necessary OS permissions should be created exclusively to run the Tomcat process.

Create a Tomcat user:

Create Tomcat User

sudo adduser tomcat

Download and unpack the core distribution.

Unpack Tomcat

sudo cp apache-tomcat-8.0.33.tar.gz /opt
cd /opt
sudo tar zxvf apache-tomcat-8.0.33.tar.gz

Change tomcat folder ownership to tomcat user and tomcat group.

Change ownership

sudo chown -R tomcat:tomcat /opt/apache-tomcat-8.0.33

Run Tomcat as a specific user:

Run Tomcat

sudo -u tomcat /opt/apache-tomcat-8.0.33/bin/ run

4.2 Windows

Create an unprivileged account (if your host is part of an Active Directory there may be already a template for service users). The user should have “Log on as a service” rights assigned to it.
Make sure the Apache Tomcat service is set to run as that user.

5. Restrict access to critical files

Make sure that everything under /opt/apache-tomcat-8.0.33/conf/ can be read only by the tomcat user. Typically you would also give write access to the tomcat user.

The Tomcat installation directory (sometimes referred to as CATALINA_HOME) should be installed as a user that is different to the one it will be run as.
Under Linux, unpacking the Tomcat distribution as root is the simplest method of doing this.

Unfortunately, Tomcat does require write access to some directories in the distribution directory, but they should be enabled only as needed.

6. Use a Firewall

Unless you are on a private network, you need a firewall. A firewall restricts who is allowed to access network ports. Make the default setting to disallow all access, then enable just the ones that are needed.

Port 8080 should have unrestricted access. If you are allowing remote management, you must also open up port 8443. Tomcat also uses port 8005 to enable shutdown. However, shutdown can only be run from the same machine as Tomcat is running from. As long as untrusted users aren’t running on your server machine, you shouldn’t have to worry about this port being open.

However, you might want to restrict public access to it so hackers aren’t tempted. If you are also using Tomcat in conjunction with another web server like Apache to handle servlet/JSP requests, you need to allow that server access to port 8009, but typically that can be restricted to access on the same machine or at least on your subnet. If you are running Tomcat in standalone version, then disable port 8009 in ${tomcat_home}/conf/server.xml.

7. Remove Default Tomcat Applications

Remove the default webapps:

Remove everything from CATALINA_HOME/webapps (ROOT, balancer, jsp-examples, servlet-examples, tomcat-docs, webdav).

Remove everything from CATALINA_HOME/server/webapps (host-manager, manager). Note that it can be useful to keep the manager webapp installed if you need the ability to redeploy without restarting Tomcat. If you choose to keep it please read the section on Securing the Manager WebApp.

Remove CATALINA_HOME/conf/Catalina/localhost/host-manager.xml and CATALINA_HOME/conf/Catalina/localhost/manager.xml (again, if you are keeping the manager application, do not remove this).

Tomcat ships with several default web applications, found in the ${tomcat_home}/webapps directory. These defaults depend on the version of Tomcat and which installer you are using.

The ROOT application contains the server’s main page. Any file that you add under ${tomcat_home}/webapps/ROOT will be served. The admin and manager applications are used for remote management. To use these applications, you must add users with roles admin and manager. The applications are then accessible from the main page, and can be used to add further users, start and stop webapps, etc. You should restrict the IP addresses that are allowed to run these applications by editing the files admin.xml and manager.xml in the ${tomcat_home}/conf/Catalina/localhost/ directory.
The servlets-examples and jsp-examples should be removed from a production server, to minimize security exposure. You can do this from the manager application or by deleting those directories from ${tomcat_home}/webapps. The tomcat-docs, balancer and webdav applications are probably harmless, but can also be removed if you want.

Most web server platforms also provide a set of samples or a test web application for demonstration and learning purposes. These applications have been known to harbor vulnerabilities, and should be removed if not in use. Tomcat’s examples web application should be removed to prevent exploitation.

8. Change default index page

Make sure the default servlet is configured not to serve index pages when a welcome file is not present. In CATALINA_HOME/conf/web.xml

index pages

    <param-value>false</param-value>  <!-- make sure this is false -->

9. Remove version string from HTTP error messages

Remove the version string from HTTP error messages by repacking CATALINA_HOME/server/lib/catalina.jar with an updated file.


 cd CATALINA_HOME/server/lib
 jar xf catalina.jar org/apache/catalina/util/

update by changing line to Tomcat repackage catalina.jar


jar uf catalina.jar org/apache/catalina/util/

remove CATALINA_HOME/server/lib/org (created when extracting the file).

10. Replace default error page

Replace the default error page (default is stacktrace) by adding the following into CATALINA_HOME/conf/web.xml. The default error page shows a full stacktrace which discloses sensitive information. Place the following within the web-app tag (after the welcome-file-list tag is fine). The following solution is not ideal as it produces a blank page because Tomcat cannot find the file specified, but at least, achieves the desired result. A well configured web application will override this default in CATALINA_HOME/webapps/APP_NAME/WEB-INF/web.xml so it won’t cause problems.

error page


11. Replace default server.xml

Rename CATALINA_HOME/conf/server.xml to CATALINA_HOME/conf/server-original.xml and rename CATALINA_HOME/conf/server-minimal.xml to CATALINA_HOME/conf/server.xml. The minimal configuration provides the same basic configuration, but without the nested comments is much easier to maintain and understand. Do not delete the original file as the comments make it useful for reference if you ever need to make changes – e.g. enable SSL.

12. Replace server version string

Replace the server version string from HTTP headers in server responses, by adding the server keyword in your Connectors in CATALINA_HOME/conf/server.xml.

Version string

<Connector port="8080" protocol="HTTP/1.1"

13. Put Tomcat’s shutdown procedure on lock-down.

This prevents malicious actors from shutting down Tomcat’s web services. Disable the shutdown port by setting the port attribute in the server.xml file to -1. If the port must be kept open, be sure to configure a strong password for shutdown.

14. Protecting the Shutdown Port

Tomcat uses a port (defaults to 8005) as a shutdown port. What this means is that to stop all webapps and stop Tomcat, cleanly the shutdown scripts make a connection to this port and send the shutdown command. This is not as huge a security problem as it may sound considering the connection to the port must be made from the machine running tomcat and the shutdown command can be changed to something other than the string SHUTDOWN. However, it’s wise to take the following precautions.

If you are running a publicly accessible server make sure you prevent external access to the shutdown port by using a suitable firewall. Change the shutdown command in CATALINA_HOME/conf/server.xml and make sure that the file is only readable by the tomcat user.

Shutdown port

<Server port="8005" shutdown="ReallyComplexWord">

15. Try to use the latest stable version of Tomcat

As Tomcat is an active open source project, the easiest way to improve the security of your instance is to keep your version up to date and keep up with the Tomcat mailing lists. New bug fixes and security patches are added in every release, and new issues that may apply to your infrastructure are discussed on the Tomcat mailing lists. Apache also notifies community members of major security threats and patches through the Tomcat Announce mailing list. Always upgrade to the latest stable version of Tomcat as soon as possible.

16. Maintain And Use Logs

Well-maintained access logs are a vital tool in identifying security holes and sources of attack. In a development environment, it is not always obvious what kinds of malicious activity you should defend against. Maintaining logs once moving to production will help make sure an application which seems secure in development stays secure in the real world.

Logs should be maintained on multiple levels – user access, application traffic, Tomcat internals, and OS/firewall, and a single process for reviewing and acting upon logs should be agreed upon by all system administrators.

To enable logging of network traffic in Tomcat, use the AccessLogValve component. This element, which can be configured on a Host, Engine, or Context basis, will create a standard web server log file for traffic to any resources associated with it. The Access Log Valve supports a variety of attributes to control the output of the valve.

As of tomcat 5.5 logging is now handled by the commons-logging framework allowing you to choose your preferred logging implementation – log4j or standard JDK logging. By default the standard JDK logging is used (or a compatible extension called juli to be more precise), storing daily log files in CATALINA_HOME/logs.

By default additional webapp log entries are added to CATALINA_HOME/logs/catalina.YYYY-MM-DD.log and System.out/System.err are redirected to CATALINA_HOME/logs/catalina.out. To place webapp log entries in individual log files create a file similar to the following within CATALINA_HOME/webapps/APP_NAME/WEB-INF/classes (change the APP_NAME value to create a unique file for each webapp).


handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler
org.apache.juli.FileHandler.level = ALL = ${catalina.base}/logs
org.apache.juli.FileHandler.prefix = APP_NAME.

If you find you get logging output duplicated in catalina.out, you most likely have unnecessary entries for java.util.logging.ConsoleHandler in your logging configuration file.

17. Securing Manager WebApp.

By default there are no users with the manager role. To make use of the manager webapp you need to add a new role and user into the CATALINA_HOME/conf/tomcat-users.xml file.


<role rolename="manager"/>
<user username="user" password="ReallyComplexPassword" roles="manager"/>

When you access the password-protected manager webapp, the password you enter will be sent over the network in (nearly) plain text, ripe for interception. By using an SSL connection instead, you can transport the password securely. Fortunately, this is not difficult to accomplish. After configuring an SSL Connector in server.xml, simply add the following to CATALINA_HOME/webapps/manager/WEB-INF/web.xml.



18. Running Tomcat with a Security Manager.

The default Tomcat configuration provides good protection for most requirements, but does not prevent a malicious application from compromising the security of other applications running in the same instance. To prevent this sort of attack, Tomcat can be run with a Security Manager enabled which strictly controls access to server resources. Tomcat documentation has a good section on enabling the Security Manager.

It’s always a good idea to start tomcat with the “-security” parameter. This makes sure (among other things), that a web application isn’t able to read/write/execute any file on the local file system without enabling it in the catalina.policy file.

19. Enforced HTTPS.

Forcing HTTPS for all transactions in Tomcat is a multistep process. The HTTPS connector must be configured, the HTTP connector must re-direct to HTTPS, and the web application’s deployment descriptor must specify HTTPS as the default protocol.

See the common HTTPS configuration below:


<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
               maxThreads="450" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS”       
               keystoreFile="conf/keystore" keystorePass="secure-pass"
               proxyHost="192.568.23.21" proxyPort="443"

20. Conclusion.

Apache Tomcat’s popularity invariably means that its vulnerabilities and exploits are well known by both security professionals and malicious actors alike. Out-of-the-box security is never sufficient for protecting against today’s cyber threats, and proper hardening of Tomcat is especially critical given the server platform’s ubiquity.

This article has been proofread by Mark Adams

Jesus Boadas

I'm a self taught programmer, I began programming back in 1991 using an IBM A10 mainframe with Pascal an Assembler IBM 360/70 emulator and Turbo C on a X86 PC, since that I work for the banking industry with emerging technologies like Fox Pro, Visual Fox Pro, Visual Basic, Visual C++, Borland C++, lately I moved out to the Airline industry, leading designing and programming in-house web applications with Flex, Actionscript, PHP, Python and Rails and in the last 7 years I focused all my work in Java, working on Linux servers using GlassFish, TomCat, Apache and MySql.
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Back to top button