The Cricket Reference Guide

Cricket: a configuration, polling and data display wrapper for RRD files

Copyright (C) 1998 Jeff R. Allen and WebTV Networks, Inc.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Introduction

Cricket was designed to solve several weaknesses WebTV found in MRTG when we tried to use it with thousands of targets, and for many different purposes (8 different applications, and counting). We found that the more we customized the MRTG config file, the larger and more unwieldy it got. We found that we were making mistakes due to the complexity, and then we wrote scripts to write the configs for us, and using these scripts, we made mistakes in a faster, more automated manner. Something needed to be done.

Cricket uses a hierarchical configuration system, thus a complete set of Cricket config files is called a "config tree". Configuration information that will be used again and again can be stored high in the tree, and inherited by all the leaves. More specific information can be stored closer to where it is used, but still in one place (instead of each place it is used). All the way down to the leaves of the tree, information from higher up can be overridden. Files are grouped into directories and processed in a predictable order within those directories. As a directory is processed, the state of the system is saved and restored. In this way, changes made to the defaults in a sub-tree do not affect a sibling sub-tree.

Understanding the config tree

Understanding the config tree is critical to understanding how to use and modify Cricket. Everything Cricket knows it learns from the config tree. That includes things like which variables to fetch for a certain type of device, how to fetch those variables, which devices to talk to, and what type of device they all are. The inheritance property of the config tree applies equally to all types of data, making it possible to make a concise description of a large, complicated set of monitored devices.

In this section, we will take a guided tour of the sample config tree that ships with Cricket. It would be a very good idea to read this section with a window open that you can use to explore the sample config tree.

The first thing to notice about the config tree is that every directory has a file in it called "Defaults". This file is not strictly speaking necessary, but you will find it in nearly every level of every config tree. It's purpose is to hold settings that will apply to the entire subtree that it sits on top of. Thus, when you look at the file named sample-config/Defaults, it's important to realize that unless those values get overridden later, they will be used throughout the entire config tree. When Cricket goes to process a directory, it processes the Defaults file first (if it exists), then processes each of the directories, and finally processes the files in alphabetical order. When processing a directory, it saves the current configuration before entering it, and restores the configuration after leaving the directory. Note that Cricket does not save and restore the configuration when processing files; one file could make a change to the defaults that another file in the same directory can see. For the time being, consider this a feature. It can be useful, as long as you are expecting it to behave that way.

Scroll through the root Defaults file and take a look at the sections. You'll see that each chunk of the file begins with a certain word (like "target", or "oid"). After that word, they differ somewhat, but generally what a chunk does is define some tag/value pairs, and assign them to some key name. For instance, the tag rrd-datafile gets set to "%dataDir%/%auto-target-name%.rrd".

That's great, you say, but what are the percent signs about? This brings us to expansion. Before a dictionary is used, it is expanded. This means that variables which are referenced with the "%tag%" syntax are replaced with their actual values. If the value also has a variable in it, it is also expanded. (There is no check for loops so don't accidentally make one!) This is a very powerful feature which makes complicated configurations boil down to a few simple config lines.

For instance, the example I chose above sets the tag rrd-datafile to a proper filename made up of the data directory, the target name, and the extension ".rrd". But you'll notice that dataDir is itself defined in terms of some other tags. As long as all the tags eventually map to some text, the expansion process turns this mess into a complete pathname. If a tag is not defined, but it referenced via an expansion, then Cricket will log a warning, but it will attempt to continue to use the partially expanded string. This behavior is characteristic of Perl programs and my programs in particular: they will attempt to muddle along, and will only really give up when they cannot do their job. This philosophy may let you sleep through the night if something breaks, but Cricket can still limp through it. Of course, if you are expecting Cricket to be one of those fascist programs that coredumps unless everything is perfect, you'll be surprised by this behavior.

The tags that Cricket uses to get it's configuration are listed below in the reference section, one at a time with a description. All other tags that appear in the dictionaries in a config tree are either in use by expansions, or ignored. For instance, nowhere in the reference section will you find dataDir mentioned. That is simply a tag that exists to make the definition rrd-datafile easier to read. You can add as many of your own tags as you want; it's all up to how you want to setup your config tree.

After Cricket expands a string, it scans the string for substrings surrounded by curly braces ({like this}). These substrings are passed to Perl's eval() function, which means you can do arbitrary math and other nifty trickery between curly braces. Some day I'll add more examples for how you might use this, but for now all I'm telling you is that it's there. You have to figure out how to use it.

Now, let us take a digression for a second to talk about targets, target types, and datasources. A datasource is something you want to graph. For instance, "router inlet temperature", or "inbound octets per second". Datasources that all relate to the same type of device are grouped together into a target type. A target is a distinct device from which you will be collecting data. Every target has a target type, which is how Cricket knows what data to fetch, and how to fetch it. This is all described in much more detail below, but for now, you already know enough to get going. This is because Cricket's sample config tree comes with lots of predefined target types that will let you look at common things on your network.

To see this stuff in action, go into the sample-config/routers directory and take a look at the Defaults file. What this file is doing is setting things up so that if you create a target of type "Cisco-7200-Router", Cricket will know what data to fetch. As you can see by the different target types defined in this file, not all routers are created equal. Some can return temperature, some can't.

Now, let's check out a target definition. Note that we've set a number of tags in the root Defaults file and in the subtree Defaults file related to the target named --default--. This special target is never used to fetch data. Instead, it is used as kind of a skeleton for all future targets that are created in the subtree.

The following is some stuff I intend to integrate soon...

Dictionaries
Cricket configuration information is stored in one of several dictionaries. For instance, everything related to a target is stored in the target dictionary. Within most dictionaries, the data is gathered according to some key. Each key has a set of tag/value pairs. Cricket expects to find certain tags to be able to do it's work. All other tags are yours to play with -- you can use them to make your config tree more readable, or to make it more powerful. See expansion for more information on what you can do with tags.
Defaults
Each time Cricket goes to process a directory, it will process the Defaults file first. Each time Cricket goes to make a new dictionary key, it will populate it from the --default-- key first. Using these two facts, you can simplify configuration by setting repeated things in the --default-- dictionary in the Defaults file. From that place in the tree on down, those variables will be available to you for your use. Thus, by setting target-type once in the --default-- entry, the target-type tag will be set for all the targets in that directory and all the other targets below that point.
Auto Variables
These variables are provided to you by Cricket to make it easier for you to write simple, portable configuration trees. For example, it's possible to explicitly set the location of all of your RRD files, but it's easier to rely on the auto-target-path variable to set them all correctly for you. All automatic variables start with 'auto-'.
View
A view lets you look at a slice of data collected from a target. This solves the problem of what to do when you collect both temperature measurements, which range from 0 to 100, and available memory measurements which could be as high as several megabytes. Using views, we can isolate the temperature data on a graph of it's own, so that the temperature measurement is not a tiny flat line at the bottom of the memory-dominated graph.

