-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
163 lines (113 loc) · 5.16 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
NAME
Net::IPAddress::Filter - A compact and fast IP Address range filter
VERSION
version 20140113
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 <Net-IPAddress-Filter@d5ve.com>
COPYRIGHT AND LICENSE
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.