### - *- mode: Perl -*-

######################################################################

### Net_SNMP_util -- SNMP utilities using Net::SNMP

######################################################################

### Copyright (c) 2005-2011 Mike Mitchell.

###

### This program is free software; you can redistribute it under the

### "Artistic License" included in this distribution (file "Artistic").

######################################################################

### Created by:  Mike Mitchell   <Mike.Mitchell@sas.com>

###

### Contributions and fixes by:

###

### Laszlo Herczeg <laszlo.herczeg@austinenergy.com>

###	ignore unimplemented SNMP_Session.pm options

###

### Daniel McDonald <dmcdonald@digicontech.com>

### 	make sure snmpwalk_flg stops when last instance in table is fetched

###

### Alexander Kozlov <avk@post.eao.ru>

###	Leave snmpwalk_flg early if no OIDs are returned

###

### <jaccobs@online.nl>

###	parse NOTIFICATION-TYPE in MIB

###

### Dan Thorson <Dan.Thorson@seagate.com>

###	Handle quotes in MIB comments better

###

### Daniel J McDonald <dan.mcdonald@austinenergy.com>

###	fix getbulk_request -> get_bulk_request typo

###

### Tobias Oetiker <tobi@oetiker.ch>

###	fix '-privpassword' error against snmpv2 hosts

###

######################################################################

package Net_SNMP_util;

=head1 NAME

Net_SNMP_util - SNMP utilities based on Net::SNMP

=head1 SYNOPSIS

The Net_SNMP_util module implements SNMP utilities using the Net::SNMP module.

It implements snmpget, snmpgetnext, snmpwalk, snmpset, snmptrap, and

snmpgetbulk.  The Net_SNMP_util module assumes that the user has a basic

understanding of the Simple Network Management Protocol and related network

management concepts.

=head1 DESCRIPTION

The Net_SNMP_util module simplifies SNMP queries even more than Net::SNMP  

alone.  Easy-to-use "get", "getnext", "walk", "set", "trap", and "getbulk"

routines are provided, hiding all the details of a SNMP query.

=cut

# ==========================================================================

use strict;

## Validate the version of Perl

BEGIN

{

    die('Perl version 5.6.0 or greater is required') if ($] < 5.006);

}

## Handle importing/exporting of symbols

use vars qw( @ISA @EXPORT $VERSION $ErrorMessage);

use Exporter;

our @ISA = qw( Exporter );

our @EXPORT = qw(

    snmpget snmpgetnext snmpwalk snmpset snmptrap snmpgetbulk snmpmaptable

    snmpmaptable4 snmpwalkhash snmpmapOID snmpMIB_to_OID snmpLoad_OID_Cache

    snmpQueue_MIB_File ErrorMessage

);

## Version of the Net_SNMP_util module

our $VERSION = v1.0.20;

use Carp;

use Net::SNMP v5.0;

# The OID numbers from RFC1213 (MIB-II) and RFC1315 (Frame Relay)

# are pre-loaded below.