Reference Section

The stuff in this section is the meat of the configuration information. If I have done a good job of designing Cricket to be easy to pick up and if I wrote a good summary above, you should be able to start adjusting the config files to fit your needs already. Use this section as a reference when you need to know the exact format for something, or the exact behavior of a certain tag.

File Format

Cricket config files are simple text files arranged into a tree-shaped set of files called a Config Tree. They are processed by a Perl module called ConfigTree.pm. This setup would make it possible to use one config tree for Cricket and other clients of ConfigTree.pm. At this time, there are no other programs that use the config tree design, but there may be in the future. It was set up this way because the config tree will grow to contain an accurate picture of your network; it makes sense to try to leverage that information to other network administration tools. The overriding philosophy here is duplicated information is bad: it is hard to maintain, and it invites silly mistakes.

The Cricket config tree is 100% incompatible with MRTG configuration files. There are not even any plans to write a converter, though one could probably be written. When you choose to use Cricket, it's a very good idea to approach your config from a fresh perspective, to take maximum advantage of Cricket's features.

The comment character for Cricket is "#". If a "#" is found at the beginning of the line (or is preceded only by whitespace) then the "#" and everything after it will be deleted. Completely blank lines are discarded from the input too.

The fundamental unit of a config file is a chunk. A chunk is made up of one line which begins in column one, and one or more lines which have whitespace before them. In this way, you can continue a long line to another line by simply inserting a newline and some whitespace. When it is glued back together internally, the newline and whitespace are replaced by a space. A chunk should have at least one word (a group of characters that are not whitespace) at the beginning. This word (called the "token" by the code) tells ConfigTree.pm what kind of chunk it is dealing with, and what kind of parser to use. If it is an unknown token, ConfigTree.pm can be told to ignore it. By default, unknown chunks cause a warning, but not a fatal error. Clients of ConfigTree.pm can control this; Cricket chooses to ignore unknown chunks.

As mentioned above, ConfigTree.pm comes with several kinds of parsers (and others can be added dynamically later). The next section describes the kinds of chunks that Cricket uses. That section will refer to this list of parser types. On first reading, you should skip this list and learn about the chunks first. Or, scan the following sections to learn about the syntax of each parser type.

Text Parser

This parser is used in cases where free-text is useful, for instance in the HTML dictionary. The first two tokens are parsed out, and they serve as the chunk type, and the key. Everything after these first two tokens is considered the value.

Simple Parser

This parser is used for simple mappings, like the OID mapping. An example of a valid OID line is:

oid ifInOctets 1.3.6.1.2.1.2.2.1.10

The format is a token, another token (called the key; ifInOctets in this case), and finally the value. The value can have whitespace in it, but only if it is surrounded by double quotes ("). If you want to embed a quote in a value, put a backslash in front of it.

Tag/Value Parser

This is the most useful, and most commonly used parser. Here's an example of a Tag/Value chunk:

graph   ifInOctets
    color       =   dark-green
    draw-as     =   AREA
    legend      =   "Average bits in"
    y-axis      =   "bits per second"
    scale       =   8,*

Like the others, it parses out two tokens, the chunk type and the key. After this, it parses a series of tag/value pairs separated by whitespace and the equals sign ("="). The values must be surrounded by quotes to embed whitespace, like the Simple Parser. Depending on the kind of data, you may or may not be allowed to repeat tags.

General

All tokens and keys are case-insensitive. The tags in a tag/value chunk are also case insensitive. The values will have their case preserved when they are used by the system.

For some tags, you can put Perl expressions into the value. (inst-names is one such tag) However, double quotes are often useful in Perl expressions. That's problematic, since at present there is no way to put quotes into values. Backslashing the quotes does not work, so don't try it and pull your hair out and blame me for your baldness. Instead, you should use single quotes. Thus it might look something like this: 

inst-names =   "('Port 1 Ethernet', 'Port 2 Ethernet', 
                 'Port 3 FDDI', 'Port 6 FDDI', 
                 'Port 7 Ethernet' , 'Port 9 Ethernet', 
                 '', '')"

Dictionary Reference

In this section, I will explain what every tag does for every dictionary. I'll try to work on that during vacation. (Now, don't you feel sorry for me and want to donate patches?)

The Target Dictionary

For each target known to Cricket, there is a target dictionary. The target dictionary holds all the information needed by Cricket to collect and store variables from a component. The target dictionary is expanded with respectis paSoftware Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Introduction

Cricket was designed to solve several weaknesses WebTV found in MRTG when we tried to use it with thousands of targets, and for many different purposes (8 different applications, and counting). We found that the more we customized the MRTG config file, the larger and more unwieldy it got. We found that we were making mistakes due to the complexity, and then we wrote scripts to write the configs for us, and using these scripts, we made mistakes in a faster, more automated manner. Something needed to be done.

Cricket uses a hierarchical configuration system, thus a complete set of Cricket config files is called a "config tree". Configuration information that will be used again and again can be stored high in the tree, and inherited by all the leaves. More specific information can be stored closer to where it is used, but still in one place (instead of each place it is used). All the way down to the leaves of the tree, information from higher up can be overridden. Files are grouped into directories and processed in a predictable order within those directories. As a directory is processed, the state of the system is saved and restored. In this way, changes made to the defaults in a sub-tree do not affect a sibling sub-tree.

Understanding the config tree

Understanding the config tree is critical to understanding how to use and modify Cricket. Everything Cricket knows it learns from the config tree. That includes things like which variables to fetch for a certain type of device, how to fetch those variables, which devices to talk to, and what type of device they all are. The inheritance property of the config tree applies equally to all types of data, making it possible to make a concise description of a large, complicated set of monitored devices.

In this section, we will take a guided tour of the sample config tree that ships with Cricket. It would be a very good idea to read this section with a window open that you can use to explore the sample config tree.

The first thing to notice about the config tree is that every directory has a file in it called "Defaults". This file is not strictly speaking necessary, but you will find it in nearly every level of every config tree. It's purpose is to hold settings that will apply to the entire subtree that it sits on top of. Thus, when you look at the file named sample-config/Defaults, it's important to realize that unless those values get overridden later, they will be used throughout the entire config tree. When Cricket goes to process a directory, it processes the Defaults file first (if it exists), then processes each of the directories, and finally processes the files in alphabetical order. When processing a directory, it saves the current configuration before entering it, and restores the configuration after leaving the directory. Note that Cricket does not save and restore the configuration when processing files; one file could make a change to the defaults that another file in the same directory can see. For the time being, consider this a feature. It can be useful, as long as you are expecting it to behave that way.

