~Intro ----- This set of documents and programs adds up to a database backed web-app called tracker. It allows network managers and engineers to track nodes on their network and the switch ports they are attatched to. It can be used and distributed freely under the terms of the Free Software Foundation GPL. General ------- The major componenets of tracker are: - The database tracker uses the perl DBI layer to access the backend database. It currently supports mySQL and PostgreSQL. - The collector scripts node_collector.pl: collects mac address forwarding (cam) tabled and arp table using SNMP. swport_collector.pl: collects information and input counter about switch ports using SNMP cdp_discoverer.pl uses snmp-util and the cisco cdp mib to discover new cisco devices on the network and add them to tracker's database of devices - The web interface perl cgi scripts accept a query string and return matching database entries. tracker-admin.pl allows for administering the tracker configuration and devices database through the web. Requirements ------------ The scripts all require perl 5 to run. The collector scripts are multi-threaded and require a perl binary that has been compiled with thread support. You must have the backend database configured and running before you start. You will need the following perl modules: -perl DBI layer, DBI.pm -DBI driver module for your database backend -CGI.pm -Net::SNMP The cdp collector will attempt to resolve system object ID to a text description. In order for this to work you should download a copy of the oid format MIBs from cisco and place them in cisco_mibs_oid under the working directory for cdp_collector.pl. Installing (getting it to run) ------------------------------ files from tracker will reside in different directories on your system. You must either pick, or create a home direcrory for tracker where the collector scripts and Cisco MIB's will reside. The collection scripts can be run as root, or a separate user account for tracker can be created. The html documents should be somewhere under your web server document root. The cgi-scripts must be somewhere your web server will run them as cgi-scripts. By default the html files point to the web scripts in /cgi-bin/tracker. The perl modules must be somewhere in your perl include path (/usr/lib/perl5 works for me). The configuration for tracker is stored in three places: Database and file locations are in tracker.pm CGI script configuration is in tracker_cgi.pm operating parameters and authentication information are stored in the database. Install the files from the tracker tar file onto your system. The files should be placed: tracker/home/* -> tracker home directory (ex. /home/tracker) tracker/www/* -> web document root (ex. /var/www/tracker) tracker/cgi-bin/* -> web script alias directory (ex. /usr/lib/cgi-bin/tracker) tracker/pm/* -> perl module include directory (ex. /usr/lib/perl5) Also install the MIB's from cisco in the tracker home directory Edit the configuration in tracker.pm to choose your database backend information and the location of the tracker home direcrory. You must initialize the tables in the database that tracker will use. The user that your web server runs as must have an account in the database. Two files are provided to initalize the database tables, mysql_commands.txt for mySQL and sql_commands.txt for PostgresQL. sql_commands.txt assumes that your web user is called 'www-data' and grants permission to that user to access the tables. Since the tracker-admin.pl script allows remote users to reconfigure tracker, and view all of the authentication in formation, I suggest that you require authentication to access it. Postgres users should be able to perform all database initiaization by running the commands 'psql DBNAME < sql_commands.txt', assuming that 'www-data' is the name of the account your web server runs as. If you have an existing tracker database, running these commands will destory any node or switch port data you have collected. Use the tracker-admin.pl interface to configure your installation of tracker. cdp_initial_state: defaults to 'dns'. In this mode discovered devices are added to the database as active if their sysname and DNS information agrees. Can be set to any state from the devices_states table. The following configuration variable are global defaults, but can be overidden for individual devices: snmp_rw_string: SNMP community string allowed to read from devices The following variables control the behaviour of the collection scripts: node_collector_threads snmp_collector_threads By default the collector scripts run in one proccess. Set these variable to the number of child thread the collector should use to perform collection. 25 is a reasonable value for both on a current dual-processor computer. Reduce the value if collection is taking too much RAM or CPU, increase to reduce the amount of time the collectors take to run. cdp_ignore_ports: Switch devices also have a special per-device field for ignored ports. The ignored ports string is a colon separated list (like 0/1:0/2) of ports that will be ingored by the switch collector. Trunk ports are ignored in any case, but you can set this to 1 and the discoverer will populate the lsit of ports to ignore based on which ports had cdp neighboors. Use this option if your network has inter-switch links that are not configured as trunks. There are two ways to populate the database of devices: Manually add all devices using the web interface, or Manually add seed devices using the web interface, and run the cdp_discoverer to automatically discover all devices on your network. Once the table of devices is populated, you can run the collector scripts from the command line, and you should be able to see the data being added to the database. You can add the collector scripts and cdp_discover to cron to run at sensible intervals. The scripts host.pl which reports on the status of a host requires an suid copy nmap at least version 2.544beta22 be in the tracker home directory. If you don't want this funcitonality, or don't want to install an suid nmap, comment out the line which in vokes it in host.pl. The cdp_discoverer and some of the query scripts rely on the resolver working correctly on the host that tracker is running on. Some of query cgi's use a staticly configured list of domains that can be customized in tracker_cgi.pm. Run the collectors to verify that the configuration is correct. After verifying that data is being added to the nodes and switch_ports tables you should schedule the collectors to run at regular intervals using cron or some other scheduling facility. Credits ------- Originally written by Stephen Roylance (sroylance@partners.org). Please feel free to cotnact me with questions, problems or suggestions. Ported to the perl DBI tranparent database layer by Jose Luis Araujo (jlaraujo@bigfoot.com).