This document outlines how to use the various tools included in CHIRP.


Chirp.pl:

The main utility provided with this package is chirp.pl.  Use this tool
to generate config files.  Running this program will generate a configuration
on standard output.  It is up to the user to redirect the output into
an appropriately named configuration file.

Usage: ./chirp.pl [-H] hostname [-c community] [-p port] [-i file] [-s file]
	Required parameters:
		hostname:        Hostname for SNMP query

	Optional parameters:
		-H|--Help:       This page
		-c|--community:  Community for SNMP query (Defaults to "public")
		-p|--port:       Port for SNMP query (Defaults to port 161)
		-i|--idfile:     ID config file
		-s|--sitefile:   Site config file

The hostname parameter is required and specifies the hostname (or IP address)
used to locate the device.

The -c parameter can be used to specify explicitly what SNMP community
name should be used in querying the device.  If this parameter is not supplied,
it will default to "public".

The -p parameter can be used to specify explicitly what SNMP port
should be used in querying the device.  If this parameter is not supplied,
it will default to port 161.

The -i parameter is used to specify explicitly the id.cfg file to be used
by CHIRP.  If this is not provided, CHIRP will look in the current directory
for a file named "id.cfg".  If CHIRP is unable to locate this file, the
configuration file generated will be for an "Unknown device" type.

The -s parameter is used to specify additional site specific configuration
definitions to be included in the generated configuration file.  Please
see the samples directory for some examples of site configuration files.


Chirptree.pl:

Chirptree.pl is a utility included to help in mass generation of configuration
trees.  It works by generating configurations for a set of devices and storing
the output into the Cricket configuration tree.  The set of devices is
determined by the file passed to chirptree.pl via the filename parameter.

Usage: ./chirptree.pl [-H] filename basedir [-i file] [-q]
	Required parameters:
		filename:        File with device list  (Use - for stdin)
 		                 Format of file is:
 		                 SUBTREE:DEVICE_NAME:HOSTNAME:SNMP_COMMUNITY:SNMP_PORT:SITE_FILE:COMMENT
		basedir:         Base directory for cricket config files

	Optional parameters:
		-H|--Help:       This page
		-i|--idfile:     ID config file
		-q|--quiet:      Quiet mode

The filename parameter specifies the file from which to read the device list.
The format for this file is outlined below.  This parameter can be specfied
as "-" to read the list from stdin.

The basedir parameter specfies the root of the Cricket config tree and is a
required parameter.

The -i parameter is used to specify explicitly the id.cfg file to be used
by CHIRP.  If this is not provided, CHIRP will look in the current directory
for a file named "id.cfg".  If CHIRP is unable to locate this file, the
configuration files generated will be for an "Unknown device" type.

The -q parameter may be used to specify that no output (other than errors)
be displayed.

The file specified by the filename parameter should have the format below.  All
fields should be separated by colons.  SUBTREE, DEVICE_NAME, and HOSTNAME are
required, all others are optional.  Comments are allowed in the file prefixed
by a #.  Leaving a field blank will cause it to be set to a default.
	SUBTREE
         	The directory structure to be created under the directory
		specified by the basedir parameter.  The created config file
		will be put under this directory in a directory named by
		DEVICE_NAME in the file "Targets".
	DEVICE_NAME      
		A name for the device.  A directory will be created under
		SUBTREE by this name.
	HOSTNAME
		The hostname (or IP address) of the device
	SNMP_COMMUNITY
		An (optional) SNMP community name to be used when querying
		the device.  By default, this will be "public".
	SNMP_PORT
		An (optional) SNMP port to be used.  By default, this will
		be 161.
	SITE_FILE
		An (optional) site.cfg file to be applied to the configuration
		after the configuration is generated.
	COMMENT
		An (optional) comment.  This is not processed.


ChirpID.pl:

ChirpID.pl is a utility used for debugging the id.cfg file.  When invoked,
it queries the specified device until it matches an entry in the id.cfg file.
The name of the first device in the id.cfg file to match is displayed.  The
algorithm used for determining the device type is the same as that used by
chirp.pl and chirptree.pl.

chirpid.pl [-H] -h hostname [-c community] [-p port] [-i file]
	-H: This page
	-h: Hostname for SNMP query
	-c: Community for SNMP query
	-p: Port for SNMP query
	-i: ID config file

The -h parameter is required and specifies the hostname (or IP address)
used to locate the device.

The -c parameter can be used to specify explicitly what SNMP community
name should used in querying the device.  If this parameter is not supplied,
it will default to "public".

The -p parameter can be used to specify explicitly what SNMP port
should be used in querying the device.  If this parameter is not supplied,
it will default to port 161.

The -i parameter is used to specify explicitly the id.cfg file to be used
by CHIRP.  If this is not provided, CHIRP will look in the current directory
for a file named "id.cfg".  If CHIRP is unable to locate this file, the
configuration file generated will be for an "Unknown device" type.