File: beginner.html

package info (click to toggle)
cricket 1.0.5-9
  • links: PTS
  • area: main
  • in suites: lenny
  • size: 1,480 kB
  • ctags: 390
  • sloc: perl: 8,287; sh: 920; ansic: 318; makefile: 62; sql: 16
file content (544 lines) | stat: -rw-r--r-- 21,921 bytes parent folder | download | duplicates (7)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
  <head>
    <title>Installing Cricket for the Complete Beginner</title>
  </head>
  <body>
    <h1>Installing Cricket for the Complete Beginner</h1>
    <p>
      This file in intended to help a total beginner get his/her first
      installation of Cricket up and running. 
    </p>
    <p>
      If you follow the steps below carefully, you will have a a minimal
      installation, following a standard layout. From here, you can
      explore on your own. When you need help, it will be easy for
      others to help you, since they will be familiar with the beginner
      setup. 
    </p>
    <ol>
      <li>
        Insure you have the right version of Perl. 
        You should be using Perl 5.004 or higher.
        You can check by running "perl -V". 
      </li>
      <li>
        Insure you are on a supported platform. For your purposes as a
        beginner, any Unix should work. Cricket also runs on Windows NT
        4.0 and Windows 2000. This document assumes a Unix platform.
        Unfortunately, there is no comparable document for beginners
        on the Windows platform. The instructions in 
        <a href="win2kwmi.html">Installing Cricket on Win2K to Monitor 
        WMI Counters</a> will help with installation, then refer to 
        this document to learn about the config tree. Do your best
        to translate Unix commands in this document to their Windows
        counterparts (i.e. Windows xcopy can replace Unix cp -r).
      </li>
      <li>
        <p>
          Install the modules you need. You need to install the
          following Perl modules for Cricket to work correctly.
        </p>
        <pre>
Module             From
--------------------------------------------------------------------
MD5                CPAN: by-authors/id/GAAS/Digest-MD5-*.tar.gz
LWP                CPAN: by-authors/id/GAAS/libwww-perl-*.tar.gz
DB_File            CPAN: by-authors/id/PMQS/DB_File-*.tar.gz
Date::Parse        CPAN: by-authors/id/GBARR/TimeDate-*.tar.gz
Time::HiRes        CPAN: by-authors/id/DEWEG/Time-HiRes-*.tar.gz

SNMP_Session       http://www.switch.ch/misc/leinen/snmp/perl
RRD                http://ee-staff.ethz.ch/~oetiker/webtools/rrdtool
        </pre>
        <p>
          Don't forget to run <tt>make site-perl-install</tt>
          when installing RRD! 
        </p>
        <p>
          Modules marked with CPAN come from the Comprehensive Perl
          Archive Network. If you don't know where to find a CPAN
          site or how to install modules, take a look at the Perl
          FAQ here: 
        </p>
        <p>
          <a href="ftp://ftp.cs.colorado.edu/pub/perl/CPAN/doc/FAQs/FAQ/PerlFAQ.html">ftp://ftp.cs.colorado.edu/pub/perl/CPAN/doc/FAQs/FAQ/PerlFAQ.html</a>
        </p>
        <p>
          You may also be able to use CPAN.pm to quickly and easily
          install modules. Type "perldoc CPAN" to learn more about
          it. Cricket ships with a CPAN-style Bundle which should
          make it simple to install the modules you need. The magic
          command to do this is: 
        </p>
        <pre>
% cd cricket/lib
% perl -I. -MCPAN -e 'install Bundle::CricketPrereq'
        </pre>
      </li>
      <li>
        <p>
          Choose a user to run Cricket. Many sites create a
          special user to run Cricket, but that's not necessary.
          If you choose to run Cricket from your own account
          understand that there will be several directories in
          your home directory that Cricket needs. Learn to live
          with them until you know how to move them elsewhere, or
          use a dedicated user for Cricket so that the directories
          won't bug you. 
        </p>
        <p>
          Do <b>not</b> run Cricket as the <tt>root</tt> user.
          Superuser privileges are not necessary to run Cricket,
          and granting them would very probably create a security
          hole on your system. 
        </p>
        <p>
          If you use a dedicated user for Cricket make certain that
          mail sent to that user ends up in your mailbox. Some of
          Cricket's runtime errors get reported (with cron's help)
          via e-mail. 
        </p>
        <p>
          In the examples, this will be the user named "cricket".
        </p>
      </li>
      <li>
        Extract the tarfile and run configure. Well, you seem to have
        already done this, since you are reading this file. Please
        make certain the expanded directory tree is in the home
        directory of the user that will be running Cricket. For
        example, if this was Cricket version 1.0.0, it would look like
        this: 
        <pre>
