7.2 Tomcat Configuration Parameters

There are three significant parameters:

  1. Memory allocated upon Tomcat startup

    • Indicates how much memory is immediately allocated and reserved to Tomcat upon startup. This memory is used by Tomcat and is never available to the other server processes.

    • Typically, this is set to 50%-100% of the maximum memory parameter discusses below. It can be lower, but pre-allocating a sizable percentage of memory enhances performance and reduces memory fragmentation.

  2. Maximum Memory available to Tomcat

    • If the memory usage grows beyond the startup allocation, Tomcat requisitions additional blocks of memory in chunks as needed up to this limit. It never returns this memory to the general server memory pool. (Although memory internally is freed and reused for Tomcat applications).

    • Tomcat guarantees to never exceed this memory allocation parameter. If Tomcat runs out of memory, it tries to reclaim unused memory via garbage collection. If this is insufficient, the web application doesn’t receive the memory allocation. Unpredictable (but invariably unpleasant) results then occur.

    • This is the most critical parameter to tune, and is the value which is automatically tuned by the installer.

  3. Stack Size

    • For each thread (which includes each and every concurrent user request), Tomcat allocates stack space.

    • This value is typically measured in KB, and defaults to 512KB.

    • It is allocated per concurrent users, and is in fact far too generous a number in general. 1000 users for example would take 500 MB of RAM just for stack space, before the program even allocates memory to run!

    • Generally, we recommend reducing this number to 160k. Increase conservatively, in 64 KB chunks, if you see out-of-stack-space errors in the logs.

The parameters are abbreviated in the Catalina Opts line as follows:

Stack Size="-Xss<value>k"

Memory Heap="-Xms<value>g"

Maximum Memory=" -Xmx<value>g"

On Linux: edit the following configuration file:

Retain 4.0-


Retain 4.2 or higher


Retain-Tomcat is automatically tuned depending on system memory. To tune the system manually, edit the following lines with the appropriate parameters for your system. For example:

CATALINA_OPTS="-Xms4g -Xmx12g -Xss-256k"

JAVA_OPTS="$JAVA_OPTS -XX:MaxmetaspaceSize=1024m"

On Windows: run the utility to configure Tomcat and modify the appropriate settings.

Retain 4.0-

Retain 4.2 or higher