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.

Author
    Copyright (c) 2010-2011 Stanislav Sinyagin <ssinyagin@k-open.com>

