|
hotsanic |
Subversion Repositories: |
Compare with Previous - Blame - Download
HotSaNICHTML overview to System and Network Information Centerby Bernd Pissny ( hotsanic@bernisys.prima.de / http://www.bernisys.prima.de )----------------------------------------------------------------------HotSaNIC documentationCONTENTS-------------------------------------------------------------------1. description2. requirements3. configuration4. starting & stopping5. web output6. troubleshooting7. upgrading8. tools9. contacting me10. credits11. future plansDESCRIPTION-------------------------------------------------------------------HotSaNIC (the acronym stands for "html overview to system and networkinformation center") consists of a set of perl-scripts built on TobiasOetiker's "rrdtool" to generate graphical system-statistics, currentlysupported platforms are linux (main development) and *BSD.I started to build this tool in december 2000, because none of theexisting 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.The whole project is built in a modular way to make it quite easy toexpand, unused modules may be switched off easily.Another advantage over most existing tools is the min/max-area that isdrawn behind the average-graphs in many modules - a feature thatreflects e.g. min/max bandwidth usage in much more detail than similartools do.The smallest time span that will be displayed covers the last hour, thelongest span diagram covers the last year though all data will be keptfor about two years (in order to have the chance to look further backin time and compare). Currently supported data-sources are traffic(local and via SNMP), system's properties likeprocesses/memory/users/loadavg, hdd usage, hdd throughput, ping-times,lm_sensors, #of running copies of given applications, distributed.netstatistics, worm-impacts (by analyzing apache-logfiles), APC-USVstatistics (load/temperature/charge...), connections to shoutcaststreams. More modules are to come on users' requests and ideas.I recently started adding some tools for debugging and to generatealarm-reports (for example if a given threshold is exceeded) which maybe mailed to the system's admins.REQUIREMENTS-------------------------------------------------------------------Tobias Oetiker's "rrdtool" is needed to let this script work. It isused to manage the databases and generate the graphics. At this point iwould like to congratulate Tobi, he did a very good job writing thismagnificent tool!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 notbe 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.""convert" from the "ImageMagick" package has to be installed to getfull functionality."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 thecorrosponding firewalling capabilities (packet filter)CONFIGURATION-------------------------------------------------------------------For version 0.3.6 first of all you should run setup.pl to generate thestart/stop script (this will be rrdgraph) and the main "settings" file.The setup-script also calls each module's setup script to generate allmodule-specific settings. After that you should check if the "settings"file in the main directory contains the correct configuration to fityour system. Then you should check the settings files in each moduledirectory and edit the generated "settings" files to fit your system.The "settings" files are (well, ok, at least they should be) quiteself-explaining, so i guess it isn't needed to explain them here -though some day I might list every single module on this page alongwith a short explanation of what they do and which features they have.STARTING AND STOPPING THE DAEMON-------------------------------------------------------------------To run the auto-update daemon the best thing would be to get yourselfroot-permissions and enter:./rrdgraph startrrdgraph will begin sampling data vor every plugin installed every 10seconds.To stop the daemon enter./rrdgraph stopMost modules will run as non-root, too, but if you want fullfunctionality it is absolutely necessary to let the whole thing run asroot. For example the PING module uses ICMP stuff that is only workingif you are running it as root.GENERATING WEB-STATISTICS-------------------------------------------------------------------Well, you should not have to worry about anything except theoutput-directory which has to be configured correctly (you will have toenter the full path!) in the main settings file.The images on the statistics pages will be built automatically byHotSaNIC every configured timespan (which will be 15min. by default) Ifyou like to build the graphs more often, you are welcome to decreasethe time-base as you like by editing the main settings file. But besure that decreasing the time-span will eat up more CPU time (which maybe needed for more important tasks ... ).To build the index.html files just start makeindex.pl and all shall bewell. The script will gather every plugin-directory and build thenecessary index-files for your webpage. In case you install a newplugin, just let HotSaNIC run a couple of minutes inititalize theplugin's databases. Then you just call makeindex.pl again and it willdo the rather nasty update-job for you. New plugins can be installed onthe fly, the only thing to do is to copy the module-directory to themain directory and maybe you have to add the new module to the RUN andSHOW entries in the main settings.If you use the "traffic" plugin, please let rrdgraph run at least some30 seconds to allow the plugin to scan your local interfaces before yourun the index-maker."rrdtimer" will call "convert.sh" about every 24h (timebase may beconfigured in main settings file). This script will generate pictogramson the main index page of your webstats from the actual weekly graphs.This will require "convert" from "ImageMagick" to be installed. It isused to resize the weekly graph images.TROUBLESHOOTING-------------------------------------------------------------------o How do I solve the "cannot find "RRDs.pm" issue?-------------------------------------------------------------------You probably forgot to install the site-perl module of rrdtool.If you installed rrdtool from the source files, you just have to doamake site-perl-installIf you used a .rpm package, you should check if the RRDs.pm hasbeen installed in the correct places. maybe you used an RPM packagewhich didn't really fit your installation - some pathes may havechanged.Or maybe you upgraded PERL, then you also may have to adapt themodules' pathes.o ping module is not working-------------------------------------------------------------------On some systems the PERL header-files may be missing. This resultsin the ping-module complaining about something like"Can't locate sys/syscall.ph in @INC (did you run h2ph?)"Linux distributions known to be affected are for example "RedHat7.2" and "Slackware"The solution would be to do (as root) the following:cd /usr/includefind . -name '*.h' -print | xargs h2phAfter that everything should run as expected. - hopefully ;)o the graphs don't show up-------------------------------------------------------------------Maybe you just started the daemon. in that case let it run for someminutes to let the databases be created and filled. Then you mayrun the "diagrams" script in the main directory to generate thegraphs. This is done by the daemon automatically every DTIME (foundin the main settings)If just the small graphs on the main page don't show, you have torun "convert.pl" (or "convert.sh") in order to create the thumbnailimages. This is done every CTIME.o the thumbnails on the main page are not updating or still don'texist-------------------------------------------------------------------Maybe you upgraded to v0.3.6 or later ?In the later snapshots of this version the thumbnails moved fromthe main web-dir to the module subdirs to enhance the overview abit. You have to call the main "makeindex.pl" to update the htmlpages once again.o after i compiled the scripts some modules fill the logfiles witherrors-------------------------------------------------------------------At the moment there is no other way than removing the binaries. Ihad such strange effects on some systems myself, but I don't knowwhy the binaries behave that way. The compiling completes withoutany errors, but the binaries won't start properly like the .plscripts do.UPGRADING-------------------------------------------------------------------Generally the upgrade process involves the following actions:o stop the daemono copy the new files over the existing oneso call the main setup scripto call each module's update script (if exists)o re-start the daemonHowever, if you intend to upgrade your HotSaNIC installation, youshould check the HotaNIC homepage firt to make sure wich additionalsteps have to be performed. Maybe you have to check the history aswell, in case you update from a very old version.Usually updates run quite smoothly without any further changes. Youshould do as described above: Stop the daemon first to make surethat no data will be fed into the databases which may lead to someannoying side-effects. Then copy the new files to the corrospondingdirectories. If some major changes occur, there will be an updatescript in the affected module which you will have to call. Thescript will take care the necessary and sometimes really nastymodifications for you.Anyway, if you copy a newer version over a previous one, it'salways a good idea to call the main setup script once again. Maybesome new important configuration items have been added since youlast upgraded or installed the tool!Oh, and don't forget to re-start the daemon afterwards ;).TOOLS-------------------------------------------------------------------Since version 0.4.0 I added a directory containing some possiblyuseful scripts and add-ons for HotSaNIC.A brief description resides in this directory, some furtherdescriptions may appear in this documentation later.One nifty thing has to be mentioned:The modules may be compied in order to start up a bit faster. Thiswill save some percent of your valuable CPU time, but it may notrun on every machine! Unhappily the behaviour of the binaries isbeyond my control. In most cases they run as smoothly as theperl-scripts, but up to three times faster, sometimes they fill theerror-log and sometimes they won't even compile. Only thing you cando is to give it a try and remove all binaries which causeproblems.The compilation process is quite easy: Just call the "compile"script in the main directory - that's all.A whole load of compiler information will scroll down your screenfor quite a while. During the (hopefully successful) compilingprocess, your daemon will automatically start to call the binariesinstead of the scripts. These are named "read-data" (without the.pl suffix). This allows to compile while the daemon is alreadyrunning.The compile script has some useful options:o "compile r" forces the re-compiling of all modules - no matterif they are already compiled or not.o "compile u" removes all binaries, leaving just the scriptsagain.o "compile c" checks if any modules have to be re-compiled (doesnot change anything, just lists them)o "compile " compiles precisely not more the given module (theprefix "data-" may be omitted).CONTACT-------------------------------------------------------------------If you encounter further problems or have any questions or newideas, please contact us at hotsanic@bernisys.prima.de, we will tryto take care of everything. It would be a good idea to put thekeyword "hotsanic" and a brief description of your request into thesubject to make sure i find your mails again in case we need themlater on.If you already have a solution for a problem you encountered,please attach the working code or the modifications you made. Aproper description of your problem and the changes you made wouldbe very helpful.Same goes for extensions ideas and support for systems other thanLinux.CREDITS-------------------------------------------------------------------At this point i'd like to thank and honor some people whosupport(ed) me and my project:o Matt Burke and Peter Reich, who are heavily involved ingetting all functions running on BSD systems !o Todd Underwood, who managed to create some RPMs !o All my trusted friends for being appreciative of my hackingtill late in the night ! ;)o Everybody who sent me hints, new ideas, extensions andbug-reports.FUTURE PLANS-------------------------------------------------------------------I intend to convert the whole shell-script crap to a PERL scriptwhich will run very much faster and therefore does not generateunnecessary system-overhead. This is already done for thedata-sampling scripts and the index generation. TODO: diagramsI would like to implement more SMNP features not only for thetraffic module (as far as possible of course).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 shortdescription. Same goes for reporting bugs of course!Thank you!----------------------------------------------------------------------