Network Visualization

Page under construction

This project consists of three major modules netdisc, netvis and netreport.

netdisc

      What is netdisc?

              netdisc is a network discovery utility that uses SNMP to discover the structure of IP networks.
      netdisc retrieves a number of MIB variables,  primarily from the MIB-2 IP group, including the
      ip.ipNetToMediaTable (IP ARP table), ip.ipAddrTable (IP address table) and interfaces.
      ifTable (IP interface tables).  Based on that information and a few other items,  netdisc will discover
      the topology of an SNMP-managed IP subnet-based network.  netdisc also can distinguish the
     difference between routers and hosts, and will output two lists, routers.ip and hosts.ip, as separate
     files.


How to install netdisc?
 

How to use netdisc?
     netdisc is typically started with no options. It reads its configuration from /etc/netdisc.conf if it exists.
     Otherwise, it will try to read configuration from $HOME/netdisc.conf. netdisc only reads the configuration
     file when it starts up, and never writes it.

     Command Line Syntax :
         netdisc [-c config-file] [-rid run-id] [-d] [-p] [-h]

     -c config-file
             Specifies the configuration file.

     -rid run-id
             Specifies the run-id. run-id is used to uniquely identify each run.  It is very useful if you want to
             combine two different runs  together.  See netreport  for more information about run-id.

     -h      Prints out a help message

     -d      Enable debugging.  This switch causes netdisc to print copious debugging information to standard
              output.  This is probably a  good idea on the first few runs at any site.

     -p     Parse configuration file.  With this flag, netdisc merely parses  the configuration file and exits.
             If netdisc successfully parses  the configuration, it dumps a description of its internal variables
             (similar to the output when -d is used).

How does netdisc work?
      netdisc starts with a node, which is called the starting point.  The starting point should either be the box
      that netdisc is run on (which  must have a snmpd daemon and have ip.ipForwarding set to 1) or should be
      an snmp-managed router in the network.  It will then retrieve MIB variables including the ip.ipForwarding
      and interfaces.ifNumber. If netdisc successfully obtains the MIB variables, then it decides if the node is a
      router or a host by checking the ip.ipForwarding. If netdisc thinks the node looks like a router, then it
      proceeds to retrieve the node's  ip.ipAddrTable and ip.ipNetToMediaTable. The ip.ipNetToMediaTable
      is very  important to the success of the discovery process that is carried out by  netdisc. netdisc uses the
      IP addresses in the ip.ipNetToMediaTable to recursively explore the network and build up a list of discovered
      nodes. Because the discovery process is a recursive process, it will not stop unless netdisc thinks that a
      termination condition is met. Termination  conditions include no information about the snmp password
      (therefore  netdisc will not follow a link), and specific IP addresses which will  cause netdisc to not acquire
      information from a link and hence not explore further.  As a result, netdisc can be taught to "not discover the
      Internet".  See netdisc.conffor more information about the termination conditions.

     netdisc does not use ip.ipRouteTable (routing table) for the following two reasons:

     Therefore we do not use the routing table. The discovery process can be divided into four steps.
     The following is a brief description of each step.             Take a quick look at the node and retrieve the MIB variables  ip.ipForwarding and interfaces.ifNumber.
            netdisc only proceeds to step 2 if the ip.ipForwarding is on (which is 1 in SNMP).  By definition, if there
            is no SNMP on a node, or we do not know the community name for the node, it is treated as a host, and
            no further discovery is done.            Take a closer look at the node and retrieve the ip.ipAddrTable and interfaces.ifTable. Once netdisc
           obtains this information, it can make a correct decision that if the node is a router or a host.
           netdisc only proceeds to step 3 if it believes that the node is a router.           Once netdisc is sure that the node is a router, it goes further to retrieve the ip.ipNetToMediaTable and
          build a list of IP addresses of its neighbors.            netdisc stops the discovery process if it found the nodes which are specified in the ipTCC section of
           netdisc.conf,  or it found the interfaces which are specified in the ifTCC section of netdisc.conf. netdisc
           also stops when it runs out of candidate nodes (no more nodes to discover).
           See netdisc.conf  for more information.