%Net_SNMP_util::OIDS = 

  (

    'iso' => '1',

    'org' => '1.3',

    'dod' => '1.3.6',

    'internet' => '1.3.6.1',

    'directory' => '1.3.6.1.1',

    'mgmt' => '1.3.6.1.2',

    'mib-2' => '1.3.6.1.2.1',

    'system' => '1.3.6.1.2.1.1',

    'sysDescr' => '1.3.6.1.2.1.1.1.0',

    'sysObjectID' => '1.3.6.1.2.1.1.2.0',

    'sysUpTime' => '1.3.6.1.2.1.1.3.0',

    'sysUptime' => '1.3.6.1.2.1.1.3.0',

    'sysContact' => '1.3.6.1.2.1.1.4.0',

    'sysName' => '1.3.6.1.2.1.1.5.0',

    'sysLocation' => '1.3.6.1.2.1.1.6.0',

    'sysServices' => '1.3.6.1.2.1.1.7.0',

    'interfaces' => '1.3.6.1.2.1.2',

    'ifNumber' => '1.3.6.1.2.1.2.1.0',

    'ifTable' => '1.3.6.1.2.1.2.2',

    'ifEntry' => '1.3.6.1.2.1.2.2.1',

    'ifIndex' => '1.3.6.1.2.1.2.2.1.1',

    'ifInOctets' => '1.3.6.1.2.1.2.2.1.10',

    'ifInUcastPkts' => '1.3.6.1.2.1.2.2.1.11',

    'ifInNUcastPkts' => '1.3.6.1.2.1.2.2.1.12',

    'ifInDiscards' => '1.3.6.1.2.1.2.2.1.13',

    'ifInErrors' => '1.3.6.1.2.1.2.2.1.14',

    'ifInUnknownProtos' => '1.3.6.1.2.1.2.2.1.15',

    'ifOutOctets' => '1.3.6.1.2.1.2.2.1.16',

    'ifOutUcastPkts' => '1.3.6.1.2.1.2.2.1.17',

    'ifOutNUcastPkts' => '1.3.6.1.2.1.2.2.1.18',

    'ifOutDiscards' => '1.3.6.1.2.1.2.2.1.19',

    'ifDescr' => '1.3.6.1.2.1.2.2.1.2',

    'ifOutErrors' => '1.3.6.1.2.1.2.2.1.20',

    'ifOutQLen' => '1.3.6.1.2.1.2.2.1.21',

    'ifSpecific' => '1.3.6.1.2.1.2.2.1.22',

    'ifType' => '1.3.6.1.2.1.2.2.1.3',

    'ifMtu' => '1.3.6.1.2.1.2.2.1.4',

    'ifSpeed' => '1.3.6.1.2.1.2.2.1.5',

    'ifPhysAddress' => '1.3.6.1.2.1.2.2.1.6',

    'ifAdminHack' => '1.3.6.1.2.1.2.2.1.7',  

    'ifAdminStatus' => '1.3.6.1.2.1.2.2.1.7',

    'ifOperHack' => '1.3.6.1.2.1.2.2.1.8',             

    'ifOperStatus' => '1.3.6.1.2.1.2.2.1.8',

    'ifLastChange' => '1.3.6.1.2.1.2.2.1.9',

    'at' => '1.3.6.1.2.1.3',

    'atTable' => '1.3.6.1.2.1.3.1',

    'atEntry' => '1.3.6.1.2.1.3.1.1',

    'atIfIndex' => '1.3.6.1.2.1.3.1.1.1',

    'atPhysAddress' => '1.3.6.1.2.1.3.1.1.2',

    'atNetAddress' => '1.3.6.1.2.1.3.1.1.3',

    'ip' => '1.3.6.1.2.1.4',

    'ipForwarding' => '1.3.6.1.2.1.4.1',

    'ipOutRequests' => '1.3.6.1.2.1.4.10',

    'ipOutDiscards' => '1.3.6.1.2.1.4.11',

    'ipOutNoRoutes' => '1.3.6.1.2.1.4.12',

    'ipReasmTimeout' => '1.3.6.1.2.1.4.13',

    'ipReasmReqds' => '1.3.6.1.2.1.4.14',

    'ipReasmOKs' => '1.3.6.1.2.1.4.15',

    'ipReasmFails' => '1.3.6.1.2.1.4.16',

    'ipFragOKs' => '1.3.6.1.2.1.4.17',

    'ipFragFails' => '1.3.6.1.2.1.4.18',

    'ipFragCreates' => '1.3.6.1.2.1.4.19',

    'ipDefaultTTL' => '1.3.6.1.2.1.4.2',

    'ipAddrTable' => '1.3.6.1.2.1.4.20',

    'ipAddrEntry' => '1.3.6.1.2.1.4.20.1',

    'ipAdEntAddr' => '1.3.6.1.2.1.4.20.1.1',

    'ipAdEntIfIndex' => '1.3.6.1.2.1.4.20.1.2',

    'ipAdEntNetMask' => '1.3.6.1.2.1.4.20.1.3',

    'ipAdEntBcastAddr' => '1.3.6.1.2.1.4.20.1.4',

    'ipAdEntReasmMaxSize' => '1.3.6.1.2.1.4.20.1.5',

    'ipRouteTable' => '1.3.6.1.2.1.4.21',

    'ipRouteEntry' => '1.3.6.1.2.1.4.21.1',

    'ipRouteDest' => '1.3.6.1.2.1.4.21.1.1',

    'ipRouteAge' => '1.3.6.1.2.1.4.21.1.10',

    'ipRouteMask' => '1.3.6.1.2.1.4.21.1.11',

    'ipRouteMetric5' => '1.3.6.1.2.1.4.21.1.12',

    'ipRouteInfo' => '1.3.6.1.2.1.4.21.1.13',

    'ipRouteIfIndex' => '1.3.6.1.2.1.4.21.1.2',

    'ipRouteMetric1' => '1.3.6.1.2.1.4.21.1.3',

    'ipRouteMetric2' => '1.3.6.1.2.1.4.21.1.4',

    'ipRouteMetric3' => '1.3.6.1.2.1.4.21.1.5',

    'ipRouteMetric4' => '1.3.6.1.2.1.4.21.1.6',

    'ipRouteNextHop' => '1.3.6.1.2.1.4.21.1.7',

    'ipRouteType' => '1.3.6.1.2.1.4.21.1.8',

    'ipRouteProto' => '1.3.6.1.2.1.4.21.1.9',

    'ipNetToMediaTable' => '1.3.6.1.2.1.4.22',

    'ipNetToMediaEntry' => '1.3.6.1.2.1.4.22.1',

    'ipNetToMediaIfIndex' => '1.3.6.1.2.1.4.22.1.1',

    'ipNetToMediaPhysAddress' => '1.3.6.1.2.1.4.22.1.2',

    'ipNetToMediaNetAddress' => '1.3.6.1.2.1.4.22.1.3',

    'ipNetToMediaType' => '1.3.6.1.2.1.4.22.1.4',

    'ipRoutingDiscards' => '1.3.6.1.2.1.4.23',

    'ipInReceives' => '1.3.6.1.2.1.4.3',

    'ipInHdrErrors' => '1.3.6.1.2.1.4.4',

    'ipInAddrErrors' => '1.3.6.1.2.1.4.5',

    'ipForwDatagrams' => '1.3.6.1.2.1.4.6',

    'ipInUnknownProtos' => '1.3.6.1.2.1.4.7',

    'ipInDiscards' => '1.3.6.1.2.1.4.8',

    'ipInDelivers' => '1.3.6.1.2.1.4.9',

    'icmp' => '1.3.6.1.2.1.5',

    'icmpInMsgs' => '1.3.6.1.2.1.5.1',

    'icmpInTimestamps' => '1.3.6.1.2.1.5.10',

    'icmpInTimestampReps' => '1.3.6.1.2.1.5.11',

    'icmpInAddrMasks' => '1.3.6.1.2.1.5.12',

    'icmpInAddrMaskReps' => '1.3.6.1.2.1.5.13',

    'icmpOutMsgs' => '1.3.6.1.2.1.5.14',

    'icmpOutErrors' => '1.3.6.1.2.1.5.15',

    'icmpOutDestUnreachs' => '1.3.6.1.2.1.5.16',

    'icmpOutTimeExcds' => '1.3.6.1.2.1.5.17',

    'icmpOutParmProbs' => '1.3.6.1.2.1.5.18',

    'icmpOutSrcQuenchs' => '1.3.6.1.2.1.5.19',

    'icmpInErrors' => '1.3.6.1.2.1.5.2',

    'icmpOutRedirects' => '1.3.6.1.2.1.5.20',

    'icmpOutEchos' => '1.3.6.1.2.1.5.21',

    'icmpOutEchoReps' => '1.3.6.1.2.1.5.22',

    'icmpOutTimestamps' => '1.3.6.1.2.1.5.23',

    'icmpOutTimestampReps' => '1.3.6.1.2.1.5.24',

    'icmpOutAddrMasks' => '1.3.6.1.2.1.5.25',

    'icmpOutAddrMaskReps' => '1.3.6.1.2.1.5.26',

    'icmpInDestUnreachs' => '1.3.6.1.2.1.5.3',

    'icmpInTimeExcds' => '1.3.6.1.2.1.5.4',

    'icmpInParmProbs' => '1.3.6.1.2.1.5.5',

    'icmpInSrcQuenchs' => '1.3.6.1.2.1.5.6',

    'icmpInRedirects' => '1.3.6.1.2.1.5.7',

    'icmpInEchos' => '1.3.6.1.2.1.5.8',

    'icmpInEchoReps' => '1.3.6.1.2.1.5.9',

    'tcp' => '1.3.6.1.2.1.6',

    'tcpRtoAlgorithm' => '1.3.6.1.2.1.6.1',

    'tcpInSegs' => '1.3.6.1.2.1.6.10',

    'tcpOutSegs' => '1.3.6.1.2.1.6.11',

    'tcpRetransSegs' => '1.3.6.1.2.1.6.12',

    'tcpConnTable' => '1.3.6.1.2.1.6.13',

    'tcpConnEntry' => '1.3.6.1.2.1.6.13.1',

    'tcpConnState' => '1.3.6.1.2.1.6.13.1.1',

    'tcpConnLocalAddress' => '1.3.6.1.2.1.6.13.1.2',

    'tcpConnLocalPort' => '1.3.6.1.2.1.6.13.1.3',

    'tcpConnRemAddress' => '1.3.6.1.2.1.6.13.1.4',

    'tcpConnRemPort' => '1.3.6.1.2.1.6.13.1.5',

    'tcpInErrs' => '1.3.6.1.2.1.6.14',

    'tcpOutRsts' => '1.3.6.1.2.1.6.15',

    'tcpRtoMin' => '1.3.6.1.2.1.6.2',

    'tcpRtoMax' => '1.3.6.1.2.1.6.3',

    'tcpMaxConn' => '1.3.6.1.2.1.6.4',

    'tcpActiveOpens' => '1.3.6.1.2.1.6.5',

    'tcpPassiveOpens' => '1.3.6.1.2.1.6.6',

    'tcpAttemptFails' => '1.3.6.1.2.1.6.7',

    'tcpEstabResets' => '1.3.6.1.2.1.6.8',

    'tcpCurrEstab' => '1.3.6.1.2.1.6.9',

    'udp' => '1.3.6.1.2.1.7',

    'udpInDatagrams' => '1.3.6.1.2.1.7.1',

    'udpNoPorts' => '1.3.6.1.2.1.7.2',

    'udpInErrors' => '1.3.6.1.2.1.7.3',

    'udpOutDatagrams' => '1.3.6.1.2.1.7.4',

    'udpTable' => '1.3.6.1.2.1.7.5',

    'udpEntry' => '1.3.6.1.2.1.7.5.1',

    'udpLocalAddress' => '1.3.6.1.2.1.7.5.1.1',

    'udpLocalPort' => '1.3.6.1.2.1.7.5.1.2',

    'egp' => '1.3.6.1.2.1.8',

    'egpInMsgs' => '1.3.6.1.2.1.8.1',

    'egpInErrors' => '1.3.6.1.2.1.8.2',

    'egpOutMsgs' => '1.3.6.1.2.1.8.3',

    'egpOutErrors' => '1.3.6.1.2.1.8.4',

    'egpNeighTable' => '1.3.6.1.2.1.8.5',

    'egpNeighEntry' => '1.3.6.1.2.1.8.5.1',

    'egpNeighState' => '1.3.6.1.2.1.8.5.1.1',

    'egpNeighStateUps' => '1.3.6.1.2.1.8.5.1.10',

    'egpNeighStateDowns' => '1.3.6.1.2.1.8.5.1.11',

    'egpNeighIntervalHello' => '1.3.6.1.2.1.8.5.1.12',

    'egpNeighIntervalPoll' => '1.3.6.1.2.1.8.5.1.13',

    'egpNeighMode' => '1.3.6.1.2.1.8.5.1.14',

    'egpNeighEventTrigger' => '1.3.6.1.2.1.8.5.1.15',

    'egpNeighAddr' => '1.3.6.1.2.1.8.5.1.2',

    'egpNeighAs' => '1.3.6.1.2.1.8.5.1.3',

    'egpNeighInMsgs' => '1.3.6.1.2.1.8.5.1.4',

    'egpNeighInErrs' => '1.3.6.1.2.1.8.5.1.5',

    'egpNeighOutMsgs' => '1.3.6.1.2.1.8.5.1.6',

    'egpNeighOutErrs' => '1.3.6.1.2.1.8.5.1.7',

    'egpNeighInErrMsgs' => '1.3.6.1.2.1.8.5.1.8',

    'egpNeighOutErrMsgs' => '1.3.6.1.2.1.8.5.1.9',

    'egpAs' => '1.3.6.1.2.1.8.6',

    'transmission' => '1.3.6.1.2.1.10',

    'frame-relay' => '1.3.6.1.2.1.10.32',

    'frDlcmiTable' => '1.3.6.1.2.1.10.32.1',

    'frDlcmiEntry' => '1.3.6.1.2.1.10.32.1.1',

    'frDlcmiIfIndex' => '1.3.6.1.2.1.10.32.1.1.1',

    'frDlcmiState' => '1.3.6.1.2.1.10.32.1.1.2',

    'frDlcmiAddress' => '1.3.6.1.2.1.10.32.1.1.3',

    'frDlcmiAddressLen' => '1.3.6.1.2.1.10.32.1.1.4',

    'frDlcmiPollingInterval' => '1.3.6.1.2.1.10.32.1.1.5',

    'frDlcmiFullEnquiryInterval' => '1.3.6.1.2.1.10.32.1.1.6',

    'frDlcmiErrorThreshold' => '1.3.6.1.2.1.10.32.1.1.7',

    'frDlcmiMonitoredEvents' => '1.3.6.1.2.1.10.32.1.1.8',

    'frDlcmiMaxSupportedVCs' => '1.3.6.1.2.1.10.32.1.1.9',

    'frDlcmiMulticast' => '1.3.6.1.2.1.10.32.1.1.10',

    'frCircuitTable' => '1.3.6.1.2.1.10.32.2',

    'frCircuitEntry' => '1.3.6.1.2.1.10.32.2.1',

    'frCircuitIfIndex' => '1.3.6.1.2.1.10.32.2.1.1',

    'frCircuitDlci' => '1.3.6.1.2.1.10.32.2.1.2',

    'frCircuitState' => '1.3.6.1.2.1.10.32.2.1.3',

    'frCircuitReceivedFECNs' => '1.3.6.1.2.1.10.32.2.1.4',

    'frCircuitReceivedBECNs' => '1.3.6.1.2.1.10.32.2.1.5',

    'frCircuitSentFrames' => '1.3.6.1.2.1.10.32.2.1.6',

    'frCircuitSentOctets' => '1.3.6.1.2.1.10.32.2.1.7',

    'frOutOctets' => '1.3.6.1.2.1.10.32.2.1.7',

    'frCircuitReceivedFrames' => '1.3.6.1.2.1.10.32.2.1.8',

    'frCircuitReceivedOctets' => '1.3.6.1.2.1.10.32.2.1.9',

    'frInOctets' => '1.3.6.1.2.1.10.32.2.1.9',

    'frCircuitCreationTime' => '1.3.6.1.2.1.10.32.2.1.10',

    'frCircuitLastTimeChange' => '1.3.6.1.2.1.10.32.2.1.11',

    'frCircuitCommittedBurst' => '1.3.6.1.2.1.10.32.2.1.12',

    'frCircuitExcessBurst' => '1.3.6.1.2.1.10.32.2.1.13',

    'frCircuitThroughput' => '1.3.6.1.2.1.10.32.2.1.14',

    'frErrTable' => '1.3.6.1.2.1.10.32.3',

    'frErrEntry' => '1.3.6.1.2.1.10.32.3.1',

    'frErrIfIndex' => '1.3.6.1.2.1.10.32.3.1.1',

    'frErrType' => '1.3.6.1.2.1.10.32.3.1.2',

    'frErrData' => '1.3.6.1.2.1.10.32.3.1.3',

    'frErrTime' => '1.3.6.1.2.1.10.32.3.1.4',

    'frame-relay-globals' => '1.3.6.1.2.1.10.32.4',

    'frTrapState' => '1.3.6.1.2.1.10.32.4.1',

    'snmp' => '1.3.6.1.2.1.11',

    'snmpInPkts' => '1.3.6.1.2.1.11.1',

    'snmpInBadValues' => '1.3.6.1.2.1.11.10',

    'snmpInReadOnlys' => '1.3.6.1.2.1.11.11',

    'snmpInGenErrs' => '1.3.6.1.2.1.11.12',

    'snmpInTotalReqVars' => '1.3.6.1.2.1.11.13',

    'snmpInTotalSetVars' => '1.3.6.1.2.1.11.14',

    'snmpInGetRequests' => '1.3.6.1.2.1.11.15',

    'snmpInGetNexts' => '1.3.6.1.2.1.11.16',

    'snmpInSetRequests' => '1.3.6.1.2.1.11.17',

    'snmpInGetResponses' => '1.3.6.1.2.1.11.18',

    'snmpInTraps' => '1.3.6.1.2.1.11.19',

    'snmpOutPkts' => '1.3.6.1.2.1.11.2',

    'snmpOutTooBigs' => '1.3.6.1.2.1.11.20',

    'snmpOutNoSuchNames' => '1.3.6.1.2.1.11.21',

    'snmpOutBadValues' => '1.3.6.1.2.1.11.22',

    'snmpOutGenErrs' => '1.3.6.1.2.1.11.24',

    'snmpOutGetRequests' => '1.3.6.1.2.1.11.25',

    'snmpOutGetNexts' => '1.3.6.1.2.1.11.26',

    'snmpOutSetRequests' => '1.3.6.1.2.1.11.27',

    'snmpOutGetResponses' => '1.3.6.1.2.1.11.28',

    'snmpOutTraps' => '1.3.6.1.2.1.11.29',

    'snmpInBadVersions' => '1.3.6.1.2.1.11.3',

    'snmpEnableAuthenTraps' => '1.3.6.1.2.1.11.30',

    'snmpInBadCommunityNames' => '1.3.6.1.2.1.11.4',

    'snmpInBadCommunityUses' => '1.3.6.1.2.1.11.5',

    'snmpInASNParseErrs' => '1.3.6.1.2.1.11.6',

    'snmpInTooBigs' => '1.3.6.1.2.1.11.8',

    'snmpInNoSuchNames' => '1.3.6.1.2.1.11.9',

    'ifName' => '1.3.6.1.2.1.31.1.1.1.1',

    'ifInMulticastPkts' => '1.3.6.1.2.1.31.1.1.1.2',

    'ifInBroadcastPkts' => '1.3.6.1.2.1.31.1.1.1.3',

    'ifOutMulticastPkts' => '1.3.6.1.2.1.31.1.1.1.4',

    'ifOutBroadcastPkts' => '1.3.6.1.2.1.31.1.1.1.5',

    'ifHCInOctets' => '1.3.6.1.2.1.31.1.1.1.6',

    'ifHCInUcastPkts' => '1.3.6.1.2.1.31.1.1.1.7',

    'ifHCInMulticastPkts' => '1.3.6.1.2.1.31.1.1.1.8',

    'ifHCInBroadcastPkts' => '1.3.6.1.2.1.31.1.1.1.9',

    'ifHCOutOctets' => '1.3.6.1.2.1.31.1.1.1.10',

    'ifHCOutUcastPkts' => '1.3.6.1.2.1.31.1.1.1.11',

    'ifHCOutMulticastPkts' => '1.3.6.1.2.1.31.1.1.1.12',

    'ifHCOutBroadcastPkts' => '1.3.6.1.2.1.31.1.1.1.13',

    'ifLinkUpDownTrapEnable' => '1.3.6.1.2.1.31.1.1.1.14',

    'ifHighSpeed' => '1.3.6.1.2.1.31.1.1.1.15',

    'ifPromiscuousMode' => '1.3.6.1.2.1.31.1.1.1.16',

    'ifConnectorPresent' => '1.3.6.1.2.1.31.1.1.1.17',

    'ifAlias' => '1.3.6.1.2.1.31.1.1.1.18',

    'ifCounterDiscontinuityTime' => '1.3.6.1.2.1.31.1.1.1.19',

    'experimental' => '1.3.6.1.3',

    'private' => '1.3.6.1.4',

    'enterprises' => '1.3.6.1.4.1',

  );

