root/docs/config/modules/snmp.xml

Revision 93c0edcfee207d81926d7e38ac2ed4ad628e7f87, 17.2 kB (checked in by Theo Schlossnagle <jesus@omniti.com>, 4 months ago)

Provide feature parity (sans walk) with the jezebel version of snmp.
This adds support for "separate_queries" and SNMPv3.

  • Property mode set to 100644
Line 
1 <?xml version="1.0"?>
2 <section xmlns="http://docbook.org/ns/docbook" version="5">
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     <variablelist>
22       <varlistentry>
23         <term>debugging</term>
24         <listitem>
25           <variablelist>
26             <varlistentry>
27               <term>required</term>
28               <listitem>
29                 <para>optional</para>
30               </listitem>
31             </varlistentry>
32             <varlistentry>
33               <term>default</term>
34               <listitem>
35                 <para>0</para>
36               </listitem>
37             </varlistentry>
38             <varlistentry>
39               <term>allowed</term>
40               <listitem>
41                 <para>\d+</para>
42               </listitem>
43             </varlistentry>
44           </variablelist>
45           <para>Enable debugging output within libnetsnmp-c.</para>
46         </listitem>
47       </varlistentry>
48     </variablelist>
49   </section>
50   <section>
51     <title>Check Configuration</title>
52     <variablelist>
53       <varlistentry>
54         <term>community</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>public</para>
67               </listitem>
68             </varlistentry>
69             <varlistentry>
70               <term>allowed</term>
71               <listitem>
72                 <para>.+</para>
73               </listitem>
74             </varlistentry>
75           </variablelist>
76           <para>The SNMP community string providing read access.</para>
77         </listitem>
78       </varlistentry>
79     </variablelist>
80     <variablelist>
81       <varlistentry>
82         <term>port</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>161</para>
95               </listitem>
96             </varlistentry>
97             <varlistentry>
98               <term>allowed</term>
99               <listitem>
100                 <para>\d+</para>
101               </listitem>
102             </varlistentry>
103           </variablelist>
104           <para>The UDP port to which SNMP queries will be sent.</para>
105         </listitem>
106       </varlistentry>
107     </variablelist>
108     <variablelist>
109       <varlistentry>
110         <term>version</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>default</term>
121               <listitem>
122                 <para>2c</para>
123               </listitem>
124             </varlistentry>
125             <varlistentry>
126               <term>allowed</term>
127               <listitem>
128                 <para>(?:1|2c|3)</para>
129               </listitem>
130             </varlistentry>
131           </variablelist>
132           <para>The SNMP version used for queries.</para>
133         </listitem>
134       </varlistentry>
135     </variablelist>
136     <variablelist>
137       <varlistentry>
138         <term>separate_queries</term>
139         <listitem>
140           <variablelist>
141             <varlistentry>
142               <term>required</term>
143               <listitem>
144                 <para>optional</para>
145               </listitem>
146             </varlistentry>
147             <varlistentry>
148               <term>default</term>
149               <listitem>
150                 <para>false</para>
151               </listitem>
152             </varlistentry>
153             <varlistentry>
154               <term>allowed</term>
155               <listitem>
156                 <para>(?:true|on|false|off)</para>
157               </listitem>
158             </varlistentry>
159           </variablelist>
160           <para>Issue a separate query (PDU) for each OID; only applicable to v1 and v2c.</para>
161         </listitem>
162       </varlistentry>
163     </variablelist>
164     <variablelist>
165       <varlistentry>
166         <term>context_name</term>
167         <listitem>
168           <variablelist>
169             <varlistentry>
170               <term>required</term>
171               <listitem>
172                 <para>optional</para>
173               </listitem>
174             </varlistentry>
175             <varlistentry>
176               <term>allowed</term>
177               <listitem>
178                 <para>.*</para>
179               </listitem>
180             </varlistentry>
181           </variablelist>
182           <para>The SNMPv3 context name.</para>
183         </listitem>
184       </varlistentry>
185     </variablelist>
186     <variablelist>
187       <varlistentry>
188         <term>context_engine</term>
189         <listitem>
190           <variablelist>
191             <varlistentry>
192               <term>required</term>
193               <listitem>
194                 <para>optional</para>
195               </listitem>
196             </varlistentry>
197             <varlistentry>
198               <term>allowed</term>
199               <listitem>
200                 <para>[0-9a-fA-F]+</para>
201               </listitem>
202             </varlistentry>
203           </variablelist>
204           <para>The SNMPv3 context engine id.</para>
205         </listitem>
206       </varlistentry>
207     </variablelist>
208     <variablelist>
209       <varlistentry>
210         <term>security_level</term>
211         <listitem>
212           <variablelist>
213             <varlistentry>
214               <term>required</term>
215               <listitem>
216                 <para>optional</para>
217               </listitem>
218             </varlistentry>
219             <varlistentry>
220               <term>default</term>
221               <listitem>
222                 <para>nanp</para>
223               </listitem>
224             </varlistentry>
225             <varlistentry>
226               <term>allowed</term>
227               <listitem>
228                 <para>(?:nanp|anp|ap)</para>
229               </listitem>
230             </varlistentry>
231           </variablelist>
232           <para>The SNMPv3 security level. nanp: noAuthNoPriv, anp: authNoPriv, ap, authPriv.</para>
233         </listitem>
234       </varlistentry>
235     </variablelist>
236     <variablelist>
237       <varlistentry>
238         <term>security_name</term>
239         <listitem>
240           <variablelist>
241             <varlistentry>
242               <term>required</term>
243               <listitem>
244                 <para>optional</para>
245               </listitem>
246             </varlistentry>
247             <varlistentry>
248               <term>allowed</term>
249               <listitem>
250                 <para>.*</para>
251               </listitem>
252             </varlistentry>
253           </variablelist>
254           <para>The SNMPv3 security name (user).</para>
255         </listitem>
256       </varlistentry>
257     </variablelist>
258     <variablelist>
259       <varlistentry>
260         <term>security_engine</term>
261         <listitem>
262           <variablelist>
263             <varlistentry>
264               <term>required</term>
265               <listitem>
266                 <para>optional</para>
267               </listitem>
268             </varlistentry>
269             <varlistentry>
270               <term>default</term>
271               <listitem>
272                 <para/>
273               </listitem>
274             </varlistentry>
275             <varlistentry>
276               <term>allowed</term>
277               <listitem>
278                 <para>[0-9a-fA-F]+</para>
279               </listitem>
280             </varlistentry>
281           </variablelist>
282           <para>The SNMPv3 security engine id.</para>
283         </listitem>
284       </varlistentry>
285     </variablelist>
286     <variablelist>
287       <varlistentry>
288         <term>auth_protocol</term>
289         <listitem>
290           <variablelist>
291             <varlistentry>
292               <term>required</term>
293               <listitem>
294                 <para>optional</para>
295               </listitem>
296             </varlistentry>
297             <varlistentry>
298               <term>default</term>
299               <listitem>
300                 <para>MD5</para>
301               </listitem>
302             </varlistentry>
303             <varlistentry>
304               <term>allowed</term>
305               <listitem>
306                 <para>(?:MD5|SHA)</para>
307               </listitem>
308             </varlistentry>
309           </variablelist>
310           <para>The SNMPv3 security authorization hashing algorithm.</para>
311         </listitem>
312       </varlistentry>
313     </variablelist>
314     <variablelist>
315       <varlistentry>
316         <term>auth_passphrase</term>
317         <listitem>
318           <variablelist>
319             <varlistentry>
320               <term>required</term>
321               <listitem>
322                 <para>optional</para>
323               </listitem>
324             </varlistentry>
325             <varlistentry>
326               <term>allowed</term>
327               <listitem>
328                 <para>.*</para>
329               </listitem>
330             </varlistentry>
331           </variablelist>
332           <para>The SNMPv3 security authorization passphrase</para>
333         </listitem>
334       </varlistentry>
335     </variablelist>
336     <variablelist>
337       <varlistentry>
338         <term>privacy_protocol</term>
339         <listitem>
340           <variablelist>
341             <varlistentry>
342               <term>required</term>
343               <listitem>
344                 <para>optional</para>
345               </listitem>
346             </varlistentry>
347             <varlistentry>
348               <term>allowed</term>
349               <listitem>
350                 <para>(?:DES|AES)</para>
351               </listitem>
352             </varlistentry>
353           </variablelist>
354           <para>The SNMPv3 security encryption algorithm.</para>
355         </listitem>
356       </varlistentry>
357     </variablelist>
358     <variablelist>
359       <varlistentry>
360         <term>privacy_passphrase</term>
361         <listitem>
362           <variablelist>
363             <varlistentry>
364               <term>required</term>
365               <listitem>
366                 <para>optional</para>
367               </listitem>
368             </varlistentry>
369             <varlistentry>
370               <term>allowed</term>
371               <listitem>
372                 <para>.*</para>
373               </listitem>
374             </varlistentry>
375           </variablelist>
376           <para>The SNMPv3 security privacy passphrase</para>
377         </listitem>
378       </varlistentry>
379     </variablelist>
380     <variablelist>
381       <varlistentry>
382         <term>oid_.+</term>
383         <listitem>
384           <variablelist>
385             <varlistentry>
386               <term>required</term>
387               <listitem>
388                 <para>optional</para>
389               </listitem>
390             </varlistentry>
391             <varlistentry>
392               <term>allowed</term>
393               <listitem>
394                 <para>.+</para>
395               </listitem>
396             </varlistentry>
397           </variablelist>
398           <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>
399         </listitem>
400       </varlistentry>
401     </variablelist>
402     <variablelist>
403       <varlistentry>
404         <term>type_.+</term>
405         <listitem>
406           <variablelist>
407             <varlistentry>
408               <term>required</term>
409               <listitem>
410                 <para>optional</para>
411               </listitem>
412             </varlistentry>
413             <varlistentry>
414               <term>allowed</term>
415               <listitem>
416                 <para>.+</para>
417               </listitem>
418             </varlistentry>
419           </variablelist>
420           <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>
421         </listitem>
422       </varlistentry>
423     </variablelist>
424     <variablelist>
425       <varlistentry>
426         <term>separate_queries</term>
427         <listitem>
428           <variablelist>
429             <varlistentry>
430               <term>required</term>
431               <listitem>
432                 <para>optional</para>
433               </listitem>
434             </varlistentry>
435             <varlistentry>
436               <term>default</term>
437               <listitem>
438                 <para>false</para>
439               </listitem>
440             </varlistentry>
441             <varlistentry>
442               <term>allowed</term>
443               <listitem>
444                 <para>^(?:true|false|on|off)$</para>
445               </listitem>
446             </varlistentry>
447           </variablelist>
448           <para>Whether or not to query each OID separately.</para>
449         </listitem>
450       </varlistentry>
451     </variablelist>
452   </section>
453   <section>
454     <title>Examples</title>
455     <example>
456       <title>Simple snmp polling of two switchports</title>
457       <para>The following example configures SNMP checks against switchport 1 and 2
458       on the switch with the IP address 10.80.116.3.</para>
459       <programlisting>
460       &lt;noit&gt;
461         &lt;modules&gt;
462           &lt;module image="snmp" name="snmp"/&gt;
463         &lt;/modules&gt;
464         &lt;checks&gt;
465           &lt;switch target="10.80.116.3" module="snmp"&gt;
466             &lt;config&gt;
467               &lt;community&gt;SeKr3t&lt;/community&gt;
468               &lt;oid_description&gt;IF-MIB::ifName.%[name]&lt;/oid_description&gt;
469               &lt;oid_alias&gt;IF-MIB::ifAlias.%[name]&lt;/oid_alias&gt;
470               &lt;oid_speed&gt;IF-MIB::ifSpeed.%[name]&lt;/oid_speed&gt;
471               &lt;oid_adminstatus&gt;IF-MIB::ifAdminStatus.%[name]&lt;/oid_adminstatus&gt;
472               &lt;oid_operstatus&gt;IF-MIB::ifOperStatus.%[name]&lt;/oid_operstatus&gt;
473               &lt;oid_inoctets&gt;IF-MIB::ifHCInOctets.%[name]&lt;/oid_inoctets&gt;
474               &lt;oid_outoctets&gt;IF-MIB::ifHCOutOctets.%[name]&lt;/oid_outoctets&gt;
475               &lt;oid_inerrors&gt;IF-MIB::ifInErrors.%[name]&lt;/oid_inerrors&gt;
476               &lt;oid_outerrors&gt;IF-MIB::ifOutErrors.%[name]&lt;/oid_outerrors&gt;
477               &lt;oid_indiscards&gt;IF-MIB::ifInDiscards.%[name]&lt;/oid_indiscards&gt;
478               &lt;oid_outdiscards&gt;IF-MIB::ifOutDiscards.%[name]&lt;/oid_outdiscards&gt;
479               &lt;oid_inucastpkts&gt;IF-MIB::ifHCInUcastPkts.%[name]&lt;/oid_inucastpkts&gt;
480               &lt;oid_outucastpkts&gt;IF-MIB::ifHCOutUcastPkts.%[name]&lt;/oid_outucastpkts&gt;
481               &lt;oid_inbcastpkts&gt;IF-MIB::ifHCInBroadcastPkts.%[name]&lt;/oid_inbcastpkts&gt;
482               &lt;oid_outbcastpkts&gt;IF-MIB::ifHCOutBroadcastPkts.%[name]&lt;/oid_outbcastpkts&gt;
483             &lt;/config&gt;
484             &lt;check uuid="1b4e28ba-2fa1-11d2-883f-e9b761bde3fb" name="1"/&gt;
485             &lt;check uuid="4deb0724-ccee-4360-83bc-255e7b9d989d" name="2"/&gt;
486           &lt;/switch&gt;
487         &lt;/checks&gt;
488       &lt;/noit&gt;
489     </programlisting>
490     </example>
491     <example>
492       <title>Example using config inheritance to show reuse</title>
493       <para>Accomplising the same goal, but by using reuse:</para>
494       <programlisting>
495       &lt;noit&gt;
496         &lt;modules&gt;
497           &lt;module image="snmp" name="snmp"/&gt;
498         &lt;/modules&gt;
499         &lt;checks&gt;
500           &lt;switch target="10.80.116.3" module="snmp"&gt;
501             &lt;config inherit="SwitchPortX"/&gt;
502               &lt;community&gt;SeKr3t&lt;/community&gt;
503             &lt;/config&gt;
504             &lt;check uuid="1b4e28ba-2fa1-11d2-883f-e9b761bde3fb" name="1"/&gt;
505             &lt;check uuid="4deb0724-ccee-4360-83bc-255e7b9d989d" name="2"/&gt;
506           &lt;/switch&gt;
507         &lt;/checks&gt;
508         &lt;config_templates&gt;
509           &lt;config id="SwitchPortX"&gt;
510             &lt;oid_description&gt;IF-MIB::ifName.%[name]&lt;/oid_description&gt;
511             &lt;oid_alias&gt;IF-MIB::ifAlias.%[name]&lt;/oid_alias&gt;
512             &lt;oid_speed&gt;IF-MIB::ifSpeed.%[name]&lt;/oid_speed&gt;
513             &lt;oid_adminstatus&gt;IF-MIB::ifAdminStatus.%[name]&lt;/oid_adminstatus&gt;
514             &lt;oid_operstatus&gt;IF-MIB::ifOperStatus.%[name]&lt;/oid_operstatus&gt;
515             &lt;oid_inoctets&gt;IF-MIB::ifHCInOctets.%[name]&lt;/oid_inoctets&gt;
516             &lt;oid_outoctets&gt;IF-MIB::ifHCOutOctets.%[name]&lt;/oid_outoctets&gt;
517             &lt;oid_inerrors&gt;IF-MIB::ifInErrors.%[name]&lt;/oid_inerrors&gt;
518             &lt;oid_outerrors&gt;IF-MIB::ifOutErrors.%[name]&lt;/oid_outerrors&gt;
519             &lt;oid_indiscards&gt;IF-MIB::ifInDiscards.%[name]&lt;/oid_indiscards&gt;
520             &lt;oid_outdiscards&gt;IF-MIB::ifOutDiscards.%[name]&lt;/oid_outdiscards&gt;
521             &lt;oid_inucastpkts&gt;IF-MIB::ifHCInUcastPkts.%[name]&lt;/oid_inucastpkts&gt;
522             &lt;oid_outucastpkts&gt;IF-MIB::ifHCOutUcastPkts.%[name]&lt;/oid_outucastpkts&gt;
523             &lt;oid_inbcastpkts&gt;IF-MIB::ifHCInBroadcastPkts.%[name]&lt;/oid_inbcastpkts&gt;
524             &lt;oid_outbcastpkts&gt;IF-MIB::ifHCOutBroadcastPkts.%[name]&lt;/oid_outbcastpkts&gt;
525           &lt;/config&gt;
526         &lt;/config_templates&gt;
527       &lt;/noit&gt;
528     </programlisting>
529     </example>
530   </section>
531 </section>
Note: See TracBrowser for help on using the browser.