This file in intended to help a total beginner get his 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.
Ensure you have the right version of Perl. You should be using Perl
5.6 or higher. You can check by running “perl -V”.
Ensure 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.
Digest::MD5”by-authors/id/GAAS/Digest-MD5-*.tar.gz”LWP”by-authors/id/GAAS/libwww-perl-*.tar.gz”DB_File”by-authors/id/PMQS/DB_File-*.tar.gz”Date::Parse”by-authors/id/GBARR/Timedate-*.tar.gz”Time::HiRes”by-authors/id/DEWEG/Time-HiRes-*.tar.gz”SNMP_Session”:http://www.switch.ch/misc/leinen/snmp/perl”RRD”:http://www.rrdtool.org/”
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 CPAN FAQ.
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--
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
Or, if you are running Vixie Cron (an enhanced version of the cron utility that is common on Linux systems):
*/5 * * * * $HOME/cricket/collect-subtrees normal
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:
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.sf.net/”.