1Net::Netmask(3)       User Contributed Perl Documentation      Net::Netmask(3)
2
3
4

NAME

6        Net::Netmask - parse, manipulate and lookup IP network blocks
7

SYNOPSIS

9        use Net::Netmask;
10
11        $block = Net::Netmask->new(network block)
12        $block = Net::Netmask->new(network block, netmask)
13        $block = Net::Netmask->new2(network block)
14        $block = Net::Netmask->new2(network block, netmask)
15
16        print $block;                      # a.b.c.d/bits or 1:2:3::4/bits
17        print $block->base()
18        print $block->mask()
19        print $block->hostmask()
20        print $block->bits()
21        print $block->size()
22        print $block->maxblock()
23        print $block->broadcast()
24        print $block->next()
25        print $block->match($ip);
26        print $block->nth(1, [$bitstep]);
27        print $block->protocol();
28
29        if ($block->sameblock("network block")) ...
30        if ($block->cmpblocks("network block")) ...
31
32        $newblock = $block->nextblock([count]);
33
34        for $ip ($block->enumerate([$bitstep])) { }
35
36        for $zone ($block->inaddr()) { }
37
38        my $table = {};
39        $block->storeNetblock([$table])
40        $block->deleteNetblock([$table])
41        @missingblocks = $block->cidrs2inverse(@blocks)
42
43        $block = findNetblock(ip, [$table])
44        $block = findOuterNetblock(ip, [$table])
45        @blocks = findAllNetblock(ip, [$table])
46        if ($block->checkNetblock([$table]) ...
47        $block2 = $block1->findOuterNetblock([$table])
48        @blocks = dumpNetworkTable([$table])
49
50        @blocks = range2cidrlist($beginip, $endip);
51        @blocks = cidrs2cidrs(@blocks_with_dups)
52
53        @listofblocks = cidrs2contiglists(@blocks);
54
55        @blocks = sort @blocks
56        @blocks = sort_network_blocks(@blocks)
57
58        @sorted_ip_addrs = sort_by_ip_address(@unsorted_ip_addrs)
59

DESCRIPTION

61       Net::Netmask parses and understands IPv4 and IPv6 CIDR blocks (see
62       <https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing> for more
63       information on CIDR blocks).  It's built with an object-oriented
64       interface, with functions being methods that operate on a Net::Netmask
65       object.
66
67       These methods provide nearly all types of information about a network
68       block that you might want.
69
70       There are also functions to insert a network block into a table and
71       then later lookup network blocks by IP address using that table.  There
72       are functions to turn a IP address range into a list of CIDR blocks.
73       There are functions to turn a list of CIDR blocks into a list of IP
74       addresses.
75
76       There is a function for sorting by text IP address.
77
78       All functions understand both IPv4 and IPv6.  Matches, finds, etc, will
79       always return false when an IPv4 address is matched against an IPv6
80       address.
81
82       IPv6 support was added in 1.9104.
83

CONSTRUCTING

85       Net::Netmask objects are created with an IP address and optionally a
86       mask.  There are many forms that are recognized:
87
88       '216.240.32.0/24'               The preferred IPv6 form.
89
90       '216.240.32.0:255.255.255.0'
91       '216.240.32.0-255.255.255.0'
92       '216.240.32.0', '255.255.255.0'
93       '216.240.32.0', '0xffffff00'
94       '216.240.32.0 - 216.240.32.255'
95       '216.240.32.4'                  A /32 block.
96
97       '216.240.32'                    Always a /24 block.
98
99       '216.240'                       Always a /16 block.
100
101       '140'                           Always a /8 block.
102
103       '216.240.32/24'
104       '216.240/16'
105       'default' or 'any'              0.0.0.0/0 (the default route)
106
107       '216.240.32.0#0.0.31.255'       A hostmask (as used by Cisco access-
108                                       lists - that is, the hostmask is the
109                                       bitwise inverse of a netmask).
110
111       '2001:db8:1234:5678::/64'       The preferred IPv6 form.
112
113       '2001:db8:1234:5678::9876'      A /128 block.
114
115       'default6' or 'any6'            ::/0 (the default route)
116
117       There are two constructor methods: "new" and "new2".  "new2" differs
118       from "new" in that it will return undef for invalid netmasks, while
119       "new" will return a netmask object even if the constructor could not
120       figure out what the network block should be.
121
122       With "new", the error string can be found as $block->{'ERROR'}.  With
123       "new2" the error can be found as Net::Netmask::errstr or
124       $Net::Netmask::error.
125

METHODS

127       ->desc()                 Returns a description of the network block.
128                                Eg: "216.240.32.0/19" or "2001:db8:1234::/48".
129                                This is also available as overloaded
130                                stringification.
131
132       ->base()                 Returns base address of the network block as a
133                                string.  Eg: "216.240.32.0".  or
134                                "2001:db8:1234::/48".  Base does not give an
135                                indication of the size of the network block.
136
137       ->mask()                 Returns the netmask as a string. Eg:
138                                "255.255.255.0" or "ffff:ffff:ffff:ffff::"
139
140       ->hostmask()             Returns the host mask which is the opposite of
141                                the netmask.  Eg: "0.0.0.255" or
142                                "::ffff:ffff:ffff:ffff".
143
144       ->bits()                 Returns the netmask as a number of bits in the
145                                network portion of the address for this block.
146                                Eg: 24.
147
148       ->size()                 Returns the number of IP addresses in a block.
149                                Eg: 256.  For IPv6 addresses, this will be a
150                                Math::BigInt object.
151
152       ->broadcast()            The blocks broadcast address. (The last IP
153                                address inside the block.) Eg: 192.168.1.0/24
154                                => 192.168.1.255 or 2001:db8::/64 =>
155                                2001:db8::ffff:ffff:ffff:ffff
156
157       ->next()                 The first IP address following the block. (The
158                                IP address following the broadcast address.)
159                                Eg: 192.168.1.0/24 => 192.168.2.0 or
160                                2001:db8:0:1::/64 => 2001:db8:0:2::/64
161
162       ->first() & ->last()     Synonyms for ->base() and ->broadcast()
163
164       ->protocol()             Added in version 1.9102.
165
166                                Returns the address family/protocol
167                                represented by the block.  Either 'IPv4' or
168                                'IPv6'.
169
170       ->match($ip)             Returns a true if the IP number $ip matches
171                                the given network. That is, a true value is
172                                returned if $ip is between base() and
173                                broadcast().  For example, if we have the
174                                network 192.168.1.0/24, then
175
176                                  192.168.0.255 => 0
177                                  192.168.1.0   => "0 "
178                                  192.168.1.1   => 1
179                                  ...
180                                  192.168.1.255 => 255
181
182                                $ip should be a dotted-quad (eg:
183                                "192.168.66.3") or an IPv6 address in standard
184                                notation (eg: "2001:db8::1").
185
186                                It just happens that the return value is the
187                                position within the block.  Since zero is a
188                                legal position, the true string "0 " is
189                                returned in it's place.  "0 " is numerically
190                                zero though.  When wanting to know the
191                                position inside the block, a good idiom is:
192
193                                  $pos = $block->match($ip) or die;
194                                  $pos += 0;
195
196       ->maxblock()             Much of the time, it is not possible to
197                                determine the size of a network block just
198                                from it's base address.  For example, with the
199                                network block '216.240.32.0/27', if you only
200                                had the '216.240.32.0' portion you wouldn't be
201                                able to tell for certain the size of the
202                                block.  '216.240.32.0' could be anything from
203                                a '/23' to a '/32'.  The maxblock() method
204                                gives the size of the largest block that the
205                                current block's address would allow it to be.
206                                The size is given in bits.  Eg: 23.
207
208       ->enumerate([$bitstep)   Returns a list of all the IP addresses in the
209                                block.  Be very careful not to use this
210                                function of large blocks.  The IP addresses
211                                are returned as strings.  Eg: '216.240.32.0',
212                                '216.240.32.1', ... '216.240.32.255'.
213
214                                If the optional argument is given, step
215                                through the block in increments of a given
216                                network size.  To step by 4, use a bitstep of
217                                30 (as in a /30 network).
218
219                                Note that for IPv6, this will return failure
220                                if more than 1,000,000,000 addresses would be
221                                returned.
222
223       ->nth($index, [$bitstep])
224                                Returns the nth element of the array that
225                                enumerate would return if it were called.  So,
226                                to get the first usable address in a block,
227                                use nth(1).  To get the broadcast address, use
228                                nth(-1).  To get the last usable address, use
229                                nth(-2).
230
231       ->inaddr()               Returns an inline list of tuples.
232
233                                For IPv4:
234
235                                There is a tuple for each DNS zone name (at
236                                the /24 level) in the block.  If the block is
237                                smaller than a /24, then the zone of the
238                                enclosing /24 is returned.
239
240                                Each tuple contains: the DNS zone name, the
241                                last component of the first IP address in the
242                                block in that zone, the last component of the
243                                last IP address in the block in that zone.
244
245                                Examples: the list returned for the block
246                                '216.240.32.0/23' would be:
247                                '32.240.216.in-addr.arpa', 0, 255,
248                                '33.240.216.in-addr.arpa', 0, 255.  The list
249                                returned for the block '216.240.32.64/27'
250                                would be: '32.240.216.in-addr.arpa', 64, 95.
251
252                                For IPv6:
253
254                                A list is returned with each DNS zone name at
255                                the shortest-prefix length possible.  This is
256                                not returned as a tuple, but just a list of
257                                strings.
258
259                                Examples: the list returned for the block
260                                '2002::/16' would be a one element list,
261                                containing just 2.0.0.2.ip6.arpa'.  The list
262                                for '2002::/17' would return a two element
263                                list containing '0.2.0.0.2.ip6.arpa' and
264                                '1.2.0.0.2.ip6.arpa'.
265
266       ->nextblock([$count])    Without a $count, return the next block of the
267                                same size after the current one.  With a
268                                count, return the Nth block after the current
269                                one.  A count of -1 returns the previous
270                                block.  Undef will be returned if out of legal
271                                address space.
272
273       ->sameblock($block)      Compares two blocks.  The second block will be
274                                auto-converted from a string if it isn't
275                                already a Net::Netmask object.  Returns 1 if
276                                they are identical.
277
278       ->cmpblocks($block)      Compares two blocks.  The second block will be
279                                auto-converted from a string if it isn't
280                                already a Net::Netmask object.  Returns -1, 0,
281                                or 1 depending on which one has the lower base
282                                address or which one is larger if they have
283                                the same base address.
284
285       ->contains($block)       Compares two blocks.  The second block will be
286                                auto-converted from a string if it isn't
287                                already a Net::Netmask object.  Returns 1 if
288                                the second block fits inside the first block.
289                                Returns 0 otherwise.
290
291       ->storeNetblock([$t])    Adds the current block to an table of network
292                                blocks.  The table can be used to query which
293                                network block a given IP address is in.
294
295                                The optional argument allows there to be more
296                                than one table.  By default, an internal table
297                                is used.   If more than one table is needed,
298                                then supply a reference to a HASH to store the
299                                data in.
300
301       ->deleteNetblock([$t])   Deletes the current block from a table of
302                                network blocks.
303
304                                The optional argument allows there to be more
305                                than one table.  By default, an internal table
306                                is used.   If more than one table is needed,
307                                then supply a reference to a HASH to store the
308                                data in.
309
310       ->checkNetblock([$t])    Returns true of the netblock is already in the
311                                network table.
312
313       ->tag($name [, $value])  Tag network blocks with your own data.  The
314                                first argument is the name of your tag (hash
315                                key) and the second argument (if present) is
316                                the new value.  The old value is returned.
317
318       ->split($parts)          Splits a netmask into a number of sub
319                                netblocks. This number must be a base 2 number
320                                (2,4,8,16,etc.) and the number must not exceed
321                                the number of IPs within this netmask.
322
323                                For instance,
324
325                                  Net::Netmask->new( '10.0.0.0/24' )->split(2)
326
327                                is equivilent to
328
329                                  ( Net::Netmask( '10.0.0.0/25'), Net::Netmask( '10.0.0.128/25' ) )
330

METHOD/FUNCTION COMBOS

332       findOuterNetblock(ip, [$t])
333                                Search the table of network blocks (created
334                                with storeNetBlock) to find if any of them
335                                contain the given IP address.  The IP address
336                                can either be a string or a Net::Netmask
337                                object (method invocation).  If more than one
338                                block in the table contains the IP address or
339                                block, the largest network block will be the
340                                one returned.
341
342                                The return value is either a Net::Netmask
343                                object or undef.
344
345       cidrs2inverse(block, @listOfBlocks)
346                                Given a block and a list of blocks,
347                                cidrs2inverse() will return a list of blocks
348                                representing the IP addresses that are in the
349                                block but not in the list of blocks.  It finds
350                                the gaps.
351
352                                The block will be auto-converted from a string
353                                if it isn't already a Net::Netmask object.
354                                The list of blocks should be Net::Netmask
355                                objects.
356
357                                The return value is a list of Net::Netmask
358                                objects.
359

OVERLOADING

361       ""                       Strinification is overloaded to be the
362                                ->desc() method.
363
364       cmp                      Numerical and string comparisons have been
365                                overloaded to the ->cmpblocks() method.  This
366                                allows blocks to be sorted without specifying
367                                a sort function.
368

FUNCTIONS

370       sort_by_ip_address       This function is included in "Net::Netmask"
371                                simply because there doesn't seem to be a
372                                better place to put it on CPAN.  It turns out
373                                that there is one method for sorting dotted-
374                                quads ("a.b.c.d") that is faster than all the
375                                rest.  This is that way.  Use it as
376                                "sort_by_ip_address(@list_of_ips)".  That was
377                                the theory anyway.  Someone sent a faster
378                                version ...
379
380                                This method also will sort IPv6 addresses, but
381                                is not performance optimized.  It is correct,
382                                however.
383
384       sort_network_blocks      This function is a function to sort
385                                Net::Netmask objects.  It's faster than the
386                                simpler "sort @blocks" that also works.
387
388       findNetblock(ip, [$t])   Search the table of network blocks (created
389                                with storeNetBlock) to find if any of them
390                                contain the given IP address.  The IP address
391                                is expected to be a string.  If more than one
392                                block in the table contains the IP address,
393                                the smallest network block will be the one
394                                returned.
395
396                                The return value is either a Net::Netmask
397                                object or undef.
398
399       findAllNetblock(ip, [$t])
400                                Search the table of network blocks (created
401                                with storeNetBlock) to find if any of them
402                                contain the given IP address.  The IP address
403                                is expected to be a string.   All network
404                                blocks in the table that contain the IP
405                                address will be returned.
406
407                                The return value is a list of Net::Netmask
408                                objects.
409
410       dumpNetworkTable([$t])   Returns a list of the networks in a network
411                                table (as created by ->storeNetblock()).
412
413       range2cidrlist($startip, $endip)
414                                Given a range of IP addresses, return a list
415                                of blocks that span that range.
416
417                                For example, range2cidrlist('216.240.32.128',
418                                '216.240.36.127'), will return a list of
419                                Net::Netmask objects that correspond to:
420
421                                    216.240.32.128/25
422                                    216.240.33.0/24
423                                    216.240.34.0/23
424                                    216.240.36.0/25
425
426       cidrs2contiglists(@listOfBlocks)
427                                "cidrs2contiglists" will rearrange a list of
428                                Net::Netmask objects such that contiguous sets
429                                are in sublists and each sublist is
430                                discontiguous with the next.
431
432                                For example, given a list of Net::Netmask
433                                objects corresponding to the following blocks:
434
435                                    216.240.32.128/25
436                                    216.240.33.0/24
437                                    216.240.36.0/25
438
439                                "cidrs2contiglists" will return a list with
440                                two sublists:
441
442                                    216.240.32.128/25 216.240.33.0/24
443
444                                    216.240.36.0/25
445
446                                Overlapping blocks will be placed in the same
447                                sublist.
448
449       cidrs2cidrs(@listOfBlocks)
450                                "cidrs2cidrs" will collapse a list of
451                                Net::Netmask objects by combining adjacent
452                                blocks into larger blocks.   It returns a list
453                                of blocks that covers exactly the same IP
454                                space.  Overlapping blocks will be collapsed.
455

AUTHORS

457       Joelle Maslak <jmaslak@antelope.net> (current maintainer)
458
459       David Muir Sharnoff (original creator/author)
460

LICENSE

462       Copyright (C) 1998-2006 David Muir Sharnoff.
463
464       Copyright (C) 2011-2013 Google, Inc.
465
466       Copyright (C) 2018 Joelle Maslak
467
468       This module may be used, modified and redistributed under the same
469       terms as Perl itself.
470
471
472
473perl v5.30.1                      2020-01-30                   Net::Netmask(3)
Impressum