1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
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 <ssinyagin@yahoo.com>
#
#
=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<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 C<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, C<nodeid> would
stay the same if a network device changes its place in the tree topology.
By default, C<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 C<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 C<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 I<Bookmark> shortcut at the bottom of the page.
For the nodes where C<nodeid> 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<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 I<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 I<rtr01> 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<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
I<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: C<NOW> or C<Gend> pointing to the beginning of
next month, and optionally C<Gstart> 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<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
=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 E<lt>ssinyagin@yahoo.comE<gt>
|
