RemoteIpValve (Apache Tomcat 11.0.24 API Documentation)
Description: declaration: package: org.apache.catalina.valves, class: RemoteIpValve

# 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, 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` (default value `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 | Either a comma separated list of CIDR blocks or a single 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 | Comma separated list of CIDR blocks or a single regular expression `Pattern` | 10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,169.254.0.0/16,100.64.0.0/10,127.0.0.0/8,::1/128,fe80::/10,fc00::/7
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 | Either a comma separated list of CIDR blocks or a single regular expression that matches the IP addresses of internal proxies. If they appear in the `remoteIpHeader` value, they will be trusted and will appear in the `proxiesHeader` value | RemoteIPTrustedProxy | Comma separated list of CIDR blocks or a single regular expression `Pattern` |
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` | `X-Forwarded-Proto`
protocolHeaderHttpsValue | Value of the `protocolHeader` to indicate that it is a 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.

Sample with internal proxies

RemoteIpValve configuration:

`<Valve className="org.apache.catalina.valves.RemoteIpValve" internalProxies="192.168.0.10/31" 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/31" 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/31" 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/31" 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 Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  ### Fields inherited from class ValveBase

  `asyncSupported, container, containerLog, next, sm`

  ### Fields inherited from interface 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
  Description
  `RemoteIpValve()`
  Default constructor that ensures `ValveBase(boolean)` is called with `true`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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()`
  Returns the configured HTTP server port.
  `int`
  `getHttpsServerPort()`
  Returns the configured HTTPS server port.
  `String`
  `getInternalProxies()`
  Obtain the currently configured internal proxies.
  `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()`
  Return the configured protocol header name.
  `String`
  `getProtocolHeaderHttpsValue()`
  Return the configured protocol header HTTPS value.
  `String`
  `getProxiesHeader()`
  Return the configured proxies header name.
  `String`
  `getRemoteIpHeader()`
  Return the configured remote IP header name.
  `boolean`
  `getRequestAttributesEnabled()`
  Return whether request attributes are enabled.
  `String`
  `getTrustedProxies()`
  Obtain the currently configured trusted proxies.
  `void`
  `invoke(Request request, Response response)`
  Perform request processing as required by this Valve.
  `boolean`
  `isChangeLocalName()`
  Returns whether the local name should be changed.
  `boolean`
  `isChangeLocalPort()`
  Returns whether the local port should be changed.
  `void`
  `setChangeLocalName(boolean changeLocalName)`
  Set whether the local name should be changed.
  `void`
  `setChangeLocalPort(boolean changeLocalPort)`
  Set whether the local port should be changed.
  `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
  `void`
  `setHttpsServerPort(int httpsServerPort)`
  Server Port value if the `protocolHeader` indicates HTTPS
  `void`
  `setInternalProxies(String internalProxies)`
  Set the internal proxies either as a comma separated list of CIDR blocks or a single regular expression.
  `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)`
  Set the trusted proxies either as a comma separated list of CIDR blocks or a single regular expression.

  ### Methods inherited from class ValveBase

  `backgroundProcess, getContainer, getDomainInternal, getNext, getObjectNameKeyProperties, initInternal, isAsyncSupported, setAsyncSupported, setContainer, setNext, startInternal, stopInternal, toString`

  ### Methods inherited from class LifecycleMBeanBase

  `destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregister`

  ### Methods inherited from class LifecycleBase

  `addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop`

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### RemoteIpValve

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

- ## Method Details

  - ### 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()
    Returns whether the local name should be changed.
    Returns:
      `true` if the local name should be changed

  - ### setChangeLocalName

    public void setChangeLocalName(boolean changeLocalName)
    Set whether the local name should be changed.
    Parameters:
      `changeLocalName` - `true` to change the local name

  - ### getHttpServerPort

    public int getHttpServerPort()
    Returns the configured HTTP server port.
    Returns:
      the HTTP server port

  - ### getHttpsServerPort

    public int getHttpsServerPort()
    Returns the configured HTTPS server port.
    Returns:
      the HTTPS server port

  - ### 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()
    Returns whether the local port should be changed.
    Returns:
      `true` if the local port should be changed

  - ### setChangeLocalPort

    public void setChangeLocalPort(boolean changeLocalPort)
    Set whether the local port should be changed.
    Parameters:
      `changeLocalPort` - `true` to change the local port

  - ### getInternalProxies

    public String getInternalProxies()
    Obtain the currently configured internal proxies.
    Returns:
      The currently configured internal proxies.

  - ### getProtocolHeader

    public String getProtocolHeader()
    Return the configured protocol header name.
    Returns:
      the protocol header name (e.g. "X-Forwarded-Proto")
    See Also:
      - `setProtocolHeader(String)`

  - ### getProtocolHeaderHttpsValue

    public String getProtocolHeaderHttpsValue()
    Return the configured protocol header HTTPS value.
    Returns:
      the protocol header value for HTTPS requests (e.g. "https")
    See Also:
      - `setProtocolHeaderHttpsValue(String)`

  - ### getProxiesHeader

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

  - ### getRemoteIpHeader

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

  - ### getRequestAttributesEnabled

    public boolean getRequestAttributesEnabled()
    Return whether request attributes are enabled.
    Returns:
      `true` if request attributes are enabled
    See Also:
      - `setRequestAttributesEnabled(boolean)`

  - ### getTrustedProxies

    public String getTrustedProxies()
    Obtain the currently configured trusted proxies.
    Returns:
      The currently configured trusted proxies.

  - ### invoke

    public void invoke(Request request, Response response) throws IOException, ServletException
    Description copied from interface: `Valve`

    Perform request processing as required by this Valve.

    An individual Valve MAY perform the following actions, in the specified order:

    - Examine and/or modify the properties of the specified Request and Response.
    - Examine the properties of the specified Request, completely generate the corresponding Response, and return control to the caller.
    - Examine the properties of the specified Request and Response, wrap either or both of these objects to supplement their functionality, and pass them on.
    - If the corresponding Response was not generated (and control was not returned), call the next Valve in the pipeline (if there is one) by executing `getNext().invoke()`.
    - Examine, but not modify, the properties of the resulting Response (which was created by a subsequently invoked Valve or Container).

    A Valve MUST NOT do any of the following things:

    - Change request properties that have already been used to direct the flow of processing control for this request (for instance, trying to change the virtual host to which a Request should be sent from a pipeline attached to a Host or Context in the standard implementation).
    - Create a completed Response AND pass this Request and Response on to the next Valve in the pipeline.
    - Consume bytes from the input stream associated with the Request, unless it is completely generating the response, or wrapping the request before passing it on.
    - Modify the HTTP headers included with the Response after the `getNext().invoke()` method has returned.
    - Perform any actions on the output stream associated with the specified Response after the `getNext().invoke()` method has returned.
    Parameters:
      `request` - The servlet request to be processed
      `response` - The servlet response to be created
    Throws:
      `IOException` - if an input/output error occurs, or is thrown by a subsequently invoked Valve, Filter, or Servlet
      `ServletException` - if a servlet error occurs, or is thrown by a subsequently invoked Valve, Filter, or Servlet

  - ### 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)
    Set the internal proxies either as a comma separated list of CIDR blocks or a single regular expression.
    Parameters:
      `internalProxies` - The new internal proxies

  - ### 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 : `X-Forwarded-Proto`

    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? These 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)
    Set the trusted proxies either as a comma separated list of CIDR blocks or a single regular expression.
    Parameters:
      `trustedProxies` - The new trusted proxies