Date    : July 13, 1999
Author  : Philip Shuman
E-Mail  : pshuman@cisco.com
Dept    : ATM Dev Test
Title   : Lab Inventory Design Specification

 1. Introduction
========================================================================

   This document describes the design and overview of implementation for
   LabIV and libraries for use in LabIV.


 2. Requirements:
========================================================================

   LabIV is to take an inventory of all known devices in the Lab without 
   causing any disruption to the testing and other work going on it the lab.
   Options will include running a queue of all or selected lab devices and
   saving the results to a database for referance at a later time. Other
   options to perform a realtime device querey will also be included.

   Scalability requirements:
   -------------------------
      * Adding new types of line cards, devices, or other new hardware to
        what LabIV supports needs to be a simple, straight forward task
        that does not require changing any of the libraries or main 
        program code.

      * The Adding/Removing of testbeds in the lab and/or hostfile should
        be automatically accounted for.

   Multiuser requirements:
   -----------------------

      * Multiple users need to be able to have read access the results stored
        in the database concurrently without causing errors. Multiple requests
        to write to the same device data should not be allowed.


 3. Flow:
========================================================================

   Main Program Flow:
   ------------------
      Load labiv.conf
      Copy host file local
      Parse the host file
      Get command line arguments
      Generate a list of all devices to be probed
      For each device on the list, get requested information 

   Device Network Library get_info Flow:
   -------------------------------------

    1 Inputs device and command to be run
    2 If previous errors occured while connecting, quit
    3 If the command was previously run, lookup the previous results and return 
    4 If the device is already connected, proceed to step 7
    5 Try connecting through the ethernet port, if sucessful proceed to step 7
    6 Try the console port. if it fails, quit
    7 Check for any errors that may have occured while connecting
    8 Run the command on the device and save the output 
   

 4. Libraries & APIs:
========================================================================

***** PUBLIC FUNCTIONS *****

   Host File Library
   -----------------
      parse_hosts_file( Host file path name );

         Opens the hosts file at the given path name. The IP address is
         extracted into the array @ip and the device name is extracted
         into the array @name with corresponding keys into each.

      search_by_name( your regexp pattern );

         Returns array of keys indexing found values in @name

   Device Network Library
   ----------------------
      getinfo( Device Name, termserv IP, termserv port, Command to be run );

         Returns a scalar storing the result of running the specified
         command on a particular device. The library will only run the
         command once and save the output for future referance. Returns
         "-1" if there were errors connecting to the device.

      connection_status( Device Name );

         Returns the scalar value corresponding to the current connection
         status of the stated device. Possible values are:
            Ethernet                    Console
            ethernet-timed-out          nopasswd
            console in use              console timed-out
            monitor                     0
            undefined:(returned error)
 
         Ethernet and Console both imply that the connection was/is
         established correctly. Any other value implies that a connection
         was not established.

      disconnect();

         Closes all open connections.

   FTP Network Library
   -------------------
      get_ftp_file( Server name or IP, LoginID, Login Passwd, Directory, File );

         Connects to the ftp server on the specified server, logs in using
         the specified login id and password, changes to the specified
         directory and downloads the specified file to the working 
         directory. While this is only used to get the hosts file in the
         current LabIV implementation, it can be used to retrieve any
         file.

   Device Profile Library
   ----------------------
      To be determined...

***** PRIVATE FUNCTIONS *****

   Host File Library
   -----------------
      none

   Device Network Library
   ----------------------
      prev_run( device, command );   Has command been run on device?

      lookup( device, command );     return results from command on device

      connected( device );           Is there a connection to device?

      check_errors( device );        Any errors while connecting?

      run_cmd( device, command );    Run command on device and store output

      enet_connect( device ); 
         Attempts to establish an telnet connection with the specified device
         via the device's ethernet port. Returns 1 (success) or 0 (failed)

      console_connect( DeviceName-or-IP, TermservName, TermservPort );
         Attempts to establish an telnet connection with the specified 
         device through the console port via the terminal server. Returns
         1 (success) or 0 (failed)


 5. File Formats:
========================================================================

Host file from Godfather:
-------------------------

<IP>            <Name>          # <TermserverName> <TermserverPort>
20.0.0.10       fs01_rhn_03     # t24 2003
40.0.0.65       gd61_40k_08     # t1 2008 (pc t16 2008)
100.0.0.52      sh01_72k_06     # t42 2006 thebert
30.0.0.50       pnni_75k_13     #termserv_07 2011

   Verify with your DNS server documentation about proper format and field
   delimitors. LabIV will use spaces or tabs as delimitors in the actual
   DNS entry. 

   The first two fields must be <IP> and <Name> seperated by at least one
   space or tab charater. Anything between the <Name> field and the # will
   be ignored.

   In the comment section, the <TermserverName> must be followed by the
   <TermserverPort> and seperated by at least one space or tab charater.
   Trailing text or leading text is ignored. <TermserverName> must be of
   the form "termserv_20" or "t20" to be recognized. Any number of digits
   is recognized (t1, t10, t100, t1000). <TermservPort> must be between
   2000 and 2099.
