------------------
Nagiosgraph README
------------------

File:    $Id$
Author:  (c) Alan Brenner, Ithaka Harbors, 2008; Soren Dossing, 2005
License: OSI Artistic License
         http://www.opensource.org/licenses/artistic-license.php

Nagiosgraph is an add-on of Nagios. It collects service performance data into
rrd format, and displays the resulting graphs via cgi.

Note: Nagios is a registered trademark of Ethan Galstad.



Usage
------

Follow the instructions in INSTALL for how to install and configure 
nagiosgraph.



Files
------

CHANGELOG         - History of changes
INSTALL           - Dcoument for how to install and use nagiosgraph
README            - This file
README.map        - Document for how to create map file entries
TODO              - A list of potential improvements to Nagiosgraph.
install.pl        - an initial stab at an installer (for the brave only).
lib/insert.pl     - Reads perfdata log from nagios and insert into rrd 
                    files.
lib/insert.sh     - A shell script wrapper around insert.pl.
lib/nagiosgraph.js - JavaScript used by show.cgi for menus.
cgi/show.cgi      - Generates an html page for the host/service specified.
cgi/showgraph.cgi - Generates graphs for show, showhost and showservices.
cgi/showhost.cgi  - Generates an html page for the host specified, showing all
                    available services on the host.
cgi/showservices.cgi - Generates an html page for the service specified, showing
                    all hosts with that service's data.
cgi/testcolor.cgi - Preview of colors for keywords in each color scheme
etc/nagiosgraph.conf - paths and other configuration
etc/hostdb.conf   - Configuration specific to showhost.cgi
etc/servdb.conf   - Configuration specific to showservices.cgi
etc/map           - Regular expression to identify services and 
                    specification for how to create rrd files.
etc/ngshared.pm   - Shared library of common perl subroutines
more_examples/*   - Additional configuration examples.
share/action.gif  - An icon for use in Nagios.
share/nagiosgraph.css - CSS stylesheet
t/*               - perl test scripts
utils/testentry.pl- A script for testing new map file entries.
utils/upgrade.pl  - A script for upgrading from older releases of Nagiosgraph.


Getting Help
------------

Visit the help forum -- http://sourceforge.net/forum/forum.php?forum_id=394748
See also the project wiki -- http://nagiosgraph.wiki.sourceforge.net



Principles of Operations
------------------------

nagiosgraph is basically a simple interface between Nagios and rrd data
files. Simplicity comes from three factors; it doesn't do much, behavior
is programmed rather than configurable, and automatically detects new
data from Nagios.

nagiosgraphs is operating in two modes. One is to collect performance
data from servicechecks from nagios, and the other is to display graphs
of the performance data collected.

All the data collected are stored in rrd files by using rrdtools. A file
called 'map' defines how identify the data from nagios and how to store
it in the rrd files. Nagios passes all the service data collected to a
nagiosgraph script called 'insert.pl'. This script will look up in
'map', which rrd file to insert the data into, and how to name the data.

In Nagios, it's possible to have extended service information pages.
A nagiosgraph cgi script called 'show.cgi' is used for such service
information links. 'show.cgi' looks up performance data stored in rrd file 
directories, and generates line charts accordingly. 

nagiosgraph automatically detects new hosts or services added in Nagios, 
so generally no re-configuration of nagiosgraph is necessary.

The 'map' configuration file is actually perl code, that will be eval'ed
by 'insert.pl' and 'show.cgi'. Several examples of servicechecks are
included in the distributed 'map' file, but generally it's necessary to
make modifications or add entries to match the output of the particular
nagios plugins in use. Knowing perl regular expression is helpful,
but the examples supplied should cover most types of performance data.

By default all available data for a servicecheck will be displayed in
the same graph. With extra configuration, embedded in the url, it's
possible to display less data or to split values into multiple graphs.
There is also a general method for specifying any rrd graph options.

