org.apache.catalina.valves

Class RemoteIpValve

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

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.connector.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.connector.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.connector.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.connector.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 StringManagersm
The StringManager for this package.
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
intgetHttpsServerPort()
StringgetInternalProxies()
StringgetProtocolHeader()
StringgetProtocolHeaderHttpsValue()
StringgetProxiesHeader()
StringgetRemoteIpHeader()
StringgetTrustedProxies()
protected static StringlistToCommaDelimitedString(List<String> stringList)
Convert an array of strings in a comma delimited string
protected static booleanmatchesOne(String str, Pattern... patterns)
Return true if the given str matches at least one of the given patterns.
voidsetHttpsServerPort(int httpsServerPort)

Server Port value if the protocolHeader indicates HTTPS

Default value : 443

voidsetInternalProxies(String commaDelimitedInternalProxies)

Comma delimited list of internal proxies.

voidsetProtocolHeader(String protocolHeader)

Header that holds the incoming protocol, usally named X-Forwarded-Proto.

voidsetProtocolHeaderHttpsValue(String protocolHeaderHttpsValue)

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

voidsetProxiesHeader(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.

voidsetRemoteIpHeader(String remoteIpHeader)

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

voidsetTrustedProxies(String commaDelimitedTrustedProxies)

Comma delimited list of proxies that are trusted when they appear in the RemoteIpValve header.

Field Detail

sm

protected static StringManager sm
The StringManager for this package.

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)

getHttpsServerPort

public int getHttpsServerPort()

getInternalProxies

public String getInternalProxies()

Returns: comma delimited list of internal proxies

See Also: setInternalProxies

getProtocolHeader

public String getProtocolHeader()

Returns: the protocol header (e.g. "X-Forwarded-Proto")

See Also: setProtocolHeader

getProtocolHeaderHttpsValue

public String getProtocolHeaderHttpsValue()

Returns: the value of the protocol header for incoming https request (e.g. "https")

See Also: setProtocolHeaderHttpsValue

getProxiesHeader

public String getProxiesHeader()

Returns: the proxies header name (e.g. "X-Forwarded-By")

See Also: setProxiesHeader

getRemoteIpHeader

public String getRemoteIpHeader()

Returns: the remote IP header name (e.g. "X-Forwarded-For")

See Also: setRemoteIpHeader

getTrustedProxies

public String getTrustedProxies()

Returns: comma delimited list of trusted proxies

See Also: setTrustedProxies

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.

setHttpsServerPort

public void setHttpsServerPort(int httpsServerPort)

Server Port value if the protocolHeader indicates HTTPS

Default value : 443

setInternalProxies

public void setInternalProxies(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}

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

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

Parameters: remoteIPHeader

setTrustedProxies

public void setTrustedProxies(String commaDelimitedTrustedProxies)

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

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

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