---------------
| DESCRIPTION |
---------------

Title   : eLuna Graph System
Version : 1.02
Date    : 2007-12-02
Website : http://steph.eluna.org/eluna_graph_system.html
Author  : Stephane Dupont
Mail    : steph@eluna.org
License : GNU General Public License (see ./LICENSE)


eLuna Graph System is an application written in Perl based on
RRDTool. Its aim is collection, and then presentation in graphic
form, of data, to aid in monitoring of a machine. By default, the
application allows monitoring of the load, the CPU usage as a
percent, memory use as a percent, number of processes, quantity
of data transmitted via eth0 (In/Out) and percentage of disc 
space in use on /. 


----------------
| PREREQUISITE |
----------------

- A machine ;)
- A root access on this machine
- An http server (preferably Apache)
- RRDTool (preferably version >= 1.2)
- Perl (preferably version >= 5.8)
  with the following modules installed :
  * DateTime
  * HTML::Template::Expr


----------------
| INSTALLATION |
----------------

- Decompress the archive into a folder accessible via Apache.

  Example :
    mv eluna_graph_system.tar.gz /var/www/graphs/
    cd /var/www/graphs/
    tar -xzf eluna_graph_system.tar.gz

- Perform a chown and/or a chmod (if necessary) on all scripts so
  that these are readable and executable by the user/group couple of
  the http server. The 'graphs' folder must also be writeable by this
  same couple. In the majority of cases, you have nothing to do.

- Schedule the execution of the 'update.pl' script every 5 minutes
  with the aid of crontab.

  Example :
    */5 * * * * root /var/www/graphs/update.pl

- Configure Apache (or any other http server...) in order that the
  'index.pl' script is interpreted correctly as a perl script and that
  it is viewed as 'DirectoryIndex'.

  Example :
    <Directory /var/www/graphs/>
      AddHandler cgi-script .pl
      Options +ExecCGI
      DirectoryIndex index.pl
    </Directory>
    
- Ensure that the '.htaccess' file containing 'deny from all' and contained
  in the 'rrd' folder is taken account of by Apache. The 'rrd' folder must
  not be accessible via http. In the case of an http server other than Apache,
  create a similar protective mechanism.

The application should now work fine. Wait about ten minutes so that the cron
task can be executed at least twice, then try to view all this in a web browser.
If everything goes well, you will see pretty little beginnings of graphs ;)

Do not hesitate to send me an email (steph@eluna.org) to let me know your
impressions.


-----------------
| CUSTOMIZATION |
-----------------

1/ Application parameters
   ----------------------

A certain number of parameters such as the name of your server, the format
of pictures generated, the size of images generated, the colours of images
generated, the default view, etc., can be modified in the 'Configuration'
section located at the beginning of the 'index.pl' file.


2/ Application appearance/texts
   ----------------------------

The application uses the Perl HTML::Template::Expr module, itself being an
extension of the Perl HTML::Template module, which allows for definition of
an external HTML template, to manage the graphical appearance, the layout
and the texts (not including images generated).

This template is located in the 'template' folder and is composed of the
'index.html' file (itself including the 'template/css/main.css' style sheet
and the images contained in the folder 'template/images/').

For more information please consult the documentation for these two modules
here: http://html-template.sourceforge.net/


3/ Add/customize elements
   ----------------------

Notes:

- It is strongly advised when adding elements to base these on an existing
  element rather than starting from zero.

- It is strongly advised that you read the documentation on RDDTool before
  customizing or adding elements. This documentation, as well as tutorials,
  are available on the RRDTool site :
    http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/


/* How it works */
   ------------

   Each element is composed of a folder placed in the 'rrd' directory. This
   folder must contain a creation file ('create.sh'), an update file
   ('update.sh' ou 'update.pl') and a file for the generation of graphs
   ('graph.pm').


/* Folder name */
   -----------

   The name of the folder must be the element ID, possibly preceded by an
   integer and by the character '_'. For example, for an element which one
   wishes to identify by 'cpu', the name of the folder may be 'cpu' or, for
   example, '123_cpu'.

   When the element ID is preceded by an integer this affects/determines
   display order. In fact, the graphs of elements are displayed in
   alphabetical order of folders containing them, and not in the
   alphabetical order of their IDs.


