root/docs/config/modules/snmp.xml

Revision e3305dbe3e16ece53b7c3702e58c4b3885c1f789, 9.5 kB (checked in by Philip Maddox <pmaddox@circonus.com>, 7 months ago)

Add Ability To Query SNMP OIDs Individually

Added a control to the SNMP check to allow for querying all of
the OIDs for a check separately. This fixes the issue where some
SNMP servers are not configured to handle bulk OID requests, as
well as the SNMP v1 issue where sending a single bad OID can
invalidate the entire request.

  • Property mode set to 100644
Line 
1 <?xml version="1.0"?>
2 <section>
3   <title>snmp</title>
4   <para>The snmp module provides SNMP polling support for reconnoiter.</para>
5   <variablelist>
6     <varlistentry>
7       <term>loader</term>
8       <listitem>
9         <para>C</para>
10       </listitem>
11     </varlistentry>
12     <varlistentry>
13       <term>image</term>
14       <listitem>
15         <para>snmp.so</para>
16       </listitem>
17     </varlistentry>
18   </variablelist>
19   <section>
20     <title>Module Configuration</title>
21   </section>
22   <section>
23     <title>Check Configuration</title>
24     <variablelist>
25       <varlistentry>
26         <term>community</term>
27         <listitem>
28           <variablelist>
29             <varlistentry>
30               <term>required</term>
31               <listitem>
32                 <para>optional</para>
33               </listitem>
34             </varlistentry>
35             <varlistentry>
36               <term>default</term>
37               <listitem>
38                 <para>public</para>
39               </listitem>
40             </varlistentry>
41             <varlistentry>
42               <term>allowed</term>
43               <listitem>
44                 <para>.+</para>
45               </listitem>
46             </varlistentry>
47           </variablelist>
48           <para>The SNMP community string providing read access.</para>
49         </listitem>
50       </varlistentry>
51     </variablelist>
52     <variablelist>
53       <varlistentry>
54         <term>port</term>
55         <listitem>
56           <variablelist>
57             <varlistentry>
58               <term>required</term>
59               <listitem>
60                 <para>optional</para>
61               </listitem>
62             </varlistentry>
63             <varlistentry>
64               <term>default</term>
65               <listitem>
66                 <para>161</para>
67               </listitem>
68             </varlistentry>
69             <varlistentry>
70               <term>allowed</term>
71               <listitem>
72                 <para>\d+</para>
73               </listitem>
74             </varlistentry>
75           </variablelist>
76           <para>The UDP port to which SNMP queries will be sent.</para>
77         </listitem>
78       </varlistentry>
79     </variablelist>
80     <variablelist>
81       <varlistentry>
82         <term>version</term>
83         <listitem>
84           <variablelist>
85             <varlistentry>
86               <term>required</term>
87               <listitem>
88                 <para>optional</para>
89               </listitem>
90             </varlistentry>
91             <varlistentry>
92               <term>default</term>
93               <listitem>
94                 <para>2c</para>
95               </listitem>
96             </varlistentry>
97             <varlistentry>
98               <term>allowed</term>
99               <listitem>
100                 <para>(1|2c|3)</para>
101               </listitem>
102             </varlistentry>
103           </variablelist>
104           <para>The SNMP version used for queries.</para>
105         </listitem>
106       </varlistentry>
107     </variablelist>
108     <variablelist>
109       <varlistentry>
110         <term>oid_.+</term>
111         <listitem>
112           <variablelist>
113             <varlistentry>
114               <term>required</term>
115               <listitem>
116                 <para>optional</para>
117               </listitem>
118             </varlistentry>
119             <varlistentry>
120               <term>allowed</term>
121               <listitem>
122                 <para>.+</para>
123               </listitem>
124             </varlistentry>
125           </variablelist>
126           <para>Defines a metric to query.  Key oid_foo will establish a metric called foo.  The value of the parameter should be an OID either in decimal notation or MIB name.</para>
127         </listitem>
128       </varlistentry>
129     </variablelist>
130     <variablelist>
131       <varlistentry>
132         <term>type_.+</term>
133         <listitem>
134           <variablelist>
135             <varlistentry>
136               <term>required</term>
137               <listitem>
138                 <para>optional</para>
139               </listitem>
140             </varlistentry>
141             <varlistentry>
142               <term>allowed</term>
143               <listitem>
144                 <para>.+</para>
145               </listitem>
146             </varlistentry>
147           </variablelist>
148           <para>Defines a coercion for a metric type.  The name of the metric must identically match one of the oid_(.+) patterns. The value can be either one of the single letter codes in the metric_type_t enum or the following string variants: guess, int32, uint32, int64, uint64, double, string.</para>
149         </listitem>
150       </varlistentry>
151     </variablelist>
152     <variablelist>
153       <varlistentry>
154         <term>separate_queries</term>
155         <listitem>
156           <variablelist>
157             <varlistentry>
158               <term>required</term>
159               <listitem>
160                 <para>optional</para>
161               </listitem>
162             </varlistentry>
163             <varlistentry>
164               <term>default</term>
165               <listitem>
166                 <para>false</para>
167               </listitem>
168             </varlistentry>
169             <varlistentry>
170               <term>allowed</term>
171               <listitem>
172                 <para>^(?:true|false|on|off)$</para>
173               </listitem>
174             </varlistentry>
175           </variablelist>
176           <para>Whether or not to query each OID separately.</para>
177         </listitem>
178       </varlistentry>
179     </variablelist>
180   </section>
181   <example>
182     <title>Simple snmp polling of two switchports</title>
183     <para>The following example configures SNMP checks against switchport 1 and 2
184       on the switch with the IP address 10.80.116.3.</para>
185     <programlisting>
186       &lt;noit&gt;
187         &lt;modules&gt;
188           &lt;module image="snmp" name="snmp"/&gt;
189         &lt;/modules&gt;
190         &lt;checks&gt;
191           &lt;switch target="10.80.116.3" module="snmp"&gt;
192             &lt;config&gt;
193               &lt;community&gt;SeKr3t&lt;/community&gt;
194               &lt;oid_description&gt;IF-MIB::ifName.%[name]&lt;/oid_description&gt;
195               &lt;oid_alias&gt;IF-MIB::ifAlias.%[name]&lt;/oid_alias&gt;
196               &lt;oid_speed&gt;IF-MIB::ifSpeed.%[name]&lt;/oid_speed&gt;
197               &lt;oid_adminstatus&gt;IF-MIB::ifAdminStatus.%[name]&lt;/oid_adminstatus&gt;
198               &lt;oid_operstatus&gt;IF-MIB::ifOperStatus.%[name]&lt;/oid_operstatus&gt;
199               &lt;oid_inoctets&gt;IF-MIB::ifHCInOctets.%[name]&lt;/oid_inoctets&gt;
200               &lt;oid_outoctets&gt;IF-MIB::ifHCOutOctets.%[name]&lt;/oid_outoctets&gt;
201               &lt;oid_inerrors&gt;IF-MIB::ifInErrors.%[name]&lt;/oid_inerrors&gt;
202               &lt;oid_outerrors&gt;IF-MIB::ifOutErrors.%[name]&lt;/oid_outerrors&gt;
203               &lt;oid_indiscards&gt;IF-MIB::ifInDiscards.%[name]&lt;/oid_indiscards&gt;
204               &lt;oid_outdiscards&gt;IF-MIB::ifOutDiscards.%[name]&lt;/oid_outdiscards&gt;
205               &lt;oid_inucastpkts&gt;IF-MIB::ifHCInUcastPkts.%[name]&lt;/oid_inucastpkts&gt;
206               &lt;oid_outucastpkts&gt;IF-MIB::ifHCOutUcastPkts.%[name]&lt;/oid_outucastpkts&gt;
207               &lt;oid_inbcastpkts&gt;IF-MIB::ifHCInBroadcastPkts.%[name]&lt;/oid_inbcastpkts&gt;
208               &lt;oid_outbcastpkts&gt;IF-MIB::ifHCOutBroadcastPkts.%[name]&lt;/oid_outbcastpkts&gt;
209             &lt;/config&gt;
210             &lt;check uuid="1b4e28ba-2fa1-11d2-883f-e9b761bde3fb" name="1"/&gt;
211             &lt;check uuid="4deb0724-ccee-4360-83bc-255e7b9d989d" name="2"/&gt;
212           &lt;/switch&gt;
213         &lt;/checks&gt;
214       &lt;/noit&gt;
215     </programlisting>
216   </example>
217   <example>
218     <title>Example using config inheritance to show reuse</title>
219     <para>Accomplising the same goal, but by using reuse:</para>
220     <programlisting>
221       &lt;noit&gt;
222         &lt;modules&gt;
223           &lt;module image="snmp" name="snmp"/&gt;
224         &lt;/modules&gt;
225         &lt;checks&gt;
226           &lt;switch target="10.80.116.3" module="snmp"&gt;
227             &lt;config inherit="SwitchPortX"/&gt;
228               &lt;community&gt;SeKr3t&lt;/community&gt;
229             &lt;/config&gt;
230             &lt;check uuid="1b4e28ba-2fa1-11d2-883f-e9b761bde3fb" name="1"/&gt;
231             &lt;check uuid="4deb0724-ccee-4360-83bc-255e7b9d989d" name="2"/&gt;
232           &lt;/switch&gt;
233         &lt;/checks&gt;
234         &lt;config_templates&gt;
235           &lt;config id="SwitchPortX"&gt;
236             &lt;oid_description&gt;IF-MIB::ifName.%[name]&lt;/oid_description&gt;
237             &lt;oid_alias&gt;IF-MIB::ifAlias.%[name]&lt;/oid_alias&gt;
238             &lt;oid_speed&gt;IF-MIB::ifSpeed.%[name]&lt;/oid_speed&gt;
239             &lt;oid_adminstatus&gt;IF-MIB::ifAdminStatus.%[name]&lt;/oid_adminstatus&gt;
240             &lt;oid_operstatus&gt;IF-MIB::ifOperStatus.%[name]&lt;/oid_operstatus&gt;
241             &lt;oid_inoctets&gt;IF-MIB::ifHCInOctets.%[name]&lt;/oid_inoctets&gt;
242             &lt;oid_outoctets&gt;IF-MIB::ifHCOutOctets.%[name]&lt;/oid_outoctets&gt;
243             &lt;oid_inerrors&gt;IF-MIB::ifInErrors.%[name]&lt;/oid_inerrors&gt;
244             &lt;oid_outerrors&gt;IF-MIB::ifOutErrors.%[name]&lt;/oid_outerrors&gt;
245             &lt;oid_indiscards&gt;IF-MIB::ifInDiscards.%[name]&lt;/oid_indiscards&gt;
246             &lt;oid_outdiscards&gt;IF-MIB::ifOutDiscards.%[name]&lt;/oid_outdiscards&gt;
247             &lt;oid_inucastpkts&gt;IF-MIB::ifHCInUcastPkts.%[name]&lt;/oid_inucastpkts&gt;
248             &lt;oid_outucastpkts&gt;IF-MIB::ifHCOutUcastPkts.%[name]&lt;/oid_outucastpkts&gt;
249             &lt;oid_inbcastpkts&gt;IF-MIB::ifHCInBroadcastPkts.%[name]&lt;/oid_inbcastpkts&gt;
250             &lt;oid_outbcastpkts&gt;IF-MIB::ifHCOutBroadcastPkts.%[name]&lt;/oid_outbcastpkts&gt;
251           &lt;/config&gt;
252         &lt;/config_templates&gt;
253       &lt;/noit&gt;
254     </programlisting>
255   </example>
256 </section>
Note: See TracBrowser for help on using the browser.