Torrus SNMP Discovery User Guide

Introduction

In many (but not only) cases Torrus is used for SNMP monitoring. It provides powerful tools which automate the process of devices' MIB discovery.

The discovery tools consist of two programs: torrus devdiscover performs the SNMP discovery, based on the discovery instructions XML file. The result of its work is a new Torrus datasource configuration file. Another utility, torrus genddx, is a program that generates the basic discovery instructions file based on a set of commandline options.

The device discovery XML, or as we call them DDX files, are usually resided in /usr/local/etc/torrus/conf/discovery/ directory. This is the default path to search for them when the absolute path is not given.

torrus genddx: Discovery instructions generator

  Usage: torrus genddx options...
  Options:
     --host=hostname         router hostname
     --hostfile=filename     space-separated router hostnames file
     --out=outfile           output file.         [routers.ddx]
     --discout=filename      discovery output file [routers.xml]
     --domain=domain         optional DNS domain name
     --version=v             SNMP version         [2c]
     --community=string      SNMP read community  [public]
     --port=number           SNMP port            [161]
     --retries=number        SNMP retries         [2]
     --timeout=number        SNMP timeout         [10]
     --subtree=string        Subtree name         [/Routers]
     --datadir=path          data-dir parameter [/srv/torrus/collector_rrd]
     --holtwinters           Enable Holt-Winters analysis

This utility generates devdiscover instructions XML file (DDX) based on commandline options and a plain list of SNMP agents' hostnames. Hostnames are specified with one or many --host=hostname options, or a plain text file with space-separated hostnames.

Each host may have a symbolic name. This symbolic name is used as the host-level subtree name. The symbolic name follows the hostname with a semicolon.

By default, the devices are placed into /Routers/ subtree hierarchy. You may change the subtree name with the --subtree option. Single slash as subtree name would cause host-level subtrees placed at the top of the datasources tree.

By default, genddx specifies the discovery output file as <routers.xml>, and it would be placed in site XML configuration directory. You most probably will change this by using the --discout option.

Examples:

  torrus genddx --out=ch-langenthal.ddx \
    --discout=ch-langenthal.xml \
    --host=192.168.34.35:Langenthal_PE1 \
    --host=192.168.34.36:Langenthal_PE2 \
    --host=192.168.34.37:Langenthal_CE_Stadtverwaltung \
    --community=blahBlah \
    --subtree=/MPLS/CH/Bern/Langenthal

  torrus devdiscover --in=ch-langenthal.ddx

Note: genddx is designed as a one-time utility. You may run it to create a typical discovery file with basic set of options. Then the discovery configuration XML would be the primary source of information, and it should be maintained by manual editing, or by some other automated means. Alternatively you may use ttproclist utility and generate highly customized discovery instruction files based on static templates and lists of SNMP nodes. See torrus_ttproclist(1) manpage for more details and examples.

torrus devdiscover: SNMP discovery tool

  Usage: torrus devdiscover --in=filename.ddx options... [ddx files]
  Options:
   --in=filename.ddx       discovery instructions XML file(s)
   --mkdir                 create data-dir directories
   --limit=regexp          limit the discovery by output files
   --forcebundle           always write the bundle file
   --fallback=integer      maximum age of XML file to fall back to
   --threads=integer       number of parallel discovery threads
   --verbose               print extra information
   --debug                 print debugging information
   --snmpdebug             print SNMP protocol details

This utility performs the SNMP discovery of devices listed in the input DDX file. The output XML file is the Torrus datasources configuration. Output file name is taken from output-file parameter in the DDX. If the output file is not an absolute path, the file is placed in the site XML configuration directory (/usr/local/etc/torrus/xmlconfig).

devdiscover is accompanied by a number of MIB- or vendor-specific modules, each responsible for finding specific SNMP variables in the SNMP device, and for generating a piece of Torrus configuration XML file responsible for that specific MIB. The list of supported generic MIBs and vendors is constantly growing. It is quite easy to create new discovery modules, and the internals are documented in Torrus SNMP Device Discovery Developer's Guide.

The output file automatically includes all required prerequisite generic and vendor template definition files.

Behaviour of devdiscover is controlled by variables in /usr/local/etc/torrus/conf/devdiscover-siteconfig.pl file. Default values for those variables reside in /usr/local/torrus/conf_defaults/devdiscover-config.pl.

For large installations, it is recommended to place RRD files into a hashed directory structure. You can enable this feature by setting

  $Torrus::DevDiscover::hashDataDirEnabled = 1;

in your devdiscover-siteconfig.pl file. Then launching devdiscover with --mkdir option would automatically create the subdirectories inside data-dir.

The XML files produced by devdiscover may be automatically changed with some local site-specific scripts. See XUpdate usage example in Torrus User Guide.

DDX, the discovery instructions file

The input file for devdiscover is an XML file. Its DTD is available in Torrus distribution in snmp-discovery.dtd.

A typical place to store the discovery XML is /usr/local/etc/torrus/conf/discovery/.

