RemoteIpFilter (Apache Tomcat 7.0.4 API Documentation)

Overview

Package

Class

Tree

Deprecated

Index

Help

Apache Tomcat 7.0.4

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.catalina.filters
Class RemoteIpFilter

java.lang.Object
  org.apache.catalina.filters.RemoteIpFilter

All Implemented Interfaces:: Filter

public class RemoteIpFilter
extends Object
implements Filter
extends Object
implements Filter

Servlet filter to integrate "X-Forwarded-For" and "X-Forwarded-Proto" HTTP headers.

Most of the design of this Servlet Filter is a port of mod_remoteip, this servlet 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 servlet filter is to replace the apparent scheme (http/https) and server port with the scheme presented by a proxy or a load balancer via a request header (e.g. "X-Forwarded-Proto").

This servlet filter proceeds as follows:

If the incoming request.getRemoteAddr() matches the servlet filter's list of internal proxies :

Loop on the comma delimited list of IPs and hostnames passed by the preceding load balancer or proxy in the given request's Http header named $remoteIpHeader (default value x-forwarded-for). Values are processed in right-to-left order.
For each ip/host of the list:
- if it matches the internal proxies list, the ip/host is swallowed
- if it matches the trusted proxies list, the ip/host is added to the created proxies header
- otherwise, the ip/host is declared to be the remote ip and looping is stopped.
If the request http header named $protocolHeader (e.g. x-forwarded-for) equals to the value of protocolHeaderHttpsValue configuration parameter (default https) then request.isSecure = true, request.scheme = https and request.serverPort = 443. Note that 443 can be overwritten with the $httpsServerPort configuration parameter.

Configuration parameters:

XForwardedFilter property	Description	Equivalent mod_remoteip directive	Format	Default Value
remoteIpHeader	Name of the Http Header read by this servlet filter that holds the list of traversed IP addresses starting from the requesting client	RemoteIPHeader	Compliant http header name	x-forwarded-for
internalProxies	List of internal proxies ip adress. If they appear in the `remoteIpHeader` value, they will be trusted and will not appear in the `proxiesHeader` value	RemoteIPInternalProxy	Comma delimited list of regular expressions (in the syntax supported by the `Pattern` library)	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} By default, 10/8, 192.168/16, 169.254/16 and 127/8 are allowed ; 172.16/12 has not been enabled by default because it is complex to describe with regular expressions
proxiesHeader	Name of the http header created by this servlet filter to hold the list of proxies that have been processed in the incoming `remoteIpHeader`	RemoteIPProxiesHeader	Compliant http header name	x-forwarded-by
trustedProxies	List of trusted proxies ip adress. If they appear in the `remoteIpHeader` value, they will be trusted and will appear in the `proxiesHeader` value	RemoteIPTrustedProxy	Comma delimited list of regular expressions (in the syntax supported by the `Pattern` library)
protocolHeader	Name of the http header read by this servlet filter that holds the flag that this request	N/A	Compliant http header name like `X-Forwarded-Proto`, `X-Forwarded-Ssl` or `Front-End-Https`	`null`
protocolHeaderHttpsValue	Value of the `protocolHeader` to indicate that it is an Https request	N/A	String like `https` or `ON`	`https`
httpServerPort	Value returned by `ServletRequest.getServerPort()` when the `protocolHeader` indicates `http` protocol	N/A	integer	80
httpsServerPort	Value returned by `ServletRequest.getServerPort()` when the `protocolHeader` indicates `https` protocol	N/A	integer	443

Regular expression vs. IP address blocks: mod_remoteip allows to use address blocks (e.g. 192.168/16) to configure RemoteIPInternalProxy and RemoteIPTrustedProxy ; as the JVM doesn't have a library similar to apr_ipsubnet_test, we rely on regular expressions.

Sample with internal proxies