Files required by netdisc

             The default configuration file for netdisc. See netdisc.conf  for more information.  This file should be
             protected in terms of  read permissions if the SNMP community strings in it are deemed valuable secrets.              The second configuration file.  netdisc searches /etc/netdisc.conf first. If it can not find it, then it searches
             for this file in the user's home directory.              The output file for discovered hosts. See hosts.ip for more information.              The output file for discovered routers. See routers.ip for more information.
 
 

Top of Page



 

netdisc.conf

     /etc/netdisc.conf is the default configuration file which defines how the netdisc utility operates.  netdisc.conf is
     only read by netdisc when it starts up and must be supplied in order for netdisc to work properly (unless an
     alternate configuration file is specified on the command line).  The configuration file is only read by netdisc, and
     not written by netdisc. If netdisc does not find the default configuration file it searches the user's home directory
     for  $HOME/netdisc.conf

     Each line of a configuration file is a separate statement.  Each configuration option begins with a tag or keyword
     and occupies one line.  The syntax of configuration options depends on the individual tag.  Tags may take zero
     or more arguments.  Blank lines and comment lines beginning with a '#' in the first column may be used to add
     whitespace or comments.

     A configuration file may be tested (parsed) by using netdisc -p. This switch causes netdisc to parse the
     configuration file and then exit without actually starting up.  It will print out internal values and exit with a success
     message if the configuration file can be parsed.

     Contents of netdisc.conf

                   1 means to check the interface even if its status is down.
                   0 means not to check it if it is down.  The default is 0.                    Specifies the community name to be used when talking to SNMP nodes.  The default community
                   name is public. This line is optional and may appear more than once if you have multiple default
                   community names. Note that it is best to list as few community names as possible.  This is because
                   each community name listed here will be tried per discovered node -- until a correct community name
                   is found.  This will slow you down on nodes (the majority) that do not speak SNMP.  If you have
                   many specific community names, use tag Community instead.  Overall the more community names
                   listed here, the slower the discovery process will be.                    Specifies agents and their community name. A default community name (specified by tag
                   DefaultCommName ) will be used for all the agents that are not listed here. Here is an example:
                           Community 131.252.222.1 public2.
                   This line may be used more than once when you have mulitple IP-CommunityName mappings.                    0 means to exclude all the interfaces defined in MIB II. (Default value)
                   (interface type number from 1 to 54).  1 means to include all the interfaces defined in MIB II.                    Specifies the interface types that you want to include (the default), or you want to exclude (use the
                   option E ). For example:
                           IfType 6 means to include the ethernet interface.
                          IfType 20 E means to exclude the basic ISDN interface.
                   Note that it only makes sense to  use E when IfExcludeMIB2 = 0, which means to include MIB II
                   interfaces but to exclude those that are listed here.                    Specifies the IP addresses (TCC) that shall stop the discovery process if they are found.  This line is
                   optional and may appear more than once if you have multiple possible termination IP addresses.
                   Once netdisc finds an IP address that matches an address listed here, it will stop adding  new nodes
                   into its internal working list (this list stores nodes that are retrieved from the previous iteration of
                   discovery process).  All nodes that are already on the list would be discovered, but no new nodes
                   would be discovered. Thus, the discovery process would be terminated when the working list is empty.                    Specifies the IP addresses of routers interfaces on which  no further discoveries are required.  This line
                   is optional and may appear more than once if you have multiple possible termination IP addresses. The
                   difference between ipTcc and ifTcc is that ifTcc prevents netdisc from discovering the subnets directly
                   connected to those specified interfaces. Put it in another words, ifTcc prunes off subnets from a large
                   inter-connected network.                    0 means not to retrieve routing table from SNMP nodes (default).
                   1 means to retrieve routing table.
                   For the routers that contain the entire Internet routing table, to retrieve it would be a disaster if you only
                   have a slow pipe or you do not have enough memory. This option is not currently implemented.                    Specifies how long to wait if there is no response from remote SNMP agents. The default value is 2
                   second. If you are using netdisc across WAN, you may need to increase timeout.                    Specifies the retry times if there is no response from remote SNMP agents. The default value is 1.
                   If you are using  netdisc across WAN, you may need to increase retry times.                    Specifies the IP address of the starting point. This line is required and the starting point should be a
                   router with a SNMP deamon running.                    Specifies the subnet mask of the starting point. This line is required.

Top of page



 

