Cricket: a configuration, polling and data display wrapper for RRD filesCopyright (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.
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.
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.
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.
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.
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.
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.
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', '', '')" |
If this tag exists, and it is set to false, then this target will be skipped when the collector comes across it. This is useful if you no longer want to collect an obsolete target, but you still want it in the config tree so that you can look at it with the grapher.
If this item is set, it tells Cricket to send the data it collects somewhere else after it is added to the RRD file. The value of this tag is interpreted as a colon separated list of two things. The first is where to send the data. The second item is used on a case-by-case basis. The only place to send data right now is to SNMP traps. To do so, set copy-to to a string like this: trap:public@traphost.company.com.
The traps Cricket sends are marked with an enterprise number of "1.3.6.1.4.1.2595.1.1" (which is enterprises.webtv.wtvOps.wtvOpsTraps). Their generic type is 6, and their specific type is 3. The first varbind is the full path to the target, including the target name. The other varbinds are the actual data. The OID's for these varbinds can be ignored. They are not significant.
New copy-to types can only be added by editing the source to the collector. Please send any patches to the Cricket maintainer, so others can use your nifty copy-to method.
This string is displayed in the description column of the directory selection list, if it is set. If not, the column is simply left blank.
Hold on tight, this is a weird one. If this is set in the dictionary of the first target displayed in the "Targets that are available" table, then the table will have only one column. This is useful when you have lots of views and don't want to lose the space used by the description column.
You can use this tag to use a more user friendly name for a target for display purposes. If you do not set it, the target name itself will be displayed.
This tag is interpreted by the grapher as a comma-separated list of events to fetch from the events dictionary, and add to the graph in the form of a vertical rule.
This is the SNMP instance number. Cricket only really needs this value to be set correctly if %inst% shows up in the ds-source tag of the datasources you are collecting. If inst is set, Cricket will attempt to evaluate it as a Perl expression.
Note: there's no protection against side-effects from this expression, so to avoid a security problem from an inst like unlink('/etc/motd'); you should make certain your config tree is only writable by you.
The result of evaluating the instance is examined to see whether it is a mapped instance, a scalar, or a vector. If it starts with "map(", it is a mapped instance. The instance mapping algorithm is used to derive an instance number from the rest of the data in the target (see Instance Mapping below for more information on this), then the target is processed as though the instance number had been a scalar all along.
If it is a scalar (i.e. inst=1) then it is processed normally. If the instance is a vector (i.e. inst="(0..12)", or inst="(1, 3, 5)") then the target is processed once for each value in the list. The target dictionary is expanded with respect to itself for each instance, so it's possible to embed %inst% into the rrd-datafile tag. In fact, it's critical to add %inst% to some part of the rrd-datafile tag, or else the data will all be stored on top of one another in the same datafile.
When making the instance selector table, Cricket will use names from this tag instead of the instances themselves. If it will be needed, inst-names is eval'ed (just like inst). For each instance in the inst tag, Cricket looks for a corresponding entry in the inst-name vector. If it finds one, it uses that as the instance name, otherwise it defaults to the instance it fetched from the inst tag.
This description shows up at the top of a page of graphs, in the "Summary" section. There is more room on this page for a longer description. You can include your own HTML as long as you close all tags that you open. If you don't feel like setting this for every target, set it to %short-desc% in the "--default--" target, and the short description will show up on each graph page for every target which does not have an explicit long description. (Such is the power of the config tree.)
If this tag exists, then the fetched value for this target will be checked after the RRD is updated. The format of a monitor-thresholds tag is 2 or more fields, colon delimited. Field 1 always contains the datasource associated with the target that you want to monitor, and field 2 specifies what monitor type you wish to apply to the specified datasource, any additional fields are passed to the monitor and are called arguments (field 3 is argument 1). Currently there are 3 supported monitor types: value, hunt, and relation.
Value monitors are the easiest to configure, and allow you to configure high-water/low-water monitoring on a datasource. Argument 1 is the low-water, and argument 2 is the high-water. Example: monitor-thresholds = "myds:value:10:20" would cause Cricket to send a trap if the last value for the datasource "myds" in the RRD file is below 10 or above 20.
Hunt monitors tell Cricket that a given target is the roll over for another target, so that if target 1 is at capacity, then traffic will begin to flow over target 2. This is especially useful to identify premature rollover in a set of modem banks configured to hunt from one to the next. Arguments for hunt monitors are as follows:
Example: monitor-thresholds = "myds:hunt:40:pop-1:myds" when placed in the target definition of pop-2, would cause Cricket to send a trap if traffic was seen on pop-2 before pop-1 reached 40 users.
Relation monitors are the most flexible, and allow Cricket to compare the value of the target you are monitoring with any other stored value within Cricket's RRD files. This can be used to compare a target against itself at a previous time (e.g. compare the traffic on a router interface to the traffic a week ago on that same interface), to compare against the same target for a different datasource (e.g. compare the packet rate on a router to the error rate), or to compare a target against a completely seperate target (e.g. compare the traffic on router-1 to the traffic on router-2 to be sure that they are load balancing correctly). Arguments for relation monitors are as follows:
Note: Monitoring of vectored instances is not supported. More than one monitor can be placed in a monitor-thresholds tag using a comma as a delimiter.
If this tag exists, then this target is considered by Cricket to be a multi-target. To the collector, this means that it simply doesn't need to collect anything, and can skip the target. To the grapher, it means this target will aggregate the data from several different targets all onto one set of graphs. It will plot the data from each of the different targets all on the same graph. It assumes that the target-type of each of the specified targets is the same. It works best if the graph dictionary for each datasource does not specify a color (otherwise you'll end up with more than one line with the same color). It enforces only one AREA graph--it will convert the others into LINE2 in order to ensure they can be seen. It does not currently support vector instances. Other than that, the syntax matches that for "targets". This tag can also be used in connection with the mtargets-ops flag to perform Arithematic operations.
Note: This tag will not work with vector instances at this time. If you absolutely need it to work, you'll need to use multiple separate scalar targets to poll the device's ports, and then use the mtargets tag to graph each of the scalar targets.
This tag is used in connection with the "mtargets" tag. This tag lets you perform arithematic operations on multiple targets. For example, this lets you add multiple targets together and graph the results. This tag must either be set to an RPN notation, or to a short-hand form, like "sum()".
If set to an RPN expression, it should be defined as a comma seperated list of operations, such as "+","-","*","/". This is used as a RPN calculator, operating on the targets listed in the mtargets definition. So, if you list three targets in your mtargets definition, you could define mtargets-ops="+,+", and the result would be a graph of the three targets added together.
If this tag is set to "sum()", the correct number of plusses will be substituted to make a valid RPN expression to sum each of the targets in the mtargets tag.
The HTML summary section also has the same set of operations done to the values there. The operations are done to each datasource defined for that target-type. If you have defined a scale for the individual datasource, these operations are done on the scaled values.
The order tag is used to control the order that targets are displayed. It has nothing to do with the order that they are polled. (Though it might work like that someday.) When the display is laid out by the CGI application, it sorts the targets from the highest order to the lowest order. Targets which have the same order are sorted alphanumerically within their order.
This tag tells Cricket where to put the data it collects, and where to find the data it will graph. Since there are no guarantees about where Cricket will be running from, you should use a full path here. The sample-config ships with a one-size-fits all definition for rrd-datafile in the root Defaults file. Except for special cases, you can probably use it and it will generate the filenames for you automatically.
This tag is used to set the step size (in seconds) for the RRD file when it is first created. This value cannot be changed once the RRD file is created, so if you need to change it in the config tree, then you must remove the RRD file, forcing Cricket to re-create it, to make the change stick. You will, of course, lose all the data you have collected so far. It is critical that the collector runs on each target at least as often as the rrd-polling-interval, otherwise RRD may mark the intervening polling periods as unknown.
RRA's are defined in terms of the fundamental polling-interval of the RRD. Thus, if you chose to adjust the rrd-polling-interval (and then run the collector at a non-standard rate) then you should re-visit the RRA definitions and probably make adjustments to them. A particular example of adjusting rrd-polling-interval would be using Cricket to monitor a 155 Mbit OC3 link. Because an SNMP Counter32 can wrap in under 5 minutes at bandwidths above 100 Mbits, it's critical to fetch the data more often, or else RRD will not be able to correctly detect and process the counter wrap. Hopefully in the next few versions, we will have an example of a part of the config tree optimized for very fast interfaces.
If this tag is present, it will override the same tag in the datasource dictionary. See the entry on rrd-max there for more information.
If this tag is present, it will override the same tag in the datasource dictionary. See the entry on rrd-min there for more information.
This description shows up in the target selection table which the CGI program displays. It is a good idea to keep this description to one line. You can include your own HTML in it as long as you close all tags that you open.
This tag is not directly used by Cricket except when it is doing instance mapping. However, it is convention (as exemplified by the sample-config tree) that this tag should hold the SNMP community string, the hostname, and the port number in the exact form that is required by the snmp:// ds-source specification. Thus, ds-sources can simply start with snmp://%snmp%/, and they will incorporate the current host, port, and community string into the ds-source tag as soon as they are expanded with respect to the current target.
When using instance mapping, the snmp tag is used directly, so it must be present, even if you are using another convention to get the data into the ds-source tags.
If this tag exists, then this target is considered by Cricket to be a multi-target. To the collector, this means that it simply doesn't need to collect anything, and can skip the target. To the grapher, it means this target will aggregate the data from several different targets all onto one report. The syntax is a semi-colon deliminated list of targets. The target definition can either by fully-qualified, which would look like "/router-interfaces/Datacenter1/ds3-1", or unqualified, in which case they are assumed to be in the current directory.
For targets with vector instance definitions, it may also be useful to specify which instance you wish to display. You can do that by putting a colon after the target definition. So, it would look something like this: targets="/switch-ports/switch-1:3;/switch-ports/switch-2:5..7". This would put up instance #3 from switch-1, and instance #5, #6, and #7 from switch-2. Variable expansion is handled in the instance definition section as well.
This functionality assumes that the target-type of each of the specified targets is the same. You also must set a target-type for the multi-target itself. There are some variables which control the presentation of this data, which are also listed in this reference.
This tag sets the text which is displayed above each graph in a "targets" multi-target. It should be an array of the same length as the "targets" array. This value overrides the default presentation, and also overrides the tag targets-short-desc. Syntax would look like: targets-long-desc="('Target1','Target2')"
By default above each graph in a targets multi-target page, the short-desc of each target being displayed is printed above that graph (as well as some other text). This replaces that text with this. It should be an array which matches the "targets" array. The syntax would look the same as for targets-long-desc.
This tag sets the target type for this target. It must be one of the target type names from the targetType dictionary. Cricket uses the targetType to decide which variables to fetch, and how much data to store in the RRD.
When this tag is set and the target is part of a multitarget which has mtargets-ops set, then data which is unknown will be treated as a 0. This is very useful when trying to create aggregate graphs that sum a set of targets that span different time ranges. By default, places where one target is unknown and the others are known will show on the graph as unknown (blank). In some cases, this can result in no graph appearing at all (when the set of known datapoints are completely disjoint). Set this flag to "true" to avoid this problem.
The short name of the current target. This does not include the entire path from the config tree root to the target.
The path leading from the base of the config tree to the current target.
The config tree root directory. This is especially useful for creating paths which you want to be relative to the config tree root. For instance, setting rrd-datafile to %auto-base%/../cricket-data/foo.rrd would put the datafile in a directory named cricket-data, next to the base of the config tree.
The name of the current view, as selected using the user interface. This is sometimes useful to incorporate into strings used in the user interface via the HTML dictionary.
This tag is used to tell Cricket where to fetch the data from. There is a scheme identifier from the beginning until the first colon. Everything after the first colon is defined on a per-scheme basis. The scheme identifier is case-insensitive.
The per-scheme part is expanded with respect to the target dictionary immediately before it is resolved into measurements, making it possible to plug values from the target dictionary into the ds-source at runtime. Likely candidates for this substitution include the SNMP hostname and community string, the instance number (which is appended to table-base OID's), and some or all of the command line for EXEC datasources.
Here's a detailed description of each scheme.
- SNMP
- These ds-sources look like this: snmp://community@hostname:port/oid. The hostname part can be either an IP address or a domain name. It will be resolved with gethostbyname() in the latter case. The oid part can include a text label which will be expanded from the OID dictionary.
- EXEC
- This ds-source is used to tell Cricket to run a shell command in order to fetch the value or values required for a target. After the exec: scheme identifier comes an integer followed by a colon, followed by a command (including whatever arguments are required for the command). The number chooses a line of output from the command (starting from line 0). For example, say the "vmstat" program on your system prints this when given the "-s" argument:
350 swap ins 2982 swap outs 239 pages swapped in 3298 pages swapped out (etc...)Then the following datasource would fetch the number of pages swapped out:exec:3:vmstat -s
Note that we allow the text output from the command (i.e. "pages swapped out") to go in to Cricket. As of version 0.64, Cricket ignores everything after the first space or tab. It will attempt to interpret the first sequence of non-space charaters on the line as a floating point number. Since an integer is a degenerate form of a floating point number, they are acceptable. This behavior holds for all ds-sources, actually, but it is most useful for the EXEC type.
If the initial integer is omitted (and there are no colons in the command line to confuse Cricket) then the line number will be assumed to be 0, and the first line of output will be used as the measurement.
- FILE
- This ds-source tells Cricket to read a file and find the results on a certain line of that file. The line is specified using the same syntax as EXEC. For example, say the file /tmp/data has two lines in it, like this:
100
235
Then this datasource would always fetch "235" from the file:
file:1:/tmp/data
Presumably, there would be some other process updating the data file with interesting data from someplace, or else the graph would be a flat line at 235.
- FUNC
- This ds-source uses a Perl function to fetch the result. It is not enabled by default, since it requires extra code to be useful, and could be a security vulnerability, if the config tree were not properly protected. To enable it, uncomment the line use func; in collector.
This ds-source uses Perl's eval keyword to evaluate some Perl code at runtime. Usually, this will be a function call to a function you have written yourself and added into collector. A good way to add the code portably is to keep it in it's own file and incorporate it with the require keyword. You will need to be careful to avoid stomping on any data that collector uses, since it will be running your code in it's namespace. This should be fixed someday, if many extensions to Cricket use this interface.
Datasources are batched together and executed with as few network transactions or shell executions are possible. For instance, if you are fetching six datasources from the same hostname, all six datasources will be rolled into one SNMP request. Likewise, if you are fetching 3 different lines from the results of the same command, that command will be run only once.
Schemes are expected to return their data as an array of numbers. If the values are of the form "XXX@YYY", then the measurement XXX will be recorded as being taken at time YYY. The time must be in the form of a Unix time_t, i.e. number of seconds since 1970. Currently, this feature is only supported by the EXEC and FILE schemes. RRD imposes the restriction that data can only be added in strictly ascending time order. Each datasource which has a time in it should have a matching time. If this is not the case, Cricket will log a warning, but use the first time it found in the array.
You might use this feature if you are fetching the data from another data collection system which is operating on a different polling cycle than Cricket. You could use a shell script to fetch the data from the other system, along with the time the data was sampled. Then you could format the result into the "XXX@YYY" format, and print it to standard out for Cricket to read.
New schemes can be added to Cricket with minimal effort. Use the file lib/exec.pm as your guide, then add a use statement for your new .pm file to collector.
The DS type is used by RRD to know how to interpret the numbers fetched from this datasource. There are three possibilities:
- GAUGE
- The measurement will be directly copied into the RRD datafile without any extra processing. Examples of this type of measurement include readings from thermometers, percent disk space free, etc.
- COUNTER
- The measurements from COUNTER datasources will be treated like SNMP counters. An SNMP counter increases monotonically until a fixed wrap-around point (usually either 2^31-2 or 2^63-2, depending on the size of the data type). To convert a COUNTER measurement into a rate (for instance, "count of octets" to "octets per second") RRD subtracts the previous value from the current one, and adjusts for any wraparound conditions. Any SNMP variable which is marked with the SNMP "COUNTER" data type should have it's rrd-ds-type set to COUNTER.
- DERIVE
- DERIVE is like COUNTER, but there is no overflow check, so negative rates are possible. This datasource type would be useful when you have a count of something (which may increase and decrease), and you want to graph the rate of change.
- ABSOLUTE
- ABSOLUTE is for COUNTERs which get reset upon reading. Some SNMP variables have this property. Using ABSOLUTE instead of COUNTER tells RRD to compute the rate assuming the value is an absolute count of octets (or whatever) during the last polling period.
The datasource type names are case-insensitive. They are passed directly through to RRD when the RRD file is created. If the datasource type is changed later, you must use rrd-tune to apply the change to the underlying RRD file. For more information about them, consult the RRD documentation for the create command.
The heartbeat for a datasource is the number of seconds that can pass between updates before the datasource is marked unknown. If this tag is changed after the RRD file has been created, then the rrd-tune tool must be used to apply the changes to the existing RRD's.
This tag is used to set the RRD maximum value parameter. If RRD gets a value higher than this number, it will throw the data away, instead of adding it to the RRA. This can be used to filter bad data, though it could be argued it would be better to simply avoid fetching bad data in the first place. When it is set to "U" (for unknown), RRD does not attempt to check incoming data against an upper bound.
If the tag rrd-max is present in the target dictionary, it will override the value found in the datasource dictionary. This makes is possible to assign different maxima to different targets.
If this value is changed after the underlying RRD file has been created, the rrd-tune script must be used to apply the changes.
Like rrd-max, this tag is passed through to RRD unchanged. It can be used to apply an upper bound to data submitted to RRD.
Also like rrd-max, if rrd-min appears in the target dictionary, it will override the rrd-min in the datasource dictionary.
Each ds tag tells Cricket about a variable it will be fetching. The value of the tag must be a known datasource name. You can use more than one ds tag to list each of the datasources that make up the target.
A view is a subset of the datasources that you'd like to display together, apart from the rest of the datasources. The syntax for the value is "view-name: ds ds ...". The view name you choose shows up in the CGI grapher, so you should try to make it descriptive. The space-separated list of datasources after the colon must be datasources that are part of the target type. Just like the ds tag, this tag can occur multiple times, once for each desired view.
There are actually two "flavors" of graph dictionary tags; per-datasource and generic. The generic tags relate to the graphs themselves, as opposed to the individual datasources drawn onto the graphs. For instance, the width and height of a graph are configured by generic tags, whereas the color of a datasource is configured by a per-datasource tag. Per-datasource tags are stored in the graph dictionary just as all the tags in the datasource dictionary are stored. Generic tags are stored only in the --default-- dictionary.
Below, the generic tags are listed.
This tag defines the requested height of the data area of the graph. This value is passed into RRD, which then draws the actual image somewhat bigger, in order to leave room for the margin, the scales, and the legend.
HTML defines image sizing tags that allow the browser to layout the page more efficiently. Using the Cricket's size hints, you can control what image sizing tags Cricket generates in it's HTML output. Most browsers will attempt to scale the image if the size hints passed in via HTML do not match the actual size of the image. The result is a hard-to-read graph that took too long to draw. Thus it is critical that if you choose to use sizing hints to help the browser layout the page, you make them precisely the same as the size of the generated image.
Because RRD pads the image with extra space, it's not possible for Cricket to guess the finished size of the image using the width and height tags. Instead, you need to find this number yourself by measuring an actual image produced by RRD. In Netscape Navigator, you can do this by right clicking on the image, then choosing Open this Image. Once the image is loaded, check the title bar for the actual size of the image.
What set of graphs are initially displayed. If you tend to be fetching graphs at low bandwidth, you might like to frob this. Setting it to "d", will make Cricket only send you the daily graph, instead of the daily and weekly graphs.
Set this tag to true to enable interlaced image. An interlaced image will appear to "fade in" in most web browsers.
Set this tag to 'gif' to get RRD Tool to create GIFs. The GIFs created by RRD are big and slow, because they do not use patented compression techniques. Cricket will use GIFs if the browser will not support PNG's.
This tag can be used to pass through arguments to the RRD Tool. The most appropriate use for this tag is to send color tags through to the RRD Tool. For instance, to make the canvas that the graph is drawn on appear black, you can set rrd-graph-args to "-c CANVAS#000000". This tag is split on whitespace before it is sent to RRD Tool, so it is not possible at this time to send arguments with embedded whitespace to RRD Tool.
Vertical rules are lines added to the graph by Cricket to help you visually find patterns in the data related to time of day. A vertical rule is placed at each "zero time" which appears on a graph. For an hourly graph, a zero time is midnight. For a daily graph, a zero time is the beginning of the most recent Monday. For a weekly graph, a zero time is the first day of the month. For a monthly graph, a zero time is the first day of the year. At this time, the definition of zero time for a given scale is hardcoded into Cricket's grapher.cgi script.
To enable vertical rules, use the vrule-color tag to choose a color for them. That's all there is to it. If vrule-color is defined, Cricket will automatically add the vertical rules for you.
Like height, this is the height of the data area of the graph. The actual height of the resulting image will differ.
Like height-hint above, this controls the value used by Cricket for the height tag in its HTML output. See height-hint for more information about how to set this.
Using this tag (and it's opposite, y-max) to explicitly control the scale of the graph. If you use either y-min or y-max, you disable auto-scaling, and so you must explicitly set both of them. These tags are especially useful when you are graphing some value which should normally be very tightly bound (for instance between 0 and 1 second), but occasionally jumps far above 1 second. In this case, all variation under one second will be invisible on the graph, unless you set the y-min to 0 and the y-max to 1.
In general, it's a good idea to leave these unset and rely on auto-scaling, unless you have a situation that calls for explicit bounds.
See y-min.
If this is set to true, then the conversion to SI units will use powers of 2 instead of powers of 10. For instance, if a router is reporting that it's moving 1048576 bits per second through a particular interface, and "bytes" is set to 1 (or "true") then the value will be reported in the HTML summary as 1 Mbit/sec. Without the bytes tag, the value would be reported at 1.04 Mbit/sec, which is slightly misleading. When measuring very large numbers of bytes, the difference can be significant.
The numbers on the veritcal axis of a graph are scaled by powers of 2 if the bytes tag is set to true for any of the datasources on the graph.
Use the color tag to explicitly control the color of the datasource as it appears both on the graph, and in the HTML summary. If this is left unset, then Cricket will automatically choose colors according to the --order-- key in the color dictionary. If you choose to set it, either set it to one of the color names in the color dictionary, or set it to an HTML-style color specification without the pound sign. For instance, to make a datasource's line red, set color to "ff0000".
This tag tells Cricket how to draw the datasource on the graph. The choices are as follows:
- AREA
- draws a filled-in shape representing the value of the datasource over time.
- LINE1
- uses a thin line
- LINE2
- uses a medium line
- LINE3
- uses a heavy line
Using legend allows you to customize the datasource name which is displayed on the graph's legend, and in the HTML summary. If you don't use a legend tag, the name of the datasource (as specified by the ds tag in the targetType dictionary) will be used.
You can adjust the number of decimal points in the HTML summary values using the precision tag. The default is two. If you simply want the value displayed to be rounded to the nearest integer, set precision to zero. Alternatively, you can set it to the string "integer".
If scale is set, then the datasource is run through a computation (usually a simple scaling operation) before it it plotted or listed in the HTML summary. The tag is interpreted as a string of operations that will be executed by a Reverse Polish Notation (RPN) calculator, separated by commas. When the expression begins executing, the current value of the datasource is already on the stack. Thus setting scale to "8,*" will multiply the datasource by 8 before plotting it.
The RPN operations available are "+" (plus), "-" (minus), "*" (multiply), "/" (divide), and "LOG" (take the natural logarithm of the top of the stack). Any other token is pushed onto the stack as a number. The top of the stack at the end of the string of operations is taken as the scaled value.
This feature is very useful when plotting bits per second from a router interface. Routers tend to report bandwidth in bytes per second, but humans tend to think about link capacity in bits per second. Using a scale tag of "8,*" can bridge this gap by scaling the bytes per second from the router into bits per second for human use.
This controls the amount of summary data shown on the top of graphs. If set to true, Cricket makes an extra call to RRD Tool to fetch the average and the maximum for the crurrent day of data. If set to false, only the current reading is shown.
Setting this tag to "false" will prevent Cricket from transforming the value printed in the HTML summary into SI units (i.e. 2000 bytes/sec is transformed into 2 kbytes/sec). The scale on the graph, however, will still have the transformation done to it. Set this tag to "false" for items that are not typically counted with SI units, like system load average.
Here are the SI units that are used by Cricket:
Symbol Magnitude Name a 10e-18 Ato f 10e-15 Femto p 10e-12 Pico n 10e-9 Nano µ 10e-6 Micro milli 10e-3 Milli k 10e3 Kilo M 10e6 Mega G 10e9 Giga T 10e12 Terra P 10e15 Peta E 10e18 Exa
Note that on graphs, 'milli' is denoted by 'm'. In the HTML summary, where there is more room, Cricket uses the less ambiguous 'milli'.
This tag can be used by the extremely fastidious user to control the HTML summary. Usually, one space is exactly what you'd want between the value and the unit specifier of the value. However, for certain units, like the degree sign, no space is called for. In this case, set space to "", the empty string.
In the HTML summary, the units tag is appended after the value of the datasource. If a datasource is collecting bandwidth information, for instance, it would make sense to set y-axis to "bits per second", since there is plenty of room for it. In the legend, where room is more limited, it would be better to set units to "bps", instead of letting it default to "bits per second".
See y-max in the generic section. If there is a generic y-max, it overrides the per-datasource y-max. If there are multiple per-datasource y-maxes, then the maximum of all of them is used.
See y-min above.
An HTML-style color specification consists of three hex numbers ranging from 00 to ff. The numbers represent the intensity of the red, green, and blue components of the final color. For an example of a correctly configured color dictionary, see the Defaults file in the root of the sample config tree.
The OID Dictionary
The OID dictionary is a convenient place to put OID's to make the
config files more readable. Before any SNMP operation, the user-supplied
OID is scanned. Any text parts of the OID that match an entry in the
OID dictionary get replaced. Note that this is a separate process from
variable expansion, for historical reasons. The keys and values in
this table are separated by whitespace. Each entry starts with the
keyword "OID".
In keeping with the conventions of ASN.1 and SNMP, OID names are case insensitive, must start with a letter, and can otherwise consist of letters and numbers.
The HTML Dictionary
The HTML dictionary holds components of the UI that is
created by the grapher using HTML. Before it is used,
the HTML dictionary is expanded with respect to itself.
Any runtime errors that the grapher finds while attempting to create the page are added to this tag. It is usually referenced in the page-footer.
Note that only errors that Cricket can find while it's running will show up here. Problems finding the Perl interpreter, or parsing grapher.cgi will still show up in the webserver's error log.
This is the complete version string, including the version number and the time it was packaged for release.
This is simply the version number from the complete Cricket version string.
This tag is set by the grapher to the title it expects to use on this page. It is normally referenced in the head tag.
This tag is incorporated into the HTML body tag. This is the perfect place to set a bacground color. It's not useful for much else, unless you want your graphs to play a MIDI file in the background.
This is HTML that will be inserted between the <head> and </head> tags. It can be used to incorporate a cascading style sheet into the Cricket user interface. This would allow you to easily control aspects of the UI design that are hardcoded in the source code.
To incorporate a CSS called "cricket.css", use a head tag like this:
html head <link rel="stylesheet" src="cricket.css" type="text/css"> |
This is the HTML that will go on the bottom of the page. As Cricket is shipped, it includes a link to the RRD Tool website. Tobias Oetiker, the author of RRD Tool, has respectfully asked frontend authors to feature a link to RRD Tool. Please take into account his wishes as you edit this tag.
The version of page-footer in the sample-config directory refers to a tag called contact, which can be used to put sub-tree specific contact information into the bottom of the page. This is only meant as an example. You might choose to put completely different information at the bottom of the page.
This is the HTML that will go at the top of the page, after the <body> tag, but before the rest of the user interface. As shipped, it illustrates how you might put a company logo on each page.
Each event should have the following tags set:
In this section, each script's functions and arguments are discussed. There is a set of common arguments that some of the scripts accept. Here are the common arguments:
The possible values are "error", "warn", "info", or "debug". Each setting includes the output created by any of the preceding settings. All diagnostic output goes to the standard error stream.
You can use this setting to use a different config tree. Experience shows, however, that it's simplest to just accept the defaults and install Cricket in an account of its own.
Collector is the script that runs every few minutes from cron in order to traverse the config tree, fetch data, and enter it into the RRD files. It's also used interactively to test configurations, and to convert old-style RRD files to RRD 1.x.x files.
The collector will process only the subtrees listed on the command line, unless there are none, in which case it will process the entire config tree. This feature is limited, however, to only the highest lever subtrees. For example, in the sample-config tree, you could only restrict collector to the "routers" subtree, no lower. These limits must be specified with the same path prefix as the config tree base is specified. Because the base defaults to a full path, you must also use full paths for the subtree limits. In addition, a subtree limit will not work correctly if there is a trailing slash on it.
When given the -convert option, the collector will attempt to upgrade old-style files it comes across to the new style. After the conversion is made, it will fetch and update the data values also. If it cannot complete the conversion, the update will harmlessly fail. If collector comes across a file that is already in the new format, it will skip the conversion, but fetch the data and update RRD files with the new data.
Except during conversion and testing, collector is usually run from collect-subtrees, which takes care of creating the huge command lines collector sometimes needs, and does other housekeeping. When testing a new subtree of the config-tree, you can use a command like "~/cricket/collector -logLevel debug /test-tree". Once you are certain the subtree is functioning correctly, you can add it to the collect-subtrees config file.
The grapher is almost never run from the command line, so options parsing is basically a moot point. The CGI script should get run by the web server automatically in response to accesses to files that end in CGI. Consult your web server documentation to find out how to make it work like this.
Because it's not generally possible to control the command line of grapher.cgi, it's critical that it either defaults to the correct base directory, or that it has the base directory hardcoded internally to it. The default base directory is $HOME/cricket-config. However, $HOME will only be set right if Cricket can guess it's username from it's URL. If there's any doubt, you should hard code the base directory by editing the first few lines of grapher.cgi.
This is basically a placeholder for when Cricket is more complicated (say it ain't so!) and requires an autoconf-generated configure script. At this point, it can point all the Cricket scripts at your Perl install, which is very helpful for sites which do not have Perl installed in a standard location.
This script will do the same kind of conversion "collector -convert" will do, but does it on single file at a time. You can give it several files on the command line, and it will attempt to convert each in turn.
Cricket gives you complete control over the contents and layout of your RRD files. This means that if you are going to be doing any serious target-type hacking, you need to understand the following concepts:
Now, with all those terms under your belt, you'll understand what I mean when I say that using the datasource, RRA, and targetType dictionaries, you can completely control the kind, source, and quantity of data you store. The RRA's in the sample-config reproduce MRTG 2.x's data format precisely, and that configuration has proven to work well for most needs. If you are going to be using Cricket for the jobs it comes ready to do, you'll simply need to copy the sample-config tree and make minor changes to the targets it specifies.
- Round Robin Array (RRA)
- This is where data is stored in an RRD. There is one RRA for each scale of data, for example 5 minute samples, 30 minute samples, and 2 hour samples. The same data is in each RRA, except it is sampled at a different rate. If an RRA can hold 12 samples and it is updated every 5 minutes, then it holds data spanning back one hour. The 13th sample will overwrite the 1st sample.
- Data Source
- A data source is one line on a graph, or one column of data if you think of the RRD as a tabular listing of data. One RRD can have many datasources in it. All up them must be updated with new data at once. Not all of them need to be graphed at once (see the information about datasource "views" below).
- Target
- A device that we are keeping stats on is a target. There is one RRD file on disk for every target. You can think of each target as a leaf on the config tree.
- Target Type
- The type of the target determines what kinds of data sources and RRA's makes up the target. When Cricket goes to update a target, it uses the target type to figure out what data to fetch about the target, and how to fetch it.
- Data Source Source (ds-source)
- This is the rather unfortunate name for the attribute of a data source that tells Cricket precisely where to fetch the data from, and which data to fetch. Encoded in the ds-source is the retrieval method (via SNMP or running a program right now) and a description of the data we want.
If you need to customize Cricket to talk to other things, then you'll be following the following general steps:
1. Create entries in the datasource dictionary that tell Cricket how to fetch your new measurement. If you are using SNMP, you'll probably want to add an entry to the OID dictionary in the same subtree, to make your datasource entry readable. For instance, say we wanted to use Cricket to talk via SNMP to an agent running on a Unix machine, and fetch the load average. We would add the OID for the load average to the OID table, then add a new entry (named "load-average") to the datasource dictionary that described this new datasource.2. Create a targetType entry to tell Cricket what datasources make up your new target-type. Assuming the RRA definitions from the --default-- entry are right, you only need to add set the "ds" tag for this entry. For the load average example, we'd put "ds=load-average" into a targetType entry named "unix-machine".
3. Create a new target who's target-type tag is set to the targetType you created in the last step. If you are using SNMP to talk to the host, you need to make certain the variable snmp-host is set (since it contributes to the snmp variable, which in turn is required in SNMP ds-sources). You could set the snmp-host tag explicitly for every tag, but that would be a pain. Instead, you could choose your target names to be hostnames, then use the auto-target-name to set snmp-host correctly all the time, by adding a line like snmp-host = %auto-target-name% to the --default-- entry for that sub-tree. If you have a rare case in your system where the target name is not the name you want to send SNMP packets to, then you could override the default snmp-host by setting snmp-host directly for that one target.
4. Run the collector on your new subtree, using the "-loglevel debug" option. This will tell you exactly what Cricket thinks things are set to when it tries to fetch your data, as well as what exactly happened when it went to fetch the data.
If you come up with an interesting configuration, please send it in to me so that I can integrate it into the sample-configs tree for future versions.
If you need to add a new kind of data gathering subroutine, you'll want to read the code to snmp.pm very carefully and make a module like it to collect your data. It's not too hard, but it might not be worth the effort -- consider using a simple Perl script to let you fetch the data via the exec method. See the http-performance sub-tree for an example of how to do this.
Interface mapping lets you configure Cricket to talk to devices based on one of the other keys in this table. The mapping part comes in when Cricket turns the key you give it into an instance number. It does this in an efficient way, which is guaranteed to be right no matter what kind of row re-arranging goes on on the router. (It seems cruel, but they are allowed to re-arrange their rows at any time. This would presumably not be part of what makes SNMP "simple".)
On the other hand, if you want to setup Cricket to use a different key (say, the IP address, or maybe the human-readable descriptions Cisco routers support), or to monitor something else via SNMP that lives in tables, then you need to read on and understand the map dictionary, and how it is used to control the interface mapping algorithm.
There are two interesting tags in a map entry that control this process. The first is the baseOID, which tells Cricket which column of which table it is going to be looking through to find the match. For the interface-name map, this is set to "ifDescr". Cricket will look up the name "ifDescr" in the OID table, and will use the resulting OID as the base-oid for an SNMP walk of the table. The other interesting tag is match, which is a string that the fetched column will be compared to. This string is expanded with respect to the target dictionary, so you can use the "%tag%" syntax there. In the sample config, we compare the ifDescr column of the interface table to "%interface-name%", which gets expanded to the current value of the the tag interface-name in the current target. If the string starts and ends with the slash character, then it is used as a Perl regular expression and a case-insensitive RE match is done, instead of a simple string match. Use this feature only when necessary. A string match is preferable, since it has less overhead.
The system is efficient and accurate. It uses an RRD metafile to store the last-used index (avoiding gratuitous table-scans) and uses an internal cache to minimize table-scans, should they be necessary. It is accurate because every time Cricket fetches data using a cached instance number, it also fetches the key in the same packet. If the key no longer matches, then the cache is invalidated, a table-scan is done to map the instance number, and the data is re-fetched using the new instance number. The maximum cost of this system is one table-scan per host anytime an instance changes, and one extra variable fetched per target.
Instance mapping is only enabled when the inst tag starts with "map(". This means that hard-coded instances and instance ranges are still completely supported, if you are not ready to use the instance mapping feature.
When it comes time to do a table scan, the instance mapping code uses the tag named snmp from the current target to find the community string, host, and port for the SNMP transaction. As discussed above, the snmp tag, by convention, has the community string, host, and port in it in a format ready to plug into SNMP ds-sources. Thus, even if you've come up with a different way to encode community string, host, and port into your datasources, you still need to have a tag named snmp for the instance mapping code to use.
The moral of the story is to try very hard to not mess with the sample-config tree. (The quote "Though this be madness, let there be a method in it." comes to mind...) It's setup the way it is for a reason, and though you may be able to make it more efficient in some ways, you won't end up with a config tree that is as flexible and broadly-applicable. Thus, I might do something later which breaks your config tree without meaning to do so. And I won't feel very sorry about it, now that you know better.
In January 1998, Tobias Oetiker released some of the first versions of the RRD tool. I took a look at this work and immediately recognized that half of my problems with MRTG would be solved by switching to using RRD as the backend, instead of rateup, the old backend for MRTG. RRD was designed to be much more flexible and much higher performance than rateup. However, RRD did not promise to make any dent at all in the complexity of our MRTG configuration, nor was it immediately obvious how we could extend MRTG to take advantage of RRD's new flexibility.
During the Spring of 1998, Tobias continued to work on RRD, but little work was being done to integrate it into a future version of MRTG. There are only so many hours in a day, afterall, and Tobias does need to earn a living too. I kept thinking about the problems facing WebTV, and how we could best put to use the really neat RRD tool while solving our config file (and, to a lesser extent, parallelization) problems. The answer was the config tree. After writing a small proof of concept, I sold my bosses on paying a contractor (Emmett Hogan) from Global Networking and Computing (http://www.gnac.com) to implement the design for an RRD frontend using the config tree idea. This project was to be a six week job, starting around July, 1998. This new frontend for RRD came to be called Super MRTG, or SMRTG.
As is often (almost always?) the case, it was very hard to predict how much time would actually be required to do the job. During Emmett's work, we learned a bunch more about how we wanted the final system to work. Emmett's finished product was still not ready to replace MRTG here at WebTV, and we were not ready to release it under the GPL. I took over SMRTG and added the features we needed to put it into production at WebTV. I also released a few versions of SMRTG to the MRTG-developers mailing list for review.
About this point a number of things happened. First, I realized that I was really unhappy with the name SMRTG for several reasons. It was too cumbersone, the project is only tangentially about routers at this point, and there was not a line of MRTG code in SMRTG -- it only looked the same. Thus, we needed a new name. I called it Cricket because it popped into mind. It's short and catchy, and there seems to be no other piece of network management software called Cricket. (There was a really cool piece of graphing software for the Mac called Cricket Graph, which might have tickled my subconscious.)
Also, Tobias and I talked about Cricket's, RRD's, and MRTG's futures. We agreed that Cricket and RRD made good partners, but that RRD is useful on it's own too. (Thus, RRD and Cricket will be distributed separately for the forseeable future.) We also agreed that it made no sense for him to duplicate my effort on the frontend, so it's unlikely there will ever be a version of MRTG that uses RRD as it's backend. Instead, we will try to help people convert to using Cricket if they need the performance of RRD. (And who doesn't!) As you can see from this history, Cricket would not exist if it wasn't for MRTG and RRD, two of Tobias' ultra-cool inventions. I am deeply indebted to that giant for letting me stand on his shoulders.
Today, in January 1999, Cricket is installed at WebTV Networks and is monitoring over 4500 targets, with over 10 different target types represented. Cricket takes data from SNMP, shell scripts, and files. During the 1998 Holiday season, Cricket gave us unprecedented visibility into the health of the WebTV Service. It has paid for itself, and we genuinely hope it will be as productive at your site.
As of version 0.68, Cricket can run under mod_perl. Typically, no special code needs to be added to scripts to make them work in the mod_perl environment, but Cricket's lazy use of namespaces required some fixup work. Mea culpa. That work has been done now, and going forward, I intend to make sure Cricket works under mod_perl.
If you'd like to use Cricket under mod_perl, you need to first fetch and install Apache with the mod_perl module. Cricket has only been tested so far with Apache 1.3.6 and mod_perl 1.19. The best way to build and install Apache and mod_perl is to fetch both packages, uncompress and untar them into one directory, then go into the mod_perl directory first and follow the directions in the INSTALL.apaci file.
Once you have an installation of Apache with mod_perl installed, you need to add lines like the following to your httpd.conf file:
<Files *.cgi> SetHandler perl-script PerlHandler Apache::Registry Options ExecCGI </Files> |
These lines tell your webserver that whenever it sees a file ending in .cgi, it should let the embeded Perl interpreter run it. This, of course, is problematic if you have some .cgi files on your webserver that cannot be run by Perl. In that case, you should use a more restrictive specification than "*.cgi" to limit the scope of the directives to files in the Cricket user's home directory.
There seems to be a bug which causes Apache to fail to find a library file in some cases. Confusingly, this tends to happen when it's trying to handle a URL that points to an image, resulting in missing images. This is strange, since serving up images should not require the Perl interpreter. You can fix this by setting the PERL5LIB environment variable to the Cricket library directory before starting the Apache webserver.
If you are going to be editing the library files (i.e. to add a new feature), you'll want to definately add the "PerlInitHandler Apache::StatINC" directive to your config file. This will make mod_perl check library timestamps and reload/reparse them when necessary. You should not run a production server with this enabled, since it does some extra work each time a library is used, which could be avoided. If you are not using the StatINC module, you will need to restart your server anytime you change a library file, or else the changes will not be picked up.
Since I am running out of time, here's a quick listing of which parsers each kind of data uses:
Since I am still running short on time, here's a listing of valid characters in various names. If you break these rules, you will get strange, confusing, undocumented behavior. Please don't do this, since it will result in very unhappy e-mail to me. If you'd like to help make Cricket more resistant to these types of errors, go for it, and send me a patch!
Also, avoid choosing names that begin and end with two dashes (like '--default--'). Future additions to the system will use names like this.