1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>A Gentle Introduction to Cricket</title>
</head>
<body>
<h1>A Gentle Introduction to Cricket</h1>
<p>
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. 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.
</p>
<p>
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.
</p>
<div>
<h2>Understanding the config tree</h2>
<p>
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.
</p>
<div>
<h3>A guided tour</h3>
<p>
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.
</p>
<p>
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 <tt>sample-config/Defaults</tt>,
it's important to realize that unless those values get
overridden later, they will be used throughout the
entire config tree.
</p>
<p>
When Cricket goes to process a directory, it processes
the Defaults file first (if it exists), then it
processes each ordinary file, and finally it processes
each of the directories. 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.
</p>
<p>
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
<tt>rrd-datafile</tt> gets set to
"%dataDir%/%auto-target-name%.rrd".
</p>
<p>
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.
</p>
<p>
For instance, the example I chose above sets the tag
<tt>rrd-datafile</tt> to a proper filename made up of
the data directory, the target name, and the extension
".rrd". But you'll notice that <tt>dataDir</tt> 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 is referenced via an
expansion, then Cricket will log a warning, but it will
attempt to continue to use the partially expanded string.
</p>
<p>
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 <tt>dataDir</tt>
mentioned. That is simply a tag that exists to make the
definition <tt>rrd-datafile</tt> 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.
</p>
<p>
After Cricket expands a string, it scans the string for
substrings surrounded by curly braces (<tt>{like
this}</tt>). These substrings are passed to Perl's
<tt>eval()</tt> 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.
</p>
</div>
<div>
<h3>Target types, and datasources</h3>
<p>
Now, let us take a digression for a second to talk about
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.
</p>
<p>
To see this stuff in action, go into the
<tt>sample-config/routers</tt> 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.
</p>
</div>
<div>
<h3>Tacking a Target</h3>
<p>
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
<tt>--default--</tt>. 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
below that point. Take a look inside the file named
<tt>Targets</tt>. This file defines some real targets.
The sample config tree comes with two,
<tt>engineering-router</tt> and <tt>main-router</tt>.
These two dictionaries are added onto the bottom of the
config tree, and are sometimes referred to as leaves. A
leaf is where some work happens.
</p>
<p>
When Cricket comes to process the
<tt>engineering-router</tt> leaf node, the first step is
to build a working copy of the dictionary. Clearly the
information in the leaf node is not enough to collect
any data from the router. For one thing, we don't know
what the hostname of the router is, so we don't know
where to send the SNMP packets. This is where the
<tt>--default--</tt> dictionaries come in. To make the
complete working dictionary for this part of the config
tree, Cricket traverses all the nodes from the root down
to the current node, gathering together the
<tt>--default--</tt> dictionaries. Items lower in the
config tree override items higher up.
</p>
<p>
Cricket uses the <tt>target-type</tt> tag to decide what
method to use to fetch the data. If does this by finding
a <tt>targetType</tt> dictionary that matches the
<tt>target-type</tt> tag for the current target. This
targetType dictionary has a tag named <tt>ds</tt>, which
is a list of the datasources we expect to fetch from
this router. Each datasource is fetched in the same way,
and there Cricket discovers that it will be talking SNMP
to this router, in order to fetch 6 variables.
</p>
<p>
Next, Cricket turns over control to the SNMP fetcher.
The fetcher is trying to turn an SNMP URL into a
measurement. The SNMP URL for the data on the
engineering-router is
<tt>snmp://public@engineering-router:161/cpu1min</tt>.
But you've probably already noticed that the only thing
the fetcher seems to have to go on is the
<tt>ds-source</tt> tag, which has a <tt>%snmp%</tt>
where we expected to find the community string, hostname
and port.
</p>
<p>
How does Cricket manufacture the whole SNMP URL for this
target?
</p>
</div>
<div>
<h3>Explaining expansion</h3>
<p>
Immediately after Cricket makes the working dictionary
for a target it is working on, it fully expands the
target with respect to itself. Likewise, when Cricket
fetches a dictionary like the <tt>cpu1min</tt>
datasource dictionary, it is also expanded with respect
to the target dictionary. By the time the SNMP fetcher
is looking for the contents of the <tt>ds-source</tt>
tag, it has already been expanded to the correct value.
</p>
<p>
Let's unwind the expansions that contributed to changing
<tt>%snmp%</tt> into
<tt>public@engineering-router:161</tt>.
</p>
<pre>
From sample-config/Defaults
snmp-community = public
snmp-port = 161
snmp = %snmp-community%@%snmp-host%:%snmp-port%
From sample-config/routers/Defaults
router = %auto-target-name%
snmp-host = %router%
</pre>
<p>
You can see that one level about the leaf, the
<tt>snmp-host</tt> tag gets set (via the <tt>router</tt>
tag) to the name of the current target. Tags starting
with <tt>auto-</tt> are provided to you by Cricket.
There are a number of these automatic tags which are
discussed below. The rest of the <tt>snmp</tt> tag is
filled in by defaults inherited from all the way up at
the top of the config tree.
</p>
<p>
This is a good example of the power of the config tree.
If you were asked to monitor a new piece of network
hardware which had a slightly different community
string, you could put a <tt>snmp-community</tt> tag in
the target's dictionary and override the one normally
inherited from above. Alternatively, if you need to
change the community string on 1000 devices
simultaneously, you could do so by simply changing it at
the root, then allowing the change to filter down to
each of the 1000 targets in your config tree.
</p>
</div>
</div>
<p>
<a href="http://cricket.sourceforge.net">Cricket</a>
version 1.0.5, released 2004-03-28.
</p>
<p>
Copyright (C) 1998-2000 Jeff Allen. Cricket is released under
the <a href="gpl.html">GNU General Public License</a>.
</p>
</body>
</html>
|
