Links Top Level Elements Executors Connectors Containers Nested Components Cluster Elements Other | Container Provided Filters| Introduction |
Tomcat provides a number of Filters which may be
configured for use with all web applications using
$CATALINA_BASE/conf/web.xml or may be configured for individual
web applications by configuring them in the application's
WEB-INF/web.xml. Each filter is described below.
This description uses the variable name $CATALINA_BASE to refer the
base directory against which most relative paths are resolved. If you have
not configured Tomcat for multiple instances by setting a CATALINA_BASE
directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
the directory into which you have installed Tomcat.
|
| Add Default Character Set Filter |
| Introduction |
The HTTP specification is clear that if no character set is specified for
media sub-types of the "text" media type, the ISO-8859-1 character set must
be used. However, browsers may attempt to auto-detect the character set.
This may be exploited by an attacker to perform an XSS attack. Internet
Explorer has this behaviour by default. Other browsers have an option to
enable it.
This filter prevents the attack by explicitly setting a character set.
Unless the provided character set is explicitly overridden by the user the
browser will adhere to the explicitly set character set, thus preventing the
XSS attack.
|
| Filter Class Name |
The filter class name for the Add Default Character Set Filter is
org.apache.catalina.filters.AddDefaultCharsetFilter
.
|
| Initialisation parameters |
The Add Default Character Set Filter supports the following initialization
parameters:
| Attribute | Description |
|---|
encoding |
Name of the character set which should be set, if no other character set
was set explicitly by a Servlet. This parameter has two special values
default and system. A value of system
uses the JVM wide default character set, which is usually set by locale.
A value of default will use ISO-8859-1.
|
|
|
| CORS Filter |
| Filter Class Name |
The filter class name for the CORS Filter is
org.apache.catalina.filters.CorsFilter.
|
| Initialisation parameters |
The CORS Filter supports following initialisation parameters:
| Attribute | Description |
|---|
cors.allowed.origins |
A list of origins
that are allowed to access the resource. A * can be
specified to enable access to resource from any origin. Otherwise, a
whitelist of comma separated origins can be provided. Eg:
http://www.w3.org, https://www.apache.org.
Defaults: * (Any origin is allowed to
access the resource).
| cors.allowed.methods |
A comma separated list of HTTP methods that can be used to access the
resource, using cross-origin requests. These are the methods which will
also be included as part of Access-Control-Allow-Methods
header in pre-flight response. Eg: GET, POST.
Defaults: GET, POST, HEAD, OPTIONS
| cors.allowed.headers |
A comma separated list of request headers that can be used when
making an actual request. These headers will also be returned as part
of Access-Control-Allow-Headers header in a pre-flight
response. Eg: Origin,Accept. Defaults:
Origin, Accept, X-Requested-With, Content-Type,
Access-Control-Request-Method, Access-Control-Request-Headers
| cors.exposed.headers |
A comma separated list of headers other than simple response headers
that browsers are allowed to access. These are the headers which will
also be included as part of Access-Control-Expose-Headers
header in the pre-flight response. Eg:
X-CUSTOM-HEADER-PING,X-CUSTOM-HEADER-PONG.
Default: None. Non-simple headers are not exposed by
default.
| cors.preflight.maxage |
The amount of seconds, browser is allowed to cache the result of the
pre-flight request. This will be included as part of
Access-Control-Max-Age header in the pre-flight response.
A negative value will prevent CORS Filter from adding this response
header to pre-flight response. Defaults:
1800
| cors.support.credentials |
A flag that indicates whether the resource supports user credentials.
This flag is exposed as part of
Access-Control-Allow-Credentials header in a pre-flight
response. It helps browser determine whether or not an actual request
can be made using credentials. Defaults:
true
| cors.request.decorate |
A flag to control if CORS specific attributes should be added to
HttpServletRequest object or not. Defaults:
true
|
Here's an example of a more advanced configuration, that overrides
defaults:
 | | | |