Scroll through the root Defaults file and take a look at the sections. You'll see that each chunk of the file begins with a certain word (like "target", or "oid"). After that word, they differ somewhat, but generally what a chunk does is define some tag/value pairs, and assign them to some key name. For instance, the tag rrd-datafile gets set to "%dataDir%/%auto-target-name%.rrd".

That's great, you say, but what are the percent signs about? This brings us to expansion. Before a dictionary is used, it is expanded. This means that variables which are referenced with the "%tag%" syntax are replaced with their actual values. If the value also has a variable in it, it is also expanded. (There is no check for loops so don't accidentally make one!) This is a very powerful feature which makes complicated configurations boil down to a few simple config lines.

For instance, the example I chose above sets the tag rrd-datafile to a proper filename made up of the data directory, the target name, and the extension ".rrd". But you'll notice that dataDir is itself defined in terms of some other tags. As long as all the tags eventually map to some text, the expansion process turns this mess into a complete pathname. If a tag is not defined, but it referenced via an expansion, then Cricket will log a warning, but it will attempt to continue to use the partially expanded string. This behavior is characteristic of Perl programs and my programs in particular: they will attempt to muddle along, and will only really give up when they cannot do their job. This philosophy may let you sleep through the night if something breaks, but Cricket can still limp through it. Of course, if you are expecting Cricket to be one of those fascist programs that coredumps unless everything is perfect, you'll be surprised by this behavior.

The tags that Cricket uses to get it's configuration are listed below in the reference section, one at a time with a description. All other tags that appear in the dictionaries in a config tree are either in use by expansions, or ignored. For instance, nowhere in the reference section will you find dataDir mentioned. That is simply a tag that exists to make the definition rrd-datafile easier to read. You can add as many of your own tags as you want; it's all up to how you want to setup your config tree.

After Cricket expands a string, it scans the string for substrings surrounded by curly braces ({like this}). These substrings are passed to Perl's eval() function, which means you can do arbitrary math and other nifty trickery between curly braces. Some day I'll add more examples for how you might use this, but for now all I'm telling you is that it's there. You have to figure out how to use it.

Now, let us take a digression for a second to talk about targets, target types, and datasources. A datasource is something you want to graph. For instance, "router inlet temperature", or "inbound octets per second". Datasources that all relate to the same type of device are grouped together into a target type. A target is a distinct device from which you will be collecting data. Every target has a target type, which is how Cricket knows what data to fetch, and how to fetch it. This is all described in much more detail below, but for now, you already know enough to get going. This is because Cricket's sample config tree comes with lots of predefined target types that will let you look at common things on your network.

To see this stuff in action, go into the sample-config/routers directory and take a look at the Defaults file. What this file is doing is setting things up so that if you create a target of type "Cisco-7200-Router", Cricket will know what data to fetch. As you can see by the different target types defined in this file, not all routers are created equal. Some can return temperature, some can't.

Now, let's check out a target definition. Note that we've set a number of tags in the root Defaults file and in the subtree Defaults file related to the target named --default--. This special target is never used to fetch data. Instead, it is used as kind of a skeleton for all future targets that are created in the subtree.

The following is some stuff I intend to integrate soon...

Dictionaries
Cricket configuration information is stored in one of several dictionaries. For instance, everything related to a target is stored in the target dictionary. Within most dictionaries, the data is gathered according to some key. Each key has a set of tag/value pairs. Cricket expects to find certain tags to be able to do it's work. All other tags are yours to play with -- you can use them to make your config tree more readable, or to make it more powerful. See expansion for more information on what you can do with tags.
Defaults
Each time Cricket goes to process a directory, it will process the Defaults file first. Each time Cricket goes to make a new dictionary key, it will populate it from the --default-- key first. Using these two facts, you can simplify configuration by setting repeated things in the --default-- dictionary in the Defaults file. From that place in the tree on down, those variables will be available to you for your use. Thus, by setting target-type once in the --default-- entry, the target-type tag will be set for all the targets in that directory and all the other targets below that point.
Auto Variables
These variables are provided to you by Cricket to make it easier for you to write simple, portable configuration trees. For example, it's possible to explicitly set the location of all of your RRD files, but it's easier to rely on the auto-target-path variable to set them all correctly for you. All automatic variables start with 'auto-'.
View
A view lets you look at a slice of data collected from a target. This solves the problem of what to do when you collect both temperature measurements, which range from 0 to 100, and available memory measurements which could be as high as several megabytes. Using views, we can isolate the temperature data on a graph of it's own, so that the temperature measurement is not a tiny flat line at the bottom of the memory-dominated graph.

Reference Section

The stuff in this section is the meat of the configuration information. If I have done a good job of designing Cricket to be easy to pick up and if I wrote a good summary above, you should be able to start adjusting the config files to fit your needs already. Use this section as a reference when you need to know the exact format for something, or the exact behavior of a certain tag.

File Format

Cricket config files are simple text files arranged into a tree-shaped set of files called a Config Tree. They are processed by a Perl module called ConfigTree.pm. This setup would make it possible to use one config tree for Cricket and other clients of ConfigTree.pm. At this time, there are no other programs that use the config tree design, but there may be in the future. It was set up this way because the config tree will grow to contain an accurate picture of your network; it makes sense to try to leverage that information to other network administration tools. The overriding philosophy here is duplicated information is bad: it is hard to maintain, and it invites silly mistakes.

The Cricket config tree is 100% incompatible with MRTG configuration files. There are not even any plans to write a converter, though one could probably be written. When you choose to use Cricket, it's a very good idea to approach your config from a fresh perspective, to take maximum advantage of Cricket's features.

The comment character for Cricket is "#". If a "#" is found at the beginning of the line (or is preceded only by whitespace) then the "#" and everything after it will be deleted. Completely blank lines are discarded from the input too.

The fundamental unit of a config file is a chunk. A chunk is made up of one line which begins in column one, and one or more lines which have whitespace before them. In this way, you can continue a long line to another line by simply inserting a newline and some whitespace. When it is glued back together internally, the newline and whitespace are replaced by a space. A chunk should have at least one word (a group of characters that are not whitespace) at the beginning. This word (called the "token" by the code) tells ConfigTree.pm what kind of chunk it is dealing with, and what kind of parser to use. If it is an unknown token, ConfigTree.pm can be told to ignore it. By default, unknown chunks cause a warning, but not a fatal error. Clients of ConfigTree.pm can control this; Cricket chooses to ignore unknown chunks.

As mentioned above, ConfigTree.pm comes with several kinds of parsers (and others can be added dynamically later). The next section describes the kinds of chunks that Cricket uses. That section will refer to this list of parser types. On first reading, you should skip this list and learn about the chunks first. Or, scan the following sections to learn about the syntax of each parser type.

Text Parser

