RemoteIpValve (Apache Tomcat 7.0.109 API Documentation)

java.lang.Object
- org.apache.catalina.util.LifecycleBase
- - org.apache.catalina.util.LifecycleMBeanBase
  - - org.apache.catalina.valves.ValveBase
    - - org.apache.catalina.valves.RemoteIpValve

All Implemented Interfaces:: MBeanRegistration, Contained, JmxEnabled, Lifecycle, 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 or trusted 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-proto) consists only of forwards that match 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.
Mark the request with the attribute Globals.REQUEST_FORWARDED_ATTRIBUTE and value Boolean.TRUE to indicate that this request has been forwarded by one or more 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	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}\| 0:0:0:0:0:0:0:1\|::1 By default, 10/8, 192.168/16, 169.254/16, 127/8 and ::1 are allowed.
proxiesHeader	Name of the http header created by this valve to hold the list of proxies that have been processed in the incoming `remoteIpHeader`	proxiesHeader	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 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"
   proxiesHeader="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"
   proxiesHeader="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"
   proxiesHeader="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"
   proxiesHeader="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 cannot trust that untrusted-proxy is the actual remote ip. request.remoteAddr is untrusted-proxy that is an IP verified by proxy1.

Nested Class Summary
- Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle
  Lifecycle.SingleUse

Field Summary
- Fields inherited from class org.apache.catalina.valves.ValveBase
  asyncSupported, container, containerLog, next, sm
- Fields inherited from class org.apache.catalina.util.LifecycleMBeanBase
  mserver
- Fields inherited from interface org.apache.catalina.Lifecycle
  AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT

Constructor Summary

Constructors
Constructor and Description

RemoteIpValve()
Default constructor that ensures ValveBase.ValveBase(boolean) is called with true.

Constructors
Constructor and Description
`RemoteIpValve()` Default constructor that ensures `ValveBase.ValveBase(boolean)` is called with `true`.

Method Summary

