plugins/cbqos/tp-cisco-cbqos.pod

   1 #  Copyright (C) 2002  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., 675 Mass Ave, Cambridge, MA 02139, USA.
  16
  17 # Stanislav Sinyagin <ssinyagin@yahoo.com>
  18 #
  19 #
  20
  21 =head1 Cisco Class-based QoS discovery and collection plugin
  22
  23 Status: Released; Last modified: 03-MAY-2004
  24
  25 =head2 Introduction
  26
  27 DiffServ-based quality of service is being deployed in many networks
  28 these days, and the choice of management systems able to monitor QoS
  29 parameters is too narrow.
  30
  31 Cisco IOS provides QoS statistics in its CISCO-CLASS-BASED-QOS-MIB.
  32 This MIB is far too complex for a regular SNMP collector.
  33
  34 The C<cbqos> Torrus plugin provides a complete solution for automated
  35 SNMP discovery and collection for QoS objects on Cisco routers.
  36 It is the first open source solution of this kind.
  37
  38 Other existing tools for QoS monitoring are:
  39
  40 =over 4
  41
  42 =item * C<genRtrConfig> by Francois Mikus (http://www.acktomic.com).
  43
  44 This tool is an add-on to Cricket (http://cricket.sourceforge.net).
  45 It provides discovery and statistics for non-hierarchical classmaps counters:
  46 pre-policy, post-policy, and drop counters.
  47
  48 =back
  49
  50
  51 =head2 Installation
  52
  53 Follow the Torrus installation guide for the main software installation.
  54
  55 Unpack the plugin distribution package in some directory:
  56
  57   gzip -dc tp-cisco-cbqos-1.X.tar.gz | tar xvf -
  58
  59 Then run the Torrus plugin installation utility:
  60
  61   torrus install_plugin tp-cisco-cbqos-1.X
  62
  63 Restart all Torrus processes, including Apache HTTP daemon.
  64
  65
  66 =head2 Usage
  67
  68 Use your Torrus the usual way: C<devdiscover> will automatically find
  69 QoS objects on your routers, C<compilexml> will find the required
  70 templates, and C<collector> will initialize all required tables and
  71 will start collecting data.
  72
  73 B<Note:> QoS is a software feature, and there's no means to determine
  74 that the configuration has changed. You need to re-run C<devdiscover>
  75 and C<compilexml> whenever your QoS configuration changes.
  76 As usual, the collector will automatically detect the router reload
  77 or Torrus configuration change, and re-initialize its tables.
  78
  79 =head2 Tunable parameters
  80
  81 The following parameters may be specified in C<devdiscover> input XML:
  82
  83 =over 4
  84
  85 =item * C<CiscoIOS_cbQoS::red-dscp-values>
  86
  87 Optional. Comma-separated list of DSCP values to be used for WRED
  88 statistics. Symbolic names like C<AF31> or C<EF> are recognized.
  89 When specified, it overrides the default list defined in
  90 C<@Torrus::DevDiscover::CiscoIOS_cbQoS::RedDscpValues> in F<cbqos-config.pl>
  91 or in F<devdiscover-siteconfig.pl>.
  92
  93 =item * C<CiscoIOS_cbQoS::classmaps-only>
  94
  95 Optional. When set to C<yes>, only classmap statistics are set for collection.
  96 Suppressed are statistics for match statements, queueing, RED, shaping,
  97 and policying. This significantly reduces the size of datasource tree,
  98 amount of SNMP queries, and collector execution time.
  99
 100 =item * C<CiscoIOS_cbQoS::suppress-match-statements>
 101
 102 Optional. When set to C<yes>, disables the match statement statistics.
 103 These statistics usually don't bring much of additional information.
 104 Besides, in some IOS versions they are almost always not updated (known
 105 for: 12.2(15)T7, ...).
 106
 107 =item * C<CiscoIOS_cbQoS::suppress-dropnobuf>
 108
 109 Optional. When set to C<yes>, disables classmap Dropped No Buffer statistics.
 110
 111 =back
 112
 113 =head2 Implementation details
 114
 115 CISCO-CLASS-BASED-QOS-MIB uses complex indexing for statistics objects:
 116
 117 =over 4
 118
 119 =item 1
 120
 121 C<cbQosPolicyIndex> in C<cbQosServicePolicyTable> is found by matching
 122 6 values: C<cbQosIfType>, C<cbQosPolicyDirection>, C<cbQosIfIndex>,
 123 C<cbQosFrDLCI>, C<cbQosAtmVPI>, C<cbQosAtmVCI>
 124
 125 =item 2
 126
 127 Use C<cbQosPolicyIndex> to access the C<cbQosObjectsTable>, and find the
 128 C<cbQosObjectsIndex> and C<cbQosConfigIndex> assigned to the QoS feature.
 129
 130 =item 3
 131
 132 Use C<cbQosConfigIndex> to access configuration tables
 133 (C<cbQosxxxCfgTable>) for information about the feature.
 134
 135 =item 4
 136
 137 Use C<cbQosPolicyIndex> and C<cbQosObjectsIndex> to access QoS statistics
 138 tables (C<cbQosxxxStatsTable>) for information about the QoS feature.
 139
 140 =back
 141
 142 The plugin introduces a special Torrus collector type, "cisco-cbqos".
 143
 144 Each Torrus datasource is identified by Service Policy, QoS Feature, and
 145 associated SNMP objects type.
 146
 147 The following parameters identify the Service Policy:
 148
 149  cbqos-direction =>
 150    "input"
 151    "output"
 152
 153  cbqos-interface-name (mapping to IF-MIB interface index)
 154
 155  cbqos-interface-type =>
 156    "mainInterface"
 157    "subInterface"
 158    "frDLCI" =>
 159      cbqos-fr-dlci
 160    "atmPVC" =>
 161      cbqos-atm-vpi
 162      cbqos-atm-vci
 163
 164
 165 The following parameters identify the QoS Feature:
 166
 167  cbqos-object-type =>
 168    "policymap"
 169    "classmap" =>
 170      cbqos-class-map-name
 171    "matchStatement" =>
 172      cbqos-match-statement-name
 173    "queueing" =>
 174      cbqos-queueing-bandwidth
 175    "randomDetect"
 176    "trafficShaping" =>
 177      cbqos-shaping-rate
 178    "police" =>
 179      cbqos-police-rate
 180
 181 SNMP objects are defined in regular Torrus XML templates. Collector
 182 substitutes C<POL> and C<OBJ> strings in C<snmp-object> parameter with
 183 the current values of policy and object index correspondingly.
 184
 185 Development of this plugin was sponsored by Cablecom GmbH.
 186
 187 =head1 Author
 188
 189 Copyright (c) 2004 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>