X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=torrus%2Fdoc%2Fnodeid_usage.pod.in;fp=torrus%2Fdoc%2Fnodeid_usage.pod.in;h=7f33a37049de89555619f297b42914672feacd7e;hp=0000000000000000000000000000000000000000;hb=74e058c8a010ef6feb539248a550d0bb169c1e94;hpb=35359a73152b3d7a9ad5e3d37faf81f6fedb76e8 diff --git a/torrus/doc/nodeid_usage.pod.in b/torrus/doc/nodeid_usage.pod.in new file mode 100644 index 000000000..7f33a3704 --- /dev/null +++ b/torrus/doc/nodeid_usage.pod.in @@ -0,0 +1,210 @@ +# Copyright (C) 2010 Stanislav Sinyagin +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. + +# $Id: nodeid_usage.pod.in,v 1.1 2010-12-27 00:04:35 ivan Exp $ +# Stanislav Sinyagin +# +# + +=head1 Torrus/OSS integration: NodeID usage guidelines + +=head2 Introduction + +Most parts of Torrus software mentioned in this document were developed under +sponsoring by the following companies: + +=over 4 + +=item * nexellent ag, Switzerland (www.nexellent.ch) + +NodeID concept and base implementation, host-based authentication. + +=item * M-net Telekommunikations GmbH, Germany (www.m-net.de) + +M-net plugin. + +=item * Fibre Noire Internet Inc, Canada (www.fibrenoire.ca) + +Extensions in M-Net plugin for NodeID manipulation. + +=back + + + +This document explains the new concept of NodeID and ways of utilizing +it for better integration of Torrus into an OSS environment. + + +=head2 NodeID concept + +Torrus 1.0.9 introduces a new parameter for datasource tree elements: +C. 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 C 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, C would +stay the same if a network device changes its place in the tree topology. + +By default, C 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 C 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 C 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 I shortcut at the bottom of the page. +For the nodes where C is defined, the bookmark will use it instead of +the path in the datasource tree. + + + +=head2 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 C 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 I 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 I router: + + wget -O graph.png \ + 'http://torrus/main?nodeid=if//rtr01//GigabitEthernet0/1//inoutbit&view=last24h&hostauth=654321' + + +=head2 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 I 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 +I. The format allows inserting extra spaces for better +readability. + +In the corresponding Device Discovery XML (DDX) file, the following +parameters would be set: + + + + + + + +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: C or C pointing to the beginning of +next month, and optionally C indicating the start of the time period. + + +=head2 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 C sets the string that would be used +in the host part of NodeID values: + + + + + + +The resulting NodeID values would be based on "0xC0FFEE" string instead of +"rtr02.example.com": + + if//0xC0FFEE//GigabitEthernet0/1//inoutbit + + +=head2 Future development + +The NodeID is a relatively new concept in Torrus, and there will be other +ways of specifying and using it in the course of Torrus development. + +One of the directions for future enhancement is a look-up of NodeID values +in some external database before or during SNMP discovery. + +The usage of NodeID is not limited to IF-MIB interfaces. Some Torrus +templates already assign NodeID values to, for example, environment sensors +and DOCSIS statistics. + + + +=head1 Author + +Copyright (c) 2010 Stanislav Sinyagin Essinyagin@yahoo.comE