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