This parser is used in cases where free-text is useful, for instance in the HTML dictionary. The first two tokens are parsed out, and they serve as the chunk type, and the key. Everything after these first two tokens is considered the value.

Simple Parser

This parser is used for simple mappings, like the OID mapping. An example of a valid OID line is:

oid ifInOctets 1.3.6.1.2.1.2.2.1.10

The format is a token, another token (called the key; ifInOctets in this case), and finally the value. The value can have whitespace in it, but only if it is surrounded by double quotes ("). If you want to embed a quote in a value, put a backslash in front of it.

Tag/Value Parser

This is the most useful, and most commonly used parser. Here's an example of a Tag/Value chunk:

graph   ifInOctets
    color       =   dark-green
    draw-as     =   AREA
    legend      =   "Average bits in"
    y-axis      =   "bits per second"
    scale       =   8,*

Like the others, it parses out two tokens, the chunk type and the key. After this, it parses a series of tag/value pairs separated by whitespace and the equals sign ("="). The values must be surrounded by quotes to embed whitespace, like the Simple Parser. Depending on the kind of data, you may or may not be allowed to repeat tags.

General

All tokens and keys are case-insensitive. The tags in a tag/value chunk are also case insensitive. The values will have their case preserved when they are used by the system.

For some tags, you can put Perl expressions into the value. (inst-names is one such tag) However, double quotes are often useful in Perl expressions. That's problematic, since at present there is no way to put quotes into values. Backslashing the quotes does not work, so don't try it and pull your hair out and blame me for your baldness. Instead, you should use single quotes. Thus it might look something like this: 

inst-names =   "('Port 1 Ethernet', 'Port 2 Ethernet', 
                 'Port 3 FDDI', 'Port 6 FDDI', 
                 'Port 7 Ethernet' , 'Port 9 Ethernet', 
                 '', '')"

Dictionary Reference

In this section, I will explain what every tag does for every dictionary. I'll try to work on that during vacation. (Now, don't you feel sorry for me and want to donate patches?)

The Target Dictionary

For each target known to Cricket, there is a target dictionary. The target dictionary holds all the information needed by Cricket to collect and store variables from a component. The target dictionary is expanded with respectis paSoftware Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Introduction

Cricket was designed to solve several weaknesses WebTV found in MRTG when we tried to use it with thousands of targets, and for many different purposes (8 different applications, and counting). We found that the more we customized the MRTG config file, the larger and more unwieldy it got. We found that we were making mistakes due to the complexity, and then we wrote scripts to write the configs for us, and using these scripts, we made mistakes in a faster, more automated manner. Something needed to be done.

Cricket uses a hierarchical configuration system, thus a complete set of Cricket config files is called a "config tree". Configuration information that will be used again and again can be stored high in the tree, and inherited by all the leaves. More specific information can be stored closer to where it is used, but still in one place (instead of each place it is used). All the way down to the leaves of the tree, information from higher up can be overridden. Files are grouped into directories and processed in a predictable order within those directories. As a directory is processed, the state of the system is saved and restored. In this way, changes made to the defaults in a sub-tree do not affect a sibling sub-tree.

Understanding the config tree

Understanding the config tree is critical to understanding how to use and modify Cricket. Everything Cricket knows it learns from the config tree. That includes things like which variables to fetch for a certain type of device, how to fetch those variables, which devices to talk to, and what type of device they all are. The inheritance property of the config tree applies equally to all types of data, making it possible to make a concise description of a large, complicated set of monitored devices.

In this section, we will take a guided tour of the sample config tree that ships with Cricket. It would be a very good idea to read this section with a window open that you can use to explore the sample config tree.

The first thing to notice about the config tree is that every directory has a file in it called "Defaults". This file is not strictly speaking necessary, but you will find it in nearly every level of every config tree. It's purpose is to hold settings that will apply to the entire subtree that it sits on top of. Thus, when you look at the file named sample-config/Defaults, it's important to realize that unless those values get overridden later, they will be used throughout the entire config tree. When Cricket goes to process a directory, it processes the Defaults file first (if it exists), then processes each of the directories, and finally processes the files in alphabetical order. When processing a directory, it saves the current configuration before entering it, and restores the configuration after leaving the directory. Note that Cricket does not save and restore the configuration when processing files; one file could make a change to the defaults that another file in the same directory can see. For the time being, consider this a feature. It can be useful, as long as you are expecting it to behave that way.

Scroll through the root Defaults file and take a look at the sections. You'll see that each chunk of the file begins with a certain word (like "target", or "oid"). After that word, they differ somewhat, but generally what a chunk does is define some tag/value pairs, and assign them to some key name. For instance, the tag rrd-datafile gets set to "%dataDir%/%auto-target-name%.rrd".

That's great, you say, but what are the percent signs about? This brings us to expansion. Before a dictionary is used, it is expanded. This means that variables which are referenced with the "%tag%" syntax are replaced with their actual values. If the value also has a variable in it, it is also expanded. (There is no check for loops so don't accidentally make one!) This is a very powerful feature which makes complicated configurations boil down to a few simple config lines.

For instance, the example I chose above sets the tag rrd-datafile to a proper filename made up of the data directory, the target name, and the extension ".rrd". But you'll notice that dataDir is itself defined in terms of some other tags. As long as all the tags eventually map to some text, the expansion process turns this mess into a complete pathname. If a tag is not defined, but it referenced via an expansion, then Cricket will log a warning, but it will attempt to continue to use the partially expanded string. This behavior is characteristic of Perl programs and my programs in particular: they will attempt to muddle along, and will only really give up when they cannot do their job. This philosophy may let you sleep through the night if something breaks, but Cricket can still limp through it. Of course, if you are expecting Cricket to be one of those fascist programs that coredumps unless everything is perfect, you'll be surprised by this behavior.

The tags that Cricket uses to get it's configuration are listed below in the reference section, one at a time with a description. All other tags that appear in the dictionaries in a config tree are either in use by expansions, or ignored. For instance, nowhere in the reference section will you find dataDir mentioned. That is simply a tag that exists to make the definition rrd-datafile easier to read. You can add as many of your own tags as you want; it's all up to how you want to setup your config tree.

After Cricket expands a string, it scans the string for substrings surrounded by curly braces ({like this}). These substrings are passed to Perl's eval() function, which means you can do arbitrary math and other nifty trickery between curly braces. Some day I'll add more examples for how you might use this, but for now all I'm telling you is that it's there. You have to figure out how to use it.

Now, let us take a digression for a second to talk about targets, target types, and datasources. A datasource is something you want to graph. For instance, "router inlet temperature", or "inbound octets per second". Datasources that all relate to the same type of device are grouped together into a target type. A target is a distinct device from which you will be collecting data. Every target has a target type, which is how Cricket knows what data to fetch, and how to fetch it. This is all described in much more detail below, but for now, you already know enough to get going. This is because Cricket's sample config tree comes with lots of predefined target types that will let you look at common things on your network.

