System Properties

Table of Contents

Introduction

The following sections list the system properties that may be set to modify
the default Tomcat behaviour.

Property replacements

Property

Description

org.apache.tomcat.util.digester. PROPERTY_SOURCE

Set this to a fully qualified name of a class that implements
org.apache.tomcat.util.IntrospectionUtils.PropertySource.
Required to have a public constructor with no arguments.

Use this to add a property source, that will be invoked when ${parameter}
denoted parameters are found in the XML files that Tomcat parses.

Property replacement from the specified property source on the JVM
system properties can also be done by adding the
org.apache.catalina.util.SystemPropertyReplacerListener
listener as a Server listener in the container.

Clustering

Property

Description

org.apache.catalina. tribes.dns_lookups

If true, the clustering module will attempt to use DNS to
resolve any host names provided in the cluster configuration.

If not specified, the default value of false will be used.

Expression Language

Property

Description

org.apache.el.BeanELResolver. CACHE_SIZE

The number of javax.el.BeanELResolver.BeanProperties objects that will
be cached by the EL Parser.

If not specified, the default of 1000 will be used.

org.apache.el.ExpressionBuilder. CACHE_SIZE

The number of parsed EL expressions that will be cached by the EL
Parser.

If not specified, the default of 5000 will be used.

org.apache.el.parser. COERCE_TO_ZERO

If true, when coercing nulls to objects of
type Number, Character or Boolean the result will be 0 for
Number and Character types and false for Boolean as required
by the EL 2.2 and earlier specifications. If this property is
false the result of the coercion will be null as
required by the EL 3.0 specification.

If not specified, the default value of false will be
used.

org.apache.el.parser. SKIP_IDENTIFIER_CHECK

If true, when parsing expressions, identifiers will not be
checked to ensure that they conform to the Java Language Specification for
Java identifiers.

If not specified, the default value of false will be used.

Jasper

Property

Description

org.apache.jasper.compiler. Generator.POOL_TAGS_WITH_EXTENDS

By default, JSPs that use their own base class via the extends
attribute of the page directive, will have Tag pooling disabled since
Jasper cannot guarantee that the necessary initialisation will have taken
place. This can have a negative impact on performance. Providing the
alternative base class calls _jspInit() from Servlet.init(), setting this
property to true will enable pooling with an alternative base
class. If the alternative base class does not call _jspInit() and this
property is true, NPEs will occur when attempting to use
tags.

If not specified, the default value of false will be used.

org.apache.jasper.compiler. Generator.STRICT_GET_PROPERTY

If true, the requirement to have the object referenced in
jsp:getProperty action to be previously "introduced"
to the JSP processor, as specified in the chapter JSP.5.3 of JSP 2.0 and
later specifications, is enforced.

If not specified, the specification compliant default of
true will be used.

org.apache.jasper.compiler. Generator.VAR_EXPRESSIONFACTORY

The name of the variable to use for the expression language expression
factory.

If not specified, the default value of _el_expressionfactory
will be used.

org.apache.jasper.compiler. Generator.VAR_INSTANCEMANAGER

The name of the variable to use for the instance manager factory.

If not specified, the default value of _jsp_instancemanager
will be used.

org.apache.jasper.compiler. Parser.STRICT_WHITESPACE

If false the requirements for whitespace before an
attribute name will be relaxed so that the lack of whitespace will not
cause an error.

If not specified, the specification compliant default of
true will be used.

org.apache.jasper.runtime. BodyContentImpl.LIMIT_BUFFER

If true, any tag buffer that expands beyond
org.apache.jasper.Constants.DEFAULT_TAG_BUFFER_SIZE will be
destroyed and a new buffer created of the default size.

If not specified, the default value of false will be used.

org.apache.jasper.runtime. JspFactoryImpl.USE_POOL

If true, a ThreadLocal PageContext pool will
be used.

If not specified, the default value of true will be used.

org.apache.jasper.runtime. JspFactoryImpl.POOL_SIZE

The size of the ThreadLocal PageContext.

If not specified, the default value of 8 will be used.

org.apache.jasper.Constants. JSP_SERVLET_BASE

The base class of the Servlets generated from the JSPs.

