

---- Overview of NRG Operation ----

- The maintenance of NRG is performed by using "make" and the "NRG
operations Makefile", usually in /usr/local/nrg.

- The existance of .mconf files is specified via the MCONF_FILES
variable in /usr/local/nrg/Makefile.  NRG.mconf and Site.mconf
are specified by default.  If you have a large or complex NRG web 
site, you may want to use multiple .mconf files.  (For example,
a regional network might have CoreRouters.mconf, SiteRouters.mconf,
CoreCircuits.mconf PeeringCircuits.mconf and Servers.mconf.)

- The existance of .conf files is specified by "ConfFiles:".
The NRG.mconf file has "ConfFiles: *.conf" so that all .conf files
in /usr/local/nrg are automatically used.

- After adding, changing or deleting a .mconf file or .conf file,
go to the /usr/local/nrg directory and do "make update".

- If you're using nrg for the first time, you should do
"make rediscover".  "make rediscover" causes nrg-autoconf to do
auto-discovery: it runs nrg-discover scripts, saves the resulting
.conf files in autoconfs.NEW and reports about changes in the resulting
configuration.

- If you've simply changed an existing .mconf or .conf file and don't
want to redo all auto-discovery, then do "make update".

- If you want to do auto-discovery of a specific meta-target, for
example, because "SomeSwitch" has a new interfaces, then do,
"make SomeSwitch"

- Note that this new configuration is not in production--it does not
effect the operation of NRG in any way.

- If the resulting configuration is acceptable, do "make notify"

- If the resulting configuration is not acceptable, you can "throw
away" this new configuration by removing the autoconfs.NEW directory.
Or you can simply ignore it and the next autoconfiguration will
remove/overwrite it.

- "make notify" will cause NRG to put the last auto-discovery into
production.  It executes nrg-rrdkeeper which will create any new
.rrd files and archive obsolete, "orphaned" .rrd files.  It will also
execute nrg-cgikeeper and nrg-tablemaker which will add, update and
archive .cgi files.  Lastly, it will executes "nrg-runmaker" which
will create the "run-nrg" script used for gathering and archiving data.

- To start using your run-nrg script quickly, execute a simple for
loop in a sh, ksh or bash shell like so:

    while (true); do
      ./run-nrg -d
      sleep 300
    done

- To put your run-nrg script into production, tell the Unix cron
facility to execute your NRG run-* script 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" >> \
      crontab
    crontab crontab

- You should be able to view your NRG web pages via 

    http://localhost/nrg/

- At this time, you may not have enough data in your RRD databases
for them to generate graphs that display noticable data.  Wait more
than five minutes and your NRG web pages should have data.

- The process of autodiscovery can be further automated using the
Unix cron facility.  Tell cron to execute "make quite-rediscover"
every weekday morning at 2am and mail you the results:

    cd /tmp
    crontab -l > crontab
    echo "0 2 * * 1,2,3,4,5 \
      (cd /usr/local/nrg; make rediscover | \
      mail -s \"NRG Autodiscovery Report\" root)" >> 
      crontab
    crontab crontab


---- A Discussion about NRG Data Collection ----

- The data collection and archiving part of NRG is done by the run-nrg
script (and sometimes other run-* scripts.)  These scripts output
information about data collection and archiving failure to STDERR.
In debug mode (eg "run-nrg -d") these scripts output specifics (an
audit trail) about data collection and archiving to STDOUT.

- Using cron to execute run-nrg (without STDERR redirected) will
cause cron to send detailed email messages about data collection and
archiving failures.

- To keep a log of NRG data collection/archiving activity and data
collection/archiving failures, use

    run-nrg -d >> /var/log/nrg.log 2>&1

- To keep a log of only NRG data collection/archiving failures, use

    run-nrg 2> /var/log/nrg.log

- You can use "RunScript[]:" .conf strings and/or RunScript: .mconf
strings to specify other run scripts.  This is useful in many ways:

- Run scripts can be used to do multiple data collection/archive runs
in parallel.  To do this, simply use multiple crontab entries--one
for each run script--that have the same time and date fields.

- Run scripts can be used to create separate logs for various classes
of data collection/archive runs.  To do this, simply redirect the
output of your various run scripts.  For example,

     run-routers -d > /var/log/nrg-routers.log 
     run-hosts -d > /var/log/nrg-hosts.log
     run-services -d > /var/log/nrg-services.log


---- A Discussion of the nrg-autoconf Script  ----

- nrg-autoconf automates the task of creating .conf files.
nrg-autoconf reads configuration information from .mconf files and
uses it to run nrg-discover-* scripts which write .conf files.

- nrg-autoconf redirects STDERR from nrg-discover-* scripts to
.error files.  The contents of these .error files can be used to
examine details about auto-discovery and fix auto-discovery problems.

- Each time nrg-autoconf executes a nrg-discover-* script, it writes
a script with no file name extension that contains the exact details
about how nrg-autoconf invoked the nrg-discover-* script.  These
scripts can be used to redo auto-discovery of a single meta-target
by hand from the command line.

- For example, if you use all the default values and have a meta target
named SomeSwitch, then nrg-autoconf will create the following files:

    autoconfs/net/SomeSwitch       - use this script to redo/examine 
                                     autodiscovery of SomeSwitch

    autoconfs/net/SomeSwitch.conf  - the .conf strings for 
                                     autodiscovery of SomeSwitch

    autoconfs/net/SomeSwitch.debug - the STDERR (debug) output from
                                     nrg-discover-ifaces -debug


