NAME

SNMP::Monitor - a Perl package for monitoring remote hosts via SNMP

SYNOPSIS

    require SNMP::Monitor;

    # Read a configuration file
    my $config = SNMP::Monitor->Configuration("/etc/snmpmon/config");

    # Create a new monitor
    my $monitor = SNMP::Monitor->new($config);

    # Start monitoring (endless loop, never returns)
    $monitor->Loop();

DESCRIPTION

The SNMP::Monitor module is a package for checking and watching arbitrary values via SNMP. Events can be triggered, Logging can be done, whatever you want.

The package is based on the SNMP package, but it is merely created for system administrators and not for programmers.

The following class methods are offered:

Configuration($file)

(Class method) Read a monitor configuration from $file. The module SNMP::Monitor::Install is available for creating such files. See SNMP::Monitor::Install. No error indicators, the method dies in case of trouble.

new($config)

(Class method) This is the monitor constructor. Given a monitor configuration $config, as returned by the Configuration method (see above), returns a new monitor. Internally the monitor is a set of sessions (instances of SNMP::Monitor::Session) and events (instances of SNMP::Monitor::Event). Currently there are two available event classes: One for watching an interface status and one for logging interface loads into a database. See "EVENT IMPLEMENTATION" below.

Message(\%attr)

(Instance method) Called for sending an E-Mail via the Mail::Internet module. See Mail::Internet(3). The following keys are supported in the hash ref \%attr:

body

The message body.

mailhost

A host being used as SMTP server. By default the mail host from the config file or localhost are used.

to

cc

bcc

Mail recipients, or recipient lists (comma separated values).

All other keys are used as mail headers, in particular the attributes subject and from should be present.

Loop()

(Instance method) The monitor enters an endless loop. Every 60 seconds it checks its event lists and requests SNMP values, if desired. (You cannot rely on these 60 seconds, though, because the SNMP package doesn't support asynchronous SNMP requests.)

EVENT IMPLEMENTATION

Currently only two event classes are available: The SNMP::Monitor::Event::IfStatus class for watching an interface status and the SNMP::Monitor::Event::IfLoad class for logging interface utilization into a database.

However, it is fairly simple two add arbitrary new event classes: All you need is a constructor method new for setting up an SNMP variable list and a method Process for processing these lists when the monitor requested it for you. Let's see the SNMP::Monitor::Event::IfStatus class for an example:

    sub new ($$$) {
        my($proto, $session, $attr) = @_;
        my $self = $proto->SUPER::new($session, $attr);

        my $table = "interfaces.ifTable.ifEntry";
        my $v = "SNMP::Varbind";
        my $num = $self->{num};
        $self->{vars} = [ $v->new(["$table.ifDescr", $num]),
                          $v->new(["$table.ifAdminStatus", $num]),
                          $v->new(["$table.ifOperStatus", $num])];
        $self;
    }

The method starts by calling its super classes constructor, SNMP::Monitor::Event::new. Once that is done, it creates an attribute $self->{'vars'}, an array ref of SNMP variables that the monitor should fill in. It might additionally initialize the attribute $self->{'init_count'}: This attribute defaults to 1, telling the monitor, that it should request variables for this event every minute. For example, the IfLoad module is using a value of 5, because logging every 5 minutes seems to me to be sufficient.

The second method to overwrite is the Process method. This is called whenever the monitor has fetched SNMP variables for the event. Here's the Process method of the IfStatus class:

  sub Process ($) {
    my($self) = @_;
    my $session = $self->{session};
    my $vr_session = $session->{vars_registered};
    my $vr_self = $self->{vars_registered};

    # The following list corresponds to the list in the 'new' method.
    # This is important when calculation the index $i in $vr_self->[$i].
    my $ifDescr = $vr_session->[$vr_self->[0]]->[0]->[2];
    my $ifAdminStatus = $vr_session->[$vr_self->[1]]->[0]->[2];
    my $ifOperStatus = $vr_session->[$vr_self->[2]]->[0]->[2];
    my $num = $self->{num};

    # Now do anything with the values; in case of the IfStatus
    # this means sending a mail whenever the status has changed
    ...

    # Note the current value for the next time we are called
    $self->{ifAdminStatus} = $ifAdminStatus;
    $self->{ifOperStatus} = $ifOperStatus;
  }

AUTHOR AND COPYRIGHT

This module is Copyright (C) 1998 by

    Jochen Wiedmann
    Am Eisteich 9
    72555 Metzingen
    Germany

    Phone: +49 7123 14887
    Email: joe@ispsoft.de

All rights reserved.

You may distribute this module under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

SEE ALSO

SNMP(3), snmpmon(1), SNMP::Monitor::Install(3)