NAME

NetworkInfo::Discovery - Modules for network discovery and mapping

SYNOPSIS

  use NetworkInfo::Discovery;

  my $d = new NetworkInfo::Discovery ('file' => '/tmp/test.xml', 
			      'autosave' => 1) 
		    || warn ("failed to make new obj");

  use NetworkInfo::Discovery::Host;

  my $host = new NetworkInfo::Discovery::Host('ipaddress'=> '192.168.1.3',
				      'mac'=> '11:11:11:11:11:11',
				      'dnsname' => 'someotherhost' ) 
		    || warn ("failed to make host");

  $d->add_host($host) || warn "failed to add new host";

  use NetworkInfo::Discovery::Sniff;

  my $s = new NetworkInfo::Discovery::Sniff;
  $s->maxcapture(60);
  $s->capture;
  $s->process_ip_packets;

  my @hosts = $s->get_hosts;

  $d->add_hosts(@hosts);
  $d->write_graph('/tmp/test.xml');


  use NetworkInfo::Discovery::Traceroute;

  my $t = new NetworkInfo::Discovery::Traceroute (host=>"www.google.com");

  my @thosts = $t->get_hosts;
  my @thops = $t->get_hops;

  $d->add_hosts(@thosts);
  $d->add_hops(@thops);

  $d->write_graph('/tmp/test.xml');

DESCRIPTION

NetworkInfo::Discovery is a set of modules that can be used to discover network topology, hosts on the network, and information about the links between hosts. The network map is controlled from a single location. Host detection currently runs from this location, but in the future there will be support for having remote agents that contribute to the central map.

METHODS

new

returns a new Discovery object, and takes the arguments shown in this example:

    $obj = NetworkInfo::Discovery->new( [autosave	=> (1|0),]
				[file    	=> $filename,]);

find_host ($host)

locates and returns a host based on the attributes set in the $host argument. $host is made by creating a Host object with only the attributes that you are looking for.

in a list context we return all hosts that match the criteria, but this may take a long time if you have a large network.

in a scalar context, we return the first match.

get_host ($id)

makes an Host object out of a graph node. $id is the id number of the node. returns undef if there is no matching node, returns the Host otherwise.

add_host ($host)

adds a single Host object into the graph.

add_hosts (@hosts)

adds more than one Host object into the graph.

delete_host ($host)

removes a single Host object from the graph.

add_hop ($hop)

adds a weighted edge between two hosts. $hop is a reference to an array like [$host1, $host2, $latency, $bandwidth]. $host1 and $host2 are actual Host objects. $latency and $bandwidth are just that between the hosts, and are optional.

add_hops

adds a list of hops. Each list item is an array ref as described in add_hop.

print_graph

prints the xml formated graph to STDOUT

read_graph ([$filename])

tries to read xml formated network data in from the $filename. if $filename is not give., tries to use what was set at creation of this object.

write_graph ([$filename])

stores the network in xml formated form in $filename. if $filename is not give., tries to use what was set at creation of this object.

file ([ $filename ])

get/set the file to store data in

network ([ $graph_base ])

get/set the network graph

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

DESTROY

just tries to write_graph if we have autosave turned on

MODULE LAYOUT

NetworkInfo::Discovery consists of several modules that all into three categories:

Network Container

The ony module that fits into the category is NetworkInfo::Discovery itself. NetworkInfo::Discovery maintains the network map as a Graph and has several functions for manipulating the graph. The nodes in this graph are NetworkInfo::Discovery::Host objects. The edges between nodes represent a direct link and are weighted by the latency measured between the connected nodes.

Network Object

NetworkInfo::Discovery::Host is the only one at this point. This type of module holds all known data about a single host.

Detection Modules

These modules should all be a subclass of NetworkInfo::Discovery::Detect. Currently NetworkInfo::Discovery::Sniff and NetworkInfo::Discovery::Traceroute are the only modules that fit here. Sniff is a passive monitor that listens to ethernet traffic on the local sement to build a list of Hosts. Traceroute is used to map the hosts and hops between the local host and a remote host.

AVAILABILITY

This module can be found in CPAN at http://www.cpan.org/authors/id/T/TS/TSCANLAN/ or at http://they.gotdns.org:88/~tscanlan/perl/ =head1 AUTHOR

Tom Scanlan <tscanlan@they.gotdns.org>

SEE ALSO

NetworkInfo::Discovery::Host

NetworkInfo::Discovery::Detect

NetworkInfo::Discovery::Sniff

NetworkInfo::Discovery::Traceroute

BUGS

Please send any bugs to Tom Scanlan <tscanlan@they.gotdns.org>

COPYRIGHT AND LICENCE

Copyright (c) 2002 Thomas P. Scanlan IV. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.