SIAM plugin for Torrus

Installation

Follow the Torrus installation guide for the main software installation.

Install the SIAM Perl module from CPAN:

  perl -MCPAN -e 'install SIAM'

Unpack the plugin distribution package in some directory:

  gzip -dc tp-siam-1.X.tar.gz | tar xvf -

Then run the Torrus plugin installation utility, pointing to the unpacked plugin directory:

  torrus install_plugin tp-siam-1.X

Overview

Service Inventory Abstraction Model (SIAM) is a Perl library available at CPAN. It is designed to be an abstraction interface between enterprise-specific inventory database and various programs, such as Torrus. SIAM is supposed to be used with an enterprise-specific driver which maps the inventory data into SIAM objects and attributes.

The tp-siam plugin consists of command-line utilities and a DevDiscover module.

siam_genddx utility

The siam_genddx command-line utility performs the following steps:

Command-line arguments:

  torrus siam_genddx [options...]
    Options:
     --server=HOSTNAME       Torrus server to match in SIAM
     --pddx=PATH             Path to store DDX files
     --pbundles=PATH         Path to store bundles XML
     --pnodes=PATH           Path to store per-node XML
     --prrd=PATH             RRD data storage path
     --verbose               print extra information
     --debug                 print debugging information

By default, the local server's hostname is matched against the torrus.server attribute. The resulting DDX files are stored in the default discovery directory. The DDX files are named as "siam-TREE.ddx" for each given tree name supplied by SIAM parameters. The DDX files would store the generated bundle files in xmlconfig/bundles/, and device-specific XML files in xmlconfig/nodes/ subdirectories of the standard XML configuration location.

The file siam-config.pl defines all default values and DDX parameters. These values can be modified in your site-specific siam-siteconfig.pl.

siam_genxml utility

siam_genxml reads the SIAM data, and takes all SIAM::Service objects having the siam.svc.type attribute set to TrafficAggregate. For those services matching the torrus.server attribute, it creates Torrus configuration XML files that present total aggregate traffic from several IF-MIB interfaces.

Command-line arguments:

  torrus siam_genxml [options...]
  Options:
    --server=HOSTNAME       Torrus server to match in SIAM
    --paggr=PATH            Path to store aggregates XML
    --verbose               print extra information
    --debug                 print debugging information

The traffic aggregate XML files are stored by default in xmlconfig/bundles/.

Torrus::DevDiscover::SIAMDD module

The discovery module Torrus::DevDiscover::SIAMDD tries to match the IF-MIB interface names in SIAM against those on the network devices. The resulting configuration contains nodeid values imported from SIAM and assigned to corresponding device interfaces. As a result, external programs can fetch Torrus data by using the enterprise-specific service identifiers.

siam_rrd_fetch utility

siam_rrd_fetch retrieves a list of devices and their corresponding service data elements, and then retrieves the aggregated data from RRD files. The aggregated data is returned to SIAM via a condition "torrus.fetch.data" on the SIAM::ServiceDataElement objects.

Usage:


  torrus siam_rrdfetch [options...]
  Options:
    --server=HOSTNAME       Torrus server to match in SIAM
    --verbose               print extra information
    --debug                 print debugging information

SIAM Attributes

SIAM::Device object attributes used by the plugin:

SIAM::ServiceUnit object attributes used by the discovery module:

SIAM::Service attributes used for traffic aggregate graphs:

SIAM::ServiceUnit attributes used in traffic aggregates:

SIAM::ServiceDataElement attributes used by siam_rrdfetch:

SIAM::ServiceDataElement computable 'torrus.fetch.latest_available' is used to determine the UNIX timestamp of the latest data already fetched in a previous run.

SIAM conditions

Conditions are used for sending the SNMP discovery status events back into the SIAM driver. They can be used for diagnostics and reporting purposes.

torrus.imported

This condition is applied to SIAM::Device and SIAM::ServiceUnit objects. The value is a status code and a status message separated by semicolon (;). Non-zero status code corresponds to success, and no status message is given. Zero status code indicates an error, and the status message explains the details.

torrus.warning

The condition is applied to SIAM::ServiceUnit in case of non-critical problems. The supplied value is a message string with the warning message.

torrus.fetch.data

This condition is set by siam_rrdfetch on SIAM::ServiceDataElement objects. It contains a hashref with the retrieved data: timestamp->counter->CF->value

Author

Copyright (c) 2011 Stanislav Sinyagin <ssinyagin@yahoo.com>