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

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:

Retrieve the SNMP devices matching the torrus.server attribute;
Create discovery instruction (DDX) files for each Torrus tree as found in SIAM data.

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.object.complete
Only complete device objects are processed. The incomplete devices are ignored.
torrus.server
This attribute is matched when the SIAM command-line utility imports the devicesinto the DDX files.
torrus.tree
The Torrus tree name. It should match an existing tree name in Torrus configuration.
siam.device.name
Unique device name which is used for sustem-id parameter in Torrus.
siam.device.inventory_id
Unique device identifier that is used to retrieve the corresponding SIAM::Device object from SIAM.
snmp.managed
Must return a true value in order for the device to be included in further processing.
snmp.host, snmp-version, snmp-community, snmp-timeout, snmp-retries
Optional attributes that may override the default values.
torrus.subtree-path
Optional attribute, identifies the subtree name where the device node is placed.

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

siam.object.complete
Only complete service unit objects are processed. The incomplete ones are ignored.
siam.svcunit.type
Type of service unit. Supported value: IFMIB.Port
torrus.port.name, torrus.port.shortname
These attributes are matched against the IF-MIB interface names in order to find the corresponding ifIndex. This list can be modified in siam-siteconfig.pl.
torrus.port.nodeid
Unique value of nodeid which will be assigned to the matched interface.
torrus.port.bandwidth
Optional service bandwidth in bit per second. If defined, the corresponding bandwidth limit parameters are applied to the interface configuration.

SIAM::Service attributes used for traffic aggregate graphs:

siam.object.complete
Only complete service objects are processed. The incomplete ones are ignored.
siam.svc.type
By default, only service object with siam.svc.type set to TrafficAggregate are treated as traffic aggregation services. Other values can be configured in siam-siteconfig.pl.
torrus.aggregate.name
Human-readable name for the aggregate. It is used as a subtree name in Torrus tree.
torrus.aggregate.nodeid
The value of this parameter is used as the base for NodeID for the aggregate leafs.
torrus.aggregate.description
[Optional] human-readable description of the aggregate.

SIAM::ServiceUnit attributes used in traffic aggregates:

siam.svcunit.type
Only IFMIB.Port is supported.
torrus.port.nodeid
Port NodeID values are used to compose the aggregate graphs.
siam.svcunit.name
The value is used to build the legend text for the aggregate.

SIAM::ServiceDataElement attributes used by siam_rrdfetch:

siam.svcdata.driver
Only data elements with the driver set to 'Torrus.TimeSeries' are processed.
torrus.nodeid
NodeID prefix -- all leaf nodes which match this prefix are collected for this data element object.
torrus.fetch.max_intervals
(Optional) maximum number of aggregation intervals to retrieve. Default: 14.
torrus.fetch.aggr_interval
(Optional) aggregation interval. Default: 86400 (24 hours).

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