Package org.jboss.netty.handler.ipfilter

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);