org.eclipse.jetty.server.handler

## Class IPAccessHandler

- java.lang.Object
- - org.eclipse.jetty.util.component.AbstractLifeCycle
  - - org.eclipse.jetty.util.component.AggregateLifeCycle
    - - org.eclipse.jetty.server.handler.AbstractHandler
      - - org.eclipse.jetty.server.handler.AbstractHandlerContainer
        - - org.eclipse.jetty.server.handler.HandlerWrapper
          - - org.eclipse.jetty.server.handler.IPAccessHandler

All Implemented Interfaces:
  Handler, HandlerContainer, Destroyable, Dumpable, LifeCycle

    public class IPAccessHandler
    extends HandlerWrapper

IP Access Handler

Controls access to the wrapped handler by the real remote IP. Control is provided by white/black lists that include both internet addresses and URIs. This handler uses the real internet address of the connection, not one reported in the forwarded for headers, as this cannot be as easily forged.

Typically, the black/white lists will be used in one of three modes:

- Blocking a few specific IPs/URLs by specifying several black list entries.
- Allowing only some specific IPs/URLs by specifying several white lists entries.
- Allowing a general range of IPs/URLs by specifying several general white list entries, that are then further refined by several specific black list exceptions

An empty white list is treated as match all. If there is at least one entry in the white list, then a request must match a white list entry. Black list entries are always applied, so that even if an entry matches the white list, a black list entry will override it.

Internet addresses may be specified as absolute address or as a combination of four octet wildcard specifications (a.b.c.d) that are defined as follows.

     nnn - an absolute value (0-255)
     mmm-nnn - an inclusive range of absolute values,
               with following shorthand notations:
               nnn- => nnn-255
               -nnn => 0-nnn
               -    => 0-255
     a,b,... - a list of wildcard specifications