hosts.ip

     hosts.ip is the output file which contains a list of discovered hosts. Each discovered host occupies one line
     and begins with a host identifier. The following is the file format:

     <hostID, Status, IpAddress, SubnetMask, IfNumNoIP, IfNumEthernet, IpForwarding, DNS, OID>

      If a host has more than one IP address bound to its interface, then each binding will have a line in the hosts.ip.
      Thus, there will be more than one line beginning with the same hostID.

Top of page



 

routers.ip

     routers.ip is the output file which contains a list of discovered routers.  Each discovered router occupies one line
     and begins with a  router identifier.  The following is the file format:
         <routerID, Status, IpAddress, SubnetMask, InterfaceID, DNS, OID>

           routerID
                   An Internal index that uniquely identify each router.

           Status
                   Indicates the status of the node between two runs. It has four values, which are SIN - single run,
                   BTH - the host exists in both runs, MIS - the host exist in the first run but does not exist in the second
                   run (it is missing), and NEW - the host exist in the second run but does not exist in the first run
                   (it is new).

           IpAddress
                   Router's IP address

           Subnetmask
                   Router's subnet mask

           InterfaceID
                   An index that uniquely identify each interface in the MIB-II interfaces group.

           DNS
                   Domain name

           OID
                  The SNMP Oject ID.

Top of page


netreport

    What is netreport?
    netreport is a utility to process the output of netdisc. netreport sorts the output of netdisc by host ID or router
    ID. In addition, netreport is able to combine the outputs of two different runs of netdisc by run-ids, and figure
    out switches from hosts by checking the number of interfaces that do not have IP addresses.

    Usage
     netreport [-r router-file] [-h host-file] [-dns] [-s switch-file] [-i number-of-interface]
                    [-rid rid1 rid2 rid3] [-b]

     netreport is typically started with at least one option, which is the name of the file containing discovered routers
     or the name of the file containing discovered hosts.  netreport then sorts the content of the  file and performs
     DNS lookups as required.  The default output file name is the input name with .sorted at the end.

     -r router-file
             Specifies the input file for discovered routers. Usually, this is the output of netdisc.

     -h host-file
             Specifies the input file for discovered host. Usually, this is the output of netdisc. With this option netreport
             sorts the input host-file by host ID and outputs a file containing 8 columns if no DNS lookup is required,
             or 9 columns if DNS lookup is required. The format of the output file is the following:
                   [hostID, Status, IP, netmask, i/f, ifNumNoIP, ifNumEthernet, DNS name(optional), OID] .

     -rid rid1 rid2 rid3
             Instruct netreport to combine the outputs of two different runs (specified by rid1 and rid2 ) of netdisc
             into one file, whose ID is specified by rid3.   netreport then figures out the  network changes between
             two runs by giving each node a status, which has four possible values, 'SIN', 'BTH', 'MIS' and 'NEW'.

     -s switch-file
             Guess the switches from the hosts and output them to switch-file. The idea is that if a host has a certain
             number of interfaces that do not have IP addresses, it is possible that the host is a switch.  You can use
             -i number-of-interface to specify how many interfaces a node has for it to be considered as a switch.
              By default, netreport uses 7 as the  minimum number of interfaces for switches.

     -i number-of-interface
             Specifiy the minium number of interfaces for switches.

     -dns
             Do DNS lookup. When this option is used, netreport will print out the resolved names.  If -r router-file
             is specified, netreport sorts the  input router-file by router ID and outputs a file containing 6 columns if
             no DNS lookup is required, or 7 columns if DNS lookup is required. The format of the output file is the
             following:
                  [routerID, Status, IP, netmask, interfaceID, DNS name(optional), OID] .

     -b
             Instruct netreport to generate a broadcast domain report. The report is a plain text file.  Each line of the
             file contains the following columns:
                  [subnetID, netmask, numberOfHost, IP, snmpPort, Dns]

             numberOfHost is the number of the hosts in the broadcast domain (a.k.a subnet) specified by subnetID.
             IP is the address of the router interface that belongs to the broadcast domain and snmpPort is the ID of
             that interface in SNMP term. If there is more than one router in that subnet, there will be more than one
             line like this. They will have the same subnetID and numberOfHost, but different IP and snmpPort might
             be different as well.
 

Top of page