Apache Tomcat 6.0.43

org.apache.catalina.valves
Class RemoteIpValve

java.lang.Object
  extended by org.apache.catalina.valves.ValveBase
      extended by org.apache.catalina.valves.RemoteIpValve
All Implemented Interfaces:
javax.management.MBeanRegistration, Contained, Valve

public class RemoteIpValve
extends ValveBase

Tomcat port of mod_remoteip, this valve 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 valve 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 valve proceeds as follows:

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

Configuration parameters:

RemoteIpValve property Description Equivalent mod_remoteip directive Format Default Value
remoteIpHeader Name of the Http Header read by this valve 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}
Note that this comma-separated regular expression is used by default but cannot be specified in the same way through String-based configuration, as the commas in the "\d{1,3}" expressions will interpreted as separators between regular expressions. The "\d{1,3}" pattern can be replaced by "\d\d?\d?" or more simply by "\d+". 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 valve 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 valve 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

This Valve may be attached to any Container, depending on the granularity of the filtering you wish to perform.

Regular expression vs. IP address blocks: mod_remoteip allows to use address blocks (e.g. 192.168/16) to configure RemoteIPInternalProxy and RemoteIPTrustedProxy ; as Tomcat doesn't have a library similar to apr_ipsubnet_test, RemoteIpValve uses regular expression to configure internalProxies and trustedProxies in the same fashion as RequestFilterValve does.


Sample with internal proxies

RemoteIpValve configuration:

 <Valve 
   className="org.apache.catalina.valves.RemoteIpValve"
   internalProxies="192\.168\.0\.10, 192\.168\.0\.11"
   remoteIpHeader="x-forwarded-for"
   remoteIpProxiesHeader="x-forwarded-by"
   protocolHeader="x-forwarded-proto"
   />

Request values:

property Value Before RemoteIpValve Value After RemoteIpValve
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

RemoteIpValve configuration:

 <Valve 
   className="org.apache.catalina.valves.RemoteIpValve"
   internalProxies="192\.168\.0\.10, 192\.168\.0\.11"
   remoteIpHeader="x-forwarded-for"
   remoteIpProxiesHeader="x-forwarded-by"
   trustedProxies="proxy1, proxy2"
   />

Request values:

property Value Before RemoteIpValve Value After RemoteIpValve
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

RemoteIpValve configuration:

 <Valve 
   className="org.apache.catalina.valves.RemoteIpValve"
   internalProxies="192\.168\.0\.10, 192\.168\.0\.11"
   remoteIpHeader="x-forwarded-for"
   remoteIpProxiesHeader="x-forwarded-by"
   trustedProxies="proxy1, proxy2"
   />

Request values:

property Value Before RemoteIpValve Value After RemoteIpValve
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

RemoteIpValve configuration:

 <Valve 
   className="org.apache.catalina.valves.RemoteIpValve"
   internalProxies="192\.168\.0\.10, 192\.168\.0\.11"
   remoteIpHeader="x-forwarded-for"
   remoteIpProxiesHeader="x-forwarded-by"
   trustedProxies="proxy1, proxy2"
   />

Request values:

property Value Before RemoteIpValve Value After RemoteIpValve
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.


Field Summary
protected static StringManager sm
          The StringManager for this package.
 
Fields inherited from class org.apache.catalina.valves.ValveBase
container, containerLog, controller, domain, mserver, next, oname
 
Constructor Summary
RemoteIpValve()
           
 
Method Summary
protected static java.util.regex.Pattern[] commaDelimitedListToPatternArray(java.lang.String commaDelimitedPatterns)
          Convert a given comma delimited list of regular expressions into an array of compiled Pattern
protected static java.lang.String[] commaDelimitedListToStringArray(java.lang.String commaDelimitedStrings)
          Convert a given comma delimited list of regular expressions into an array of String
 int getHttpServerPort()
           
 int getHttpsServerPort()
           
 java.lang.String getInfo()
          Return descriptive information about this Valve implementation.
 java.lang.String getInternalProxies()
           
 java.lang.String getProtocolHeader()
           
 java.lang.String getProtocolHeaderHttpsValue()
           
 java.lang.String getProxiesHeader()
           
 java.lang.String getRemoteIpHeader()
           
 java.lang.String getTrustedProxies()
           
 void invoke(Request request, Response response)
          The implementation-specific logic represented by this Valve.