Methods
Modifier and Type	Method and Description
`protected static String[]`	`commaDelimitedListToStringArray(String commaDelimitedStrings)` Convert a given comma delimited String into an array of String
`String`	`getHostHeader()` Obtain the name of the HTTP header used to override the value returned by `Request.getServerName()` and (optionally depending on {link `isChangeLocalName()` `Request.getLocalName()`.
`int`	`getHttpServerPort()`
`int`	`getHttpsServerPort()`
`String`	`getInfo()` Return descriptive information about this Valve implementation.
`String`	`getInternalProxies()`
`String`	`getPortHeader()` Obtain the name of the HTTP header used to override the value returned by `Request.getServerPort()` and (optionally depending on {link `isChangeLocalPort()` `Request.getLocalPort()`.
`String`	`getProtocolHeader()`
`String`	`getProtocolHeaderHttpsValue()`
`String`	`getProxiesHeader()`
`String`	`getRemoteIpHeader()`
`boolean`	`getRequestAttributesEnabled()`
`String`	`getTrustedProxies()`
`void`	`invoke(Request request, Response response)` The implementation-specific logic represented by this Valve.
`boolean`	`isChangeLocalName()`
`boolean`	`isChangeLocalPort()`
`protected static String`	`listToCommaDelimitedString(List<String> stringList)` Convert an array of strings in a comma delimited string
`void`	`setChangeLocalName(boolean changeLocalName)`
`void`	`setChangeLocalPort(boolean changeLocalPort)`
`void`	`setHostHeader(String hostHeader)` Set the name of the HTTP header used to override the value returned by `Request.getServerName()` and (optionally depending on {link `isChangeLocalName()` `Request.getLocalName()`.
`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(String internalProxies)` Regular expression that defines the internal proxies.
`void`	`setPortHeader(String portHeader)` Set the name of the HTTP header used to override the value returned by `Request.getServerPort()` and (optionally depending on {link `isChangeLocalPort()` `Request.getLocalPort()`.
`void`	`setProtocolHeader(String protocolHeader)` Header that holds the incoming protocol, usually named `X-Forwarded-Proto`.
`void`	`setProtocolHeaderHttpsValue(String protocolHeaderHttpsValue)` Case insensitive value of the protocol header to indicate that the incoming http request uses SSL.
`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`	`setRequestAttributesEnabled(boolean requestAttributesEnabled)` Should this valve set request attributes for IP address, Hostname, protocol and port used for the request?
`void`	`setTrustedProxies(String trustedProxies)` Regular expression defining proxies that are trusted when they appear in the `remoteIpHeader` header.

Methods inherited from class org.apache.catalina.valves.ValveBase
backgroundProcess, event, getContainer, getDomainInternal, getNext, getObjectNameKeyProperties, initInternal, isAsyncSupported, setAsyncSupported, setContainer, setNext, startInternal, stopInternal, toString

Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase
destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister

Methods inherited from class org.apache.catalina.util.LifecycleBase
addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop

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

- Constructor Detail
  - RemoteIpValve
```
public RemoteIpValve()
```
    Default constructor that ensures ValveBase.ValveBase(boolean) is called with true.
- Method Detail
  - commaDelimitedListToStringArray
```
protected static String[] commaDelimitedListToStringArray(String commaDelimitedStrings)
```
    Convert a given comma delimited String into an array of String
    
    Parameters:
    commaDelimitedStrings - The string to convert
    
    Returns:
    array of String (non null)
  - listToCommaDelimitedString
```
protected static String listToCommaDelimitedString(List<String> stringList)
```
    Convert an array of strings in a comma delimited string
    
    Parameters:
    stringList - The string list to convert
    
    Returns:
    The concatenated string
  - getHostHeader
```
public String getHostHeader()
```
    Obtain the name of the HTTP header used to override the value returned by Request.getServerName() and (optionally depending on {link isChangeLocalName() Request.getLocalName().
    
    Returns:
    The HTTP header name
  - setHostHeader
```
public void setHostHeader(String hostHeader)
```
    Set the name of the HTTP header used to override the value returned by Request.getServerName() and (optionally depending on {link isChangeLocalName() Request.getLocalName().
    
    Parameters:
    hostHeader - The HTTP header name
  - isChangeLocalName
```
public boolean isChangeLocalName()
```
  - setChangeLocalName
```
public void setChangeLocalName(boolean changeLocalName)
```
  - getHttpServerPort
```
public int getHttpServerPort()
```
  - getHttpsServerPort
```
public int getHttpsServerPort()
```
  - getPortHeader
```
public String getPortHeader()
```
    Obtain the name of the HTTP header used to override the value returned by Request.getServerPort() and (optionally depending on {link isChangeLocalPort() Request.getLocalPort().
    
    Returns:
    The HTTP header name
  - setPortHeader
```
public void setPortHeader(String portHeader)
```
    Set the name of the HTTP header used to override the value returned by Request.getServerPort() and (optionally depending on {link isChangeLocalPort() Request.getLocalPort().
    
    Parameters:
    portHeader - The HTTP header name
  - isChangeLocalPort
```
public boolean isChangeLocalPort()
```
  - setChangeLocalPort
```
public void setChangeLocalPort(boolean changeLocalPort)
```
  - getInfo
```
public String getInfo()
```
    Return descriptive information about this Valve implementation.
    
    Specified by:
    
    getInfo in interface Valve
    
    Overrides:
    
    getInfo in class ValveBase
    
    Returns:
    descriptive information about this Valve implementation.
  - getInternalProxies
```
public String getInternalProxies()
```
    Returns:
    Regular expression that defines the internal proxies
    See Also:
    setInternalProxies(String)
  - getProtocolHeader
```
public String getProtocolHeader()
```
    Returns:
    the protocol header (e.g. "X-Forwarded-Proto")
    See Also:
    setProtocolHeader(String)
  - getProtocolHeaderHttpsValue
```
public String getProtocolHeaderHttpsValue()
```
    Returns:
    the value of the protocol header for incoming https request (e.g. "https")
    See Also:
    setProtocolHeaderHttpsValue(String)
  - getProxiesHeader
```
public String getProxiesHeader()
```
    Returns:
    the proxies header name (e.g. "X-Forwarded-By")
    See Also:
    setProxiesHeader(String)
  - getRemoteIpHeader
```
public String getRemoteIpHeader()
```
    Returns:
    the remote IP header name (e.g. "X-Forwarded-For")
    See Also:
    setRemoteIpHeader(String)
  - getRequestAttributesEnabled
```
public boolean getRequestAttributesEnabled()
```
    Returns:
    true if the attributes will be logged, otherwise false
    See Also:
    setRequestAttributesEnabled(boolean)
  - getTrustedProxies
```
public String getTrustedProxies()
```
    Returns:
    Regular expression that defines the trusted proxies
    See Also:
    setTrustedProxies(String)
  - invoke
```
public void invoke(Request request,
          Response response)
            throws IOException,
                   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:
    
    IOException - if an input/output error occurs
    
    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
    
    Parameters:
    httpServerPort - The server port
  - setHttpsServerPort
```
public void setHttpsServerPort(int httpsServerPort)
```
    Server Port value if the protocolHeader indicates HTTPS
    
    Default value : 443
    
    Parameters:
    httpsServerPort - The server port
  - setInternalProxies
```
public void setInternalProxies(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}|0:0:0:0:0:0:0:1
    
    Parameters:
    internalProxies - The proxy regular expression
  - setProtocolHeader
```
public void setProtocolHeader(String protocolHeader)
```
    Header that holds the incoming protocol, usually named X-Forwarded-Proto. If null, request.scheme and request.secure will not be modified.
    
    Default value : null
    
    Parameters:
    protocolHeader - The header name
  - 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
    
    Parameters:
    protocolHeaderHttpsValue - The header name
  - 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
    
    Parameters:
    proxiesHeader - The header name
  - 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 - The header name
  - setRequestAttributesEnabled
```
public void setRequestAttributesEnabled(boolean requestAttributesEnabled)
```
    Should this valve set request attributes for IP address, Hostname, protocol and port used for the request? This are typically used in conjunction with the AccessLog which will otherwise log the original values. Default is true. The attributes set are:
    - org.apache.catalina.AccessLog.RemoteAddr
    - org.apache.catalina.AccessLog.RemoteHost
    - org.apache.catalina.AccessLog.Protocol
    - org.apache.catalina.AccessLog.ServerPort
    - org.apache.tomcat.remoteAddr
    Parameters:
    requestAttributesEnabled - true causes the attributes to be set, false disables the setting of the attributes.
  - setTrustedProxies
```
public void setTrustedProxies(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.
    
    Parameters:
    trustedProxies - The regular expression

Class RemoteIpValve

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

Field Summary

Fields inherited from class org.apache.catalina.valves.ValveBase

Fields inherited from class org.apache.catalina.util.LifecycleMBeanBase

Fields inherited from interface org.apache.catalina.Lifecycle

Constructor Summary

Method Summary

Methods inherited from class org.apache.catalina.valves.ValveBase

Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase

Methods inherited from class org.apache.catalina.util.LifecycleBase

Methods inherited from class java.lang.Object

Constructor Detail

RemoteIpValve

Method Detail

commaDelimitedListToStringArray

listToCommaDelimitedString

getHostHeader

setHostHeader

isChangeLocalName

setChangeLocalName

getHttpServerPort

getHttpsServerPort

getPortHeader

setPortHeader

isChangeLocalPort

setChangeLocalPort

getInfo

getInternalProxies

getProtocolHeader

getProtocolHeaderHttpsValue

getProxiesHeader

getRemoteIpHeader

getRequestAttributesEnabled

getTrustedProxies

invoke

setHttpServerPort

setHttpsServerPort

setInternalProxies

setProtocolHeader

setProtocolHeaderHttpsValue

setProxiesHeader

setRemoteIpHeader

setRequestAttributesEnabled

setTrustedProxies