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 comma separated list of fully qualified name of classes that implement 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:-default-value} denoted parameters (with optional default values) 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 using the REPLACE_SYSTEM_PROPERTIES system property.

org.apache.tomcat.util.digester.EnvironmentPropertySource can be used to replace parameters from the process' environment variables, e.g. injected ConfigMaps or Secret objects in container based systems like OpenShift or Kubernetes.

org.apache.tomcat.util.digester.SystemPropertySource does replacement with system properties. It is always enabled, but can also be spefied as part of the property value.

org.apache.tomcat.util.digester. REPLACE_SYSTEM_PROPERTIES

Set this boolean system property to true to cause property replacement from the digester property source on the JVM system properties.

Expression Language

Property Description
org.apache.el.BeanELResolver. CACHE_SIZE

The number of jakarta.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.

Specifications

Property Description
org.apache.catalina. STRICT_SERVLET_COMPLIANCE

The default value of this system property is false.

If this is true the default values will be changed to true instead of false for:

  • org.apache.tomcat.util.http.
    ServerCookie.STRICT_NAMING
  • The alwaysAccessSession attribute of any Context element.
  • The contextGetResourceRequiresSlash attribute of any Context element.
  • The dispatcherWrapsSameObject attribute of any Context element.
  • The resourceOnlyServlets attribute of any Context element.
  • The tldValidation attribute of any Context element.
  • The useRelativeRedirects attribute of any Context element.
  • The xmlNamespaceAware attribute of any Context element.
  • The xmlValidation attribute of any Context element.
  • The sessionActivityCheck attribute of any Manager element.
  • The sessionLastAccessAtStart attribute of any Manager element.
org.apache.tomcat.websocket. STRICT_SPEC_COMPLIANCE

The default value of this system property is false.

If this is true the default values will be changed to true instead of false for:

  • org.apache.tomcat.websocket.server.WsServerContainer#isEnforceNoAddAfterHandshake
org.apache.tomcat.util.http. ServerCookie.STRICT_NAMING

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.

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).
  • invalid host names

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_BUFFER_SIZE

The default size for buffers used in the Websockets container.

The default value is 8192 which corresponds to 8KB.

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.

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 2.

jakarta.mail.Session.Factory

The class name of the factory to use to create resources of type jakarta.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.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.

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

org.apache.catalina.startup. CredentialHandlerRuleSet.MAX_NESTED_LEVELS

The NestedCredentialHandler allows nested CredentialHandlers. This property controls the maximum permitted number of levels of nesting.

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

org.apache.catalina.tribes.io. BufferPool.DEFAULT_POOL_SIZE

The size of the buffer pool which is used by Tribes in bytes.

If not specified, the default value of 100*1024*1024 (100MB) will be used.