Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 37 ยท Security and TLS

Hardening Apache Tomcat for Production

A practical Tomcat hardening checklist: remove default apps, run as a non-root user, shut down the shutdown port, hide version info and lock down error pages.

A freshly unpacked Tomcat is built to be convenient, not locked down. It ships with sample applications, a manager web app, a shutdown port that accepts a plain-text word, error pages that print the version number and a stack trace, and an AJP connector in older releases. Each one is a small risk. Hardening means working through that list so the server shows attackers as little as possible and does as little as possible with its privileges.

This lesson is a checklist you can apply to any installation. The settings are read-only (Tomcat cannot run on this site), and a runnable Java stand-in turns the checklist into an automatic audit of a configuration.

1. Run as an unprivileged user

Never run Tomcat as root or Administrator. Create a dedicated account such as tomcat, give it ownership of logs, temp, work and webapps only, and keep conf read-only for it:

Terminal
useradd --system --home /opt/tomcat --shell /usr/sbin/nologin tomcat
chown -R root:tomcat /opt/tomcat/conf && chmod -R g=r,o= /opt/tomcat/conf
chown -R tomcat:tomcat /opt/tomcat/{logs,temp,work,webapps}

Ports below 1024 need root on Linux. Instead of running as root, listen on 8080 or 8443 and forward 80/443 with a firewall rule or a reverse proxy.

2. Remove what you do not use

Delete webapps/docs, webapps/examples, webapps/ROOT (replace it with your own), and if you do not use them manager and host-manager. The example servlets have a history of vulnerabilities. If you keep the manager, restrict it with a RemoteCIDRValve (see valves and access control) and give it a strong password.

Also disable the AJP connector unless you need it. The "Ghostcat" bug (CVE-2020-1938) allowed file reads through an exposed AJP port. Since Tomcat 9.0.31 AJP is off by default and requires a secret when enabled. In server.xml, keep the line commented out or bind it to localhost with a secret.

3. Neutralize the shutdown port

The <Server port="8005" shutdown="SHUTDOWN"> line lets anyone who can reach the port stop Tomcat by sending the word. It only listens on localhost by default, but on shared hosts any local user can use it. Disable it with port="-1", and stop Tomcat through the service manager instead:

XML
<Server port="-1" shutdown="SHUTDOWN">

4. Hide the version and stack traces

By default error pages show Apache Tomcat/11.0.x and, for uncaught exceptions, a stack trace. Both help attackers. Add the ErrorReportValve settings to the <Host> and keep the server header generic:

XML
<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="false">
  <Valve className="org.apache.catalina.valves.ErrorReportValve"
         showReport="false" showServerInfo="false"/>
</Host>

<Connector port="8080" protocol="HTTP/1.1" server="web" xpoweredBy="false" />

In each application add <error-page> entries to web.xml for 404 and 500 that show friendly pages. Setting autoDeploy="false" also stops Tomcat from deploying anything someone drops into webapps while running.

5. Restrict what applications may do

  • Set allowTrace="false" (default) so the TRACE method stays off, and consider limiting methods to those you need in web.xml.
  • Add useHttpOnly="true" (default) and secure flags to the session cookie: <cookie-config><http-only>true</http-only><secure>true</secure></cookie-config>.
  • Set maxPostSize, maxHttpHeaderSize and maxParameterCount on connectors so oversized requests are refused early.
  • Prefer the HttpHeaderSecurityFilter for X-Content-Type-Options, X-Frame-Options and HSTS.
  • Keep Tomcat and the JDK patched. Follow tomcat-announce for security releases.

The Java Security Manager that older guides recommend was deprecated in Java 17 and is not available in Tomcat 11, so use OS-level isolation (containers, a dedicated user, SELinux or AppArmor) instead.

An automatic audit

A hardening checklist is easiest to keep when a script checks it. The stand-in below takes a configuration as simple key/value pairs (the parsing of XML is left out) and prints findings. It shows how you might wire such a check into a deployment pipeline.

Java Stand-in: configuration audit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Secrets and file permissions

Do not leave passwords in server.xml. Tomcat can read property placeholders such as ${db.password} from system properties, so pass them with -Ddb.password=... from a protected environment file read by the service unit. For context.xml data sources, the same placeholders work. Set file modes so only root and the tomcat group can read conf/. The default umask of 0027 in catalina.sh (set UMASK="0027") stops log files from being world-readable.

A simple permissions check

The next stand-in compares a file's POSIX mode to what the hardening guide asks for. Tomcat's own scripts do not do this, but a post-install check does:

Java Stand-in: permission check

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should Tomcat not run as root?

    A process runs with its user's privileges, so a dedicated low-privilege account limits what a successful attack can do.
  2. 2. How do you disable the shutdown port?

    port="-1" turns the shutdown listener off; stop Tomcat with the service manager or a signal instead.
  3. 3. What does ErrorReportValve showReport="false" do?

    The valve still produces an error page but omits the exception report that reveals internals.
  4. 4. Which connector had the Ghostcat vulnerability?

    CVE-2020-1938 affected exposed AJP ports; AJP now needs a secret and is disabled by default.

Summary

  • Run as a dedicated unprivileged user and keep conf read-only.
  • Remove sample and management apps you do not use; secure or disable AJP.
  • Disable the shutdown port, hide versions and stack traces, turn off autoDeploy.
  • Set cookie flags, size limits and security headers; keep Tomcat and Java patched.
  • Automate the checklist so every deployment is audited.

Next: Valves, filters and access control