HotSaNIC
HTML overview to System and Network Information Center
by Bernd Pissny ( hotsanic@bernisys.prima.de / http://www.bernisys.prima.de )

HotSaNIC documentation


CONTENTS
1.requirements
2.configuration
3.starting & stopping
4.web output
5.troubleshooting
6.upgrading
7.contacting me
8.credits
9.future plans


REQUIREMENTS
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!

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."

"convert" from the "ImageMagick" package has to be installed to get full 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 the corrosponding firewalling capabilities (packet filter)


CONFIGURATION
For version 0.3.6 first of all you should run setup.pl to generate the start/stop script (this will be rrdgraph) and the main "settings" file. The setup-script also calle 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.

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.


STARTING AND STOPPING THE DAEMON
To run the auto-update daemon the best thing would be to get yourself root-permissions and enter:

./rrdgraph start

rrdgraph will begin sampling data vor every plugin installed every 10 seconds.

To stop the daemon enter

./rrdgraph stop

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.

GENERATING WEB-STATISTICS
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.

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 ... ).

To build the index.html files just start makeindex.pl 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 makeindex.pl 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.

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.

"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.

This will require "convert" from "ImageMagick" to be installed. It is used to resize the weekly graph images.


TROUBLESHOOTING
  • ping module is not working
    On some systems the PERL header-files may be missing. This results in 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 "RedHat 7.2" and "Slackware"

    The solution would be to do (as root) the following:

    cd /usr/include
    find . -name '*.h' -print | xargs h2ph


    After that everything should run as expected. - hopefully ;)

  • the graphs don't show up
    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)
    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.

  • the thumbnails on the main page are not updating or still don't exist
    Maybe you upgraded to v0.3.6 or later ?
    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.

  • after i compiled the scripts some modules fill the logfiles with errors
    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 behaves in that way. Compiling went without any errors, but ithe binaries the won't start properly like the .pl scripts do.



    UPGRADING
    If you are upgrading your HotSaNIC version, you should check the HotaNIC homepage, if you have to run any scripts in order to update some databases (maybe you have to check the history when you update from a very old version).
    Usually the updates run quite smoothly without any further changes. You should just stop the daemon before upgrading and don't forget to re-start it afterwards ;).


    CONTACT
    If you encounter any further problems, please contact me, I will try to take care of them. To make sure i your mail fastest possible, please put the keyword "hotsanic" somewhere into the subject.

    If you already have a solution for a problem you encountered, please put it in your mail and/or attach the working code and a small description!

    Same goes for extensions ideas and support for systems other than Linux.


    CREDITS
    At this point i'd like to thank and honor some people who support(ed) me and my project:
    • Matt Burke and Peter Reich, who are heavily involved in getting all functions running on BSD systems !
    • Todd Underwood, who managed to create RedHat RPMs of all my work !
    • All my trusted friends for being appreciative of my hacking till late in the night ! ;)


    FUTURE PLANS
    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

    I would like to implement SMNP features as well, my work-version already has this (rudimentary) in the traffic module. It's quite usable and i would like to implement it in other omdules as well (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 the directory-tree and include a short description. Same goes for reporting bugs of course!

    Thank you!