NAME
rrdmon - generate rrd bases from a remote mon server
OVERVIEW
RRDMON is a tool to graph the service statuses reported by MON, using
RRDTOOL. rrdmon collects the data by the network, creates or updates the
rrd bases and generates dynamic, good and meaningful graphical web
pages.
All was made to avoid configuration work.
FEATURES
* Keeps the database in a fixed size, thanks to RRDTOOL.
* Generates different graphics to scale years, months, weeks, days and
hours statistics or any other period.
* Minimalize the configuration. In fact, in most of the cases, no
configuration is needed at all. Information is searched on the fly.
If the configuration MON server changes then RRDMON changes too, but
it keeps the old statistics.
* The data granularity is taken from the MON server. If a monitor is run
every 3 minutes, rrdmon will query the server every 3 minutes for
that service. It will input the data to rrdtool just one time per
interval.
* The graphics are created by a command line or on demand by a web
interface. The graphics are only generated when it worth to do it.
STARTING
All was made to avoid configuration work.
For the lazy joe
Get MON and RRDTOOL, install them. Run a MON server on localhost, port
2583. untar the RRDMON archive where you want.
Create a directory where you want to stand rrdmon data (images, cgi
scripts, rrd databases). Choose a place exported by a web server, for
example /usr/local/apache/htdocs/rrdmon/, if you want rrdmon be visible
by others (you do, no?). Go in that directory and type:
rrdmon
This will create 3 directories named cgi-bin/, images/, and rrdbases/.
If any problem occurs, rrdmon will complain on STDOUT or STDERR,
depending on the problem. When there is no problem, rrdmon mutes (UNIX
or chinese philosophy, if what you want to say is not better than the
silence, keep quiet).
If your MON server is not Localhost on port 2583 you can try:
rrdmon --monserver=<hostname> --monport=<port>
You can safely type (and read):
rrdmon --help
Go in the cgi-bin/ directory and type:
echo | ./Localhost+2583+7200.cgi
If there is no file, you are unlucky. Go to the next section. The png
images (gif creations are uglyly patented, sorry) are created in the
images/ directory. See them with a graphic tool (GIMP is good but so is
Lynx).
That is all folks. Have fun.
For the webmaster joe
Set you web server (Apache is good) to map .cgi extension with the cgi
handler, or make directory cgi-bin/ become a cgi-bin directory. In other
words, tell your web server that uppon client request, do not give the
file itself but run it and give the stdout result to the client.
Plus, the cgi user must have write permissions on the directory images/.
The default cgi user is 'nobody'. So perhaps you will need a command
like:
chown nobody.nobody images/
or a less secure one (not so bad if PUT HTTP request is not allowed in
the images/ directory, which is the default):
chmod a+w images/
If the cgi user is not 'nobody', adjust the previous command with yours.
If you do not understand what I am talking about, you should give up
this reading, learn a bit about HTTP and CGI and come back. Let us go
on, I speak too much.
Run a web browser (Lynx is so cute for this job) and try one of the cgi
scripts, by just going on the url you chose to map rrdmon, for example
http://localhost/rrdmon/cgi-bin/. If you can see some beautifull
pictures then you are lucky.
Now, run rrdmon for eternity :
rrdmon --noend
That is all folks. Have fun.
what can I do safely?
* run :
rrdmon --help
* remove the images.
rm images/*
* remove the cgi scripts.
rm cgi-bin/*
* kill rrdmon with Ctrl-C or Ctrl-\
killall rrdmon
what can I do unsafely?
* remove the rrd bases. You will loose your data.
* cross the road in England.
For the unlucky joe
If you are unluky with the previous setup or if you disagree with the
default configuration, read on. You can configure rrdmon with several
options.
--topdir <directory> Where is the top directory ?
This directory is the base with which all default paths will be prepend.
Default is "./"
rrdmon --topdir=/usr/local/apache/htdocs/rrdmon \
--imagedirforweb=/rrdmon/images
--cgidir <directory> Where will go the cgi scripts in the local
filesystem ?
use the --cgidir option. By default, it is <--topdir>/cgi-bin I do not
think it will be a good value for you. if <--cgidir> begins with a slash
("/") then this path is absolute, else it is relative to <--topdir>.
rrdmon have to havethe write permission on this directory. Example :
rrdmon --topdir=/usr/local/apache/htdocs/rrdmon \
--cgidir=/usr/local/apache/cgi-bin \
--imagedirforweb=/rrdmon/images
--rrdcgi <path> What is the rrdcgi complete name (including its name) ?
use the --rrdcgi option. RRDMON needs it to add the shebang line in the
cgi scripts. The shebang line tells the UNIX system how to interpret the
code (#!/usr/local/bin/rrdcgi). Example :
rrdmon --rrdcgi=/usr/local/bin/rrdcgi
--topdirforcgi <directory> Where is the top directory for the cgi
scripts ?
If the --topdir option is absolute, ie it begins with "/", you do not
need this option.
rrdmon --topdir=./foo \
--topdirforcgi=../
--rrddir <directory> Where will go the rrd databases ?
rrdmon uses this directory to store the round robin databases. By
default, it is <--topdir>/rrdbases use the --rrddir option to set this
directory. relative path is appended to <--topdir>.
Example :
rrdmon --rrddir=/usr/local/apache/htdocs/rrdmon/rrdbases
--rrddirforcgi <directory> Where will go the rrd databases ?
No, this is not a copy and paste mistake. In fact a problem occurs in
you use a relative path for the --rrddir option. The cgi scripts can not
guess where the rrdbases files are. So there is this silly option.
Is is the path used by the cgi scripts. By default, it is <--
topdirforcgi>/rrdbases If you give an absolute path then it is an
absolute path, else it is relative to <--topdirforcgi>. Most of the
times, the web server does a chroot in the directory where is the cgi
script, before running it; so you can give a relative path from the cgi
directory.
Example :
rrdmon --rrddirforcgi=../rrdbases
--imagedir <directory> Where will go the images ?
use the --imagedir option to set this directory. By default, it is it is
<--topdir>/images You can give a relative path (appended to <--topdir>
option) or an absolute one. The user id used by your web server to run
the cgi scripts must have write permissions in this directory.
Example :
rrdmon --imagedir=/usr/local/apache/htdocs/rrdmon/images
--imagedircgi <directory> Where will go the images ?
You know the story now. use the --imagedirforcgi option to set this
directory. By default, it is <--topdirforcgi>/images You can give a
relative path (appended to <--topdirforcgi>) or an absolute one.
Example :
rrdmon --imagedircgi=../images
--imagedirweb <directory> Where will go the images ?
This is not a joke. The story gets complicated. The web user accesses
the images by a different path, sometimes. use the --imagedirweb option
to set this directory. By default, it is <--imagedircgi> option. Example
:
rrdmon --imagedirweb=../images
LINKS
RRDMON can be found at : ftp://ftp.linux-france.org/pub/prj/minotaure/
MON can be found at : http://www.kernel.org/software/mon/ The Linux
kernel is also there because of Benedict, Jim, and Transmeta.
RRDTOOL can be found at http://ee-
staff.ethz.ch/~oetiker/webtools/rrdtool/
PERL can be found at http://www.perl.com
LITERATE PROGRAMING
From here the documentation is not up to date since it is not up at all.
I could not get Knut's book, out of print. 'quote for nedit. Prefer to
see the ugly code :-)
GET OPTIONS
I know that the variables names are often too long. I like that. It
makes very difficult to keep the code in 80 columns. Nobody has never
complain nor patch anything, nobody cares.
If you add an option, please update the usage() function AND the default
behavior AND the debugOption output. Thanks.
MON CONNECTION
We connect the MON server to ask it its local time, the operationnal
status of every services.
CREATE AND UPDATE RRD BASES
We look at the rrddir directory to see if there is already the
databases. If databases are missing we create them and we create the
different entries for generating the graphics.
By default four graphics are made, like in MRTG but you can override
this behavior. 1 day is 86400 secondes. Graphics are :
2 hours are 2 * 60 min = 7200 s
2 days are 2 * 1 day = 172800 s
2 weeks are 14 * 1 day = 1209600 s
2 months are 62 * 1 day = 5356800 s
1 year is 366 * 1 day = 31622400 s
20 years are 20 * 365 days = 630720000 s