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= --monport= 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 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 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 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 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 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 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 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 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 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