If not specified, the default value of
org.apache.jasper.runtime.HttpJspBase will be used.

org.apache.jasper.Constants. SERVICE_METHOD_NAME

The name of the service method called by the base class.

If not specified, the default value of _jspService
will be used.

org.apache.jasper.Constants. SERVLET_CLASSPATH

The name of the ServletContext attribute that provides the classpath
for the JSP.

If not specified, the default value of
org.apache.catalina.jsp_classpath will be used.

org.apache.jasper.Constants. JSP_FILE

The name of the request attribute for <jsp-file>
element of a servlet definition. If present on a request, this overrides
the value returned by request.getServletPath() to select the
JSP page to be executed.

If not specified, the default value of
org.apache.catalina.jsp_file will be used.

Deprecated: This will be removed in Tomcat 9.0.x
onwards. It is replaced by the use of the jspFile servlet initialisation
parameter

org.apache.jasper.Constants. PRECOMPILE

The name of the query parameter that causes the JSP engine to just
pregenerate the servlet but not invoke it.

If not specified, the default value of jsp_precompile
will be used, as defined by JSP specification (JSP.11.4.2).

org.apache.jasper.Constants. JSP_PACKAGE_NAME

The default package name for compiled jsp pages.

If not specified, the default value of org.apache.jsp
will be used.

org.apache.jasper.Constants. TAG_FILE_PACKAGE_NAME

The default package name for tag handlers generated from tag files.

If not specified, the default value of org.apache.jsp.tag
will be used.

org.apache.jasper.Constants. ALT_DD_ATTR

The servlet context attribute under which the alternate deployment
descriptor for this web application is stored.

If not specified, the default value of
org.apache.catalina.deploy.alt_dd will be used.

org.apache.jasper.Constants. TEMP_VARIABLE_NAME_PREFIX

Prefix to use for generated temporary variable names.

If not specified, the default value of _jspx_temp
will be used.

org.apache.jasper.Constants. USE_INSTANCE_MANAGER_FOR_TAGS

If true, the instance manager is used to obtain tag
handler instances.

If not specified, the default value of false will be used.

Security

Property

Description

org.apache.catalina.connector. RECYCLE_FACADES

If this is true or if a security manager is in use a new
facade object will be created for each request.

If not specified, the default value of false will be used.

org.apache.catalina.connector. CoyoteAdapter.ALLOW_BACKSLASH

If this is true the '\' character will be permitted as a
path delimiter.

If this is true then
a call to Response.getWriter() if no character encoding
has been specified will result in subsequent calls to
Response.getCharacterEncoding() returning
ISO-8859-1 and the Content-Type response header
will include a charset=ISO-8859-1 component. (SRV.15.2.22.1)

If not specified, the default specification compliant value of
true will be used.

If this is true then the path passed to
ServletContext.getResource() or
ServletContext.getResourceAsStream() must start with
"/". If false, code like
getResource("myfolder/myresource.txt") will work as Tomcat
will prepend "/" to the provided path.

If org.apache.catalina.STRICT_SERVLET_COMPLIANCE is set to
true, the default of this setting will be true,
else the default value will be false.

org.apache.catalina.core. ApplicationDispatcher.WRAP_SAME_OBJECT

If this is true then any wrapped request or response
object passed to an application dispatcher will be checked to ensure that
it has wrapped the original request or response.

If org.apache.catalina.STRICT_SERVLET_COMPLIANCE is set to
true, the default of this setting will be true,
else the default value will be false.

If this is true then the requirements of the Servlet specification
that Cookie names must adhere to RFC2109 will be enforced. If this is
false the naming rules specified in RFC6265 (allow the leading "$")
will be used.

If org.apache.catalina.STRICT_SERVLET_COMPLIANCE is set to
true, the default of this setting will be true,
else the default value will be false.

Sessions

Property

Description

org.apache.catalina.authenticator. Constants.SSO_SESSION_COOKIE_NAME

An alternative name for the single sign on session cookie. Defaults to
JSESSIONIDSSO.

org.apache.catalina.core. StandardHostValve.ACCESS_SESSION