# GIL

my %revOIDS = ();	# Reversed %Net_SNMP_util::OIDS hash

my $RevNeeded = 1;

undef $Net_SNMP_util::Host;

undef $Net_SNMP_util::Session;

undef $Net_SNMP_util::Version;

undef $Net_SNMP_util::LHost;

undef $Net_SNMP_util::IPv4only;

undef $Net_SNMP_util::ContextEngineID;

undef $Net_SNMP_util::ContextName;

$Net_SNMP_util::Debug = 0;

$Net_SNMP_util::SuppressWarnings = 0;

$Net_SNMP_util::CacheFile = "OID_cache.txt";

$Net_SNMP_util::CacheLoaded = 0;

$Net_SNMP_util::ReturnArrayRefs = 0;

$Net_SNMP_util::ReturnHashRefs = 0;

$Net_SNMP_util::MaxRepetitions = 12;

### Prototypes

sub snmpget ($@);

sub snmpgetnext ($@);

sub snmpopen ($$$);

sub snmpwalk ($@);

sub snmpwalk_flg ($$@);

sub snmpset ($@);

sub snmptrap ($$$$$@);

sub snmpgetbulk ($$$@);

sub snmpwalkhash ($$@);

sub toOID (@);

sub snmpmapOID (@);

sub snmpMIB_to_OID ($);

