------------------------
nagiosgraph Installation
------------------------

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

The instructions below are mainly for latest stable versions of Nagios,
e.g. 2.12, and might differ in other versions of Nagios. See the end of this
document for platform specific notes.



Installation Preliminaries
--------------------------

 - Check required packages: nagios, nagios-plugins, rrdtool, perl,
   perl-CGI, and perl-rrdtool

 - Extract the Nagiosgraph tarball into a temporary location:

   tar xzvf nagiosgraph-1.3.0.tgz

 - Copy the contents of etc into your preferred configuration target location,
   e.g. /etc/nagios/nagiosgraph

 - Edit the perl scripts in the cgi and lib directories, modifying the "use lib"
   lines to point to the directory in the previous step.

 - Copy the contents of lib into a location Nagios can execute file in
   e.g. /usr/lib/nagios

 - Copy the contents of cgi into the Nagios cgi-bin directory,
   e.g. /usr/lib/nagios/cgi-bin

 - Copy the share/action.gif file into the Nagios image directory,
   e.g. /usr/share/nagios/images

 - Copy the share/nagiosgraph.css file into the Nagios stylesheets directory,
   e.g. /usr/share/nagios/stylesheets

 - Copy the share/nagiosgraph.js file into a directory serve-able by your web
   server, and configure the "javascript = /nagios/nagiosgraph.js" in the
   nagiosgraph.conf to point to URL for nagiosgraph.sh.

 - Edit paths, debug level etc. in nagiosgraph.conf.

 - Update permissions of "rrddir" (as defined in nagiosgraph.conf),
   so that the *nagios* user can write to it and the *www* user can read it.

 - Update permissions of "logfile" (as defined in nagiosgraph.conf)
   so that both the *nagios* and *www* users can write to "logfile".


Upgrade Notes
-------------

 - Follow the above steps, except only copy the etc/ngshared.pm file from the
   etc directory to your configuration target location.

 - Use diff, or a similar tool, to update your nagiosgraph.conf with new fields
   from etc/nagiosgraph.conf, and in particular, note the JavaScript change.
   The majority of the JavaScript used in each web page is now a separate file
   that gets sent seperately to the browser, and as such needs to go where the
   web server can send it.

 - You may want to look at etc/map to see if there are any new examples that you
   may find useful.



Service Perfdata Processing Configuration
-----------------------------------------

NOTE: Two ways to define data processing -- the new style and the old style.

+-----------+
| New Style |
+-----------+

In new style, all performance data append to a file,
then, nagios invokes insert.pl at a regular interval to update rrd files.

 - In nagios.cfg set:

     process_performance_data=1
     service_perfdata_file=/var/spool/nagios/perfdata.log
     service_perfdata_file_template=$LASTSERVICECHECK$||$HOSTNAME$||$SERVICEDESC$||$SERVICEOUTPUT$||$SERVICEPERFDATA$
     service_perfdata_file_mode=a
     service_perfdata_file_processing_interval=30
     service_perfdata_file_processing_command=process-service-perfdata

   Make sure that service_perfdata_command is either commented out
   or not defined.

   Make sure that location of service_perfdata_file matches that of perflog
   defined in nagiosgraph.conf.

 - In checkcommands.cfg or misccommands.cfg, depending on which
   defined in nagios.cfg:

     define command {
       command_name  process-service-perfdata
       command_line  /usr/local/nagios/nagiosgraph/insert.pl
     }

   Make sure there is only one definition for process-service-perfdata.

   Some installations of Nagios (with embedded perl) requires to specify
   location of perl. Modify command_line to:

     command_line /usr/bin/perl /etc/nagios/nagiosgraph/insert.pl


+-----------+
| Old Style |
+-----------+

The old style consumes more CPU. Nagios invokes insert.pl immediately after
every service check, to update the corresponding rrd files.

 - In nagios.cfg:

     process_performance_data=1
     service_perfdata_command=process-service-perfdata

   Make sure that service_perfdata_file_processing_command is either
   commented out or not defined.

 - In checkcommands.cfg or misccommands.cfg, depending on which one is
   defined in nagios.cfg:

     define command{
       command_name  process-service-perfdata
       command_line  /usr/local/nagios/nagiosgraph/insert.pl "$LASTSERVICECHECK$||$HOSTNAME$||$SERVICEDESC$||$SERVICEOUTPUT$||$SERVICEPERFDATA$"
     }


   Those Nagios with embedded perl might need specifying the location of
   perl so insert the full path to perl binary in the command_line, such as:

     command_line /usr/bin/perl /etc/nagios/nagiosgraph/insert.pl "$LASTSERVICECHECK$||$HOSTNAME$||$SERVICEDESC$||$SERVICEOUTPUT$||$SERVICEPERFDATA$"