If this is true, every request that is associated with a
session will cause the session's last accessed time to be updated
regardless of whether or not the request explicitly accesses the session.

If org.apache.catalina.STRICT_SERVLET_COMPLIANCE is set to
true, the default of this setting will be true,
else the default value will be false.

org.apache.catalina.session. StandardSession.ACTIVITY_CHECK

If this is true, Tomcat will track the number of active
requests for each session. When determining if a session is valid, any
session with at least one active request will always be considered valid.

If org.apache.catalina.STRICT_SERVLET_COMPLIANCE is set to
true, the default of this setting will be true,
else the default value will be false.

org.apache.catalina.session. StandardSession.LAST_ACCESS_AT_START

If this is true, the last accessed time for sessions will
be calculated from the beginning of the previous request. If
false, the last accessed time for sessions will be calculated
from the end of the previous request. This also affects how the idle time
is calculated.

If org.apache.catalina.STRICT_SERVLET_COMPLIANCE is set to
true, the default of this setting will be true,
else the default value will be false.

Logging

Property

Description

org.apache.juli.formatter

If no logging configuration file is specified and no logging configuration class is specified
using the java.util.logging.config.class and java.util.logging.config.file
properties the default logging framework org.apache.juli will use the default
java.util.logging.SimpleFormatter for all console output.
To simply override the console output formatter, one can use the described property. Example:
-Dorg.apache.juli.formatter=org.apache.juli.OneLineFormatter

org.apache.juli. AsyncMaxRecordCount

The maximum number of log records that the JULI AsyncFileHandler will queue in memory.
New records are added to the queue and get asynchronously removed from the queue
and written to the files by a single writer thread.
When the queue is full and a new record is being logged
the log record will be handled based on the org.apache.juli.AsyncOverflowDropType setting.

The default value is 10000 records.
This number represents the global number of records, not on a per handler basis.

org.apache.juli. AsyncOverflowDropType

When the queue of log records of the JULI AsyncFileHandler is full,
new log records are handled according to the following setting:

1 - the newest record in the queue will be dropped and not logged

2 - the oldest record in the queue will be dropped and not logged

3 - suspend the logging thread until older records got written to the log file and the queue is no longer full.
This is the only setting that ensures that no messages get lost.

4 - drop the current log record

The default value is 1 (drop the newest record in the queue).

org.apache.juli. AsyncLoggerPollInterval

The poll interval in milliseconds for the asynchronous logger thread.
If the log queue is empty, the async thread will issue a poll(poll interval)
in order to not wake up too often.

The default value is 1000 milliseconds.

org.apache.juli.logging. UserDataHelper.CONFIG

The type of logging to use for errors generated by invalid input data.
The options are: DEBUG_ALL, INFO_THEN_DEBUG,
INFO_ALL and NONE. When
INFO_THEN_DEBUG is used, the period for which errors are
logged at DEBUG rather than INFO is controlled by the system property
org.apache.juli.logging.UserDataHelper.SUPPRESSION_TIME.

The default value is INFO_THEN_DEBUG.

The errors currently logged using this system are:

invalid cookies;

invalid parameters;

too many headers, too many parameters (hitting
maxHeaderCount or maxParameterCount limits
of a connector).

Other errors triggered by invalid input data may be added to this
system in later versions.

org.apache.juli.logging. UserDataHelper.SUPPRESSION_TIME

When using INFO_THEN_DEBUG for
org.apache.juli.logging.UserDataHelper.CONFIG this system
property controls how long messages are logged at DEBUG after a message
has been logged at INFO. Once this period has elapsed, the next message
will be logged at INFO followed by a new suppression period where
messages are logged at DEBUG and so on. The value is measured
in seconds.

A value of 0 is equivalent to using INFO_ALL
for org.apache.juli.logging.UserDataHelper.CONFIG.

A negative value means an infinite suppression period.

The default value is 86400 (24 hours).

JAR Scanning

Property

Description

tomcat.util.scan. StandardJarScanFilter.jarsToSkip

A list of comma-separated file name patters that is used as the default
value for pluggabilitySkip and tldSkip
attributes of the standard
JarScanFilter implementation.

The coded default is empty, however the system property is set in
a default Tomcat installation via the
$CATALINA_BASE/conf/catalina.properties file.

