|
hotsanic |
Subversion Repositories: |
Compare with Previous - Blame - Download
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"><HTML><HEAD><TITLE>HotSaNIC documentation</TITLE></HEAD><BODY bgcolor=#FFFFFF><center><img src="HotSaNIC-small.gif" width=307 height=107 alt="HotSaNIC"><br>HTML overview to System and Network Information Center<br>by Bernd Pissny ( <a href="mailto:hotsanic@bernisys.prima.de">hotsanic@bernisys.prima.de</a> / <a href="http://www.bernisys.prima.de">http://www.bernisys.prima.de</a> )<br><hr><h2>HotSaNIC documentation</h2><table border=0 width=500><tr valign=top><td><br><b>CONTENTS</b><hr noshade><table border=0 cellspacing=5><tr><td>1.</td><td><a href="#descr">description</a><br></td></tr><tr><td>2.</td><td><a href="#req">requirements</a><br></td></tr><tr><td>3.</td><td><a href="#conf">configuration</a><br></td></tr><tr><td>4.</td><td><a href="#run">starting & stopping</a><br></td></tr><tr><td>5.</td><td><a href="#web">web output</a><br></td></tr><tr><td>6.</td><td><a href="#trouble">troubleshooting</a><br></td></tr><tr><td>7.</td><td><a href="#upgrade">upgrading</a><br></td></tr><tr><td>8.</td><td><a href="#tools">tools</a><br></td></tr><tr><td>9.</td><td><a href="#contact">contacting me</a><br></td></tr><tr><td>10.</td><td><a href="#credits">credits</a><br></td></tr><tr><td>11.</td><td><a href="#plans">future plans</a><br></td></tr></table><br><br><a name="descr"><b>DESCRIPTION</b></a><hr noshade>HotSaNIC (the acronym stands for "html overview to system and network information center") consists of a set of perl-scripts built on Tobias Oetiker's "rrdtool" to generate graphical system-statistics, currently supported platforms are linux (main development) and *BSD.<br>I started to build this tool in december 2000, because none of the existing stats-tools gave me the flexibility and resolution i expected. Most tools had a minimum query-time of one minute, while i use a 10sec. timebase, which shows a lot more dynamics in the graphs.<br>The whole project is built in a modular way to make it quite easy to expand, unused modules may be switched off easily.<br>Another advantage over most existing tools is the min/max-area that is drawn behind the average-graphs in many modules - a feature that reflects e.g. min/max bandwidth usage in much more detail than similar tools do.<br>The smallest time span that will be displayed covers the last hour, the longest span diagram covers the last year though all data will be kept for about two years (in order to have the chance to look further back in time and compare).Currently supported data-sources are traffic (local and via SNMP), system's properties like processes/memory/users/loadavg, hdd usage, hdd throughput, ping-times, lm_sensors, #of running copies of given applications, distributed.net statistics, worm-impacts (by analyzing apache-logfiles), APC-USV statistics (load/temperature/charge...), connections to shoutcast streams. More modules are to come on users' requests and ideas.<br>I recently started adding some tools for debugging and to generate alarm-reports (for example if a given threshold is exceeded) which may be mailed to the system's admins.<br><br><br><a name="req"><b>REQUIREMENTS</b></a><hr noshade>Tobias Oetiker's "rrdtool" is needed to let this script work. It is used to manage the databases and generate the graphics. At this point i would like to congratulate Tobi, he did a very good job writing this magnificent tool!<br><br>Since I mainly use Perl5 to sample the data and update the databases, of course this has to be installed on your system. But this should not be an issue since most systems already come with full Perl5 support. But please be sure to install the perl-libraries of "rrdtool" using "make site-perl-install" afer you install "rrdtool."<br><br>"convert" from the "ImageMagick" package has to be installed to get full functionality.<br><br>"iptables" or "ipchains" has to be installed if you want to use the "network" module. Maybe you have to build a new kernel which has the corrosponding firewalling capabilities (packet filter)<br><br><br><a name="conf"><b>CONFIGURATION</b></a><hr noshade>For version 0.3.6 first of all you should run <font color="#c00000">setup.pl</font> to generate the start/stop script (this will be <font color="#c00000">rrdgraph</font>) and the main "settings" file. The setup-script also calls each module's setup script to generate all module-specific settings. After that you should check if the "settings" file in the main directory contains the correct configuration to fit your system. Then you should check the settings files in each module directory and edit the generated "settings" files to fit your system.<br><br>The "settings" files are (well, ok, at least they should be) quite self-explaining, so i guess it isn't needed to explain them here - though some day I might list every single module on this page along with a short explanation of what they do and which features they have.<br><br><br><a name="run"><b>STARTING AND STOPPING THE DAEMON</b></a><hr noshade>To run the auto-update daemon the best thing would be to get yourself root-permissions and enter:<br><br><font color="#c00000">./rrdgraph start</font><br><br>rrdgraph will begin sampling data vor every plugin installed every 10 seconds.<br><br>To stop the daemon enter<br><br><font color="#c00000">./rrdgraph stop</font><br><br>Most modules will run as non-root, too, but if you want full functionality it is absolutely necessary to let the whole thing run as root. For example the PING module uses ICMP stuff that is only working if you are running it as root.<br><br><a name="web"><b>GENERATING WEB-STATISTICS</b></a><hr noshade>Well, you should not have to worry about anything except the output-directory which has to be configured correctly (you will have to enter the full path!) in the main settings file.<br><br>The images on the statistics pages will be built automatically by HotSaNIC every configured timespan (which will be 15min. by default) If you like to build the graphs more often, you are welcome to decrease the time-base as you like by editing the main settings file. But be sure that decreasing the time-span will eat up more CPU time (which may be needed for more important tasks ... ).<br><br>To build the index.html files just start <font color="#c00000">makeindex.pl</font> and all shall be well. The script will gather every plugin-directory and build the necessary index-files for your webpage. In case you install a new plugin, just let HotSaNIC run a couple of minutes inititalize the plugin's databases. Then you just call <font color="#c00000">makeindex.pl</font> again and it will do the rather nasty update-job for you. New plugins can be installed on the fly, the only thing to do is to copy the module-directory to the main directory and maybe you have to add the new module to the RUN and SHOW entries in the main settings.<br><br>If you use the "traffic" plugin, please let rrdgraph run at least some 30 seconds to allow the plugin to scan your local interfaces before you run the index-maker.<br><br>"rrdtimer" will call "convert.sh" about every 24h (timebase may be configured in main settings file). This script will generate pictograms on the main index page of your webstats from the actual weekly graphs.<br><br>This will require "convert" from "ImageMagick" to be installed.It is used to resize the weekly graph images.<br><br><br><a name="trouble"><b>TROUBLESHOOTING</b></a><hr noshade><ul type=disc><li><b>How do I solve the "cannot find "RRDs.pm" issue?</b><hr size=1>You probably forgot to install the site-perl module of rrdtool.<br><br>If you installed rrdtool from the source files, you just have to do a<br><br><font color="#c00000">make site-perl-install</font><br><br>If you used a .rpm package, you should check if the RRDs.pm has been installed in the correct places. maybe you used an RPM package which didn't really fit your installation - some pathes may have changed.<br><br>Or maybe you upgraded PERL, then you also may have to adapt the modules' pathes.<br><br><li><b>ping module is not working</b><hr size=1>On some systems the PERL header-files may be missing. This results in the ping-module complaining about something like<br><br>"Can't locate sys/syscall.ph in @INC (did you run h2ph?)"<br><br>Linux distributions known to be affected are for example "RedHat 7.2" and "Slackware"<br><br>The solution would be to do (as root) the following:<br><br><font color="#c00000">cd /usr/include<br>find . -name '*.h' -print | xargs h2ph</font><br><br>After that everything should run as expected. - hopefully ;)<br><br><li><b>the graphs don't show up</b><hr size=1>Maybe you just started the daemon. in that case let it run for some minutes to let the databases be created and filled. Then you may run the "diagrams" script in the main directory to generate the graphs. This is done by the daemon automatically every DTIME (found in the main settings)<br>If just the small graphs on the main page don't show, you have to run "convert.pl" (or "convert.sh") in order to create the thumbnail images. This is done every CTIME.<br><br><li><b>the thumbnails on the main page are not updating or still don't exist</b><hr size=1>Maybe you upgraded to v0.3.6 or later ?<br>In the later snapshots of this version the thumbnails moved from the main web-dir to the module subdirs to enhance the overview a bit. You have to call the main "makeindex.pl" to update the html pages once again.<br><br><li><b>after i compiled the scripts some modules fill the logfiles with errors</b><hr size=1>At the moment there is no other way than removing the binaries. I had such strange effects on some systems myself, but I don't know why the binaries behave that way. The compiling completes without any errors, but the binaries won't start properly like the .pl scripts do.<br><br><br><br><a name="upgrade"><b>UPGRADING</b></a><hr noshade>Generally the upgrade process involves the following actions:<br><ul type="disc"><li>stop the daemon<li>copy the new files over the existing ones<li>call the main setup script<li>call each module's update script (if exists)<li>re-start the daemon</ul>However, if you intend to upgrade your HotSaNIC installation, you should check the HotaNIC homepage firt to make sure wich additional steps have to be performed. Maybe you have to check the history as well, in case you update from a very old version.<br>Usually updates run quite smoothly without any further changes. You should do as described above: Stop the daemon first to make sure that no data will be fed into the databases which may lead to some annoying side-effects. Then copy the new files to the corrosponding directories. If some major changes occur, there will be an update script in the affected module which you will have to call. The script will take care the necessary and sometimes really nasty modifications for you.<br>Anyway, if you copy a newer version over a previous one, it's always a good idea to call the main setup script once again. Maybe some new important configuration items have been added since you last upgraded or installed the tool!<br>Oh, and don't forget to re-start the daemon afterwards ;).<br><br><br><a name="tools"><b>TOOLS</b></a><hr noshade>Since version 0.4.0 I added a directory containing some possibly useful scripts and add-ons for HotSaNIC.<br>A brief description resides in this directory, some further descriptions may appear in this documentation later.<br><br>One nifty thing has to be mentioned:<br>The modules may be compied in order to start up a bit faster. This will save some percent of your valuable CPU time, but it may not run on every machine! Unhappily the behaviour of the binaries is beyond my control. In most cases they run as smoothly as the perl-scripts, but up to three times faster, sometimes they fill the error-log and sometimes they won't even compile. Only thing you can do is to give it a try and remove all binaries which cause problems.<br><br>The compilation process is quite easy: Just call the "compile" script in the main directory - that's all.<br>A whole load of compiler information will scroll down your screen for quite a while. During the (hopefully successful) compiling process, your daemon will automatically start to call the binaries instead of the scripts. These are named "read-data" (without the .pl suffix). This allows to compile while the daemon is already running.<br>The compile script has some useful options:<br><ul type="disc"><li>"compile r" forces the re-compiling of all modules - no matter if they are already compiled or not.<li>"compile u" removes all binaries, leaving just the scripts again.<li>"compile c" checks if any modules have to be re-compiled (does not change anything, just lists them)<li>"compile <modulename>" compiles precisely not more the given module (the prefix "data-" may be omitted).</ul><br><br><a name="contact"><b>CONTACT</b></a><hr noshade>If you encounter further problems or have any questions or new ideas, please contact us at <a href="mailto:hotsanic@bernisys.prima.de">hotsanic@bernisys.prima.de</a>, we will try to take care of everything. It would be a good idea to put the keyword "hotsanic" and a brief description of your request into the subject to make sure i find your mails again in case we need them later on.<br><br>If you already have a solution for a problem you encountered, please attach the working code or the modifications you made. A proper description of your problem and the changes you made would be very helpful.<br><br>Same goes for extensions ideas and support for systems other than Linux.<br><br><br><a name="credits"><b>CREDITS</b></a><hr noshade>At this point i'd like to thank and honor some people who support(ed) me and my project:<ul type=disc><li>Matt Burke and Peter Reich, who are heavily involved in getting all functions running on BSD systems !<li>Todd Underwood, who managed to create some RPMs !<li>All my trusted friends for being appreciative of my hacking till late in the night ! ;)<li>Everybody who sent me hints, new ideas, extensions and bug-reports.</ul><br><br><a name="plans"><b>FUTURE PLANS</b></a><hr noshade>I intend to convert the whole shell-script crap to a PERL script which will run very much faster and therefore does not generate unnecessary system-overhead. This is already done for the data-sampling scripts and the index generation. TODO: diagrams<br><br>I would like to implement more SMNP features not only for the traffic module (as far as possible of course).<br><br>In case you have written your own plug-in and you find it useful, be sure to e-mail me a .tgz of your module and include a short description. Same goes for reporting bugs of course!<br><br>Thank you!<br></td></tr></table></center><br><HR><center><img src="/gif/apache_pb.gif"></center></BODY></HTML>