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
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="HTML Tidy for Linux/x86 (vers 1st August 2004), see www.w3.org">
<title>SNMP Query XML Syntax</title>
<meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
<link rel="HOME" title="The Cacti Manual" href="index.html">
<link rel="UP" title="Data Queries" href="data_queries.html">
<link rel="PREVIOUS" title="Data Queries" href="data_queries.html">
<link rel="NEXT" title="Script Query XML Syntax" href="script_query_xml.html">
<link rel="STYLESHEET" type="text/css" href="manual.css">
</head>
<body class="SECT1" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="NAVHEADER">
<table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
<th colspan="3" align="center">The Cacti Manual</th>
</tr>
<tr>
<td width="10%" align="left" valign="bottom"><a href="data_queries.html" accesskey="P">Prev</a></td>
<td width="80%" align="center" valign="bottom">Chapter 10. Data Queries</td>
<td width="10%" align="right" valign="bottom"><a href="script_query_xml.html" accesskey="N">Next</a></td>
</tr>
</table>
<hr align="left" width="100%">
</div>
<div class="SECT1">
<h1 class="SECT1"><a name="SNMP_QUERY_XML" id="SNMP_QUERY_XML">SNMP Query XML Syntax</a></h1>
<pre class="PROGRAMLISTING">
<query>
<name>Get SNMP Interfaces</name>
<description>Queries a host for a list of monitorable interfaces</description>
<oid_index>.1.3.6.1.2.1.2.2.1.1</oid_index>
<oid_index_parse>OID/REGEXP:.*\.([0-9]{1,3}\.[0-9]{1,3})$</oid_index_parse>
<oid_num_indexes>.1.3.6.1.2.1.2.1.0</oid_num_indexes>
<index_order>ifDescr:ifName:ifIndex</index_order>
<index_order_type>numeric</index_order_type>
<index_title_format>|chosen_order_field|</index_title_format>
<fields>
<ifIndex>
<name>Index</name>
<method>walk</method>
<source>value</source>
<direction>input</direction>
<oid>.1.3.6.1.2.1.2.2.1.1</oid>
</ifIndex>
</fields>
</query>
</pre>
<div class="TABLE">
<a name="AEN895" id="AEN895"></a>
<p><b>Table 10-3. SNMP Query XML Field Reference</b></p>
<table border="1" frame="border" rules="all" class="CALSTABLE">
<col width="1*">
<col width="2*">
<thead>
<tr>
<th align="center">Field</th>
<th align="center">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>query->name</td>
<td>(Optional) You can enter a "friendly name" for the SNMP query here. It will not be used by Cacti, and is for identification only.</td>
</tr>
<tr>
<td>query->description</td>
<td>(Optional) You can enter a description for the SNMP query here. It will not be used by Cacti, and is for identification only.</td>
</tr>
<tr>
<td>query->oid_index</td>
<td>
<p>Every SNMP query must have an OID that represents the index values for the query when walked. As described above, any data query in Cacti must contain a field that uniquely identifies each row returned by the query. In the example above, the oid_index points to the OID of ifIndex in the interface MIB.</p>
<p><b class="EMPHASIS">Note:</b> Starting with version 0.8.6c, Cacti is able to parse unique indexes from the OID itself. While the regular expression used for parsing the value from the OID is defined below, you must still specify an OID that can be walked by Cacti in order to obtain the list of OID's. Any OID defined for one of your input fields should work in this case. The values returned from the snmpwalk walk will be completely disregarded.</p>
</td>
</tr>
<tr>
<td>query->oid_index_parse</td>
<td>This field should only be used if you are trying to parse the unique index from the OID itself. If this field is defined, to obtain a list of indexes, Cacti walks the OID provided in the <span class="PROPERTY">oid_index</span> field above. It then applies the regular expression provided in this field to the list of OID's that are returned. The matched substrings that remain become the list of indexes for this SNMP query.</td>
</tr>
<tr>
<td>query->oid_num_indexes</td>
<td>An OID that can be queried to determine the total number of available indexes. If specified, this will be used to determine when to automatically recache this SNMP query when it is attached to a device.</td>
</tr>
<tr>
<td>query->index_order</td>
<td>As of version 0.8.6, Cacti will attempt to find the best field to index off of based on whether each row in the query is unique and non-null. If specified, Cacti will perform this check on the fields listed here in the order specified. Only input fields can be specified and multiple fields should be delimited with a colon.</td>
</tr>
<tr>
<td>query->index_order_type</td>
<td>
<p>For sorting purposes, specify whether the index is numeric or alphanumeric.</p>
<p><code class="PARAMETER">numeric</code>: The indexes in this SNMP query are to be sorted numerically (ie. 1,2,3,10,20,31)</p>
<p><code class="PARAMETER">alphabetic</code>: The indexes in this SNMP query are to be sorted alphabetically (1,10,2,20,3,31).</p>
</td>
</tr>
<tr>
<td>query->index_title_format</td>
<td>Specify the title format to use when representing an index to the user. Any input field name can be used as a variable if enclosed in pipes (|). The variable <code class="PARAMETER">|chosen_order_field|</code> will be substituted with the field chosen by Cacti to index off of (see index_order above).</td>
</tr>
<tr>
<td>query->fields</td>
<td>Each field contained within the SNMP query must be defined under this tag.</td>
</tr>
<tr>
<td>query->fields->ifIndex</td>
<td>Each defined field in the SNMP query must have a unique name given to it. Do not use spaces or any non-alphanumeric characters, this name must be identifiable within Cacti.</td>
</tr>
<tr>
<td>query->fields->ifIndex->name</td>
<td>Here you can specify a "friendly name" for the field. This name will be used by Cacti to help the user identify this field.</td>
</tr>
<tr>
<td>query->fields->ifIndex->method</td>
<td>
<p>Tell Cacti how you want it to gather SNMP information for this field.</p>
<p><code class="PARAMETER">get</code>: The 'get' method obtains a list of indexes and does an snmpget for each index of the OID specified for this field.</p>
<p><code class="PARAMETER">walk</code>: The 'walk' method does a walk of the OID specified for this field. Both methods will return the same values, even though the 'walk' method is typically more efficient.</p>
</td>
</tr>
<tr>
<td>query->fields->ifIndex->source</td>
<td>
<p>When Cacti obtains a list for this field, you need to tell it how to derive its value for each row.</p>
<p><code class="PARAMETER">value</code>: The 'value' option simply returns the result of the snmpget for each row.</p>
<p><code class="PARAMETER">OID/REGEXP:(regexp_match)</code>: The 'OID/REGEXP:(regexp_match)' can be used when you need to use a POSIX-based regular expression to derive the value from the OID. The most common example of this is to retreive the IP address of an interface, and can be seen in the 'interface.xml' file.</p>
<p><code class="PARAMETER">VALUE/REGEXP:(regexp_match)</code>: The 'OID/REGEXP:(regexp_match)' option can be used to parse the value based on a regular expression, returning the first match.</p>
<p><code class="PARAMETER">index</code>: Simply use the value of the index for this row as the value. If the index is being parsed from the OID using the <span class="PROPERTY">oid_index_parse</span> field, you must specify <code class="PARAMETER">index</code> here.</p>
</td>
</tr>
<tr>
<td>query->fields->ifIndex->direction</td>
<td>
<p><code class="PARAMETER">input</code>: Input values are the "known" values that you will use to derive the output values, this is where the "query" part of SNMP query comes in. When you create a graph based on an SNMP query, Cacti will prompt you to choose the input value to base the graph on.</p>
<p><code class="PARAMETER">output</code>: Output values are "unknown" values that are returned from the script. An SNMP query may return multiple statistics for a single index. For instance, a single interface could return bytes/sec in, errors, packets/sec, etc.</p>
<p>A rule of thumb is that input fields contain semi-static data that is not graphable, while the output fields contain the data that will be graphed.</p>
</td>
</tr>
<tr>
<td>query->fields->ifIndex->oid</td>
<td>You must specify the actual OID that corresponds with the field. Each value for this field can be obtained by doing an snmpget on 'oid.(each)snmpindex'.</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="NAVFOOTER">
<hr align="left" width="100%">
<table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
<td width="33%" align="left" valign="top"><a href="data_queries.html" accesskey="P">Prev</a></td>
<td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">Home</a></td>
<td width="33%" align="right" valign="top"><a href="script_query_xml.html" accesskey="N">Next</a></td>
</tr>
<tr>
<td width="33%" align="left" valign="top">Data Queries</td>
<td width="34%" align="center" valign="top"><a href="data_queries.html" accesskey="U">Up</a></td>
<td width="33%" align="right" valign="top">Script Query XML Syntax</td>
</tr>
</table>
</div>
</body>
</html>
|
