org.apache.catalina.valves

## Class RemoteIpValve

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

    - ### 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`.

  - ### 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
    `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` | `isChangeLocalPort()`
    `protected static String` | `listToCommaDelimitedString(List<String> stringList)` Convert an array of strings in a comma delimited string
    `void` | `setChangeLocalPort(boolean changeLocalPort)`
    `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, init, removeLifecycleListener, setState, setState, 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
      Returns:
        array of String (non `null`)

    - #### listToCommaDelimitedString

          protected static String listToCommaDelimitedString(List<String> stringList)

      Convert an array of strings in a comma delimited string

    - #### getHttpsServerPort

          public int getHttpsServerPort()

    - #### getHttpServerPort

          public int getHttpServerPort()

    - #### isChangeLocalPort

          public boolean isChangeLocalPort()

    - #### setChangeLocalPort

          public void setChangeLocalPort(boolean changeLocalPort)

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

    - #### getInfo

          public String getInfo()

      Return descriptive information about this Valve implementation.
      Specified by:
        `getInfo` in interface `Valve`
      Overrides:
        `getInfo` in class `ValveBase`

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

    - #### setHttpsServerPort

          public void setHttpsServerPort(int httpsServerPort)

      Server Port value if the `protocolHeader` indicates HTTPS

      Default value : 443

    - #### 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}

    - #### 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`

    - #### 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` -

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

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