

---- Welcome to Network Resource Grapher! ----

NRG is a system for maintaining and visualizing network data and
other resource utilization data.  It automates the maintenance
of RRDtool databases and graph web pages (that look like
MRTG web pages.)  NRG is primarily configured using very terse
meta-configuration strings.  These strings tell NRG to autodiscover
network devices and verify that their current NRG configuration
is correct.  Ultimately, the NRG system creates and maintains a
web site which indexes, graphs and provides textual tables of the
following types of data:

    - Apache web server throughput
    - Apache web server query rates
    - BIND dns server query rates
    - BIND dns server error rates 
    - Cisco ATM PVC utilization
    - Cisco CPU busy 
    - Cisco memory utilization 
    - DNS query response times
    - FTP response times
    - IMAP response times
    - HP ProCurve CPU busy 
    - HP ProCurve memory utilization 
    - HTTP response times
    - Network interface utilization via SNMP
    - Network interface errors via SNMP
    - Ping data (latency and reachability)
    - POP3 response times
    - Sendmail message rates
    - Sendmail message throughput
    - SMTP response times
    - SSH response times
    - Unix file system utilization via Net-SNMP's snmpd
    - Unix load average via Net-SNMP's snmpd
    - Unix memory utilization via Net-SNMP's snmpd
    - Unix virtual memory utilization via Net-SNMP's snmpd


---- Using NRG ----

An RRDtool installation usually has at least three types of files:
".rrd files" which contain RRDtool databases, rrdcgi "graph web
page" scripts which display graphs of RRDtool data on the web and
"data collection scripts" that automate data collection.

The operation of RRDtool involves the addition, deletion and updating
of these types of files.  NRG automates the operation RRDtool by
maintaining these three types of files (and two others) for you.
In addition to the three types of files already described, NRG
maintains "table web pages" and "index web pages".  NRG table web
pages provide a textual table with the current values of DSs for
a set of similar RRDs with hyperlinks to the corresponding graph
web pages.  NRG index web pages hyperlink to all .cgi files in a
given directory tree.

To automate data collection, NRG generates the "run-nrg" script
which executes snmpget or other data collection commands and
does "rrdtool update" to archive data into RRDs.  The run-nrg
script is a sophisticated perl script which is self-locking and
has configurable command timeouts.  These features optimize the
likelihood of efficient data collection.

The "nrg-autoconf" script along with a Makefile automate the
operation of NRG.  To make changes to your NRG server, just edit
the NRG.mconf file, do "make update" to preview the resulting
changes in configuration, and do "make notify" to put the changes
into production.  (If the resulting changes in configuration are
not correct, simply do nothing.)

Read the file "configuration" for full instructions about configuring NRG.
After that, read the file "operation".  For information about operating
NRG at the meta-layer, read the file "metaconf".  For information about
the NRG configuration keywords, read L<conf-strings>.


---- Quick Start ----


    cd /usr/local/src
    gzcat nrg-0.x.tar.gz | tar -xf -
    cd nrg-0.x
    ./configure
    # nrg installs on top of rrdtool...
    mv /usr/local/rrdtool-1.0.x /usr/local/nrg  
    make install
    cd /usr/local/nrg
    # edit the Makefile: set WEB_PREFIX to the path to your 
    # web server content...
    vi Makefile
    mkdir /var/www/html/nrg
    # edit Site.mconf: set WebRootDir[*] to the path to your
    # web server content, change "SomeSwitch" to the name of 
    # some SNMP device and change the IP address and SNMP 
    # community read string accordingly...
    vi Site.mconf
    make rediscover
    make notify
    # do data collection...
    ./run-nrg -d
    # wait five minutes and do (verbose) data collection...
    sleep 300
    ./run-nrg 
    # configure your web server to execute .cgi files and 
    # run as your login... then view your nrg web site at
    # http://localhost/nrg/
    # configure cron to gather your NRG data every five
    # minutes...
    cd /tmp
    crontab -l > crontab
    echo "0,5,10,15,20,25,30,35,40,45,50,55 * * * * \
      /usr/local/nrg/run-nrg -d > /tmp/run-nrg.log 2>&1" >> \
        crontab
    crontab crontab


---- Assumptions ----

NRG assumes you know the basics about Unix, networking and SNMP--the
simple network management protocol.  You can read a brief description
of SNMP by doing "man rrdtutorial" and skipping to the "Some words
on SNMP" section.

You should also know a little about RRDtool.  Do the tutorial (see
"man rrdtutorial") and make at least one or two modifications to
the examples it provides.  Also do "man rrdcgi" and try one of the
example rrdcgi scripts.


---- Building and Installing NRG ----

Read the file "install" for instructions about localizing and installing 
NRG.  


---- The Source ----

ftp://noc.hep.wisc.edu/pub/src/nrg/


---- The Mailing Lists ----

There are two mailing lists for NRG: nrg-users and nrg-announce.  To 
subscribe, send a message with the text "subscribe" to
nrg-users-request@mail.physics.wisc.edu
or
nrg-users-announce@mail.physics.wisc.edu


---- Contact Information ----

Feel free to send email to rader@hep.wisc.edu.

 steve
 - - -
 systems and network manager
 high energy physics
 university of wisconsin

