File: inst-mapping.html

package info (click to toggle)
cricket 1.0.5-9
  • links: PTS
  • area: main
  • in suites: lenny
  • size: 1,480 kB
  • ctags: 390
  • sloc: perl: 8,287; sh: 920; ansic: 318; makefile: 62; sql: 16
file content (163 lines) | stat: -rw-r--r-- 7,704 bytes parent folder | download | duplicates (8)
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
<!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>Understanding Instance Mapping</title>
  </head>
  <body>
    <h1>Understanding Instance Mapping </h1>
    <p>
      Cricket has a nifty feature called instance mapping. Basically it's
      meant to take the busywork out of monitoring SNMP devices. In this
      document, you'll learn far more than you ever wanted to know about it.
    </p>

    <div>
      <h2>The Problem</h2>
      <p>
          In the SNMP world, when something is stored in a table, each
          table row has a number. These numbers, called instance
          numbers, are used to reference the rows. Since routers
          typically have lots of interfaces, they are stored in a
          table, indexed by these instance numbers. I can ask a router
          to give me the traffic measurements from row number 4, and
          it will know what I mean and go do it. However, when we
          humans think about router interfaces, we don't think about
          instance numbers. We think about some other identifier for
          the row, like the interface name or the IP address. 
      </p>
      <p>
        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 <b>not</b> be part of what makes SNMP
        "simple".)
      </p>
    </div>
    
    <div>
      <h2> What does this mean to me? </h2>
      <p>
        Nothing, as long as you are using the sample config tree's
        router-interface subtree. It comes ready to automatically do
        interface mapping using the interfaces name as a key. When
        you use <tt>listInterfaces</tt> to make an interfaces file,
        it will set the "interface-name" tag for you, and Cricket
        will use that to do the instance mapping automatically.
      </p>
      <p>
        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 <tt>map</tt>
        dictionary, and how it is used to control the interface
        mapping algorithm.
      </p>
    </div>
    
    <div>
      <h2>The Icky Details</h2>
      <p>
        When Cricket comes across an instance number which looks
        like <tt>map(interface-name)</tt>, then it knows that
        instead of using a hard-coded instance number, or an
        instance set, it will be using the instance mapping code to
        find the instance number. It uses the part inside the
        parenthesis ("interface-name" in the case above) to find an
        entry in the <tt>map</tt> dictionary that it can use to help
        map the given key to an instance number.
      </p>
      <p>
        There are two interesting tags in a <tt>map</tt> entry that
        control this process. The first is the <tt>baseOID</tt>,
        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 <tt>match</tt>, 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 <tt>interface-name</tt> 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.
      </p>
      <p>
        The system is efficient and accurate. It uses a file sitting
        right next to your RRD file 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.
      </p>
      <p>
        Instance mapping is only enabled when the <tt>inst</tt> 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.
      </p>
    </div>
    
    <div>
      <h2>The Ickiest Details</h2>
      <p>
        The SNMP queries done by the instance mapping algorithm are
        implemented semi-independently from the rest of Cricket's
        datasource management code. This is partly because it was
        easier to implement that way, and partly because instance
        mapping is an intrinsically SNMP-thing, and it probably will
        never make sense to talk about using instance mapping with
        an exec datasource.
      </p>
      <p>
        When it comes time to do a table scan, the instance mapping
        code uses the tag named <tt>snmp</tt> 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.
      </p>
      <p>
        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.
      </p>
    </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>