Re: "Installing Cricket for the Complete Beginner" documentation patch :-)
Sam Hooker <[email protected]> Mon, 18 May 2009 13:59:16 -0400 (EDT)
| Newsgroups | gmane.network.cricket.user |
|---|---|
| Message-ID | <1661129694.611242669556899.JavaMail.root@malcolm> |
------=_Part_39_56446803.1242669556895 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 7bit Sorry for any confusion caused by my last post, which appears to have arrive w/o its attachment. There should be two files attached to this one: a text file in "diff -Naur" format, and an HTML file. Cheers, -sth sam hooker|[email protected]|http://www.noiseplant.com Are you satisfied? ([y]/n): ----- "Timothy Rand" <[email protected]> wrote: > Yes, although it would not open by just clicking on it. I had to > tell Windows XP to use firefox to view it. XP is probably confused > by the name of the attachment "beginner.html.patch" > > > -----Original Message----- > From: Sam Hooker [mailto:[email protected]] > Sent: Monday, May 18, 2009 10:24 AM > To: Timothy Rand > Subject: Re: [cricket-users] "Installing Cricket for the Complete > Beginner" documentation patch :-) > > > Hi Tim, > > Thanks for letting me know. I'll try w/o the GPG signature. Can you > see an attachment to this email? > > > Cheers, > > -sth > > sam hooker|[email protected]|http://www.noiseplant.com > > Are you satisfied? ([y]/n): > > ----- "Timothy Rand" <[email protected]> wrote: > > > Thanks Sam - > > The patch was not attached to your email > > - Tim > > > > -----Original Message----- > > From: Sam Hooker [mailto:[email protected]] > > Sent: Monday, May 18, 2009 8:49 AM > > To: [email protected] > > Subject: [cricket-users] "Installing Cricket for the Complete > > Beginner" documentation patch :-) > > > > -----BEGIN PGP SIGNED MESSAGE----- > > Hash: SHA1 > > > > > > Hi there, > > > > Thanks to the folks that maintain the Cricket documentation: it's > > quite helpful. I was running through "Installing Cricket for the > > Complete Beginner" today, and noted a few grammatical errors, along > > > with a little formatting inconsistency that might make it tough for > > > someone who's a newbie sysadmin (as opposed to just a newbie > Cricket > > users) to grok. I've attached a patch with some proposed changes > that > > 1) straighten up some apparent typos and 2) try to make the "text > > decoration" style a little more internally-consistent. (I attempted > to > > follow the standard used by O'Reilly and other publishers of > technical > > books, to achieve more "newbie-friendliness" through familiarity.) > > > > While I tried to steer clear of "editorializing" about style, tone, > > > and voice (which I found to be generally good), the patch also > > includes some small changes in construction, aimed at clarifying a > few > > minor awkwardnesses and increasing encouragement of The Serious > > Newb(tm). ;-) My feelings will be unhurt if these are rejected. > > > > Finally, I disclaim any warranty of perfection, as 1) I'm human, > and > > 2) I did this during a very short break at work. Thanks to the > Cricket > > team and community for maintaining a great tool! > > > > > > Cheers, > > > > - -sth > > > > sam hooker|[email protected]|http://www.noiseplant.com > > > > Are you satisfied? ([y]/n): > > > > -----BEGIN PGP SIGNATURE----- > > Version: GnuPG v1.4.8 (Darwin) > > Comment: Use GnuPG with Firefox : http://getfiregpg.org (Version: > > 0.7.5) > > > > iEYEARECAAYFAkoRg1UACgkQX8KByLv3aQ1CeQCfSVc/hd5rVqTfoxAZ0znCih2Y > > aM4AoNFrL76t52EE2N+wzWksDTpzvvHj > > =+Tnr > > -----END PGP SIGNATURE----- ------=_Part_39_56446803.1242669556895 Content-Type: text/plain; name=beginner.html.patch.txt Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=beginner.html.patch.txt --- beginner.html 2009-05-18 10:34:16.000000000 -0400 +++ proposed-beginner.html 2009-05-18 11:28:10.000000000 -0400 @@ -11,7 +11,7 @@ installation of Cricket up and running. </p> <p> - If you follow the steps below carefully, you will have a a minimal + If you follow the steps below carefully, you will have 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 @@ -19,12 +19,12 @@ </p> <ol> <li> - Insure you have the right version of Perl. + Ensure 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 + 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 @@ -33,7 +33,7 @@ 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). + counterparts (i.e. Windows' <TT>xcopy</TT> can replace Unix's <TT>cp -r</TT>). </li> <li> <p> @@ -57,7 +57,7 @@ when installing RRD! </p> <p> - Modules marked with CPAN come from the Comprehensive Perl + 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: @@ -67,14 +67,14 @@ </p> <p> You may also be able to use CPAN.pm to quickly and easily - install modules. Type "perldoc CPAN" to learn more about + install modules. Type <TT>perldoc CPAN</TT> 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' +% <B>cd cricket/lib</B> +% <B>perl -I. -MCPAN -e 'install Bundle::CricketPrereq'</B> </pre> </li> <li> @@ -95,7 +95,7 @@ hole on your system. </p> <p> - If you use a dedicated user for Cricket make certain that + 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. @@ -105,23 +105,23 @@ </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 + Extract the tarfile and run configure. (You may have + already done this, since you're reading this file.) Please + be 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 - +% <B>cd ~cricket</B> +% <B>gunzip -c cricket-1.0.0.tar.gz | tar xvf -</B> </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 +% <B>cd ~cricket/cricket-1.0.0</B> +% <B>sh configure</B> </pre> <p> This will fix the Perl scripts to work in your @@ -131,32 +131,32 @@ <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 + 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 +% <B>cd ~cricket</B> +% <B>ln -s cricket-1.0.0 cricket</B> </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 + <I>$HOME/cricket</I>, 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 + and edit it. You will need to set <TT><I>$gCricketHome</I></TT> 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 + other things). The <TT><I>$gInstallRoot</I></TT> variable should point + to the location of the Cricket scripts. We recommend that + you 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 + the instructions so far, <TT><I>$gInstallRoot</I></TT> will be set correctly without changing the sample, so cricket-conf.pl will contain these two lines: </p> @@ -177,12 +177,12 @@ <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 + tree from the Cricket distribution to $HOME/cricket-config. You can use </p> <pre> -% cd ~cricket -% cp -r cricket/sample-config cricket-config +% <B>cd ~cricket</B> +% <B>cp -r cricket/sample-config cricket-config</B> </pre> <p> but the parts of the tree you won't be using immediately @@ -196,7 +196,7 @@ <li> <p> Setup the routers subtree. Go into the routers tree and - look at the targets file. This is where you want to tell + look at the Targets file. This is where you want to tell Cricket which router to talk to. </p> <p> @@ -222,7 +222,7 @@ 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 + <I>/etc/hosts</I>) 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. @@ -246,15 +246,21 @@ </p> <p> Comment out the other target in that file (main-router) - using the Cricket comment symbol "#". + using the Cricket comment symbol <TT>#</TT>, like so: </p> + <PRE> +<B>#</B> target main-router +<B>#</B> target-type=Cisco-7500-Router +<B>#</B> short-desc = "Main router" + + </PRE> <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 + 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 @@ -276,10 +282,10 @@ compile it. Storing it in a compiled form makes accessing it quicker and easier. Do this: </p> - <pre>% ~/cricket/compile</pre> + <pre>% <B>~/cricket/compile</B></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 + If the compile command gives you any errors, stop at this + point and fix the problem. This is a good time 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 @@ -291,7 +297,7 @@ run the collector by hand on just this subtree first to see if there were any errors. </p> - <pre>% ~/cricket/collector /routers</pre> + <pre>% <B>~/cricket/collector /routers</pre></B> <p> You should see something like this on screen, though this example was wrapped by hand for readability: @@ -304,9 +310,9 @@ [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. + You can add the arguments <TT>-logLevel debug</TT> at the end + of the command-line to get more information that helps in + solving problems. </p> </li> <li> @@ -314,25 +320,25 @@ 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. + avoid the grunt work. This tool is called <TT>listInterfaces</TT>, + and it comes in the <I>util</I> directory. </p> <p> - listInterfaces one or two arguments. It must have a router + <TT>listInterfaces</TT> takes 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, + When you run <TT>listInterfaces</TT> against a router, it will + print a Cricket config to its standard output. Thus, you can use it like this to save some work: </p> - <pre>% ~/cricket/util/listInterfaces engineering-router > interfaces</pre> + <pre>% <B>~/cricket/util/listInterfaces engineering-router > interfaces</B></pre> <p> You should check the automatically generated interfaces - file and make certain it only lists interfaces you are - interested in. + file and make certain it only lists interfaces in which + you are interested. </p> <p> By adding this file, you've just changed the config tree. @@ -348,7 +354,7 @@ 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> + <pre>% <B>~/cricket/collector /router-interfaces</B></pre> <p> Once again, you should see that Cricket is successfully retrieving data for your targets. @@ -362,40 +368,39 @@ <p> The collector is usually run from a wrapper program whose job it is to handle locking, rotating log files, and other - administivia. + administrivia. </p> <p> - The wrapper is called collect-subtrees. It reads a file - from the Cricket install directory called "subtree-sets". + The wrapper is called <TT>collect-subtrees</TT>. It reads a file + from the Cricket install directory called <I>subtree-sets</I>. 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 + Cricket will expect to find its 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 + This is a critical feature when it comes to increasing 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 +<B>0,5,10,15,20,25,30,35,40,45,50,55 * * * * $HOME/cricket/collect-subtrees normal</B> </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. + Usually, this is done by typing <TT>crontab -e</TT>. In the + crontab, your entry must all be on one line. </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 + likely to see will also show up in the <I>$HOME/cricket-logs</I> directory). </p> </li> @@ -404,10 +409,10 @@ 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. + into your <I>$HOME/public_html</I> directory via a softlink. 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: + resources that might help you succeed: </p> <p> </p> @@ -446,14 +451,14 @@ 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 . + % <B>cd $HOME/public_html</B> + % <B>mkdir cricket</B> + % <B>cd cricket</B> + % <B>ln -s $HOME/cricket/VERSION .</B> + % <B>ln -s $HOME/cricket/grapher.cgi .</B> + % <B>ln -s $HOME/cricket/mini-graph.cgi .</B> + % <B>ln -s $HOME/cricket/lib .</B> + % <B>ln -s $HOME/cricket/images .</B> </pre> <p> These links expose the minimal amount of Cricket necessary @@ -499,7 +504,7 @@ 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 + in <I>$HOME/cricket-logs</I> for errors) then you can take some time to read the other documentation, or maybe even grab a beer. </p> ------=_Part_39_56446803.1242669556895 Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline ------------------------------------------------------------------------------ Crystal Reports - New Free Runtime and 30 Day Trial Check out the new simplified licensing option that enables unlimited royalty-free distribution of the report engine for externally facing server and web deployment. http://p.sf.net/sfu/businessobjects ------=_Part_39_56446803.1242669556895 Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ cricket-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/cricket-users ------=_Part_39_56446803.1242669556895--