To see this stuff in action, go into the sample-config/routers directory and take a look at the Defaults file. What this file is doing is setting things up so that if you create a target of type "Cisco-7200-Router", Cricket will know what data to fetch. As you can see by the different target types defined in this file, not all routers are created equal. Some can return temperature, some can't.

Now, let's check out a target definition. Note that we've set a number of tags in the root Defaults file and in the subtree Defaults file related to the target named --default--. This special target is never used to fetch data. Instead, it is used as kind of a skeleton for all future targets that are created in the subtree.

The following is some stuff I intend to integrate soon...

Dictionaries
Cricket configuration information is stored in one of several dictionaries. For instance, everything related to a target is stored in the target dictionary. Within most dictionaries, the data is gathered according to some key. Each key has a set of tag/value pairs. Cricket expects to find certain tags to be able to do it's work. All other tags are yours to play with -- you can use them to make your config tree more readable, or to make it more powerful. See expansion for more information on what you can do with tags.
Defaults
Each time Cricket goes to process a directory, it will process the Defaults file first. Each time Cricket goes to make a new dictionary key, it will populate it from the --default-- key first. Using these two facts, you can simplify configuration by setting repeated things in the --default-- dictionary in the Defaults file. From that place in the tree on down, those variables will be available to you for your use. Thus, by setting target-type once in the --default-- entry, the target-type tag will be set for all the targets in that directory and all the other targets below that point.
Auto Variables
These variables are provided to you by Cricket to make it easier for you to write simple, portable configuration trees. For example, it's possible to explicitly set the location of all of your RRD files, but it's easier to rely on the auto-target-path variable to set them all correctly for you. All automatic variables start with 'auto-'.
View
A view lets you look at a slice of data collected from a target. This solves the problem of what to do when you collect both temperature measurements, which range from 0 to 100, and available memory measurements which could be as high as several megabytes. Using views, we can isolate the temperature data on a graph of it's own, so that the temperature measurement is not a tiny flat line at the bottom of the memory-dominated graph.

Reference Section

The stuff in this section is the meat of the configuration information. If I have done a good job of designing Cricket to be easy to pick up and if I wrote a good summary above, you should be able to start adjusting the config files to fit your needs already. Use this section as a reference when you need to know the exact format for something, or the exact behavior of a certain tag.

File Format

Cricket config files are simple text files arranged into a tree-shaped set of files called a Config Tree. They are processed by a Perl module called ConfigTree.pm. This setup would make it possible to use one config tree for Cricket and other clients of ConfigTree.pm. At this time, there are no other programs that use the config tree design, but there may be in the future. It was set up this way because the config tree will grow to contain an accurate picture of your network; it makes sense to try to leverage that information to other network administration tools. The overriding philosophy here is duplicated information is bad: it is hard to maintain, and it invites silly mistakes.

The Cricket config tree is 100% incompatible with MRTG configuration files. There are not even any plans to write a converter, though one could probably be written. When you choose to use Cricket, it's a very good idea to approach your config from a fresh perspective, to take maximum advantage of Cricket's features.

The comment character for Cricket is "#". If a "#" is found at the beginning of the line (or is preceded only by whitespace) then the "#" and everything after it will be deleted. Completely blank lines are discarded from the input too.

The fundamental unit of a config file is a chunk. A chunk is made up of one line which begins in column one, and one or more lines which have whitespace before them. In this way, you can continue a long line to another line by simply inserting a newline and some whitespace. When it is glued back together internally, the newline and whitespace are replaced by a space. A chunk should have at least one word (a group of characters that are not whitespace) at the beginning. This word (called the "token" by the code) tells ConfigTree.pm what kind of chunk it is dealing with, and what kind of parser to use. If it is an unknown token, ConfigTree.pm can be told to ignore it. By default, unknown chunks cause a warning, but not a fatal error. Clients of ConfigTree.pm can control this; Cricket chooses to ignore unknown chunks.

As mentioned above, ConfigTree.pm comes with several kinds of parsers (and others can be added dynamically later). The next section describes the kinds of chunks that Cricket uses. That section will refer to this list of parser types. On first reading, you should skip this list and learn about the chunks first. Or, scan the following sections to learn about the syntax of each parser type.

Text Parser

This parser is used in cases where free-text is useful, for instance in the HTML dictionary. The first two tokens are parsed out, and they serve as the chunk type, and the key. Everything after these first two tokens is considered the value.

Simple Parser

This parser is used for simple mappings, like the OID mapping. An example of a valid OID line is:

oid ifInOctets 1.3.6.1.2.1.2.2.1.10

The format is a token, another token (called the key; ifInOctets in this case), and finally the value. The value can have whitespace in it, but only if it is surrounded by double quotes ("). If you want to embed a quote in a value, put a backslash in front of it.

Tag/Value Parser

This is the most useful, and most commonly used parser. Here's an example of a Tag/Value chunk:

graph   ifInOctets
    color       =   dark-green
    draw-as     =   AREA
    legend      =   "Average bits in"
    y-axis      =   "bits per second"
    scale       =   8,*

Like the others, it parses out two tokens, the chunk type and the key. After this, it parses a series of tag/value pairs separated by whitespace and the equals sign ("="). The values must be surrounded by quotes to embed whitespace, like the Simple Parser. Depending on the kind of data, you may or may not be allowed to repeat tags.

General

All tokens and keys are case-insensitive. The tags in a tag/value chunk are also case insensitive. The values will have their case preserved when they are used by the system.

For some tags, you can put Perl expressions into the value. (inst-names is one such tag) However, double quotes are often useful in Perl expressions. That's problematic, since at present there is no way to put quotes into values. Backslashing the quotes does not work, so don't try it and pull your hair out and blame me for your baldness. Instead, you should use single quotes. Thus it might look something like this: 

inst-names =   "('Port 1 Ethernet', 'Port 2 Ethernet', 
                 'Port 3 FDDI', 'Port 6 FDDI', 
                 'Port 7 Ethernet' , 'Port 9 Ethernet', 
                 '', '')"

Dictionary Reference

In this section, I will explain what every tag does for every dictionary. I'll try to work on that during vacation. (Now, don't you feel sorry for me and want to donate patches?)

The Target Dictionary

For each target known to Cricket, there is a target dictionary. The target dictionary holds all the information needed by Cricket to collect and store variables from a component. The target dictionary is expanded with respectis paSoftware Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Introduction

