Apache Tomcat 7.0.27

org.apache.catalina.filters
Class RemoteIpFilter

java.lang.Object
  extended by org.apache.catalina.filters.RemoteIpFilter
All Implemented Interfaces:
Filter

public class RemoteIpFilter
extends java.lang.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 :

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 Regular expression that matches the IP addresses of internal proxies. If they appear in the remoteIpHeader value, they will be trusted and will not appear in the proxiesHeader value RemoteIPInternalProxy Regular expression (in the syntax supported by java.util.regex) 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 Regular expression that matches the IP addresses of trusted proxies. If they appear in the remoteIpHeader value, they will be trusted and will appear in the proxiesHeader value RemoteIPTrustedProxy Regular expression (in the syntax supported by java.util.regex)  
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 java.lang.String CHANGE_LOCAL_PORT_PARAMETER
           
protected static java.lang.String HTTP_SERVER_PORT_PARAMETER
           
protected static java.lang.String HTTPS_SERVER_PORT_PARAMETER
           
protected static java.lang.String INTERNAL_PROXIES_PARAMETER
           
protected static java.lang.String PORT_HEADER_PARAMETER
           
protected static java.lang.String PROTOCOL_HEADER_HTTPS_VALUE_PARAMETER
           
protected static java.lang.String PROTOCOL_HEADER_PARAMETER
           
protected static java.lang.String PROXIES_HEADER_PARAMETER
           
protected static java.lang.String REMOTE_IP_HEADER_PARAMETER
           
