Torrus/OSS integration: NodeID usage guidelines

Introduction

Most parts of Torrus software mentioned in this document were developed under sponsoring by the following companies:

nexellent ag, Switzerland (www.nexellent.ch)

NodeID concept and base implementation, host-based authentication.
M-net Telekommunikations GmbH, Germany (www.m-net.de)

M-net plugin.
Fibre Noire Internet Inc, Canada (www.fibrenoire.ca)

Extensions in M-Net plugin for NodeID manipulation.
upc cablecom GmbH (www.upc-cablecom.ch)

SIAM library and its binding with Torrus and Extopus.

This document explains the new concept of NodeID and ways of utilizing it for better integration of Torrus into an OSS environment.

NodeID concept

Torrus 1.0.9 introduces a new parameter for datasource tree elements: nodeid. This parameter is not inherited from parent subtrees to child subtrees or leaves. Also the XML configuration compiler verifies uniqueness of its values across the whole tree.

The purpose of nodeid is to provide persistent identifiers to the tree elements. Unlike the token numbers, these identifiers are not changing between re-compilations of the tree. Also unlike the path string, nodeid would stay the same if a network device changes its place in the tree topology.

By default, nodeid value is composed of SNMP host name and device component name, such as IF-MIB interface. It can also be easily adapted to contain external identifiers, such as Asset ID or Service ID from some external inventory database.

Once nodeid values are put into the XML configuration (usually SNMP discovery engine does it) and compiled into the configuration database, they can be used for accessing the Torrus graphs from external systems.

The command-line utility torrus nodeid helps searching through existing NodeID values, and also renders the graphs on request.

Another quick way to find the NodeID value is to navigate to the desired graph page and check the Bookmark shortcut at the bottom of the page. For the nodes where nodeid is defined, the bookmark will use it instead of the path in the datasource tree.

Host-based authentication

Many Torrus deployments have user authentication enabled. This makes it complicated for other OSS systems to retrieve graphs from the Torrus rendering engine.

Torrus 1.0.9 introduces host-based authentication: a special user is created for requestor's IP address. The requestor specifies its unique password in the URL as hostauth parameter. Also the Torrus WebUI does not send the session cookie back to the requestor.

This new feature makes it easy to display Torrus graphs inside user self-service portals without giving direct access to the Torrus server.

For example, the following command adds the host 10.0.0.5 with password "654321" to the admin group:

  torrus acl --addhost=10.0.0.5 --hostpassword=654321 --addtogroup=admin

Then the following command executed from 10.0.0.5 would retrieve an InOut_bps graph for the last 24 hours for a given interface on rtr01 router:

  wget -O graph.png \
    'http://torrus/main?nodeid=if//rtr01//GigabitEthernet0/1//inoutbit&view=last24h&hostauth=654321'

M-net plugin

Details of M-net plugin are explained in the plugin documentation. The plugin interprets description strings on device network interfaces: it catches all key-value pairs of format key1=val1;key2=val2;... and performs various actions on them.

Now assume there's an external inventory system, and each network interface is assigned a unique Asset ID. Our natural wish would be to use these asset IDs in NodeID strings, instead of hostnames and interfaces. This way we are secured against hardware changes and upgrades (assuming that Asset ID stays unchanged).

In order to take advantage of M-Net plugin, the Asset ID values should be configured in all interface descriptions, like follows:

  interface GigabitEthernet0/1
    description bw=200M; assetid=VPNLINK00055; ct=BC

In the example above, the interface description tells that this is a 200Mbps link, connection type is Business Customer, and the unique link identifier is VPNLINK00055. The format allows inserting extra spaces for better readability.

In the corresponding Device Discovery XML (DDX) file, the following parameters would be set:

  <host>
    <param name="snmp-host" value="rtr01.example.com"/>
    <param name="M_net::manage" value="yes"/>
    <param name="M_net::nodeid-prefix-key" value="assetid"/>
  </host>

As a result, after the SNMP discovery and XML compiler finish their work, we get a number of NodeID values associated with this customer connection:

      assetid//VPNLINK00055
      assetid//VPNLINK00055//inbytes
      assetid//VPNLINK00055//indrops
      assetid//VPNLINK00055//inerr
      assetid//VPNLINK00055//inoutbit
      assetid//VPNLINK00055//inpackets
      assetid//VPNLINK00055//outbytes
      assetid//VPNLINK00055//outdrops
      assetid//VPNLINK00055//outerr
      assetid//VPNLINK00055//outpackets

The first NodeID refers to the interface-level subtree in Torrus configuration, and all other values refer to the corresponding graphs for this interface.

So, now the customer self-service portal would retrieve the input/output summary graph with the following URL (wget woulld be certainly replaced by a corresponding command in PHP or other Web programming language):

  wget -O graph.png \
    'http://torrus/main?nodeid=assetid//VPNLINK00055//inoutbit&view=last24h&hostauth=654321'

Of course, a number of additional view definitions could be created, in order to create graphs of needed size and time span. Also, for example, a calendar month's graph could be generated by specifying the followiong parameters in the URL: NOW or Gend pointing to the beginning of next month, and optionally Gstart indicating the start of the time period.

Setting the host identifier

Alternatively to the technique explained above, the local OSS environment could require some custom identifiers assigned to the network devices. For example, CA Spectrum software uses its internal Model Handles to refer to devices.

The discovery parameter nodeid-device sets the string that would be used in the host part of NodeID values:

  <host>
    <param name="snmp-host" value="rtr02.example.com"/>
    <param name="nodeid-device" value="0xC0FFEE"/>
  </host>

The resulting NodeID values would be based on "0xC0FFEE" string instead of "rtr02.example.com":

  if//0xC0FFEE//GigabitEthernet0/1//inoutbit

Service-centric display: SIAM+Extopus

Service Inventory Abstraction Model (SIAM) is a new 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.

Torrus 1.0.10 introduces a new plugin module: tp-siam. It consists of a command-line utility which generates DDX files from SIAM data, and a DevDiscover module which 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 those values would be typically based on service identifiers in the inventory database. Thus the external programs can fetch Torrus data by using the enterprise-specific service identifiers.

Extopus (www.extopus.org) is a Tobi Oetiker's new software product, a universal front-end for various open-source systems. It's designed to aggregate and display data from various sources, such as network monitoring systems. Extopus contains plugin modules for SIAM and Torrus, and allows for service-centric display (opposed to Torrus' device-centric presentation).

SIAM represents the inventory data in a service-centric fashion: customer contracts consist of services, and each service may contain multiple physical objects, such as device interfaces. Also the user privilege system in SIAM allows assigning visible contracts to the front-end users. Extopus allows the end-user to log in and navigate through its service hierarchy, and display the traffic graphs and summaries which are pulled and proxied from a Torrus server.