• Introduction
• Add Default Character Set Filter
  1. Introduction
  2. Filter Class Name
  3. Initialisation parameters
• CSRF Prevention Filter
  1. Introduction
  2. Filter Class Name
  3. Initialisation parameters
• Remote Address Filter
  1. Introduction
  2. Filter Class Name
  3. Initialisation parameters
• Remote Host Filter
  1. Introduction
  2. Filter Class Name
  3. Initialisation parameters
• Remote IP Filter
  1. Introduction
  2. Filter Class Name
  3. Basic configuration to handle 'x-forwarded-for'
  4. Basic configuration to handle 'x-forwarded-for' and 'x-forwarded-proto'
  5. Advanced configuration with internal proxies
  6. Advanced configuration with trusted proxies
  7. Advanced configuration with internal and trusted proxies
  8. Advanced configuration with an untrusted proxy
  9. Initialisation parameters
• Request Dumper Filter
  1. Introduction
  2. Filter Class Name
  3. Initialisation parameters
  4. Sample Configuration
• WebDAV Fix Filter
  1. Introduction
  2. Filter Class Name
  3. Initialisation parameters

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.

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 does not support any initialization parameters.

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 does not support any initialization parameters.

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.

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 comma-separated list of regular expression patterns 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 comma-separated list of regular expression patterns 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.

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.

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 comma-separated list of regular expression patterns 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 comma-separated list of regular expression patterns 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.

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.

Filter Class Name

The filter class name for the Remote IP Filter is org.apache.catalina.filters.RemoteIpFilter .

Basic configuration to handle 'x-forwarded-for'

