\documentclass{ictlab}

% Copyright (c) 2003 by Nick Urbanik <nicku(at)nicku.org>.
% This material may be distributed only subject to the terms and
% conditions set forth in the Open Publication License, v1.0 or later
% (the latest version is presently available at
% http://www.opencontent.org/openpub/).

\RCS $Revision: 1.19 $

\usepackage{verbatim,key,alltt,amstext}
\usepackage[hang,bf,nooneline]{caption2}
\ifx\pdftexversion\undefined \else
  \usepackage[pdfpagemode=None,pdfauthor={Nick Urbanik}]{hyperref}
\fi

\newcommand*{\labTitle}{Configuring Cricket to Monitor SNMP Objects}
\providecommand*{\SNMP}{\acro{SNMP}\xspace}
\providecommand*{\MIB}{\acro{MIB}\xspace}
\providecommand*{\ID}{\acro{ID}\xspace}
\providecommand*{\OID}{\acro{OID}\xspace}
\providecommand*{\IOS}{\acro{IOS}\xspace}
\providecommand*{\FAQ}{\acro{FAQ}\xspace}
\providecommand*{\RPM}{\acro{RPM}\xspace}
\providecommand*{\MRTG}{\acro{MRTG}\xspace}
\providecommand*{\CPAN}{\acro{CPAN}\xspace}
\providecommand*{\RRD}{\acro{RRD}\xspace}
\providecommand*{\URL}{\acro{URL}\xspace}

\renewcommand*{\floatpagefraction}{0.75} % default is .5, to increase
% density.
\renewcommand*{\bottomfraction}{0.6} % default is 0.3
\renewcommand*{\topfraction}{0.85} % default is 0.7
\renewcommand*{\textfraction}{0.1} % default is 0.2


\begin{document}

\tableofcontents
%\Large
\subsection*{Background:}

There are two free software packages for monitoring \SNMP objects from
a web interface.

The most widely known is \MRTG, the ``Multi Router Traffic
Grapher\@.''  \MRTG is well suited to monitoring network traffic from
router interfaces, but has certain limitations in many other
situations.  Red Hat Linux comes with \MRTG as a ready-built software
package, and it is very easy to set it up to monitor network traffic.
See \url{http://people.ee.ethz.ch/~oetiker/webtools/mrtg/}.

The newer package is called \emph{Cricket}, and this is what we will
install and configure today.  Cricket has greater flexibility, and can
be extended in more ways.  Cricket is available from
\url{http://cricket.sourceforge.net/}.

Both packages are written mostly in Perl\@.  There are links to both
of these software packages from the subject web site.

\section{Procedure}

There are eight steps to install and configure Cricket, as I
demonstrated at the last lecture:
\begin{itemize}
\item install the necessary Perl modules using \CPAN
\item create a user called \texttt{cricket}
\item unpack the Cricket tarball and run the configure script
\item copy the sample configuration files into a directory called
  \texttt{cricket-config}
\item modify the configuration to point to what you want to monitor
\item configure \texttt{cron} to run the data collector
\item create a \texttt{public\_html} directory, and set up the
  programs in that directory
\item configure Apache so that it will run the programs
\end{itemize}

\subsection{Open the Documentation}
\label{sec:open-documentation}

\begin{enumerate}
\item Go to the Cricket installation web page at
\url{http://cricket.sourceforge.net/support/doc/beginner.html}.
\begin{explanation}
  You can get there from the main Cricket page by following these
  links: \emph{support} $\to$ \emph{documentation} $\to$
  \emph{Installing Cricket for the Complete Beginner}\@.
\end{explanation}
\end{enumerate}

\subsection{Installing the Necessary Perl modules}
\label{sec:perl-modules}

There are several Perl modules that Cricket requires.  Some of these
are already installed on your computer, some are not.  You will
install them with the \CPAN program, which downloads them from the
Internet, compiles, tests, then installs them if they pass all tests.

The modules to install from \CPAN include:
\begin{itemize}
\item MD5
\item DB\_File
\item Date::Parse
\item Time::HiRes
\item CGI
\item Net::SNMP
\end{itemize}


\subsubsection{Installing the Required Perl Modules from CPAN}

\begin{enumerate}
\item First, you need the \CPAN Perl module.  People who cloned their
  hard disk from mine will find that you need to install it:
  \begin{alltt}
$ \textbf{sudo rpm -Uhv \bs
  /home/nfs/rh-8.0-updated/RedHat/RPMS/perl-CPAN-1.61-55.i386.rpm}
  \end{alltt}%$
  \begin{explanation}
    As usual, use the \key{tab} key to complete the file name; I don't
    remember these version numbers myself, of course!
  \end{explanation}
\item Secondly, you need the development software package for the
  Berkeley Database system required to build \texttt{DB\_File}:
\begin{alltt}
$ \textbf{sudo rpm -Uhv \bs
/home/nfs/rh-8.0-updated/RedHat/RPMS/db4-devel-4.0.14-14.i386.rpm}
\end{alltt}%$
\item Start the \CPAN modules' \texttt{shell} method from your own
  (not \texttt{cricket}'s) account:
\begin{alltt}
$ \textbf{sudo perl -MCPAN -e shell}
\end{alltt}%$
\item The shell will begin its interactive configuration process.
  Accept all defaults by pressing \key{Enter}, \textbf{\emph{except
      for the following}}:
  \begin{itemize}
  \item When prompted ``\texttt{CPAN build and cache directory?}''
    enter: \texttt{/var/cache/cpan} \ Do not accept the default in
    your home directory; it will not work, since the \texttt{root}
    user has no right to write to your \acro{NFS} mounted home
    directory.
  \item When asked to choose a Policy on building prerequisites,
  choose ``\texttt{follow}'':
  \begin{alltt}
Policy on building prerequisites (follow, ask or ignore)? [ask] \textbf{follow}
  \end{alltt}
  \begin{explanation}
    Some Perl modules depend on others.  When installing a module that
    depends on others, a selection of ``\texttt{ask}'' here means the
    \CPAN shell will prompt you and require you to press \key{Enter}
    to install the prerequisite module.  The selection
    ``\texttt{follow}'' means, ``Don't ask me; just go ahead, download
    and install any modules that are needed to install this one''.
  \end{explanation}

  \item For ``\texttt{Your http\_proxy?}'' enter
    \texttt{http://hqproxy.vtc.edu.hk:8080/}

  \item When asked to pick a nearby continent, enter \texttt{5} to
    select \texttt{(5) North America} (Do not select
    \texttt{(2)~Asia}, \texttt{2} \texttt{ftp://\allowbreak
      ftp\allowbreak.pacific\allowbreak.net\allowbreak.hk\allowbreak
      /pub\allowbreak/mirror\allowbreak/CPAN/}, because like many Hong
    Kong mirror sites, it is not maintained properly)
  \item When asked to ``\texttt{Select your country}'', enter \texttt{3}
    to select \texttt{(3) United States}.
  \item When asked ``\texttt{Select as many URLs as you like}'', I
    suggest just enter the first few numbers (corresponding to the
    first few \URL{}s); I put ``\texttt{1 2 3 4 5 6 7}''.  The numbers
    are just separated by spaces.
%%     \texttt{ftp:\allowbreak//ftp\allowbreak
%%       .sunsite\allowbreak.utk\allowbreak.edu\allowbreak/pub\allowbreak/CPAN/},
%%     plus a few others from the list.
  \item Configuration should complete.
  \end{itemize}

\item Now, at the \verb|cpan> | prompt, type:
\begin{alltt}
cpan> \textbf{install MD5}
cpan> \textbf{install Date::Parse}
\ldots
\end{alltt}
and so on, installing all the six modules listed above.
\item For more information about the \CPAN software, type
  ``\texttt{help}''.  There is a manual page; type \texttt{perldoc
  CPAN}, or \texttt{man CPAN} to read it.
\end{enumerate}

% \subsubsection{Alternative Method for installing CPAN Perl Modules}

% There is a ``Bundle'' facility with \CPAN that allows you to download
% a bundle of software modules.  To use this bundle supplied with
% Cricket:
% \begin{enumerate}
% \item Open a terminal window as your own account

% \item Copy the bundle to the \texttt{/tmp} directory:
% \begin{alltt}
% $ \textbf{sudo cp -a ~cricket/cricket/lib/Bundle /tmp}
% \end{alltt}%$

% \item Now install the software modules specified in the bundle:
% \begin{alltt}
% $ \textbf{cd /tmp}
% $ \textbf{sudo perl -I. -MCPAN -e 'install Bundle::CricketPrereq'}
% \end{alltt}
%   \begin{explanation}
%     This will start a process that will download, complile, test and
%     install all the Perl modules listed above.
%   \end{explanation}
% \end{enumerate}


\subsubsection{Installing the other two Perl Modules}

The other two Perl modules are not available from \CPAN; see the
Cricket documentation for the location.  We start here assuming that
\texttt{ictlab} is mounted on \texttt{/home/nfs}.  I have set up
appropriate \emph{automounter} entries in our \LDAP directory server
so that when you change to or list this directory, it will mount the
network file system by \NFS.

Do this in your own account.

\paragraph{Installing SNMP\_Session:}

\begin{enumerate}
\item Unpack the \texttt{SNMP\_Session} tarball into your (not
  \texttt{cricket}'s) home directory:
\begin{alltt}
$ \textbf{cd}
$ \textbf{tar xvzf /home/nfs/snmp/SNMP_Session-0.94.tar.gz}
$ \textbf{cd SNMP_Session-0.94}
$ \textbf{perl Makefile.PL}
$ \textbf{make}
$ \textbf{sudo make install}
\end{alltt}
The \texttt{SNMP\_Session} Perl modules are now installed.
\begin{explanation}
  You can get the latest copy of this module from
  \url{ftp://ftp.switch.ch/software/sources/network/snmp/perl/}.  The
  web page is at \url{http://www.switch.ch/misc/leinen/snmp/perl/}.
\end{explanation}
\end{enumerate}

\paragraph{Installing the Round Robin Database:}

This is available as two \acro{RPM} packages, built from source
\RPM{}s downloaded from \url{http://rpmfind.net/linux/falsehope/home/gomez/rrdtool/rrdtool-1.0.39-1.7.2.src.rpm}.
\begin{enumerate}
\item Simply install using the \texttt{rpm} program:
\begin{alltt}
$  \textbf{sudo rpm -Uhv \bs
/home/nfs/redhat/contrib/rrdtool-*1.0.39-1.8.0.i386.rpm --nodeps}
\end{alltt}%$
\end{enumerate}

After this, all the required Perl packages are installed.


\subsection{Creating the \texttt{cricket} account}
\label{sec:cricket-account}

Here you create a local user.   You will install the software into the
home directory of this user.

\paragraph{Setting your path}
\label{sec:path}

\begin{enumerate}
\item Look at your path by typing:
\begin{alltt}
$ \textbf{echo $PATH}
\end{alltt}
\item If the directories \texttt{/sbin} and \texttt{/usr/sbin} are not
  already on your path, add them:
  \begin{enumerate}
  \item edit your login script:
\begin{alltt}
$  \textbf{emacs \(\sim\)/.bash_profile &}
\end{alltt}%$
  \item Add a line like this at the end of your login script:
\begin{alltt}
export PATH=$PATH:/sbin:/usr/sbin
\end{alltt}%$
  \item Copy and paste this line into your terminal window.
  \end{enumerate}
\end{enumerate}

\paragraph{Now create the \texttt{cricket} account:}

\begin{enumerate}
\item Make sure that your \texttt{useradd} program is configured to
  create local accounts (see the handout I wrote about this for more
  information):
\begin{alltt}
$ \textbf{sudo mkdir /home2}
$ \textbf{sudo useradd -D -b /home2}
\end{alltt}

\item Create a local user \texttt{cricket}:
\begin{alltt}
$ \textbf{sudo useradd -c "Cricket Manager" cricket}
\end{alltt}%$

\item Give this user a password:
\begin{alltt}
$ \textbf{sudo passwd cricket}
\end{alltt}%$
\end{enumerate}


\subsection{Unpacking Cricket and running \texttt{configure}}
\label{sec:unpacking-cricket}

The Cricket tarball is available for download either from the Cricket
web site, or you can install it directly from our server:
\begin{enumerate}
%% \item mount the server:
%% \begin{alltt}
%% $ \textbf{sudo mkdir /mnt/nfs}
%% $ \textbf{sudo mount nicku.org:/var/ftp/pub /mnt/nfs}
%% \end{alltt}

\item Open a window and become \texttt{cricket}:
\begin{alltt}
$ \textbf{xhost +localhost}
$ \textbf{su - cricket}
\end{alltt}
  \begin{explanation}
    The first command lets other users besides you (such as
    \texttt{cricket}) display on the local X server.

    The minus sign `\texttt{-}' runs \texttt{cricket}'s login
    scripts.
  \end{explanation}
  
\item Change to \texttt{cricket}'s home directory and unpack the
  Cricket tarball:
\begin{alltt}
$ \textbf{cd}
$ \textbf{tar xvzf /home/nfs/snmp/cricket-1.0.3.tar.gz}
\end{alltt}

\item Now create a symbolic link to the Cricket directory:
\begin{alltt}
$ \textbf{ln -s cricket-1.0.3 cricket}
\end{alltt}%$

\item Now run the \texttt{configure} script, which puts the path to
  \texttt{perl} in the first line of the Perl programs:
\begin{alltt}
$ \textbf{cd \(\sim\)/cricket}
$ \textbf{./configure}
\end{alltt}

\item Now copy the file \texttt{cricket-conf.pl.sample} to
  \texttt{cricket-conf.pl}:
\begin{alltt}
$ \textbf{cd \(\sim\)/cricket}
$ \textbf{cp cricket-conf.pl.sample cricket-conf.pl}
\end{alltt}
%   \begin{explanation}
%     If you use different names from what I have shown here, you may
%     need to edit this file.
%   \end{explanation}
  
\item Edit the file $\sim$\texttt{/cricket/cricket-conf.pl}, and
  change the line:
\begin{alltt}
$gCricketHome = "/home/cricket";
\end{alltt}
to
\begin{alltt}
$gCricketHome = "/home2/cricket";
\end{alltt}
\end{enumerate}


\subsection{Copy the Config Tree and Modify it}
\label{sec:copy-config-tree}

Cricket uses a directory of configuration files that the authors call
a \emph{config tree}.  Here we copy the sample config tree, and modify
it.
\begin{enumerate}
\item First copy the sample tree as the user \texttt{cricket}:
\begin{alltt}
$ \textbf{cd}
$ \textbf{cp -a cricket/sample-config cricket-config}
\end{alltt}

\item Now copy the configuration that I wrote for the demonstration in
  the lecture theatre.  Here I assume that \texttt{ictlab} is mounted
  on \texttt{/home/nfs}.
\begin{alltt}
$ cd \(\sim\)/cricket-config
$ cp -a /home/nfs/snmp/servers .
#      This is a dot __________^
\end{alltt}
  \begin{explanation}
    There are two files in this directory: \texttt{Defaults} and
    \texttt{Targets}\@.  These tell Cricket to monitor the system load
    on our server \texttt{ictlab}, and also the amount of free swap
    space, and the amount of free memory.  You will later need to
    modify the config tree to monitor other devices.

    If you copied the two files from \texttt{/home/nfs/snmp/servers}
    into $\sim$\texttt{/cricket-config} instead of into the directory
    $\sim$\texttt{/cricket-config/servers}, then the collector will
    not work.  If you have done this, simply go back and copy the
    sample configuration files back again.
  \end{explanation}

\item Every time you modify the config tree, you need to run the
  \texttt{compile} script (as the user \texttt{cricket}):
\begin{alltt}
$ \(\sim\)/cricket/compile
\end{alltt}%$

\item Cricket collects data from data sources using a script called
  the \texttt{collector}.  This will be run by \texttt{cron}.  First,
  check that the config tree has been set up correctly:
\begin{alltt}
$ \(\sim\)/cricket/collector /servers
\end{alltt}%$
  This should run without errors, and five data items should be shown:
  the three values for system load, and the free swap space in
  kilobytes, and free memory.
\end{enumerate}


\subsection{Adding a \texttt{cron} entry for Cricket}
\label{sec:cron}

Cricket collects the information it graphs using \texttt{cron}, every
five minutes.  To use \texttt{cron} to gather the information for
Cricket, you need to add an entry to \texttt{cricket}'s crontab like
this.  First, you need to be \texttt{cricket}.
\begin{enumerate}
\item The \texttt{cron} program collects information about the network
  periodically using script called \texttt{collect-subtrees}.  This
  script reads a configuration file $\sim$\texttt{cricket/\allowbreak
    cricket/\allowbreak subtree-sets}.  Edit this file:
\begin{alltt}
$ emacs \(\sim\)/cricket/subtree-sets &
\end{alltt}%$

\item Add a new \texttt{set} to it like this:
\begin{alltt}
set linuxservers:
        /servers
\end{alltt}
  \begin{explanation}
    The script \texttt{collect-subtrees} takes one parameter, the
    \emph{set} of data to collect.  Here our set is called
    \texttt{linuxservers} so we use that parameter in our
    \texttt{cron} entry.
  \end{explanation}

\item Start editing \texttt{cricket}'s crontab:
\begin{alltt}
$ \textbf{crontab -e}
\end{alltt}%$

\item In the editor, you need to add an entry like this:
\begin{alltt}
*/5 * * * * $HOME/cricket/collect-subtrees linuxservers
\end{alltt}%$
  which will run the program \texttt{\$HOME/\allowbreak
    cricket/\allowbreak collect-subtrees
    linuxservers}\linebreak[4] \mbox{every} five minutes.
\end{enumerate}


\subsection{Setting up the \texttt{public\_html} directory in \texttt{cricket}'s home directory
  for Apache}
\label{sec:links}

I found it necessary to make a minor change from the instructions for
putting the \acro{CGI} programs in the \texttt{public\_html}
directory.  This is what I did, as the user \texttt{cricket}:
\begin{alltt}
$ cd
$ mkdir -p public_html/cricket
$ cd public_html/cricket
$ ln -s \(\sim\)/cricket/VERSION
$ ln \(\sim\)/cricket/grapher.cgi .
$ ln \(\sim\)/cricket/mini-graph.cgi .
$ ln -s \(\sim\)/cricket/lib \(\sim\)/cricket/images .
# Note: this is a dot ------------------^
\end{alltt}%$
The only difference is that I made a \emph{hard link}, rather than a
\emph{symbolic link}, to the \acro{CGI} programs.

\label{sec:doc-link}%
I have also added a link to the documentation, so that you can easily
read it online:
\begin{alltt}
$ ln -s \(\sim\)/cricket/doc \(\sim\)/public_html
\end{alltt}%$
You can read the Cricket documentation at
\url{http://localhost/~cricket/doc/} after you have set up
Apache---see the next section.


\subsection{Configuring the Apache Web Server}
\label{sec:completing}


Now configure Apache to run Cricket:
\begin{enumerate}
\item Edit Apache's configuration file:
\begin{alltt}
$ \textbf{sudo -v}
$ \textbf{sudo emacs /etc/httpd/conf/httpd.conf &}
\end{alltt}
\item Search for the string ``\texttt{UserDir}'' in your editor
\item Comment out the line
  \begin{alltt}
    UserDir disable
  \end{alltt}
  by putting a hash ``\texttt{\#}'' in front of it:
  \begin{alltt}
    #UserDir disable
  \end{alltt}
  and \emph{un}comment the line
  \begin{alltt}
    UserDir public_html
  \end{alltt}
  by \emph{removing} the hash character.

\item Search for the ``Directory'' section for \texttt{public\_html}.

\item If the section is commented out, copy it and uncomment the copy.
  
\item You need to add the option \texttt{ExecCGI}, and should end up
  with something like this:
\begin{alltt}
<Directory /home2/*/public_html>
   Options MultiViews Indexes SymLinksIfOwnerMatch ExecCGI
</Directory>
\end{alltt}
  \begin{explanation}
    Note that the manual for Apache is included on your hard disk.
    When Apache is running, you will find it at this location:
    \url{http://localhost/manual/}.  The manual is very complete, and
    explains every possible configuration option of Apache\@.
  \end{explanation}

\item You also need to uncomment the line in Apache's configuration
  file:
\begin{alltt}
AddHandler cgi-script .cgi
\end{alltt}

\item Note too that \texttt{cricket}'s home directory, and
  $\sim$\texttt{cricket\allowbreak/public\_html}, and
  $\sim$\texttt{cricket\allowbreak/public\_html\allowbreak/cricket}
  all need to have the group write permission removed, but the execute
  permission added for group and others.  This is to satisfy the
  requirements of \texttt{suexec}, which is the mechanism by which
  Apache executes Cricket's programs as the user \texttt{cricket}.
  \begin{explanation}
    The complete documentation for \texttt{suexec} is included with
    the online \texttt{Apache} documentation on your hard disk.

    Okay, it seems nobody understands that, so here's the recipe:
\begin{alltt}
$ chmod go=x \(\sim\)
$ chmod go=rx \(\sim\)/cricket \(\sim\)/public_html \(\sim\)/public_html/cricket
\end{alltt}
The permissions should look something like this:
{\scriptsize%
\begin{alltt}
$ \textbf{ls -ldL \(\sim\) \(\sim\)/cricket \(\sim\)/public_html \(\sim\)/public_html/cricket}
drwx--x--x    7 cricket  cricket      4096 Dec 18 13:44 /home2/cricket
drwxr-xr-x    7 cricket  cricket      4096 Dec 11 17:21 /home2/cricket/cricket
drwxr-xr-x    2 cricket  cricket      4096 Dec 11 17:55 /home2/cricket/public_html
drwxr-xr-x    2 cricket  cricket      4096 Dec 11 17:55 /home2/cricket/public_html/cricket
\end{alltt}}%$
You could remove write permission for group from all the files like this:
  \begin{alltt}
$ \textbf{chmod -R g-w \(\sim\)}
  \end{alltt}%$
  which will remove the write permission for group of all files below
  \(\sim\)\texttt{/public\_html}.
  \end{explanation}

\item You can use the \texttt{serviceconf} program to start Apache's
  \texttt{httpd} service in runlevels 3, 4 and 5.
  \begin{explanation}
    Alternatively you can use the same method to start and maintain
    the Apache service as with \texttt{nscd} given on
    page~\pageref{sec:nscd}.
\begin{alltt}
$ \textbf{sudo service httpd start}
$ \textbf{sudo chkconfig --level 345 httpd on}
\end{alltt}
  \end{explanation}
\end{enumerate}


\paragraph{Testing, and using the log files:}

\begin{enumerate}
\item Now open a web browser, and go to
  \url{http://localhost/~cricket/cricket/grapher.cgi}

\item If you see a server error message:
  \begin{enumerate}
  \item View the log files for Apache to see what is happening.  I
  suggest change the group ownership of the log file directory to you,
  so that you can see the files without being root:
  \begin{alltt}
$ \textbf{ls -ld /var/log/httpd}
drwx------    2 root     root         4096 Oct 31 17:52 /var/log/httpd
$ \textbf{sudo chgrp nicku /var/log/httpd}
$ \textbf{sudo chmod g+rx /var/log/httpd}
$ \textbf{ls -ld /var/log/httpd}
drwxr-x---    2 root     nicku        4096 Oct 31 17:52 /var/log/httpd
  \end{alltt}
  Now change to the web server's log directory and examine the logs:
  \begin{alltt}
$ \textbf{cd /var/log/httpd}
$ \textbf{ls -ltr}
$ \textbf{tail -f error_log}
  \end{alltt}%$
  
  \item You may also want to open two more windows, and leave them
    open, running \texttt{tail -f} on \texttt{suexec\_log} and
    \texttt{access\_log}.  In particular, monitoring
    \texttt{suexec\_log} will let you know about permission problems
    when accessing the programs.

  \item After modifying Apache's configuration, tell Apache to reload
    it:
\begin{alltt}
$ \textbf{sudo service httpd graceful}
\end{alltt}%$
  \end{enumerate}
  
\item If you see the Cricket page, click on \textsf{servers}, then
  \textsf{load}, and you should see the graphs of system load there.
\end{enumerate}


\section{Adding a new set of Graphs and Targets for Cricket to
  Monitor}
\label{sec:Adding-a-new-set-of-Graphs-and-Targets-for-Cricket-to-Monitor}

Now this is where you use your knowledge of \SNMP.  Refer to the page
\emph{Setting up New Devices in Cricket}, at
\url{http://cricket.sourceforge.net/support/doc/new-devices.html}, or
\url{http://localhost/~cricket/doc/new-devices.html} if you make the
link I described at the end of section~\vref{sec:doc-link}.  There is
a useful set of configurations in
\url{http://www.gnac.com/techinfo/cricket_contrib/index.html}.  The
reference for the configuration of Cricket is at
\url{http://cricket.sourceforge.net/support/doc/reference.html}.

Cricket has a very active mailing list for users, about ten posts per
day.  I had an perfect solution to my problem in less than two hours.
The subscription information is available at
\url{http://cricket.sourceforge.net/support/}.

\subsection{Cricket's Configuration Tree}
\label{sec:configuration-tree}

The directory $\sim$\texttt{/cricket-config} contains a directory
tree.  This directory tree contains the configuration of cricket.  It
is called a ``config tree'' because the configuration files at the
higher levels provide default values, and some of these values are
overridden by the configuration files at the lower levels.

Every directory in $\sim$\texttt{/cricket-config} contains a file
called \texttt{Defaults}\@.  

The top level configuration file,
$\sim$\texttt{/cricket-config\allowbreak/Defaults}, contains a very
large number of useful definitions.  In particular, it is set up so
that all you need to plot network traffic is in place.  The \OID{}s
are provided for all the useful items in the Mib-2 Interfaces table.
Look at this file; you will see that the default graphs are graphs
of network traffic in and out of a network interface.

Each chunk of the file begins with a word such as ``\texttt{target}''
or ``\texttt{OID}''.  After that word, they are different, but you
will see many things such as \\
\texttt{rrd-datafile =
  \%dataDir\%/\%auto-target-name\%.rrd}.\\
The percent signs indicate a variable that is expanded somewhere else
in the configuration tree.  Many of these variables have reasonable
defaults that are defined at the top level of the tree.  You only need
to fill in the values for some (such as the hostname of the target)
further down in the config tree.

\subsubsection{A Closer Look at the Config Tree}
\label{sec:closer-look-at-config-tree}

The configuration is divided into \emph{dictionaries}.  Below some
dictionaries, there are \emph{tags} and \emph{values}, arranged like
this:
\begin{alltt}
\(dictionary-name\)
    \(tag1\) = \(value1\)
    \(tag2\) = \(value2\)
    ...
\end{alltt}
These are the dictionaries available:
\begin{description}
\item[target] A device that we monitor is a target.  There is one \RRD
  file for each target.
\item[datasource] A Data source is one line on a graph.  One \RRD can
  have many datasources in it.  All datasources in one \RRD need to be
  updated by the collector at once.
\item[targetType] Determines what kinds of data sources there are for
  the target with this targetType.  The collector uses the targetType
  to decide what data to fetch, and how to fetch it.
\item[graph] Determines how individual data sources are graphed.
\item[color] Maps colour names to \HTML colours.  Probably no need to
  change this.
\item[oid] Maps an \OID to a name
\item[html] determines what \HTML goes into each page
\item[event] draws vertical bars on the graph to indicate events, such
  as the end of one day and the start of the next.  No need to change
  this.
\item[rra] Holds parameters used by Cricket when creating a new \RRD
  file.  No need to change this.
\end{description}


\subsection{The servers subtree}

Let us consider how the configuration for \texttt{/servers} works

I decided to monitor the system load average and the available free
memory.

There are five \emph{data sources} here, three for the load averages,
one for available swap, and one for free memory.  These are listed
under the \texttt{targetType} dictionary name.

\subsubsection{Variable Expansion}

When the collector gets the system load data from \texttt{ictlab}, it
uses an \SNMP \URL something like this:

\url{snmp://public@nicku.org:161:2.0:5:1.0:1/1.3.6.1.4.1.2021.10.1.3.1}

But where did all that come from?

Let's look in the Target dictionary in the top level
$\sim$\texttt{/cricket-config/Defaults} file:
\begin{alltt}
Target    --default--
    snmp-host           = %auto-target-name%
    snmp-community      = public
    snmp-port           = 161
    snmp-timeout        = 2.0
    snmp-retries        = 5
    snmp-backoff        = 1.0
    snmp-version        = 1
    snmp                = %snmp-community%@%snmp-host%:%snmp-port%:
%snmp-timeout%:%snmp-retries%:%snmp-backoff%:%snmp-version%
\end{alltt}
So what about \texttt{\%auto-target-name\%}?  This is automatically
set by Cricket to the name of the target.  So let's see part of the
file $\sim$\texttt{/cricket-config/servers/Targets}:
\begin{alltt}
target  nicku.org
    target-type =   linux-machine
\end{alltt}
Finally, let's see how the \OID and the data source is defined in $\sim$\texttt{/cricket-config\allowbreak/servers\allowbreak/Defaults}:
\begin{alltt}
OID     laLoad1min  1.3.6.1.4.1.2021.10.1.3.1
datasource  laLoad1min   ds-source   =   snmp://%snmp%/laLoad1min
\end{alltt}
So default values mostly come from the top level of the configuration
tree and are inherited below. You can override any default defined at
the top level with values you define further down.

\subsection{Tables and Instance Numbers}
\label{sec:instance-numbers}

We examined the Interfaces table of Mib-2 in some detail.  Each row in
the table corresponds to one network interface.  How do we use \SNMP
to \texttt{get} information on a particular network interface?  Let's
look at \texttt{ifInOctets}, in the \MIB file
\texttt{/usr\allowbreak/share\allowbreak/snmp\allowbreak
  /mibs\allowbreak/RFC1213-MIB.txt}\@.  The definition of
\texttt{ifInOctets} is:
\begin{alltt}
ifInOctets OBJECT-TYPE
    SYNTAX  Counter
    ACCESS  read-only
    STATUS  mandatory
    DESCRIPTION
            "The total number of octets received on the
            interface, including framing characters."
    ::= { ifEntry 10 }
\end{alltt}
Let's get the \OID of this table entry:
\begin{alltt}
$ \textbf{snmptranslate -IR -Of ifInOctets}
.1.3.6.1.2.1.2.2.1.10
\end{alltt}%$
Good, now let's see the value on \texttt{ictlab}:
\begin{alltt}
$ \textbf{snmpwalk -c public ictlab .1.3.6.1.2.1.2.2.1.10}
interfaces.ifTable.ifEntry.ifInOctets.1 = Counter32: 752366405
interfaces.ifTable.ifEntry.ifInOctets.2 = Counter32: 791891118
\end{alltt}%$
Hey, there are two of them!  What are they?  Well, Mib-2 provides a
description of the interface in \texttt{ifDescr}; let's see what that
says:
\begin{alltt}
$ \textbf{snmpwalk -c public ictlab ifDescr}              
interfaces.ifTable.ifEntry.ifDescr.1 = lo
interfaces.ifTable.ifEntry.ifDescr.2 = eth0
\end{alltt}%$
Okay, so the entries in the \texttt{ifTable} with a \texttt{.1} at the
end on \texttt{ictlab} relate to the loopback interface, while the
entries with a \texttt{.2} at the end are about the Ethernet
interface.

This number at the end of the \OID is called an \emph{instance
  number}, and is the way that \SNMP selects items from a table.
Notice that the instance numbers begin at 1 for table entries.  What
  about for scalars?
\begin{alltt}
$ \textbf{snmpwalk -c public ictlab sysUpTime}
system.sysUpTime.0 = Timeticks: (103614809) 11 days, 23:49:08.09
\end{alltt}%$
The instance number for a scalar is always zero.

Typically, the loopback interface is the first entry in the table, and
other interfaces follow.  However, \SNMP does not prevent a router
from changing the order of the interfaces.  This could be a real
problem; after rebooting a router, you may find that the graph for
your subnet is now collecting data for a different subnet!  Luckily,
Cricket has a solution to this called \emph{instance mapping},
described in
\url{http://cricket.sourceforge.net/support/doc/inst-mapping.html}.

It is also possible to directly provide a value for the instance
number for a target to graph, instead of using instance mapping.  For
example, you could set
\begin{alltt}
target \emph{hostname-of-server-or-router}
    inst = 2
\end{alltt}
to draw graphs of interface two of the machine called
\emph{hostname-of-server-or-router}.

\subsubsection{The \texttt{listInterfaces} Utility}
\label{sec:listinterfaces}

A very nice Cricket utility is provided to automatically find the
names of all the interfaces on a server or router, then map each name
to an instance number.  This is described in
\url{http://cricket.sourceforge.net/support/doc/beginner.html}.  The
name of the utility is \texttt{listInterfaces}.  If
\texttt{main-router} is the hostname of a server or router that you
want to plot statistics of the network interfaces from, you can do:
\begin{alltt}
$ \(\sim\)/cricket/util/listInterfaces main-router > interfaces
\end{alltt}%$
The file \texttt{interfaces} can then be used in the
$\sim$\texttt{/cricket\allowbreak/cricket-config\allowbreak
  /router-interfaces} directory to specify how to plot each interface.
All that is left is simply to put an entry in \texttt{subtree-sets} so
that the collector will collect the data from the server or router,
and then run the \texttt{compile} script.  Cricket provides enormous
flexibility once it is set up.

\subsection{Monitoring High-End Cisco Switches: the \texttt{genCatConfig} Utility}

To monitor high-end Cisco Catalyst$^{\text{TM}}$ switches, such as our
6509 (but not Cisco Catalyst 3500XL switches), 
there is a tool available for automatically generating the
configuration for Cricket\@.  It is currently available from
\url{http://www.certaintysolutions.com/tech-advice/cricket-contrib/}; you can
download the program from that page.  Note that all these programs are
available from our own server \texttt{ictlab}, by many protocols,
including
\url{http://nicku.org/ftp/snmp/cricket-contrib}, and by
\NFS from
\texttt{ictlab\allowbreak:/var\allowbreak/ftp\allowbreak/pub\allowbreak/snmp}.

Read the file $\sim$\texttt{/cricket/util/README.genCatConfig} for
the full documentation; this is just a short summary.  To install it,

\begin{itemize}
\item become \texttt{cricket}, and 
\item untar the package into
\texttt{/tmp}.  Then 
\item copy the directory
\texttt{/tmp/sample-config/catalysts} and its
contents into $\sim$\texttt{/cricket-config}.  
\item Copy the contents of
\texttt{/tmp/util} into
$\sim$\texttt{/cricket/util}.
\item Edit the two executables and change the first line in each file
  from
\begin{verbatim}
#!/usr/local/bin/perl
\end{verbatim}
to
\begin{verbatim}
#! /usr/bin/perl
\end{verbatim}
\item Make a host table entry for the router
in \texttt{/etc/hosts}.  
\item Change directory to $\sim$\texttt{/cricket-config/catalysts}
\item Then run
\begin{alltt}
$ \textbf{\(\sim\)/cricket/util/genCatConfig -2 -v -C \meta{community-string} \meta{router-hostname}}
\end{alltt}%$
\sloppypar{}replacing \meta{router-hostname} with the host name of the
Catalyst router that you put into the \texttt{/etc/hosts} file, and
\meta{community-string} with its read-only community string.

\item Add \texttt{/catalysts/\emph{router-hostname}} to Cricket's
  \texttt{subtree-sets} file.
\item Run $\sim$\texttt{/cricket/compile}.  It should now collect
  data.  Test it using the collector.
\end{itemize}


\subsection{Monitoring 35xx Cisco Switches and Routers}
\label{sec:35xx-cisco}

According to the genCatConfig documentation:
\begin{quote}
  Some Catalysts (e.g.  2900XL and 3500XL switches) run router \IOS and
  respond to a different set of \MIB{}s.  They should be handled as
  routers, not switches.  (see \texttt{genRtrConfig}).
\end{quote}
So download \texttt{genRtrConfig} from the same place as
\texttt{genCatConfig} above.  The installation process is similar, but
not identical.  In particular, the Cisco 3500XL series does not
support the 64 bit counters, so we have to use \SNMP version 1!  Here
is how to do it:
\begin{enumerate}
\item as \texttt{cricket}, untar the package into \texttt{/tmp}:
  \begin{alltt}
$ \textbf{cd /tmp}
$ \textbf{tar xvzf /home/nfs/snmp/genRtrConfig-1.4.tar.gz}
  \end{alltt}
\item Copy the directory \texttt{/tmp/sample-config/cisco-routers} and
  its contents to $\sim$\texttt{/cricket-config}:
\begin{alltt}
$ \textbf{cp -a /tmp/sample-config/cisco-routers \(\sim\)/cricket-config}
\end{alltt}%$
\item Copy the contents of
\texttt{/tmp/util} to $\sim$\texttt{/cricket/util}:
\begin{alltt}
$ \textbf{cp -a /tmp/util/* \(\sim\)/cricket/util}
\end{alltt}%$
\item Edit \(\sim\)\texttt{/cricket/util/genRtrConfig} and change the
  first line from \texttt{\#!/usr/local/bin/perl} to
  \texttt{\#!/usr/bin/perl}
\item Make a host table entry for the switch in \texttt{/etc/hosts}.
\item Change directory to
  \(\sim\)\texttt{/cricket-config/cisco-routers} and run the program
  \texttt{genRtrConfig} like this:
  \begin{alltt}
$ \textbf{\(\sim\)/cricket/util/genRtrConfig -C \meta{community-string} --chassis \bs
--ciscoint -v \meta{hostname-of-switch}}
  \end{alltt}%$
\item Add \texttt{/cisco-routers/\meta{switch-hostname}} to Cricket's
  \texttt{subtree-sets} file.
\item Run $\sim$\texttt{/cricket/compile}.  It should now collect
  data.  Test it using the collector.
\end{enumerate}

\subsection{Running the Name Service Caching Daemon}
\label{sec:nscd}

In the past, some people experienced problems unless the name service
caching daemon (\texttt{nscd}) is running on their machines.  This
service is very important to reduce the load on our \LDAP server, and
will improve the performance of your machine also, and should always
be turned on.  To turn on \texttt{nscd}:
\begin{enumerate}
\item First, start it now:
\begin{alltt}
$ \textbf{sudo service nscd start}
\end{alltt}%$
  
\item Now make sure that it always starts as a service when the
  computer boots:
\begin{alltt}
$ \textbf{sudo chkconfig --level 345 nscd on}
\end{alltt}%$
This turns the \texttt{nscd} service on in runlevels 3, 4 and 5.

\item Finally, verify that the service is configured correctly:
\begin{alltt}
$ \textbf{chkconfig nscd --list}
nscd            0:off   1:off   2:off   3:on    4:on    5:on    6:off
\end{alltt}%$
If you do not see ``\texttt{on}'' for runlevels 3, 4 and 5, something
is wrong (perhaps a typing mistake?)
\end{enumerate}


\subsection{Installing the Red Hat Updates}
\label{sec:installing-updates}

You will also benefit by installing the Red Hat Linux updates.  These
are in the directory \texttt{/home/nfs/redhat-8.0/updates} on
\texttt{ictlab}, assuming \texttt{ictlab:/var/ftp/pub} is mounted on
\texttt{/home/nfs}.  You can install them like this:
\begin{alltt}
$ \textbf{cd /home/nfs/redhat-8.0/updates/i686}
$ \textbf{sudo rpm -Fhv *.rpm}
$ \textbf{cd ../i386}
$ \textbf{sudo rpm -Fhv *.rpm ../noarch/*.rpm}
\end{alltt}

\end{document}