XForwardedFilter configuration:

 <filter>
    <filter-name>RemoteIpFilter</filter-name>
    <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
    <init-param>
       <param-name>internalProxies</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>
 
 <filter-mapping>
    <filter-name>RemoteIpFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
 </filter-mapping>

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 as been traversed by the request. x-forwarded-by is null because all the proxies are trusted or internal.

Sample with trusted proxies

RemoteIpFilter configuration:

 <filter>
    <filter-name>RemoteIpFilter</filter-name>
    <filter-class>org.apache.catalina.filters.RemoteIpFilter</filter-class>
    <init-param>
       <param-name>internalProxies</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>
 
 <filter-mapping>
    <filter-name>RemoteIpFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
 </filter-mapping>

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-by is null because all the proxies are trusted or internal.

Sample 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>internalProxies</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>
 
 <filter-mapping>
    <filter-name>RemoteIpFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
 </filter-mapping>

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-by is null because all the proxies are trusted or internal.

Sample 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>internalProxies</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>
 
 <filter-mapping>
    <filter-name>RemoteIpFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
 </filter-mapping>

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.

Nested Class Summary
`static class`	`RemoteIpFilter.XForwardedRequest`

Field Summary
`protected static String`	`HTTP_SERVER_PORT_PARAMETER`
`protected static String`	`HTTPS_SERVER_PORT_PARAMETER`
`protected static String`	`INTERNAL_PROXIES_PARAMETER`
`protected static String`	`PROTOCOL_HEADER_HTTPS_VALUE_PARAMETER`
`protected static String`	`PROTOCOL_HEADER_PARAMETER`
`protected static String`	`PROXIES_HEADER_PARAMETER`
`protected static String`	`REMOTE_IP_HEADER_PARAMETER`
`protected static String`	`TRUSTED_PROXIES_PARAMETER`

Constructor Summary
`RemoteIpFilter()`

