Net::IPAddress::Filter - A compact and fast IP Address range filter
version 20140113
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' ]
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.
Constructs new blank filter object.
Expects: None.
Returns: Blessed filter object.
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 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.
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.
Find any matching ranges for a given IP address. Each range holds a value field, and these values will be returned.
Returns: The value fields for any ranges spanning the test IP.
Utility function to convert the given IP addresses into numbers. It handles CIDR, and optional or out-of-order args.
Returns: Ordered pair of integers.
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.
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.
Support for IPv6 Addresses. This would need a lot of work, as
Set::IntervalTree uses long ints internally, and IPv6 needs 128-bit numbers.
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.
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
Net::IPAddress::Filter is hosted on github at https://github.com/d5ve/p5-Net-IPAddress-Filter.git
Dave Webb <Net-IPAddress-Filter@d5ve.com>
This software is copyright (c) 2014 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.
To install Net::IPAddress::Filter, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::IPAddress::Filter
CPAN shell
perl -MCPAN -e shell install Net::IPAddress::Filter
For more information on module installation, please visit the detailed CPAN module installation guide.