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.
Table Of Contents
- 1. The tools
- 2. Introduction
- 3. Prerequisites
- 4. Run Tomcat as Unprivileged User
- 5. Restrict access to critical files
- 6. Use a Firewall
- 7. Remove Default Tomcat Applications
- 8. Change default index page
- 9. Remove version string from HTTP error messages
- 10. Replace default error page
- 11. Replace default server.xml
- 12. Replace server version string
- 13. Put Tomcat’s shutdown procedure on lock-down
- 14. Protecting the Shutdown Port
- 15. Try to use the latest stable version of Tomcat
- 16. Maintain And Use Logs
- 17. Securing Manager WebApp
- 18. Running Tomcat with a Security Manager
- 19. Enforced HTTPS
- 20. Conclusion
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/catalina.sh 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
<servlet>
<servlet-name>default</servlet-name>
<servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
<init-param>
<param-name>debug</param-name>
<param-value>0</param-value>
</init-param>
<init-param>
<param-name>listings</param-name>
<param-value>false</param-value> <!-- make sure this is false -->
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
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 ServerInfo.properties file.
unpack
cd CATALINA_HOME/server/lib jar xf catalina.jar org/apache/catalina/util/ServerInfo.properties
update ServerInfo.properties by changing server.info line to server.info=Apache Tomcat repackage catalina.jar
repack
jar uf catalina.jar org/apache/catalina/util/ServerInfo.properties
remove CATALINA_HOME/server/lib/org (created when extracting the ServerInfo.properties 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
<error-page> <exception-type>java.lang.Throwable</exception-type> <location>/error.jsp</location> </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"
connectionTimeout="20000"
redirectPort="8443"
server="Apache"/>
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 logging.properties 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).
logs
handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler
org.apache.juli.FileHandler.level = ALL
org.apache.juli.FileHandler.directory = ${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.
password
<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.
security-constraint
<security-constraint>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
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:
HTTPS
<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"
URIEncoding="UTF-8"
maxHttpHeaderSize="32768"/>
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
