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>