package SNMP::Simple;
use strict;
use warnings;
use Carp;
=head1 NAME
SNMP::Simple - shortcuts for when using SNMP
=cut
our $VERSION = 0.02;
use SNMP;
$SNMP::use_enums = 1; # can be overridden with new(UseEnums=>0)
=head1 SYNOPSIS
use SNMP::Simple;
$name = $s->get('sysName'); # same as sysName.0
$location = $s->get('sysLocation');
@array = $s->get_list('hrPrinterStatus');
$arrayref = $s->get_list('hrPrinterStatus');
@list_of_lists = $s->get_table(
qw(
prtConsoleOnTime
prtConsoleColor
prtConsoleDescription
)
);
@list_of_hashes = $s->get_named_table(
name => 'prtInputDescription',
media => 'prtInputMediaName',
status => 'prtInputStatus',
level => 'prtInputCurrentLevel',
max => 'prtInputMaxCapacity',
);
=head1 DESCRIPTION
This module provides shortcuts when performing repetitive information-retrieval
tasks with L<SNMP>.
Instead of this:
use SNMP;
$vars = new SNMP::VarList( ['prtConsoleOnTime'], ['prtConsoleColor'],
['prtConsoleDescription'], );
my ( $light_status, $light_color, $light_desc ) = $s->getnext($vars);
die $s->{ErrorStr} if $s->{ErrorStr};
while ( !$s->{ErrorStr} and $$vars[0]->tag eq "prtConsoleOnTime" ) {
push @{ $data{lights} },
{
status => ( $light_status ? 0 : 1 ),
color => SNMP::mapEnum( $$vars[1]->tag, $light_color ),
description => $light_desc,
};
( $light_status, $light_color, $light_desc ) = $s->getnext($vars);
}
...you can do this:
use SNMP::Simple;
$data{lights} = $s->get_named_table(
status => 'prtConsoleOnTime',
color => 'prtConsoleColor',
name => 'prtConsoleDescription',
);
=head2 SNMP Beginners, read me first!
Please, please, B<please> do not use this module as a starting point for
working with SNMP and Perl. Look elsewhere for starting resources:
=over 4
=item * The L<SNMP> module
=item * The Net-SNMP web site (L<http://www.net-snmp.org/>) and tutorial (L<http://www.net-snmp.org/tutorial-5/>)
=item * Appendix E of Perl for System Administration (L<http://www.amazon.com/exec/obidos/tg/detail/-/1565926099>) by David N. Blank-Edelman
=back
=head2 SNMP Advanced and Intermediate users, read me first!
I'll admit this is a complete slaughtering of SNMP, but my goals were precise.
If you think SNMP::Simple could be refined in any way, feel free to send me
suggestions/fixes/patches.
=cut
=head1 METHODS
=head2 new( @args )
Creates a new SNMP::Simple object. Arguments given are passed directly to
C<SNMP::Session-E<gt>new>. See L<SNMP/"SNMP::Session"> for details.
Example:
use SNMP::Simple
my $s = SNMP::Simple->new(
DestHost => 'host.example.com',
Community => 'public',
Version => 1,
) or die "couldn't create session";
...
=cut
sub new {
my ( $class, @args ) = @_;
my $session = SNMP::Session->new(@args)
or croak "Couldn't create session";
bless \$session, $class;
}
=head2 get( $oid )
Gets the named variable and returns its value. If no value is returned,
C<get()> will try to retrieve a list named C<$name> and return its first vlaue.
Thus, for convenience,
$s->get('sysDescr')
..should be the same as:
$s->get('sysDescr.0')
Numbered OIDs are fine, too, with or without a leading dot:
$s->get('1.3.6.1.2.1.1.1.0')
C<SNMP::mapEnum()> is automatically used on the result.
=cut
sub get {
my ( $self, $name ) = @_;
my $result = $$self->get($name) || ( $self->get_list($name) )[0];
my $enum = SNMP::mapEnum( $name, $result );
return defined $enum ? $enum : $result;
}
=head2 get_list( $oid )
Returns leaves of the given OID.
If called in array context, returns an array. If called in scalar context,
returns an array reference.
=cut
sub get_list {
my ( $self, $oid ) = @_;
my @table = $self->get_table($oid);
my @output = map { $_->[0] } @table;
return wantarray ? @output : \@output;
}
=head2 get_table( @oids )
Given a list of OIDs, this will return a list of lists of all of the values of
the table.
For example, to get a list of all known network interfaces on a machine and
their status:
$s->get_table('ifDescr', 'ifOperStatus')
Would return something like the following:
[ 'lo', 'up' ],
[ 'eth0', 'down' ],
[ 'eth1', 'up' ],
[ 'sit0', 'down' ]
If called in array context, returns an array (of arrays). If called in scalar
context, returns an array reference.
=cut
sub get_table {
my ( $self, @oids ) = @_;
my @output = ();
# build our varlist, the fun VarList way
my $vars = new SNMP::VarList( map { [$_] } @oids );
# get our initial results, assume that we should be able to get at least
# *one* row back
my @results = $$self->getnext($vars);
croak $$self->{ErrorStr} if $$self->{ErrorStr};
# dNb's recipe for iteration: make sure that there's no error and that the
# OID name of the first cell is actually what we want
while ( !$$self->{ErrorStr} and $$vars[0]->tag eq $oids[0] ) {
push @output, [@results];
@results = $$self->getnext($vars);
}
return wantarray ? @output : \@output;
}
=head2 get_named_table( %oids_by_alias )
Like L<"get_table">, but lets you rename ugly OID names on the fly. To get
a list of all known network interfaces on a machine and their status:
$s->get_table( name => 'ifDescr', status => 'ifOperStatus' )
Would return something like the following:
{
status => 'up',
name => 'lo'
},
{
status => 'down',
name => 'eth0'
},
{
status => 'up',
name => 'eth1'
},
{
status => 'down',
name => 'sit0'
}
If called in array context, returns an array (of hashes). If called in scalar
context, returns an array reference.
=cut
sub get_named_table {
my $self = shift;
my %oid_to_name = reverse @_;
my @oids = keys %oid_to_name;
# remap table so it's a list of hashes instead of a list of lists
my @table = $self->get_table( keys %oid_to_name );
my @output;
foreach my $row (@table) {
my %data = ();
for ( my $i = 0; $i < @oids; $i++ ) {
$data{ $oid_to_name{ $oids[$i] } } = $row->[$i];
}
push @output, \%data;
}
return wantarray ? @output : \@output;
}
=head1 EXAMPLES
A sample script F<examples/printerstats.pl> is included with this distribution.
=head1 SEE ALSO
L<SNMP>
=head1 AUTHOR
Ian Langworth, C<< <ian@cpan.org> >>
=head1 BUGS
=over 4
=item * There are no real tests.
=item * I haven't tested this with v3.
=back
Please report any bugs or feature requests to
C<bug-snmp-simple@rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org>. I will be notified, and then you'll automatically be
notified of progress on your bug as I make changes.
=head1 COPYRIGHT & LICENSE
Copyright 2005 Ian Langworth, All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
=cut
1;