sub Check_OID ($);

sub snmpLoad_OID_Cache ($);

sub snmpQueue_MIB_File (@);

sub ASNtype ($);

sub error_msg ($);

sub MIB_fill_OID ($);

sub version () { $VERSION; }

=head1 Option Notes

=over

=item host Parameter

SNMP parameters can be specified as part of the hostname/ip address passed

as the first argument.  The syntax is

    community@host:port:timeout:retries:backoff:version

If the community is left off, it defaults to "public".

If the port is left off, it defaults to 161 for everything but snmptrap().

The snmptrap() routine uses a default port of 162.

Timeout and retries defaults to whatever Net::SNMP uses, currently 5.0 seconds

and 1 retry (2 tries total).

The backoff parameter is currently unimplemented.

The version parameter defaults to SNMP version 1.  Some SNMP values such as

64-bit counters have to be queried using SNMP version 2.  Specifying "2" or

"2c" as the version parameter will accomplish this.  The snmpgetbulk routine

is only supported in SNMP version 2 and higher.  Additional security features

are available under SNMP version 3.

Some machines have additional security features that only allow SNMP

queries to come from certain IP addresses.  If the host doing the query

has multiple interfaces, it may be necessary to specify the interface

the query should come from.  The port parameter is further broken down into

    remote_port!local_address!local_port

