Apache Tomcat JVM Memory Sizing Engine & Config Compiler

Tomcat Version	Minimum Java	Recommended Java	Specification / Servlet Support	Package Namespace	Lifecycle Status
Tomcat 11.0.x	Java 17	Java 21 LTS / 25	Jakarta EE 11 (Servlet 6.1, JSP 4.0, EL 6.0, WebSocket 2.2)	`jakarta.*`	Active / Latest
Tomcat 10.1.x	Java 11	Java 17 LTS / 21 LTS	Jakarta EE 10 (Servlet 6.0, JSP 3.1, EL 5.0, WebSocket 2.1)	`jakarta.*`	Long-Term Production
Tomcat 10.0.x	Java 8	Java 11 LTS	Jakarta EE 9 (Servlet 5.0, JSP 3.0) - Migration Bridge	`jakarta.*`	End of Life (EOL)
Tomcat 9.0.x	Java 8	Java 11 LTS / 17 LTS	Java EE 8 (Servlet 4.0, JSP 2.3, EL 3.0, WebSocket 1.1)	`javax.*`	Maintenance Mode
Tomcat 8.5.x	Java 7	Java 8 / 11	Java EE 7 (Servlet 3.1, JSP 2.3)	`javax.*`	End of Life (March 2024)

Critical Migration Guide: javax.* to jakarta.* Namespace

When migrating from Tomcat 9 (or older) to Tomcat 10.1 / 11, the underlying package namespace changes from javax.servlet.* to jakarta.servlet.*.

Legacy Tomcat 9 Dependency (pom.xml)

<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>4.0.1</version>
    <scope>provided</scope>
</dependency>

Modern Tomcat 10.1+ Dependency (pom.xml)

<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <version>6.0.0</version>
    <scope>provided</scope>
</dependency>

Automated Migration Tool: For legacy WAR files that cannot be recompiled, use the Apache Tomcat Migration Tool for Jakarta EE (jakartaee-migration-*.jar) to transpile bytecode automatically.

1. Linux Enterprise Installation (Ubuntu / Debian / RHEL)

Follow standard POSIX security protocols: isolate Tomcat under an unprivileged system user without interactive login shell.

1Create Dedicated System User & Directories

# Create dedicated unprivileged tomcat user & group
sudo useradd -r -m -U -d /opt/tomcat -s /bin/false tomcat

# Download and unpack Apache Tomcat 10.1.x
sudo mkdir -p /opt/tomcat
wget https://dlcdn.apache.org/tomcat/tomcat-10/v10.1.34/bin/apache-tomcat-10.1.34.tar.gz -O /tmp/tomcat.tar.gz
sudo tar -xzvf /tmp/tomcat.tar.gz -C /opt/tomcat --strip-components=1

2Configure POSIX Permissions & Directory Ownership

