NAME
Net::Netmask - parse, manipulate and lookup IP network blocks
SYNOPSIS
use Net::Netmask;
$block = Net::Netmask->new(network block)
$block = Net::Netmask->new(network block, netmask)
$block = Net::Netmask->new2(network block)
$block = Net::Netmask->new2(network block, netmask)
print $block; # a.b.c.d/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)
DESCRIPTION
Net::Netmask parses and understands IPv4 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.
CONSTRUCTING
Net::Netmask objects are created with an IP address and optionally a
mask. There are many forms that are recognized:
'216.240.32.0/24' The preferred form.
'216.240.32.0:255.255.255.0'
'216.240.32.0-255.255.255.0'
'216.240.32.0', '255.255.255.0'
'216.240.32.0', '0xffffff00'
'216.240.32.0 - 216.240.32.255'
'216.240.32.4' A /32 block.
'216.240.32' Always a /24 block.
'216.240' Always a /16 block.
'140' Always a /8 block.
'216.240.32/24'
'216.240/16'
'default' or 'any' 0.0.0.0/0 (the default route)
'216.240.32.0#0.0.31.255' A hostmask (as used by Cisco
access-lists - that is, the hostmask is
the bitwise inverse of a netmask).
There are two constructor methods: "new" and "new2". "new2" 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
"new2" the error can be found as Net::Netmask::errstr or
$Net::Netmask::error.
METHODS
->desc() Returns a description of the network block. Eg:
"216.240.32.0/19". This is also available as
overloaded stringification.
->base() Returns base address of the network block as a
string. Eg: "216.240.32.0". Base does not give
an indication of the size of the network block.
->mask() Returns the netmask as a string. Eg:
"255.255.255.0".
->hostmask() Returns the host mask which is the opposite of
the netmask. Eg: "0.0.0.255".
->bits() Returns the netmask as a number of bits in the
network portion of the address for this block.
Eg: 24.
->size() Returns the number of IP addresses in a block.
Eg: 256.
->broadcast() The blocks broadcast address. (The last IP
address inside the block.) Eg: 192.168.1.0/24
=> 192.168.1.255
->next() The first IP address following the block. (The
IP address following the broadcast address.)
Eg: 192.168.1.0/24 => 192.168.2.0
->first() & ->last() Synonyms for ->base() and ->broadcast()
->protocol() Added in version 1.9102.
Returns the address family/protocol represented
by the block. Today, this will always be
"IPv4".
->match($ip) Returns a true if the IP number $ip matches the
given network. That is, a true value is
returned if $ip is between base() and
broadcast(). For example, if we have the
network 192.168.1.0/24, then
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")
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;
->maxblock() Much of the time, it is not possible to
determine the size of a network block just from
it's base address. For example, with the
network block '216.240.32.0/27', if you only
had the '216.240.32.0' portion you wouldn't be
able to tell for certain the size of the block.
'216.240.32.0' could be anything from a '/23'
to a '/32'. The maxblock() method gives the
size of the largest block that the current
block's address would allow it to be. The size
is given in bits. Eg: 23.
->enumerate([$bitstep) Returns a list of all the IP addresses in the
block. Be very careful not to use this function
of large blocks. The IP addresses are returned
as strings. Eg: '216.240.32.0', '216.240.32.1',
... '216.240.32.255'.
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).
->nth($index, [$bitstep])
Returns the nth element of the array that
enumerate would return if it were called. So,
to get the first usable address in a block, use
nth(1). To get the broadcast address, use
nth(-1). To get the last usable address, use
nth(-2).
->inaddr() Returns an inline list of tuples. There is a
tuple for each DNS zone name 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.
->nextblock([$count]) Without a $count, return the next block of the
same size after the current one. With a count,
return the Nth block after the current one. A
count of -1 returns the previous block. Undef
will be returned if out of legal address space.
->sameblock($block) Compares two blocks. The second block will be
auto-converted from a string if it isn't
already a Net::Netmask object. Returns 1 if
they are identical.
->cmpblocks($block) Compares two blocks. The second block will be
auto-converted from a string if it isn't
already a Net::Netmask object. Returns -1, 0,
or 1 depending on which one has the lower base
address or which one is larger if they have the
same base address.
->contains($block) Compares two blocks. The second block will be
auto-converted from a string if it isn't
already a Net::Netmask object. Returns 1 if the
second block fits inside the first block.
Returns 0 otherwise.
->storeNetblock([$t]) Adds the current block to an table of network
blocks. The table can be used to query which
network block a given IP address is 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.
->deleteNetblock([$t]) Deletes the current block from a table of
network blocks.
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.
->checkNetblock([$t]) Returns true of the netblock is already in the
network table.
->tag($name [, $value]) Tag network blocks with your own data. The
first argument is the name of your tag (hash
key) and the second argument (if present) is
the new value. The old value is returned.
->split($parts) Splits a netmask into a number of sub
netblocks. This number must be a base 2 number
(2,4,8,16,etc.) and the number must not exceed
the number of IPs within this netmask.
For instance,
Net::Netmask->new( '10.0.0.0/24' )->split(2)
is equivilent to
( Net::Netmask( '10.0.0.0/25'), Net::Netmask( '10.0.0.128/25' ) )
METHOD/FUNCTION COMBOS
findOuterNetblock(ip, [$t])
Search the table of network blocks (created
with storeNetBlock) to find if any of them
contain the given IP address. The IP address
can either be a string or a Net::Netmask object
(method invocation). If more than one block in
the table contains the IP address or block, the
largest network block will be the one returned.
The return value is either a Net::Netmask
object or undef.
cidrs2inverse(block, @listOfBlocks)
Given a block and a list of blocks,
cidrs2inverse() will return a list of blocks
representing the IP addresses that are in the
block but not in the list of blocks. It finds
the gaps.
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.
OVERLOADING
"" Strinification is overloaded to be the ->desc()
method.
cmp Numerical and string comparisons have been
overloaded to the ->cmpblocks() method. This
allows blocks to be sorted without specifying a
sort function.
FUNCTIONS
sort_by_ip_address This function is included in "Net::Netmask"
simply because there doesn't seem to be a
better place to put it on CPAN. It turns out
that there is one method for sorting
dotted-quads ("a.b.c.d") that is faster than
all the rest. This is that way. Use it as
"sort_by_ip_address(@list_of_ips)". That was
the theory anyway. Someone sent a faster
version ...
sort_network_blocks This function is a function to sort
Net::Netmask objects. It's faster than the
simpler "sort @blocks" that also works.
findNetblock(ip, [$t]) Search the table of network blocks (created
with storeNetBlock) to find if any of them
contain the given IP address. The IP address is
expected to be a string. If more than one block
in the table contains the IP address, the
smallest network block will be the one
returned.
The return value is either a Net::Netmask
object or undef.
findAllNetblock(ip, [$t])
Search the table of network blocks (created
with storeNetBlock) to find if any of them
contain the given IP address. The IP address is
expected to be a string. All network blocks in
the table that contain the IP address will be
returned.
The return value is a list of Net::Netmask
objects.
dumpNetworkTable([$t]) Returns a list of the networks in a network
table (as created by ->storeNetblock()).
range2cidrlist($startip, $endip)
Given a range of IP addresses, return a list of
blocks that span that range.
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
cidrs2contiglists(@listOfBlocks)
"cidrs2contiglists" will rearrange a list of
Net::Netmask objects such that contiguous sets
are in sublists and each sublist is
discontiguous with the next.
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.
cidrs2cidrs(@listOfBlocks)
"cidrs2cidrs" will collapse a list of
Net::Netmask objects by combining adjacent
blocks into larger blocks. It returns a list of
blocks that covers exactly the same IP space.
Overlapping blocks will be collapsed.
AUTHORS
Joelle Maslak <jmaslak@antelope.net> (current maintainer)
David Muir Sharnoff (original creator/author)
LICENSE
Copyright (C) 1998-2006 David Muir Sharnoff.
Copyright (C) 2011-2013 Google, Inc.
Copyright (C) 2018 Joelle Maslak
This module may be used, modified and redistributed under the same terms
as Perl itself.