| Net::Netmask(3pm) | User Contributed Perl Documentation | Net::Netmask(3pm) |
Net::Netmask - parse, manipulate and lookup IP network blocks
use Net::Netmask;
$block = Net::Netmask->safe_new(network block)
$block = Net::Netmask->safe_new(network block, netmask)
$block = Net::Netmask->new2(network block)
$block = Net::Netmask->new2(network block, netmask)
$block = Net::Netmask->new(network block) # Don't use in new code!
$block = Net::Netmask->new(network block, netmask) # Don't use in new code!
print $block; # a.b.c.d/bits or 1:2:3::4/bits
print $block->base()
print $block->mask()
print $block->hostmask()
print $block->bits()
print $block->size()
print $block->maxblock()
print $block->broadcast()
print $block->next()
print $block->match($ip);
print $block->nth(1, [$bitstep]);
print $block->protocol();
if ($block->sameblock("network block")) ...
if ($block->cmpblocks("network block")) ...
$newblock = $block->nextblock([count]);
for $ip ($block->enumerate([$bitstep])) { }
for $zone ($block->inaddr()) { }
my $table = {};
$block->storeNetblock([$table])
$block->deleteNetblock([$table])
@missingblocks = $block->cidrs2inverse(@blocks)
$block = findNetblock(ip, [$table])
$block = findOuterNetblock(ip, [$table])
@blocks = findAllNetblock(ip, [$table])
if ($block->checkNetblock([$table]) ...
$block2 = $block1->findOuterNetblock([$table])
@blocks = dumpNetworkTable([$table])
@blocks = range2cidrlist($beginip, $endip);
@blocks = cidrs2cidrs(@blocks_with_dups)
@listofblocks = cidrs2contiglists(@blocks);
@blocks = sort @blocks
@blocks = sort_network_blocks(@blocks)
@sorted_ip_addrs = sort_by_ip_address(@unsorted_ip_addrs)
Net::Netmask parses and understands IPv4 and IPv6 CIDR blocks (see <https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing> for more information on CIDR blocks). It's built with an object-oriented interface, with functions being methods that operate on a Net::Netmask object.
These methods provide nearly all types of information about a network block that you might want.
There are also functions to insert a network block into a table and then later lookup network blocks by IP address using that table. There are functions to turn a IP address range into a list of CIDR blocks. There are functions to turn a list of CIDR blocks into a list of IP addresses.
There is a function for sorting by text IP address.
All functions understand both IPv4 and IPv6. Matches, finds, etc, will always return false when an IPv4 address is matched against an IPv6 address.
IPv6 support was added in 1.9104.
Net::Netmask objects are created with an IP address and optionally a mask. There are many forms that are recognized:
There are two constructor methods: "new" and "safe_new" (also known as "new2").
"safe_new" differs from "new" in that it will return undef for invalid netmasks, while "new" will return a netmask object even if the constructor could not figure out what the network block should be.
With "new", the error string can be found as $block->{'ERROR'}. With "safe_new" the error can be found as Net::Netmask::errstr or $Net::Netmask::error.
IMPORTANT: You want to use "safe_new" or "new2" ("new2" is a synonym for "safe_new") in new code!
As of version 2.000, the following abbreviated IPv4 netblocks are not accepted by default, but can be accepted with options.
To accept these, you can call the constructor with a "shortnet" option set to a true value. Example:
my $block = Net::Netmask->safe_new("216.240/16", shortnet => 1);
For compatibility with older codebases, it's also possible to change the default to use the old behavior. To do this, you can set the $Net::Netmask::SHORTNET_DEFAULT variable to a true value. It is recommended that this be done by localizing the variable. Example:
local $Net::Netmask::SHORTNET_DEFAULT = 1
my $block = Net::Netmask->safe_new("216.240/16");
Please be aware that there are security implications to this as other Perl modules, system libraries, or utilities may not parse these addresses the same way. This is why the default was changed.
For instance:
perl -MNet::Netmask -E "say Net::Netmask->safe_new("10.20", shortnet => 1)"
Will print "10.2.0.0/16". However:
perl -MSocket -E "say inet_ntoa(inet_aton('10.20'))"
Will often print "10.0.0.20" which is obviously very different, and if the Net::Netmask module was used to check an IP aggainst an ACL, and then another program was executed (that uses inet_aton(), for instance), the ACL processing might not match the connection.
Thus, it is advised to use this with caution.
Returns the address family/protocol represented by the block. Either 'IPv4' or 'IPv6'.
192.168.0.255 => 0
192.168.1.0 => "0 "
192.168.1.1 => 1
...
192.168.1.255 => 255
$ip should be a dotted-quad (eg: "192.168.66.3") or an IPv6 address in standard notation (eg: "2001:db8::1").
It just happens that the return value is the position within the block. Since zero is a legal position, the true string "0 " is returned in it's place. "0 " is numerically zero though. When wanting to know the position inside the block, a good idiom is:
$pos = $block->match($ip) or die;
$pos += 0;
If the optional argument is given, step through the block in increments of a given network size. To step by 4, use a bitstep of 30 (as in a /30 network).
Note that for IPv6, this will return failure if more than 1,000,000,000 addresses would be returned.
For IPv4:
There is a tuple for each DNS zone name (at the /24 level) in the block. If the block is smaller than a /24, then the zone of the enclosing /24 is returned.
Each tuple contains: the DNS zone name, the last component of the first IP address in the block in that zone, the last component of the last IP address in the block in that zone.
Examples: the list returned for the block '216.240.32.0/23' would be: '32.240.216.in-addr.arpa', 0, 255, '33.240.216.in-addr.arpa', 0, 255. The list returned for the block '216.240.32.64/27' would be: '32.240.216.in-addr.arpa', 64, 95.
For IPv6:
A list is returned with each DNS zone name at the shortest-prefix length possible. This is not returned as a tuple, but just a list of strings.
Examples: the list returned for the block '2002::/16' would be a one element list, containing just 2.0.0.2.ip6.arpa'. The list for '2002::/17' would return a two element list containing '0.2.0.0.2.ip6.arpa' and '1.2.0.0.2.ip6.arpa'.
The optional argument allows there to be more than one table. By default, an internal table is used. If more than one table is needed, then supply a reference to a HASH to store the data in.
The optional argument allows there to be more than one table. By default, an internal table is used. If more than one table is needed, then supply a reference to a HASH to store the data in.
For instance,
Net::Netmask->safe_new( '10.0.0.0/24' )->split(2)
is equivalent to
( Net::Netmask( '10.0.0.0/25'), Net::Netmask( '10.0.0.128/25' ) )
The return value is either a Net::Netmask object or undef.
The block will be auto-converted from a string if it isn't already a Net::Netmask object. The list of blocks should be Net::Netmask objects.
The return value is a list of Net::Netmask objects.
This method also will sort IPv6 addresses, but is not performance optimized. It is correct, however.
The return value is either a Net::Netmask object or undef.
The return value is a list of Net::Netmask objects.
For example, range2cidrlist('216.240.32.128', '216.240.36.127'), will return a list of Net::Netmask objects that correspond to:
216.240.32.128/25
216.240.33.0/24
216.240.34.0/23
216.240.36.0/25
For example, given a list of Net::Netmask objects corresponding to the following blocks:
216.240.32.128/25
216.240.33.0/24
216.240.36.0/25
"cidrs2contiglists" will return a list with two sublists:
216.240.32.128/25 216.240.33.0/24
216.240.36.0/25
Overlapping blocks will be placed in the same sublist.
Joelle Maslak <jmaslak@antelope.net> (current maintainer)
David Muir Sharnoff (original creator/author)
Copyright (C) 1998-2006 David Muir Sharnoff.
Copyright (C) 2011-2013 Google, Inc.
Copyright (C) 2018-2021 Joelle Maslak
This module may be used, modified and redistributed under the same terms as Perl itself.
| 2022-10-13 | perl v5.36.0 |