# Restrict ownership and lock down execution privileges
sudo chown -R tomcat:tomcat /opt/tomcat
sudo chmod -R u+rwX,g+rX,o-rwx /opt/tomcat
sudo chmod -R u+x /opt/tomcat/bin/*.sh

# Create dedicated log and heap dump folders
sudo mkdir -p /opt/tomcat/logs/heapdumps
sudo chown -R tomcat:tomcat /opt/tomcat/logs/heapdumps
sudo chmod 750 /opt/tomcat/logs/heapdumps

3Install Hardened systemd Service Unit (/etc/systemd/system/tomcat.service)

[Unit]
Description=Apache Tomcat Web Application Container
After=network.target

[Service]
Type=forking
User=tomcat
Group=tomcat

Environment="JAVA_HOME=/opt/java/jdk-17"
Environment="CATALINA_HOME=/opt/tomcat"
Environment="CATALINA_BASE=/opt/tomcat"
Environment="CATALINA_PID=/opt/tomcat/temp/tomcat.pid"

ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/opt/tomcat/bin/shutdown.sh

Restart=on-failure
RestartSec=10

# Security Sandbox Hardening
ProtectSystem=strict
ProtectHome=true
NoNewPrivileges=true
ReadWritePaths=/opt/tomcat/logs /opt/tomcat/temp /opt/tomcat/webapps /opt/tomcat/work

[Install]
WantedBy=multi-user.target

4Enable & Start Service

sudo systemctl daemon-reload
sudo systemctl enable --now tomcat
sudo systemctl status tomcat

2. Windows Server Installation & Best Practices

Avoid extracting Tomcat into directories with spaces (e.g. C:\Program Files\) to eliminate path-parsing escaping anomalies in third-party native libraries.

Recommended Target Directory: C:\Tomcat or D:\Services\Tomcat10
Service Registration: Execute service.bat install Tomcat10 via elevated Command Prompt.
Service JVM Configuration GUI: Execute tomcat10w.exe //ES//Tomcat10 to adjust memory options in the registry.

1. Linux logrotate Policy (/etc/logrotate.d/tomcat)

Standard Tomcat directs standard output and standard error unbuffered to catalina.out. The copytruncate directive is mandatory to prevent JVM file handle locking:

/opt/tomcat/logs/catalina.out {
    copytruncate
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    create 0640 tomcat tomcat
    dateext
    dateformat -%Y%m%d
    size 100M
}

copytruncate: Truncates the original file in place without renaming it, preventing Tomcat crash from lost file handles.
delaycompress: Postpones compression to the next rotation cycle so active log tailing is uninterrupted.

2. rsyslog Centralized Forwarding (/etc/rsyslog.d/30-tomcat.conf)

Forward Tomcat application and access logs directly to centralized logging clusters (Graylog, Splunk, Datadog, Elasticsearch) with reliable disk-assisted memory queues:

# Module loading for file tailing
module(load="imfile" PollingInterval="2")

# Input definition for Tomcat Access Logs
input(type="imfile"
      File="/opt/tomcat/logs/localhost_access_log.*.txt"
      Tag="tomcat-access:"
      Severity="info"
      Facility="local0")

# Input definition for Catalina Output
input(type="imfile"
      File="/opt/tomcat/logs/catalina.out"
      Tag="tomcat-catalina:"
      Severity="notice"
      Facility="local0")

# Disk-Assisted High Availability Forwarding Queue
local0.* action(type="omfwd"
        target="siem.internal.corp"
        port="514"
        protocol="tcp"
        action.resumeRetryCount="-1"
        queue.type="LinkedList"
        queue.filename="q_tomcat_fwd"
        queue.maxdiskspace="1g"
        queue.saveonshutdown="on")

3. High-Precision AccessLogValve with Latency Telemetry (%D)

Configure buffered access logging in conf/server.xml to log request duration in milliseconds (%D):

<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
       prefix="localhost_access_log" suffix=".txt"
       pattern="%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-Agent}i" %D"
       buffered="true"
       rotatable="true" />

Interactive DataSource Generator (context.xml / server.xml)

Database Engine

JNDI Name

Max Total Connections

Compiled Production <Resource> XML Fragment

<!-- PostgreSQL Production DataSource -->
<Resource name="jdbc/ProductionDB"
          auth="Container"
          type="javax.sql.DataSource"
          factory="org.apache.tomcat.dbcp.dbcp2.BasicDataSourceFactory"
          driverClassName="org.postgresql.Driver"
          url="jdbc:postgresql://db.corp.internal:5432/myapp_db?ssl=true&amp;sslmode=verify-full"
          username="app_user"
          password="StrongSecretPassword123"
          initialSize="10"
          maxTotal="100"
          maxIdle="30"
          minIdle="10"
          maxWaitMillis="10000"
          testOnBorrow="true"
          validationQuery="SELECT 1"
          testWhileIdle="true"
          timeBetweenEvictionRunsMillis="30000"
          removeAbandonedOnBorrow="true"
          removeAbandonedTimeout="60"
          logAbandoned="true" />

Connection Leak Protection: removeAbandonedOnBorrow="true" and removeAbandonedTimeout="60" automatically closes and reclaims SQL connections that unclosed application code abandoned for over 60 seconds.

1. Generate Modern PKCS12 Keystore

PKCS12 is the industry standard format replacing legacy JKS. Generate a 2048/4096-bit RSA keypair:

Linux / Windows Terminal Command

keytool -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -validity 365 \
  -keystore /opt/tomcat/conf/keystore.p12 -storetype PKCS12 \
  -storepass ChangeMe123 -keypass ChangeMe123 \
  -dname "CN=app.example.com, OU=IT, O=Enterprise, L=Riyadh, C=SA"

sudo chmod 600 /opt/tomcat/conf/keystore.p12
sudo chown tomcat:tomcat /opt/tomcat/conf/keystore.p12

2. Modern HTTPS Connector with HTTP/2 (conf/server.xml)

Configure an encrypted NIO connector with HTTP/2 multiplexing enabled on port 8443 or 443:

<!-- Modern SSL/TLS Connector with HTTP/2 Support -->
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="200" SSLEnabled="true" scheme="https" secure="true">
    <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
    <SSLHostConfig protocols="TLSv1.2+TLSv1.3"
                   ciphers="TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256">
        <Certificate certificateKeystoreFile="conf/keystore.p12"
                     certificateKeystorePassword="ChangeMe123"
                     certificateKeystoreType="PKCS12"
                     type="RSA" />
    </SSLHostConfig>
</Connector>

3. Enforce Global HTTPS Redirects (conf/web.xml)

Redirect all plain HTTP traffic automatically to secure HTTPS at the container level:

<security-constraint>
    <web-resource-collection>
        <web-resource-name>Entire Application</web-resource-name>
        <url-pattern>/*</url-pattern>
    </web-resource-collection>
    <user-data-constraint>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
</security-constraint>

1. Garbage Collection Algorithms Comparison

Collector	JVM Flags	Target Pause Latency	Recommended Heap Range	Ideal Workload
G1GC (Default)	`-XX:+UseG1GC`	50ms – 200ms	2 GB – 32 GB+	Standard enterprise web apps, balanced throughput & latency.
Generational ZGC	`-XX:+UseZGC -XX:+ZGenerational` (JDK 21+)	< 1ms (Sub-millisecond)	8 GB – 1024 GB	Ultra-low latency financial, gaming, real-time trading APIs.
ParallelGC	`-XX:+UseParallelGC`	Stop-The-World (Seconds)	512 MB – 8 GB	Batch computation, offline ETL processing, memory constrained hosts.

2. Tomcat Connector & Thread Pool Architecture (conf/server.xml)

Tuning the HTTP/1.1 and HTTP/2 NIO connector thread pool prevents thread exhaustion and request starvation:

<Connector port="8080" protocol="org.apache.coyote.http11.Http11NioProtocol"
           connectionTimeout="20000"
           maxThreads="300"
           minSpareThreads="50"
           acceptCount="100"
           maxConnections="8192"
           enableLookups="false"
           compression="on"
           compressionMinSize="2048"
           compressableMimeType="text/html,text/xml,text/plain,text/css,application/json,application/javascript" />

maxThreads: Maximum concurrent request processing threads (default 200). Rule of thumb: 1.5 × Peak Concurrent Active Requests.
minSpareThreads: Pool of warm standby threads created on boot.
acceptCount: Operating system TCP backlog queue when all worker threads are occupied.
maxConnections: Maximum open TCP keepalive connections handled asynchronously via epoll/kqueue.

1. Standard Cluster Configuration (conf/server.xml)

Place the <Cluster> element inside the <Engine> or <Host> block to enable peer-to-peer session state replication:

<Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
         channelSendOptions="8">
    <Manager className="org.apache.catalina.ha.session.DeltaManager"
             expireSessionsOnShutdown="false"
             notifyListenersOnReplication="true"/>
    <Channel className="org.apache.catalina.tribes.group.GroupChannel">
        <Membership className="org.apache.catalina.ha.mcast.McastService"
                    address="228.0.0.4"
                    port="45564"
                    frequency="500"
                    dropTime="3000"/>
        <Receiver className="org.apache.catalina.ha.tcp.nio.NioReceiver"
                  address="auto"
                  port="4000"
                  autoBind="100"
                  selectorTimeout="5000"
                  maxThreads="6"/>
        <Sender className="org.apache.catalina.ha.tcp.ReplicationTransmitter">
            <Transport className="org.apache.catalina.ha.tcp.PooledParallelSender"/>
        </Sender>
    </Channel>
</Cluster>

Webapp Prerequisite: Add <distributable/> inside your application's WEB-INF/web.xml and ensure all session attribute objects implement java.io.Serializable.

1. WAR Deployment Patterns

Root Application (/)

Deploy your artifact as webapps/ROOT.war to serve traffic on the domain root without subpath prefix.

sudo cp target/app.war /opt/tomcat/webapps/ROOT.war

Custom Context Path (/api)

Deploy your artifact as webapps/api.war or configure external context descriptor in conf/Catalina/localhost/api.xml.

<Context docBase="/var/deployments/api.war" reloadable="false" />

2. Zero-Downtime Parallel Versioned Deployments (myapp##version.war)

Tomcat natively supports parallel deployment without interrupting in-flight sessions: simply append ##<version> to the WAR filename.

# Version 1 running: existing users stay on v1
sudo cp target/app-v1.war /opt/tomcat/webapps/myapp##001.war

# Deploy Version 2: new sessions automatically route to v2; v1 drains gracefully!
sudo cp target/app-v2.war /opt/tomcat/webapps/myapp##002.war

3. GitHub Actions Automated Deployment Pipeline

name: Deploy to Production Tomcat

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
      - name: Build with Maven
        run: mvn clean package -DskipTests
      - name: Deploy WAR to Tomcat via SSH
        uses: appleboy/scp-action@master
        with:
          host: ${{ secrets.HOST }}
          username: tomcat
          key: ${{ secrets.SSH_KEY }}
          source: "target/ROOT.war"
          target: "/opt/tomcat/webapps/"

1. Essential Baseline Security Checklist

1
Delete Default Demo Webapps: Remove rm -rf /opt/tomcat/webapps/{docs,examples,manager,host-manager} to eliminate reconnaissance surfaces.
2
Mask Server Banners: Add server="Apache" or server="ApplicationServer" in <Connector> to hide exact Tomcat build versions.
3
Disable Stacktrace Leakage: Configure ErrorReportValve showReport="false" showServerInfo="false" in conf/server.xml.
4
Enforce Secure Session Cookies: Add <cookie-config><http-only>true</http-only><secure>true</secure></cookie-config> in conf/web.xml.

2. NGINX Reverse Proxy Configuration & RemoteIpValve

When placing Tomcat behind NGINX, HAProxy, or AWS Application Load Balancer, enable RemoteIpValve in conf/server.xml to correctly capture client IP addresses:

Tomcat conf/server.xml

<Valve className="org.apache.catalina.valves.RemoteIpValve"
       internalProxies="10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|127\.0\.0\.1"
       remoteIpHeader="x-forwarded-for"
       protocolHeader="x-forwarded-proto" />

NGINX /etc/nginx/conf.d/tomcat.conf

server {
    listen 80;
    server_name app.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name app.example.com;

    ssl_certificate /etc/letsencrypt/live/app.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Incident Diagnosis & Remediation Library

💥 java.lang.OutOfMemoryError: Java heap space ▼

Root Cause: Application memory allocations exceeded -Xmx capacity, or an uncollected object graph caused a memory leak.

Remediation Steps:

Verify memory sizing via our Sizing Generator: ensure -Xmx does not exceed safe ceiling (X_{mx_max}).
Analyze generated heap dump (-XX:+HeapDumpOnOutOfMemoryError) using Eclipse Memory Analyzer (MAT) or VisualVM.
Check for common leaks: static collections, unclosed ThreadLocal variables, or unclosed database resultsets.

⚠️ java.lang.OutOfMemoryError: Metaspace ▼

Root Cause: Native memory allocated for class metadata exceeded -XX:MaxMetaspaceSize, frequently caused by repeated application redeployments without Tomcat restarts (Classloader leaks).

Remediation Steps:

Increase Metaspace quota to -XX:MaxMetaspaceSize=1024m for Spring/Hibernate applications.
In staging/production, select Unbounded (JVM Default) in our generator to let JVM dynamically scale metadata native arenas.
Trigger full JVM service restart upon application version updates.

🚫 Port Collision: Address already in use (BindException: 8080 / 8005) ▼

Root Cause: Another process (or an orphaned zombie Tomcat process) is already bound to HTTP port 8080 or shutdown port 8005.

Remediation Steps:

# Linux: Find process PID and kill
sudo lsof -i :8080
sudo kill -9 <PID>

# Windows: Find process and terminate
netstat -ano | findstr :8080
taskkill /F /PID <PID>

🔍 CPU Spikes & High Thread Latency (Thread Dump Analysis) ▼

Remediation Steps: Capture 3 sequential thread dumps 10 seconds apart to detect deadlocks and blocked worker threads:

# Using modern jcmd utility
jcmd $(pgrep -f catalina) Thread.print > /tmp/threaddump_1.txt
sleep 10
jcmd $(pgrep -f catalina) Thread.print > /tmp/threaddump_2.txt

1. Target Architecture & Runtime Environment

Deployment Environment Profile

Java Runtime Version

Tomcat Launch Mode

JVM Garbage Collector

2. Resource Budgeting & Sizing Engine

Effective Memory Pool (Meffective)

Initial vs Maximum Heap

Max Metaspace (-XX:MaxMetaspaceSize)

Thread Call Stacks & Direct Memory

3. Java Runtime Paths & Diagnostic Telemetry

JAVA_HOME Path

OutOfMemoryError Diagnostic Dump

Application Timezone

Custom JVM Arguments

4. Compiled Production Configuration Artifact

Critical Migration Guide: javax.* to jakarta.* Namespace

1. Linux Enterprise Installation (Ubuntu / Debian / RHEL)

2. Windows Server Installation & Best Practices

1. Linux logrotate Policy (/etc/logrotate.d/tomcat)

2. rsyslog Centralized Forwarding (/etc/rsyslog.d/30-tomcat.conf)

3. High-Precision AccessLogValve with Latency Telemetry (%D)

Interactive DataSource Generator (context.xml / server.xml)

1. Generate Modern PKCS12 Keystore

2. Modern HTTPS Connector with HTTP/2 (conf/server.xml)

3. Enforce Global HTTPS Redirects (conf/web.xml)

1. Garbage Collection Algorithms Comparison

2. Tomcat Connector & Thread Pool Architecture (conf/server.xml)

1. Standard Cluster Configuration (conf/server.xml)

1. WAR Deployment Patterns

2. Zero-Downtime Parallel Versioned Deployments (myapp##version.war)

3. GitHub Actions Automated Deployment Pipeline

1. Essential Baseline Security Checklist

2. NGINX Reverse Proxy Configuration & RemoteIpValve

Incident Diagnosis & Remediation Library

Paste Raw Thread Dump

Thread Telemetry Diagnosis

Effective Memory Pool (M_effective)