IPAccessHandler (Jetty :: Aggregate :: All core Jetty 7.6.8.v20121106 API)
Date: 2012-11-06

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
    Modifier and Type | Method and Description
    --- | ---
    `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

Copyright © 1995-2012 Mort Bay Consulting. All Rights Reserved.