Configuring Graphing and Display
--------------------------------

 - For Nagios versions < 2.6, define in cgi.cfg the following:

     xedtemplate_config_file=/usr/local/etc/nagios/serviceextinfo.cfg

 - For Nagios version 2.6 and later.
     Note: This may also be what is required for earlier versions of Nagios.
     It is uncertain as when Nagios started handling extended services differently.

     If you have these lines in nagios.cfg, then this step is what you need to do
     instead of the one above.

     # Extended host/service info definitions are now stored along with
     # other object definitions:
     # cfg_file=/etc/nagios/hostextinfo.cfg
     # cfg_file=/etc/nagios/serviceextinfo.cfg

     Un-comment the 2 cfg_file= lines.
     [NOTE: hostextinfo.cfg not required for Nagios 2.9]


 - Edit or create hostextinfo.cfg [NOTE: For Nagios 2.9, skip this step.]

     define hostextinfo {
       host_name  your-host
     }

     This must be the host you will use in serviceextinfo.cfg

 - Edit serviceextinfo.cfg

   Most services can be graphed with no particular configuration like this:

     define serviceextinfo {
       service_description  DNS
       hostgroup       servers
       notes_url       /nagiosgraph/show.cgi?host=$HOSTNAME$&service=$SERVICEDESC$
       icon_image      graph.gif
       icon_image_alt  View graphs
     }

 -- Instead of hostgroup line a host_name line with all hosts where this
    type of data are being collected.

 -- For Nagios 2.9, delete or comment out the two lines of icon_image
    and icon_image_alt. And, replace nagios/images/notes.gif with your own
    40x40 gif file.

 -- Some type of services have data values that have big differences in the
    magnitude. In such cases it's good idea to split up into seperate
    graphs. Here's an example for ntp for Nagios 2:

     define serviceextinfo {
       service_description  NTP
       host_name       server01,server02,server03,server04
       notes_url       /nagiosgraph/show.cgi?host=$HOSTNAME$&service=$SERVICEDESC$&db=ntp,jitter,offset&db=ntp,stratum
       icon_image      graph.gif
       icon_image_alt  View graphs
     }

    For Nagios 3, just add the notes_url to the existing service definition.

 -- Add geom option (e.g. &geom=350x100) to notes_url line for custom sizes of
    graphs.

 -- Add rrdopts option (e.g. &rrdopts=%2Dl%200%20%2Du%20100 (meaning:
   "-l 0 -u 100")) to notes_url line for custom Y axis ranges. Any
   rrdgraph options can be specified, but has to be url encoded.

 -- Add &fixedscale to set the Y-axis to be in the same units as the
   supplied perf data. Will also set the legends to be in same units


 - Configure Apache to point to show.cgi. For example:

     ScriptAlias /nagiosgraph/ /usr/local/nagios/nagiosgraph/



Adding New Mapping and Troubleshooting
--------------------------------------

 - To add new service types, edit the map file. This contains regular
   expression to identify service types, and defines how to store data in
   rrd files. Use testentry.pl for testing before inserting in map file.

   You can also run the nagios check command from the command line to see
   what is returned.

   NOTE: The current entry in map file for HTTP does not work for Fedora core 6
   with Nagios 2.6 and later.  This is what did work.

	# Service type: unix-www
	#   ouput:OK - HTTP/1.1 302 Found - 0.002 second response time |time=0.001920s;;;0.000000 size=126B;;;0
	/output:.*?HTTP.*?([.0-9]+) sec/
	and push @s, [ http,
		[ rt, GAUGE, $1 ] ];

 - Restart Nagios. Increase debug level in nagiosgraph.conf if things don't
   work right away.

 - Keep an eye on the log file. It can grow big. Perhaps rotate it, or
   decrease log level when everything works fine.



Platform Specific Notes
-----------------------

CentOS 5 and Nagiosgraph 0.9:
-----------------------------

  wget 'http://dag.wieers.com/rpm/packages/rrdtool/rrdtool-1.2.18-1.el5.rf.i386.rpm'
  wget 'http://dag.wieers.com/rpm/packages/rrdtool/perl-rrdtool-1.2.18-1.el5.rf.i386.rpm'
  wget 'http://dag.wieers.com/rpm/packages/rrdtool/rrdtool-devel-1.2.18-1.el5.rf.i386.rpm'
  wget 'http://mesh.dl.sourceforge.net/sourceforge/nagiosgraph/nagiosgraph-0.9.0.tgz'
  yum install -y libart_lgpl.i386
  rpm -hiv *rrdtool*.rpm

  tar xzvf nagiosgraph-0.9.0.tgz
  cd nagiosgraph-0.9.0
  mkdir /usr/local/nagios/nagiosgraph
  cp -r . /usr/local/nagios/nagiosgraph/
  mkdir /usr/local/nagios/nagiosgraph/rrd
  chmod go+rX /usr/local/nagios/nagiosgraph
  chown nagios /usr/local/nagios/nagiosgraph/rrd
  mkdir -p /var/spool/nagios
  touch /var/log/nagiosgraph.log /var/spool/nagios/perfdata.log
  chown nagios.apache /var/log/nagiosgraph.log /var/spool/nagios/perfdata.log
  chmod 664 /var/log/nagiosgraph.log
  chmod 644 /var/spool/nagios/perfdata.log

  ln -s /usr/local/nagios/nagiosgraph/nagiosgraph.conf /usr/local/etc/nagiosgraph.conf

  cp nagiosgraph.css /usr/local/nagios/share/stylesheets