Here are some examples:

    somehost

    somehost:161

    somehost:161!192.168.2.4!4000  use 192.168.2.4 and port 4000 as source

    somehost:!192.168.2.4          use 192.168.2.4 as source

    somehost:!!4000                use port 4000 as source

Most people will only need to use the first form ("somehost").

=item OBJECT IDENTIFIERs

To further simplify SNMP queries, the query routines use a small table that

maps the textual representation of OBJECT IDENTIFIERs to their dotted notation.

The OBJECT IDENTIFIERs from RFC1213 (MIB-II) and RFC1315 (Frame Relay) are

preloaded.  This allows OBJECT IDENTIFIERs like "ifInOctets.4" to be used

instead of the more cumbersome "1.3.6.1.2.1.2.2.1.10.4".

Several functions are provided to manage the mapping table.  Mapping entries

can be added directly, SNMP MIB files can be read, and a cache file with the

text-to-OBJECT-IDENTIFIER mappings are maintained.  By default, the file

"OID_cache.txt" is loaded, but it can by changed by setting the variable

$Net_SNMP_util::CacheFile to the desired file name.  The functions to

manipulate the mappings are:

    snmpmapOID			Add a textual OID mapping directly

    snmpMIB_to_OID		Read a SNMP MIB file

    snmpLoad_OID_Cache		Load an OID-mapping cache file

    snmpQueue_MIB_File		Queue a SNMP MIB file for loading on demand