% cd ~cricket
% gunzip -c cricket-1.0.0.tar.gz | tar xvf -
        </pre> 
        <p>
          You now need to run "sh configure" from
          $HOME/cricket-1.0.0:
        </p>
        <pre>
% cd ~cricket/cricket-1.0.0
% sh configure
        </pre> 
        <p>
          This will fix the Perl scripts to work in your
          environment.
        </p>
      </li>
      <li>
        <p>
          Make a softlink to the version you are running. To make
          it easier to upgrade later you'll want to make a link
          from a generic name to the specific name you are
          currently running.
        </p>
        <p>To do this:</p>
        <pre>
% cd ~cricket
% ln -s cricket-1.0.0 cricket
        </pre> 
        <p>
          This makes it so that you can refer to things in
          $HOME/cricket, and still get the version 1.0.0 copies of
          those files. You'll then be able to swing that link over
          to newer versions as they become available. 
        </p>
        <p>
          If you don't have a cricket-conf.pl file yet, copy the
          example file cricket-conf.pl.sample to cricket-conf.pl,
          and edit it. You will need to set $gCricketHome to the
          home directory of the user that Cricket runs as (this
          is used to locate the cricket-config directory, among
          other things). The $gInstallRoot variable should point
          to where the Cricket scripts are. It is recommended to
          point this to the symlink, so that you can just copy
          this file if you upgrade Cricket later. If you followed
          the instructions so far, $gInstallRoot will be set
          correctly without changing the sample, so cricket-conf.pl
          will contain these two lines: 
        </p>
        <pre>
$gCricketHome = "/home/cricket";
$gInstallRoot = "$gCricketHome/cricket";
        </pre>
        <p>
          There usually is no need to set $gConfigRoot explicitly,
          so leave that line commented out. 
        </p>
        <p>
          Usually, there is no need to touch anything else in this
          file.
        </p>
      </li>
      <li>
        <p>
          Copy the sample-config tree and modify it for your site.
          Copy the files you intend to use from the sample-config
          tree from the cricket distribution to
          $HOME/cricket-config. You can use 
        </p>
        <pre>
% cd ~cricket
% cp -r cricket/sample-config cricket-config
        </pre>
        <p>
          but the parts of the tree you won't be using immediately
          may cause some (otherwise harmless) warnings later on.
          If you don't copy the entire tree, make sure to at least
          include the top level Defaults file! Let's focus on two
          subtrees, routers and router-interfaces. If you can get
          these going, you'll be able to get others going too. 
        </p>
      </li>
      <li>
        <p>
          Setup the routers subtree. Go into the routers tree and
          look at the targets file. This is where you want to tell
          Cricket which router to talk to. 
        </p>
        <p>
          Note: As far as beginners are concerned, statistics are
          only available from Cisco routers. If you have another
          kind of router, you should skip to the router-interfaces
          step for now. Later, when you understand the system
          better, you can come back and use contributed
          configurations from other Cricket users with hardware
          like yours to make your routers subtree work. 
        </p>
        <p>
          You will be editing the file "Targets" to tell Cricket
          about your router. You want to change these lines: 
        </p>
        <pre>
target  engineering-router
target-type=Cisco-7500-Router
short-desc  =   "Router for engineering folks"
        </pre> 
        <p>
          You should change the words "engineering-router" in the
          first line to the hostname of the router you want to talk
          to. If it has not been assigned a hostname, you need to
          stop and do that (perhaps by simply editing
          <tt>/etc/hosts</tt>) before configuring Cricket for the
          first time. Cricket can talk to things via an IP address,
          but configuring it that way is beyond the scope of this
          document. 
        </p>
        <p>
          You should change the words "Cisco-7500-Router" to reflect
          the kind of router you have. You can choose from this list: 
        </p>
        <ul>
          <li>Cisco-2500-Router</li>
          <li>Cisco-3600-Router</li>
          <li>Cisco-7200-Router</li>
          <li>Cisco-7500-Router</li>
        </ul>
        <p>
          If your router type is not on this list, choose
          "Cisco-2500-Router" for now. You can experiment with other
          types later, if you want. The only difference is the
          amount of information you get about ambient temperature
          where the router is installed. 
        </p>
        <p>
          Comment out the other target in that file (main-router)
          using the Cricket comment symbol "#". 
        </p>
        <p>
          Finally, if you are not using the default SNMP community
          string, "public", you need to tell Cricket what community
          string to use. Since a community string is something that
          is usually shared across many network devices, it should
          live at a higher place in the config tree. This is a
          useful feature of the config tree -- it lets you move
          things that apply to lots of targets to a single place
          (higher in the config tree) where it will be easier to
          maintain. To set the community string for your
          installation, edit the the root Defaults file, which is
          ~/cricket-config/Default. It has a section like this in
          it:
        </p>
        <pre>
