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. Cricket is an exceptionally
flexible system. It had to be that way to solve the tricky problems we
intended to throw at it here at WebTV. If you follow the steps below
carefully, you will have a running configuration using a standard
setup. It will make it easier for people to help you with it, and it
will give you a foundation to learn more about the tool. This is
not a comprehensive tutorial. It will get you up and running and ready
to explore the system in more depth, if you want.

1. Insure you have the right version of Perl.

You should be using Perl 5.004 or higher. You can check by running
"perl -V".

2. Insure you are on a supported platform.

For your purposes as a beginner, any Unix should work. If you are
using Windows, you must use Windows NT 4.0 (no other variations of
Windows have been tested). If you are using Windows NT, the specific
recommendations about where to put files and the examples will not
make any sense to you. Please follow along and do your best. We'll
hopefully have NT versions of these instructions in the future.

3. Install the modules you need.

You need to install the following Perl modules for Cricket to work
correctly. The location to the right is where to fetch them from.

    Module             From
    --------------------------------------------------------------------
    MD5                CPAN
    Time::HiRes        CPAN
    LWP                CPAN
    DB_File            CPAN
	Date::Parse        CPAN (in Timedate-*.tar.gz)
    SNMP_Session       http://www.switch.ch/misc/leinen/snmp/perl
    RRD                http://ee-staff.ethz.ch/~oetiker/webtools/rrdtool

Modules marked with CPAN come from the Comprehensive Perl Archive
Network. If you don't know where to find a CPAN site or install
modules, take a look at the Perl FAQ here:

	ftp://ftp.cs.colorado.edu/pub/perl/CPAN/doc/FAQs/FAQ/PerlFAQ.html

Generally, to install a module you execute these steps:

	% gunzip -c MODULE.tar.gz | tar xvf -
	% cd MODULE
	% perl Makefile.PL
	% make
	% make test
	% su		# most installations require you to be root to install
	# make install

4. 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.

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".

5. 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:

	% cd ~cricket
	% gunzip -c cricket-1.00.tar.gz | tar xvf -

You now need to run "sh configure" from $HOME/cricket-1.00.
This will fix the Perl scripts to work in your environment.

6. 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.  (Windows
NT 4.0 users can't use this trick. A Win32 shortcut is not the same
thing as a Unix softlink and will not help here.)

To do this:

	% cd ~cricket
	% ln -s cricket-1.00 cricket

This makes it so that you can refer to things in $HOME/cricket, and
still get the version 1.00 copies of those files. You'll then be able
to swing that link over to newer versions as they become available.

7. Copy the sample-config tree and modify it

Copy the sample-config tree from the cricket distribution to
$HOME/cricket-config.

	% cd ~cricket
	% cp -r cricket/sample-config cricket-config

Most of that tree you won't be using immediately. 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.

8. 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: At this time, statistics are only available from Cisco
routers. If you have another kind of router, you should skip to the
router-interfaces step, since you won't be able to get chassis
measurements from your routers until you find a configuration that
works with your router.

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 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 others 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 the 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 Defautlts
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

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 use "-logLevel debug" to get more information to try to
solve problems.

9. 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 interfaces file and make certain it only lists
interfaces you are interested in. 

Once again, run the collector by hand to make certain that it will
be able to talk to your router and collect data. As above, the command
to do this is:

        % ~/cricket/collector /router-interfaces

Once again, you should see that Cricket is successfully retreiving
data for your targets.

10. Run the collector from cron

Now you need to set up cron to run the collector every five minutes
for you.

Windows NT users: cron is a Unix service that schedules commands to
run at certain times. There are services like this available for NT
from the Resource Kit or for free off the net. If you are a NT user,
please give me a pointer to a useful cron-like service for NT that
works for you. The rest of this section will pretty much be useles
to NT users.

The collector is usually run from a wrapper program whose
job it is to handle locking, rotating log files, and creating
the huge command line that the collector sometimes requires. 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 all get processed together.
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. If you want to later move things
around a bit, you could edit this file to tell Cricket where
to find the files you moved. (You'd also need to edit the source
code to the grapher, discussed below.)

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).

11. Set up the Grapher

For this part of the installation, you will need a web server
running which is correctly configured to let you run CGI
scripts from your $HOME/public_html directory.
If you don't have that set up right now, you need to go
fetch Apache from http://www.apache.org, install it, and
configure it correctly. Cricket is only tested here at WebTV
with Apache, though it should work with other servers
that implement CGI correctly.

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.

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 ther web server error log. The
answer to what went wrong will almost certainly be in there.

12. 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 to a T3. (Well, we can always think big...)

13. The Next Step

Now that you are an expert, you should add 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 it and it will be included
in a future version of Cricket!