Cricket was designed to solve several weaknesses WebTV found in MRTG when we tried to use it with thousands of targets, and for many different purposes (8 different applications, and counting). We found that the more we customized the MRTG config file, the larger and more unwieldy it got. We found that we were making mistakes due to the complexity, and then we wrote scripts to write the configs for us, and using these scripts, we made mistakes in a faster, more automated manner. Something needed to be done.

Cricket uses a hierarchical configuration system, thus a complete set of Cricket config files is called a "config tree". Configuration information that will be used again and again can be stored high in the tree, and inherited by all the leaves. More specific information can be stored closer to where it is used, but still in one place (instead of each place it is used). All the way down to the leaves of the tree, information from higher up can be overridden. Files are grouped into directories and processed in a predictable order within those directories. As a directory is processed, the state of the system is saved and restored. In this way, changes made to the defaults in a sub-tree do not affect a sibling sub-tree.

Understanding the config tree

Understanding the config tree is critical to understanding how to use and modify Cricket. Everything Cricket knows it learns from the config tree. That includes things like which variables to fetch for a certain type of device, how to fetch those variables, which devices to talk to, and what type of device they all are. The inheritance property of the config tree applies equally to all types of data, making it possible to make a concise description of a large, complicated set of monitored devices.

In this section, we will take a guided tour of the sample config tree that ships with Cricket. It would be a very good idea to read this section with a window open that you can use to explore the sample config tree.

The first thing to notice about the config tree is that every directory has a file in it called "Defaults". This file is not strictly speaking necessary, but you will find it in nearly every level of every config tree. It's purpose is to hold settings that will apply to the entire subtree that it sits on top of. Thus, when you look at the file named sample-config/Defaults, it's important to realize that unless those values get overridden later, they will be used throughout the entire config tree. When Cricket goes to process a directory, it processes the Defaults file first (if it exists), then processes each of the directories, and finally processes the files in alphabetical order. When processing a directory, it saves the current configuration before entering it, and restores the configuration after leaving the directory. Note that Cricket does not save and restore the configuration when processing files; one file could make a change to the defaults that another file in the same directory can see. For the time being, consider this a feature. It can be useful, as long as you are expecting it to behave that way.

Scroll through the root Defaults file and take a look at the sections. You'll see that each chunk of the file begins with a certain word (like "target", or "oid"). After that word, they differ somewhat, but generally what a chunk does is define some tag/value pairs, and assign them to some key name. For instance, the tag rrd-datafile gets set to "%dataDir%/%auto-target-name%.rrd".

That's great, you say, but what are the percent signs about? This brings us to expansion. Before a dictionary is used, it is expanded. This means that variables which are referenced with the "%tag%" syntax are replaced with their actual values. If the value also has a variable in it, it is also expanded. (There is no check for loops so don't accidentally make one!) This is a very powerful feature which makes complicated configurations boil down to a few simple config lines.

For instance, the example I chose above sets the tag rrd-datafile to a proper filename made up of the data directory, the target name, and the extension ".rrd". But you'll notice that dataDir is itself defined in terms of some other tags. As long as all the tags eventually map to some text, the expansion process turns this mess into a complete pathname. If a tag is not defined, but it referenced via an expansion, then Cricket will log a warning, but it will attempt to continue to use the partially expanded string. This behavior is characteristic of Perl programs and my programs in particular: they will attempt to muddle along, and will only really give up when they cannot do their job. This philosophy may let you sleep through the night if something breaks, but Cricket can still limp through it. Of course, if you are expecting Cricket to be one of those fascist programs that coredumps unless everything is perfect, you'll be surprised by this behavior.

The tags that Cricket uses to get it's configuration are listed below in the reference section, one at a time with a description. All other tags that appear in the dictionaries in a config tree are either in use by expansions, or ignored. For instance, nowhere in the reference section will you find dataDir mentioned. That is simply a tag that exists to make the definition rrd-datafile easier to read. You can add as many of your own tags as you want; it's all up to how you want to setup your config tree.

After Cricket expands a string, it scans the string for substrings surrounded by curly braces ({like this}). These substrings are passed to Perl's eval() function, which means you can do arbitrary math and other nifty trickery between curly braces. Some day I'll add more examples for how you might use this, but for now all I'm telling you is that it's there. You have to figure out how to use it.

Now, let us take a digression for a second to talk about targets, target types, and datasources. A datasource is something you want to graph. For instance, "router inlet temperature", or "inbound octets per second". Datasources that all relate to the same type of device are grouped together into a target type. A target is a distinct device from which you will be collecting data. Every target has a target type, which is how Cricket knows what data to fetch, and how to fetch it. This is all described in much more detail below, but for now, you already know enough to get going. This is because Cricket's sample config tree comes with lots of predefined target types that will let you look at common things on your network.

To see this stuff in action, go into the sample-config/routers directory and take a look at the Defaults file. What this file is doing is setting things up so that if you create a target of type "Cisco-7200-Router", Cricket will know what data to fetch. As you can see by the different target types defined in this file, not all routers are created equal. Some can return temperature, some can't.

Now, let's check out a target definition. Note that we've set a number of tags in the root Defaults file and in the subtree Defaults file related to the target named --default--. This special target is never used to fetch data. Instead, it is used as kind of a skeleton for all future targets that are created in the subtree.

The following is some stuff I intend to integrate soon...

Dictionaries
Cricket configuration information is stored in one of several dictionaries. For instance, everything related to a target is stored in the target dictionary. Within most dictionaries, the data is gathered according to some key. Each key has a set of tag/value pairs. Cricket expects to find certain tags to be able to do it's work. All other tags are yours to play with -- you can use them to make your config tree more readable, or to make it more powerful. See expansion for more information on what you can do with tags.
Defaults
Each time Cricket goes to process a directory, it will process the Defaults file first. Each time Cricket goes to make a new dictionary key, it will populate it from the --default-- key first. Using these two facts, you can simplify configuration by setting repeated things in the --default-- dictionary in the Defaults file. From that place in the tree on down, those variables will be available to you for your use. Thus, by setting target-type once in the --default-- entry, the target-type tag will be set for all the targets in that directory and all the other targets below that point.
Auto Variables
These variables are provided to you by Cricket to make it easier for you to write simple, portable configuration trees. For example, it's possible to explicitly set the location of all of your RRD files, but it's easier to rely on the auto-target-path variable to set them all correctly for you. All automatic variables start with 'auto-'.
View
A view lets you look at a slice of data collected from a target. This solves the problem of what to do when you collect both temperature measurements, which range from 0 to 100, and available memory measurements which could be as high as several megabytes. Using views, we can isolate the temperature data on a graph of it's own, so that the temperature measurement is not a tiny flat line at the bottom of the memory-dominated graph.

Reference Section

The stuff in this section is the meat of the configuration information. If I have done a good job of designing Cricket to be easy to pick up and if I wrote a good summary above, you should be able to start adjusting the config files to fit your needs already. Use this section as a reference when you need to know the exact format for something, or the exact behavior of a certain tag.

