Apache Tomcat 6.0.53

## org.apache.catalina.valves
Class RemoteIpValve

    java.lang.Object
      org.apache.catalina.valves.ValveBase
          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 :

- 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:

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

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