tomcat.util.scan. StandardJarScanFilter.jarsToScan

A list of comma-separated file name patters that is used as the default
value for pluggabilityScan and tldScan
attributes of the standard
JarScanFilter implementation.

The coded default is empty, however the system property is set in
a default Tomcat installation via the
$CATALINA_BASE/conf/catalina.properties file.

Websockets

Property

Description

org.apache.tomcat. websocket.ALLOW_UNSUPPORTED_EXTENSIONS

If true, allow unknown extensions to be declared by
the user.

The default value is false.

org.apache.tomcat. websocket.DEFAULT_ORIGIN_HEADER_VALUE

Default value of the origin header that will be sent by the client
during the upgrade handshake.

The default is null so that no origin header is sent.

org.apache.tomcat. websocket.DEFAULT_PROCESS_PERIOD

The number of periodic ticks between periodic processing which
involves in particular session expiration checks.

The default value is 10 which corresponds to 10
seconds.

org.apache.tomcat. websocket.DISABLE_BUILTIN_EXTENSIONS

If true, disable all built-in extensions provided by the
server, such as message compression.

The default value is false.

org.apache.tomcat. websocket.STREAMS_DROP_EMPTY_MESSAGES

If true, streams provided to the user (writer and output
stream) will not send an empty message when flushing and there is no
data to flush, or when it is closed without having been used (for
example if an error occurs).

The default value is false.

Other

Property

Description

catalina.useNaming

If this is false it will override the
useNaming attribute for all
Context elements.

javax.sql.DataSource.Factory

The class name of the factory to use to create resources of type
javax.sql.DataSource. If not specified the default of
org.apache.tomcat.dbcp.dbcp2.BasicDataSourceFactory is used
which is a package renamed (to avoid conflicts) copy of
Apache Commons DBCP.

javax.mail.Session.Factory

The class name of the factory to use to create resources of type
javax.mail.Session. If not specified the default of
org.apache.naming.factory.MailSessionFactory is used.

jvmRoute

Provides a default value for the jvmRoute attribute of the
Engine element. It does not override the value
configured on the Engine element.

catalina.config

The location from which to load the catalina.properties configuration
file. This may be an absolute URL, a relative (to the current working
directory) URL or an alternative file name in which case Tomcat will
attempt to load the file from the default location of
$CATALINA_BASE/conf/.

tomcat.util.buf.StringCache.byte.enabled

If true, the String cache is enabled for
ByteChunk.

If not specified, the default value of false will be used.

tomcat.util.buf.StringCache.char.enabled

If true, the String cache is enabled for
CharChunk.

If not specified, the default value of false will be used.

tomcat.util.buf.StringCache.trainThreshold

The number of times toString() must be called before the
cache is activated.

If not specified, the default value of 20000 will be used.

tomcat.util.buf.StringCache.cacheSize

The size of the String cache.

If not specified, the default value of 200 will be used.

org.apache.tomcat.util.buf.UriUtil. WAR_SEPARATOR

The character to use to separate the WAR file and WAR content parts of
a WAR URL using the custom WAR scheme provided by Tomcat. This is
equivalent to how ! is used in JAR URLs.

If not specified, the default value of * will be used.

tomcat.util.buf.StringCache.maxStringSize

The maximum length of String that will be cached.

If not specified, the default value of 128 will be used.

org.apache.tomcat.util. http.FastHttpDateFormat.CACHE_SIZE

The size of the cache to use parsed and formatted date value.

If not specified, the default value of 1000 will be used.

org.apache.tomcat.util. net.NioSelectorShared

If true, use a shared selector for servlet write/read.

If not specified, the default value of true will be used.

org.apache.catalina.startup. EXIT_ON_INIT_FAILURE

If true, the server will exit if an exception happens
during the server initialization phase. To support this feature, this
system property is used as the default for the
throwOnFailure attribute of a Connector.

If not specified, the default value of false will be
used.

org.apache.catalina.startup. RealmRuleSet.MAX_NESTED_REALM_LEVELS

The CombinedRealm allows nested Realms. This property controls the
maximum permitted number of levels of nesting.