Target  --default--
  ... other stuff ...
  snmp-community      = public
        </pre>
        <p>
          Change "public" to your community string. Write the file
          and exit.
        </p>
        <p>
          After you make any changes to the config tree, you need to
          compile it. Storing it in a compiled form makes accessing
          it quicker and easier. Do this: 
        </p>
        <pre>% ~/cricket/compile</pre>
        <p>
          If the compile command give you any errors, stop at this
          point and fix the problem. This is a good time to check
          to make sure you are logged in to the Cricket user account
          (try out the <tt>whoami</tt> command and see what it
          says). Check the <a
            href="http://cricket.sourceforge.net/support/FAQ">FAQ</a>
          for more help with errors often seen in this step. 
        </p>
        <p>
          Now, you are ready to try out your configuration. We will
          run the collector by hand on just this subtree first to
          see if there were any errors. 
        </p>
        <pre>% ~/cricket/collector /routers</pre>
        <p>
          You should see something like this on screen, though this
          example was wrapped by hand for readability: 
        </p>
        <pre>
[25-Jan-1999 15:21:20 ] Starting collector: Cricket version 0.64
              ( Fri May 14 14:14:28 PDT 1999 )
[25-Jan-1999 15:21:20 ] Retrieved data for engineering-router:
              19,19,15,22,2510380,49824724
[25-Jan-1999 15:21:20 ] Processed 1 targets in 2 seconds.
        </pre> 
        <p>
          You can add the arguments "-logLevel debug" on to the end
          of the command-line to get more information to help to
          solve problems.
        </p>
      </li>
      <li>
        <p>
          Set up the router-interfaces subtree. We will setup the
          router-interfaces subtree in much the same way that we set
          up the routers subtree. However, there's a tool to help us
          avoid the grunt work. This tool is called 'listInterfaces',
          and it comes in the util directory. 
        </p>
        <p>
          listInterfaces one or two arguments. It must have a router
          name as the first argument, and it can take a community
          string as the second argument. If you do not specify the
          community string, it defaults to "public". 
        </p>
        <p>
          When you run listInterfaces against a router, it will
          print a Cricket config to it's standard output. Thus,
          you can use it like this to save some work: 
        </p>
        <pre>% ~/cricket/util/listInterfaces engineering-router > interfaces</pre> 
        <p>
          You should check the automatically generated interfaces
          file and make certain it only lists interfaces you are
          interested in. 
        </p>
        <p>
          By adding this file, you've just changed the config tree.
          Remember, you must compile the tree every time you edit
          it. Or rather, if you forget to compile the tree, the
          Cricket collector will do it for you, but in that case you
          are not likely to see any errors you might have
          introduced, so it's always a good idea to compile
          explicitly.
        </p>
        <p>
          Once again, run the collector by hand to make certain that
          it will be able to talk to your router and collect data.
          The command to do this is: 
        </p>
        <pre>% ~/cricket/collector /router-interfaces</pre>
        <p>
          Once again, you should see that Cricket is successfully
          retrieving data for your targets. 
        </p>
      </li>
      <li>
        <p>
          Run the collector from cron. Now you need to set up cron
          to run the collector every five minutes for you. 
        </p>
        <p>
          The collector is usually run from a wrapper program whose
          job it is to handle locking, rotating log files, and other
          administivia. 
        </p>
        <p>
          The wrapper is called collect-subtrees. It reads a file
          from the Cricket install directory called "subtree-sets".
          This file holds lists of subtrees which will get processed
          together in a group. It also lists the places where
          Cricket will expect to find it's configuration and log
          directory. As it comes in the distribution, this file
          needs no changes. 
        </p>
        <p>
          Later, you will find that this file lets you control what
          parts of your config tree will be collected in parallel.
          This is a critical feature to increase the number of
          devices you can poll. 
        </p>
        <p>
          You'll need to add an entry like this to cron:
        </p>
        <pre>
