• RRFW SNMP Discovery User Guide
• Introduction
• genddx: Discovery instructions generator
• devdiscover: SNMP discovery tool
• Discovery Instructions File
• XML elements
• Common parameters
• Parameters for RFC2863_IF_MIB
• Other generic MIB parameters
• Vendor parameters
• Author

RRFW SNMP Discovery User Guide

Introduction

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

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

genddx: Discovery instructions generator

  Usage: $RRFW_HOME/bin/genddx options...
  Options:
     --host=hostname         router hostname
     --hostfile=filename     space-separated router hostnames file
     --out=outfile           output file.         [discover-routers.xml]
     --discout=filename      discovery output file
            [/usr/local/rrfw-0.1/share/rrfw/xmlconfig/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   [/var/snmpcollector]
     --holtwinters           Enable Holt-Winters analysis

This utility generates devdiscover instructions XML file based on commandline options and a plain list of SNMP agents' hostnames. Hostnames are apecified 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. 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 RRFW configuration output file with absolute path pointing to xmlconfig subdirectory of the installation, with the file name <routers.xml>. You most probably will change this by using the --discout option.

Examples:

  ./bin/genddx --out=share/rrfw/discovery/ch-langenthal.ddx \
    --discout=share/rrfw/xmlconfig/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

  ./bin/devdiscover --in=share/rrfw/discovery/ch-langenthal.ddx

devdiscover: SNMP discovery tool

  Usage: $RRFW_HOME/bin/devdiscover --in=filename.xml options...
  Options:
   --in=infile             discovery instructions XML file
   --mkdir                 create data-dir directories
   --limit=regexp          limit the discovery by output files
   --verbose               print extra information
   --debug                 print debugging information

This utility performs the SNMP discovery of devices listed in the input XML file. The output XML file is the RRFW datasources configuration. Output file name is taken from output-file parameter in the instructions XML file.

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 RRFW 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 RRFW 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 $RRFW_HOME/share/rrfw/devdiscover-siteconfig.pl file. Default values for those variables reside in $RRFW_HOME/share/rrfw/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

  $RRFW::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 RRFW User Guide.

Discovery Instructions File

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

A typical place to store the discovery XML is share/rrfw/discovery/ directory under the RRFW installation path.

Example:

    <?xml version="1.0" encoding="UTF8"?>
    <snmp-discovery>
      <file-info>
        <format-version>
    1.0
        </format-version>
      </file-info>
      <creator-info>
    RRFW version 0.1.4d
    This file was generated by command:
    /usr/local/rrfw-0.1/bin/genddx \
     --discout=share/rrfw/xmlconfig/myrouters.xml \
     --community=blahblah  --host=10.0.0.1  --host=10.0.1.1
    On Tue Dec  2 17:43:30 2003
      </creator-info>
      <param name="data-dir" value="/var/snmpcollector"/>
      <param name="domain-name" value=""/>
      <param name="host-subtree" value="/Routers"/>
      <param name="output-file" value="share/rrfw/xmlconfig/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"/>
      </host>
      <host>
        <param name="snmp-host" value="10.0.1.1"/>
        <param name="symbolic-name" value="10.0.1.1"/>
      </host>
    </snmp-discovery>

XML elements

• snmp-discovery
  
Mandatory. The top-level element.
• file-info
  
Mandatory. It must contain the element format-version.
• format-version
  
Mandatory. It must contain a format version currently supported by devdiscover. Currently supported version is 1.0.
• creator-info
  
Optional. May contain the information about the file creator: a human author name, or a program.
• param
  
Some parameters are mandatory. This element defines a global or host-specific parameter. Mandatory attribute name identifies the parameter, and the value is taken eother from value attribute, or from the textual content of the element.

param element should be the child element of snmp-discovery for global parameters or host for host-level parameters. Host-level parameters override the values of global parameters.

These parameters are for devdiscover only. They are not RRFW configuration parameters, although some of them are directly copied into the generated configuration file.

• host
  
Mandatory. Defines a host to run SNMP discovery.

Common parameters

• collector-period, collector-timeoffset, collector-dispersed-timeoffset, collector-timeoffset-min, collector-timeoffset-max, collector-timeoffset-step
  
Optional. When defined, these parameters override those from snmp-defaults template in snmp-defs.xml.
• output-file
  
Mandatory. Specifies the output filename for generated RRFW configuration. In the parameter value, $XMLCONFIG is replaced with the default RRFW XML configuration directory name.
• output-bundle
  
Optional. Specifies a comma-separated list of XML file names for bundle output. Each bundle file will contain <include> statement for each corresponding output-file. In the parameter value, $XMLCONFIG is replaced with the default RRFW XML configuration directory name.
• snmp-port, snmp-community, snmp-version, snmp-timeout, snmp-retries, snmp-host
  
Mandatory. These parameters define the SNMP agent properties and are copied one-to-one to the output configuration.
• domain-name
  
Optional. Defines a DNS domain name to be appended to snmp-host.
• data-dir
  
Mandatory. Defines the directory path where RRD files for this host are stored. In case if hashed directories are enabled, data-dir specifies the base path under which the hashed subdirectories are created.
• symbolic-name
  
Optional. Determines the host-specific subtree name. If not specified, the subtree is named by system-id, or by snmp-host if system ID is not defined.
• system-id
  
Optional. If defined, it overrides the default value of system ID, which is equal to the value of snmp-host.
• snmp-oids-per-pdu
  
Optional. When defined, these parameters overwrites the value from the template and vendor-specific discovery modules.
• snmp-check-sysuptime
  
Optional. Default: yes. Devdiscover sets this parameter to no when it finds SNMPv2-MIB::sysUpTime variable unavailable in the device.
• host-subtree
  
Optional. Defines the datasourse tree path under which the host-specific subtree is created.
• rrd-hwpredict
  
Optional. Valid values: yes, no. Determines if Holt-Winters forecasting should be enabled for the given host.
• disable-devtypes
  
Optional. Comma-separated list of discovery device types that need to be excluded from discovery process. For example, ATMEL appliances conflict with Empire SystemEdge MIBs, and you need to disable EmpireSystemedge module in order to run the discovery on those appliances.
• only-devtypes
  
Optional comma-separated list of device types. If defined, only the specified types will be used for device probing.
• host-aliases
  
Optional comma-separated list of alias paths for a given host. Aliases must be unique for each host.
• custom-host-templates
  
Optional comma-separated list of template names that will be applied to the resulting XML configuration at the host level.
• host-copy-params
  
Optional comma-separated list of parameter names that should be copied from the discovery configuration file to the generated RRFW configuration at the host level.

Parameters for RFC2863_IF_MIB

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

• RFC2863_IF_MIB::suppress-hc-counters
  
Some agents do not implement 64-bit counters correctly. When this parameter is set to yes, 64-bit interface counters are not used for the host. For Cisco IOS devices, the CiscoIOS discovery module tries to detect such situation automatically.
• RFC2863_IF_MIB::subtree-name
  
Defines the child subtree name within host-level subtree where interface counters are located. Default: Interface_Counters.
• RFC2863_IF_MIB::exclude-interfaces
  
Comma-separated list of interface names which should be excluded from configuration. Spaces are allowed between the names and commas. The names should be the ones that are used for interface subtrees.
• RFC2863_IF_MIB::tokenset-members
  
This parameter defines which interfaces' InOut_bps leaves to add to which tokensets. The value is a semicolon-separated (;) list of entries of form tset:interface,interface, where tset is a name of the tokenset, and the interface is the subtree name of the corresponding interface. The token sets must be defined elsewhere in RRFW configuration. Example:

  <host>
    <param name="snmp-host" value="192.168.49.131"/>
    <param name="RFC2863_IF_MIB::tokenset-members">
     clusters: 10_1, 10_2;
     uplinks: 1_1, 1_2
    </param>
  </host>

• RFC2863_IF_MIB::errors-monitor
  
When set to yes, all interface error and discard counters are assigned to a monitor called RFC2863_IF_MIB-errors. It is up to you to define the monitor somewhere in the configuration.
• RFC2863_IF_MIB::copy-params
  
Optional comma-separated list of parameter names that would be copied to the output RRFW configuration at interface level. For each parameter param, the value for a particular interface intf will be taken from parameter RFC2863_IF_MIB::param::intf in the discovery configuration file. Example:

  <host>
    <param name="snmp-host" value="192.168.49.131"/>
    <param name="RFC2863_IF_MIB::copy-params" value="intf-error-threshold"/>
    <param name="RFC2863_IF_MIB::intf-error-threshold::10_1" value="300"/>
    <param name="RFC2863_IF_MIB::intf-error-threshold::2_1" value="900"/>
  </host>

Other generic MIB parameters

• RFC2790_HOST_RESOURCES::sysperf-subtree-name
  
Defines the child subtree name within host-level subtree where system CPU and memory statistics are located. Default: System_Performance.

Vendor parameters

• CiscoGeneric::disable-cpu-stats
  
When set to yes, Cisco CPU usage statistics are excluded from discovery.
• CiscoGeneric::disable-memory-pools
  
When set to yes, Cisco memory pool usage statistics are excluded from discovery.
• CiscoGeneric::disable-sensors
  
When set to yes, Cisco temperature sensors are excluded from discovery.
• CiscoGeneric::use-fahrenheit
  
When set to yes, Cisco temperature sensors are recorded and displayed in degrees Fahrenheit.
• CiscoGeneric::file-per-sensor
  
When set to yes, Cisco temperature sensor values are stored in a separate RRD file per sensor ID. This is useful for modular big routers like Cisco GSR.
• CiscoIOS::disable-membuf-stats
  
When set to yes, Cisco memory buffer statistics are excluded from discovery.
• CiscoIOS::disable-ipsec-stats
  
When set to yes, IPSec statistics are excluded from discovery.
• CiscoCatOS::suppress-noname-ports
  
When set to yes, only those Catalyst ports are included in configuration which have a port name (set up by set port name command).

Author

Copyright (c) 2002-2003 Stanislav Sinyagin <ssinyagin@yahoo.com>