File: Netmask.pod

package info (click to toggle)
libnet-netmask-perl 1.9015-3
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 172 kB
  • ctags: 89
  • sloc: perl: 1,187; makefile: 10
file content (447 lines) | stat: -rw-r--r-- 13,050 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
=head1 NAME

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

=head1 SYNOPSIS

use Net::Netmask;

 $block = new Net::Netmask (network block)
 $block = new Net::Netmask (network block, netmask)
 $block = new2 Net::Netmask (network block)
 $block = new2 Net::Netmask (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]);

 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)

=head1 DESCRIPTION

Net::Netmask parses and understands IPv4 CIDR blocks.  It's built
with an object-oriented interface.  Nearly all functions are 
methods that operate on a Net::Netmask object.

There are methods that provide the nearly all bits of information
about a network block that you might want.

There are also functions to put a network block into a table and
then later lookup network blocks by IP address in 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.

=head1 CONSTRUCTING

Net::Netmask objects are created with an IP address and optionally
a mask.  There are many forms that are recognized:

=over 32

=item '216.240.32.0/24'

The preferred form.

=item '216.240.32.0:255.255.255.0'

=item '216.240.32.0-255.255.255.0'

=item '216.240.32.0', '255.255.255.0'

=item '216.240.32.0', '0xffffff00'

=item '216.240.32.0 - 216.240.32.255'

=item '216.240.32.4'

A /32 block.

=item '216.240.32'

Always a /24 block.

=item '216.240'

Always a /16 block.

=item '140'

Always a /8 block.

=item '216.240.32/24'

=item '216.240/16'

=item 'default' or 'any'

0.0.0.0/0 (the default route)

=item '216.240.32.0#0.0.31.255'

A hostmask (as used by Cisco access-lists).

=back

There are two constructor methods: C<new> and C<new2>.  The difference
is that C<new2> will return undef for invalid netmasks and C<new> will
return a netmask object even if the constructor could not figure out
what the network block should be.

With C<new>, the error string can be found as $block->{'ERROR'}.  With
C<new2> the error can be found as Net::Netmask::errstr or 
$Net::Netmask::error.

=head1 METHODS

=over 25

=item ->B<desc>()

Returns a description of the network block.  Eg: 216.240.32.0/19.
This is also available as overloaded stringification.

=item ->B<base>()

Returns base address of the network block as a string.  Eg: 216.240.32.0.  
B<Base> does not give an indication of the size of the network block.

=item ->B<mask>()

Returns the netmask as a string. Eg: 255.255.255.0. 

=item ->B<hostmask>()

Returns the host mask which is the opposite of the netmask. 
Eg: 0.0.0.255.

=item ->B<bits>()

Returns the netmask as a number of bits in the network
portion of the address for this block.  Eg: 24.

=item ->B<size>()

Returns the number of IP addresses in a block.  Eg: 256.

=item ->B<broadcast>()

The blocks broadcast address. (The last IP address inside the
block.) Eg: 192.168.1.0/24 => 192.168.1.255

=item ->B<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

=item ->B<first>() & ->B<last>()

Synonyms for ->B<base>() and ->B<broadcast>()

=item ->B<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() amd 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;

=item ->B<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 B<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.

=item ->B<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).

=item ->B<nth>($index, [$bitstep])

Returns the nth element of the array that B<enumerate> would return
if it were called.  So, to get the first usable address in a block,
use B<nth>(1).  To get the broadcast address, use B<nth>(-1).  To
get the last usable adress, use B<nth>(-2).

=item ->B<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.

=item ->B<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.

=item ->B<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.

=item ->B<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.

=item ->B<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.

=item ->B<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.

=item ->B<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.

=item ->B<checkNetblock>([$t])

Returns true of the netblock is already in the network table.

=item ->B<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.

=back

=head1 METHOD/FUNCTION COMBOS

=over 25

=item B<findOuterNetblock>(ip, [$t])

Search the table of network blocks (created with B<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.

=item B<cidrs2inverse>(block, @listOfBlocks)

Given a block and a list of blocks, B<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.

=back

=head1 OVERLOADING

Overloading doesn't seem to work completeley on perl before version
5.6.1.  The test suite doesn't test overloading before that.  At
least for sort.

=over 25

=item B<"">

Strinification is overloaded to be the ->B<desc>() method.

=item B<cmp>

Numerical and string comparisions have been overloaded to 
the ->B<cmpblocks>() method.  This allows blocks to be sorted
without specifying a sort function.

=back

=head1 FUNCTIONS

=over 25

=item B<sort_by_ip_address>

This function is included in C<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 C<sort_by_ip_address(@list_of_ips)>.  That was
the theory anyway.  Someone sent a faster version ...

=item B<sort_network_blocks>

This function is a function to sort Net::Netmask objects.  It's
faster than the simpler C<sort @blocks> that also works.

=item B<findNetblock>(ip, [$t])

Search the table of network blocks (created with B<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.

=item B<findAllNetblock>(ip, [$t])

Search the table of network blocks (created with B<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.

=item B<dumpNetworkTable>([$t])

Returns a list of the networks in a network table (as 
created by ->B<storeNetblock>()).

=item B<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 corrospond to:

	216.240.32.128/25
	216.240.33.0/24
	216.240.34.0/23
	216.240.36.0/25

=item B<cidrs2contiglists>(@listOfBlocks)

C<cidrs2contiglists> will rearrange a list of Net::Netmask objects
such that contiguous sets are in sublists and each sublist is
discontigeous 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

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

=item B<cidrs2cidrs>(@listOfBlocks)

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

=back

=head1 LICENSE  

Copyright (C) 1998-2006 David Muir Sharnoff.  License hereby
granted for anyone to use, modify or redistribute this module at 
their own risk.  Please feed useful changes back to <muir@idiom.com>.

If you found this module useful, please thank me (the author) by
giving me a chance to bid to provide your next high-speed Internet
link.  I run multiple ISPs and can generally save you money and
provide a top-notch service for your T1s, T3s, OC3s, etc.  Please
send your request to <muir@idiom.com>.  Thank you.