=item Net::SNMP extensions

This module is built on top of Net::SNMP.  Net::SNMP has a different method

of specifying SNMP parameters.  To support this different method, this module

will accept an optional hash reference containing the SNMP parameters. The

hash may contain the following:

	[-port		=> $port,]

	[-localaddr	=> $localaddr,]

	[-localport     => $localport,]

	[-version       => $version,]

	[-domain        => $domain,]

	[-timeout       => $seconds,]

	[-retries       => $count,]

	[-maxmsgsize    => $octets,]

	[-debug         => $bitmask,]

	[-community     => $community,]   # v1/v2c  

	[-username      => $username,]    # v3

	[-authkey	=> $authkey,]     # v3  

	[-authpassword  => $authpasswd,]  # v3  

	[-authprotocol  => $authproto,]   # v3  

	[-privkey       => $privkey,]     # v3  

	[-privpassword  => $privpasswd,]  # v3  

	[-privprotocol  => $privproto,]   # v3

	[-contextengineid => $engine_id,] # v3 

	[-contextname     => $name,]      # v3

Please see the documentation for Net::SNMP for a description of these

parameters.

=item SNMPv3 Arguments

A SNMP context is a collection of management information accessible by a SNMP 

entity.  An item of management information may exist in more than one context 

and a SNMP entity potentially has access to many contexts.  The combination of 

a contextEngineID and a contextName unambiguously identifies a context within 

an administrative domain.  In a SNMPv3 message, the contextEngineID and 

contextName are included as part of the scopedPDU.  All methods that generate 

a SNMP message optionally take a B<-contextengineid> and B<-contextname> 

argument to configure these fields.

=over

=item Context Engine ID

The B<-contextengineid> argument expects a hexadecimal string representing

the desired contextEngineID.  The string must be 10 to 64 characters (5 to 

32 octets) long and can be prefixed with an optional "0x".  Once the 

B<-contextengineid> is specified it stays with the object until it is changed 

again or reset to default by passing in the undefined value.  By default, the 

contextEngineID is set to match the authoritativeEngineID of the authoritative

SNMP engine.

=item Context Name

The contextName is passed as a string which must be 0 to 32 octets in length 

using the B<-contextname> argument.  The contextName stays with the object 

until it is changed.  The contextName defaults to an empty string which 

represents the "default" context.

=back

=back

=cut

# [public methods] ---------------------------------------------------

=head1 Functions

=head2 snmpget() - send a SNMP get-request to the remote agent

    @result = snmpget(

		[community@]host[:port[:timeout[:retries[:backoff[:version]]]]],

		[\%param_hash],

		@oids

	    );

This function performs a SNMP get-request query to gather data from the remote

agent on the host specified.  The message is built using the list of OBJECT

IDENTIFIERs passed as an array.  Each OBJECT IDENTIFIER is placed into a single

SNMP GetRequest-PDU in the same order that it held in the original list.

The requested values are returned in an array in the same order as they were

requested.  In scalar context the first requested value is returned.

=cut

#

# snmpget.

#

