NAME
    Config::IPFilter - Simple, rule-based IP filter

Synopsis
        use Config::IPFilter;
        my $filter = Config::IPFilter->new;
        my $rule   = $filter->add_rule('89.238.128.0', '89.238.191.255', 127,
                                     'Example range');

        # A list of example IPv4 addresses. IPv6 works too.
        my @ipv4 = qw[89.238.156.165 89.238.156.169 89.238.156.170 89.238.167.84
            89.238.167.86 89.238.167.99];

        # Check a list of ips
        say sprintf '%15s is %sbanned', $_, $filter->is_banned($_) ? '' : 'not '
            for @ipv4;

        # Lower the acces level by one pushes it below our ban threshold
        $rule->decrease_access_level;

        # Check a list of ips
        say sprintf '%15s is %sbanned', $_,
            $filter->is_banned($_) ? 'now ' : 'still not '
            for @ipv4;

    You could also load rules directly from an "ipfilter.dat" file.

Description
        # Example of a "ipfilter.dat" file
        #
        # All entered IP ranges will be blocked in both directions. Be careful
        # what you enter here. Wrong entries may totally block access to the
        # network.
        #
        # Format:
        # IP-Range , Access Level , Description
        #
        # Access Levels:
        # 127 blocked
        # >=127 permitted

        064.094.089.000 - 064.094.089.255 , 000 , Gator.com

    This entry will block the IPs from 064.094.089.000 to 064.094.089.255,
    i.e. your code should not connect to any IP in this range.

    At the moment only one, read-only access level is implemented; a value
    at or below 127 means that addresses in that range are banned.

Methods
    Here's a list of 'em...

  my $filter = Config::IPFilter->new( )
    This builds a new, empty object. There are currently no expected
    arguments.

  $filter->add_rule( $rule )
    This method adds a new range to the in-memory ipfilter.

  $filter->add_rule( $lower, $upper, $access_level, $description )
    This method coerces the arguments into a new rule which is then added to
    the in-memory ipfilter.

  $filter->count_rules( )
    Returns a tally of all loaded rules.

  $filter->is_empty( )
    Returns a boolean value indicating whether or not there are any rules
    loaded in the ipfilter.

  $filter->clear_rules( )
    Deletes all rules from the ipfilter.

  $filter->load( $path )
    Slurps an "ipfilter.dat"-like file and adds the rules found inside to
    the ipfilter.

  $filter->save( $path )
    Stores the in-memory ipfilter to disk.

  $filter->is_banned( $ip )
    If $ip is banned, the first rule in which it was found below the
    threshold is returned.

    If not, a false value is returned. Currently, rules with an access_level
    at or below 127 are considered banned.

IPv6 Support
    The standard ipfilter.dat only supports IPv4 addresses but
    Net::BitTorrent's current implementation supports IPv6 as well. Keep
    this in mind when storing an ipfilter.dat file to disk.

Notes
    This is a very good example of code which should not require Moose. In a
    future version, I hope to switch to Moo. ...when "coerce" works to some
    degree.

See Also
    Emule Project's ipfilter.dat documentation
    <http://www.emule-project.net/home/perl/help.cgi?l=1&topic_id=142&rm=sho
    w_topic>

Author
    Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

    CPAN ID: SANKO

License and Legal
    Copyright (C) 2010, 2011 by Sanko Robinson <sanko@cpan.org>

    This program is free software; you can redistribute it and/or modify it
    under the terms of The Artistic License 2.0
    <http://www.perlfoundation.org/artistic_license_2_0>. See the LICENSE
    file included with this distribution or notes on the Artistic License
    2.0 <http://www.perlfoundation.org/artistic_2_0_notes> for
    clarification.

    When separated from the distribution, all original POD documentation is
    covered by the Creative Commons Attribution-Share Alike 3.0 License
    <http://creativecommons.org/licenses/by-sa/3.0/us/legalcode>. See the
    clarification of the CCA-SA3.0
    <http://creativecommons.org/licenses/by-sa/3.0/us/>.