This section has been added to the Debian version of Cricket for the benefit of Debian users. Keep the following information in mind when using this document to configure Cricket on a Debian system.
This file in intended to help a total beginner get his/her first installation of Cricket up and running.
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.
Install the modules you need. You need to install the following Perl modules for Cricket to work correctly.
Installing Cricket for the Complete Beginner
This file in intended to help a total beginner get his/her first
installation of Cricket up and running.
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.
-
Insure you have the right version of Perl.
You should be using Perl 5.004 or higher.
You can check by running "perl -V".
-
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
Installing Cricket on Win2K to Monitor
WMI Counters 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).
-
Install the modules you need. You need to install the
following Perl modules for Cricket to work correctly.
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
Don't forget to run make site-perl-install
when installing RRD!
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:
ftp://ftp.cs.colorado.edu/pub/perl/CPAN/doc/FAQs/FAQ/PerlFAQ.html
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:
% cd cricket/lib
% perl -I. -MCPAN -e 'install Bundle::CricketPrereq'
-
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.
Do not run Cricket as the root user.
Superuser privileges are not necessary to run Cricket,
and granting them would very probably create a security
hole on your system.
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.
In the examples, this will be the user named "cricket".
-
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:
% cd ~cricket
% gunzip -c cricket-1.0.0.tar.gz | tar xvf -
You now need to run "sh configure" from
$HOME/cricket-1.0.0:
% cd ~cricket/cricket-1.0.0
% sh configure
This will fix the Perl scripts to work in your
environment.
-
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.
To do this:
% cd ~cricket
% ln -s cricket-1.0.0 cricket
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.
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:
$gCricketHome = "/home/cricket";
$gInstallRoot = "$gCricketHome/cricket";
There usually is no need to set $gConfigRoot explicitly,
so leave that line commented out.
Usually, there is no need to touch anything else in this
file.
-
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
% cd ~cricket
% cp -r cricket/sample-config cricket-config
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.
-
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.
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.
You will be editing the file "Targets" to tell Cricket
about your router. You want to change these lines:
target engineering-router
target-type=Cisco-7500-Router
short-desc = "Router for engineering folks"
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
/etc/hosts) 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.
You should change the words "Cisco-7500-Router" to reflect
the kind of router you have. You can choose from this list:
- Cisco-2500-Router
- Cisco-3600-Router
- Cisco-7200-Router
- Cisco-7500-Router
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.
Comment out the other target in that file (main-router)
using the Cricket comment symbol "#".
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:
Target --default--
... other stuff ...
snmp-community = public
Change "public" to your community string. Write the file
and exit.
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:
% ~/cricket/compile
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 whoami command and see what it
says). Check the FAQ
for more help with errors often seen in this step.
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.
% ~/cricket/collector /routers
You should see something like this on screen, though this
example was wrapped by hand for readability:
[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.
You can add the arguments "-logLevel debug" on to the end
of the command-line to get more information to help to
solve problems.
-
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.
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".
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:
% ~/cricket/util/listInterfaces engineering-router > interfaces
You should check the automatically generated interfaces
file and make certain it only lists interfaces you are
interested in.
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.
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:
% ~/cricket/collector /router-interfaces
Once again, you should see that Cricket is successfully
retrieving data for your targets.
-
Run the collector from cron. Now you need to set up cron
to run the collector every five minutes for you.
The collector is usually run from a wrapper program whose
job it is to handle locking, rotating log files, and other
administivia.
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.
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.
You'll need to add an entry like this to cron:
0,5,10,15,20,25,30,35,40,45,50,55 * * * * $HOME/cricket/collect-subtrees normal
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.
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).
-
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:
-
The Idiot's Guide to Solving Perl CGI Problems
(Don't feel bad, you
are not the idiot they are talking about, OK?)
-
The CGI section of the Apache FAQ
-
The Cricket FAQ
Please do not continue until you are certain things are
configured correctly.
Hint: if you are using a
vanilla RedHat Linux install, you are not ready to
continue until you do something about suEXEC.
See the Cricket
FAQ for more info.
OK, now that you have Apache (or some other web server)
correctly installed, you need to make some more links.
% 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 .
These links expose the minimal amount of Cricket necessary
to the web server.
Now, try going to this URL:
http://localhost/~cricket/cricket/grapher.cgi
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 ~cricket bit), using
another method to start grapher.cgi, you'll have to
edit grapher.cgi and uncomment the lines
# $ENV{'HOME'} = '/path/to/cricket/home';
# return;
and replace /path/to/cricket/home with the
directory you actually installed Cricket in.
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.
-
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.
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.
:)
-
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.
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
http://cricket.sourceforge.net.
Cricket version
1.0.5, released 2004-03-28.
Copyright (C) 1998-2000 Jeff Allen. Cricket is released under
the GNU General Public License.