sub snmpget ($@) {

  my($host, @vars) = @_;

  my($session, @enoid, %args, $ret, $oid, @retvals);

  @retvals = ();

  $session = &snmpopen($host, 0, \@vars);

  if (!defined($session)) {

    carp "SNMPGET Problem for $host"

      unless ($Net_SNMP_util::SuppressWarnings > 1);

    return wantarray ? @retvals : undef;

  }

  @enoid = &toOID(@vars);

  if ($#enoid < 0) {

    return wantarray ? @retvals : undef;

  }

  $args{'-varbindlist'} = \@enoid;

  if ($Net_SNMP_util::Version > 2) {

    $args{'-contextengineid'} = $Net_SNMP_util::ContextEngineID

      if (defined($Net_SNMP_util::ContextEngineID));

    $args{'-contextname'} = $Net_SNMP_util::ContextName

      if (defined($Net_SNMP_util::ContextName));

  }

  $ret = $session->get_request(%args);

  if ($ret) {

      foreach $oid (@enoid) {

      push @retvals, $ret->{$oid} if (exists($ret->{$oid}));

    }

    return wantarray ? @retvals : $retvals[0];

  }

  $ret = join(' ', @vars);

  error_msg("SNMPGET Problem for $ret on ${host}: " . $session->error());

  return wantarray ? @retvals : undef;

}

=head2 snmpgetnext() - send a SNMP get-next-request to the remote agent

    @result = snmpgetnext(

		[community@]host[:port[:timeout[:retries[:backoff[:version]]]]],

		[\%param_hash],

		@oids

	    );

This function performs a SNMP get-next-request query to gather data from the

remote agent on the host specified.  The message is built using the list of

OBJECT IDENTIFIERs passed as an array.  Each OBJECT IDENTIFIER is placed into a

single SNMP GetNextRequest-PDU in the same order that it held in the original

list.

The requested values are returned in an array in the same order as they were

requested.  The OBJECT IDENTIFIER number is added as a prefix to each value

using a colon as a separator, like '1.3.6.1.2.1.2.2.1.2.1:ethernet'.

In scalar context the first requested value is returned.

=cut

#

# snmpgetnext.

#

sub snmpgetnext ($@) {

  my($host, @vars) = @_;

  my($session, @enoid, %args, $ret, $oid, @retvals);

  @retvals = ();

  $session = &snmpopen($host, 0, \@vars);

  if (!defined($session)) {

    carp "SNMPGETNEXT Problem for $host"

      unless ($Net_SNMP_util::SuppressWarnings > 1);

    return wantarray ? @retvals : undef;

  }

  @enoid = &toOID(@vars);

  if ($#enoid < 0) {

    return wantarray ? @retvals : undef;

  }

  $args{'-varbindlist'} = \@enoid;

  if ($Net_SNMP_util::Version > 2) {

    $args{'-contextengineid'} = $Net_SNMP_util::ContextEngineID

      if (defined($Net_SNMP_util::ContextEngineID));

    $args{'-contextname'} = $Net_SNMP_util::ContextName

      if (defined($Net_SNMP_util::ContextName));

  }

  $ret = $session->get_next_request(%args);

  if ($ret) {

    foreach $oid (@enoid) {

      push @retvals, $oid . ':' . $ret->{$oid} if (exists($ret->{$oid}));

    }

    return wantarray ? @retvals : $retvals[0];

  }

  $ret = join(' ', @vars);

  error_msg("SNMPGETNEXT Problem for $ret on ${host}: " . $session->error());

  return wantarray ? @retvals : undef;

}

=head2 snmpgetbulk() - send a SNMP get-bulk-request to the remote agent

    @result = snmpgetbulk(

		[community@]host[:port[:timeout[:retries[:backoff[:version]]]]],

		$nonrepeaters,

		$maxrepetitions,

		[\%param_hash],

		@oids

	    );

This function performs a SNMP get-bulk-request query to gather data from the

remote agent on the host specified.

=over

=item *

The B<$nonrepeaters> value specifies the number of variables in the @oids list

for which a single successor is to be returned.  If it is null or undefined,

a value of 0 is used.

=item *

The B<$maxrepetitions> value specifies the number of successors to be returned

for the remaining variables in the @oids list.  If it is null or undefined,

the default value of 12 is used.

=item *

The message is built using the list of

OBJECT IDENTIFIERs passed as an array.  Each OBJECT IDENTIFIER is placed into a

single SNMP GetNextRequest-PDU in the same order that it held in the original

list.

=back

The requested values are returned in an array in the same order as they were

requested.

B<NOTE:> This function can only be used when the SNMP version is set to

SNMPv2c or SNMPv3.

=cut

#

# snmpgetbulk.

#