File Format

Cricket config files are simple text files arranged into a tree-shaped set of files called a Config Tree. They are processed by a Perl module called ConfigTree.pm. This setup would make it possible to use one config tree for Cricket and other clients of ConfigTree.pm. At this time, there are no other programs that use the config tree design, but there may be in the future. It was set up this way because the config tree will grow to contain an accurate picture of your network; it makes sense to try to leverage that information to other network administration tools. The overriding philosophy here is duplicated information is bad: it is hard to maintain, and it invites silly mistakes.

The Cricket config tree is 100% incompatible with MRTG configuration files. There are not even any plans to write a converter, though one could probably be written. When you choose to use Cricket, it's a very good idea to approach your config from a fresh perspective, to take maximum advantage of Cricket's features.

The comment character for Cricket is "#". If a "#" is found at the beginning of the line (or is preceded only by whitespace) then the "#" and everything after it will be deleted. Completely blank lines are discarded from the input too.

The fundamental unit of a config file is a chunk. A chunk is made up of one line which begins in column one, and one or more lines which have whitespace before them. In this way, you can continue a long line to another line by simply inserting a newline and some whitespace. When it is glued back together internally, the newline and whitespace are replaced by a space. A chunk should have at least one word (a group of characters that are not whitespace) at the beginning. This word (called the "token" by the code) tells ConfigTree.pm what kind of chunk it is dealing with, and what kind of parser to use. If it is an unknown token, ConfigTree.pm can be told to ignore it. By default, unknown chunks cause a warning, but not a fatal error. Clients of ConfigTree.pm can control this; Cricket chooses to ignore unknown chunks.

As mentioned above, ConfigTree.pm comes with several kinds of parsers (and others can be added dynamically later). The next section describes the kinds of chunks that Cricket uses. That section will refer to this list of parser types. On first reading, you should skip this list and learn about the chunks first. Or, scan the following sections to learn about the syntax of each parser type.

Text Parser

This parser is used in cases where free-text is useful, for instance in the HTML dictionary. The first two tokens are parsed out, and they serve as the chunk type, and the key. Everything after these first two tokens is considered the value.

Simple Parser

This parser is used for simple mappings, like the OID mapping. An example of a valid OID line is:

oid ifInOctets 1.3.6.1.2.1.2.2.1.10

The format is a token, another token (called the key; ifInOctets in this case), and finally the value. The value can have whitespace in it, but only if it is surrounded by double quotes ("). If you want to embed a quote in a value, put a backslash in front of it.

Tag/Value Parser

This is the most useful, and most commonly used parser. Here's an example of a Tag/Value chunk:

graph   ifInOctets
    color       =   dark-green
    draw-as     =   AREA
    legend      =   "Average bits in"
    y-axis      =   "bits per second"
    scale       =   8,*

Like the others, it parses out two tokens, the chunk type and the key. After this, it parses a series of tag/value pairs separated by whitespace and the equals sign ("="). The values must be surrounded by quotes to embed whitespace, like the Simple Parser. Depending on the kind of data, you may or may not be allowed to repeat tags.

General

All tokens and keys are case-insensitive. The tags in a tag/value chunk are also case insensitive. The values will have their case preserved when they are used by the system.

For some tags, you can put Perl expressions into the value. (inst-names is one such tag) However, double quotes are often useful in Perl expressions. That's problematic, since at present there is no way to put quotes into values. Backslashing the quotes does not work, so don't try it and pull your hair out and blame me for your baldness. Instead, you should use single quotes. Thus it might look something like this: 

inst-names =   "('Port 1 Ethernet', 'Port 2 Ethernet', 
                 'Port 3 FDDI', 'Port 6 FDDI', 
                 'Port 7 Ethernet' , 'Port 9 Ethernet', 
                 '', '')"

Dictionary Reference

In this section, I will explain what every tag does for every dictionary. I'll try to work on that during vacation. (Now, don't you feel sorry for me and want to donate patches?)

The Target Dictionary

For each target known to Cricket, there is a target dictionary. The target dictionary holds all the information needed by Cricket to collect and store variables from a component. The target dictionary is expanded with respectis paSoftware Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Introduction

Cricket was designed to solve several weaknesses WebTV found in MRTG when we tried to use it with thousands of targets, and for many different purposes (8 different applications, and counting). We found that the more we customized the MRTG config file, the larger and more unwieldy it got. We found that we were making mistakes due to the complexity, and then we wrote scripts to write the configs for us, and using these scripts, we made mistakes in a faster, more automated manner. Something needed to be done.

Cricket uses a hierarchical configuration system, thus a complete set of Cricket config files is called a "config tree". Configuration information that will be used again and again can be stored high in the tree, and inherited by all the leaves. More specific information can be stored closer to where it is used, but still in one place (instead of each place it is used). All the way down to the leaves of the tree, information from higher up can be overridden. Files are grouped into directories and processed in a predictable order within those directories. As a directory is processed, the state of the system is saved and restored. In this way, changes made to the defaults in a sub-tree do not affect a sibling sub-tree.

Understanding the config tree

Understanding the config tree is critical to understanding how to use and modify Cricket. Everything Cricket knows it learns from the config tree. That includes things like which variables to fetch for a certain type of device, how to fetch those variables, which devices to talk to, and what type of device they all are. The inheritance property of the config tree applies equally to all types of data, making it possible to make a concise description of a large, complicated set of monitored devices.

In this section, we will take a guided tour of the sample config tree that ships with Cricket. It would be a very good idea to read this section with a window open that you can use to explore the sample config tree.

The first thing to notice about the config tree is that every directory has a file in it called "Defaults". This file is not strictly speaking necessary, but you will find it in nearly every level of every config tree. It's purpose is to hold settings that will apply to the entire subtree that it sits on top of. Thus, when you look at the file named sample-config/Defaults, it's important to realize that unless those values get overridden later, they will be used throughout the entire config tree. When Cricket goes to process a directory, it processes the Defaults file first (if it exists), then processes each of the directories, and finally processes the files in alphabetical order. When processing a directory, it saves the current configuration before entering it, and restores the configuration after leaving the directory. Note that Cricket does not save and restore the configuration when processing files; one file could make a change to the defaults that another file in the same directory can see. For the time being, consider this a feature. It can be useful, as long as you are expecting it to behave that way.

Scroll through the root Defaults file and take a look at the sections. You'll see that each chunk of the file begins with a certain word (like "target", or "oid"). After that word, they differ somewhat, but generally what a chunk does is define some tag/value pairs, and assign them to some key name. For instance, the tag rrd-datafile gets set to "%dataDir%/%auto-target-name%.rrd".

