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

Nagiosgraph is an add-on of Nagios. It collects service performance data into
rrd format, and displays the resulting graphs via cgi.  It can be embedded
directly into Nagios so that graphs show up just like other trend reports.

Note: Nagios is a registered trademark of Ethan Galstad.

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



Usage
------

The INSTALL file contains installation and configuration instructions.


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



Files
------

CHANGELOG         - History of changes
INSTALL           - How to install and use nagiosgraph
README            - This file
README.map        - 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.
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.
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/rrdopts.conf  - Per-service options to rrdgraph
etc/map           - Regular expression to identify services and
                    specification for how to create rrd files.
etc/ngshared.pm   - Shared library of common perl subroutines
examples/*        - Configuration examples.
share/action.gif  - An icon for use in Nagios.
share/nagiosgraph.css - CSS stylesheet
share/nagiosgraph.js - JavaScript
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.



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.

