torrus/doc/nodeid_usage.pod.in

   1 #  Copyright (C) 2010  Stanislav Sinyagin
   2 #
   3 #  This program is free software; you can redistribute it and/or modify
   4 #  it under the terms of the GNU General Public License as published by
   5 #  the Free Software Foundation; either version 2 of the License, or
   6 #  (at your option) any later version.
   7 #
   8 #  This program is distributed in the hope that it will be useful,
   9 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 #  GNU General Public License for more details.
  12 #
  13 #  You should have received a copy of the GNU General Public License
  14 #  along with this program; if not, write to the Free Software
  15 #  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
  16
  17 # $Id: nodeid_usage.pod.in,v 1.1 2010-12-27 00:04:35 ivan Exp $
  18 # Stanislav Sinyagin <ssinyagin@yahoo.com>
  19 #
  20 #
  21
  22 =head1 Torrus/OSS integration: NodeID usage guidelines
  23
  24 =head2 Introduction
  25
  26 Most parts of Torrus software mentioned in this document were developed under
  27 sponsoring by the following companies:
  28
  29 =over 4
  30
  31 =item * nexellent ag, Switzerland (www.nexellent.ch)
  32
  33 NodeID concept and base implementation, host-based authentication.
  34
  35 =item * M-net Telekommunikations GmbH, Germany (www.m-net.de)
  36
  37 M-net plugin.
  38
  39 =item * Fibre Noire Internet Inc, Canada (www.fibrenoire.ca)
  40
  41 Extensions in M-Net plugin for NodeID manipulation.
  42
  43 =back
  44
  45
  46
  47 This document explains the new concept of NodeID and ways of utilizing
  48 it for better integration of Torrus into an OSS environment.
  49
  50
  51 =head2 NodeID concept
  52
  53 Torrus 1.0.9 introduces a new parameter for datasource tree elements:
  54 C<nodeid>. This parameter is not inherited from parent subtrees to child
  55 subtrees or leaves. Also the XML configuration compiler verifies uniqueness
  56 of its values across the whole tree.
  57
  58 The purpose of C<nodeid> is to provide persistent identifiers to the tree
  59 elements. Unlike the token numbers, these identifiers are not changing between
  60 re-compilations of the tree. Also unlike the path string, C<nodeid> would
  61 stay the same if a network device changes its place in the tree topology.
  62
  63 By default, C<nodeid> value is composed of SNMP host name and device
  64 component name, such as IF-MIB interface. It can also be easily adapted to
  65 contain external identifiers, such as Asset ID or Service ID from some
  66 external inventory database.
  67
  68 Once C<nodeid> values are put into the XML configuration (usually
  69 SNMP discovery engine does it) and compiled into the configuration database,
  70 they can be used for accessing the Torrus graphs from external systems.
  71
  72 The command-line utility C<torrus nodeid> helps searching through existing
  73 NodeID values, and also renders the graphs on request.
  74
  75 Another quick way to find the NodeID value is to navigate to the desired
  76 graph page and check the I<Bookmark> shortcut at the bottom of the page.
  77 For the nodes where C<nodeid> is defined, the bookmark will use it instead of
  78 the path in the datasource tree.
  79
  80
  81
  82 =head2 Host-based authentication
  83
  84 Many Torrus deployments have user authentication enabled. This makes it
  85 complicated for other OSS systems to retrieve graphs from the Torrus rendering
  86 engine.
  87
  88 Torrus 1.0.9 introduces host-based authentication: a special user
  89 is created for requestor's IP address. The requestor specifies its unique
  90 password in the URL as C<hostauth> parameter. Also the Torrus WebUI does not
  91 send the session cookie back to the requestor.
  92
  93 This new feature makes it easy to display Torrus graphs inside user
  94 self-service portals without giving direct access to the Torrus server.
  95
  96 For example, the following command adds the host 10.0.0.5 with password
  97 "654321" to the I<admin> group:
  98
  99   torrus acl --addhost=10.0.0.5 --hostpassword=654321 --addtogroup=admin
 100
 101 Then the following command executed from 10.0.0.5 would retrieve an
 102 InOut_bps graph for the last 24 hours for a given interface on I<rtr01> router:
 103
 104   wget -O graph.png \
 105     'http://torrus/main?nodeid=if//rtr01//GigabitEthernet0/1//inoutbit&view=last24h&hostauth=654321'
 106
 107
 108 =head2 M-net plugin
 109
 110 Details of M-net plugin are explained in the plugin documentation.
 111 The plugin interprets description strings on device network interfaces:
 112 it catches all key-value pairs of format I<key1=val1;key2=val2;...> and
 113 performs various actions on them.
 114
 115 Now assume there's an external inventory system, and each network interface is
 116 assigned a unique Asset ID. Our natural wish would be to use these asset IDs
 117 in NodeID strings, instead of hostnames and interfaces. This way we are
 118 secured against hardware changes and upgrades (assuming that Asset ID stays
 119 unchanged).
 120
 121 In order to take advantage of M-Net plugin, the Asset ID values should be
 122 configured in all interface descriptions, like follows:
 123
 124   interface GigabitEthernet0/1
 125     description bw=200M; assetid=VPNLINK00055; ct=BC
 126
 127 In the example above, the interface description tells that this is a 200Mbps
 128 link, connection type is Business Customer, and the unique link identifier is
 129 I<VPNLINK00055>.  The format allows inserting extra spaces for better
 130 readability.
 131
 132 In the corresponding Device Discovery XML (DDX) file, the following
 133 parameters would be set:
 134
 135   <host>
 136     <param name="snmp-host" value="rtr01.example.com"/>
 137     <param name="M_net::manage" value="yes"/>
 138     <param name="M_net::nodeid-prefix-key" value="assetid"/>
 139   </host>
 140
 141 As a result, after the SNMP discovery and XML compiler finish their work,
 142 we get a number of NodeID values associated with this customer connection:
 143
 144       assetid//VPNLINK00055
 145       assetid//VPNLINK00055//inbytes
 146       assetid//VPNLINK00055//indrops
 147       assetid//VPNLINK00055//inerr
 148       assetid//VPNLINK00055//inoutbit
 149       assetid//VPNLINK00055//inpackets
 150       assetid//VPNLINK00055//outbytes
 151       assetid//VPNLINK00055//outdrops
 152       assetid//VPNLINK00055//outerr
 153       assetid//VPNLINK00055//outpackets
 154
 155 The first NodeID refers to the interface-level subtree in Torrus
 156 configuration, and all other values refer to the corresponding graphs
 157 for this interface.
 158
 159 So, now the customer self-service portal would retrieve the input/output
 160 summary graph with the following URL (wget woulld be certainly replaced by a
 161 corresponding command in PHP or other Web programming language):
 162
 163   wget -O graph.png \
 164     'http://torrus/main?nodeid=assetid//VPNLINK00055//inoutbit&view=last24h&hostauth=654321'
 165
 166 Of course, a number of additional view definitions could be created, in order
 167 to create graphs of needed size and time span. Also, for example, a calendar
 168 month's graph could be generated by specifying the followiong
 169 parameters in the URL: C<NOW> or C<Gend> pointing to the beginning of
 170 next month, and optionally C<Gstart> indicating the start of the time period.
 171
 172
 173 =head2 Setting the host identifier
 174
 175 Alternatively to the technique explained above, the local OSS environment
 176 could require some custom identifiers assigned to the network devices.
 177 For example, CA Spectrum software uses its internal Model Handles to refer to
 178 devices.
 179
 180 The discovery parameter C<nodeid-device> sets the string that would be used
 181 in the host part of NodeID values:
 182
 183   <host>
 184     <param name="snmp-host" value="rtr02.example.com"/>
 185     <param name="nodeid-device" value="0xC0FFEE"/>
 186   </host>
 187
 188 The resulting NodeID values would be based on "0xC0FFEE" string instead of
 189 "rtr02.example.com":
 190
 191   if//0xC0FFEE//GigabitEthernet0/1//inoutbit
 192
 193
 194 =head2 Future development
 195
 196 The NodeID is a relatively new concept in Torrus, and there will be other
 197 ways of specifying and using it in the course of Torrus development.
 198
 199 One of the directions for future enhancement is a look-up of NodeID values
 200 in some external database before or during SNMP discovery.
 201
 202 The usage of NodeID is not limited to IF-MIB interfaces. Some Torrus
 203 templates already assign NodeID values to, for example, environment sensors
 204 and DOCSIS statistics.
 205
 206
 207
 208 =head1 Author
 209
 210 Copyright (c) 2010 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>