=head1 NAME

B<check_snmp> - spong-network module to check for proper SNMP agent operation

=head1 DESCRIPTION

This is a plugin module for the Spong L<spong-network> program. It is a core
Spong module. The B<check_snmp> module checks for the SNMP agent running
in the host for proper operation. 

The module check SNMP by issuing an I<snmpget> operation for the I<systemGroup>
table of the host. If the operation is sucessfully, snmp service is deemed
OK. The module also has an option check for the I<sysObjectId>. An expected
I<sysObjectId> value can be specified to be checked against the I<sysObjectId>
value retrieved in the snmpget operation. If the values don't agree, a
critical (red) status is reported

=cut
#
# $Id: check_snmp,v 1.5 2000/11/29 17:12:49 sljohnson Exp $

# Register the routine with the plugin registry
$PLUGINS{'snmp'} = \&check_snmp;

use BER "0.57";			# should be in eval
use SNMP_Session "0.59";	# should be in eval
use SNMP_util "0.57";		# should be in eval
use Socket;

# This check will connect to a unit and ask it to return the system group
# If it can do that, then we assume it is ok - if it can't then something is wrong.

sub check_snmp {
	my ($host ) = @_;
	my ($color, $summary, $message ) = ( "green", "", "" );
	my  $snmp_session;

        # Find the community name to use
	my ($community) = $HOSTS{$host}->{'snmp_community'} ||
                          $HOSTS_DEFAULTS{'snmp_community'} ||
                          'public';

        # Find an expect oid to find
	my ($expect) = $HOSTS{$host}->{'expect_oid'} ||
                       $HOSTS_DEFAULTS{'expect_oid'};
   
	$snmp_session = SNMP_Session->open ($host, $community, 161);

        if (! $snmp_session ) { 
           $color = 'red';
           $summary = "Error creating session to $host";
           $message = $SNMP_Session::errmsg . "\n";;
           return ( $color, $summary, $message );
        }

	snmpmapOID('sysObjectID' => '1.3.6.1.2.1.1.2.0');

	$SNMP_Session::suppress_warnings = 2;
	my ($sysDescr,$sysUpTime,$sysContact,$sysName,$sysLocation,$sysObjectID) =
		snmpget("$community\@$host",
			'sysDescr',
			'sysUpTime',
			'sysContact',
			'sysName',	
			'sysLocation', 
			'sysObjectID');

        if ( ! defined $sysDescr )  {
           $color = 'red';
           $summary = 'Error retreiving System Group information';
           $message = $SNMP_Session::errmsg . "\n";
           return ( $color, $summary, $message );
        }

	debug ("snmp - $sysObjectID", 4 );

	if ($sysObjectID) {
		$message = "retrieved system group from $host\n\n";
		$message .= "sysDescr: $sysDescr\n";
		$message .= "sysUpTime: $sysUpTime\n";
		$message .= "sysContact: $sysContact\n";
		$message .= "sysName: $sysName\n";
		$message .= "sysLocation: $sysLocation\n";
		$message .= "sysObjectID: $sysObjectID\n";
		if ( $expect && "$sysObjectID" ne "$expect") {
			$color = "red";
			$summary = "wrong equipment type";
			$message .= "sysObjectID should have been $expect\n";
		} else {
			$summary = "snmp ok";
		}
	} else {
		$color = "red";
		$summary = "can't retreive system group from $host";
		$message = "can't retreive system group from $host\n";
	}
   
        $snmp_session->close();
	debug ("snmp - $host - $color, $summary" );
	return ($color, $summary, $message );
}



1;


__END__

=head2 Output Returned

=over 4

=item Status

If the I<snmpget> operation is successfully, 'green' status is return. If an
SNMP error occurs a 'red' status is returned.

If an B<expect_objid> is specified for the host, a 'green' status is returned
if the I<snmpget> operation is successful and the I<sysObjectId> value matches
the B<expect_objid>. If the values don't match, a 'red' status is returned.

=item Summary Field

If there are no problems, "snmp ok" is returned. Otherwise the summary field
will have a short description of that the problem or anamoly is.

=item Detail Message Field

If normal operation the detail message will have the values of the system
description (I<sysDesc>), uptime (I<sysUpTime>), contact (I<sysContact>), name
(I<sysName>), location (I<sysLocation>), and object id (I<sysObjectID>) fields
from the System Group. If an B<expect_objid> was specified for the host and the
retrived object id doesn't match, the expected value will also be listed.
Otherwise this field will have a detailed description of the cause of an error.

=back

=head2 Configuration

=over 4

=item SNMP Community Name

The default SNMP Community name is I<public>. To override the default name
specify a C<snmp_community> attribute in a host's entry in the I<%HOSTS>
variable in the L<spong.conf> configuration file. See 
L<"EXAMPLES"> for a detailed example.

=item Expected System Object ID

You can specify an expected I<sysObjectID> value to be checked against the
retrieved. Specify a C<expect_objid> attribute in a host's entry in the
I<%HOSTS> variable in the L<spong.conf> configuration file. See the
L<Examples|"EXAMPLES"> section for a detailed example.

=back

=head1 EXAMPLES

 %HOSTS = ( 'hostname.my-inc.com' => { 'services'  => 'snmp',
                                       'ip_addr'  => ['192.168.13.123'],
                                       'snmp_community' => 'local-read',
                                       'expect_objid' =>
                                           '1.3.6.1.4.1.2021.250.10',
          );

=head1 SEE ALSO

L<spong-network>, L<check_interfaces>,
L<spong-network Modules Template|spong-network-mod-template>,
L<Spong Developer's Guide|developer-guide>

=head1 NOTES

The B<check_snmp> module uses an SNMP I<snmpget> operation to poll a host.
It retrieves the values of the system description (I<sysDesc>), uptime
(I<sysUpTime>), contact (I<sysContact>), name (I<sysName>), location
(I<sysLocation>), and object id (I<sysObjectID>) fields from the System Group.
If the I<snmpget> operation was successful, the snmp service is deemed OK.

If an optional B<expect_objid> value is specified for the host, it will be
compared to the I<sysObjectID> value retrieved from the host. If the values
don't match a critical ('red') status is generated.

=head1 RESTRICTIONS

B<check_interfaces> uses the C<SNMP_Session>, C<SNMP_utils> and C<BER> modules
from the B<SNMP_Session> package. The B<SNMP_Session> package must be installed
in order for this module to work.

The latest version of B<SNMP_Session> package can be obtained from:

  http://www.switch.ch/misc/leinen/snmp/perl/index.html 

=head1 AUTHOR

The original author is Mike Bayliss <F<mbayliss@datax.be>>. Extra debug code
and enhancements added by Stephen L Johnson <F<sjohnson@monsters.org>>.

