| 1 | 1 | simandl | <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> |
| 2 | | | <HTML> |
| 3 | | | <HEAD> |
| 4 | | | <TITLE>HotSaNIC documentation</TITLE> |
| 5 | | | </HEAD> |
| 6 | | | |
| 7 | | | <BODY bgcolor=#FFFFFF> |
| 8 | | | |
| 9 | | | <center> |
| 10 | | | <img src="HotSaNIC-small.gif" width=307 height=107 alt="HotSaNIC"><br> |
| 11 | | | HTML overview to System and Network Information Center<br> |
| 12 | | | 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> |
| 13 | | | <hr> |
| 14 | | | <h2>HotSaNIC documentation</h2> |
| 15 | | | <table border=0 width=500><tr valign=top><td> |
| 16 | | | <br> |
| 17 | | | <b>CONTENTS</b><hr noshade> |
| 18 | | | <table border=0 cellspacing=5> |
| 19 | | | <tr><td>1.</td><td><a href="#descr">description</a><br></td></tr> |
| 20 | | | <tr><td>2.</td><td><a href="#req">requirements</a><br></td></tr> |
| 21 | | | <tr><td>3.</td><td><a href="#conf">configuration</a><br></td></tr> |
| 22 | | | <tr><td>4.</td><td><a href="#run">starting & stopping</a><br></td></tr> |
| 23 | | | <tr><td>5.</td><td><a href="#web">web output</a><br></td></tr> |
| 24 | | | <tr><td>6.</td><td><a href="#trouble">troubleshooting</a><br></td></tr> |
| 25 | | | <tr><td>7.</td><td><a href="#upgrade">upgrading</a><br></td></tr> |
| 26 | | | <tr><td>8.</td><td><a href="#tools">tools</a><br></td></tr> |
| 27 | | | <tr><td>9.</td><td><a href="#contact">contacting me</a><br></td></tr> |
| 28 | | | <tr><td>10.</td><td><a href="#credits">credits</a><br></td></tr> |
| 29 | | | <tr><td>11.</td><td><a href="#plans">future plans</a><br></td></tr> |
| 30 | | | </table> |
| 31 | | | <br> |
| 32 | | | <br> |
| 33 | | | <a name="descr"><b>DESCRIPTION</b></a><hr noshade> |
| 34 | | | 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> |
| 35 | | | 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> |
| 36 | | | The whole project is built in a modular way to make it quite easy to expand, unused modules may be switched off easily.<br> |
| 37 | | | Another advantage over most existing tools are the very complex graphs which show a lot more details. Most graphs are underlayed with an area that covers the min/max range of samples taken at each time.<br> |
| 38 | | | Quite all important system-stats are supported, more modules are to come on users' requests and ideas.<br> |
| 39 | | | 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 (to have the chance to look further back in time and compare).<br> |
| 40 | | | Additionally there are 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> |
| 41 | | | <br> |
| 42 | | | <br> |
| 43 | | | <a name="req"><b>REQUIREMENTS</b></a><hr noshade> |
| 44 | | | Tobias Oetiker's "rrdtool" is needed to run this set of scripts. It is used to manage the databases and generate the graphics. Make sure that the "rrdtool" perl-libraries are installed on your system!<br> |
| 45 | | | At this point i would like to congratulate Tobi, he did a very good job writing this magnificent tool!<br> |
| 46 | | | <br> |
| 47 | | | Since I mainly use Perl5 to sample the data and update the databases, of course this has to be installed on your system, too. But this should not be an issue since most systems already come with full Perl5 support.<br> |
| 48 | | | <br> |
| 49 | | | "convert" from the "ImageMagick" package has to be installed to get full functionality.<br> |
| 50 | | | <br> |
| 51 | | | Some modules require further tools or kernel features to be present. Please refer to the module documentations for more information.<br> |
| 52 | | | <br> |
| 53 | | | <br> |
| 54 | | | <a name="conf"><b>CONFIGURATION</b></a><hr noshade> |
| 55 | | | All you should need to do for configuring is running <font color="#c00000">setup.pl</font> to generate the start/stop script (called <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 within the module's subdirectory. After that you should check if the "settings" file in the main directory contains the correct configuration to fit your system. After that you should check the ""settings" files in each configured module's directory and edit it to fit your system.<br> |
| 56 | | | There are plenty of comments into the "settings" files, so they should be quite self-explaining.<br> |
| 57 | | | <br> |
| 58 | | | <br> |
| 59 | | | <a name="run"><b>STARTING AND STOPPING THE DAEMON</b></a><hr noshade> |
| 60 | | | Since there are some datasources only the "root" user has access to, best would be to run it as "root". This is simply dome by getting yourself root-permissions and typing:<br> |
| 61 | | | <br> |
| 62 | | | <font color="#c00000">./rrdgraph start</font><br> |
| 63 | | | <br> |
| 64 | | | rrdgraph will then begin to initialize itself and to sample data vor each configured module every 10 seconds.<br> |
| 65 | | | <br> |
| 66 | | | To stop the daemon enter<br> |
| 67 | | | <br> |
| 68 | | | <font color="#c00000">./rrdgraph stop</font><br> |
| 69 | | | <br> |
| 70 | | | <br> |
| 71 | | | <a name="web"><b>GENERATING WEB-STATISTICS</b></a><hr noshade> |
| 72 | | | The images on the statistics pages will be built automatically by HotSaNIC every 15 minutes. If you like to build the graphs more ore less often, you are welcome to decrease or increas the time-base as you like by editing the main settings file. But be careful with too low timespans, because it will use more CPU time (which may be needed for more important tasks ... ).<br> |
| 73 | | | <br> |
| 74 | | | Usually 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> |
| 75 | | | <br> |
| 76 | | | If not yet done, run <font color="#c00000">makeindex.pl</font> to generate all html files. The script will gather every module and build the necessary index-files for your webpage. In case you install a new module, just let HotSaNIC run a couple of minutes to inititalize the plugin's databases. Then you just call <font color="#c00000">makeindex.pl</font> again and it will rebuild all html files. New plugins can be installed quite "on the fly". Just copy it to the "modules" directory and add it to the RUN and SHOW entries in the main settings.<br> |
| 77 | | | <br> |
| 78 | | | <br> |
| 79 | | | "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.<br> |
| 80 | | | <br> |
| 81 | | | <br> |
| 82 | | | <a name="trouble"><b>TROUBLESHOOTING</b></a><hr noshade> |
| 83 | | | In case you encounter any trouble with HotSaNIC, you should check the logfiles for possible errors.<br> |
| 84 | | | Each "settings" file may contain an item "DEBUGLEVEL=<level>" which changes the logging behaviour. Increasing the value will usually increase verbosity, a value less than zero turns off all special information.<br> |
| 85 | | | <ul type=disc> |
| 86 | | | <li><b>How do I solve the "cannot find "RRDs.pm" issue?</b><hr size=1> |
| 87 | | | You probably forgot to install the site-perl module of rrdtool.<br> |
| 88 | | | <br> |
| 89 | | | If you installed rrdtool from the source files, you just have to do a<br> |
| 90 | | | <br> |
| 91 | | | <font color="#c00000">make site-perl-install</font><br> |
| 92 | | | <br> |
| 93 | | | 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> |
| 94 | | | <br> |
| 95 | | | Or maybe you upgraded PERL, then you also may have to adapt the modules' pathes.<br> |
| 96 | | | <br> |
| 97 | | | <li><b>ping module is not working</b><hr size=1> |
| 98 | | | On some systems the PERL header-files may be missing. This results in the ping-module complaining about something like<br> |
| 99 | | | <br> |
| 100 | | | "Can't locate sys/syscall.ph in @INC (did you run h2ph?)"<br> |
| 101 | | | <br> |
| 102 | | | Linux distributions known to be affected are for example "RedHat 7.2" and "Slackware"<br> |
| 103 | | | <br> |
| 104 | | | The solution would be to do (as root) the following:<br> |
| 105 | | | <br> |
| 106 | | | <font color="#c00000">cd /usr/include<br> |
| 107 | | | find . -name '*.h' -print | xargs h2ph</font><br> |
| 108 | | | <br> |
| 109 | | | After that everything should run as expected. - hopefully ;)<br> |
| 110 | | | <br> |
| 111 | | | <li><b>the graphs don't show up</b><hr size=1> |
| 112 | | | 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> |
| 113 | | | 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> |
| 114 | | | <br> |
| 115 | | | <li><b>the thumbnails on the main page are not updating or still don't exist</b><hr size=1> |
| 116 | | | Maybe you upgraded to v0.3.6 or later ?<br> |
| 117 | | | 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> |
| 118 | | | </ul> |
| 119 | | | <br> |
| 120 | | | <br> |
| 121 | | | <br> |
| 122 | | | <a name="upgrade"><b>UPGRADING</b></a><hr noshade> |
| 123 | | | Generally the upgrade process involves the following actions:<br> |
| 124 | | | <ul type="disc"> |
| 125 | | | <li>stop the daemon |
| 126 | | | <li>copy the new files over the existing ones |
| 127 | | | <li>call the main setup script |
| 128 | | | <li>call each module's update script (if exists) |
| 129 | | | <li>re-start the daemon |
| 130 | | | </ul> |
| 131 | | | 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> |
| 132 | | | 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> |
| 133 | | | 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> |
| 134 | | | Oh, and don't forget to re-start the daemon afterwards ;).<br> |
| 135 | | | <br> |
| 136 | | | <br> |
| 137 | | | <a name="tools"><b>TOOLS</b></a><hr noshade> |
| 138 | | | The "tools" directory contains some useful scripts and add-ons for HotSaNIC.<br> |
| 139 | | | A brief description resides in this directory, some further descriptions may appear in this documentation later.<br> |
| 140 | | | <br> |
| 141 | | | <br> |
| 142 | | | <a name="contact"><b>CONTACT</b></a><hr noshade> |
| 143 | | | If you encounter further problems or have any questions or new ideas, please contact us via email to: "hotsanic at bernisys dot prima dot de" and we will try to take care of everything. Please put the keyword "hotsanic" and a brief description of your request into the subject!<br> |
| 144 | | | <br> |
| 145 | | | You may also use the project's tracker system on sourceforge.net to report errors, post bugfixes or to request feature enhancements and extensions.<br> |
| 146 | | | <br> |
| 147 | | | <br> |
| 148 | | | <a name="credits"><b>CREDITS</b></a><hr noshade> |
| 149 | | | At this point i'd like to thank and honor some people who support(ed) me and my project: |
| 150 | | | <ul type=disc> |
| 151 | | | <li>Matt Burke and Peter Reich, who are heavily involved in getting all functions running on BSD systems ! |
| 152 | | | <li>Todd Underwood, who managed to create some RPMs ! |
| 153 | | | <li>All my trusted friends for being appreciative of my hacking till late in the night ! ;) |
| 154 | | | <li>Everybody who sent me hints, new ideas, extensions and bug-reports. |
| 155 | | | </ul> |
| 156 | | | <br> |
| 157 | | | <br> |
| 158 | | | <a name="plans"><b>FUTURE PLANS</b></a><hr noshade> |
| 159 | | | Converting the whole shell-script crap to PERL. TODO: makerrd scripts<br> |
| 160 | | | <br> |
| 161 | | | </td></tr></table> |
| 162 | | | </center> |
| 163 | | | <br> |
| 164 | | | <HR> |
| 165 | | | </BODY> |
| 166 | | | </HTML> |
| 167 | | | |
