NAME

VBTK::Snmp - Snmp monitoring.

SYNOPSIS

  $stdHeader = 
      [ 'Time              Idx IfDescr                           Bytes/Sec In',
        '----------------- --- --------------------------------- ------------' ];
  $stdDetail = 
      [ '@<<<<<<<<<<<<<<<< @<< @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< @>>>>>>>>>>>',
        '$time,            @data[0,1],                           int($delta[2]/60)' ];

  $s = new VBTK::Snmp (
    Interval          => 60,
    Labels            => [ 'ifIndex','ifDescr','ifInOctets' ],
    Host          => 'myhost',
    Port          => 161,
    VBServerURI       => 'http://myvbserver:4712',
    VBHeader          => $stdHeader,
    VBDetail          => $stdDetail,          
    LogFile           => '/var/log/snmp.myhost.log'
    LogHeader         => $stdHeader,
    LogDetail         => $stdDetail,
    RotateLogAt       => '12:00am',
    Timeout           => undef,
  );

  $s->addVBObj (
    VBObjName           => ".myhost.netio",
  );

  &VBTK::runAll;

DESCRIPTION

This perl library provides the ability to request SNMP data from a specified host and then set the status of a VBObject based on the results of that data.

Note that the 'new VBTK::Snmp' and '$s->addVBObj' lines just initialize and register the objects. It's the &VBTK::runAll which starts the monitoring.

SUB-CLASSES

There are many values to setup when declaring an SNMP monitor object. To simplify things, most of these values will default appropriately. In addition, several sub-classes are provided which have customized defaults for specific uses. The following sub-classes are provided:

VBTK::Snmp::Mib2NetIO

Defaults for monitoring network I/O.

VBTK::Snmp::Dynamo

Defaults for monitoring a dynamo server.

VBTK::Snmp::WinNTCpu

Defaults to monitoring CPU utilization on an NT server, by using the SNMP packages in the NT resource kit.

Others will follow.

PUBLIC METHODS

The following methods are available to the common user:

$s = new VBTK::Snmp (<parm1> => <val1>, <parm2> => <val2>, ...)

The allowed parameters are:

Interval

The interval (in seconds) on which the command should be run. (Defaults to 60)

    Interval => 60,

Labels

An array of strings containing SNMP labels or oid's to be monitored. (Required)

    Labels => [ 'ifIndex','ifDescr','ifInOctets' ],

Host

Hostname or IP address to monitor.

    Host => 'myhost',

Port

Port number on which the snmp service is listening

Community

The community string to use when connecting to the Snmp host. (Default to 'public')

VBServerURI

A URI which specifies which VB Server to report results to. Defaults to the environment variable $VBURI.

    VBServerURI => 'http://myvbserver:4712',

VBHeader

An array containing strings to be used as header lines when transmitting results to the VB Server process.

  VBHeader = [ 
      'Time              Idx IfDescr                           Bytes/Sec In',
      '----------------- --- --------------------------------- ------------' ];

VBDetail

An array containing strings to be used to format the detail lines which will be sent to the VB Server process. These strings can make use of the Perl picture format syntax.

  VBDetail => [
      '@<<<<<<<<<<<<<<<< @<< @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< @>>>>>>>>>>>',
      '$time,            @data[0,1],                           int($delta[2]/60)' ];

The following variables will be set just before these detail lines are evaluated:

$time

A datestamp of the form YYYYMMDD-HH:MM:SS

@data

An two-dimensional array containing the SNMP data returned.

@delta

An array containing the delta's calculated between the current @data and the previous @data. In multi-row output, the row number is used to match up multiple @data arrays with their previous @data values to calulate the deltas. These deltas are most useful when monitoring the change in counters. This is very common in SNMP monitors.

LogFile

A string containing the path to a file where a log file should be written.

    LogFile => '/var/log/snmp.myhost.log',

LogHeader

Same as VBHeader, but to be used in formatting the log file.

LogDetail

Same as VBDetail, but to be used in formatting the log file.

RotateLogAt

A string containing a date/time expression indicating when the log file should be rotated. When the log is rotated, the current log will have a timestamp appended to the end of it after which logging will continue to a new file with the original name. The expression will be passed to Date::Manip so it can be just about any recognizable date/time expression.

    RotateLogAt => '12:00am',

PreProcessor

A pointer to a subroutine to which incoming data should be passed for pre-processing. The subroutine will be passed a pointer to the @data array as received by the Parser. With SNMP data, the @data array will contain an array of arrays. The subroutine can modify this data, remove rows, group rows into columns, etc. This is a fairly advanced function, so don't use it unless you know what you're doing.

    # Filter out any rows where column 2 is less than 10
    PreProcessor = sub {
        my($data) = @_;
        @{$data} = grep($_->[2] >= 10,@{$data});
    }

Timeout

A number indicating the number of seconds to wait for the response from the SNMP host before re-trying. Be careful with setting this too high, since the VBTK engine is single-threaded, and a long delay can delay status reports from other objects. (Defaults to 3)

    Timeout => 3,

Retries

A number indicating the number of times to retry the SNMP request before setting the status to 'ErrorStatus'. Be careful with setting this too high, since the VBTK engine is single-threaded, and a long delay can delay status reports from other objects. (Defaults to 1)

    Retries => 1,

ErrorStatus

The status to which any associated VBObjects should be set if the SNMP request times out or fails. (Defaults to 'Failed')

    ErrorStatus => 'Warning',

GetMultRows

A boolean (0 or 1) indicating whether the SNMP monitor should expect multiple rows in the result set. This must be set to get correct results since it determines whether we'll use 'get' or 'getnext' to retrieve the data. (Defaults to 0)

    GetMultRows => 1,

$o = $s->addVBObj(<parm1> => <val1>, <parm2> => <val2>, ...)

The 'addVBObj' is used to define VBObjects which will appear on the VBServer to which status reports are transmitted. See the VBTK::Parser class for a list of valid parms and their descriptions.

$s->addMibFiles(<file1>,...)

Add's specific Mib files into the list of MIB files to be searched when resolving Label names to OID's.

    $s->addMibFiles('/usr/vbtk/mib/NTCPU.mib');

$s->addMibDirs(<dir1>,...)

Add's directories into the list of directories to search when resolving Label names to OID's.

    $s->addMibDirs('/usr/vbtk/mib');

PRIVATE METHODS

The following private methods are used internally. Do not try to use them unless you know what you are doing.

To be documented...

SEE ALSO

VBTK VBTK::Parser

AUTHOR

Brent Henry, vbtoolkit@yahoo.com

COPYRIGHT

Copyright (C) 1996-2002 Brent Henry

This program is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation available at: http://www.gnu.org/copyleft/gpl.html

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.