Method Summary
`protected static Pattern[]`	`commaDelimitedListToPatternArray(String commaDelimitedPatterns)` Convert a given comma delimited list of regular expressions into an array of compiled `Pattern`
`protected static String[]`	`commaDelimitedListToStringArray(String commaDelimitedStrings)` Convert a given comma delimited list of regular expressions into an array of String
`void`	`destroy()` Called by the web container to indicate to a filter that it is being taken out of service.
`void`	`doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain chain)`
`void`	`doFilter(ServletRequest request, ServletResponse response, FilterChain chain)` Wrap the incoming `request` in a `RemoteIpFilter.XForwardedRequest` if the http header `x-forwareded-for` is not empty.
`int`	`getHttpsServerPort()`
`Pattern[]`	`getInternalProxies()`
`String`	`getProtocolHeader()`
`String`	`getProtocolHeaderHttpsValue()`
`String`	`getProxiesHeader()`
`String`	`getRemoteIpHeader()`
`Pattern[]`	`getTrustedProxies()`
`void`	`init(FilterConfig filterConfig)` Called by the web container to indicate to a filter that it is being placed into service.
`protected static String`	`listToCommaDelimitedString(List<String> stringList)` Convert an array of strings in a comma delimited string
`protected static boolean`	`matchesOne(String str, Pattern... patterns)` Return `true` if the given `str` matches at least one of the given `patterns`.
`void`	`setHttpServerPort(int httpServerPort)` Server Port value if the `protocolHeader` indicates HTTP (i.e.
`void`	`setHttpsServerPort(int httpsServerPort)` Server Port value if the `protocolHeader` indicates HTTPS Default value : 443
`void`	`setInternalProxies(String internalProxies)` Comma delimited list of internal proxies.
`void`	`setProtocolHeader(String protocolHeader)` Header that holds the incoming protocol, usally named `X-Forwarded-Proto`.
`void`	`setProtocolHeaderHttpsValue(String protocolHeaderHttpsValue)` Case insensitive value of the protocol header to indicate that the incoming http request uses HTTPS.
`void`	`setProxiesHeader(String proxiesHeader)` The proxiesHeader directive specifies a header into which mod_remoteip will collect a list of all of the intermediate client IP addresses trusted to resolve the actual remote IP.
`void`	`setRemoteIpHeader(String remoteIpHeader)` Name of the http header from which the remote ip is extracted.
`void`	`setTrustedProxies(String trustedProxies)` Comma delimited list of proxies that are trusted when they appear in the `remoteIpHeader` header.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

HTTP_SERVER_PORT_PARAMETER

protected static final String HTTP_SERVER_PORT_PARAMETER

See Also:: Constant Field Values

HTTPS_SERVER_PORT_PARAMETER

protected static final String HTTPS_SERVER_PORT_PARAMETER

See Also:: Constant Field Values

INTERNAL_PROXIES_PARAMETER

protected static final String INTERNAL_PROXIES_PARAMETER

See Also:: Constant Field Values

PROTOCOL_HEADER_PARAMETER

protected static final String PROTOCOL_HEADER_PARAMETER

See Also:: Constant Field Values

PROTOCOL_HEADER_HTTPS_VALUE_PARAMETER

protected static final String PROTOCOL_HEADER_HTTPS_VALUE_PARAMETER

See Also:: Constant Field Values

PROXIES_HEADER_PARAMETER

protected static final String PROXIES_HEADER_PARAMETER

See Also:: Constant Field Values

REMOTE_IP_HEADER_PARAMETER

protected static final String REMOTE_IP_HEADER_PARAMETER

See Also:: Constant Field Values

TRUSTED_PROXIES_PARAMETER

protected static final String TRUSTED_PROXIES_PARAMETER

See Also:: Constant Field Values

Constructor Detail

RemoteIpFilter

public RemoteIpFilter()

Method Detail

commaDelimitedListToPatternArray

protected static Pattern[] commaDelimitedListToPatternArray(String commaDelimitedPatterns)

Convert a given comma delimited list of regular expressions into an array of compiled Pattern

Returns:: array of patterns (not null)

commaDelimitedListToStringArray

protected static String[] commaDelimitedListToStringArray(String commaDelimitedStrings)

Convert a given comma delimited list of regular expressions into an array of String

Returns:: array of patterns (non null)

listToCommaDelimitedString

protected static String listToCommaDelimitedString(List<String> stringList)

Convert an array of strings in a comma delimited string

matchesOne

protected static boolean matchesOne(String str,
                                    Pattern... patterns)

Return true if the given str matches at least one of the given patterns.

destroy

public void destroy()

Description copied from interface: javax.servlet.Filter

Called by the web container to indicate to a filter that it is being taken out of service. This method is only called once all threads within the filter's doFilter method have exited or after a timeout period has passed. After the web container calls this method, it will not call the doFilter method again on this instance of the filter.

This method gives the filter an opportunity to clean up any resources that are being held (for example, memory, file handles, threads) and make sure that any persistent state is synchronized with the filter's current state in memory.

Specified by:: destroy in interface Filter

doFilter

public void doFilter(HttpServletRequest request,
                     HttpServletResponse response,
                     FilterChain chain)
              throws IOException,
                     ServletException

Throws:: IOException; ServletException

doFilter

public void doFilter(ServletRequest request,
                     ServletResponse response,
                     FilterChain chain)
              throws IOException,
                     ServletException

Wrap the incoming request in a RemoteIpFilter.XForwardedRequest if the http header x-forwareded-for is not empty.

Specified by:: doFilter in interface Filter

Throws:: IOException; ServletException

getHttpsServerPort

public int getHttpsServerPort()

getInternalProxies

public Pattern[] getInternalProxies()

getProtocolHeader

public String getProtocolHeader()

getProtocolHeaderHttpsValue

public String getProtocolHeaderHttpsValue()

getProxiesHeader

public String getProxiesHeader()

getRemoteIpHeader

public String getRemoteIpHeader()

getTrustedProxies

public Pattern[] getTrustedProxies()

init

public void init(FilterConfig filterConfig)
          throws ServletException

Description copied from interface: javax.servlet.Filter

Called by the web container to indicate to a filter that it is being placed into service. The servlet container calls the init method exactly once after instantiating the filter. The init method must complete successfully before the filter is asked to do any filtering work.

The web container cannot place the filter into service if the init method either
1.Throws a ServletException
2.Does not return within a time period defined by the web container

Specified by:: init in interface Filter

Throws:: ServletException

setHttpServerPort

public void setHttpServerPort(int httpServerPort)

Server Port value if the protocolHeader indicates HTTP (i.e. protocolHeader is not null and has a value different of protocolHeaderHttpsValue).

Default value : 80

setHttpsServerPort

public void setHttpsServerPort(int httpsServerPort)

Server Port value if the protocolHeader indicates HTTPS

Default value : 443

setInternalProxies

public void setInternalProxies(String internalProxies)

Comma delimited list of internal proxies. Can be expressed with regular expressions.

Default value : 10\.\d{1,3}\.\d{1,3}\.\d{1,3}, 192\.168\.\d{1,3}\.\d{1,3}, 127\.\d{1,3}\.\d{1,3}\.\d{1,3}

setProtocolHeader

public void setProtocolHeader(String protocolHeader)

Header that holds the incoming protocol, usally named X-Forwarded-Proto. If null, request.scheme and request.secure will not be modified.

Default value : null

setProtocolHeaderHttpsValue

public void setProtocolHeaderHttpsValue(String protocolHeaderHttpsValue)

Case insensitive value of the protocol header to indicate that the incoming http request uses HTTPS.

Default value : https

setProxiesHeader

public void setProxiesHeader(String proxiesHeader)

The proxiesHeader directive specifies a header into which mod_remoteip will collect a list of all of the intermediate client IP addresses trusted to resolve the actual remote IP. Note that intermediate RemoteIPTrustedProxy addresses are recorded in this header, while any intermediate RemoteIPInternalProxy addresses are discarded.

Name of the http header that holds the list of trusted proxies that has been traversed by the http request.

The value of this header can be comma delimited.

Default value : X-Forwarded-By

setRemoteIpHeader

public void setRemoteIpHeader(String remoteIpHeader)

Name of the http header from which the remote ip is extracted.

The value of this header can be comma delimited.

Default value : X-Forwarded-For

setTrustedProxies

public void setTrustedProxies(String trustedProxies)

Comma delimited list of proxies that are trusted when they appear in the remoteIpHeader header. Can be expressed as a regular expression.

Default value : empty list, no external proxy is trusted.

Overview

Package

Class

Tree

Deprecated

Index

Help

Apache Tomcat 7.0.4

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.catalina.filters Class RemoteIpFilter

HTTP_SERVER_PORT_PARAMETER

HTTPS_SERVER_PORT_PARAMETER

INTERNAL_PROXIES_PARAMETER

PROTOCOL_HEADER_PARAMETER

PROTOCOL_HEADER_HTTPS_VALUE_PARAMETER

PROXIES_HEADER_PARAMETER

REMOTE_IP_HEADER_PARAMETER

TRUSTED_PROXIES_PARAMETER

RemoteIpFilter

commaDelimitedListToPatternArray

commaDelimitedListToStringArray

listToCommaDelimitedString

matchesOne

destroy

doFilter

doFilter

getHttpsServerPort

getInternalProxies

getProtocolHeader

getProtocolHeaderHttpsValue

getProxiesHeader

getRemoteIpHeader

getTrustedProxies

init

setHttpServerPort

setHttpsServerPort

setInternalProxies

setProtocolHeader

setProtocolHeaderHttpsValue

setProxiesHeader

setRemoteIpHeader

setTrustedProxies

org.apache.catalina.filters
Class RemoteIpFilter