This document covers the recommended steps for installing CHIRP under UNIX. Step 1: To install CHIRP, gunzip and untar the package to your favorite location. We recommend /usr/local/chirp. Do the same thing with CHIRP that you do with Cricket. If you have Cricket in /usr/local/cricket and a symbolic link in /home/cricket, put CHIRP in /usr/local/chirp and add a symbolic link in /home/cricket/chirp pointing to /usr/local/chirp. Step 2: CHIRP requires SNMP_Session to be installed. As of the time of this writing, SNMP_Session is version 0.77. SNMP_Session is available at http://www.switch.ch/misc/leinen/snmp/perl and is required for Cricket as well. Step 3: You may need to edit the various Perl modules for "use lib" statements. While every effort is made to keep any paths out of the Perl scripts and modules, sometimes a hardcoded path might sneak by. In particular, you'll want to watch out for 'use lib "/usr/local/cricket/lib";' statements in the driver modules. Step 4: You may have to edit the Perl executables (all the .pl files) for the first line of the file. The first line contains the command line to run under UNIX (#!/usr/bin/perl -w). If your system has Perl in another location (such as /bin/perl), you will have to correct these files. Step 5: You may want to create a site.cfg file. This file looks similar to any ordinary Cricket config file. You specify this file with the -s option to chirp.pl. If this option is there, CHIRP will parse the file and apply all the configuration data in it to the configuration generated by a driver. This may be useful for either overriding settings in a generated config file, or for adding new settings to a generated config file. For example, assume a driver generates a configuration file which contains: graph --default-- draw-as = LINE1 However, you would rather the configuration file specified LINE3 for the default graph. Without the site.cfg file, your options would be to either 1) change the driver, and then change it again every time the driver is updated. Or 2) manually change the configuration file after generating it, and then change it again every time you regenerate it. Both of these are a drag. Using a site.cfg file which looks like this, you can override it automatically: graph --default-- draw-as = LINE3 When you run CHIRP, just run it as: chirp -h hostname -s site.cfg and the output configuration file will have your site changes. This site.cfg file has many uses. You can use it as above for setting defaults or overriding generated configuration file default settings. You can use it to specify all of your RRAs and default RRA settings for all target types. This should be specfied in an inherited Defaults file, but sometimes that just isn't easy and you would rather a particular device has a specific setting not taken from a Defaults file. It's also possible to apply a setting to all targets in this manner. If your site.cfg file contains: target * display-name = "My target" then _every_ target generated in the output configuration file will have this tag set. It's also important to note that you can have as many different site.cfg file as you like. (There is no restriction on the name of them) You may want to have different site.cfg files to apply against different drivers generated configurations, or for specific devices. Check out the samples directory for some sample site.cfg files. Step 6: You may need to edit the id.cfg file if you add additional drivers that were not distributed with CHIRP. The id.cfg file contains the methods for identifying a particular device and associating that device to a driver. Hopefully, these other drivers will contain additional documentation about what should be in the id.cfg file. The syntax for the id.cfg file looks as follows: OID MyOID0 .0.1.2.3.4.5.6 OID MyOID2 .9.8.7.6.5.4.3 Device Device_Name Module = "lib::Vendor::Model" Package = "CHIRP::Vendor::Model" Options = "Some options, maybe" Match = "TAG0 & TAG1" TAG0 = "snmp://%snmp%/MyOID0=SomeValue0" TAG1 = "snmp://%snmp%/MyOID1=SomeValue1" Vendor = "Vendor of device" Model = "Model of device" The important tags to note are the Module, Package, and Match tags. The Module tag gives the Perl path to the driver module. Here, Module points to "lib::Vendor::Model" which means, the module is in a directory named "Vendor" in a directory named "lib" and is named "Model.pm". The "lib" directory must be in the PERLLIB search path or in the current directory when chirp.pl is run. The Package tag specifies the Perl package name that the module uses. To get this, look for the package command in the module itself. The Match tag specifies additional tags which must be matched in order for this driver to be applied to the current device. In this case, the Match specified that the device must respond to SNMP queries such that the value retrieved for OID .0.1.2.3.4.5.6 matches the regular expression "SomeValue0" and the value retrieved for OID .9.8.7.6.5.4.3 matches the regular expression "SomeValue1". The Vendor and Model tags are not actually used. They are mostly there for documentation. In order for chirp.pl to find the id.cfg file, either use the -i option to chirp.pl or chirp.pl will look in the current directory for a file named id.cfg. Step 7: Call chirp.pl for all of your devices. CHIRP will generate the configuration file on STDOUT, so it is up to you to redirect that to another file for Cricket. Update Cricket to make sure it will look at the new configuration files, do a compile, then check to see if you can see your device in Cricket! Another utility is included called chirptree.pl. This is a Perl script which is able to automate the creation of lots of config files. It works by scanning a file which contains a list of all of your network devices that you would like Cricket to monitor. Chirptree.pl is suitable for calling from cron. Please see USAGE.txt for more information. Yet another utility is included called chirpid.pl. This is a Perl script useful for debugging id.cfg. Run it with a hostname and optional community and port parameters and it will query the device and report the name of the device entry in id.cfg that matched the device.