torrus/doc/devdoc/devdiscover.pod

   1 #  devdiscover.pod - Guide to devdiscover
   2 #  Copyright (C) 2003 Shawn Ferry, Stanislav Sinyagin
   3 #
   4 #  This program is free software; you can redistribute it and/or modify
   5 #  it under the terms of the GNU General Public License as published by
   6 #  the Free Software Foundation; either version 2 of the License, or
   7 #  (at your option) any later version.
   8 #
   9 #  This program is distributed in the hope that it will be useful,
  10 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 #  GNU General Public License for more details.
  13 #
  14 #  You should have received a copy of the GNU General Public License
  15 #  along with this program; if not, write to the Free Software
  16 #  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
  17
  18 # $Id: devdiscover.pod,v 1.1 2010-12-27 00:04:36 ivan Exp $
  19 # Shawn Ferry <sferry at sevenspace dot com> <lalartu at obscure dot org>
  20 # Stanislav Sinyagin <ssinyagin@yahoo.com>
  21 #
  22
  23 =head1 Torrus SNMP Device Discovery Developer's Guide
  24
  25 =head2 C<devdiscover> overview
  26
  27 C<devdiscover> is an extensible, module based, SNMP device discovery
  28 utility. It is intended to automatically generate Torrus configuration
  29 files, based on SNMP discovery results and templates.
  30
  31 See I<Torrus Command Reference> for command usage and functionality overview.
  32
  33 In general, C<devdiscover> consists of the following files and functional
  34 parts:
  35
  36 =over 4
  37
  38 =item * C<bin/devdiscover.in>
  39
  40 This file is installed as C<bin/devdiscover> in Torrus installation directory,
  41 with certain variables substituted. The program provides all the commandline
  42 functionality and options processing. Once the CLI options are processed and
  43 verified, the control is passed to the C<Torrus::DevDiscover> object.
  44
  45 =item * C<Torrus::DevDiscover>
  46
  47 This Perl module is responsible for the SNMP discovery process organization:
  48
  49 =over 8
  50
  51 =item *
  52
  53 it registers the discovery modules;
  54
  55 =item *
  56
  57 establishes an SNMP session to the target host;
  58
  59 =item *
  60
  61 initiates a new C<Torrus::DevDiscover::DevDetails> object for the target host;
  62
  63 =item *
  64
  65 stores the connection-specific parameters to the device object;
  66
  67 =item *
  68
  69 for each registered discovery module, executes C<checkdevtype()> in
  70 I<sequential> order;
  71
  72 =item *
  73
  74 for those discovery modules which paid interest in this target host,
  75 executes C<discover()> in I<sequential> order;
  76
  77 =item *
  78
  79 upon request from C<bin/devdiscover>, builds the configuration
  80 XML tree, by calling C<buildConfig()> in I<sequential> order for each
  81 relevant discovery module for each target host.
  82
  83 =back
  84
  85 =item * C<Torrus::DevDiscover::DevDetails>
  86
  87 This Perl module is defined in F<perllib/Torrus/DevDiscover.pm>, and provides
  88 the functionality to store the results of SNMP device discovery.
  89
  90 =item * C<Torrus::ConfigBuilder>
  91
  92 This module is an encapsulation wrapper for XML configuration builder.
  93 It provides methods for every element of Torrus configuration.
  94
  95 =item * Discovery Modules
  96
  97 These provide all the functionality for SNMP discovery. Normally
  98 one module covers one MIB, or sometimes several vendor-specific MIBs,
  99 and it is responsible for finding out the device details necessary
 100 for Torrus configuration building. Usually a discovery module refers to one or
 101 several I<template definition files>. A module may depend on
 102 other modules' discovery results. This is controlled by its
 103 C<sequence number>. Vendor-independent discovery modules are normally named
 104 as C<Torrus::DevDiscover::RFCXXXX_SOME_HUMAN_NAME>, and vendor-specific
 105 ones are named as C<Torrus::DevDiscover::Vendor[Product[Subsystem]]>.
 106
 107 =item * Template definition files
 108
 109 These are XML documents residing in F<xmlconfig/vendor> and
 110 F<xmlconfig/generic> directories. Each file is a piece of Torrus configuration,
 111 and contains definitions and templates for particular MIB or vendor.
 112 Generic template definition files are for vendor-independent MIBs,
 113 and normally they are named as F<rfcXXXX.some-human-name.xml>.
 114 Vendor-specific files are named as F<vendor.product[.subsystem].xml>.
 115
 116 =back
 117
 118
 119 =head2 Discovery Module Internals
 120
 121 Discovery modules are Perl packages with few required components.
 122 Before creating your own modules, please read and follow
 123 I<Torrus Programming Style Guide>.
 124
 125 Upon initialization, C<Torrus::DevDiscover> loads the modules listed in
 126 C<@Torrus::DevDiscover::loadModules> array. This array is pre-populated
 127 by standard module names in F<devdiscover-config.pl>.
 128 You can add new module names by pushing them onto this array in your
 129 local F<devdiscover-siteconfig.pl>.
 130
 131 =head3 Module Registration
 132
 133 Each discovery module should register itself in DevDiscover registry.
 134 Normally there's only one registry entry per discovery module, though
 135 it's not a limitation. The registry entry is identified by a registry
 136 name, which normally repeats the module name.
 137
 138 Example:
 139
 140     $Torrus::DevDiscover::registry{'RFC2790_HOST_RESOURCES'} = {
 141         'sequence'     => 100,
 142         'checkdevtype' => \&checkdevtype,
 143         'discover'     => \&discover,
 144         'buildConfig'  => \&buildConfig
 145         };
 146
 147 Each registry entry must contain 4 fields:
 148
 149 =over 4
 150
 151 =item * C<sequence>
 152
 153 The sequence number determines the order in which every discovery module's
 154 procedure is executed. Sequence numbers of dependant modules must
 155 be higher than those of their dependencies.
 156
 157 Generic MIB discovery modules should have the sequence number 100. If
 158 a particular generic module depends on other generic modules, its sequence
 159 number may be 110.
 160
 161 Vendor-specific modules should have the sequence number 500.
 162 Vendor-specific modules that depend on other vendor-specific modules,
 163 should have sequence number 510.
 164
 165 Dependencies deeper than one level may exist, but it's recommended
 166 to avoid them. For most cases this should be enough.
 167
 168 Exception is made for C<RFC2863_IF_MIB> module, which has the sequence
 169 number 50. That is because it provides the basic interface discovery,
 170 and many other modules depend on its results.
 171
 172 Another exception is vendor-specific modules where the SNMP session parameters
 173 must be set earliest possible. One of such parameters is C<snmp-max-msg-size>.
 174 Some vendor SNMP agents would not be walked properly without this setting.
 175 In these occasions, the sequence number is below 50. The recommended value
 176 is 30.
 177
 178 =item * C<checkdevtype>
 179
 180 Must be a subroutine reference. This subroutine is called with two object
 181 references as arguments: C<Torrus::DevDiscover> and
 182 C<Torrus::DevDiscover::DevDetails>.
 183 The purpose of this subroutine is to determine if the target host is
 184 of required type, or if it supports the required MIB.
 185 The subroutine should return true if and only if the target host
 186 supports the MIB variables this module is supposed to discover.
 187
 188 In general, C<checkdevtype> subroutine is small, and checks one or several
 189 OIDs presence on the host, or their values, e.g. the value of I<sysObjectID>
 190 variable. It should perform as less as possible SNMP requests, in order to
 191 speed up the pre-discovery process.
 192
 193 =item * C<discover>
 194
 195 Must be a subroutine reference. This subroutine is called with the same
 196 two arguments as C<checkdevtype()>. It is called for those modules only,
 197 whose C<checkdevtype()> has returned true. The subroutine should return true
 198 if no errors occured during the discovery.
 199
 200 The purpose of C<discover()> is to perform the actual SNMP discovery,
 201 and prepare the parameter values for future XML configuration.
 202
 203 =item * C<buildConfig>
 204
 205 Must be a subroutine reference. This subroutine is called with three object
 206 references as arguments: C<Torrus::DevDiscover::DevDetails>,
 207 C<Torrus::ConfigBuilder>, and an XML element object, which should be used only
 208 to pass data to ConfigBuilder methods.
 209
 210 This subroutine is designed to construct the resulting XML configuration
 211 subtree as a child of a given XML element. Upper level subtrees
 212 are handled by CLI options processing code.
 213
 214 =back
 215
 216
 217 =head3 OID Definitions
 218
 219 OID definitions are designed to provide symbolic names to OIDs
 220 in numerical notation. Normally the symbolic names repeat the names from
 221 corresponding MIBs.
 222
 223 The definitions must be defined in an C<oiddef> hash defined in the
 224 package namespace. Then they are automatically imported by DevDiscover
 225 initialization procerure.
 226
 227 Example:
 228
 229     our %oiddef =
 230         (
 231          'hrSystemUptime'               => '1.3.6.1.2.1.25.1.1.0',
 232          'hrSystemNumUsers'             => '1.3.6.1.2.1.25.1.5.0',
 233          'hrSystemProcesses'            => '1.3.6.1.2.1.25.1.6.0',
 234          'hrSystemMaxProcesses'         => '1.3.6.1.2.1.25.1.7.0',
 235          'hrMemorySize'                 => '1.3.6.1.2.1.25.2.2.0',
 236          'hrStorageTable'               => '1.3.6.1.2.1.25.2.3.1',
 237          'hrStorageIndex'               => '1.3.6.1.2.1.25.2.3.1.1',
 238          'hrStorageType'                => '1.3.6.1.2.1.25.2.3.1.2',
 239          'hrStorageDescr'               => '1.3.6.1.2.1.25.2.3.1.3',
 240          'hrStorageAllocationUnits'     => '1.3.6.1.2.1.25.2.3.1.4',
 241          'hrStorageSize'                => '1.3.6.1.2.1.25.2.3.1.5',
 242          'hrStorageUsed'                => '1.3.6.1.2.1.25.2.3.1.6',
 243          'hrStorageAllocationFailures'  => '1.3.6.1.2.1.25.2.3.1.7'
 244          );
 245
 246
 247 =head3 Template References
 248
 249 Normally a discovery module would refer to configuration templates
 250 defined in template definition files. In order to provide an extra level of
 251 flexibility, these templates should be defined in
 252 F<devdiscover-config.pl> or in F<devdiscover-siteconfig.pl>.
 253
 254 It is recommended that the template references in the discovery modules
 255 follow the naming standard: C<module::template-name>.
 256
 257 ConfigBuilder's C<addTemplateApplication()> method looks up every
 258 template name in the global hash C<%Torrus::ConfigBuilder::templateRegistry>
 259 and figures out the source XML file and the actual template name.
 260
 261 Example:
 262
 263     $Torrus::ConfigBuilder::templateRegistry{
 264         'RFC2790_HOST_RESOURCES::hr-system-uptime'} = {
 265             'name'   => 'mytest-hr-system-uptime',
 266             'source' => 'mytest.templates.xml'
 267             };
 268
 269
 270 =head3 Interface filtering
 271
 272 Usually not all interfaces from ifTable need to be monitored.
 273 For example, Loopback and Null0 interfaces on Cisco routers.
 274
 275 C<Torrus::DevDiscover::RFC2863_IF_MIB> provides the functionality to
 276 automatically filter out the interfaces, based on filter definitions.
 277 Filter definitions are registered by calling the subroutine
 278 C<Torrus::DevDiscover::RFC2863_IF_MIB::addInterfaceFilter
 279 ($devdetails, $interfaceFilter)>. The second argument is a reference
 280 to a hash of the following structure:
 281
 282 Keys are symbolic names that mean nothing and need only to be unique.
 283 Values are hash references with the following entries: C<ifType>
 284 specifies the IANA interface type, and optional C<ifDescr> specifies
 285 a regular expression to match against interface description.
 286
 287 The filters are usually registered within C<checkdevtype> subroutine
 288 of the vendor module, after the device type is identified. See
 289 F<CiscoIOS.pm> and F<CiscoCatOS.pm> as examples.
 290
 291
 292 =head2 Authors
 293
 294 Shawn Ferry: initial draft.
 295
 296 Stanislav Sinyagin: revision and detailed content.