sub snmpgetbulk ($$$@) {

  my($host, $nr, $mr, @vars) = @_;

  my($session, %args, @enoid, $ret);

  my($oid, @retvals);

  @retvals = ();

  $session = &snmpopen($host, 0, \@vars);

  if (!defined($session)) {

    carp "SNMPGETBULK Problem for $host"

      unless ($Net_SNMP_util::SuppressWarnings > 1);

    return @retvals;

  }

  if ($Net_SNMP_util::Version < 2) {

    carp "SNMPGETBULK Problem for $host : must use SNMP version > 1"

      unless ($Net_SNMP_util::SuppressWarnings > 1);

    return @retvals;

  }

  $args{'-nonrepeaters'} = $nr if ($nr > 0);

  $mr = $Net_SNMP_util::MaxRepetitions if ($mr <= 0);

  $args{'-maxrepetitions'} = $mr;

  if ($Net_SNMP_util::Version > 2) {

    $args{'-contextengineid'} = $Net_SNMP_util::ContextEngineID

      if (defined($Net_SNMP_util::ContextEngineID));

    $args{'-contextname'} = $Net_SNMP_util::ContextName

      if (defined($Net_SNMP_util::ContextName));

  }

  @enoid = &toOID(@vars);

  return @retvals if ($#enoid < 0);

  $args{'-varbindlist'} = \@enoid;

  $ret = $session->get_bulk_request(%args);

  if ($ret) {

    @enoid = &Net::SNMP::oid_lex_sort(keys %$ret);

    foreach $oid (@enoid) {

      push @retvals, $oid . ":" . $ret->{$oid};

    }

    return @retvals;

  } else {

    $ret = join(' ', @vars);

    error_msg("SNMPGETBULK Problem for $ret on ${host}: " . $session->error());

    return @retvals;

  }

}

=head2 snmpwalk() - walk OBJECT IDENTIFIER tree(s) on the remote agent

    @result = snmpwalk(

		[community@]host[:port[:timeout[:retries[:backoff[:version]]]]],

		[\%param_hash],

		@oids

	    );

This function performs a sequence of SNMP get-next-request or get-bulk-request

(if the SNMP version is 2 or higher) queries to gather data from the remote

agent on the host specified.  The initial message is built using the list of

OBJECT IDENTIFIERs passed as an array.  Each OBJECT IDENTIFIER is placed into a

single SNMP GetNextRequest-PDU in the same order that it held in the original

list.  Queries continue until all the returned OBJECT IDENTIFIERs are no longer

a child of the base OBJECT IDENTIFIERs.

The requested values are returned in an array in the same order as they were

requested.  The OBJECT IDENTIFIER number is added as a prefix to each value

using a colon as a separator, like '1.3.6.1.2.1.2.2.1.2.1:ethernet'.  If only

one OBJECT IDENTIFIER is requested, just the "instance" part of the OBJECT

IDENTIFIER is added as a prefix, like '1:ethernet', '2:ethernet', '3:fddi'.

=cut

#

# snmpwalk.

#

sub snmpwalk ($@) {

  my($host, @vars) = @_;

  return(&snmpwalk_flg($host, undef, @vars));

}

=head2 snmpset() - send a SNMP set-request to the remote agent

    @result = snmpset(

		[community@]host[:port[:timeout[:retries[:backoff[:version]]]]],

		[\%param_hash],

		$oid1, $type1, $value1,

		[$oid2, $type2, $value2 ...]

	    );

This function is used to modify data on the remote agent using a SNMP

set-request.  The message is built using the list of values consisting of groups

of an OBJECT IDENTIFIER, an object type, and the actual value to be set.

The object type can be one of the following strings:

    integer | int

    string | octetstring | octet string

    oid | object id | object identifier

    ipaddr | ip addr4ess

    timeticks

    uint | uinteger | uinteger32 | unsigned int | unsigned integer | unsigned integer32

    counter | counter 32

    counter64

    gauge | gauge32

The object type may also be an octet corresponding to the ASN.1 type.  See

the Net::SNMP documentation for more information.

The requested values are returned in an array in the same order as they were

requested.  In scalar context the first requested value is returned.

=cut

#

# snmpset.

#

sub snmpset($@) {

  my($host, @vars) = @_;

  my($session, @vals, %args, $ret);

  my($oid, $type, $value, @enoid, @retvals);

  @retvals = ();

  $session = &snmpopen($host, 0, \@vars);

  if (!defined($session)) {

    carp "SNMPSET Problem for $host"

      unless ($Net_SNMP_util::SuppressWarnings > 1);

    return wantarray ? @retvals : undef;

  }

  if ($Net_SNMP_util::Version > 2) {

    $args{'-contextengineid'} = $Net_SNMP_util::ContextEngineID

      if (defined($Net_SNMP_util::ContextEngineID));

    $args{'-contextname'} = $Net_SNMP_util::ContextName

      if (defined($Net_SNMP_util::ContextName));

  }

  while(@vars) {

    ($oid) = toOID((shift @vars));

    $ret   = shift @vars;

    $value = shift @vars;

    $type  = ASNtype($ret);

    if (!defined($type)) {

      carp "Unknown SNMP type: $type\n"

	unless ($Net_SNMP_util::SuppressWarnings > 1);

    }

    push @vals, $oid, $type, $value;

    push @enoid, $oid;

  }

  if ($#vals < 0) {

    return wantarray ? @retvals : undef;

  }

  $args{'-varbindlist'} = \@vals;

  $ret = $session->set_request(%args);

  if ($ret) {

      foreach $oid (@enoid) {

	push @retvals, $ret->{$oid} if (exists($ret->{$oid}));

    }

    return wantarray ? @retvals : $retvals[0];

  }

  $ret = join(' ', @enoid);

  error_msg("SNMPSET Problem for $ret on ${host}: " . $session->error());

  return wantarray ? @retvals : undef;

}

=head2 snmptrap() - send a SNMP trap to the remote manager

    @result = snmptrap(

		[community@]host[:port[:timeout[:retries[:backoff[:version]]]]],

		$enterprise,

		$agentaddr,

		$generictrap,