1Net::Netmask(3) User Contributed Perl Documentation Net::Netmask(3)
2
3
4
6 Net::Netmask - parse, manipulate and lookup IP network blocks
7
9 use Net::Netmask;
10
11 $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
18 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
31 if ($block->sameblock("network block")) ...
32 if ($block->cmpblocks("network block")) ...
33
34 $newblock = $block->nextblock([count]);
35
36 for $ip ($block->enumerate([$bitstep])) { }
37
38 for $zone ($block->inaddr()) { }
39
40 my $table = {};
41 $block->storeNetblock([$table])
42 $block->deleteNetblock([$table])
43 @missingblocks = $block->cidrs2inverse(@blocks)
44
45 $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
52 @blocks = range2cidrlist($beginip, $endip);
53 @blocks = cidrs2cidrs(@blocks_with_dups)
54
55 @listofblocks = cidrs2contiglists(@blocks);
56
57 @blocks = sort @blocks
58 @blocks = sort_network_blocks(@blocks)
59
60 @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
69 These methods provide nearly all types of information about a network
70 block that you might want.
71
72 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
78 There is a function for sorting by text IP address.
79
80 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
84 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
90 '216.240.32.0/24' The preferred IPv4 form.
91
92 '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
99 'default' or 'any' 0.0.0.0/0 (the default route)
100
101 '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
105 '2001:db8:1234:5678::/64' The preferred IPv6 form.
106
107 '2001:db8:1234:5678::9876' A /128 block.
108
109 'default6' or 'any6' ::/0 (the default route)
110
111 There are two constructor methods: "new" and "safe_new" (also known as
112 "new2").
113
114 "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
118 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
122 IMPORTANT: You want to use "safe_new" or "new2" ("new2" is a synonym
123 for "safe_new") in new code!
124
125 As of version 2.000, the following abbreviated IPv4 netblocks are not
126 accepted by default, but can be accepted with options.
127
128 '216.240.32' Always a /24 block.
129
130 '216.240' Always a /16 block.
131
132 '140' Always a /8 block.
133
134 '216.240.32/24'
135 '216.240/16'
136
137 To accept these, you can call the constructor with a "shortnet" option
138 set to a true value. Example:
139
140 my $block = Net::Netmask->safe_new("216.240/16", shortnet => 1);
141
142 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
147 local $Net::Netmask::SHORTNET_DEFAULT = 1
148 my $block = Net::Netmask->safe_new("216.240/16");
149
150 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
154 For instance:
155
156 perl -MNet::Netmask -E "say Net::Netmask->safe_new("10.20", shortnet => 1)"
157
158 Will print "10.2.0.0/16". However:
159
160 perl -MSocket -E "say inet_ntoa(inet_aton('10.20'))"
161
162 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
167 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
175 ->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
180 ->mask() Returns the netmask as a string. Eg:
181 "255.255.255.0" or "ffff:ffff:ffff:ffff::"
182
183 ->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
187 ->bits() Returns the netmask as a number of bits in the
188 network portion of the address for this block.
189 Eg: 24.
190
191 ->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
195 ->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
200 ->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
205 ->first() & ->last() Synonyms for ->base() and ->broadcast()
206
207 ->protocol() Added in version 1.9102.
208
209 Returns the address family/protocol
210 represented by the block. Either 'IPv4' or
211 'IPv6'.
212
213 ->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
219 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
225 $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
229 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
236 $pos = $block->match($ip) or die;
237 $pos += 0;
238
239 ->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
251 ->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
257 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
262 Note that for IPv6, this will return failure
263 if more than 1,000,000,000 addresses would be
264 returned.
265
266 ->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
274 ->inaddr() Returns an inline list of tuples.
275
276 For IPv4:
277
278 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
283 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
288 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
295 For IPv6:
296
297 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
302 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
309 ->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
316 ->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
321 ->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
328 ->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
334 ->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
338 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
344 ->deleteNetblock([$t]) Deletes the current block from a table of
345 network blocks.
346
347 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
353 ->checkNetblock([$t]) Returns true of the netblock is already in the
354 network table.
355
356 ->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
361 ->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
366 For instance,
367
368 Net::Netmask->safe_new( '10.0.0.0/24' )->split(2)
369
370 is equivalent to
371
372 ( 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
385 The return value is either a Net::Netmask
386 object or undef.
387
388 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
395 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
400 The return value is a list of Net::Netmask
401 objects.
402
404 "" Strinification is overloaded to be the
405 ->desc() method.
406
407 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
423 This method also will sort IPv6 addresses, but
424 is not performance optimized. It is correct,
425 however.
426
427 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
431 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
439 The return value is either a Net::Netmask
440 object or undef.
441
442 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
450 The return value is a list of Net::Netmask
451 objects.
452
453 dumpNetworkTable([$t]) Returns a list of the networks in a network
454 table (as created by ->storeNetblock()).
455
456 range2cidrlist($startip, $endip)
457 Given a range of IP addresses, return a list
458 of blocks that span that range.
459
460 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
464 216.240.32.128/25
465 216.240.33.0/24
466 216.240.34.0/23
467 216.240.36.0/25
468
469 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
475 For example, given a list of Net::Netmask
476 objects corresponding to the following blocks:
477
478 216.240.32.128/25
479 216.240.33.0/24
480 216.240.36.0/25
481
482 "cidrs2contiglists" will return a list with
483 two sublists:
484
485 216.240.32.128/25 216.240.33.0/24
486
487 216.240.36.0/25
488
489 Overlapping blocks will be placed in the same
490 sublist.
491
492 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
502 David Muir Sharnoff (original creator/author)
503
505 Copyright (C) 1998-2006 David Muir Sharnoff.
506
507 Copyright (C) 2011-2013 Google, Inc.
508
509 Copyright (C) 2018-2021 Joelle Maslak
510
511 This module may be used, modified and redistributed under the same
512 terms as Perl itself.
513
514
515
516perl v5.36.0 2022-09-01 Net::Netmask(3)