jablonka.czprosek.czf

hotsanic

 Subversion Repositories:
[/] [branches/] [HotSaNIC-0.5.0-pre6/] [Documentation/] [README] - Blame information for rev 17

 

Line No. Rev Author Line
11simandl 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 
7HotSaNIC 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 are the very complex graphs
40 which show a lot more details. Most graphs are underlayed with an area
41 that covers the min/max range of samples taken at each time.
42 Quite all important system-stats are supported, more modules are to
43 come on users' requests and ideas.
44 The smallest time span that will be displayed covers the last hour, the
45 longest span diagram covers the last year though all data will be kept
46 for about two years (to have the chance to look further back in time
47 and compare).
48 Additionally there are some tools for debugging and to generate
49 alarm-reports (for example if a given threshold is exceeded) which may
50 be mailed to the system's admins.
51 
52 REQUIREMENTS
53 
54 -------------------------------------------------------------------
55 
56 Tobias Oetiker's "rrdtool" is needed to run this set of scripts. It is
57 used to manage the databases and generate the graphics. Make sure that
58 the "rrdtool" perl-libraries are installed on your system!
59 At this point i would like to congratulate Tobi, he did a very good job
60 writing this magnificent tool!
61 
62 Since I mainly use Perl5 to sample the data and update the databases,
63 of course this has to be installed on your system, too. But this should
64 not be an issue since most systems already come with full Perl5
65 support.
66 
67 "convert" from the "ImageMagick" package has to be installed to get
68 full functionality.
69 
70 Some modules require further tools or kernel features to be present.
71 Please refer to the module documentations for more information.
72 
73 CONFIGURATION
74 
75 -------------------------------------------------------------------
76 
77 All you should need to do for configuring is running setup.pl to
78 generate the start/stop script (called rrdgraph) and the main
79 "settings" file. The setup-script also calls each module's setup script
80 to generate all module-specific settings within the module's
81 subdirectory. After that you should check if the "settings" file in the
82 main directory contains the correct configuration to fit your system.
83 After that you should check the ""settings" files in each configured
84 module's directory and edit it to fit your system.
85 There are plenty of comments into the "settings" files, so they should
86 be quite self-explaining.
87 
88 STARTING AND STOPPING THE DAEMON
89 
90 -------------------------------------------------------------------
91 
92 Since there are some datasources only the "root" user has access to,
93 best would be to run it as "root". This is simply dome by getting
94 yourself root-permissions and typing:
95 
96 ./rrdgraph start
97 
98 rrdgraph will then begin to initialize itself and to sample data vor
99 each configured module every 10 seconds.
100 
101 To stop the daemon enter
102 
103 ./rrdgraph stop
104 
105 GENERATING WEB-STATISTICS
106 
107 -------------------------------------------------------------------
108 
109 The images on the statistics pages will be built automatically by
110 HotSaNIC every 15 minutes. If you like to build the graphs more ore
111 less often, you are welcome to decrease or increas the time-base as you
112 like by editing the main settings file. But be careful with too low
113 timespans, because it will use more CPU time (which may be needed for
114 more important tasks ... ).
115 
116 Usually you should not have to worry about anything except the
117 output-directory, which has to be configured correctly (you will have
118 to enter the full path!) in the main settings file.
119 
120 If not yet done, run makeindex.pl to generate all html files. The
121 script will gather every module and build the necessary index-files for
122 your webpage. In case you install a new module, just let HotSaNIC run a
123 couple of minutes to inititalize the plugin's databases. Then you just
124 call makeindex.pl again and it will rebuild all html files. New plugins
125 can be installed quite "on the fly". Just copy it to the "modules"
126 directory and add it to the RUN and SHOW entries in the main settings.
127 
128 "rrdtimer" will call "convert.sh" about every 24h (timebase may be
129 configured in main settings file). This script will generate pictograms
130 on the main index page of your webstats from the actual weekly graphs.
131 This will require "convert" from "ImageMagick" to be installed.
132 
133 TROUBLESHOOTING
134 
135 -------------------------------------------------------------------
136 
137 In case you encounter any trouble with HotSaNIC, you should check the
138 logfiles for possible errors.
139 Each "settings" file may contain an item "DEBUGLEVEL=<level>" which
140 changes the logging behaviour. Increasing the value will usually
141 increase verbosity, a value less than zero turns off all special
142 information.
143 o How do I solve the "cannot find "RRDs.pm" issue?
144 
145 -------------------------------------------------------------------
146 
147 You probably forgot to install the site-perl module of rrdtool.
148 
149 If you installed rrdtool from the source files, you just have to do
150 a
151 
152 make site-perl-install
153 
154 If you used a .rpm package, you should check if the RRDs.pm has
155 been installed in the correct places. maybe you used an RPM package
156 which didn't really fit your installation - some pathes may have
157 changed.
158 
159 Or maybe you upgraded PERL, then you also may have to adapt the
160 modules' pathes.
161 
162 o ping module is not working
163 
164 -------------------------------------------------------------------
165 
166 On some systems the PERL header-files may be missing. This results
167 in the ping-module complaining about something like
168 
169 "Can't locate sys/syscall.ph in @INC (did you run h2ph?)"
170 
171 Linux distributions known to be affected are for example "RedHat
172 7.2" and "Slackware"
173 
174 The solution would be to do (as root) the following:
175 
176 cd /usr/include
177 find . -name '*.h' -print | xargs h2ph
178 
179 After that everything should run as expected. - hopefully ;)
180 
181 o the graphs don't show up
182 
183 -------------------------------------------------------------------
184 
185 Maybe you just started the daemon. in that case let it run for some
186 minutes to let the databases be created and filled. Then you may
187 run the "diagrams" script in the main directory to generate the
188 graphs. This is done by the daemon automatically every DTIME (found
189 in the main settings)
190 If just the small graphs on the main page don't show, you have to
191 run "convert.pl" (or "convert.sh") in order to create the thumbnail
192 images. This is done every CTIME.
193 
194 o the thumbnails on the main page are not updating or still don't
195 exist
196 
197 -------------------------------------------------------------------
198 
199 Maybe you upgraded to v0.3.6 or later ?
200 In the later snapshots of this version the thumbnails moved from
201 the main web-dir to the module subdirs to enhance the overview a
202 bit. You have to call the main "makeindex.pl" to update the html
203 pages once again.
204 
205 UPGRADING
206 
207 -------------------------------------------------------------------
208 
209 Generally the upgrade process involves the following actions:
210 o stop the daemon
211 o copy the new files over the existing ones
212 o call the main setup script
213 o call each module's update script (if exists)
214 o re-start the daemon
215 However, if you intend to upgrade your HotSaNIC installation, you
216 should check the HotaNIC homepage firt to make sure wich additional
217 steps have to be performed. Maybe you have to check the history as
218 well, in case you update from a very old version.
219 Usually updates run quite smoothly without any further changes. You
220 should do as described above: Stop the daemon first to make sure that
221 no data will be fed into the databases which may lead to some annoying
222 side-effects. Then copy the new files to the corrosponding directories.
223 If some major changes occur, there will be an update script in the
224 affected module which you will have to call. The script will take care
225 the necessary and sometimes really nasty modifications for you.
226 Anyway, if you copy a newer version over a previous one, it's always a
227 good idea to call the main setup script once again. Maybe some new
228 important configuration items have been added since you last upgraded
229 or installed the tool!
230 Oh, and don't forget to re-start the daemon afterwards ;).
231 
232 TOOLS
233 
234 -------------------------------------------------------------------
235 
236 The "tools" directory contains some useful scripts and add-ons for
237 HotSaNIC.
238 A brief description resides in this directory, some further
239 descriptions may appear in this documentation later.
240 
241 CONTACT
242 
243 -------------------------------------------------------------------
244 
245 If you encounter further problems or have any questions or new ideas,
246 please contact us via email to: "hotsanic at bernisys dot prima dot de"
247 and we will try to take care of everything. Please put the keyword
248 "hotsanic" and a brief description of your request into the subject!
249 
250 You may also use the project's tracker system on sourceforge.net to
251 report errors, post bugfixes or to request feature enhancements and
252 extensions.
253 
254 CREDITS
255 
256 -------------------------------------------------------------------
257 
258 At this point i'd like to thank and honor some people who support(ed)
259 me and my project:
260 o Matt Burke and Peter Reich, who are heavily involved in getting all
261 functions running on BSD systems !
262 o Todd Underwood, who managed to create some RPMs !
263 o All my trusted friends for being appreciative of my hacking till
264 late in the night ! ;)
265 o Everybody who sent me hints, new ideas, extensions and bug-reports.
266 
267 FUTURE PLANS
268 
269 -------------------------------------------------------------------
270 
271 Converting the whole shell-script crap to PERL. TODO: makerrd scripts
272 
273 ----------------------------------------------------------------------

Powered by WebSVN 2.2.1