<filter>
<filter-name>CorsFilter</filter-name>
<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
<init-param>
<param-name>cors.allowed.origins</param-name>
<param-value>*</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.methods</param-name>
<param-value>GET,POST,HEAD,OPTIONS,PUT</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.headers</param-name>
<param-value>Content-Type,X-Requested-With,accept,Origin,Access-Control-Request-Method,Access-Control-Request-Headers</param-value>
</init-param>
<init-param>
<param-name>cors.exposed.headers</param-name>
<param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</param-value>
</init-param>
<init-param>
<param-name>cors.support.credentials</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>cors.preflight.maxage</param-name>
<param-value>10</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CorsFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
| | | | |
|
| CORS Filter and HttpServletRequest attributes |
CORS Filter adds information about the request, in HttpServletRequest
object, for consumption downstream. Following attributes are set, if
cors.request.decorate initialisation parameter is
true:
- cors.isCorsRequest: Flag to determine if request is
a CORS request.
- cors.request.origin: The Origin URL, i.e. the URL of
the page from where the request originated.
- cors.request.type: Type of CORS request. Possible
values:
SIMPLE: A request which is not preceded by a
pre-flight request.ACTUAL: A request which is preceded by a pre-flight
request.PRE_FLIGHT: A pre-flight request.NOT_CORS: A normal same-origin request.INVALID_CORS: A cross-origin request, which is
invalid.
- cors.request.headers: Request headers sent as
Access-Control-Request-Headers header, for a pre-flight
request.
|
|
| CSRF Prevention Filter |
| Introduction |
This filter provides basic CSRF protection for a web application. The
filter assumes that it is mapped to /* and that all URLs
returned to the client are encoded via a call to
HttpServletResponse#encodeRedirectURL(String) or
HttpServletResponse#encodeURL(String).
This filter prevents CSRF by generating a nonce and storing it in the
session. URLs are also encoded with the same nonce. When the next request is
received the nonce in the request is compared to the nonce in the session
and only if they are the same is the request allowed to continue.
|
| Filter Class Name |
The filter class name for the CSRF Prevention Filter is
org.apache.catalina.filters.CsrfPreventionFilter
.
|
| Initialisation parameters |
The CSRF Prevention Filter supports the following initialisation
parameters:
| Attribute | Description |
|---|
denyStatus |
HTTP response status code that is used when rejecting denied
request. The default value is 403.
| entryPoints |
A comma separated list of URLs that will not be tested for the
presence of a valid nonce. They are used to provide a way to navigate
back to a protected application after having navigated away from it.
Entry points will be limited to HTTP GET requests and should not trigger
any security sensitive actions.
| nonceCacheSize |
The number of previously issued nonces that will be cached on a LRU
basis to support parallel requests, limited use of the refresh and back
in the browser and similar behaviors that may result in the submission
of a previous nonce rather than the current one. If not set, the default
value of 5 will be used.
| randomClass |
The name of the class to use to generate nonces. The class must be an
instance of java.util.Random. If not set, the default value
of java.security.SecureRandom will be used.
|
|
|
| Expires Filter |
| Introduction |
ExpiresFilter is a Java Servlet API port of Apache
mod_expires.
This filter controls the setting of the Expires HTTP header and the
max-age directive of the Cache-Control HTTP header in
server responses. The expiration date can set to be relative to either the
time the source file was last modified, or to the time of the client access.
These HTTP headers are an instruction to the client about the document's
validity and persistence. If cached, the document may be fetched from the
cache rather than from the source until this time has passed. After that, the
cache copy is considered "expired" and invalid, and a new copy must
be obtained from the source.
To modify Cache-Control directives other than max-age (see
RFC
2616 section 14.9), you can use other servlet filters or Apache Httpd
mod_headers module.
|
| Expiration headers generation eligibility |
A response is eligible to be enriched by ExpiresFilter if :
- no expiration header is defined (
Expires header or the
max-age directive of the Cache-Control header),
- the response status code is not excluded by the directive
ExpiresExcludedResponseStatusCodes,
- the
Content-Type of the response matches one of the types
defined the in ExpiresByType directives or the
ExpiresDefault directive is defined.
Note : If Cache-Control header contains other directives than
max-age, they are concatenated with the max-age directive
that is added by the ExpiresFilter.
|
| Expiration configuration selection |
The expiration configuration if elected according to the following algorithm:
ExpiresByType matching the exact content-type returned by
HttpServletResponse.getContentType() possibly including the charset
(e.g. 'text/xml;charset=UTF-8'),ExpiresByType matching the content-type without the charset if
HttpServletResponse.getContentType() contains a charset (e.g. '
text/xml;charset=UTF-8' -> 'text/xml'),ExpiresByType matching the major type (e.g. substring before
'/') of HttpServletResponse.getContentType()
(e.g. 'text/xml;charset=UTF-8' -> 'text
'),ExpiresDefault
|
| Filter Class Name |
The filter class name for the Expires Filter is
org.apache.catalina.filters.ExpiresFilter
.
|
| Initialisation parameters |
The Expires Filter supports the following
initialisation parameters:
| Attribute | Description |
|---|
ExpiresExcludedResponseStatusCodes |
This directive defines the http response status codes for which the
ExpiresFilter will not generate expiration headers. By default, the
304 status code ("Not modified") is skipped. The
value is a comma separated list of http status codes.
This directive is useful to ease usage of ExpiresDefault directive.
Indeed, the behavior of 304 Not modified (which does specify a
Content-Type header) combined with Expires and
Cache-Control:max-age= headers can be unnecessarily tricky to
understand.
See sample below the table
| ExpiresByType <content-type> |
This directive defines the value of the Expires header and the
max-age directive of the Cache-Control header generated for
documents of the specified type (e.g., text/html). The second
argument sets the number of seconds that will be added to a base time to
construct the expiration date. The Cache-Control: max-age is
calculated by subtracting the request time from the expiration date and
expressing the result in seconds.
The base time is either the last modification time of the file, or the time
of the client's access to the document. Which should be used is
specified by the <code> field; M means that the
file's last modification time should be used as the base time, and
A means the client's access time should be used. The duration
is expressed in seconds. A2592000 stands for
access plus 30 days in alternate syntax.
The difference in effect is subtle. If M (modification in
alternate syntax) is used, all current copies of the document in all caches
will expire at the same time, which can be good for something like a weekly
notice that's always found at the same URL. If A (
access or now in alternate syntax) is used, the date of
expiration is different for each client; this can be good for image files
that don't change very often, particularly for a set of related
documents that all refer to the same images (i.e., the images will be
accessed repeatedly within a relatively short timespan).
Note: When the content type includes a charset (e.g.
'ExpiresByType text/xml;charset=utf-8'), Tomcat removes blank chars
between the ';' and the 'charset' keyword. Due to this,
configuration of an expiration with a charset must not include
such a space character.
See sample below the table
It overrides, for the specified MIME type only, any
expiration date set by the ExpiresDefault directive.
You can also specify the expiration time calculation using an alternate
syntax, described earlier in this document.
| ExpiresDefault |
This directive sets the default algorithm for calculating the
expiration time for all documents in the affected realm. It can be
overridden on a type-by-type basis by the ExpiresByType directive. See the
description of that directive for details about the syntax of the
argument, and the "alternate syntax"
description as well.
|
Sample : exclude response status codes 302, 500 and 503
| | | |
<init-param>
<param-name>ExpiresExcludedResponseStatusCodes</param-name>
<param-value>302, 500, 503</param-value>
</init-param>
| | | | |
Sample for ExpiresByType initialization parameter
| | | |
<init-param>
<param-name>ExpiresByType text/html</param-name>
<param-value>access plus 1 month 15 days 2 hours</param-value>
</init-param>
<init-param>
<!-- 2592000 seconds = 30 days -->
<param-name>ExpiresByType image/gif</param-name>
<param-value>A2592000</param-value>
</init-param>
| | | | |
|
| Troubleshooting |
To troubleshoot, enable logging on the
org.apache.catalina.filters.ExpiresFilter.
Extract of logging.properties
| | | |
org.apache.catalina.filters.ExpiresFilter.level = FINE
| | | | |
Sample of initialization log message:
| | | |
Mar 26, 2010 2:01:41 PM org.apache.catalina.filters.ExpiresFilter init
FINE: Filter initialized with configuration ExpiresFilter[
excludedResponseStatusCode=[304],
default=null,
byType={
image=ExpiresConfiguration[startingPoint=ACCESS_TIME, duration=[10 MINUTE]],
text/css=ExpiresConfiguration[startingPoint=ACCESS_TIME, duration=[10 MINUTE]],
text/javascript=ExpiresConfiguration[startingPoint=ACCESS_TIME, duration=[10 MINUTE]]}]
| | | | |
Sample of per-request log message where ExpiresFilter adds an
expiration date is below. The message is on one line and is wrapped here
for better readability.
| | | |
Mar 26, 2010 2:09:47 PM org.apache.catalina.filters.ExpiresFilter onBeforeWriteResponseBody
FINE: Request "/tomcat.gif" with response status "200"
content-type "image/gif", set expiration date 3/26/10 2:19 PM
| | | | |
Sample of per-request log message where ExpiresFilter does not add
an expiration date:
| | | |
Mar 26, 2010 2:10:27 PM org.apache.catalina.filters.ExpiresFilter onBeforeWriteResponseBody
FINE: Request "/docs/config/manager.html" with response status "200"
content-type "text/html", no expiration configured
| | | | |
|
|
| Failed Request Filter |
| Introduction |
This filter triggers parameters parsing in a request and rejects the
request if some parameters were skipped during parameter parsing because
of parsing errors or request size limitations (such as
maxParameterCount attribute in a
Connector).
This filter can be used to ensure that none parameter values submitted by
client are lost.
Note that parameter parsing may consume the body of an HTTP request, so
caution is needed if the servlet protected by this filter uses
request.getInputStream() or request.getReader()
calls. In general the risk of breaking a web application by adding this
filter is not so high, because parameter parsing does check content type
of the request before consuming the request body.
Note, that for the POST requests to be parsed correctly, a
SetCharacterEncodingFilter filter must be configured above
this one. See CharacterEncoding page in the FAQ for details.
The request is rejected with HTTP status code 400 (Bad Request).
|
| Filter Class Name |
The filter class name for the Failed Request Filter is
org.apache.catalina.filters.FailedRequestFilter
.
|
|
| Remote Address Filter |
| Introduction |
The Remote Address Filter allows you to compare the
IP address of the client that submitted this request against one or more
regular expressions, and either allow the request to continue
or refuse to process the request from this client.
The syntax for regular expressions is different than that for
'standard' wildcard matching. Tomcat uses the java.util.regex
package. Please consult the Java documentation for details of the
expressions supported.
Note: There is a caveat when using this filter with
IPv6 addresses. Format of the IP address that this valve is processing
depends on the API that was used to obtain it. If the address was obtained
from Java socket using Inet6Address class, its format will be
x:x:x:x:x:x:x:x. That is, the IP address for localhost
will be 0:0:0:0:0:0:0:1 instead of the more widely used
::1. Consult your access logs for the actual value.
See also: Remote Host Filter.
|
| Filter Class Name |
The filter class name for the Remote Address Filter is
org.apache.catalina.filters.RemoteAddrFilter
.
|
| Initialisation parameters |
The Remote Address Filter supports the following
initialisation parameters:
| Attribute | Description |
|---|
allow |
A regular expression (using java.util.regex) that the
remote client's IP address is compared to. If this attribute
is specified, the remote address MUST match for this request to be
accepted. If this attribute is not specified, all requests will be
accepted UNLESS the remote address matches a deny
pattern.
| deny |
A regular expression (using java.util.regex) that the
remote client's IP address is compared to. If this attribute
is specified, the remote address MUST NOT match for this request to be
accepted. If this attribute is not specified, request acceptance is
governed solely by the accept attribute.
| denyStatus |
HTTP response status code that is used when rejecting denied
request. The default value is 403. For example,
it can be set to the value 404.
|
|
|
| Remote Host Filter |
| Introduction |
The Remote Host Filter allows you to compare the
hostname of the client that submitted this request against one or more
regular expressions, and either allow the request to continue
or refuse to process the request from this client.
The syntax for regular expressions is different than that for
'standard' wildcard matching. Tomcat uses the java.util.regex
package. Please consult the Java documentation for details of the
expressions supported.
Note: This filter processes the value returned by
method ServletRequest.getRemoteHost(). To allow the method
to return proper host names, you have to enable "DNS lookups" feature on
a Connector.
See also: Remote Address Filter,
HTTP Connector configuration.
|
| Filter Class Name |
The filter class name for the Remote Address Filter is
org.apache.catalina.filters.RemoteHostFilter
.
|
| Initialisation parameters |
The Remote Host Filter supports the following
initialisation parameters:
| Attribute | Description |
|---|
allow |
A regular expression (using java.util.regex) that the
remote client's hostname is compared to. If this attribute
is specified, the remote hostname MUST match for this request to be
accepted. If this attribute is not specified, all requests will be
accepted UNLESS the remote hostname matches a deny
pattern.
| deny |
A regular expression (using java.util.regex) that the
remote client's hostname is compared to. If this attribute
is specified, the remote hostname MUST NOT match for this request to be
accepted. If this attribute is not specified, request acceptance is
governed solely by the accept attribute.
| denyStatus |
HTTP response status code that is used when rejecting denied
request. The default value is 403. For example,
it can be set to the value 404.
|
|
|
| Remote IP Filter |
| Introduction |
Tomcat port of
mod_remoteip,
this filter replaces the apparent client remote IP address and hostname for
the request with the IP address list presented by a proxy or a load balancer
via a request headers (e.g. "X-Forwarded-For").
Another feature of this filter is to replace the apparent scheme
(http/https), server port and request.secure with the scheme presented
by a proxy or a load balancer via a request header
(e.g. "X-Forwarded-Proto").
If used in conjunction with Remote Address/Host filters then this filter
should be defined first to ensure that the correct client IP address is
presented to the Remote Address/Host filters.
Note: By default this filter has no effect on the
values that are written into access log. The original values are restored
when request processing leaves the filter and that always happens earlier
than access logging. To pass the remote address, remote host, server port
and protocol values set by this filter to the access log,
they are put into request attributes. Publishing these values here
is enabled by default, but AccessLogValve should be explicitly
configured to use them. See documentation for
requestAttributesEnabled attribute of
AccessLogValve.
The names of request attributes that are set by this filter
and can be used by access logging are the following:
org.apache.catalina.AccessLog.RemoteAddrorg.apache.catalina.AccessLog.RemoteHostorg.apache.catalina.AccessLog.Protocolorg.apache.catalina.AccessLog.ServerPortorg.apache.tomcat.remoteAddr
|
| Filter Class Name |
The filter class name for the Remote IP Filter is
org.apache.catalina.filters.RemoteIpFilter
.
|
| Initialisation parameters |
The Remote IP Filter supports the
following initialisation parameters:
| Attribute | Description |
|---|
remoteIpHeader |
Name of the HTTP Header read by this valve that holds the list of
traversed IP addresses starting from the requesting client. If not
specified, the default of x-forwarded-for is used.
| internalProxies |
Regular expression (using java.util.regex) that a
proxy's IP address must match to be considered an internal proxy.
Internal proxies that appear in the remoteIpHeader will
be trusted and will not appear in the proxiesHeader
value. If not specified the default value of
10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|169\.254\.\d{1,3}\.\d{1,3}|127\.\d{1,3}\.\d{1,3}\.\d{1,3}
will be used.
| proxiesHeader |
Name of the HTTP header created by this valve to hold the list of
proxies that have been processed in the incoming
remoteIpHeader. If not specified, the default of
x-forwarded-by is used.
| requestAttributesEnabled |
Set to true to set the request attributes used by
AccessLog implementations to override the values returned by the
request for remote address, remote host, server port and protocol.
Request attributes are also used to enable the forwarded remote address
to be displayed on the status page of the Manager web application.
If not set, the default value of true will be used.
| trustedProxies |
Regular expression (using java.util.regex) that a
proxy's IP address must match to be considered an trusted proxy.
Trusted proxies that appear in the remoteIpHeader will
be trusted and will appear in the proxiesHeader value.
If not specified, no proxies will be trusted.
| protocolHeader |
Name of the HTTP Header read by this valve that holds the protocol
used by the client to connect to the proxy. If not specified, the
default of null is used.
| portHeader |
Name of the HTTP Header read by this valve that holds the port
used by the client to connect to the proxy. If not specified, the
default of null is used.
| protocolHeaderHttpsValue |
Value of the protocolHeader to indicate that it is
an HTTPS request. If not specified, the default of https is
used.
| httpServerPort |
Value returned by ServletRequest.getServerPort()
when the protocolHeader indicates http
protocol and no portHeader is present. If not
specified, the default of 80 is used.
| httpsServerPort |
Value returned by ServletRequest.getServerPort()
when the protocolHeader indicates https
protocol and no portHeader is present. If not
specified, the default of 443 is used.
| changeLocalPort |
If true, the value returned by
ServletRequest.getLocalPort() and
ServletRequest.getServerPort() is modified by the this
filter. If not specified, the default of false is used.
|
|
|
| Request Dumper Filter |
| Introduction |
The Request Dumper Filter logs information from the request and response
objects and is intended to be used for debugging purposes. When using this
Filter, it is recommended that the
org.apache.catalina.filter.RequestDumperFilter logger is
directed to a dedicated file and that the
org.apache.juli.VerbatimFormmater is used.
WARNING: Using this filter has side-effects. The
output from this filter includes any parameters included with the request.
The parameters will be decoded using the default platform encoding. Any
subsequent calls to request.setCharacterEncoding() within
the web application will have no effect.
|
| Filter Class Name |
The filter class name for the Request Dumper Filter is
org.apache.catalina.filters.RequestDumperFilter
.
|
|
| Set Character Encoding Filter |
| Introduction |
User agents don't always include character encoding information in
requests. Depending on the how the request is processed, usually the
default encoding of ISO-8859-1 is used. This is not always
desirable. This filter provides options for setting that encoding or
forcing it to a particular value. Essentially this filter calls
ServletRequest.setCharacterEncoding() method.
Effectively the value set by this filter is used when parsing parameters
in a POST request, if parameter parsing occurs later than this filter. Thus
the order of filter mappings is important. Note that the encoding for GET
requests is not set here, but on a Connector. See
CharacterEncoding page in the FAQ for details.
|
| Filter Class Name |
The filter class name for the Set Character Encoding Filter is
org.apache.catalina.filters.SetCharacterEncodingFilter
.
|
| Initialisation parameters |
The Set Character Encoding Filter supports the following initialization
parameters:
| Attribute | Description |
|---|
encoding |
Name of the character encoding which should be set.
| ignore |
Determines if any character encoding specified by the user agent is
ignored. If this attribute is true, any value provided by
the user agent is ignored. If false, the encoding is only
set if the user agent did not specify an encoding. The default value
is false.
|
|
|
| WebDAV Fix Filter |
| Introduction |
Microsoft operating systems have two WebDAV clients. One is used with
port 80, the other is used for all other ports. The implementation used with
port 80 does not adhere to the WebDAV specification and fails when trying to
communicate with the Tomcat WebDAV Servlet. This Filter provides a fix for
this by forcing the use of the WebDAV implementation that works, even when
connecting via port 80.
|
| Filter Class Name |
The filter class name for the WebDAV Fix Filter is
org.apache.catalina.filters.WebdavFixFilter
.
|
|
|