protected static java.lang.String TRUSTED_PROXIES_PARAMETER
           
 
Constructor Summary
RemoteIpFilter()
           
 
Method Summary
protected static java.lang.String[] commaDelimitedListToStringArray(java.lang.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()
           
 java.util.regex.Pattern getInternalProxies()
           
 java.lang.String getPortHeader()
           
 java.lang.String getProtocolHeader()
           
 java.lang.String getProtocolHeaderHttpsValue()
           
 java.lang.String getProxiesHeader()
           
 java.lang.String getRemoteIpHeader()
           
 boolean getRequestAttributesEnabled()
           
 java.util.regex.Pattern getTrustedProxies()
           
 void init(FilterConfig filterConfig)
          Called by the web container to indicate to a filter that it is being placed into service.
 boolean isChangeLocalPort()
           
protected static java.lang.String listToCommaDelimitedString(java.util.List<java.lang.String> stringList)
          Convert an array of strings in a comma delimited string
 void setChangeLocalPort(boolean changeLocalPort)
           If true, the return values for both ServletRequest.getLocalPort() and ServletRequest.getServerPort() wil be modified by this Filter rather than just ServletRequest.getServerPort().
 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(java.lang.String internalProxies)
           Regular expression that defines the internal proxies.
 void setPortHeader(java.lang.String portHeader)
           Header that holds the incoming port, usally named X-Forwarded-Port.
 void setProtocolHeader(java.lang.String protocolHeader)
           Header that holds the incoming protocol, usally named X-Forwarded-Proto.
 void setProtocolHeaderHttpsValue(java.lang.String protocolHeaderHttpsValue)
           Case insensitive value of the protocol header to indicate that the incoming http request uses HTTPS.
 void setProxiesHeader(java.lang.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(java.lang.String remoteIpHeader)
           Name of the http header from which the remote ip is extracted.
 void setRequestAttributesEnabled(boolean requestAttributesEnabled)
          Should this filter set request attributes for IP address, Hostname, protocol and port used for the request?
 void setTrustedProxies(java.lang.String trustedProxies)
           Regular expression defining 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 java.lang.String HTTP_SERVER_PORT_PARAMETER
See Also:
Constant Field Values

HTTPS_SERVER_PORT_PARAMETER

protected static final java.lang.String HTTPS_SERVER_PORT_PARAMETER
See Also:
Constant Field Values

INTERNAL_PROXIES_PARAMETER

protected static final java.lang.String INTERNAL_PROXIES_PARAMETER
See Also:
Constant Field Values

PROTOCOL_HEADER_PARAMETER

protected static final java.lang.String PROTOCOL_HEADER_PARAMETER
See Also:
Constant Field Values

PROTOCOL_HEADER_HTTPS_VALUE_PARAMETER

protected static final java.lang.String PROTOCOL_HEADER_HTTPS_VALUE_PARAMETER
See Also:
Constant Field Values

PORT_HEADER_PARAMETER

protected static final java.lang.String PORT_HEADER_PARAMETER
See Also:
Constant Field Values

CHANGE_LOCAL_PORT_PARAMETER

protected static final java.lang.String CHANGE_LOCAL_PORT_PARAMETER
See Also:
Constant Field Values

PROXIES_HEADER_PARAMETER

protected static final java.lang.String PROXIES_HEADER_PARAMETER
See Also:
Constant Field Values

REMOTE_IP_HEADER_PARAMETER

protected static final java.lang.String REMOTE_IP_HEADER_PARAMETER
See Also:
Constant Field Values

TRUSTED_PROXIES_PARAMETER

protected static final java.lang.String TRUSTED_PROXIES_PARAMETER
See Also:
Constant Field Values
Constructor Detail

RemoteIpFilter

public RemoteIpFilter()
Method Detail

commaDelimitedListToStringArray

protected static java.lang.String[] commaDelimitedListToStringArray(java.lang.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 java.lang.String listToCommaDelimitedString(java.util.List<java.lang.String> stringList)
Convert an array of strings in a comma delimited string


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 java.io.IOException,
                     ServletException
Throws:
java.io.IOException
ServletException

doFilter

public void doFilter(ServletRequest request,
                     ServletResponse response,
                     FilterChain chain)
              throws java.io.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:
java.io.IOException
ServletException

isChangeLocalPort

public boolean isChangeLocalPort()

getHttpsServerPort

public int getHttpsServerPort()

getInternalProxies

public java.util.regex.Pattern getInternalProxies()

getProtocolHeader

public java.lang.String getProtocolHeader()

getPortHeader

public java.lang.String getPortHeader()

getProtocolHeaderHttpsValue

public java.lang.String getProtocolHeaderHttpsValue()

getProxiesHeader

public java.lang.String getProxiesHeader()

getRemoteIpHeader

public java.lang.String getRemoteIpHeader()

getRequestAttributesEnabled

public boolean getRequestAttributesEnabled()
Returns:
true if the attributes will be logged, otherwise false
See Also:
setRequestAttributesEnabled(boolean)

getTrustedProxies

public java.util.regex.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

setChangeLocalPort

public void setChangeLocalPort(boolean changeLocalPort)

If true, the return values for both ServletRequest.getLocalPort() and ServletRequest.getServerPort() wil be modified by this Filter rather than just ServletRequest.getServerPort().

Default value : false


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(java.lang.String internalProxies)

Regular expression that defines the internal proxies.

Default value : 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}


setPortHeader

public void setPortHeader(java.lang.String portHeader)

Header that holds the incoming port, usally named X-Forwarded-Port. If null, httpServerPort or httpsServerPort will be used.

Default value : null


setProtocolHeader

public void setProtocolHeader(java.lang.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(java.lang.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(java.lang.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(java.lang.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


setRequestAttributesEnabled

public void setRequestAttributesEnabled(boolean requestAttributesEnabled)
Should this filter set request attributes for IP address, Hostname, protocol and port used for the request? This are typically used in conjunction with an AccessLog which will otherwise log the original values. Default is true. The attributes set are:

Parameters:
requestAttributesEnabled - true causes the attributes to be set, false disables the setting of the attributes.

setTrustedProxies

public void setTrustedProxies(java.lang.String trustedProxies)

Regular expression defining proxies that are trusted when they appear in the remoteIpHeader header.

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


Apache Tomcat 7.0.27

Copyright © 2000-2012 Apache Software Foundation. All Rights Reserved.