/* Creation: 'create.sh' */
   ---------------------

   The file 'create.sh' is responsible for the creation of the Round Robin
   Database. It is in fact nothing more than a shell file containing an RRD
   creation command. The RRD created must be named 'id.rrd', where 'id' is
   the element ID.

   For various reasons, and notably for reasons of coherence, it is desirable
   to specify the same RRA (Round Robin Archives) and the same step value for
   each of the elements of the application.

   Example:
     Creation of a Round Robin Database corresponding to the 'cpu' element
     and intended for the storage of four DS (Data Sources): 'user',
     'system', 'nice' and 'idle'. 

     #!/bin/bash

     rrdtool create cpu.rrd \
       --start `date +%s` \
       --step 300 \
       DS:user:COUNTER:600:0:U \
       DS:system:COUNTER:600:0:U \
       DS:nice:COUNTER:600:0:U \
       DS:idle:COUNTER:600:0:U \
       RRA:AVERAGE:0.5:1:2016 \
       RRA:AVERAGE:0.5:6:1344 \
       RRA:AVERAGE:0.5:24:732 \
       RRA:AVERAGE:0.5:144:1460


/* Update: 'update.sh' / 'update.pl' */
   ---------------------------------

   The file 'update.sh' is responsible for the updating of the Round Robin
   Database associated to the element. The execution of this script must
   therefore insert in the RRD a new value for all DS (Data Sources) defined
   in the creation file.

   Note that it is possible to replace this 'update.sh' shell file with a
   perl file 'update.pl'. If the first is not found, the second will be
   executed.

   Example:
     Updating of the RRD associated with the 'cpu' element by a perl script

     #!/usr/bin/perl

     $dummy = `cat /proc/stat | grep "^cpu "`;
     $dummy =~ /(.*) (.*) (.*) (.*) (.*)/;

     system("rrdtool update cpu.rrd -t user:system:nice:idle N:$2:$3:$4:$5");


/* Graph generation: 'graph.pm' */
   ----------------------------

   The file 'graph.pm' contains parameters for the display of the graph
   associated with the element. This must include :

   * The graph title, contained in the variable $GRAPH_TITLES{'id'} (where
     'id' is the element ID in single quotes). If {#server#} is present in
     this title it will be substituted by the server name during graph
     generation.

   * A group of parameters that will be transferred to RDDTool during graph
     generation. This group of parameters must be contained in the variable
     $GRAPH_CMDS{'id'} (where 'id' is the element ID in single quotes).

     A certain number of substitutions will be effected among these
     parameters during graph generation.
     See the following list:

     {#server#}    : Server name
     {#path#}      : Element folder path
     {#color1#}    : Draw color 1
     {#color2#}    : Draw color 2
     {#color3#}    : Draw color 3
     {#color4#}    : Draw color 4
     {#color5#}    : Draw color 5
     {#dcolor1#}   : Gradient color 1
     {#dcolor2#}   : Gradient color 2
     {#dcolor3#}   : Gradient color 3
     {#linecolor#} : Lines color

     Note that certain parameters are managed by the application and do not
     require specification here. These parameters are:

     ~ the name of the image file generated
     ~ the type of the image file generated
     ~ the start date of the graph (--start)
     ~ the end date of the graph (--end)
     ~ the graph dimensions (--w and --h)
     ~ graph commentary

   Example :
     'graph.pm' file associated with the 'cpu' element from the preceding examples

     $GRAPH_TITLES{'cpu'} = "{#server#} - CPU Usage";
     $GRAPH_CMDS{'cpu'} = <<"CPU_GRAPH_CMD";
     --title "{#server#} - CPU Usage"
     --vertical-label="Percent"
     --lower-limit 0 --upper-limit 100
     DEF:user={#path#}cpu.rrd:user:AVERAGE
     DEF:system={#path#}cpu.rrd:system:AVERAGE
     DEF:nice={#path#}cpu.rrd:nice:AVERAGE
     DEF:idle={#path#}cpu.rrd:idle:AVERAGE
     CDEF:total=user,system,+,nice,+,idle,+
     CDEF:p_user=user,total,/,100,*
     CDEF:p_system=system,total,/,100,*
     CDEF:p_nice=nice,total,/,100,*
     CDEF:mysum=p_user,p_system,+,p_nice,+
     AREA:p_user{#dcolor1#}:"User   "
     GPRINT:p_user:LAST:"Current\\: %5.2lf%%  "
     GPRINT:p_user:AVERAGE:"Average\\: %5.2lf%%  "
     GPRINT:p_user:MAX:"Max\\: %5.2lf%%\\n"
     STACK:p_system{#dcolor2#}:"System "
     GPRINT:p_system:LAST:"Current\\: %5.2lf%%  "
     GPRINT:p_system:AVERAGE:"Average\\: %5.2lf%%  "
     GPRINT:p_system:MAX:"Max\\: %5.2lf%%\\n"
     STACK:p_nice{#dcolor3#}:"Nice   "
     GPRINT:p_nice:LAST:"Current\\: %5.2lf%%  "
     GPRINT:p_nice:AVERAGE:"Average\\: %5.2lf%%  "
     GPRINT:p_nice:MAX:"Max\\: %5.2lf%%\\n"
     LINE1:mysum{#linecolor#}
     CPU_GRAPH_CMD

     1; # Return true