| 1 | 1 | simandl | HotSaNIC |
| 2 | | | HTML overview to System and Network Information Center |
| 3 | | | by Bernd Pissny ( hotsanic@bernisys.prima.de / http://www.bernisys.prima.de ) |
| 4 | | | |
| 5 | | | ---------------------------------------------------------------------- |
| 6 | | | |
| 7 | | | HotSaNIC documentation |
| 8 | | | |
| 9 | | | CONTENTS |
| 10 | | | |
| 11 | | | ------------------------------------------------------------------- |
| 12 | | | |
| 13 | | | 1. description |
| 14 | | | 2. requirements |
| 15 | | | 3. configuration |
| 16 | | | 4. starting & stopping |
| 17 | | | 5. web output |
| 18 | | | 6. troubleshooting |
| 19 | | | 7. upgrading |
| 20 | | | 8. tools |
| 21 | | | 9. contacting me |
| 22 | | | 10. credits |
| 23 | | | 11. future plans |
| 24 | | | |
| 25 | | | DESCRIPTION |
| 26 | | | |
| 27 | | | ------------------------------------------------------------------- |
| 28 | | | |
| 29 | | | HotSaNIC (the acronym stands for "html overview to system and network |
| 30 | | | information center") consists of a set of perl-scripts built on Tobias |
| 31 | | | Oetiker's "rrdtool" to generate graphical system-statistics, currently |
| 32 | | | supported platforms are linux (main development) and *BSD. |
| 33 | | | I started to build this tool in december 2000, because none of the |
| 34 | | | existing stats-tools gave me the flexibility and resolution i expected. |
| 35 | | | Most tools had a minimum query-time of one minute, while i use a 10sec. |
| 36 | | | timebase, which shows a lot more dynamics in the graphs. |
| 37 | | | The whole project is built in a modular way to make it quite easy to |
| 38 | | | expand, unused modules may be switched off easily. |
| 39 | | | Another advantage over most existing tools is the min/max-area that is |
| 40 | | | drawn behind the average-graphs in many modules - a feature that |
| 41 | | | reflects e.g. min/max bandwidth usage in much more detail than similar |
| 42 | | | tools do. |
| 43 | | | The smallest time span that will be displayed covers the last hour, the |
| 44 | | | longest span diagram covers the last year though all data will be kept |
| 45 | | | for about two years (in order to have the chance to look further back |
| 46 | | | in time and compare). Currently supported data-sources are traffic |
| 47 | | | (local and via SNMP), system's properties like |
| 48 | | | processes/memory/users/loadavg, hdd usage, hdd throughput, ping-times, |
| 49 | | | lm_sensors, #of running copies of given applications, distributed.net |
| 50 | | | statistics, worm-impacts (by analyzing apache-logfiles), APC-USV |
| 51 | | | statistics (load/temperature/charge...), connections to shoutcast |
| 52 | | | streams. More modules are to come on users' requests and ideas. |
| 53 | | | I recently started adding some tools for debugging and to generate |
| 54 | | | alarm-reports (for example if a given threshold is exceeded) which may |
| 55 | | | be mailed to the system's admins. |
| 56 | | | |
| 57 | | | REQUIREMENTS |
| 58 | | | |
| 59 | | | ------------------------------------------------------------------- |
| 60 | | | |
| 61 | | | Tobias Oetiker's "rrdtool" is needed to let this script work. It is |
| 62 | | | used to manage the databases and generate the graphics. At this point i |
| 63 | | | would like to congratulate Tobi, he did a very good job writing this |
| 64 | | | magnificent tool! |
| 65 | | | |
| 66 | | | Since I mainly use Perl5 to sample the data and update the databases, |
| 67 | | | of course this has to be installed on your system. But this should not |
| 68 | | | be an issue since most systems already come with full Perl5 support. |
| 69 | | | But please be sure to install the perl-libraries of "rrdtool" using |
| 70 | | | "make site-perl-install" afer you install "rrdtool." |
| 71 | | | |
| 72 | | | "convert" from the "ImageMagick" package has to be installed to get |
| 73 | | | full functionality. |
| 74 | | | |
| 75 | | | "iptables" or "ipchains" has to be installed if you want to use the |
| 76 | | | "network" module. Maybe you have to build a new kernel which has the |
| 77 | | | corrosponding firewalling capabilities (packet filter) |
| 78 | | | |
| 79 | | | CONFIGURATION |
| 80 | | | |
| 81 | | | ------------------------------------------------------------------- |
| 82 | | | |
| 83 | | | For version 0.3.6 first of all you should run setup.pl to generate the |
| 84 | | | start/stop script (this will be rrdgraph) and the main "settings" file. |
| 85 | | | The setup-script also calls each module's setup script to generate all |
| 86 | | | module-specific settings. After that you should check if the "settings" |
| 87 | | | file in the main directory contains the correct configuration to fit |
| 88 | | | your system. Then you should check the settings files in each module |
| 89 | | | directory and edit the generated "settings" files to fit your system. |
| 90 | | | |
| 91 | | | The "settings" files are (well, ok, at least they should be) quite |
| 92 | | | self-explaining, so i guess it isn't needed to explain them here - |
| 93 | | | though some day I might list every single module on this page along |
| 94 | | | with a short explanation of what they do and which features they have. |
| 95 | | | |
| 96 | | | STARTING AND STOPPING THE DAEMON |
| 97 | | | |
| 98 | | | ------------------------------------------------------------------- |
| 99 | | | |
| 100 | | | To run the auto-update daemon the best thing would be to get yourself |
| 101 | | | root-permissions and enter: |
| 102 | | | |
| 103 | | | ./rrdgraph start |
| 104 | | | |
| 105 | | | rrdgraph will begin sampling data vor every plugin installed every 10 |
| 106 | | | seconds. |
| 107 | | | |
| 108 | | | To stop the daemon enter |
| 109 | | | |
| 110 | | | ./rrdgraph stop |
| 111 | | | |
| 112 | | | Most modules will run as non-root, too, but if you want full |
| 113 | | | functionality it is absolutely necessary to let the whole thing run as |
| 114 | | | root. For example the PING module uses ICMP stuff that is only working |
| 115 | | | if you are running it as root. |
| 116 | | | |
| 117 | | | GENERATING WEB-STATISTICS |
| 118 | | | |
| 119 | | | ------------------------------------------------------------------- |
| 120 | | | |
| 121 | | | Well, you should not have to worry about anything except the |
| 122 | | | output-directory which has to be configured correctly (you will have to |
| 123 | | | enter the full path!) in the main settings file. |
| 124 | | | |
| 125 | | | The images on the statistics pages will be built automatically by |
| 126 | | | HotSaNIC every configured timespan (which will be 15min. by default) If |
| 127 | | | you like to build the graphs more often, you are welcome to decrease |
| 128 | | | the time-base as you like by editing the main settings file. But be |
| 129 | | | sure that decreasing the time-span will eat up more CPU time (which may |
| 130 | | | be needed for more important tasks ... ). |
| 131 | | | |
| 132 | | | To build the index.html files just start makeindex.pl and all shall be |
| 133 | | | well. The script will gather every plugin-directory and build the |
| 134 | | | necessary index-files for your webpage. In case you install a new |
| 135 | | | plugin, just let HotSaNIC run a couple of minutes inititalize the |
| 136 | | | plugin's databases. Then you just call makeindex.pl again and it will |
| 137 | | | do the rather nasty update-job for you. New plugins can be installed on |
| 138 | | | the fly, the only thing to do is to copy the module-directory to the |
| 139 | | | main directory and maybe you have to add the new module to the RUN and |
| 140 | | | SHOW entries in the main settings. |
| 141 | | | |
| 142 | | | If you use the "traffic" plugin, please let rrdgraph run at least some |
| 143 | | | 30 seconds to allow the plugin to scan your local interfaces before you |
| 144 | | | run the index-maker. |
| 145 | | | |
| 146 | | | "rrdtimer" will call "convert.sh" about every 24h (timebase may be |
| 147 | | | configured in main settings file). This script will generate pictograms |
| 148 | | | on the main index page of your webstats from the actual weekly graphs. |
| 149 | | | |
| 150 | | | This will require "convert" from "ImageMagick" to be installed. It is |
| 151 | | | used to resize the weekly graph images. |
| 152 | | | |
| 153 | | | TROUBLESHOOTING |
| 154 | | | |
| 155 | | | ------------------------------------------------------------------- |
| 156 | | | |
| 157 | | | o How do I solve the "cannot find "RRDs.pm" issue? |
| 158 | | | |
| 159 | | | ------------------------------------------------------------------- |
| 160 | | | |
| 161 | | | You probably forgot to install the site-perl module of rrdtool. |
| 162 | | | |
| 163 | | | If you installed rrdtool from the source files, you just have to do |
| 164 | | | a |
| 165 | | | |
| 166 | | | make site-perl-install |
| 167 | | | |
| 168 | | | If you used a .rpm package, you should check if the RRDs.pm has |
| 169 | | | been installed in the correct places. maybe you used an RPM package |
| 170 | | | which didn't really fit your installation - some pathes may have |
| 171 | | | changed. |
| 172 | | | |
| 173 | | | Or maybe you upgraded PERL, then you also may have to adapt the |
| 174 | | | modules' pathes. |
| 175 | | | |
| 176 | | | o ping module is not working |
| 177 | | | |
| 178 | | | ------------------------------------------------------------------- |
| 179 | | | |
| 180 | | | On some systems the PERL header-files may be missing. This results |
| 181 | | | in the ping-module complaining about something like |
| 182 | | | |
| 183 | | | "Can't locate sys/syscall.ph in @INC (did you run h2ph?)" |
| 184 | | | |
| 185 | | | Linux distributions known to be affected are for example "RedHat |
| 186 | | | 7.2" and "Slackware" |
| 187 | | | |
| 188 | | | The solution would be to do (as root) the following: |
| 189 | | | |
| 190 | | | cd /usr/include |
| 191 | | | find . -name '*.h' -print | xargs h2ph |
| 192 | | | |
| 193 | | | After that everything should run as expected. - hopefully ;) |
| 194 | | | |
| 195 | | | o the graphs don't show up |
| 196 | | | |
| 197 | | | ------------------------------------------------------------------- |
| 198 | | | |
| 199 | | | Maybe you just started the daemon. in that case let it run for some |
| 200 | | | minutes to let the databases be created and filled. Then you may |
| 201 | | | run the "diagrams" script in the main directory to generate the |
| 202 | | | graphs. This is done by the daemon automatically every DTIME (found |
| 203 | | | in the main settings) |
| 204 | | | If just the small graphs on the main page don't show, you have to |
| 205 | | | run "convert.pl" (or "convert.sh") in order to create the thumbnail |
| 206 | | | images. This is done every CTIME. |
| 207 | | | |
| 208 | | | o the thumbnails on the main page are not updating or still don't |
| 209 | | | exist |
| 210 | | | |
| 211 | | | ------------------------------------------------------------------- |
| 212 | | | |
| 213 | | | Maybe you upgraded to v0.3.6 or later ? |
| 214 | | | In the later snapshots of this version the thumbnails moved from |
| 215 | | | the main web-dir to the module subdirs to enhance the overview a |
| 216 | | | bit. You have to call the main "makeindex.pl" to update the html |
| 217 | | | pages once again. |
| 218 | | | |
| 219 | | | o after i compiled the scripts some modules fill the logfiles with |
| 220 | | | errors |
| 221 | | | |
| 222 | | | ------------------------------------------------------------------- |
| 223 | | | |
| 224 | | | At the moment there is no other way than removing the binaries. I |
| 225 | | | had such strange effects on some systems myself, but I don't know |
| 226 | | | why the binaries behave that way. The compiling completes without |
| 227 | | | any errors, but the binaries won't start properly like the .pl |
| 228 | | | scripts do. |
| 229 | | | |
| 230 | | | UPGRADING |
| 231 | | | |
| 232 | | | ------------------------------------------------------------------- |
| 233 | | | |
| 234 | | | Generally the upgrade process involves the following actions: |
| 235 | | | o stop the daemon |
| 236 | | | o copy the new files over the existing ones |
| 237 | | | o call the main setup script |
| 238 | | | o call each module's update script (if exists) |
| 239 | | | o re-start the daemon |
| 240 | | | However, if you intend to upgrade your HotSaNIC installation, you |
| 241 | | | should check the HotaNIC homepage firt to make sure wich additional |
| 242 | | | steps have to be performed. Maybe you have to check the history as |
| 243 | | | well, in case you update from a very old version. |
| 244 | | | Usually updates run quite smoothly without any further changes. You |
| 245 | | | should do as described above: Stop the daemon first to make sure |
| 246 | | | that no data will be fed into the databases which may lead to some |
| 247 | | | annoying side-effects. Then copy the new files to the corrosponding |
| 248 | | | directories. If some major changes occur, there will be an update |
| 249 | | | script in the affected module which you will have to call. The |
| 250 | | | script will take care the necessary and sometimes really nasty |
| 251 | | | modifications for you. |
| 252 | | | Anyway, if you copy a newer version over a previous one, it's |
| 253 | | | always a good idea to call the main setup script once again. Maybe |
| 254 | | | some new important configuration items have been added since you |
| 255 | | | last upgraded or installed the tool! |
| 256 | | | Oh, and don't forget to re-start the daemon afterwards ;). |
| 257 | | | |
| 258 | | | TOOLS |
| 259 | | | |
| 260 | | | ------------------------------------------------------------------- |
| 261 | | | |
| 262 | | | Since version 0.4.0 I added a directory containing some possibly |
| 263 | | | useful scripts and add-ons for HotSaNIC. |
| 264 | | | A brief description resides in this directory, some further |
| 265 | | | descriptions may appear in this documentation later. |
| 266 | | | |
| 267 | | | One nifty thing has to be mentioned: |
| 268 | | | The modules may be compied in order to start up a bit faster. This |
| 269 | | | will save some percent of your valuable CPU time, but it may not |
| 270 | | | run on every machine! Unhappily the behaviour of the binaries is |
| 271 | | | beyond my control. In most cases they run as smoothly as the |
| 272 | | | perl-scripts, but up to three times faster, sometimes they fill the |
| 273 | | | error-log and sometimes they won't even compile. Only thing you can |
| 274 | | | do is to give it a try and remove all binaries which cause |
| 275 | | | problems. |
| 276 | | | |
| 277 | | | The compilation process is quite easy: Just call the "compile" |
| 278 | | | script in the main directory - that's all. |
| 279 | | | A whole load of compiler information will scroll down your screen |
| 280 | | | for quite a while. During the (hopefully successful) compiling |
| 281 | | | process, your daemon will automatically start to call the binaries |
| 282 | | | instead of the scripts. These are named "read-data" (without the |
| 283 | | | .pl suffix). This allows to compile while the daemon is already |
| 284 | | | running. |
| 285 | | | The compile script has some useful options: |
| 286 | | | o "compile r" forces the re-compiling of all modules - no matter |
| 287 | | | if they are already compiled or not. |
| 288 | | | o "compile u" removes all binaries, leaving just the scripts |
| 289 | | | again. |
| 290 | | | o "compile c" checks if any modules have to be re-compiled (does |
| 291 | | | not change anything, just lists them) |
| 292 | | | o "compile " compiles precisely not more the given module (the |
| 293 | | | prefix "data-" may be omitted). |
| 294 | | | |
| 295 | | | CONTACT |
| 296 | | | |
| 297 | | | ------------------------------------------------------------------- |
| 298 | | | |
| 299 | | | If you encounter further problems or have any questions or new |
| 300 | | | ideas, please contact us at hotsanic@bernisys.prima.de, we will try |
| 301 | | | to take care of everything. It would be a good idea to put the |
| 302 | | | keyword "hotsanic" and a brief description of your request into the |
| 303 | | | subject to make sure i find your mails again in case we need them |
| 304 | | | later on. |
| 305 | | | |
| 306 | | | If you already have a solution for a problem you encountered, |
| 307 | | | please attach the working code or the modifications you made. A |
| 308 | | | proper description of your problem and the changes you made would |
| 309 | | | be very helpful. |
| 310 | | | |
| 311 | | | Same goes for extensions ideas and support for systems other than |
| 312 | | | Linux. |
| 313 | | | |
| 314 | | | CREDITS |
| 315 | | | |
| 316 | | | ------------------------------------------------------------------- |
| 317 | | | |
| 318 | | | At this point i'd like to thank and honor some people who |
| 319 | | | support(ed) me and my project: |
| 320 | | | o Matt Burke and Peter Reich, who are heavily involved in |
| 321 | | | getting all functions running on BSD systems ! |
| 322 | | | o Todd Underwood, who managed to create some RPMs ! |
| 323 | | | o All my trusted friends for being appreciative of my hacking |
| 324 | | | till late in the night ! ;) |
| 325 | | | o Everybody who sent me hints, new ideas, extensions and |
| 326 | | | bug-reports. |
| 327 | | | |
| 328 | | | FUTURE PLANS |
| 329 | | | |
| 330 | | | ------------------------------------------------------------------- |
| 331 | | | |
| 332 | | | I intend to convert the whole shell-script crap to a PERL script |
| 333 | | | which will run very much faster and therefore does not generate |
| 334 | | | unnecessary system-overhead. This is already done for the |
| 335 | | | data-sampling scripts and the index generation. TODO: diagrams |
| 336 | | | |
| 337 | | | I would like to implement more SMNP features not only for the |
| 338 | | | traffic module (as far as possible of course). |
| 339 | | | |
| 340 | | | In case you have written your own plug-in and you find it useful, |
| 341 | | | be sure to e-mail me a .tgz of your module and include a short |
| 342 | | | description. Same goes for reporting bugs of course! |
| 343 | | | |
| 344 | | | Thank you! |
| 345 | | | |
| 346 | | | ---------------------------------------------------------------------- |