0,5,10,15,20,25,30,35,40,45,50,55 * * * * $HOME/cricket/collect-subtrees normal
        </pre>
        <p>
          Usually, this is done by typing "crontab -e". In the
          crontab, it will all be on one line. It has been manually
          wrapped above for readability. 
        </p>
        <p>
          If the script generates output, it will be sent to the
          user who owns the crontab. You should make certain you
          can see that mail. If you don't see the mail, you won't
          know what's wrong (though most of the messages you are
          likely to see will also show up in the $HOME/cricket-logs
          directory). 
        </p>
      </li>
      <li>
        <p>
          Set up the Grapher. For this part of the installation, you
          will need an installation of Apache running which is
          correctly configured to let you run CGI scripts linked
          into your $HOME/public_html directory via a symlink.
          Configuring the web server correctly has proven to be the
          hardest for beginning Cricket users. Here are some
          resources that might help you get it right: 
        </p>
        <p>
        </p>
        <ul>
          <li>
            <a href="http://www.cpan.org/doc/FAQs/cgi/idiots-guide.html">
              The Idiot's Guide to Solving Perl CGI Problems
            </a>
            (Don't feel bad, <a href="http://localhost/">you</a>
            are not the idiot they are talking about, OK?) 
          </li>
          <li>
            <a href="http://www.apache.org/docs/misc/FAQ.html#CGIoutsideScriptAlias">
              The CGI section of the Apache FAQ
            </a>
          </li>
          <li>
            <a href="http://cricket.sourceforge.net/support/FAQ">
              The Cricket FAQ
            </a>
          </li>
        </ul>
        <p>
          Please do not continue until you are certain things are
          configured correctly. 
          <span style="color: red">Hint</span>: if you are using a
          vanilla RedHat Linux install, you are not ready to
          continue until you do something about <a
          href="http://www.apache.org/docs/suexec.html">suEXEC</a>.
          See the <a
            href="http://cricket.sourceforge.net/support/FAQ">Cricket
            FAQ</a> for more info. 
        </p>
        <p>
          OK, now that you have Apache (or some other web server)
          correctly installed, you need to make some more links. 
        </p>
        <pre>
  % cd $HOME/public_html
  % mkdir cricket
  % cd cricket
  % ln -s $HOME/cricket/VERSION .
  % ln -s $HOME/cricket/grapher.cgi .
  % ln -s $HOME/cricket/mini-graph.cgi .
  % ln -s $HOME/cricket/lib .
  % ln -s $HOME/cricket/images .
        </pre>
        <p>
          These links expose the minimal amount of Cricket necessary
          to the web server. 
        </p>
        <p>
          Now, try going to this URL: 
        </p>
        <p>
          <a href="http://localhost/~cricket/cricket/grapher.cgi">
            http://localhost/~cricket/cricket/grapher.cgi
          </a>
        </p>
        <p>
          If you are running under a different user, or your
          webserver is on a different machine from your web
          browser, alter the URL accordingly. Additionally,
          if you want to get rid of the username reference
          in the URL (i.e., the <tt>~cricket</tt> bit), using
          another method to start grapher.cgi, you'll have to
          edit grapher.cgi and uncomment the lines 
        </p>
        <pre>
# $ENV{'HOME'} = '/path/to/cricket/home';
# return;
        </pre>
        <p>
          and replace <tt>/path/to/cricket/home</tt> with the
          directory you actually installed Cricket in. 
        </p>
        <p>
          You should see the front page, including some graphics and
          a couple of links to more stuff. If you get a web server
          error page instead you MUST go check the web server error
          log. The answer to what went wrong will almost certainly
          be in there. 
        </p>
      </li>
      <li>
        <p>
          You're done! The graphs will not show any data for a
          while, since it takes some time to have enough history
          to make an interesting graph. As long as you are certain
          the collector is working right (now would be a very good
          time to check your e-mail for errors, and scan the files
          in $HOME/cricket-logs for errors) then you can take some
          time to read the other documentation, or maybe even grab
          a beer. 
        </p>
        <p>
          After about an hour, you should have some mildly
          interesting graphs. After a day, hopefully you'll have
          some very interesting graphs. After three months, you'll
          finally have graphs that you can show to your boss to
          prove that you need to upgrade the office's 384 kilobit
          DSL to a T3. We're pulling for you, really we are. 
          <tt>:)</tt>
        </p>
      </li>
      <li>
        <p>
          The Next Step. Now that you are an expert (expert
          beginner, that is), you should add some more targets to
          your config tree, and explore the other subtrees in the
          sample-config tree. With those subtrees, you can monitor
          web server performance, switch port usage, and other
          interesting stuff. 
        </p>
        <p>
          As you learn more, you'll be able to make your own
          subtrees to handle special kinds of data unique to your
          site. If you make a subtree that can support a device
          others are using, please submit to the Cricket contributed
          configurations site, which is part of Cricket's homepage at 
          <a href="http://cricket.sourceforge.net/">http://cricket.sourceforge.net</a>. 
        </p>
      </li>
    </ol>
    <p>
      <a href="http://cricket.sourceforge.net">Cricket</a> version
      1.0.5, released 2004-03-28. 
    </p>
    <p>
      Copyright (C) 1998-2000 Jeff Allen. Cricket is released under
      the <a href="gpl.html">GNU General Public License</a>. 
    </p>
  </body>
</html>