# Package org.jboss.netty.handler.ipfilter

Implementation of a Ip based Filter handlers.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  IpFilteringHandler | The Interface IpFilteringHandler.
  IpFilterListener | The listener interface for receiving ipFilter events.
  IpFilterRule | This Interface defines an Ip Filter Rule.
  IpSet | This Interface defines an IpSet object.

- Class Summary
  Class | Description
  --- | ---
  CIDR |
  CIDR4 |
  CIDR6 |
  IpFilteringHandlerImpl | General class that handle Ip Filtering.
  IpFilterRuleHandler | Implementation of Filter of IP based on ALLOW and DENY rules.
  IpFilterRuleList | The Class IpFilterRuleList is a helper class to generate a List of Rules from a string.
  IpSubnet | This class allows to check if an IP V4 or V6 Address is contained in a subnet.
  IpSubnetFilterRule | Ip V4 and Ip V6 filter rule.
  IpV4Subnet | This class allows to check if an IP-V4-Address is contained in a subnet.
  IpV4SubnetFilterRule | IpV4 only Filter Rule
  OneIpFilterHandler | Handler that block any new connection if there are already a currently active channel connected with the same InetAddress (IP).
  PatternRule | The Class PatternRule represents an IP filter rule using string patterns.

## Package org.jboss.netty.handler.ipfilter Description

Implementation of a Ip based Filter handlers.

The main goal of this package is to allow to filter connections based on IP rules. The main interface is ``IpFilteringHandler`` which all filters will extend.

Two IP filtering are proposed:

- `OneIpFilterHandler`: This filter proposes to allow only one connection by client's IP Address. I.E. this filter will prevent two connections from the same client based on its IP address.
- `IpFilterRuleHandler`: This filter proposes to allow or block IP range (based on standard notation or on CIDR notation) when the connection is running. It relies on another class like `IpV4SubnetFilterRule` (IPV4 support only), `IpSubnetFilterRule` (IPV4 and IPV6 support) or `PatternRule` (string pattern support) which implements those Ip ranges.

Standard use could be as follow: The accept method must be overridden (of course you can override others).

- `accept` method allows to specify your way of choosing if a new connection is to be allowed or not.
In `OneIpFilterHandler` and `IpFilterRuleHandler`, this method is already implemented.
- handleRefusedChannel method is executed when the accept method filters (blocks, so returning false) the new connection. This method allows you to implement specific actions to be taken before the channel is closed. After this method is called, the channel is immediately closed.
So if you want to send back a message to the client, don't forget to return a respectful ChannelFuture, otherwise the message could be missed since the channel will be closed immediately after this call and the waiting on this channelFuture (at least with respect of asynchronous operations).
Per default implementation this method invokes an `IpFilterListener` or returns null if no listener has been set.
- `continues` is called when any event appears after CONNECTED event and only for blocked channels.
It should return True if this new event has to go to next handlers in the pipeline if any, and False (default) if no events has to be passed to the next handlers when a channel is blocked. This is intend to prevent any unnecessary action since the connection is refused.
However, you could change its behavior for instance because you don't want that any event will be blocked by this filter by returning always true or according to some events.
Note that OPENED and BOUND events are still passed to the next entry in the pipeline since those events come out before the CONNECTED event, so there is no possibility to filter those two events before the CONNECTED event shows up. Therefore, you might want to let CLOSED and UNBOUND be passed to the next entry in the pipeline.
Per default implementation this method invokes an `IpFilterListener` or returns false if no listener has been set.
- Finally `handleUpstream` traps the CONNECTED and DISCONNECTED events.
If in the CONNECTED events the channel is blocked (`accept` refused the channel), then any new events on this channel will be blocked.
However, you could change its behavior for instance because you don't want that all events will be blocked by this filter by testing the result of isBlocked, and if so, calling `ctx.sendUpstream(e);` after calling the super method or by changing the `continues` method.

A typical setup for ip filter for TCP/IP socket would be:

     ChannelPipeline pipeline = ...;

     IpFilterRuleHandler firewall = new IpFilterRuleHandler();
     firewall.addAll(new IpFilterRuleList("+n:localhost, +c:192.168.0.0/27, -n:*"));
     pipeline.addFirst("firewall", firewall);

Copyright © 2008-2012 The Netty Project. All Rights Reserved.