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->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

DESCRIPTION

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

CONSTRUCTING

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

METHODS

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

METHOD/FUNCTION COMBOS

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

OVERLOADING

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

FUNCTIONS

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

AUTHORS

500       Joelle Maslak <jmaslak@antelope.net> (current maintainer)
501
502       David Muir Sharnoff (original creator/author)
503

LICENSE

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.38.0                      2023-07-21                   Net::Netmask(3)
Impressum