NAME

NetworkInfo::Discovery::Register - Register of network information

SYNOPSIS

    use NetworkInfo::Discovery::Register;

    # is like doing a $r->autosave(1) and $r->file("/tmp/the.register")
    my $r = new NetworkInfo::Discovery::Register(autosave=>1, file=>"/tmp/the.register");

    $r->read_register();    # restore state from last save

    # ACLs allow us to remember only what we are allowed to
    $r->clear_acl;
    $r->add_acl("allow", "192.168.1.3/24"); # 192.168.1.3/24 gets converted to 192.168.1.0/24 
    $r->add_acl("deny", "0.0.0.0/0");

    my $interface = { ip    =>  '192.168.1.1',
                      mac   =>  'aa:bb:cc:dd:ee:ff',
                      mask  =>  '255.255.255.0',    # or 24 (as in prefix notation)
                      dns   =>  'www.somehost.org',
                    };

    $r->add_interface($interface);

    my $subnet  = { ip      =>  '192.168.1.0', # this is the network address
                    mask    =>  24, # could also be '255.255.255.0'
                  };

    $r->add_subnet($subnet);

    my $gateway =   { ip    =>  '192.168.1.254',
                      mask  =>  24,
                      mac   =>  'ff:ee:dd:cc:bb:aa',
                      dns   =>  'router.somehost.org',
                    };

    $r->add_gateway($gateway);

    $r->write_register();    # save state for future restore

DESCRIPTION

NetworkInfo::Discovery::Register is a place to combine all that we have discovered about the network. As more information gets put in, the more corrolation we should see here.

For example, finding the netmask of an interface is not easy to do. If we happen to find a subnet from some source (say RIP, or an ICMP "Address Mask Request"), we may later see that those hosts with no netmask probably fit into the subnet. Once we are sure of this, we can add the netmask to the interfaces, and the interfaces into the subnet. By combining our knowledge in this manner, hopefully we discover more than we would by finding random bits of information.

The register stores information about interfaces, gateways, and subnets. Each is a list of hashes in it's core, and thus has an extensible set of attributes that we can tag onto each object. With that said, the pieces of information that I am using for corrolation is as follows (a * denotes that an attribute is mandatory):

    interface
        ip      # * this is the ip address of the interface
        mac     # * this is the ethernet MAC address of the interface
        mask    # the network mask in prefix or dotted-quad format 

    subnet
        ip      # * an ip address on the subnet
        mask    # * the network mask in prefix or dotted-quad 

    gateway
        ip      # * ip address of the interface that is this gateway

In this module we also provide for persistance using Storable. No one likes forgetting information, right?

METHODS

new

add_interface ($interface_hashref)

add_interface_to_subnet ($interface_index, $subnet_index)

delete_interface ($interface_hashref)

This cuts an interface out of the interface list. To keep holes from forming in the list, take the last interface off the list and put it in place of the one we want to delete.

Also, keep track of pointers to subnets and gateways, from subnets and gateways, and interface lookup tables.

The special case is when we are the last interface in the list, and should just cut us out.

add_interface_to_gateway ($interface_index, $gateway_index)

remove_interface_from_gateway ($interface_index, $gateway_index)

remove_interface_from_subnet ($interface_index, $subnet_index)

has_interface($interface_hashref)

update_interface($interface_hashref)

add_subnet($subnet_hashref)

has_subnet($subnet_hashref)

add_gateway($gateway_hashref)

has_gateway($gateway_hashref)

verify_args($hashref)

internal only

verify_structure

internal only.

print_register

prints the formated register to STDOUT

read_register ([$filename])

tries to read the register from a file. if $filename is not give., tries to use what was set at creation of this object.

write_register ([$filename])

stores the register in $filename. if $filename is not given, tries to use what was set at creation of this object.

file ([ $filename ])

get/set the file to store data in

autosave

get/set auto save. pass this a "1" to turn on, a "0" to turn off. Autosave means that we will try to save the register to our "file" before we exit.

test_acl ($ip_to_test)

$ip_to_test is the ip addresse you want to check against the acl list set using add_acl. it should be in the form "a.b.c.d". we return as soon as we find a matching rule that says allow or deny. we return 1 to accept it, 0 to deny it.

acl_match ($ip_to_test, @against_these)

ip is like 172.16.20.4 the acls are either in CIDR notation "172.16.4.12/25" or a single address returns true if the ip matches the acl. returns false otherwise

add_acl ("(allow|deny)", @acls)

this function sets a list of hosts/networks that we are allowed to discover. note that order matters. the first argument is set to allow or deny. the meaning should be clear. @acls is a list of ip addresses in the form: a.b.c.d/mask # to acl a whole network or a.b.c.d # to acl a host

the following calls will allow us to discover stuff on only the network 172.16.1.0/24: $d->add_acl("allow", "172.16.1.0/24"); $d->add_acl("deny", "0.0.0.0/0");

the following calls will allow us to discover anything but stuff on network 172.16.1.0/24: $d->add_acl("deny", "172.16.1.0/24"); $d->add_acl("allow", "0.0.0.0/0");

clear_acl

this function clears the acl list

guess_mask ($ip)

attempt to guess the mask based on the ip. returns the guessed mask

add_event ("string")

add an event to the log

DESTROY

just tries to write_register if we have autosave turned on