Example:

    <?xml version="1.0" encoding="UTF-8"?>
    <snmp-discovery>
      <file-info>
        <format-version>
    1.0
        </format-version>
      </file-info>
      <creator-info>
       Manually edited by Vassisuali Poupkine
      </creator-info>
      <param name="data-dir" value="/srv/torrus/collector_rrd"/>
      <param name="domain-name" value=""/>
      <param name="host-subtree" value="/Routers"/>
      <param name="output-file" value="myrouters.xml"/>
      <param name="rrd-hwpredict" value="no"/>
      <param name="snmp-community" value="blahblah"/>
      <param name="snmp-port" value="161"/>
      <param name="snmp-retries" value="2"/>
      <param name="snmp-timeout" value="10"/>
      <param name="snmp-version" value="2c"/>

      <host>
        <param name="snmp-host" value="10.0.0.1"/>
        <param name="symbolic-name" value="10.0.0.1"/>

        <!-- Example of 15-second polling interval.
             15-second stats are stored for 10 days, and 5-minute
             aggregates are stored for 30 days.-->

        <param name="collector-period" value="15"/>
        <param name="collector-timeoffset" value="0"/>
        <param name="rrd-create-rra">
           RRA:AVERAGE:0:1:57600
           RRA:AVERAGE:0.25:20:8640      RRA:MAX:0.25:20:8640
        </param>
      </host>

      <host>
        <param name="snmp-host" value="10.0.1.1"/>
        <param name="symbolic-name" value="10.0.1.1"/>

        <!--
         Example of extended RRA definition.
         The RRD files are approximately 8 times bigger than standard.
         5-minute stats: 366 days
         60-minute max and average: 190 days
         daily max and average: 732 days
         In hourly aggregates, 20 minutes missing is allowed.
         In daily aggregates, 6 hours missing is allowed.
        -->
       <param name="rrd-create-rra">
         RRA:AVERAGE:0:1:105408
         RRA:AVERAGE:0.34:12:4560     RRA:MAX:0.34:12:4560
         RRA:AVERAGE:0.25:288:732    RRA:MAX:0.25:288:732
       </param>
      </host>
    </snmp-discovery>

XML elements

Common parameters

Parameters for RFC2863_IF_MIB

This discovery module is responsible for agent's interfaces table and interface counters. Recognized optional parameters are:

Other generic MIB parameters

Vendor parameters

See also: Torrus Vendor Support List for the list of supported MIBs and vendors.

Object selectors

Selectors are a common mechanism for applying customizations to some discovery objects. For example, you may want to apply a monitor to byte counters of interfaces that have a special word in the description. Or apply Holt-Winters prediction to a certain subset of interfaces.

Selectors are defined in a DDX file as regular parameters. The parameter selectors defines a list of selector names. Each selector is identifed by its name and type. The type of selector defines which objects will be searched: IF-MIB interfaces, or Cisco temperature sensors, or something else. The parameters are described below.

RFC2863_IF_MIB selector

This type of selector selects the network interfaces on a SNMP device. The following attribute names are supported:

ifType is compared numerically. ifSubtreeName and ifComment are regular expressions. ifSubtreeName accepts multiple expressions separated by space, and the selector matches if any of these expressions matches the subtree name.

The following actions are supported:

CiscoCPU selector

A selector of this type selects CPU statistics Cisco router or switch.

The attributes supported are: CPUName and CPUDescr, and their values are regular expressions that should match the CPU name or description, as discovered by devdiscover.

The action supported is TokensetMember, and its argument specifies the tokenset where to place the CPU statistics graph.

CiscoSensor selector

A selector of this type selects temperature sensors on a Cisco router or switch.

The only attribute supported is SensorDescr, and its value is a regular expression that should match the sensor description, as discovered by devdiscover.

Actions supported: Monitor, TokensetMember.

ALU_SAP selector

This selector type is designed for SAP entries in Alcatel-Lucent ESS and SR routers.

Attributes supported: sapDescr (regexp), custDescr (regexp), sapName (exact match), sapPort (exact match).

Actions supported: RemoveSAP (excludes a selected SAP from the datasources).

NetBotzSensor selector

A selector of this type selects sensors on a NetBotz environment monitoring appliances.

Attributes supported: SensorLabel, EnclosureLabel, EnclosureID. Arguments are matched as regular expressions.

Actions supported: Monitor, TokensetMember.

RFC2662_ADSL_LINE selector

This type of selector applies to ADSL line statistics.

Attributes supported: ifSubtreeName.

Actions supported: AtucSnrMonitor, AturSnrMonitor, AtucAtnMonitor, AturAtnMonitor, AtucAttRateMonitor, AturAttRateMonitor, AtucTxRateMonitor, AturTxRateMonitor, AtucLofsMonitor, AturLofsMonitor, AtucLossMonitor, AturLossMonitor, AtucLprsMonitor, AturLprsMonitor, AtucESsMonitor, AturESsMonitor, AtucInitsMonitor.

RFC4293_IP_MIB_v4 and RFC4293_IP_MIB_v6 selectors

