1NAME
2 Net::Netmask - parse, manipulate and lookup IP network blocks
3
4SYNOPSIS
5 use Net::Netmask;
6
7 $block = Net::Netmask->safe_new(network block)
8 $block = Net::Netmask->safe_new(network block, netmask)
9 $block = Net::Netmask->new2(network block)
10 $block = Net::Netmask->new2(network block, netmask)
11 $block = Net::Netmask->new(network block) # Don't use in new code!
12 $block = Net::Netmask->new(network block, netmask) # Don't use in new code!
13
14 print $block; # a.b.c.d/bits or 1:2:3::4/bits
15 print $block->base()
16 print $block->mask()
17 print $block->hostmask()
18 print $block->bits()
19 print $block->size()
20 print $block->maxblock()
21 print $block->broadcast()
22 print $block->next()
23 print $block->match($ip);
24 print $block->nth(1, [$bitstep]);
25 print $block->protocol();
26
27 if ($block->sameblock("network block")) ...
28 if ($block->cmpblocks("network block")) ...
29
30 $newblock = $block->nextblock([count]);
31
32 for $ip ($block->enumerate([$bitstep])) { }
33
34 for $zone ($block->inaddr()) { }
35
36 my $table = {};
37 $block->storeNetblock([$table])
38 $block->deleteNetblock([$table])
39 @missingblocks = $block->cidrs2inverse(@blocks)
40
41 $block = findNetblock(ip, [$table])
42 $block = findOuterNetblock(ip, [$table])
43 @blocks = findAllNetblock(ip, [$table])
44 if ($block->checkNetblock([$table]) ...
45 $block2 = $block1->findOuterNetblock([$table])
46 @blocks = dumpNetworkTable([$table])
47
48 @blocks = range2cidrlist($beginip, $endip);
49 @blocks = cidrs2cidrs(@blocks_with_dups)
50
51 @listofblocks = cidrs2contiglists(@blocks);
52
53 @blocks = sort @blocks
54 @blocks = sort_network_blocks(@blocks)
55
56 @sorted_ip_addrs = sort_by_ip_address(@unsorted_ip_addrs)
57
58DESCRIPTION
59 Net::Netmask parses and understands IPv4 and IPv6 CIDR blocks (see
60 <https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing> for more
61 information on CIDR blocks). It's built with an object-oriented
62 interface, with functions being methods that operate on a Net::Netmask
63 object.
64
65 These methods provide nearly all types of information about a network
66 block that you might want.
67
68 There are also functions to insert a network block into a table and then
69 later lookup network blocks by IP address using that table. There are
70 functions to turn a IP address range into a list of CIDR blocks. There
71 are functions to turn a list of CIDR blocks into a list of IP addresses.
72
73 There is a function for sorting by text IP address.
74
75 All functions understand both IPv4 and IPv6. Matches, finds, etc, will
76 always return false when an IPv4 address is matched against an IPv6
77 address.
78
79 IPv6 support was added in 1.9104.
80
81CONSTRUCTING
82 Net::Netmask objects are created with an IP address and optionally a
83 mask. There are many forms that are recognized:
84
85 '216.240.32.0/24' The preferred IPv6 form.
86
87 '216.240.32.0:255.255.255.0'
88 '216.240.32.0-255.255.255.0'
89 '216.240.32.0', '255.255.255.0'
90 '216.240.32.0', '0xffffff00'
91 '216.240.32.0 - 216.240.32.255'
92 '216.240.32.4' A /32 block.
93
94 'default' or 'any' 0.0.0.0/0 (the default route)
95
96 '216.240.32.0#0.0.31.255' A hostmask (as used by Cisco
97 access-lists - that is, the hostmask is
98 the bitwise inverse of a netmask).
99
100 '2001:db8:1234:5678::/64' The preferred IPv6 form.
101
102 '2001:db8:1234:5678::9876' A /128 block.
103
104 'default6' or 'any6' ::/0 (the default route)
105
106 There are two constructor methods: "new" and "safe_new" (also known as
107 "new2").
108
109 "safe_new" differs from "new" in that it will return undef for invalid
110 netmasks, while "new" will return a netmask object even if the
111 constructor could not figure out what the network block should be.
112
113 With "new", the error string can be found as $block->{'ERROR'}. With
114 "safe_new" the error can be found as Net::Netmask::errstr or
115 $Net::Netmask::error.
116
117 IMPORTANT: You want to use "safe_new" or "new2" ("new2" is a synonym for
118 "new") in new code!
119
120 As of version 2.000, the following abbreviated IPv4 netblocks are not
121 accepted by default, but can be accepted with options.
122
123 '216.240.32' Always a /24 block.
124
125 '216.240' Always a /16 block.
126
127 '140' Always a /8 block.
128
129 '216.240.32/24'
130 '216.240/16'
131
132 To accept these, you can call the constructor with a "shortnet" option
133 set to a true value. Example:
134
135 my $block = Net::Netmask->safe_new("216.240/16", shortnet => 1);
136
137 For compatibility with older codebases, it's also possible to change the
138 default to use the old behavior. To do this, you can set the
139 $Net::Netmask::SHORTNET_DEFAULT variable to a true value. It is
140 recommended that this be done by localizing the variable. Example:
141
142 local $Net::Netmask::SHORTNET_DEFAULT = 1
143 my $block = Net::Netmask->safe_new("216.240/16");
144
145 Please be aware that there are security implications to this as other
146 Perl modules, system libraries, or utilities may not parse these
147 addresses the same way. This is why the default was changed.
148
149 For instance:
150
151 perl -MNet::Netmask -E "say Net::Netmask->safe_new("10.20", shortnet => 1)"
152
153 Will print "10.2.0.0/16". However:
154
155 perl -MSocket -E "say inet_ntoa(inet_aton('10.20'))"
156
157 Will often print "10.0.0.20" which is obviously very different, and if
158 the Net::Netmask module was used to check an IP aggainst an ACL, and
159 then another program was executed (that uses inet_aton(), for instance),
160 the ACL processing might not match the connection.
161
162 Thus, it is advised to use this with caution.
163
164METHODS
165 ->desc() Returns a description of the network block. Eg:
166 "216.240.32.0/19" or "2001:db8:1234::/48". This
167 is also available as overloaded
168 stringification.
169
170 ->base() Returns base address of the network block as a
171 string. Eg: "216.240.32.0". or
172 "2001:db8:1234::/48". Base does not give an
173 indication of the size of the network block.
174
175 ->mask() Returns the netmask as a string. Eg:
176 "255.255.255.0" or "ffff:ffff:ffff:ffff::"
177
178 ->hostmask() Returns the host mask which is the opposite of
179 the netmask. Eg: "0.0.0.255" or
180 "::ffff:ffff:ffff:ffff".
181
182 ->bits() Returns the netmask as a number of bits in the
183 network portion of the address for this block.
184 Eg: 24.
185
186 ->size() Returns the number of IP addresses in a block.
187 Eg: 256. For IPv6 addresses, this will be a
188 Math::BigInt object.
189
190 ->broadcast() The blocks broadcast address. (The last IP
191 address inside the block.) Eg: 192.168.1.0/24
192 => 192.168.1.255 or 2001:db8::/64 =>
193 2001:db8::ffff:ffff:ffff:ffff
194
195 ->next() The first IP address following the block. (The
196 IP address following the broadcast address.)
197 Eg: 192.168.1.0/24 => 192.168.2.0 or
198 2001:db8:0:1::/64 => 2001:db8:0:2::/64
199
200 ->first() & ->last() Synonyms for ->base() and ->broadcast()
201
202 ->protocol() Added in version 1.9102.
203
204 Returns the address family/protocol represented
205 by the block. Either 'IPv4' or 'IPv6'.
206
207 ->match($ip) Returns a true if the IP number $ip matches the
208 given network. That is, a true value is
209 returned if $ip is between base() and
210 broadcast(). For example, if we have the
211 network 192.168.1.0/24, then
212
213 192.168.0.255 => 0
214 192.168.1.0 => "0 "
215 192.168.1.1 => 1
216 ...
217 192.168.1.255 => 255
218
219 $ip should be a dotted-quad (eg:
220 "192.168.66.3") or an IPv6 address in standard
221 notation (eg: "2001:db8::1").
222
223 It just happens that the return value is the
224 position within the block. Since zero is a
225 legal position, the true string "0 " is
226 returned in it's place. "0 " is numerically
227 zero though. When wanting to know the position
228 inside the block, a good idiom is:
229
230 $pos = $block->match($ip) or die;
231 $pos += 0;
232
233 ->maxblock() Much of the time, it is not possible to
234 determine the size of a network block just from
235 it's base address. For example, with the
236 network block '216.240.32.0/27', if you only
237 had the '216.240.32.0' portion you wouldn't be
238 able to tell for certain the size of the block.
239 '216.240.32.0' could be anything from a '/23'
240 to a '/32'. The maxblock() method gives the
241 size of the largest block that the current
242 block's address would allow it to be. The size
243 is given in bits. Eg: 23.
244
245 ->enumerate([$bitstep) Returns a list of all the IP addresses in the
246 block. Be very careful not to use this function
247 of large blocks. The IP addresses are returned
248 as strings. Eg: '216.240.32.0', '216.240.32.1',
249 ... '216.240.32.255'.
250
251 If the optional argument is given, step through
252 the block in increments of a given network
253 size. To step by 4, use a bitstep of 30 (as in
254 a /30 network).
255
256 Note that for IPv6, this will return failure if
257 more than 1,000,000,000 addresses would be
258 returned.
259
260 ->nth($index, [$bitstep])
261 Returns the nth element of the array that
262 enumerate would return if it were called. So,
263 to get the first usable address in a block, use
264 nth(1). To get the broadcast address, use
265 nth(-1). To get the last usable address, use
266 nth(-2).
267
268 ->inaddr() Returns an inline list of tuples.
269
270 For IPv4:
271
272 There is a tuple for each DNS zone name (at the
273 /24 level) in the block. If the block is
274 smaller than a /24, then the zone of the
275 enclosing /24 is returned.
276
277 Each tuple contains: the DNS zone name, the
278 last component of the first IP address in the
279 block in that zone, the last component of the
280 last IP address in the block in that zone.
281
282 Examples: the list returned for the block
283 '216.240.32.0/23' would be:
284 '32.240.216.in-addr.arpa', 0, 255,
285 '33.240.216.in-addr.arpa', 0, 255. The list
286 returned for the block '216.240.32.64/27' would
287 be: '32.240.216.in-addr.arpa', 64, 95.
288
289 For IPv6:
290
291 A list is returned with each DNS zone name at
292 the shortest-prefix length possible. This is
293 not returned as a tuple, but just a list of
294 strings.
295
296 Examples: the list returned for the block
297 '2002::/16' would be a one element list,
298 containing just 2.0.0.2.ip6.arpa'. The list for
299 '2002::/17' would return a two element list
300 containing '0.2.0.0.2.ip6.arpa' and
301 '1.2.0.0.2.ip6.arpa'.
302
303 ->nextblock([$count]) Without a $count, return the next block of the
304 same size after the current one. With a count,
305 return the Nth block after the current one. A
306 count of -1 returns the previous block. Undef
307 will be returned if out of legal address space.
308
309 ->sameblock($block) Compares two blocks. The second block will be
310 auto-converted from a string if it isn't
311 already a Net::Netmask object. Returns 1 if
312 they are identical.
313
314 ->cmpblocks($block) Compares two blocks. The second block will be
315 auto-converted from a string if it isn't
316 already a Net::Netmask object. Returns -1, 0,
317 or 1 depending on which one has the lower base
318 address or which one is larger if they have the
319 same base address.
320
321 ->contains($block) Compares two blocks. The second block will be
322 auto-converted from a string if it isn't
323 already a Net::Netmask object. Returns 1 if the
324 second block fits inside the first block.
325 Returns 0 otherwise.
326
327 ->storeNetblock([$t]) Adds the current block to an table of network
328 blocks. The table can be used to query which
329 network block a given IP address is in.
330
331 The optional argument allows there to be more
332 than one table. By default, an internal table
333 is used. If more than one table is needed, then
334 supply a reference to a HASH to store the data
335 in.
336
337 ->deleteNetblock([$t]) Deletes the current block from a table of
338 network blocks.
339
340 The optional argument allows there to be more
341 than one table. By default, an internal table
342 is used. If more than one table is needed, then
343 supply a reference to a HASH to store the data
344 in.
345
346 ->checkNetblock([$t]) Returns true of the netblock is already in the
347 network table.
348
349 ->tag($name [, $value]) Tag network blocks with your own data. The
350 first argument is the name of your tag (hash
351 key) and the second argument (if present) is
352 the new value. The old value is returned.
353
354 ->split($parts) Splits a netmask into a number of sub
355 netblocks. This number must be a base 2 number
356 (2,4,8,16,etc.) and the number must not exceed
357 the number of IPs within this netmask.
358
359 For instance,
360
361 Net::Netmask->safe_new( '10.0.0.0/24' )->split(2)
362
363 is equivilent to
364
365 ( Net::Netmask( '10.0.0.0/25'), Net::Netmask( '10.0.0.128/25' ) )
366
367METHOD/FUNCTION COMBOS
368 findOuterNetblock(ip, [$t])
369 Search the table of network blocks (created
370 with storeNetBlock) to find if any of them
371 contain the given IP address. The IP address
372 can either be a string or a Net::Netmask object
373 (method invocation). If more than one block in
374 the table contains the IP address or block, the
375 largest network block will be the one returned.
376
377 The return value is either a Net::Netmask
378 object or undef.
379
380 cidrs2inverse(block, @listOfBlocks)
381 Given a block and a list of blocks,
382 cidrs2inverse() will return a list of blocks
383 representing the IP addresses that are in the
384 block but not in the list of blocks. It finds
385 the gaps.
386
387 The block will be auto-converted from a string
388 if it isn't already a Net::Netmask object. The
389 list of blocks should be Net::Netmask objects.
390
391 The return value is a list of Net::Netmask
392 objects.
393
394OVERLOADING
395 "" Strinification is overloaded to be the ->desc()
396 method.
397
398 cmp Numerical and string comparisons have been
399 overloaded to the ->cmpblocks() method. This
400 allows blocks to be sorted without specifying a
401 sort function.
402
403FUNCTIONS
404 sort_by_ip_address This function is included in "Net::Netmask"
405 simply because there doesn't seem to be a
406 better place to put it on CPAN. It turns out
407 that there is one method for sorting
408 dotted-quads ("a.b.c.d") that is faster than
409 all the rest. This is that way. Use it as
410 "sort_by_ip_address(@list_of_ips)". That was
411 the theory anyway. Someone sent a faster
412 version ...
413
414 This method also will sort IPv6 addresses, but
415 is not performance optimized. It is correct,
416 however.
417
418 sort_network_blocks This function is a function to sort
419 Net::Netmask objects. It's faster than the
420 simpler "sort @blocks" that also works.
421
422 findNetblock(ip, [$t]) Search the table of network blocks (created
423 with storeNetBlock) to find if any of them
424 contain the given IP address. The IP address is
425 expected to be a string. If more than one block
426 in the table contains the IP address, the
427 smallest network block will be the one
428 returned.
429
430 The return value is either a Net::Netmask
431 object or undef.
432
433 findAllNetblock(ip, [$t])
434 Search the table of network blocks (created
435 with storeNetBlock) to find if any of them
436 contain the given IP address. The IP address is
437 expected to be a string. All network blocks in
438 the table that contain the IP address will be
439 returned.
440
441 The return value is a list of Net::Netmask
442 objects.
443
444 dumpNetworkTable([$t]) Returns a list of the networks in a network
445 table (as created by ->storeNetblock()).
446
447 range2cidrlist($startip, $endip)
448 Given a range of IP addresses, return a list of
449 blocks that span that range.
450
451 For example, range2cidrlist('216.240.32.128',
452 '216.240.36.127'), will return a list of
453 Net::Netmask objects that correspond to:
454
455 216.240.32.128/25
456 216.240.33.0/24
457 216.240.34.0/23
458 216.240.36.0/25
459
460 cidrs2contiglists(@listOfBlocks)
461 "cidrs2contiglists" will rearrange a list of
462 Net::Netmask objects such that contiguous sets
463 are in sublists and each sublist is
464 discontiguous with the next.
465
466 For example, given a list of Net::Netmask
467 objects corresponding to the following blocks:
468
469 216.240.32.128/25
470 216.240.33.0/24
471 216.240.36.0/25
472
473 "cidrs2contiglists" will return a list with two
474 sublists:
475
476 216.240.32.128/25 216.240.33.0/24
477
478 216.240.36.0/25
479
480 Overlapping blocks will be placed in the same
481 sublist.
482
483 cidrs2cidrs(@listOfBlocks)
484 "cidrs2cidrs" will collapse a list of
485 Net::Netmask objects by combining adjacent
486 blocks into larger blocks. It returns a list of
487 blocks that covers exactly the same IP space.
488 Overlapping blocks will be collapsed.
489
490AUTHORS
491 Joelle Maslak <jmaslak@antelope.net> (current maintainer)
492
493 David Muir Sharnoff (original creator/author)
494
495LICENSE
496 Copyright (C) 1998-2006 David Muir Sharnoff.
497
498 Copyright (C) 2011-2013 Google, Inc.
499
500 Copyright (C) 2018-2021 Joelle Maslak
501
502 This module may be used, modified and redistributed under the same terms
503 as Perl itself.
504
505