protected static java.lang.String listToCommaDelimitedString(java.util.List<java.lang.String> stringList)
          Convert an array of strings in a comma delimited string
protected static boolean matchesOne(java.lang.String str, java.util.regex.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 is not null and does not indicate HTTP Default value : 80
 void setHttpsServerPort(int httpsServerPort)
           Server Port value if the protocolHeader indicates HTTPS Default value : 443
 void setInternalProxies(java.lang.String commaDelimitedInternalProxies)
           Comma delimited list of internal proxies.
 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 SSL.
 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 setTrustedProxies(java.lang.String commaDelimitedTrustedProxies)
           Comma delimited list of proxies that are trusted when they appear in the remoteIpHeader header.
 
Methods inherited from class org.apache.catalina.valves.ValveBase
backgroundProcess, createObjectName, event, getContainer, getContainerName, getController, getDomain, getNext, getObjectName, getParentName, postDeregister, postRegister, preDeregister, preRegister, setContainer, setController, setNext, setObjectName, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

sm

protected static StringManager sm
The StringManager for this package.

Constructor Detail

RemoteIpValve

public RemoteIpValve()
Method Detail

commaDelimitedListToPatternArray

protected static java.util.regex.Pattern[] commaDelimitedListToPatternArray(java.lang.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 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


matchesOne

protected static boolean matchesOne(java.lang.String str,
                                    java.util.regex.Pattern... patterns)
Return true if the given str matches at least one of the given patterns.


getHttpsServerPort

public int getHttpsServerPort()

getHttpServerPort

public int getHttpServerPort()

getInfo

public java.lang.String getInfo()
Return descriptive information about this Valve implementation.

Specified by:
getInfo in interface Valve
Overrides:
getInfo in class ValveBase

getInternalProxies

public java.lang.String getInternalProxies()
Returns:
comma delimited list of internal proxies
See Also:
setInternalProxies(String)

getProtocolHeader

public java.lang.String getProtocolHeader()
Returns:
the protocol header (e.g. "X-Forwarded-Proto")
See Also:
setProtocolHeader(String)

getProtocolHeaderHttpsValue

public java.lang.String getProtocolHeaderHttpsValue()
Returns:
the value of the protocol header for incoming https request (e.g. "https")
See Also:
setProtocolHeaderHttpsValue(String)

getProxiesHeader

public java.lang.String getProxiesHeader()
Returns:
the proxies header name (e.g. "X-Forwarded-By")
See Also:
setProxiesHeader(String)

getRemoteIpHeader

public java.lang.String getRemoteIpHeader()
Returns:
the remote IP header name (e.g. "X-Forwarded-For")
See Also:
setRemoteIpHeader(String)

getTrustedProxies

public java.lang.String getTrustedProxies()
Returns:
comma delimited list of trusted proxies
See Also:
setTrustedProxies(String)

invoke

public void invoke(Request request,
                   Response response)
            throws java.io.IOException,
                   javax.servlet.ServletException
The implementation-specific logic represented by this Valve. See the Valve description for the normal design patterns for this method.

This method MUST be provided by a subclass.

Specified by:
invoke in interface Valve
Specified by:
invoke in class ValveBase
Parameters:
request - The servlet request to be processed
response - The servlet response to be created
Throws:
java.io.IOException - if an input/output error occurs
javax.servlet.ServletException - if a servlet error occurs

setHttpServerPort

public void setHttpServerPort(int httpServerPort)

Server Port value if the protocolHeader is not null and does not indicate HTTP

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 commaDelimitedInternalProxies)

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}
Note: If you want to configure the same value, you have to replace "\d{1,3}" with "\d\d?\d?" or more simply with "\d+". Otherwise the commas in the expression will be mistaken for separators between regular expressions.


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

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

Parameters:
remoteIpHeader -

setTrustedProxies

public void setTrustedProxies(java.lang.String commaDelimitedTrustedProxies)

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.


Apache Tomcat 6.0.43

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