These selectors apply to the IP-MIB statistics if they are present on the device and their discovery is activated by RFC4293_IP_MIB::ipv4-stats or RFC4293_IP_MIB::ipv6-stats parameters.

Attributes supported: ifSubtreeName.

Actions supported: InBytesMonitor, OutBytesMonitor, InBytesParameters, OutBytesParameters, TokensetMember

Examples

The following example applies a monitor called temp60degrees to all inlet sensors on a Cisco device:

  <host>
    <param name="snmp-host" value="router1"/>
    <param name="output-file" value="router1.xml"/>
    <param name="selectors" value="inlet"/>
    <param name="inlet-selector-type" value="CiscoSensor"/>
    <param name="inlet-selector-expr"  value="{SensorDescr}"/>
    <param name="inlet-SensorDescr" value="Inlet"/>
    <param name="inlet-selector-actions"  value="Monitor"/>
    <param name="inlet-Monitor-arg" value="temp60degrees"/>
  </host>

The following example enables Holt-Winters prediction and specifies some parameters to all FastEthernet interfaces which have the string "SRV-ID" in their descriptions:

  <host>
    <param name="snmp-host" value="router2"/>

    <param name="selectors"  value="FastEthHW"/>
    <param name="FastEthHW-selector-type"     value="RFC2863_IF_MIB"/>

    <param name="FastEthHW-selector-expr"    
           value="{ifSubtreeName},{ifComment},AND"/>
    <param name="FastEthHW-ifSubtreeName"     value="^FastEthernet"/>
    <param name="FastEthHW-ifComment"         value="SRV-ID"/>

    <param name="FastEthHW-selector-actions"
           value="HoltWinters,Parameters"/>

    <param name="FastEthHW-Parameters-arg"
       value="rrd-create-hw-alpha=0.2; rrd-create-hw-beta=0.01"/>
  </host>

The following example sets up the monitors defined in examples/docsis-monitors.xml:

    <param name="selectors" value="docs"/>
    <param name="docs-selector-type" value="RFC2863_IF_MIB"/>
    <param name="docs-selector-expr"  value="{ifSubtreeName}"/>
    <param name="docs-ifSubtreeName"  value="^Cable"/>
    <param name="docs-selector-actions"> 
          DocsisUpSNRMonitor,
          DocsisUpFECCorMonitor,
          DocsisUpFECUncorMonitor,
          DocsisDownUtilMonitor,
          DocsisMacModemsMonitor,
          DocsisUpUtilMonitor,
          DocsisUpSlotsMonitor,
          InErrorsMonitor,
          OutErrorsMonitor
    </param>
    <param name="docs-DocsisUpSNRMonitor-arg" 
           value="docsis-snr-1,docsis-snr-2,docsis-snr-3"/>

    <param name="docs-DocsisUpFECCorMonitor-arg" 
           value="docsis-feccor-1,docsis-feccor-2"/>

    <param name="docs-DocsisUpFECUncorMonitor-arg" 
           value="docsis-fecuncor-1,docsis-fecuncor-2,docsis-fecuncor-3"/>

    <param name="docs-DocsisDownUtilMonitor-arg" 
           value="docsis-downutl-1,docsis-downutl-2,docsis-downutl-3"/>

    <param name="docs-DocsisMacModemsMonitor-arg" 
           value="docsis-modems-1,docsis-modems-2"/>

    <param name="docs-DocsisUpUtilMonitor-arg" 
           value="docsis-uputil-1,docsis-uputil-2,docsis-uputil-3"/>
    
    <param name="docs-DocsisUpSlotsMonitor-arg" 
           value="docsis-upslots-1,docsis-upslots-2,docsis-upslots-3"/>
    
    <param name="docs-InErrorsMonitor-arg" 
           value="docs-inerrors-1,docs-inerrors-2"/>

    <param name="docs-OutErrorsMonitor-arg" 
           value="docs-outerrors-1,docs-outerrors-2"/>

This example excludes all non-Gigabit ports from discovery results:

  <host>
    <param name="snmp-host"                 value="router001"/>
    <param  name="output-file"              value="routers/router001.xml"/>
    <param name="selectors"                 value="NotGigE" />
    <param  name="NotGigE-selector-type"    value="RFC2863_IF_MIB"  />
    <param name="NotGigE-selector-expr"     value="{ifSubtreeName},NOT"  />
    <param  name="NotGigE-ifSubtreeName"    value="^Gigabit" />
    <param  name="NotGigE-selector-actions" value="RemoveInterface" />
  </host>

The following example sets the SNR monitoring on ADSL line statistics:

  <param name="selectors" value="AdslMon" />
  <param  name="AdslMon-selector-type"    value="RFC2662_ADSL_LINE"/>
  <param  name="AdslMon-selector-actions">
     AtucSnrMonitor,
     AturSnrMonitor
  </param>
  <param name="AdslMon-AtucSnrMonitor-arg" value="adsl-snr-6db"/>
  <param name="AdslMon-AturSnrMonitor-arg" value="adsl-snr-6db"/>

Author

Copyright (c) 2002-2011 Stanislav Sinyagin <ssinyagin@k-open.com>