Vault 📚

03_tomcat

7 min read

Apache Tomcat

Apache Tomcat, often referred to as Tomcat, is an open-source web server and servlet container that implements the Java Servlet, JavaServer Pages (JSP), and WebSocket specifications. Maintained by the Apache Software Foundation, Tomcat serves as a robust and lightweight platform for hosting Java-based web applications. It can also handle static resources, though it is primarily optimized for dynamic Java content. In modern enterprise environments, Tomcat plays a crucial role in serving Java EE (Jakarta EE) components and microservices.

Core Architecture and Concepts

Servlets and JSP

Tomcat implements the Servlet specification, which allows developers to create Java classes (Servlets) that respond to HTTP requests. JSP (JavaServer Pages) is a syntax for writing embedded Java code within HTML. Under the hood, Tomcat compiles JSP files into Servlets.

Catalina, Coyote, and Jasper

  1. Catalina: The heart of Tomcat. Implements the Servlet specification and manages the overall request processing pipeline.
  2. Coyote: The HTTP connector component that listens for incoming connections on TCP ports, then translates requests into a form Catalina can handle.
  3. Jasper: The JSP engine that compiles JSP files into Java classes (Servlets).

Below is a conceptual diagram of how an HTTP request flows through Tomcat:

    HTTP/HTTPS
+-----------------+
|     Client      |
+--------+--------+
         |
         | 1. Send HTTP request
         v
+-------------------------+
|        Coyote          |
| (HTTP Connector/Listener)
+-----------+------------+
            | 2. Parse HTTP request,
            |    create request object
            v
+-------------------------+
|        Catalina        |
| (Servlet Container)    |
+-----------+------------+
            | 3. Map request to a servlet or JSP
            |    via web.xml or annotations
            v
+-------------------------+
|   Servlet/JSP/Jakarta   |
|      (Application)      |
+-----------+------------+
            | 4. Application processes logic
            |    and returns a response
            v
+-------------------------+
|        Catalina        |
|  (Generates response)  |
+-----------+------------+
            | 5. Format into HTTP response
            v
+-------------------------+
|        Coyote          |
| (Sends HTTP response)  |
+-----------+------------+
            |
            | 6. Response sent back to client
            v
+-----------------+
|    Client       |
+-----------------+

Installing and Directory Structure

Installation

  1. Download the latest Tomcat binary (e.g., apache-tomcat-9.0.xx.zip or .tar.gz) from the Apache Tomcat site.
  2. Unpack it into a desired directory, such as /opt/tomcat or C:\Tomcat.
  3. Set environment variables (optional but common):
    • CATALINA_HOME: Points to the Tomcat installation directory.
    • JAVA_HOME: Points to the location of your Java SDK.

Important Directories

apache-tomcat-9.0.xx/
├── bin/               (Startup/shutdown scripts, *.bat and *.sh)
├── conf/              (Core configuration files, e.g., server.xml, web.xml)
├── lib/               (Tomcat internal libraries and dependencies)
├── logs/              (Log files for Catalina, host-manager, etc.)
├── temp/              (Temporary files)
├── webapps/           (Deployed web applications, each in its own folder or WAR)
└── work/              (Working directory for compiled JSP and session data)
  • bin: Contains scripts like startup.sh and shutdown.sh on Unix systems, or startup.bat and shutdown.bat on Windows.
  • conf: Houses the critical server.xml, which defines connectors and other global settings, and web.xml, which defines default servlet mappings and MIME types.
  • webapps: Default location for deploying WAR files or exploded web application directories.
  • logs: Stores log files (catalina.out, localhost_access_log.*, etc.).

Key Configuration Files

server.xml

conf/server.xml is Tomcat’s main configuration file. Common elements include:

<Server port="8005" shutdown="SHUTDOWN">
    <Service name="Catalina">
 
        <Connector port="8080" protocol="HTTP/1.1"
                   connectionTimeout="20000"
                   redirectPort="8443" />
        
        <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
 
        <Engine name="Catalina" defaultHost="localhost">
            <Host name="localhost"  appBase="webapps"
                  unpackWARs="true" autoDeploy="true">
            </Host>
        </Engine>
    </Service>
</Server>
  • Server: The root element. The port="8005" attribute sets the port that listens for shutdown commands.
  • Service: A collection of connectors working with a single Engine.
  • Connector: Defines how Tomcat receives requests. The default HTTP connector is on port 8080. An AJP connector might also be defined (port 8009).
  • Engine: The request processing engine, with a defaultHost referencing a <Host> element.
  • Host: Represents a virtual host. The appBase is the directory where web apps are deployed.

web.xml (Global)

conf/web.xml holds default servlet mappings and configurations shared by all web apps. It also sets MIME mappings for file extensions.

Context Configuration

Tomcat’s <Context> descriptor can appear in several places, e.g., conf/context.xml or META-INF/context.xml in each web app. It configures resources like databases (JDBC DataSources) or session manager specifics.

