71513: Card tokenization [tokenize for unsaved cards, bug fix to saving from cust_main]
[freeside.git] / torrus / doc / snmpdiscovery.pod.in
1 #  Copyright (C) 2002-2009  Stanislav Sinyagin
2 #
3 #  This program is free software; you can redistribute it and/or modify
4 #  it under the terms of the GNU General Public License as published by
5 #  the Free Software Foundation; either version 2 of the License, or
6 #  (at your option) any later version.
7 #
8 #  This program is distributed in the hope that it will be useful,
9 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
10 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11 #  GNU General Public License for more details.
12 #
13 #  You should have received a copy of the GNU General Public License
14 #  along with this program; if not, write to the Free Software
15 #  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
16
17 # $Id: snmpdiscovery.pod.in,v 1.1 2010-12-27 00:04:35 ivan Exp $
18 # Stanislav Sinyagin <ssinyagin@yahoo.com>
19 #
20 #
21
22 =head1 Torrus SNMP Discovery User Guide
23
24 =head2 Introduction
25
26 In many (but not only) cases Torrus is used for SNMP monitoring.
27 It provides powerful tools which automate the process of devices' MIB
28 discovery.
29
30 The discovery tools consist of two programs: C<torrus devdiscover> performs
31 the SNMP discovery, based on the discovery instructions XML file.
32 The result of its work is a new Torrus datasource configuration file.
33 Another utility, C<torrus genddx>, is a program that generates the
34 basic discovery instructions file based on a set of commandline options.
35
36 The device discovery XML, or as we call them DDX files, are usually
37 resided in F<@siteconfdir@/discovery/> directory. This is the default
38 path to search for them when the absolute path is not given.
39
40 =head2 C<torrus genddx>: Discovery instructions generator
41
42   Usage: torrus genddx options...
43   Options:
44      --host=hostname         router hostname
45      --hostfile=filename     space-separated router hostnames file
46      --out=outfile           output file.         [routers.ddx]
47      --discout=filename      discovery output file [routers.xml]
48      --domain=domain         optional DNS domain name
49      --version=v             SNMP version         [2c]
50      --community=string      SNMP read community  [public]
51      --port=number           SNMP port            [161]
52      --retries=number        SNMP retries         [2]
53      --timeout=number        SNMP timeout         [10]
54      --subtree=string        Subtree name         [/Routers]
55      --datadir=path          data-dir parameter [@defrrddir@]
56      --holtwinters           Enable Holt-Winters analysis
57
58 This utility generates C<devdiscover> instructions XML file (DDX) based on
59 commandline options and a plain list of SNMP agents' hostnames.
60 Hostnames are specified with one or many C<--host=hostname> options,
61 or a plain text file with space-separated hostnames.
62
63 Each host may have a symbolic name. This symbolic name is used as
64 the host-level subtree name. The symbolic name follows the hostname with
65 a semicolon.
66
67 By default, the devices are placed into C</Routers/> subtree hierarchy.
68 You may change the subtree name with the I<--subtree> option.
69 Single slash as subtree name would cause host-level subtrees placed at the top
70 of the datasources tree.
71
72 By default, C<genddx> specifies the discovery output file as <routers.xml>,
73 and it would be placed in site XML configuration directory.
74 You most probably will change this by using the C<--discout> option.
75
76 Examples:
77
78   torrus genddx --out=ch-langenthal.ddx \
79     --discout=ch-langenthal.xml \
80     --host=192.168.34.35:Langenthal_PE1 \
81     --host=192.168.34.36:Langenthal_PE2 \
82     --host=192.168.34.37:Langenthal_CE_Stadtverwaltung \
83     --community=blahBlah \
84     --subtree=/MPLS/CH/Bern/Langenthal
85
86   torrus devdiscover --in=ch-langenthal.ddx
87
88 B<Note:> C<genddx> is designed as a one-time utility. You may run it to create
89 a typical discovery file with basic set of options. Then the discovery
90 configuration XML would be the primary source of information, and it should
91 be maintained by manual editing, or by some other automated means.
92 Alternatively you may use C<ttproclist> utility and generate highly customized
93 discovery instruction files based on static templates and lists of SNMP nodes.
94 See L<torrus_ttproclist(@mansec_usercmd@)> manpage for more details and
95 examples.
96
97
98
99 =head2 C<torrus devdiscover>: SNMP discovery tool
100
101   Usage: torrus devdiscover --in=filename.ddx options... [ddx files]
102   Options:
103    --in=filename.ddx       discovery instructions XML file(s)
104    --mkdir                 create data-dir directories
105    --limit=regexp          limit the discovery by output files
106    --forcebundle           always write the bundle file
107    --fallback=integer      maximum age of XML file to fall back to
108    --threads=integer       number of parallel discovery threads
109    --verbose               print extra information
110    --debug                 print debugging information
111    --snmpdebug             print SNMP protocol details
112
113 This utility performs the SNMP discovery of devices listed in the input
114 DDX file. The output XML file is the Torrus datasources configuration.
115 Output file name is taken from C<output-file> parameter in the DDX.
116 If the output file is not an absolute path, the file is placed
117 in the site XML configuration directory (F<@sitexmldir@>).
118
119 C<devdiscover> is accompanied by a number of MIB- or vendor-specific
120 modules, each responsible for finding specific SNMP variables in
121 the SNMP device, and for generating a piece of Torrus configuration XML
122 file responsible for that specific MIB. The list of supported generic MIBs and
123 vendors is constantly growing. It is quite easy to create new discovery
124 modules, and the internals are documented in
125 I<Torrus SNMP Device Discovery Developer's Guide>.
126
127 The output file automatically includes all required prerequisite
128 generic and vendor template definition files.
129
130 Behaviour of C<devdiscover> is controlled by variables in
131 F<@siteconfdir@/devdiscover-siteconfig.pl> file. Default values for
132 those variables reside in F<@cfgdefdir@/devdiscover-config.pl>.
133
134 For large installations, it is recommended to place RRD files into
135 a hashed directory structure. You can enable this feature by setting
136
137   $Torrus::DevDiscover::hashDataDirEnabled = 1;
138
139 in your F<devdiscover-siteconfig.pl> file.
140 Then launching C<devdiscover> with C<--mkdir> option would automatically
141 create the subdirectories inside C<data-dir>.
142
143 The XML files produced by C<devdiscover> may be automatically changed
144 with some local site-specific scripts. See XUpdate usage example in
145 I<Torrus User Guide>.
146
147
148 =head2 DDX, the discovery instructions file
149
150 The input file for C<devdiscover> is an XML file. Its DTD is available
151 in Torrus distribution in F<snmp-discovery.dtd>.
152
153 A typical place to store the discovery XML is F<@siteconfdir@/discovery/>.
154
155 Example:
156
157     <?xml version="1.0" encoding="UTF-8"?>
158     <snmp-discovery>
159       <file-info>
160         <format-version>
161     1.0
162         </format-version>
163       </file-info>
164       <creator-info>
165     Torrus version 0.1.4d
166     This file was generated by command:
167     /usr/local/torrus-0.1/bin/genddx \
168      --discout=share/torrus/xmlconfig/myrouters.xml \
169      --community=blahblah  --host=10.0.0.1  --host=10.0.1.1
170     On Tue Dec  2 17:43:30 2003
171       </creator-info>
172       <param name="data-dir" value="@defrrddir@"/>
173       <param name="domain-name" value=""/>
174       <param name="host-subtree" value="/Routers"/>
175       <param name="output-file" value="myrouters.xml"/>
176       <param name="rrd-hwpredict" value="no"/>
177       <param name="snmp-community" value="blahblah"/>
178       <param name="snmp-port" value="161"/>
179       <param name="snmp-retries" value="2"/>
180       <param name="snmp-timeout" value="10"/>
181       <param name="snmp-version" value="2c"/>
182       <host>
183         <param name="snmp-host" value="10.0.0.1"/>
184         <param name="symbolic-name" value="10.0.0.1"/>
185       </host>
186       <host>
187         <param name="snmp-host" value="10.0.1.1"/>
188         <param name="symbolic-name" value="10.0.1.1"/>
189       </host>
190     </snmp-discovery>
191
192 =head3 XML elements
193
194 =over 4
195
196 =item * C<snmp-discovery>
197
198 Mandatory. The top-level element.
199
200 =item * C<file-info>
201
202 Mandatory. It must contain the element C<format-version>.
203
204 =item * C<format-version>
205
206 Mandatory. It must contain a format version currently
207 supported by devdiscover. Currently supported version is C<1.0>.
208
209 =item * C<creator-info>
210
211 Optional. May contain the information about the file creator: a human author
212 name, or a program.
213
214 =item * C<param>
215
216 Some parameters are mandatory. This element defines a global or host-specific
217 parameter. Mandatory attribute C<name> identifies the parameter,
218 and the value is taken eother from C<value> attribute, or from the
219 textual content of the element.
220
221 C<param> element should be the child element of C<snmp-discovery> for global
222 parameters or C<host> for host-level parameters. Host-level parameters
223 override the values of global parameters.
224
225 These parameters are for C<devdiscover> only. They are not Torrus configuration
226 parameters, although some of them are directly copied into the generated
227 configuration file.
228
229 =item * C<host>
230
231 Mandatory. Defines a host to run SNMP discovery.
232
233 =back
234
235
236 =head3 Common parameters
237
238 =over 4
239
240 =item * C<collector-period>, C<collector-timeoffset>,
241 C<collector-dispersed-timeoffset>, C<collector-timeoffset-min>,
242 C<collector-timeoffset-max>, C<collector-timeoffset-step>,
243 C<monitor-period>, C<monitor-timeoffset>
244
245 Optional. When defined, these parameters override those from C<snmp-defaults>
246 template in F<snmp-defs.xml>.
247
248 =item * C<output-file>
249
250 Mandatory. Specifies the output filename for generated Torrus configuration.
251 If it's a relative path, the file is placed in F<@sitexmldir@> directory.
252
253 =item * C<output-bundle>
254
255 Optional. Specifies a comma-separated list of XML file names for bundle
256 output. Each bundle file will contain E<lt>includeE<gt> statement for each
257 corresponding C<output-file>.
258
259 =item * C<snmp-ipversion>, C<snmp-transport>, C<snmp-port>,
260         C<snmp-community>,  C<snmp-version>, C<snmp-timeout>,
261         C<snmp-retries>, C<snmp-host>, C<snmp-username>, C<snmp-authkey>,
262         C<snmp-authpassword>, C<snmp-authprotocol>, C<snmp-privkey>,
263         C<snmp-privpassword>, C<snmp-privprotocol>
264
265 Mandatory SNMP session parameters. Authentication parameters depend on the
266 SNMP version used. See the I<XML Configuration Guide> for details.
267 These parameters define the SNMP agent properties and are
268 copied one-to-one to the output configuration.
269
270 =item * C<domain-name>
271
272 Optional. Defines a DNS domain name to be appended to C<snmp-host>.
273
274 =item * C<snmp-localaddr> and C<snmp-localport>
275
276 Optional parameters specifying the local socket binding address and port.
277
278 =item * C<data-dir>
279
280 Mandatory. Defines the directory path where RRD files for this host
281 are stored. In case if hashed directories are enabled, C<data-dir> specifies
282 the base path under which the hashed subdirectories are created.
283
284 =item * C<symbolic-name>
285
286 Optional. Determines the host-specific subtree name. If not specified,
287 the subtree is named by C<system-id>, or by C<snmp-host> if system ID is
288 not defined.
289
290 =item * C<system-id>
291
292 Optional. If defined, it overrides the default value of system ID, which
293 is equal to the value of C<snmp-host>.
294
295 =item * C<nodeid-device>
296
297 Optional. Defines the host-specific reference for I<nodeid>. Default value
298 is equal to C<system-id>.
299
300 =item * C<snmp-oids-per-pdu>
301
302 Optional. When defined, these parameters overwrites the value from the
303 template and vendor-specific discovery modules.
304
305 =item * C<snmp-check-sysuptime>
306
307 Optional. Default: C<yes>. Devdiscover sets this parameter to C<no> when it
308 finds SNMPv2-MIB::sysUpTime variable unavailable in the device.
309
310 =item * C<snmp-max-msg-size>
311
312 Optional. If defined, it sets the SNMP maximum message size different from
313 default. The default value is 1470 (defined in Net::SNMP).
314
315 =item * C<host-subtree>
316
317 Optional. Defines the datasourse tree path under which the host-specific
318 subtree is created.
319
320 =item * C<rrd-hwpredict>
321
322 Optional. Valid values: C<yes>, C<no>. Determines if Holt-Winters forecasting
323 should be enabled for the given host.
324
325 =item * C<disable-devtypes>
326
327 Optional. Comma-separated list of discovery device types that need to be
328 excluded from discovery process. For example, ATMEL appliances conflict with
329 Empire SystemEdge MIBs, and you need to disable C<EmpireSystemedge> module
330 in order to run the discovery on those appliances.
331
332 =item * C<only-devtypes>
333
334 Optional comma-separated list of device types. If defined, only the specified
335 types will be used for device probing.
336
337 =item * C<host-aliases>
338
339 Optional comma-separated list of alias paths for a given host. Aliases
340 must be unique for each host.
341
342 =item * C<custom-host-templates>
343
344 Optional comma-separated list of template names that will be applied
345 to the resulting XML configuration at the host level.
346
347 =item * C<include-files>
348
349 Optional comma-separated list of XML files that will be listed in C<include>
350 statements in the resulting XML output.
351
352
353 =item * C<host-copy-params>
354
355 Optional comma-separated list of parameter names that should be copied
356 from the discovery configuration file to the generated Torrus configuration
357 at the host level.
358
359 =item * C<selectors>
360
361 Optional comma-separated list of object selectors. They are explained in more
362 detail below.
363
364 =item * C<disable-snmpcollector>
365
366 When set to C<yes>, this parameter disables SNMP collection for this
367 host. It is useful for creating custom views, in conjunction with
368 C<RFC2863_IF_MIB::only-interfaces> parameter.
369
370 =item * C<define-tokensets>
371
372 Semicolon-separated (;) list of pairs of tokenset names and descriptions.
373 Each tokenset name is followed by colon (:) and the description text:
374
375   <param name="define-tokensets">
376     important-graphs: Important Graphs;
377     unimportant-graphs: Unimportant Graphs
378   </param>
379
380 =item * C<suppress-legend>
381
382 if set to C<yes>, the legend is not shown. It usually has uptime,
383 software version, and contact information for the SNMP device.
384
385 =item * C<comment>
386
387 Sets the comment string for the host.
388
389 =item * C<show-recursive>
390
391 Default: C<yes>. When set to C<no>, the link to the recursive view at the
392 host level is omitted.
393
394 =item * C<template-registry-overlays>
395
396 If defined, this should be a comma-separated list of template registry
397 entries that override the default template references. The overlaying
398 templates should be referred in
399 C<%Torrus::DevDiscover::templateOverlays>.
400 For example, we want to redefine the interface counter template. Then
401 in the DDX file, we set
402
403   <param name="template-registry-overlays" value="my_ifcounters"/>
404
405 Then in F<devdiscover-siteconfig.pl> we set 
406
407   %Torrus::DevDiscover::templateOverlays = {
408       'my_ifcounters' => {
409           'RFC2863_IF_MIB::iftable-octets' => {
410              'name'   => 'my-iftable-octets',
411              'source' => 'mycustom-rfc2863.if-mib.xml'
412              },
413          'RFC2863_IF_MIB::ifxtable-hcoctets' => {
414              'name'   => 'my-ifxtable-hcoctets',
415              'source' => 'mycustom-rfc2863.if-mib.xml'
416              },
417          }};
418
419
420 =back
421
422
423 =head3 Parameters for C<RFC2863_IF_MIB>
424
425 This discovery module is responsible for agent's interfaces table and
426 interface counters. Recognized optional parameters are:
427
428 =over 4
429
430 =item * C<RFC2863_IF_MIB::suppress-hc-counters>
431
432 Some agents do not implement 64-bit counters correctly. When this parameter
433 is set to C<yes>, 64-bit interface counters are not used for the host.
434 For Cisco IOS devices, the C<CiscoIOS> discovery module tries to detect
435 such situation automatically.
436
437 =item * C<RFC2863_IF_MIB::subtree-name>
438
439 Defines the child subtree name within host-level subtree where interface
440 counters are located. Default: C<Interface_Counters>.
441
442 =item * C<RFC2863_IF_MIB::subtree-comment>
443
444 Defines the comment string for interface counters subtree.
445 Default: I<Interface traffic and error counters>.
446
447 =item * C<RFC2863_IF_MIB::list-admindown-interfaces>
448
449 If set to C<yes>, interfaces with ifAdminStatus set to other than up(1)
450 are included in the discovery results.
451 By default, such interfaces are not listed.
452
453 =item * C<RFC2863_IF_MIB::list-notpresent-interfaces>
454
455 If set to C<yes>, the interfaces with ifOperStatus status set to notPresent(6)
456 are included in the discovery results. By default, such interfaces are
457 not listed.
458
459 =item * C<RFC2863_IF_MIB::exclude-down-interfaces>
460
461 If set to C<yes>, the interfaces with ifOperStatus equal to down(2)
462 are excluded from the discovery results.
463
464 =item * C<RFC2863_IF_MIB::exclude-interfaces>
465
466 Comma-separated list of interface names which should be excluded from
467 configuration. Spaces are allowed between the names and commas.
468 The names should be the ones that are used for interface subtrees.
469
470 =item * C<RFC2863_IF_MIB::only-interfaces>
471
472 If defined, this parameter specifies the list of interfaces that will be
473 included in the discovery results. The names should match the interface
474 subtree names. Caution: if specified incorrectly, this parameter may
475 disable discovery for all interfaces on a device.
476
477 =item * C<RFC2863_IF_MIB::tokenset-members>
478
479 This parameter defines which interfaces' C<InOut_bps> leaves to add to
480 which tokensets. The value is a semicolon-separated (;) list of
481 entries of form I<tset:interface,interface>, where I<tset> is a name of the
482 tokenset, and the I<interface> is the subtree name of the corresponding
483 interface. The token sets must be defined elsewhere in Torrus configuration.
484 Example:
485
486   <host>
487     <param name="snmp-host" value="192.168.49.131"/>
488     <param name="RFC2863_IF_MIB::tokenset-members">
489      clusters: 10_1, 10_2;
490      uplinks: 1_1, 1_2
491     </param>
492   </host>
493
494 Alternatively, this parameter can be defined at the global level,
495 and then each interface should be pretended by the SNMP host name (the same as
496 in C<snmp-host> parameter) and slash sign (/):
497
498     <param name="RFC2863_IF_MIB::tokenset-members">
499      clusters: RTR01/Ethernet0_0, RTR01/FastEthernet2_1;
500     </param>
501
502
503 =item * C<RFC2863_IF_MIB::copy-params>
504
505 Optional comma-separated list of parameter names that would be copied
506 to the output Torrus configuration at interface level.
507 For each parameter I<param>, the value for a particular interface I<intf>
508 will be taken from parameter C<RFC2863_IF_MIB::I<param>::I<intf>> in
509 the discovery configuration file. Example:
510
511   <host>
512     <param name="snmp-host" value="192.168.49.131"/>
513     <param name="RFC2863_IF_MIB::copy-params" value="intf-error-threshold"/>
514     <param name="RFC2863_IF_MIB::intf-error-threshold::10_1" value="300"/>
515     <param name="RFC2863_IF_MIB::intf-error-threshold::2_1" value="900"/>
516   </host>
517
518 =item * C<RFC2863_IF_MIB::ifindex-map-hint>
519
520 Optional. For a device that doesn't have a corresponding vendor-specific
521 discovery module, this parameter would advice C<devdiscover> how to build
522 C<ifTable> index mapping. By default, the interfaces are mapped by
523 C<ifDescr> variables. For many vendors, this would not give reliable
524 mapping. Valid values are: C<ifName>, C<ifPhysAddress>, and C<ifIndex>.
525 The first two suggest the mapping by corresponding SNMP variables, and
526 the third one should be used for devices with fixed C<ifIndex> layout: in
527 this case, the C<ifIndex> values are recorded as they are at the moment of
528 discovery. This option is ignored if the device is supported by a vendor
529 specific discovery module.
530
531 =item * C<RFC2863_IF_MIB::subtree-name-hint>
532
533 Optional. By default, per-interface subtrees are named after the values of
534 C<ifDescr> SNMP variables. If this option is set to C<ifName>, this
535 SNMP variable would be used for subtree naming. This option is ignored if
536 the device is supported by a vendor specific discovery module.
537
538 =item * C<RFC2863_IF_MIB::nodeid-hint>
539
540 Optional. By default, per-interface I<nodeid> is derived from
541 C<RFC2863_IF_MIB::ifindex-map-hint>. This parameter can change the
542 reference table for nodeid. Valid values are:
543 C<ifDescr>, C<ifName>, C<ifAlias>, C<ifIndex>.
544
545
546 =item * C<RFC2863_IF_MIB::noout>
547
548 If set to C<yes>, all the interface statistics are skipped from
549 the XML configuration output. Still the interface table is examined and
550 the results may be used by other discovery modules.
551
552 =item * C<RFC2863_IF_MIB::bandwidth-usage>
553
554 If set to C<yes>, the bandwidth usage percentage will be shown for those
555 interfaces where two parameters are defined (in megabits per second):
556 C<bandwidth-limit-in> and C<bandwidth-limit-out>. These interface
557 parameters may be set by C<RFC2863_IF_MIB::bandwidth-limits> discovery
558 parameter, or by selectors with the action C<Parameters>, or by
559 setting C<RFC2863_IF_MIB::copy-params>.
560
561 =item * C<RFC2863_IF_MIB::bandwidth-limits>
562
563 Defines the values (in megabits per second) for C<bandwidth-limit-in> and
564 C<bandwidth-limit-out> interface parameters. Semicolon-separated list
565 of (I<Inteface name>:I<Input limit>:I<Output limit>) values, for example:
566
567   <host>
568     <param name="snmp-host" value="10.1.1.5"/>
569     <param name="symbolic-name" value="bsr2k.example.net"/>
570     <param name="output-file" value="bsr2k.example.net.xml"/>
571     <param name="RFC2863_IF_MIB::bandwidth-usage" value="yes" />
572     <param name="RFC2863_IF_MIB::bandwidth-limits">
573       ethernet0_0:10:10; ethernet0_1:20:20;
574     </param>
575   </host>
576
577
578 =item * C<RFC2863_IF_MIB::traffic-summaries>,
579 C<RFC2863_IF_MIB::traffic-XXX-path>, C<RFC2863_IF_MIB::traffic-XXX-comment>,
580 C<RFC2863_IF_MIB::traffic-XXX-interfaces>
581
582 Defines traffic summary graphs. A summary graph presents a sum of
583 traffic from several interfaces. The interfaces can belong to different
584 hosts, but then these hosts should have the same C<output-file> parameter
585 value. C<RFC2863_IF_MIB::traffic-summaries> defines a list of summary names,
586 C<RFC2863_IF_MIB::traffic-XXX-path> specifies the full path in the
587 datasource tree to display the graph, optional
588 C<RFC2863_IF_MIB::traffic-XXX-comment> defines a descriptive comment
589 for the graph, and C<RFC2863_IF_MIB::traffic-XXX-interfaces> lists the
590 interfaces that comprise this sum. The interfaces can be defined at the host
591 level in the form C<name, name, ...> or at the global level in the form
592 C<host/intf, host/intf, ...>. Example:
593
594   <param name="RFC2863_IF_MIB::traffic-summaries" value="sum1" />
595   <param name="RFC2863_IF_MIB::traffic-sum1-path" value="/Summary/Sum1" />
596   <param name="RFC2863_IF_MIB::traffic-sum1-comment" value="Test summary" />
597
598   <host>
599     <param name="snmp-host" value="router1.network.net"/>
600     <param name="RFC2863_IF_MIB::traffic-sum1-interfaces" 
601              value="GigabitEthernet0_2" />
602     <param name="output-file" value="TEST/core.xml"/>
603   </host>
604
605   <host>
606     <param name="snmp-host" value="router2.network.net"/>
607     <param name="RFC2863_IF_MIB::traffic-sum1-interfaces" 
608              value="GigabitEthernet1_0" />
609     <param name="output-file" value="TEST/core.xml"/>
610   </host>
611
612
613 =back
614
615 =head3 Other generic MIB parameters
616
617 =over 4
618
619 =item * C<RFC2790_HOST_RESOURCES::sysperf-subtree-name>
620
621 Defines the child subtree name within host-level subtree where system CPU
622 and memory statistics are located. Default: C<System_Performance>.
623
624 =item * C<RFC2670_DOCS_IF::upstreams-only>
625
626 If set to C<yes>, only the DOCSIS upstream statistics are enabled, and
627 downstream and MAC layer stats are skipped.
628
629 =back
630
631 =head3 Vendor parameters
632
633 =over 4
634
635 =item * C<Arbor_E::disable-bundle-offer>,
636     C<Arbor_E::disable-bundle-offer-deny>,
637     C<Arbor_E::disable-bundle-offer-pktsize>,
638     C<Arbor_E::disable-bundle-offer-rate>,
639     C<Arbor_E::disable-bundle-offer-subcount>, C<Arbor_E::disable-flowdev>,
640     C<Arbor_E::enable-bundle-name-rrd>,
641     C<Arbor_E::disable-e30-buffers>, C<Arbor_E::disable-e30-bundle>,
642     C<Arbor_E::disable-e30-cpu>,
643     C<Arbor_E::disable-e30-fwdTable>,
644     C<Arbor_E::disable-e30-fwdTable-login>,
645     C<Arbor_E::disable-e30-hdd>, C<Arbor_E::enable-e30-hdd-errors>,
646     C<Arbor_E::disable-e30-hdd-logs>, C<Arbor_E::disable-e30-l2tp>,
647     C<Arbor_E::disable-e30-mem>, C<Arbor_E::enable-e30-mempool>,
648     C<Arbor_E::disable-e30-bundle>, C<Arbor_E::disable-e30-bundle-deny>, 
649     C<Arbor_E::disable-e30-bundle-rate>, C<Arbor_E::disable-e30-slowpath>
650
651 When set to C<yes>, the corresponding statistics are included or excluded from
652 the graphs.
653
654 =item * C<Arbor_E::enable-e30-bundle-name-rrd>
655
656 When set to C<yes>, the data will be written to filenames based on the name
657 bundle instead of by the ID of the bundle.
658
659 =item * C<Apple_AE::disable-clients-stats>
660
661 When set to C<yes>, wireless client machines are not tracked.
662
663 =item * C<CiscoGeneric::disable-cpu-stats>
664
665 When set to C<yes>, Cisco CPU usage statistics are excluded from discovery.
666
667 =item * C<CiscoGeneric::disable-memory-pools>
668
669 When set to C<yes>, Cisco memory pool usage statistics are excluded from
670 discovery. For Cisco series 7500, see the note in the
671 I<Torrus Vendor Support List>.
672
673 =item * C<CiscoGeneric::disable-sensors>
674
675 When set to C<yes>, Cisco temperature sensors are excluded from discovery.
676
677 =item * C<CiscoGeneric::use-fahrenheit>
678
679 When set to C<yes>, Cisco temperature sensors are recorded and displayed
680 in degrees Fahrenheit.
681
682 =item * C<CiscoGeneric::file-per-sensor>
683
684 When set to C<yes>, Cisco temperature sensor values are stored in
685 a separate RRD file per sensor ID. This is useful for modular big routers
686 like Cisco GSR.
687
688 =item * C<CiscoGeneric::disable-psupplies>
689
690 if set to C<yes>, Cisco power supply statistics are not collected.
691
692 =item * C<CiscoGeneric::power-monitor>
693
694 Name of the power supply monitor for Cisco devices.
695
696 =item * C<CiscoIOS::enable-membuf-stats>
697
698 When set to C<yes>, Cisco memory buffer statistics are included to the 
699 discovery. Many IOS releases report faulty information, thus these
700 stats are disabled by default.
701
702 =item * C<CiscoIOS::disable-ipsec-stats>
703
704 When set to C<yes>, IPSec statistics are excluded from discovery.
705
706 =item * C<CiscoIOS::disable-bgp-stats>
707
708 If set to C<yes>, BGP statistics are not included.
709
710 =item * C<CiscoIOS::enable-vlan-interfaces>
711
712 When set to C<yes>, the interfaces VlanXXX are added to statistics.
713 By default they are not included, because some hardware platforms give
714 irrelevant counter statistics.
715
716 =item * C<CiscoIOS::enable-unrouted-vlan-interfaces>
717
718 When set to C<yes>, the interfaces "unrouted Vlan XXX" are added to statistics.
719 By default they are not included, because some hardware platforms provide
720 no statistics for such interfaces.
721
722
723 =item * C<CiscoCatOS::suppress-noname-ports>
724
725 When set to C<yes>, only those Catalyst ports are included in configuration
726 which have a port name (set up by C<set port name> command).
727
728 =item * C<CiscoIOS_MacAccounting::bgponly>
729
730 When set to C<yes>, Cisco MAC accounting statistics will be enabled for
731 those MACs which correspond to BGP peers only.
732
733 =item * C<bgp-as-description-NNNN>
734
735 Specifies a description for an autonomous system number. Currently it's used
736 with Cisco MAC accounting and Cisco BGP statistics only.
737
738 =item * C<peer-ipaddr-description-AAA_AAA_AAA_AAA>
739
740 Specifies a description for a peer by its IP address. Dots in IP address should
741 be replaced with underscores. Currently it's used with Cisco
742 MAC accounting and Cisco BGP statistics only.
743
744 =item * C<CiscoIOS_MacAccounting::tokenset-members>
745
746 Works the same way as C<RFC2863_IF_MIB::tokenset-members> and assigns MAC
747 accounting peers to tokensets.
748
749 =item * C<CiscoIOS::disable-car-stats>
750
751 When set to C<yes>, the Committed Access Rate statistics are disabled
752 from discovery.
753
754 =item * C<CiscoIOS::disable-vpdn-stats>
755
756 When set to C<yes>, the VPDN (Virtual Private Dial-up Network) statistics
757 are disabled from discovery.
758
759 =item * C<CiscoIOS::short-device-comment>
760
761 If set to C<yes>, the Hw Serial and Revision strings are not shown in
762 device comment.
763
764 =item * C<CiscoSCE::disable-disk>, C<CiscoSCE::disable-gc>,
765     C<CiscoSCE::disable-qos>, C<CiscoSCE::disable-rdr>,
766     C<CiscoSCE::disable-subs>, C<CiscoSCE::disable-tp>
767
768 If set to C<yes>, the corresponding statistics are excluded from Cisco SCE
769 graphs.
770
771 =item * C<FTOS::disable-cpu>, C<FTOS::disable-power>,
772     C<FTOS::disable-temperature>
773
774 When set to C<yes>, disables the corresponding statistics category.
775
776 =item * C<FTOS::use-fahrenheit>, C<FTOS::file-per-sensor>
777
778 When set to C<yes>, enables the user of fahrenheit temperature, or writes
779 multiple rrd files.
780
781 =item * C<JunOS::disable-cos>, C<JunOS::disable-cos-red>,
782     C<JunOS::disable-cos-tail>, C<JunOS::disable-firewall>,
783     C<JunOS::disable-operating>, C<JunOS::disable-rpf>
784
785 When set to C<yes>, disables the corresponding statistics category for JunOS
786 devices.
787
788 =item * C<Liebert::disable-temperature>, C<Liebert::disable-humidity>,
789     C<Liebert::disable-state>, C<Liebert::disable-stats>
790
791 When set to C<yes>, disable the corresponding statistics category for Liebert
792 devices.
793
794 =item * C<Liebert::use-fahrenheit>
795
796 When set to C<yes>, the temperature readings will be in fahrenheit.
797
798
799 =item * C<NetBotz::temp-max>, C<NetBotz::humi-max>, C<NetBotz::dew-max>
800
801 Set a numeric value for the maximum temperature, humidity, or dew point
802 on NetBotz sensor graphs. The maximum is displayed with a dark red line.
803
804 =item * C<Paradyne::slot-name>
805
806 Mandatory for Paradyne DSLAM devices. It should uniquely identify
807 the slot within the device. Any sequence of word characters is allowed.
808
809 =back
810
811 See also: I<Torrus Vendor Support List> for the list of supported MIBs and
812 vendors.
813
814 =head2 Object selectors
815
816 Selectors are a common mechanism for applying customizations to
817 some discovery objects. For example, you may want to apply a monitor
818 to byte counters of interfaces that have a special word in the description.
819 Or apply Holt-Winters prediction to a certain subset of interfaces.
820
821 Selectors are defined in a DDX file as regular parameters.
822 The parameter C<selectors> defines a list of selector names.
823 Each selector is identifed by its name and type. The type of selector
824 defines which objects will be searched: IF-MIB interfaces, or Cisco
825 temperature sensors, or something else. The parameters are described
826 below.
827
828 =over 4
829
830 =item * C<selectors>
831
832 Comma-separated list of selector names. Further below we use C<S> as
833 selector name, C<A> as attribute name, and C<T> as action name.
834
835 =item * C<S-selector-type>
836
837 Type of objects to be selected. Supported values are: C<RFC2863_IF_MIB>,
838 C<CiscoCPU>, C<CiscoSensor>.
839
840 =item * C<S-selector-expr>
841
842 An RPN (reverse Polish notation) expression that defines the
843 object attributes to be checked and relation between them. Attribute names
844 should be specified in curly braces ({}). The rest of the syntax is described
845 in I<RPN expressions in Torrus> guide. The attribute names are specific to the
846 selector type and are described below.
847
848 =item * C<S-A>
849
850 For a given selector name C<S> and attribute name C<A>,
851 this parameter defines the attribute value that should be compared
852 to the object's properties. In most cases it defines a regular
853 expression that should match the value of a corresponding object's
854 property.
855
856 =item * C<S-selector-actions>
857
858 For a given selector name C<S>, this parameter defines a comma-separated
859 list of actions to be applied for objects where C<S-selector-expr> returns
860 true. The action names are specific to the selector type and are
861 described below.
862
863 =item * C<S-T-arg>
864
865 For a given selector C<S> and action C<T>, this parameter defines
866 an argument that should be passed to the action. Each action
867 defines its own meaning of the argument.
868
869 =back
870
871
872
873 =head3 RFC2863_IF_MIB selector
874
875 This type of selector selects the network interfaces on a SNMP device.
876 The following attribute names are supported:
877
878 =over 4
879
880 =item * C<ifSubtreeName>, C<ifSubtreeName1>, ...
881
882 Interface-level subtree name as you see it in the discovery results.
883 You can compose a complex expression of subtree matches, by
884 createing attributes with different numbers at the end.
885
886 =item * C<ifComment>
887
888 Comment string that is defined in C<comment> parameter. It is
889 usually derived from an interface description.
890
891 =item * C<ifType>
892
893 Numeric IANA interface type, as returned by C<ifType> SNMP variable.
894
895 =back
896
897 C<ifType> is compared numerically.
898 C<ifSubtreeName> and C<ifComment> are regular expressions.
899 C<ifSubtreeName> accepts multiple expressions separated by space,
900 and the selector matches if any of these expressions matches the subtree name.
901
902
903
904 The following actions are supported:
905
906 =over 4
907
908 =item * C<InBytesMonitor>, C<OutBytesMonitor>
909
910 The argument defines the monitor name to be applied to the input
911 or output bytes counter.
912
913 =item * C<InDiscardsMonitor>, C<OutDiscardsMonitor>,
914 C<InErrorsMonitor>, C<OutErrorsMonitor>
915
916 The argument defines the monitor name to be applied to discard and error 
917 counters that are discovered for a given interface.
918
919 =item * C<NotifyPolicy>
920
921 The argument defines the value for C<notify-policy> parameter. See the manual
922 for F<action_notify> for more details.
923
924 =item * C<HoltWinters>
925
926 No argument needed. This action enables Holt-Winters prediction
927 for given interface's counters.
928
929 =item * C<NoPacketCounters>, C<NoDiscardCounters>, C<NoErrorCounters>
930
931 No argument needed. The action disables the packet, discard or error counters
932 for a given interface to be collected.
933
934 =item * C<TokensetMember>
935
936 The argument is a comma-separated list of tokenset names where C<InOutBbs>
937 graphs would be added. This action complements
938 C<RFC2863_IF_MIB::tokenset-members>.
939
940 =item * C<Parameters>
941
942 The argument defines additional configuration parameters to be
943 placed at the interface level. The value should be one
944 or several C<param=value> pairs separated by semicolon (;).
945 Parameters defined in C<RFC2863_IF_MIB::copy-params> may override
946 the ones defined in this action.
947
948 =item * C<InBytesParameters>, C<OutBytesParameters>
949
950 Analagous to C<Parameters>, but the parameters are applied to InBytes and
951 OutBytes leaves of the selected interface.
952
953 =item * C<DocsisUpSNRMonitor>
954
955 For a DOCSIS CMTS, this action assigns a new  monitor to the upstream
956 Signal/Noise ratio gauge, instead of the default monitor.
957
958 =item * C<DocsisUpSNRTokenset>
959
960 For a DOCSIS CMTS, this action adds the Signal/Noise ratio graph to a
961 specified tokenset.
962
963 =item * C<DocsisUpFECCorMonitor>
964
965 For a DOCSIS CMTS, this action assigns a monitor to the C<Correctable>
966 counter of the upstream FEC statistics.
967
968 =item * C<DocsisUpFECUncorMonitor>
969
970 For a DOCSIS CMTS, this action assigns a monitor to the C<Uncorrectable>
971 counter of the upstream FEC statistics.
972
973 =item * C<DocsisDownUtilMonitor>
974
975 For a DOCSIS CMTS, this action assigns a monitor to the downstream
976 C<UsedBytes> counter.
977
978 =item * C<DocsisMacModemsMonitor>
979
980 For Cisco uBR, this action assigns a monitor to the C<Modems_Registered> gauge
981 in the MAC layer stats.
982
983 =item * C<DocsisUpUtilMonitor>, C<DocsisUpSlotsMonitor>
984
985 For Cisco uBR, this action assigns a monitor to upstream utilization and
986 free contention timeslots gauges correspondingly.
987
988 =back
989
990
991 =head3 CiscoCPU selector
992
993 A selector of this type selects CPU statistics Cisco router or
994 switch.
995
996 The attributes supported are: C<CPUName> and C<CPUDescr>, and their
997 values are regular expressions that should match the CPU name or description,
998 as discovered by C<devdiscover>.
999
1000 The action supported is C<TokensetMember>, and its argument specifies
1001 the tokenset where to place the CPU statistics graph.
1002
1003
1004 =head3 CiscoSensor selector
1005
1006 A selector of this type selects temperature sensors on a Cisco router or
1007 switch.
1008
1009 The only attribute supported is C<SensorDescr>, and its value is a regular
1010 expression that should match the sensor description, as discovered
1011 by C<devdiscover>.
1012
1013 Actions supported: C<Monitor>, C<TokensetMember>.
1014
1015
1016 =head3 ALU_SAP selector
1017
1018 This selector type is designed for SAP entries in Alcatel-Lucent ESS and SR
1019 routers.
1020
1021 Attributes supported: C<sapDescr> (regexp), C<custDescr> (regexp),
1022 C<sapName> (exact match), C<sapPort> (exact match).
1023
1024 Actions supported: C<RemoveSAP> (excludes a selected SAP from the datasources).
1025
1026
1027
1028 =head3 Examples
1029
1030 The following example applies a monitor called C<temp60degrees> to all
1031 inlet sensors on a Cisco device:
1032
1033   <host>
1034     <param name="snmp-host" value="router1"/>
1035     <param name="output-file" value="router1.xml"/>
1036     <param name="selectors" value="inlet"/>
1037     <param name="inlet-selector-type" value="CiscoSensor"/>
1038     <param name="inlet-selector-expr"  value="{SensorDescr}"/>
1039     <param name="inlet-SensorDescr" value="Inlet"/>
1040     <param name="inlet-selector-actions"  value="Monitor"/>
1041     <param name="inlet-Monitor-arg" value="temp60degrees"/>
1042   </host>
1043
1044 The following example enables Holt-Winters prediction and specifies some
1045 parameters to all FastEthernet interfaces which have the string "SRV-ID"
1046 in their descriptions:
1047
1048   <host>
1049     <param name="snmp-host" value="router2"/>
1050
1051     <param name="selectors"  value="FastEthHW"/>
1052     <param name="FastEthHW-selector-type"     value="RFC2863_IF_MIB"/>
1053
1054     <param name="FastEthHW-selector-expr"    
1055            value="{ifSubtreeName},{ifComment},AND"/>
1056     <param name="FastEthHW-ifSubtreeName"     value="^FastEthernet"/>
1057     <param name="FastEthHW-ifComment"         value="SRV-ID"/>
1058
1059     <param name="FastEthHW-selector-actions"
1060            value="HoltWinters,Parameters"/>
1061
1062     <param name="FastEthHW-Parameters-arg"
1063        value="rrd-create-hw-alpha=0.2; rrd-create-hw-beta=0.01"/>
1064   </host>
1065
1066 The following example sets up the monitors defined in
1067 F<examples/docsis-monitors.xml>:
1068
1069     <param name="selectors" value="docs"/>
1070     <param name="docs-selector-type" value="RFC2863_IF_MIB"/>
1071     <param name="docs-selector-expr"  value="{ifSubtreeName}"/>
1072     <param name="docs-ifSubtreeName"  value="^Cable"/>
1073     <param name="docs-selector-actions"> 
1074           DocsisUpSNRMonitor,
1075           DocsisUpFECCorMonitor,
1076           DocsisUpFECUncorMonitor,
1077           DocsisDownUtilMonitor,
1078           DocsisMacModemsMonitor,
1079           DocsisUpUtilMonitor,
1080           DocsisUpSlotsMonitor,
1081           InErrorsMonitor,
1082           OutErrorsMonitor
1083     </param>
1084     <param name="docs-DocsisUpSNRMonitor-arg" 
1085            value="docsis-snr-1,docsis-snr-2,docsis-snr-3"/>
1086
1087     <param name="docs-DocsisUpFECCorMonitor-arg" 
1088            value="docsis-feccor-1,docsis-feccor-2"/>
1089
1090     <param name="docs-DocsisUpFECUncorMonitor-arg" 
1091            value="docsis-fecuncor-1,docsis-fecuncor-2,docsis-fecuncor-3"/>
1092
1093     <param name="docs-DocsisDownUtilMonitor-arg" 
1094            value="docsis-downutl-1,docsis-downutl-2,docsis-downutl-3"/>
1095
1096     <param name="docs-DocsisMacModemsMonitor-arg" 
1097            value="docsis-modems-1,docsis-modems-2"/>
1098
1099     <param name="docs-DocsisUpUtilMonitor-arg" 
1100            value="docsis-uputil-1,docsis-uputil-2,docsis-uputil-3"/>
1101     
1102     <param name="docs-DocsisUpSlotsMonitor-arg" 
1103            value="docsis-upslots-1,docsis-upslots-2,docsis-upslots-3"/>
1104     
1105     <param name="docs-InErrorsMonitor-arg" 
1106            value="docs-inerrors-1,docs-inerrors-2"/>
1107
1108     <param name="docs-OutErrorsMonitor-arg" 
1109            value="docs-outerrors-1,docs-outerrors-2"/>
1110
1111
1112
1113 =head1 Author
1114
1115 Copyright (c) 2002-2005 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>