NAME Net::IPAddress::Filter - A compact and fast IP Address range filter VERSION version 20121117 SYNOPSIS my $filter = Net::IPAddress::Filter->new(); # # Simple usage: # $filter->add_range('10.0.0.10', '10.0.0.50'); $filter->add_range('192.168.1.1'); print "In filter\n" if $filter->in_filter('10.0.0.25'); # # CIDR syntax # $filter->add_range('172.168.0.0/24'); # Equivalent to: $filter->add_range('172.168.0.0', '172.168.0.255'); # # Annotated ranges # $filter->add_range_with_value('IANA-reserved range', '10.0.0.0', '10.255.255.255'); my $array_ref = $filter->get_matches('10.128.0.0'); # [ 'IANA-reserved range' ] DESCRIPTION Net::IPAddress::Filter can be used to check if a given IP address is contained in a set of filtered ranges. A range can contain any number of addresses, and ranges can overlap. Net::IPAddress::Filter uses the XS module Set::IntervalTree under the hood. An Interval Tree is a data structure optimised for fast insertions and searches of ranges, so sequential scans are avoided. The XS tree data structure is more compact than a pure Perl version of the same. In testing on an AMD Athlon(tm) 64 X2 Dual Core Processor 4200+, Net::IPAddress::Filter did about 60k range inserts per second, and about 140k lookups per second. The process memory size grew by about 1MB per 10,000 ranges inserted. METHODS new ( ) Constructs new blank filter object. Expects: None. Returns: Blessed filter object. add_range( ) Add a range of IP addresses to the filter. The range can be specified in three ways. 1) As a single IP address. 2) As a pair of IP addresses. 3) As a single IP address with a CIDR suffix. In this case, any second IP address passed in by the caller will be ignored. Expects: $start_ip - A dotted quad IP address string with optional CIDR suffix. $end_ip - An optional dotted quad IP address string. Defaults to $start_ip. Returns: 1 if it didn't die in the attempt - insert() returns undef. add_range_with_value( ) Add a range of IP addresses to the filter, plus associate a scalar value with that range. I couldn't think of a neat way to handle an optional value and an optional range end in the same method, otherwise I would have put this in add_range(). Expects: $value - A perl scalar to associate with this range. $start_ip - A dotted quad IP address string with optional CIDR suffix. $end_ip - An optional dotted quad IP address string. Defaults to $start_ip. Returns: 1 if it didn't die in the attempt - insert() returns undef. in_filter( ) Test whether a given IP address is in one of the ranges in the filter. Expects: $test_ip - A dotted quad IP address string. Returns: Number of ranges which span the test IP. get_matches( ) Find any matching ranges for a given IP address. Each range holds a value field, and these values will be returned. Expects: $test_ip - A dotted quad IP address string. Returns: The value fields for any ranges spanning the test IP. FUNCTIONS _get_start_and_end_numbers( ) Utility function to convert the given IP addresses into numbers. It handles CIDR, and optional or out-of-order args. Expects: $start_ip - A dotted quad IP address string with optional CIDR suffix. $end_ip - An optional dotted quad IP address string. Defaults to $start_ip. Returns: Ordered pair of integers. _ip_address_to_number( ) Utility function to convert a dotted quad IP address to a number. TODO: Handle IPv6 addresses as well. Expects: A dotted quad IP address string. Returns: The integer representation of the IP address. CAVEATS AND TIPS * Set::IntervalTree versions < 0.03 have a known bug where in_filter('128.0.0.0') will give a false positive if there are any ranges in the filter. 128.0.0.0 is 2^31. This is fixed in version 0.03 onwards. TODO * Support for IPv6 Addresses. This would need a lot of work, as Set::IntervalTree uses long ints internally, and IPv6 needs 128-bit numbers. SEE ALSO * Config::IPFilter - Moose-based pure Perl IP address filter. * Net::BitTorrent::Network::IPFilter - Moose-based pure Perl IP address filter. * NET::IPFilter - Pure Perl extension for Accessing eMule / Bittorrent IPFilter.dat Files and checking a given IP against this ipfilter.dat IP Range. BUGS OR FEATURE REQUESTS See https://rt.cpan.org/Public/Dist/Display.html?Name=Net-IPAddress-Filter to report and view bugs, or to request features. Alternatively, email bug-Net-IPAddress-Filter@rt.cpan.org REPOSITORY Net::IPAddress::Filter is hosted on github at https://github.com/d5ve/p5-Net-IPAddress-Filter.git AUTHOR Dave Webb COPYRIGHT AND LICENSE This software is copyright (c) 2012 by Dave Webb. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.