Deploying Applications

WAR Files and Exploded Directories

Typically, web applications are packaged as a .war (Web ARchive) file, containing Java classes, JSPs, and static assets. When dropped into CATALINA_HOME/webapps, Tomcat automatically expands it into a folder with the same name (unless auto-deployment is turned off).

For instance, if you place myapp.war in webapps, Tomcat serves it at http://localhost:8080/myapp/.

Manager Web App

Tomcat includes a “Manager” application that allows you to deploy, start, stop, or undeploy web apps via a browser interface or by using scripts. It’s accessible at http://localhost:8080/manager/html by default, although security constraints may require editing conf/tomcat-users.xml to grant roles:

<tomcat-users>
    <role rolename="manager-gui"/>
    <user username="admin" password="secret" roles="manager-gui"/>
</tomcat-users>

You can then log in and manage deployments.

CLI Deployment

You can deploy a WAR remotely using curl or other tools. Example:

curl -u admin:secret -T myapp.war "http://localhost:8080/manager/text/deploy?path=/myapp&update=true"

Handling HTTP Connectors and SSL/TLS

HTTP Connector

By default, Tomcat listens on port 8080 for HTTP traffic. You can change this in server.xml:

<Connector port="8080" protocol="HTTP/1.1" 
           connectionTimeout="20000"
           redirectPort="8443" />
  • port="8080": The TCP port.
  • connectionTimeout="20000": Waits 20 seconds for requests to send data.
  • redirectPort="8443": If the app requires SSL or a security constraint, Tomcat redirects to 8443.

Enabling HTTPS

To enable HTTPS, define an SSL connector in server.xml. You need a keystore or certificate:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" SSLEnabled="true">
    <SSLHostConfig>
        <Certificate certificateKeystoreFile="path/to/keystore.jks"
                     certificateKeystorePassword="changeit"
                     type="RSA" />
    </SSLHostConfig>
</Connector>

Clients connecting to https://server:8443/ use TLS to secure the connection.

Clustering and Session Replication

In a multi-instance setup, Tomcat can replicate HTTP session data across cluster nodes. This ensures users do not lose session data if a node fails or restarts.

<Engine name="Catalina" defaultHost="localhost" jvmRoute="node1">
    <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/>
    ...
</Engine>
  • jvmRoute="node1": Distinguishes sessions from this node.
  • <Cluster>: The element that configures session replication.
  • Typically requires additional configuration to specify membership using multicast or static IP addresses for other cluster members.

Performance Tuning

A few key points for Tomcat performance:

Thread Pool Size

Each connector has a thread pool. The default might be maxThreads="200". Under heavy load, increasing it can help handle more simultaneous requests, but too high a value can lead to thread contention or excessive CPU usage.

Connection Timeouts

Use a connectionTimeout (in milliseconds) that balances not dropping slow clients too quickly and not tying up threads indefinitely.

Keep-Alive Settings

HTTP keep-alive can reduce overhead, but holding connections open too long can consume threads. Tuning maxKeepAliveRequests or using more advanced I/O like NIO can help.

Memory Settings

Adjust the JVM’s heap size with CATALINA_OPTS or JAVA_OPTS. For example:

export CATALINA_OPTS="-Xms512m -Xmx2048m -XX:MaxPermSize=256m"

Ensure the server has enough memory to handle all threads and web app needs.

Logging and Monitoring

Look at logs/catalina.out and your web app logs for errors or performance warnings. Tools like JMX or the built-in manager’s status page can show thread usage, memory consumption, and request throughput.

Security Hardening

  1. Remove Default Apps: The examples or host-manager apps might not be needed in production.
  2. Change Shutdown Port: The default port 8005 and SHUTDOWN command are potential security exposures; consider disabling or changing them.
  3. Use Realms for Authentication: Tomcat Realms can integrate with LDAP, JDBC, or custom providers.
  4. Restrict Manager Access: Ensure only authorized IPs or users can reach the manager app.
  5. Keep Up to Date: Regularly update Tomcat to patch vulnerabilities.

Common Tasks Summary

  • Install Tomcat and set JAVA_HOME.
  • Edit server.xml to change port or configure SSL.
  • Deploy .war to webapps or via the Manager app.
  • Monitor logs and usage. Tweak thread pools, memory, timeouts.
  • Harden the server by removing unneeded apps, restricting manager, and securing ports.

Below is a condensed ASCII map of an example environment:

     Internet
         |
         | (HTTP/HTTPS on 80/443)
         v
+------------------+
|  Apache httpd    |
|  or Nginx        |  <-- Reverse proxy
+--------+---------+
         | (AJP or HTTP on 8009/8080)
         v
  +---------------+
  |    Tomcat     |
  | (multiple     |
  |  webapps)     |
  +---------------+
         |
         | Database connections (JDBC)
         v
     +-----------+
     |  MySQL    |
     |  or other |
     +-----------+

Graph View