Torrus SNMP Device Discovery Developer's Guide

devdiscover overview

devdiscover is an extensible, module based, SNMP device discovery utility. It is intended to automatically generate Torrus configuration files, based on SNMP discovery results and templates.

See Torrus Command Reference for command usage and functionality overview.

In general, devdiscover consists of the following files and functional parts:

Discovery Module Internals

Discovery modules are Perl packages with few required components. Before creating your own modules, please read and follow Torrus Programming Style Guide.

Upon initialization, Torrus::DevDiscover loads the modules listed in @Torrus::DevDiscover::loadModules array. This array is pre-populated by standard module names in devdiscover-config.pl. You can add new module names by pushing them onto this array in your local devdiscover-siteconfig.pl.

Module Registration

Each discovery module should register itself in DevDiscover registry. Normally there's only one registry entry per discovery module, though it's not a limitation. The registry entry is identified by a registry name, which normally repeats the module name.

Example:

    $Torrus::DevDiscover::registry{'RFC2790_HOST_RESOURCES'} = {
        'sequence'     => 100,
        'checkdevtype' => \&checkdevtype,
        'discover'     => \&discover,
        'buildConfig'  => \&buildConfig
        };

Each registry entry must contain 4 fields:

OID Definitions

OID definitions are designed to provide symbolic names to OIDs in numerical notation. Normally the symbolic names repeat the names from corresponding MIBs.

The definitions must be defined in an oiddef hash defined in the package namespace. Then they are automatically imported by DevDiscover initialization procerure.

Example:

    our %oiddef =
        (
         'hrSystemUptime'               => '1.3.6.1.2.1.25.1.1.0',
         'hrSystemNumUsers'             => '1.3.6.1.2.1.25.1.5.0',
         'hrSystemProcesses'            => '1.3.6.1.2.1.25.1.6.0',
         'hrSystemMaxProcesses'         => '1.3.6.1.2.1.25.1.7.0',
         'hrMemorySize'                 => '1.3.6.1.2.1.25.2.2.0',
         'hrStorageTable'               => '1.3.6.1.2.1.25.2.3.1',
         'hrStorageIndex'               => '1.3.6.1.2.1.25.2.3.1.1',
         'hrStorageType'                => '1.3.6.1.2.1.25.2.3.1.2',
         'hrStorageDescr'               => '1.3.6.1.2.1.25.2.3.1.3',
         'hrStorageAllocationUnits'     => '1.3.6.1.2.1.25.2.3.1.4',
         'hrStorageSize'                => '1.3.6.1.2.1.25.2.3.1.5',
         'hrStorageUsed'                => '1.3.6.1.2.1.25.2.3.1.6',
         'hrStorageAllocationFailures'  => '1.3.6.1.2.1.25.2.3.1.7'
         );

Template References

Normally a discovery module would refer to configuration templates defined in template definition files. In order to provide an extra level of flexibility, these templates should be defined in devdiscover-config.pl or in devdiscover-siteconfig.pl.

It is recommended that the template references in the discovery modules follow the naming standard: module::template-name.

ConfigBuilder's addTemplateApplication() method looks up every template name in the global hash %Torrus::ConfigBuilder::templateRegistry and figures out the source XML file and the actual template name.

Example:

    $Torrus::ConfigBuilder::templateRegistry{
        'RFC2790_HOST_RESOURCES::hr-system-uptime'} = {
            'name'   => 'mytest-hr-system-uptime',
            'source' => 'mytest.templates.xml'
            };

Interface filtering

Usually not all interfaces from ifTable need to be monitored. For example, Loopback and Null0 interfaces on Cisco routers.

Torrus::DevDiscover::RFC2863_IF_MIB provides the functionality to automatically filter out the interfaces, based on filter definitions. Filter definitions are registered by calling the subroutine Torrus::DevDiscover::RFC2863_IF_MIB::addInterfaceFilter ($devdetails, $interfaceFilter). The second argument is a reference to a hash of the following structure:

Keys are symbolic names that mean nothing and need only to be unique. Values are hash references with the following entries: ifType specifies the IANA interface type, and optional ifDescr specifies a regular expression to match against interface description.

The filters are usually registered within checkdevtype subroutine of the vendor module, after the device type is identified. See CiscoIOS.pm and CiscoCatOS.pm as examples.

Authors

Shawn Ferry: initial draft.

Stanislav Sinyagin: revision and detailed content.