Index of /~plonka/NetTree

[ICO]NameLast modifiedSizeDescription
[PARENTDIR]Parent Directory  -  
[DIR]old/2014-05-25 12:02 -  
[ ]ReadMe1998-11-23 10:03 547  
[ ]NetTree-1.022.tar.gz2003-06-11 14:47 12K 
NetTree - a package to encapusate the subnet allocations within a network

NAME

NetTree - a package to encapusate the subnet allocations within a network

SYNOPSIS 

   use NetTree;


   $tree = new NetTree '10.0.0.0/8';
   %collisions = $tree->add('10.0.0.0/24', 'my subnet');
   %collisions = $tree->add('10.0.1.0/24', 'my subnet too');
   $tree->prune;
   @available = $tree->available;
   grep { print "$_\n" } @available;
   %unavailable = $tree->unavailable;
   while (($subnet, $cargo) = each %unavailable) {
       print "$subnet $cargo\n"
   }


   printf "%s\n", octets2bits('10.0.0.0/8');
   printf "%s\n", scalar(bits2octets(octets2bits('10.0.0.0/8')));

DESCRIPTION

NetTree is a package used to define, and perform operations upon, networks. A NetTree object encapsulates a binary search tree of nodes that define the subnets within that network.

NetTree.pm was originally conceived of, and written to validate subnet specifications which, in the past, were stored using simpler methods such as a flat file with one subnet (and its description) per line. With such a simple data structure (essentially an array of subnet specifications) it was difficult to enforce that subnet specifications do not define overlapping networks (due to typos or administrative accidents). It was similarly difficult to find which subnet contains a given (smaller) subnet or host. The binary search tree representation solved these problems and is a fairly frugal representation of even a sparsely populated network.

The following methods and subroutines are defined:

new
The new method constructs and returns a NetTree object. It has one optional argument specifying the network number and mask width. If not supplied, it essentially defaults to ``0.0.0.0/0'' - that is, the network containing all 32-bit IP addresses. Note that, if possible, it is advantageous for performance reasons to specify the network and mask width. However, this can only be done if one knows the network in which all subsequently added subnets will reside, for instance the class A, B or C network that your organization uses.

octets2bits
The NetTree::octets2bits subroutine takes a network specification as either one scalar argument in ``n.n.n.n/n'' format, or an array of the individual digits and mask width. If the network mask width is not specified, it is assumed to be 32 - that is an individual host address. This subroutine returns a network specification as a bit string. This bit string is of the mask width characters in length.

bits2octets
The NetTree::octets2bits subroutine takes a network specification in bit string format (such as that returned by NetTree::octets2bits) as an argument. In a scalar context, this subroutine returns a network specification in ``n.n.n.n/n'' format. In an array context an array of the individual digits and the network mask width is returned.

subnet
The subnet method takes a network or host specification in ``n.n.n.n/n'' format. If the network mask width is unspecified it is assumed to be 32 - that is, an individual host address specification. subnet returns a hash of subnets in which the specified network or host resides. (Usually only one element would be returned in the hash.)

The hash's key is in ``n.n.n.n/n'' format and the corresponding value is whatever node value was specified when that subnet was added to the tree.

add
The add method takes 2 arguments. The first is a network or host specification in ``n.n.n.n/n'' format. If the network mask width is unspecified it is assumed to be 32 - that is, an individual host address specification. The second argument is a node value which you would like to store in the tree (for later retrieval). For instance a subnet description might be a useful value.

On success, add returns an empty list. On failure, i.e. if this network specification collides with existing subnets, a hash is returned. The hash's key is in ``n.n.n.n/n'' format and the corresponding value is whatever node value was specified when the subnets were added to the tree.

prune
The prune method prunes the NetTree object by coallescing adjacent subnets that have the same node values. That is, it determines that two subnets, for instance ``10.0.0.0/25'' and ``10.0.0.128/25'', can be combined, into ``10.0.0.0/24'', if the node values which were specified when those subnets were added are equivalent. The node values are compared with the ``eq'' operator. (This should probably be improved so that if the node values are not references a comparision (``eq'') is performed, otherwise a numeric comparision (``<=>'') is performed. Also, it would be nice to improve it so that the caller can specify a comparision function such as with perl's sort function.)

available
The available method returns an array of network specifications in ``n.n.n.n/n'' format. These ``available'' subnets are those that have not been added to the given NetTree object.

unavailable
The unavailable method returns a hash of ``unavailable'' subnets - i.e. those subnets that have been added to the given NetTree object. The hash's key is in ``n.n.n.n/n'' format and the corresponding value is whatever node value was specified when that subnet was added to the tree.

clearcache
The clearcache method forces the cache used by the subnets method to speed things up. You might want to do this periodically if your processes are getting too large. (Otherwise the cache grows without bound.)

BUGS

Currently only IP networks with 32-bit addresses can be reliably represented by a NetTree object.

AUTHOR

Dave Plonka

Copyright (C) 1998 Dave Plonka. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

VERSION

The version number is the module file RCS revision number ($Revision: 1.20 $) with the minor number printed right justified with leading zeroes to 3 decimal places. For instance, RCS revision 1.1 would yield a package version number of 1.001.

This is so that revision 1.10 (which is version 1.010), for example, will test greater than revision 1.2 (which is version 1.002) when you want to require a minimum version of this module.