Internet address specification is separated from the URI pattern using the "|" (pipe) character. URI patterns follow the servlet specification for simple * prefix and suffix wild cards (e.g. /, /foo, /foo/bar, /foo/bar/*, *.baz).

Earlier versions of the handler used internet address prefix wildcard specification to define a range of the internet addresses (e.g. 127., 10.10., 172.16.1.). They also used the first "/" character of the URI pattern to separate it from the internet address. Both of these features have been deprecated in the current version.

Examples of the entry specifications are:

- 10.10.1.2 - all requests from IP 10.10.1.2
- 10.10.1.2|/foo/bar - all requests from IP 10.10.1.2 to URI /foo/bar
- 10.10.1.2|/foo/* - all requests from IP 10.10.1.2 to URIs starting with /foo/
- 10.10.1.2|*.html - all requests from IP 10.10.1.2 to URIs ending with .html
- 10.10.0-255.0-255 - all requests from IPs within 10.10.0.0/16 subnet
- 10.10.0-.-255|/foo/bar - all requests from IPs within 10.10.0.0/16 subnet to URI /foo/bar
- 10.10.0-3,1,3,7,15|/foo/* - all requests from IPs addresses with last octet equal to 1,3,7,15 in subnet 10.10.0.0/22 to URIs starting with /foo/

Earlier versions of the handler used internet address prefix wildcard specification to define a range of the internet addresses (e.g. 127., 10.10., 172.16.1.). They also used the first "/" character of the URI pattern to separate it from the internet address. Both of these features have been deprecated in the current version.

### Nested Class Summary

### Nested classes/interfaces inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

`AbstractLifeCycle.AbstractLifeCycleListener`

### Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.LifeCycle

`LifeCycle.Listener`

### Field Summary

### Fields inherited from class org.eclipse.jetty.server.handler.HandlerWrapper

`_handler`

### Fields inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

`_listeners, FAILED, RUNNING, STARTED, STARTING, STOPPED, STOPPING`

### Constructor Summary

Constructors
Constructor and Description
`IPAccessHandler()` Creates new handler object
`IPAccessHandler(String[] white, String[] black)` Creates new handler object and initializes white- and black-list

### Method Summary

Methods
`protected void` `add(String entry, IPAddressMap<PathMap> patternMap)` Helper method to parse the new entry and add it to the specified address pattern map.
`void` `addBlack(String entry)` Add a blacklist entry to an existing handler configuration
`void` `addWhite(String entry)` Add a whitelist entry to an existing handler configuration
`protected void` `doStart()` Dump the white- and black-list configurations when started
`String` `dump()` Dump the handler configuration
`protected void` `dump(StringBuilder buf, IPAddressMap<PathMap> patternMap)` Dump a pattern map into a StringBuilder buffer
`void` `handle(String target, Request baseRequest, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Checks the incoming request against the whitelist and blacklist
`protected boolean` `isAddrUriAllowed(String addr, String path)` Check if specified request is allowed by current IPAccess rules.
`protected void` `set(String[] entries, IPAddressMap<PathMap> patternMap)` Helper method to process a list of new entries and replace the content of the specified address pattern map
`void` `setBlack(String[] entries)` Re-initialize the blacklist of existing handler object
`void` `setWhite(String[] entries)` Re-initialize the whitelist of existing handler object

### Methods inherited from class org.eclipse.jetty.server.handler.HandlerWrapper

`destroy, doStop, expandChildren, getHandler, getHandlers, getNestedHandlerByClass, setHandler, setServer`

### Methods inherited from class org.eclipse.jetty.server.handler.AbstractHandlerContainer

`dump, expandHandler, findContainerOf, getChildHandlerByClass, getChildHandlers, getChildHandlersByClass`

### Methods inherited from class org.eclipse.jetty.server.handler.AbstractHandler

`dumpThis, getServer`

### Methods inherited from class org.eclipse.jetty.util.component.AggregateLifeCycle

`addBean, addBean, contains, dump, dump, dump, dumpObject, dumpStdErr, getBean, getBeans, getBeans, isManaged, manage, removeBean, removeBeans, unmanage`

### Methods inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

`addLifeCycleListener, getState, getState, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeLifeCycleListener, start, stop`

### Methods inherited from class java.lang.Object

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

### Methods inherited from interface org.eclipse.jetty.util.component.LifeCycle

`addLifeCycleListener, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeLifeCycleListener, start, stop`

### Constructor Detail

#### IPAccessHandler

    public IPAccessHandler()

Creates new handler object

#### IPAccessHandler

    public IPAccessHandler(String[] white,
                   String[] black)

Creates new handler object and initializes white- and black-list

Parameters:
  `white` - array of whitelist entries
  `black` - array of blacklist entries

### Method Detail

#### addWhite

    public void addWhite(String entry)

Add a whitelist entry to an existing handler configuration

Parameters:
  `entry` - new whitelist entry

#### addBlack

    public void addBlack(String entry)

Add a blacklist entry to an existing handler configuration

Parameters:
  `entry` - new blacklist entry

#### setWhite

    public void setWhite(String[] entries)

Re-initialize the whitelist of existing handler object

Parameters:
  `entries` - array of whitelist entries

#### setBlack

    public void setBlack(String[] entries)

Re-initialize the blacklist of existing handler object

Parameters:
  `entries` - array of blacklist entries

#### handle

    public void handle(String target,
              Request baseRequest,
              javax.servlet.http.HttpServletRequest request,
              javax.servlet.http.HttpServletResponse response)
                throws IOException,
                       javax.servlet.ServletException

Checks the incoming request against the whitelist and blacklist

Specified by:
  `handle` in interface `Handler`
Overrides:
  `handle` in class `HandlerWrapper`
Parameters:
  `target` - The target of the request - either a URI or a name.
  `baseRequest` - The original unwrapped request object.
  `request` - The request either as the `Request` object or a wrapper of that request. The `AbstractHttpConnection.getCurrentConnection()` method can be used access the Request object if required.
  `response` - The response as the `Response` object or a wrapper of that request. The `AbstractHttpConnection.getCurrentConnection()` method can be used access the Response object if required.
Throws:
  `IOException`
  `javax.servlet.ServletException`
See Also:
  `HandlerWrapper.handle(java.lang.String, org.eclipse.jetty.server.Request, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`

#### add

    protected void add(String entry,
           IPAddressMap<PathMap> patternMap)

Helper method to parse the new entry and add it to the specified address pattern map.

Parameters:
  `entry` - new entry
  `patternMap` - target address pattern map

#### set

    protected void set(String[] entries,
           IPAddressMap<PathMap> patternMap)

Helper method to process a list of new entries and replace the content of the specified address pattern map

Parameters:
  `entries` - new entries
  `patternMap` - target address pattern map

#### isAddrUriAllowed

    protected boolean isAddrUriAllowed(String addr,
                           String path)

Check if specified request is allowed by current IPAccess rules.

Parameters:
  `addr` - internet address
  `path` - context path
Returns:
  true if request is allowed

#### doStart

    protected void doStart()
                    throws Exception

Dump the white- and black-list configurations when started

Overrides:
  `doStart` in class `HandlerWrapper`
Throws:
  `Exception`
See Also:
  `HandlerWrapper.doStart()`

#### dump

    public String dump()

Dump the handler configuration

Specified by:
  `dump` in interface `Dumpable`
Overrides:
  `dump` in class `AggregateLifeCycle`

#### dump

    protected void dump(StringBuilder buf,
            IPAddressMap<PathMap> patternMap)

Dump a pattern map into a StringBuilder buffer

Parameters:
  `buf` - buffer
  `patternMap` - pattern map to dump