That's great, you say, but what are the percent signs about? This brings us to expansion. Before a dictionary is used, it is expanded. This means that variables which are referenced with the "%tag%" syntax are replaced with their actual values. If the value also has a variable in it, it is also expanded. (There is no check for loops so don't accidentally make one!) This is a very powerful feature which makes complicated configurations boil down to a few simple config lines.

For instance, the example I chose above sets the tag rrd-datafile to a proper filename made up of the data directory, the target name, and the extension ".rrd". But you'll notice that dataDir is itself defined in terms of some other tags. As long as all the tags eventually map to some text, the expansion process turns this mess into a complete pathname. If a tag is not defined, but it referenced via an expansion, then Cricket will log a warning, but it will attempt to continue to use the partially expanded string. This behavior is characteristic of Perl programs and my programs in particular: they will attempt to muddle along, and will only really give up when they cannot do their job. This philosophy may let you sleep through the night if something breaks, but Cricket can still limp through it. Of course, if you are expecting Cricket to be one of those fascist programs that coredumps unless everything is perfect, you'll be surprised by this behavior.

The tags that Cricket uses to get it's configuration are listed below in the reference section, one at a time with a description. All other tags that appear in the dictionaries in a config tree are either in use by expansions, or ignored. For instance, nowhere in the reference section will you find dataDir mentioned. That is simply a tag that exists to make the definition rrd-datafile easier to read. You can add as many of your own tags as you want; it's all up to how you want to setup your config tree.

After Cricket expands a string, it scans the string for substrings surrounded by curly braces ({like this}). These substrings are passed to Perl's eval() function, which means you can do arbitrary math and other nifty trickery between curly braces. Some day I'll add more examples for how you might use this, but for now all I'm telling you is that it's there. You have to figure out how to use it.

Now, let us take a digression for a second to talk about targets, target types, and datasources. A datasource is something you want to graph. For instance, "router inlet temperature", or "inbound octets per second". Datasources that all relate to the same type of device are grouped together into a target type. A target is a distinct device from which you will be collecting data. Every target has a target type, which is how Cricket knows what data to fetch, and how to fetch it. This is all described in much more detail below, but for now, you already know enough to get going. This is because Cricket's sample config tree comes with lots of predefined target types that will let you look at common things on your network.

To see this stuff in action, go into the sample-config/routers directory and take a look at the Defaults file. What this file is doing is setting things up so that if you create a target of type "Cisco-7200-Router", Cricket will know what data to fetch. As you can see by the different target types defined in this file, not all routers are created equal. Some can return temperature, some can't.

Now, let's check out a target definition. Note that we've set a number of tags in the root Defaults file and in the subtree Defaults file related to the target named --default--. This special target is never used to fetch data. Instead, it is used as kind of a skeleton for all future targets that are created in the subtree.

The following is some stuff I intend to integrate soon...

Dictionaries
Cricket configuration information is stored in one of several dictionaries. For instance, everything related to a target is stored in the target dictionary. Within most dictionaries, the data is gathered according to some key. Each key has a set of tag/value pairs. Cricket expects to find certain tags to be able to do it's work. All other tags are yours to play with -- you can use them to make your config tree more readable, or to make it more powerful. See expansion for more information on what you can do with tags.
Defaults
Each time Cricket goes to process a directory, it will process the Defaults file first. Each time Cricket goes to make a new dictionary key, it will populate it from the --default-- key first. Using these two facts, you can simplify configuration by setting repeated things in the --default-- dictionary in the Defaults file. From that place in the tree on down, those variables will be available to you for your use. Thus, by setting target-type once in the --default-- entry, the target-type tag will be set for all the targets in that directory and all the other targets below that point.
Auto Variables
These variables are provided to you by Cricket to make it easier for you to write simple, portable configuration trees. For example, it's possible to explicitly set the location of all of your RRD files, but it's easier to rely on the auto-target-path variable to set them all correctly for you. All automatic variables start with 'auto-'.
View
A view lets you look at a slice of data collected from a target. This solves the problem of what to do when you collect both temperature measurements, which range from 0 to 100, and available memory measurements which could be as high as several megabytes. Using views, we can isolate the temperature data on a graph of it's own, so that the temperature measurement is not a tiny flat line at the bottom of the memory-dominated graph.

Reference Section

The stuff in this section is the meat of the configuration information. If I have done a good job of designing Cricket to be easy to pick up and if I wrote a good summary above, you should be able to start adjusting the config files to fit your needs already. Use this section as a reference when you need to know the exact format for something, or the exact behavior of a certain tag.

File Format

Cricket config files are simple text files arranged into a tree-shaped set of files called a Config Tree. They are processed by a Perl module called ConfigTree.pm. This setup would make it possible to use one config tree for Cricket and other clients of ConfigTree.pm. At this time, there are no other programs that use the config tree design, but there may be in the future. It was set up this way because the config tree will grow to contain an accurate picture of your network; it makes sense to try to leverage that information to other network administration tools. The overriding philosophy here is duplicated information is bad: it is hard to maintain, and it invites silly mistakes.

The Cricket config tree is 100% incompatible with MRTG configuration files. There are not even any plans to write a converter, though one could probably be written. When you choose to use Cricket, it's a very good idea to approach your config from a fresh perspective, to take maximum advantage of Cricket's features.

The comment character for Cricket is "#". If a "#" is found at the beginning of the line (or is preceded only by whitespace) then the "#" and everything after it will be deleted. Completely blank lines are discarded from the input too.

The fundamental unit of a config file is a chunk. A chunk is made up of one line which begins in column one, and one or more lines which have whitespace before them. In this way, you can continue a long line to another line by simply inserting a newline and some whitespace. When it is glued back together internally, the newline and whitespace are replaced by a space. A chunk should have at least one word (a group of characters that are not whitespace) at the beginning. This word (called the "token" by the code) tells ConfigTree.pm what kind of chunk it is dealing with, and what kind of parser to use. If it is an unknown token, ConfigTree.pm can be told to ignore it. By default, unknown chunks cause a warning, but not a fatal error. Clients of ConfigTree.pm can control this; Cricket chooses to ignore unknown chunks.

As mentioned above, ConfigTree.pm comes with several kinds of parsers (and others can be added dynamically later). The next section describes the kinds of chunks that Cricket uses. That section will refer to this list of parser types. On first reading, you should skip this list and learn about the chunks first. Or, scan the following sections to learn about the syntax of each parser type.

Text Parser

This parser is used in cases where free-text is useful, for instance in the HTML dictionary. The first two tokens are parsed out, and they serve as the chunk type, and the key. Everything after these first two tokens is considered the value.

Simple Parser

This parser is used for simple mappings, like the OID mapping. An example of a valid OID line is:

oid ifInOctets 1.3.6.1.2.1.2.2.1.10

The format is a token, another token (called t