The filter will process the x-forwarded-for http header. <filter> <filter-name>RemoteIpFilter</filter-name> <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class> </filter> <filter-mapping> <filter-name>RemoteIpFilter</filter-name> <url-pattern>/*</url-pattern> <dispatcher>REQUEST</dispatcher> </filter-mapping>

Basic configuration to handle 'x-forwarded-for' and 'x-forwarded-proto'

The filter will process x-forwarded-for and x-forwarded-proto http headers. Expected value for the x-forwarded-proto header in case of SSL connections is https (case insensitive). <filter> <filter-name>RemoteIpFilter</filter-name> <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class> <init-param> <param-name>protocolHeader</param-name> <param-value>x-forwarded-proto</param-value> </init-param> </filter> <filter-mapping> <filter-name>RemoteIpFilter</filter-name> <url-pattern>/*</url-pattern> <dispatcher>REQUEST</dispatcher> </filter-mapping>

Advanced configuration with internal proxies

RemoteIpFilter configuration: <filter> <filter-name>RemoteIpFilter</filter-name> <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class> <init-param> <param-name>allowedInternalProxies</param-name> <param-value>192\.168\.0\.10, 192\.168\.0\.11</param-value> </init-param> <init-param> <param-name>remoteIPHeader</param-name> <param-value>x-forwarded-for</param-value> </init-param> <init-param> <param-name>remoteIPProxiesHeader</param-name> <param-value>x-forwarded-by</param-value> </init-param> <init-param> <param-name>protocolHeader</param-name> <param-value>x-forwarded-proto</param-value> </init-param> </filter> Request values: Property Value Before RemoteIpFilter Value After RemoteIpFilter request.remoteAddr 192.168.0.10 140.211.11.130 request.header['x-forwarded-for'] 140.211.11.130, 192.168.0.10 null request.header['x-forwarded-by'] null null request.header['x-forwarded-proto'] https https request.scheme http https request.secure false true request.serverPort 80 443 Note : x-forwarded-by header is null because only internal proxies has been traversed by the request. x-forwarded-for is null because all the proxies are trusted or internal.

Advanced configuration with trusted proxies

RemoteIpFilter configuration: <filter> <filter-name>RemoteIpFilter</filter-name> <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class> <init-param> <param-name>allowedInternalProxies</param-name> <param-value>192\.168\.0\.10, 192\.168\.0\.11</param-value> </init-param> <init-param> <param-name>remoteIPHeader</param-name> <param-value>x-forwarded-for</param-value> </init-param> <init-param> <param-name>remoteIPProxiesHeader</param-name> <param-value>x-forwarded-by</param-value> </init-param> <init-param> <param-name>trustedProxies</param-name> <param-value>proxy1, proxy2</param-value> </init-param> </filter> Request values: Property Value Before RemoteIpFilter Value After RemoteIpFilter request.remoteAddr 192.168.0.10 140.211.11.130 request.header['x-forwarded-for'] 140.211.11.130, proxy1, proxy2 null request.header['x-forwarded-by'] null proxy1, proxy2 Note : proxy1 and proxy2 are both trusted proxies that come in x-forwarded-for header, they both are migrated in x-forwarded-by header. x-forwarded-for is null because all the proxies are trusted or internal.

Advanced configuration with internal and trusted proxies

RemoteIpFilter configuration: <filter> <filter-name>RemoteIpFilter</filter-name> <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class> <init-param> <param-name>allowedInternalProxies</param-name> <param-value>192\.168\.0\.10, 192\.168\.0\.11</param-value> </init-param> <init-param> <param-name>remoteIPHeader</param-name> <param-value>x-forwarded-for</param-value> </init-param> <init-param> <param-name>remoteIPProxiesHeader</param-name> <param-value>x-forwarded-by</param-value> </init-param> <init-param> <param-name>trustedProxies</param-name> <param-value>proxy1, proxy2</param-value> </init-param> </filter> Request values: Property Value Before RemoteIpFilter Value After RemoteIpFilter request.remoteAddr 192.168.0.10 140.211.11.130 request.header['x-forwarded-for'] 140.211.11.130, proxy1, proxy2, 192.168.0.10 null request.header['x-forwarded-by'] null proxy1, proxy2 Note : proxy1 and proxy2 are both trusted proxies that come in x-forwarded-for header, they both are migrated in x-forwarded-by header. As 192.168.0.10 is an internal proxy, it does not appear in x-forwarded-by. x-forwarded-for is null because all the proxies are trusted or internal.

Advanced configuration with an untrusted proxy

RemoteIpFilter configuration: <filter> <filter-name>RemoteIpFilter</filter-name> <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class> <init-param> <param-name>allowedInternalProxies</param-name> <param-value>192\.168\.0\.10, 192\.168\.0\.11</param-value> </init-param> <init-param> <param-name>remoteIPHeader</param-name> <param-value>x-forwarded-for</param-value> </init-param> <init-param> <param-name>remoteIPProxiesHeader</param-name> <param-value>x-forwarded-by</param-value> </init-param> <init-param> <param-name>trustedProxies</param-name> <param-value>proxy1, proxy2</param-value> </init-param> </filter> Request values: Property Value Before RemoteIpFilter Value After RemoteIpFilter request.remoteAddr 192.168.0.10 untrusted-proxy request.header['x-forwarded-for'] 140.211.11.130, untrusted-proxy, proxy1 140.211.11.130 request.header['x-forwarded-by'] null proxy1 Note : x-forwarded-by holds the trusted proxy proxy1. x-forwarded-by holds 140.211.11.130 because untrusted-proxy is not trusted and thus, we can not trust that untrusted-proxy is the actual remote ip. request.remoteAddr is untrusted-proxy that is an IP verified by proxy1.

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 List of internal proxies' IP addresses as comma separated regular expressions. If they appear in the remoteIpHeader value, they 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. trustedProxies List of trusted proxies' IP addresses as comma separated regular expressions. If they appear in the remoteIpHeader value, they 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. 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. If not specified, the default of 80 is used. httpsServerPort Value returned by ServletRequest.getServerPort() when the protocolHeader indicates https protocol. If not specified, the default of 443 is used.

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 .

Initialisation parameters

The Request Dumper Filter does not support any initialization parameters.

Sample Configuration

The following entries in a web application's web.xml would enable the Request Dumper filter for all requests for that web application. If the entries were added to CATALINA_BASE/conf/web.xml, the Request Dumper Filter would be enabled for all web applications. <filter> <filter-name>requestdumper</filter-name> <filter-class> org.apache.catalina.filters.RequestDumperFilter </filter-class> </filter> <filter-mapping> <filter-name>requestdumper</filter-name> <url-pattern>*</url-pattern> </filter-mapping> The following entries in CATALINA_BASE/conf/logging.properties would create a separate log file for the Request Dumper Filter output. # To this configuration below, 1request-dumper.org.apache.juli.FileHandler # also needs to be added to the handlers property near the top of the file 1request-dumper.org.apache.juli.FileHandler.level = INFO 1request-dumper.org.apache.juli.FileHandler.directory = ${catalina.base}/logs 1request-dumper.org.apache.juli.FileHandler.prefix = request-dumper. 1request-dumper.org.apache.juli.FileHandler.formatter = org.apache.juli.VerbatimFormatter org.apache.catalina.filters.RequestDumperFilter.level = INFO org.apache.catalina.filters.RequestDumperFilter.handlers = 1request-dumper.org.apache.juli.FileHandler

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 .

Initialisation parameters

The WebDAV Fix Filter does not support any initialization parameters.