开通博客赚积分
发布资源赚积分
分类

源码开发语言/平台
当前位置：首页 > 源码/资料 > Internet/网络编程 > SNMP编程 > 查看源码
Net_SNMP_util.pm
资源名称：mrtg-2.13.2.zip　[点击查看]
上传用户：shbosideng
上传日期：2013-05-04
资源大小：1555k
文件大小：63k
源码类别：

SNMP编程

开发平台：

C/C++

Net_SNMP_util.pm：源码内容
  1. ### - *- mode: Perl -*-
  2. ######################################################################
  3. ### Net_SNMP_util -- SNMP utilities using Net::SNMP
  4. ######################################################################
  5. ### Copyright (c) 2005, Mike Mitchell.
  6. ###
  7. ### This program is free software; you can redistribute it under the
  8. ### "Artistic License" included in this distribution (file "Artistic").
  9. ######################################################################
  10. ### Created by:  Mike Mitchell   <Mike.Mitchell@sas.com>
  11. ###
  12. ### Contributions and fixes by:
  13. ###
  14. ### Laszlo Herczeg <laszlo.herczeg@austinenergy.com>
  15. ### ignore unimplemented SNMP_Session.pm options
  16. ######################################################################
  18. package Net_SNMP_util;
  20. =head1 NAME
  22. Net_SNMP_util - SNMP utilities based on Net::SNMP
  24. =head1 SYNOPSIS
  26. The Net_SNMP_util module implements SNMP utilities using the Net::SNMP module.
  27. It implements snmpget, snmpgetnext, snmpwalk, snmpset, snmptrap, and
  28. snmpgetbulk.  The Net_SNMP_util module assumes that the user has a basic
  29. understanding of the Simple Network Management Protocol and related network
  30. management concepts.
  32. =head1 DESCRIPTION
  34. The Net_SNMP_util module simplifies SNMP queries even more than Net::SNMP  
  35. alone.  Easy-to-use "get", "getnext", "walk", "set", "trap", and "getbulk"
  36. routines are provided, hiding all the details of a SNMP query.
  38. =cut
  40. # ==========================================================================
  42. use strict;
  44. ## Validate the version of Perl
  46. BEGIN
  47. {
  48.     die('Perl version 5.6.0 or greater is required') if ($] < 5.006);
  49. }
  51. ## Handle importing/exporting of symbols
  53. use vars qw( @ISA @EXPORT $VERSION );
  54. use Exporter;
  56. our @ISA = qw( Exporter );
  58. our @EXPORT = qw(
  59.     snmpget snmpgetnext snmpwalk snmpset snmptrap snmpgetbulk snmpmaptable
  60.     snmpmaptable4 snmpwalkhash snmpmapOID snmpMIB_to_OID snmpLoad_OID_Cache
  61.     snmpQueue_MIB_File
  62. );
  64. ## Version of the Net_SNMP_util module
  66. our $VERSION = v1.0.5;
  68. use Carp;
  70. use Net::SNMP v5.0;
  72. # The OID numbers from RFC1213 (MIB-II) and RFC1315 (Frame Relay)
  73. # are pre-loaded below.
  74. %Net_SNMP_util::OIDS = 
  75.   (
  76.     'iso' => '1',
  77.     'org' => '1.3',
  78.     'dod' => '1.3.6',
  79.     'internet' => '1.3.6.1',
  80.     'directory' => '1.3.6.1.1',
  81.     'mgmt' => '1.3.6.1.2',
  82.     'mib-2' => '1.3.6.1.2.1',
  83.     'system' => '1.3.6.1.2.1.1',
  84.     'sysDescr' => '1.3.6.1.2.1.1.1.0',
  85.     'sysObjectID' => '1.3.6.1.2.1.1.2.0',
  86.     'sysUpTime' => '1.3.6.1.2.1.1.3.0',
  87.     'sysUptime' => '1.3.6.1.2.1.1.3.0',
  88.     'sysContact' => '1.3.6.1.2.1.1.4.0',
  89.     'sysName' => '1.3.6.1.2.1.1.5.0',
  90.     'sysLocation' => '1.3.6.1.2.1.1.6.0',
  91.     'sysServices' => '1.3.6.1.2.1.1.7.0',
  92.     'interfaces' => '1.3.6.1.2.1.2',
  93.     'ifNumber' => '1.3.6.1.2.1.2.1.0',
  94.     'ifTable' => '1.3.6.1.2.1.2.2',
  95.     'ifEntry' => '1.3.6.1.2.1.2.2.1',
  96.     'ifIndex' => '1.3.6.1.2.1.2.2.1.1',
  97.     'ifInOctets' => '1.3.6.1.2.1.2.2.1.10',
  98.     'ifInUcastPkts' => '1.3.6.1.2.1.2.2.1.11',
  99.     'ifInNUcastPkts' => '1.3.6.1.2.1.2.2.1.12',
  100.     'ifInDiscards' => '1.3.6.1.2.1.2.2.1.13',
  101.     'ifInErrors' => '1.3.6.1.2.1.2.2.1.14',
  102.     'ifInUnknownProtos' => '1.3.6.1.2.1.2.2.1.15',
  103.     'ifOutOctets' => '1.3.6.1.2.1.2.2.1.16',
  104.     'ifOutUcastPkts' => '1.3.6.1.2.1.2.2.1.17',
  105.     'ifOutNUcastPkts' => '1.3.6.1.2.1.2.2.1.18',
  106.     'ifOutDiscards' => '1.3.6.1.2.1.2.2.1.19',
  107.     'ifDescr' => '1.3.6.1.2.1.2.2.1.2',
  108.     'ifOutErrors' => '1.3.6.1.2.1.2.2.1.20',
  109.     'ifOutQLen' => '1.3.6.1.2.1.2.2.1.21',
  110.     'ifSpecific' => '1.3.6.1.2.1.2.2.1.22',
  111.     'ifType' => '1.3.6.1.2.1.2.2.1.3',
  112.     'ifMtu' => '1.3.6.1.2.1.2.2.1.4',
  113.     'ifSpeed' => '1.3.6.1.2.1.2.2.1.5',
  114.     'ifPhysAddress' => '1.3.6.1.2.1.2.2.1.6',
  115.     'ifAdminHack' => '1.3.6.1.2.1.2.2.1.7',  
  116.     'ifAdminStatus' => '1.3.6.1.2.1.2.2.1.7',
  117.     'ifOperHack' => '1.3.6.1.2.1.2.2.1.8',             
  118.     'ifOperStatus' => '1.3.6.1.2.1.2.2.1.8',
  119.     'ifLastChange' => '1.3.6.1.2.1.2.2.1.9',
  120.     'at' => '1.3.6.1.2.1.3',
  121.     'atTable' => '1.3.6.1.2.1.3.1',
  122.     'atEntry' => '1.3.6.1.2.1.3.1.1',
  123.     'atIfIndex' => '1.3.6.1.2.1.3.1.1.1',
  124.     'atPhysAddress' => '1.3.6.1.2.1.3.1.1.2',
  125.     'atNetAddress' => '1.3.6.1.2.1.3.1.1.3',
  126.     'ip' => '1.3.6.1.2.1.4',
  127.     'ipForwarding' => '1.3.6.1.2.1.4.1',
  128.     'ipOutRequests' => '1.3.6.1.2.1.4.10',
  129.     'ipOutDiscards' => '1.3.6.1.2.1.4.11',
  130.     'ipOutNoRoutes' => '1.3.6.1.2.1.4.12',
  131.     'ipReasmTimeout' => '1.3.6.1.2.1.4.13',
  132.     'ipReasmReqds' => '1.3.6.1.2.1.4.14',
  133.     'ipReasmOKs' => '1.3.6.1.2.1.4.15',
  134.     'ipReasmFails' => '1.3.6.1.2.1.4.16',
  135.     'ipFragOKs' => '1.3.6.1.2.1.4.17',
  136.     'ipFragFails' => '1.3.6.1.2.1.4.18',
  137.     'ipFragCreates' => '1.3.6.1.2.1.4.19',
  138.     'ipDefaultTTL' => '1.3.6.1.2.1.4.2',
  139.     'ipAddrTable' => '1.3.6.1.2.1.4.20',
  140.     'ipAddrEntry' => '1.3.6.1.2.1.4.20.1',
  141.     'ipAdEntAddr' => '1.3.6.1.2.1.4.20.1.1',
  142.     'ipAdEntIfIndex' => '1.3.6.1.2.1.4.20.1.2',
  143.     'ipAdEntNetMask' => '1.3.6.1.2.1.4.20.1.3',
  144.     'ipAdEntBcastAddr' => '1.3.6.1.2.1.4.20.1.4',
  145.     'ipAdEntReasmMaxSize' => '1.3.6.1.2.1.4.20.1.5',
  146.     'ipRouteTable' => '1.3.6.1.2.1.4.21',
  147.     'ipRouteEntry' => '1.3.6.1.2.1.4.21.1',
  148.     'ipRouteDest' => '1.3.6.1.2.1.4.21.1.1',
  149.     'ipRouteAge' => '1.3.6.1.2.1.4.21.1.10',
  150.     'ipRouteMask' => '1.3.6.1.2.1.4.21.1.11',
  151.     'ipRouteMetric5' => '1.3.6.1.2.1.4.21.1.12',
  152.     'ipRouteInfo' => '1.3.6.1.2.1.4.21.1.13',
  153.     'ipRouteIfIndex' => '1.3.6.1.2.1.4.21.1.2',
  154.     'ipRouteMetric1' => '1.3.6.1.2.1.4.21.1.3',
  155.     'ipRouteMetric2' => '1.3.6.1.2.1.4.21.1.4',
  156.     'ipRouteMetric3' => '1.3.6.1.2.1.4.21.1.5',
  157.     'ipRouteMetric4' => '1.3.6.1.2.1.4.21.1.6',
  158.     'ipRouteNextHop' => '1.3.6.1.2.1.4.21.1.7',
  159.     'ipRouteType' => '1.3.6.1.2.1.4.21.1.8',
  160.     'ipRouteProto' => '1.3.6.1.2.1.4.21.1.9',
  161.     'ipNetToMediaTable' => '1.3.6.1.2.1.4.22',
  162.     'ipNetToMediaEntry' => '1.3.6.1.2.1.4.22.1',
  163.     'ipNetToMediaIfIndex' => '1.3.6.1.2.1.4.22.1.1',
  164.     'ipNetToMediaPhysAddress' => '1.3.6.1.2.1.4.22.1.2',
  165.     'ipNetToMediaNetAddress' => '1.3.6.1.2.1.4.22.1.3',
  166.     'ipNetToMediaType' => '1.3.6.1.2.1.4.22.1.4',
  167.     'ipRoutingDiscards' => '1.3.6.1.2.1.4.23',
  168.     'ipInReceives' => '1.3.6.1.2.1.4.3',
  169.     'ipInHdrErrors' => '1.3.6.1.2.1.4.4',
  170.     'ipInAddrErrors' => '1.3.6.1.2.1.4.5',
  171.     'ipForwDatagrams' => '1.3.6.1.2.1.4.6',
  172.     'ipInUnknownProtos' => '1.3.6.1.2.1.4.7',
  173.     'ipInDiscards' => '1.3.6.1.2.1.4.8',
  174.     'ipInDelivers' => '1.3.6.1.2.1.4.9',
  175.     'icmp' => '1.3.6.1.2.1.5',
  176.     'icmpInMsgs' => '1.3.6.1.2.1.5.1',
  177.     'icmpInTimestamps' => '1.3.6.1.2.1.5.10',
  178.     'icmpInTimestampReps' => '1.3.6.1.2.1.5.11',
  179.     'icmpInAddrMasks' => '1.3.6.1.2.1.5.12',
  180.     'icmpInAddrMaskReps' => '1.3.6.1.2.1.5.13',
  181.     'icmpOutMsgs' => '1.3.6.1.2.1.5.14',
  182.     'icmpOutErrors' => '1.3.6.1.2.1.5.15',
  183.     'icmpOutDestUnreachs' => '1.3.6.1.2.1.5.16',
  184.     'icmpOutTimeExcds' => '1.3.6.1.2.1.5.17',
  185.     'icmpOutParmProbs' => '1.3.6.1.2.1.5.18',
  186.     'icmpOutSrcQuenchs' => '1.3.6.1.2.1.5.19',
  187.     'icmpInErrors' => '1.3.6.1.2.1.5.2',
  188.     'icmpOutRedirects' => '1.3.6.1.2.1.5.20',
  189.     'icmpOutEchos' => '1.3.6.1.2.1.5.21',
  190.     'icmpOutEchoReps' => '1.3.6.1.2.1.5.22',
  191.     'icmpOutTimestamps' => '1.3.6.1.2.1.5.23',
  192.     'icmpOutTimestampReps' => '1.3.6.1.2.1.5.24',
  193.     'icmpOutAddrMasks' => '1.3.6.1.2.1.5.25',
  194.     'icmpOutAddrMaskReps' => '1.3.6.1.2.1.5.26',
  195.     'icmpInDestUnreachs' => '1.3.6.1.2.1.5.3',
  196.     'icmpInTimeExcds' => '1.3.6.1.2.1.5.4',
  197.     'icmpInParmProbs' => '1.3.6.1.2.1.5.5',
  198.     'icmpInSrcQuenchs' => '1.3.6.1.2.1.5.6',
  199.     'icmpInRedirects' => '1.3.6.1.2.1.5.7',
  200.     'icmpInEchos' => '1.3.6.1.2.1.5.8',
  201.     'icmpInEchoReps' => '1.3.6.1.2.1.5.9',
  202.     'tcp' => '1.3.6.1.2.1.6',
  203.     'tcpRtoAlgorithm' => '1.3.6.1.2.1.6.1',
  204.     'tcpInSegs' => '1.3.6.1.2.1.6.10',
  205.     'tcpOutSegs' => '1.3.6.1.2.1.6.11',
  206.     'tcpRetransSegs' => '1.3.6.1.2.1.6.12',
  207.     'tcpConnTable' => '1.3.6.1.2.1.6.13',
  208.     'tcpConnEntry' => '1.3.6.1.2.1.6.13.1',
  209.     'tcpConnState' => '1.3.6.1.2.1.6.13.1.1',
  210.     'tcpConnLocalAddress' => '1.3.6.1.2.1.6.13.1.2',
  211.     'tcpConnLocalPort' => '1.3.6.1.2.1.6.13.1.3',
  212.     'tcpConnRemAddress' => '1.3.6.1.2.1.6.13.1.4',
  213.     'tcpConnRemPort' => '1.3.6.1.2.1.6.13.1.5',
  214.     'tcpInErrs' => '1.3.6.1.2.1.6.14',
  215.     'tcpOutRsts' => '1.3.6.1.2.1.6.15',
  216.     'tcpRtoMin' => '1.3.6.1.2.1.6.2',
  217.     'tcpRtoMax' => '1.3.6.1.2.1.6.3',
  218.     'tcpMaxConn' => '1.3.6.1.2.1.6.4',
  219.     'tcpActiveOpens' => '1.3.6.1.2.1.6.5',
  220.     'tcpPassiveOpens' => '1.3.6.1.2.1.6.6',
  221.     'tcpAttemptFails' => '1.3.6.1.2.1.6.7',
  222.     'tcpEstabResets' => '1.3.6.1.2.1.6.8',
  223.     'tcpCurrEstab' => '1.3.6.1.2.1.6.9',
  224.     'udp' => '1.3.6.1.2.1.7',
  225.     'udpInDatagrams' => '1.3.6.1.2.1.7.1',
  226.     'udpNoPorts' => '1.3.6.1.2.1.7.2',
  227.     'udpInErrors' => '1.3.6.1.2.1.7.3',
  228.     'udpOutDatagrams' => '1.3.6.1.2.1.7.4',
  229.     'udpTable' => '1.3.6.1.2.1.7.5',
  230.     'udpEntry' => '1.3.6.1.2.1.7.5.1',
  231.     'udpLocalAddress' => '1.3.6.1.2.1.7.5.1.1',
  232.     'udpLocalPort' => '1.3.6.1.2.1.7.5.1.2',
  233.     'egp' => '1.3.6.1.2.1.8',
  234.     'egpInMsgs' => '1.3.6.1.2.1.8.1',
  235.     'egpInErrors' => '1.3.6.1.2.1.8.2',
  236.     'egpOutMsgs' => '1.3.6.1.2.1.8.3',
  237.     'egpOutErrors' => '1.3.6.1.2.1.8.4',
  238.     'egpNeighTable' => '1.3.6.1.2.1.8.5',
  239.     'egpNeighEntry' => '1.3.6.1.2.1.8.5.1',
  240.     'egpNeighState' => '1.3.6.1.2.1.8.5.1.1',
  241.     'egpNeighStateUps' => '1.3.6.1.2.1.8.5.1.10',
  242.     'egpNeighStateDowns' => '1.3.6.1.2.1.8.5.1.11',
  243.     'egpNeighIntervalHello' => '1.3.6.1.2.1.8.5.1.12',
  244.     'egpNeighIntervalPoll' => '1.3.6.1.2.1.8.5.1.13',
  245.     'egpNeighMode' => '1.3.6.1.2.1.8.5.1.14',
  246.     'egpNeighEventTrigger' => '1.3.6.1.2.1.8.5.1.15',
  247.     'egpNeighAddr' => '1.3.6.1.2.1.8.5.1.2',
  248.     'egpNeighAs' => '1.3.6.1.2.1.8.5.1.3',
  249.     'egpNeighInMsgs' => '1.3.6.1.2.1.8.5.1.4',
  250.     'egpNeighInErrs' => '1.3.6.1.2.1.8.5.1.5',
  251.     'egpNeighOutMsgs' => '1.3.6.1.2.1.8.5.1.6',
  252.     'egpNeighOutErrs' => '1.3.6.1.2.1.8.5.1.7',
  253.     'egpNeighInErrMsgs' => '1.3.6.1.2.1.8.5.1.8',
  254.     'egpNeighOutErrMsgs' => '1.3.6.1.2.1.8.5.1.9',
  255.     'egpAs' => '1.3.6.1.2.1.8.6',
  256.     'transmission' => '1.3.6.1.2.1.10',
  257.     'frame-relay' => '1.3.6.1.2.1.10.32',
  258.     'frDlcmiTable' => '1.3.6.1.2.1.10.32.1',
  259.     'frDlcmiEntry' => '1.3.6.1.2.1.10.32.1.1',
  260.     'frDlcmiIfIndex' => '1.3.6.1.2.1.10.32.1.1.1',
  261.     'frDlcmiState' => '1.3.6.1.2.1.10.32.1.1.2',
  262.     'frDlcmiAddress' => '1.3.6.1.2.1.10.32.1.1.3',
  263.     'frDlcmiAddressLen' => '1.3.6.1.2.1.10.32.1.1.4',
  264.     'frDlcmiPollingInterval' => '1.3.6.1.2.1.10.32.1.1.5',
  265.     'frDlcmiFullEnquiryInterval' => '1.3.6.1.2.1.10.32.1.1.6',
  266.     'frDlcmiErrorThreshold' => '1.3.6.1.2.1.10.32.1.1.7',
  267.     'frDlcmiMonitoredEvents' => '1.3.6.1.2.1.10.32.1.1.8',
  268.     'frDlcmiMaxSupportedVCs' => '1.3.6.1.2.1.10.32.1.1.9',
  269.     'frDlcmiMulticast' => '1.3.6.1.2.1.10.32.1.1.10',
  270.     'frCircuitTable' => '1.3.6.1.2.1.10.32.2',
  271.     'frCircuitEntry' => '1.3.6.1.2.1.10.32.2.1',
  272.     'frCircuitIfIndex' => '1.3.6.1.2.1.10.32.2.1.1',
  273.     'frCircuitDlci' => '1.3.6.1.2.1.10.32.2.1.2',
  274.     'frCircuitState' => '1.3.6.1.2.1.10.32.2.1.3',
  275.     'frCircuitReceivedFECNs' => '1.3.6.1.2.1.10.32.2.1.4',
  276.     'frCircuitReceivedBECNs' => '1.3.6.1.2.1.10.32.2.1.5',
  277.     'frCircuitSentFrames' => '1.3.6.1.2.1.10.32.2.1.6',
  278.     'frCircuitSentOctets' => '1.3.6.1.2.1.10.32.2.1.7',
  279.     'frOutOctets' => '1.3.6.1.2.1.10.32.2.1.7',
  280.     'frCircuitReceivedFrames' => '1.3.6.1.2.1.10.32.2.1.8',
  281.     'frCircuitReceivedOctets' => '1.3.6.1.2.1.10.32.2.1.9',
  282.     'frInOctets' => '1.3.6.1.2.1.10.32.2.1.9',
  283.     'frCircuitCreationTime' => '1.3.6.1.2.1.10.32.2.1.10',
  284.     'frCircuitLastTimeChange' => '1.3.6.1.2.1.10.32.2.1.11',
  285.     'frCircuitCommittedBurst' => '1.3.6.1.2.1.10.32.2.1.12',
  286.     'frCircuitExcessBurst' => '1.3.6.1.2.1.10.32.2.1.13',
  287.     'frCircuitThroughput' => '1.3.6.1.2.1.10.32.2.1.14',
  288.     'frErrTable' => '1.3.6.1.2.1.10.32.3',
  289.     'frErrEntry' => '1.3.6.1.2.1.10.32.3.1',
  290.     'frErrIfIndex' => '1.3.6.1.2.1.10.32.3.1.1',
  291.     'frErrType' => '1.3.6.1.2.1.10.32.3.1.2',
  292.     'frErrData' => '1.3.6.1.2.1.10.32.3.1.3',
  293.     'frErrTime' => '1.3.6.1.2.1.10.32.3.1.4',
  294.     'frame-relay-globals' => '1.3.6.1.2.1.10.32.4',
  295.     'frTrapState' => '1.3.6.1.2.1.10.32.4.1',
  296.     'snmp' => '1.3.6.1.2.1.11',
  297.     'snmpInPkts' => '1.3.6.1.2.1.11.1',
  298.     'snmpInBadValues' => '1.3.6.1.2.1.11.10',
  299.     'snmpInReadOnlys' => '1.3.6.1.2.1.11.11',
  300.     'snmpInGenErrs' => '1.3.6.1.2.1.11.12',
  301.     'snmpInTotalReqVars' => '1.3.6.1.2.1.11.13',
  302.     'snmpInTotalSetVars' => '1.3.6.1.2.1.11.14',
  303.     'snmpInGetRequests' => '1.3.6.1.2.1.11.15',
  304.     'snmpInGetNexts' => '1.3.6.1.2.1.11.16',
  305.     'snmpInSetRequests' => '1.3.6.1.2.1.11.17',
  306.     'snmpInGetResponses' => '1.3.6.1.2.1.11.18',
  307.     'snmpInTraps' => '1.3.6.1.2.1.11.19',
  308.     'snmpOutPkts' => '1.3.6.1.2.1.11.2',
  309.     'snmpOutTooBigs' => '1.3.6.1.2.1.11.20',
  310.     'snmpOutNoSuchNames' => '1.3.6.1.2.1.11.21',
  311.     'snmpOutBadValues' => '1.3.6.1.2.1.11.22',
  312.     'snmpOutGenErrs' => '1.3.6.1.2.1.11.24',
  313.     'snmpOutGetRequests' => '1.3.6.1.2.1.11.25',
  314.     'snmpOutGetNexts' => '1.3.6.1.2.1.11.26',
  315.     'snmpOutSetRequests' => '1.3.6.1.2.1.11.27',
  316.     'snmpOutGetResponses' => '1.3.6.1.2.1.11.28',
  317.     'snmpOutTraps' => '1.3.6.1.2.1.11.29',
  318.     'snmpInBadVersions' => '1.3.6.1.2.1.11.3',
  319.     'snmpEnableAuthenTraps' => '1.3.6.1.2.1.11.30',
  320.     'snmpInBadCommunityNames' => '1.3.6.1.2.1.11.4',
  321.     'snmpInBadCommunityUses' => '1.3.6.1.2.1.11.5',
  322.     'snmpInASNParseErrs' => '1.3.6.1.2.1.11.6',
  323.     'snmpInTooBigs' => '1.3.6.1.2.1.11.8',
  324.     'snmpInNoSuchNames' => '1.3.6.1.2.1.11.9',
  325.     'ifName' => '1.3.6.1.2.1.31.1.1.1.1',
  326.     'ifInMulticastPkts' => '1.3.6.1.2.1.31.1.1.1.2',
  327.     'ifInBroadcastPkts' => '1.3.6.1.2.1.31.1.1.1.3',
  328.     'ifOutMulticastPkts' => '1.3.6.1.2.1.31.1.1.1.4',
  329.     'ifOutBroadcastPkts' => '1.3.6.1.2.1.31.1.1.1.5',
  330.     'ifHCInOctets' => '1.3.6.1.2.1.31.1.1.1.6',
  331.     'ifHCInUcastPkts' => '1.3.6.1.2.1.31.1.1.1.7',
  332.     'ifHCInMulticastPkts' => '1.3.6.1.2.1.31.1.1.1.8',
  333.     'ifHCInBroadcastPkts' => '1.3.6.1.2.1.31.1.1.1.9',
  334.     'ifHCOutOctets' => '1.3.6.1.2.1.31.1.1.1.10',
  335.     'ifHCOutUcastPkts' => '1.3.6.1.2.1.31.1.1.1.11',
  336.     'ifHCOutMulticastPkts' => '1.3.6.1.2.1.31.1.1.1.12',
  337.     'ifHCOutBroadcastPkts' => '1.3.6.1.2.1.31.1.1.1.13',
  338.     'ifLinkUpDownTrapEnable' => '1.3.6.1.2.1.31.1.1.1.14',
  339.     'ifHighSpeed' => '1.3.6.1.2.1.31.1.1.1.15',
  340.     'ifPromiscuousMode' => '1.3.6.1.2.1.31.1.1.1.16',
  341.     'ifConnectorPresent' => '1.3.6.1.2.1.31.1.1.1.17',
  342.     'ifAlias' => '1.3.6.1.2.1.31.1.1.1.18',
  343.     'ifCounterDiscontinuityTime' => '1.3.6.1.2.1.31.1.1.1.19',
  344.     'experimental' => '1.3.6.1.3',
  345.     'private' => '1.3.6.1.4',
  346.     'enterprises' => '1.3.6.1.4.1',
  347.   );
  349. # GIL
  350. my %revOIDS = (); # Reversed %Net_SNMP_util::OIDS hash
  351. my $RevNeeded = 1;
  353. undef $Net_SNMP_util::Host;
  354. undef $Net_SNMP_util::Session;
  355. undef $Net_SNMP_util::Version;
  356. undef $Net_SNMP_util::LHost;
  357. undef $Net_SNMP_util::IPv4only;
  358. undef $Net_SNMP_util::ContextEngineID;
  359. undef $Net_SNMP_util::ContextName;
  360. $Net_SNMP_util::Debug = 0;
  361. $Net_SNMP_util::SuppressWarnings = 0;
  362. $Net_SNMP_util::CacheFile = "OID_cache.txt";
  363. $Net_SNMP_util::CacheLoaded = 0;
  364. $Net_SNMP_util::ReturnArrayRefs = 0;
  365. $Net_SNMP_util::ReturnHashRefs = 0;
  366. $Net_SNMP_util::MaxRepetitions = 12;
  368. ### Prototypes
  369. sub snmpget ($@);
  370. sub snmpgetnext ($@);
  371. sub snmpopen ($$$);
  372. sub snmpwalk ($@);
  373. sub snmpwalk_flg ($$@);
  374. sub snmpset ($@);
  375. sub snmptrap ($$$$$@);
  376. sub snmpgetbulk ($$$@);
  377. sub snmpwalkhash ($$@);
  378. sub toOID (@);
  379. sub snmpmapOID (@);
  380. sub snmpMIB_to_OID ($);
  381. sub Check_OID ($);
  382. sub snmpLoad_OID_Cache ($);
  383. sub snmpQueue_MIB_File (@);
  384. sub ASNtype ($);
  386. sub version () { $VERSION; }
  388. =head1 Option Notes
  390. =over
  392. =item host Parameter
  394. SNMP parameters can be specified as part of the hostname/ip address passed
  395. as the first argument.  The syntax is
  397.     community@host:port:timeout:retries:backoff:version
  399. If the community is left off, it defaults to "public".
  400. If the port is left off, it defaults to 161 for everything but snmptrap().
  401. The snmptrap() routine uses a default port of 162.
  402. Timeout and retries defaults to whatever Net::SNMP uses, currently 5.0 seconds
  403. and 1 retry (2 tries total).
  404. The backoff parameter is currently unimplemented.
  405. The version parameter defaults to SNMP version 1.  Some SNMP values such as
  406. 64-bit counters have to be queried using SNMP version 2.  Specifying "2" or
  407. "2c" as the version parameter will accomplish this.  The snmpgetbulk routine
  408. is only supported in SNMP version 2 and higher.  Additional security features
  409. are available under SNMP version 3.
  411. Some machines have additional security features that only allow SNMP
  412. queries to come from certain IP addresses.  If the host doing the query
  413. has multiple interfaces, it may be necessary to specify the interface
  414. the query should come from.  The port parameter is further broken down into
  416.     remote_port!local_address!local_port
  418. Here are some examples:
  420.     somehost
  421.     somehost:161
  422.     somehost:161!192.168.2.4!4000  use 192.168.2.4 and port 4000 as source
  423.     somehost:!192.168.2.4          use 192.168.2.4 as source
  424.     somehost:!!4000                use port 4000 as source
  426. Most people will only need to use the first form ("somehost").
  428. =item OBJECT IDENTIFIERs
  430. To further simplify SNMP queries, the query routines use a small table that
  431. maps the textual representation of OBJECT IDENTIFIERs to their dotted notation.
  432. The OBJECT IDENTIFIERs from RFC1213 (MIB-II) and RFC1315 (Frame Relay) are
  433. preloaded.  This allows OBJECT IDENTIFIERs like "ifInOctets.4" to be used
  434. instead of the more cumbersome "1.3.6.1.2.1.2.2.1.10.4".
  436. Several functions are provided to manage the mapping table.  Mapping entries
  437. can be added directly, SNMP MIB files can be read, and a cache file with the
  438. text-to-OBJECT-IDENTIFIER mappings are maintained.  By default, the file
  439. "OID_cache.txt" is loaded, but it can by changed by setting the variable
  440. $Net_SNMP_util::CacheFile to the desired file name.  The functions to
  441. manipulate the mappings are:
  443.     snmpmapOID Add a textual OID mapping directly
  444.     snmpMIB_to_OID Read a SNMP MIB file
  445.     snmpLoad_OID_Cache Load an OID-mapping cache file
  446.     snmpQueue_MIB_File Queue a SNMP MIB file for loading on demand
  448. =item Net::SNMP extensions
  450. This module is built on top of Net::SNMP.  Net::SNMP has a different method
  451. of specifying SNMP parameters.  To support this different method, this module
  452. will accept an optional hash reference containing the SNMP parameters. The
  453. hash may contain the following:
  455. [-port => $port,]
  456. [-localaddr => $localaddr,]
  457. [-localport     => $localport,]
  458. [-version       => $version,]
  459. [-domain        => $domain,]
  460. [-timeout       => $seconds,]
  461. [-retries       => $count,]
  462. [-maxmsgsize    => $octets,]
  463. [-debug         => $bitmask,]
  464. [-community     => $community,]   # v1/v2c  
  465. [-username      => $username,]    # v3
  466. [-authkey => $authkey,]     # v3  
  467. [-authpassword  => $authpasswd,]  # v3  
  468. [-authprotocol  => $authproto,]   # v3  
  469. [-privkey       => $privkey,]     # v3  
  470. [-privpassword  => $privpasswd,]  # v3  
  471. [-privprotocol  => $privproto,]   # v3
  472. [-contextengineid => $engine_id,] # v3 
  473. [-contextname     => $name,]      # v3
  475. Please see the documentation for Net::SNMP for a description of these
  476. parameters.
  478. =item SNMPv3 Arguments
  480. A SNMP context is a collection of management information accessible by a SNMP 
  481. entity.  An item of management information may exist in more than one context 
  482. and a SNMP entity potentially has access to many contexts.  The combination of 
  483. a contextEngineID and a contextName unambiguously identifies a context within 
  484. an administrative domain.  In a SNMPv3 message, the contextEngineID and 
  485. contextName are included as part of the scopedPDU.  All methods that generate 
  486. a SNMP message optionally take a B<-contextengineid> and B<-contextname> 
  487. argument to configure these fields.
  489. =over
  491. =item Context Engine ID
  493. The B<-contextengineid> argument expects a hexadecimal string representing
  494. the desired contextEngineID.  The string must be 10 to 64 characters (5 to 
  495. 32 octets) long and can be prefixed with an optional "0x".  Once the 
  496. B<-contextengineid> is specified it stays with the object until it is changed 
  497. again or reset to default by passing in the undefined value.  By default, the 
  498. contextEngineID is set to match the authoritativeEngineID of the authoritative
  499. SNMP engine.
  501. =item Context Name
  503. The contextName is passed as a string which must be 0 to 32 octets in length 
  504. using the B<-contextname> argument.  The contextName stays with the object 
  505. until it is changed.  The contextName defaults to an empty string which 
  506. represents the "default" context.
  508. =back
  510. =back
  512. =cut
  514. # [public methods] ---------------------------------------------------
  516. =head1 Functions
  518. =head2 snmpget() - send a SNMP get-request to the remote agent
  520.     @result = snmpget(
  521. [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
  522. [%param_hash],
  523. @oids
  524.     );
  526. This function performs a SNMP get-request query to gather data from the remote
  527. agent on the host specified.  The message is built using the list of OBJECT
  528. IDENTIFIERs passed as an array.  Each OBJECT IDENTIFIER is placed into a single
  529. SNMP GetRequest-PDU in the same order that it held in the original list.
  531. The requested values are returned in an array in the same order as they were
  532. requested.  In scalar context the first requested value is returned.
  534. =cut
  536. #
  537. # snmpget.
  538. #
  539. sub snmpget ($@) {
  540.   my($host, @vars) = @_;
  541.   my($session, @enoid, %args, $ret, $oid, @retvals);
  543.   $session = &snmpopen($host, 0, @vars);
  544.   if (!defined($session)) {
  545.     carp "SNMPGET Problem for $host"
  546.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  547.     return undef;
  548.   }
  550.   @enoid = &toOID(@vars);
  551.   return undef unless defined $enoid[0];
  553.   $args{'-varbindlist'} = @enoid;
  554.   if ($Net_SNMP_util::Version > 2) {
  555.     $args{'-contextengineid'} = $Net_SNMP_util::ContextEngineID
  556.       if (defined($Net_SNMP_util::ContextEngineID));
  557.     $args{'-contextname'} = $Net_SNMP_util::ContextName
  558.       if (defined($Net_SNMP_util::ContextName));
  559.   }
  561.   $ret = $session->get_request(%args);
  563.   if ($ret) {
  564.       foreach $oid (@enoid) {
  565.       push @retvals, $ret->{$oid} if (exists($ret->{$oid}));
  566.     }
  567.     return wantarray ? @retvals : $retvals[0];
  568.   }
  569.   $ret = join(' ', @vars);
  570.   $oid = $session->error();
  571.   carp "SNMPGET Problem for $ret on $host : $oid"
  572.     unless ($Net_SNMP_util::SuppressWarnings > 1);
  573.   return undef;
  574. }
  576. =head2 snmpgetnext() - send a SNMP get-next-request to the remote agent
  578.     @result = snmpgetnext(
  579. [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
  580. [%param_hash],
  581. @oids
  582.     );
  584. This function performs a SNMP get-next-request query to gather data from the
  585. remote agent on the host specified.  The message is built using the list of
  586. OBJECT IDENTIFIERs passed as an array.  Each OBJECT IDENTIFIER is placed into a
  587. single SNMP GetNextRequest-PDU in the same order that it held in the original
  588. list.
  590. The requested values are returned in an array in the same order as they were
  591. requested.  The OBJECT IDENTIFIER number is added as a prefix to each value
  592. using a colon as a separator, like '1.3.6.1.2.1.2.2.1.2.1:ethernet'.
  593. In scalar context the first requested value is returned.
  595. =cut
  597. #
  598. # snmpgetnext.
  599. #
  600. sub snmpgetnext ($@) {
  601.   my($host, @vars) = @_;
  602.   my($session, @enoid, %args, $ret, $oid, @retvals);
  604.   $session = &snmpopen($host, 0, @vars);
  605.   if (!defined($session)) {
  606.     carp "SNMPGETNEXT Problem for $host"
  607.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  608.     return undef;
  609.   }
  611.   @enoid = &toOID(@vars);
  612.   return undef unless defined $enoid[0];
  614.   $args{'-varbindlist'} = @enoid;
  615.   if ($Net_SNMP_util::Version > 2) {
  616.     $args{'-contextengineid'} = $Net_SNMP_util::ContextEngineID
  617.       if (defined($Net_SNMP_util::ContextEngineID));
  618.     $args{'-contextname'} = $Net_SNMP_util::ContextName
  619.       if (defined($Net_SNMP_util::ContextName));
  620.   }
  622.   $ret = $session->get_next_request(%args);
  624.   if ($ret) {
  625.       foreach $oid (@enoid) {
  626.       push @retvals, $oid . ':' . $ret->{$oid} if (exists($ret->{$oid}));
  627.     }
  628.     return wantarray ? @retvals : $retvals[0];
  629.   }
  630.   $ret = join(' ', @vars);
  631.   $oid = $session->error();
  632.   carp "SNMPGETNEXT Problem for $ret on $host : $oid"
  633.     unless ($Net_SNMP_util::SuppressWarnings > 1);
  634.   return undef;
  635. }
  637. =head2 snmpgetbulk() - send a SNMP get-bulk-request to the remote agent
  639.     @result = snmpgetbulk(
  640. [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
  641. $nonrepeaters,
  642. $maxrepetitions,
  643. [%param_hash],
  644. @oids
  645.     );
  647. This function performs a SNMP get-bulk-request query to gather data from the
  648. remote agent on the host specified.
  650. =over
  652. =item *
  654. The B<$nonrepeaters> value specifies the number of variables in the @oids list
  655. for which a single successor is to be returned.  If it is null or undefined,
  656. a value of 0 is used.
  658. =item *
  660. The B<$maxrepetitions> value specifies the number of successors to be returned
  661. for the remaining variables in the @oids list.  If it is null or undefined,
  662. the default value of 12 is used.
  664. =item *
  666. The message is built using the list of
  667. OBJECT IDENTIFIERs passed as an array.  Each OBJECT IDENTIFIER is placed into a
  668. single SNMP GetNextRequest-PDU in the same order that it held in the original
  669. list.
  671. =back
  673. The requested values are returned in an array in the same order as they were
  674. requested.
  676. B<NOTE:> This function can only be used when the SNMP version is set to
  677. SNMPv2c or SNMPv3.
  679. =cut
  681. #
  682. # snmpgetbulk.
  683. #
  684. sub snmpgetbulk ($$$@) {
  685.   my($host, $nr, $mr, @vars) = @_;
  686.   my($session, %args, @enoid, $ret);
  687.   my($oid, @retvals);
  689.   $session = &snmpopen($host, 0, @vars);
  690.   if (!defined($session)) {
  691.     carp "SNMPGETBULK Problem for $hostn"
  692.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  693.     return undef;
  694.   }
  696.   if ($Net_SNMP_util::Version < 2) {
  697.     carp "SNMPGETBULK Problem for $host : must use SNMP version > 1"
  698.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  699.     return undef;
  700.   }
  702.   $args{'-nonrepeaters'} = $nr if ($nr > 0);
  703.   $mr = $Net_SNMP_util::MaxRepetitions if ($mr <= 0);
  704.   $args{'-maxrepetitions'} = $mr;
  706.   if ($Net_SNMP_util::Version > 2) {
  707.     $args{'-contextengineid'} = $Net_SNMP_util::ContextEngineID
  708.       if (defined($Net_SNMP_util::ContextEngineID));
  709.     $args{'-contextname'} = $Net_SNMP_util::ContextName
  710.       if (defined($Net_SNMP_util::ContextName));
  711.   }
  713.   @enoid = &toOID(@vars);
  714.   return undef unless defined $enoid[0];
  716.   $args{'-varbindlist'} = @enoid;
  717.   $ret = $session->getbulk_request(%args);
  719.   if ($ret) {
  720.     @enoid = &Net::SNMP::oid_lex_sort(keys %$ret);
  721.     foreach $oid (@enoid) {
  722.       push @retvals, $oid . ":" . $ret->{$oid};
  723.     }
  724.     return (@retvals);
  725.   } else {
  726.     $ret = join(' ', @vars);
  727.     $oid = $session->error();
  728.     carp "SNMPGETBULK Problem for $ret on $host : $oidn"
  729.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  730.     return undef;
  731.   }
  732. }
  735. =head2 snmpwalk() - walk OBJECT IDENTIFIER tree(s) on the remote agent
  737.     @result = snmpwalk(
  738. [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
  739. [%param_hash],
  740. @oids
  741.     );
  743. This function performs a sequence of SNMP get-next-request or get-bulk-request
  744. (if the SNMP version is 2 or higher) queries to gather data from the remote
  745. agent on the host specified.  The initial message is built using the list of
  746. OBJECT IDENTIFIERs passed as an array.  Each OBJECT IDENTIFIER is placed into a
  747. single SNMP GetNextRequest-PDU in the same order that it held in the original
  748. list.  Queries continue until all the returned OBJECT IDENTIFIERs are no longer
  749. a child of the base OBJECT IDENTIFIERs.
  751. The requested values are returned in an array in the same order as they were
  752. requested.  The OBJECT IDENTIFIER number is added as a prefix to each value
  753. using a colon as a separator, like '1.3.6.1.2.1.2.2.1.2.1:ethernet'.  If only
  754. one OBJECT IDENTIFIER is requested, just the "instance" part of the OBJECT
  755. IDENTIFIER is added as a prefix, like '1:ethernet', '2:ethernet', '3:fddi'.
  757. =cut
  759. #
  760. # snmpwalk.
  761. #
  762. sub snmpwalk ($@) {
  763.   my($host, @vars) = @_;
  764.   return(&snmpwalk_flg($host, undef, @vars));
  765. }
  767. =head2 snmpset() - send a SNMP set-request to the remote agent
  769.     @result = snmpset(
  770. [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
  771. [%param_hash],
  772. $oid1, $type1, $value1,
  773. [$oid2, $type2, $value2 ...]
  774.     );
  776. This function is used to modify data on the remote agent using a SNMP
  777. set-request.  The message is built using the list of values consisting of groups
  778. of an OBJECT IDENTIFIER, an object type, and the actual value to be set.
  779. The object type can be one of the following strings:
  781.     integer | int
  782.     string | octetstring | octet string
  783.     oid | object id | object identifier
  784.     ipaddr | ip addr4ess
  785.     timeticks
  786.     uint | uinteger | uinteger32 | unsigned int | unsigned integer | unsigned integer32
  787.     counter | counter 32
  788.     counter64
  789.     gauge | gauge32
  791. The object type may also be an octet corresponding to the ASN.1 type.  See
  792. the Net::SNMP documentation for more information.
  794. The requested values are returned in an array in the same order as they were
  795. requested.  In scalar context the first requested value is returned.
  797. =cut
  799. #
  800. # snmpset.
  801. #
  802. sub snmpset($@) {
  803.   my($host, @vars) = @_;
  804.   my($session, @vals, %args, $ret);
  805.   my($oid, $type, $value, @enoid, @retvals);
  807.   $session = &snmpopen($host, 0, @vars);
  808.   if (!defined($session)) {
  809.     carp "SNMPSET Problem for $host"
  810.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  811.     return undef;
  812.   }
  814.   if ($Net_SNMP_util::Version > 2) {
  815.     $args{'-contextengineid'} = $Net_SNMP_util::ContextEngineID
  816.       if (defined($Net_SNMP_util::ContextEngineID));
  817.     $args{'-contextname'} = $Net_SNMP_util::ContextName
  818.       if (defined($Net_SNMP_util::ContextName));
  819.   }
  821.   while(@vars) {
  822.     ($oid) = toOID((shift @vars));
  823.     $ret   = shift @vars;
  824.     $value = shift @vars;
  825.     $type  = ASNtype($ret);
  826.     if (!defined($type)) {
  827.       carp "unknown SNMP type: $typen"
  828. unless ($Net_SNMP_util::SuppressWarnings > 1);
  829.     }
  830.     push @vals, $oid, $type, $value;
  831.     push @enoid, $oid;
  832.   }
  833.   return undef unless defined $vals[0];
  835.   $args{'-varbindlist'} = @vals;
  837.   $ret = $session->set_request(%args);
  838.   if ($ret) {
  839.       foreach $oid (@enoid) {
  840.       push @retvals, $ret->{$oid} if (exists($ret->{$oid}));
  841.     }
  842.     return wantarray ? @retvals : $retvals[0];
  843.   }
  844.   $ret = join(' ', @enoid);
  845.   $oid = $session->error();
  846.   carp "SNMPSET Problem for $ret on $host : $oid"
  847.     unless ($Net_SNMP_util::SuppressWarnings > 1);
  848.   return undef;
  849. }
  851. =head2 snmptrap() - send a SNMP trap to the remote manager
  853.     @result = snmptrap(
  854. [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
  855. $enterprise,
  856. $agentaddr,
  857. $generictrap,
  858. $specifictrap,
  859. [%param_hash],
  860. $oid1, $type1, $value1, 
  861. [$oid2, $type2, $value2 ...]
  862.     );
  864. This function sends a SNMP trap to the remote manager on the host specified.
  865. The message is built using the list of values consisting of groups of an
  866. OBJECT IDENTIFIER, an object type, and the actual value to be set.
  867. The object type can be one of the following strings:
  869.     integer | int
  870.     string | octetstring | octet string
  871.     oid | object id | object identifier
  872.     ipaddr | ip addr4ess
  873.     timeticks
  874.     uint | uinteger | uinteger32 | unsigned int | unsigned integer | unsigned integer32
  875.     counter | counter 32
  876.     counter64
  877.     gauge | gauge32
  879. The object type may also be an octet corresponding to the ASN.1 type.  See
  880. the Net::SNMP documentation for more information.
  882. A true value is returned if sending the trap is successful.  The undefined value
  883. is returned when a failure has occurred.
  885. When the trap is sent as SNMPv2c, the B<$enterprise>, B<$agentaddr>,
  886. B<$generictrap>, and B<$specifictrap> arguments are ignored.  Furthermore,
  887. the first two (oid, type, value) tuples should be:
  889. =over
  891. =item *
  893. sysUpTime.0 - ('1.3.6.1.2.1.1.3.0', 'timeticks', $timeticks)
  895. =item *
  897. snmpTrapOID.0 - ('1.3.6.1.6.3.1.1.4.1.0', 'oid', $oid)
  899. =back
  901. B<NOTE:> This function can only be used when the SNMP version is set to
  902. SNMPv1 or SNMPv2c.
  904. =cut
  906. #
  907. # Send an SNMP trap
  908. #
  909. sub snmptrap($$$$$@) {
  910.   my($host, $ent, $agent, $gen, $spec, @vars) = @_;
  911.   my($oid, $type, $value, $ret, @enoid, @vals);
  912.   my($session, %args);
  914.   $session = &snmpopen($host, 1, @vars);
  915.   if (!defined($session)) {
  916.     carp "SNMPTRAP Problem for $hostn"
  917.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  918.     return undef;
  919.   }
  921.   if ($Net_SNMP_util::Version == 1) {
  922.     $args{'-enterprise'} = $ent if (defined($ent) && (length($ent) > 0));
  923.     $args{'-agentaddr'} = $agent if (defined($agent) && (length($agent) > 0));
  924.     $args{'-generictrap'} = $gen if (defined($gen) && (length($gen) > 0));
  925.     $args{'-specifictrap'} = $spec if (defined($spec) && (length($spec) > 0));
  926.   } elsif ($Net_SNMP_util::Version > 2) {
  927.     carp "SNMPTRAP Problem for $host : must use SNMP version 1 or 2"
  928.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  929.   }
  931.   while(@vars) {
  932.     ($oid) = toOID((shift @vars));
  933.     $ret   = shift @vars;
  934.     $value = shift @vars;
  935.     $type  = ASNtype($ret);
  936.     if (!defined($type)) {
  937.       carp "unknown SNMP type: $typen"
  938. unless ($Net_SNMP_util::SuppressWarnings > 1);
  939.     }
  940.     push @vals, $oid, $type, $value;
  941.     push @enoid, $oid;
  942.   }
  943.   return undef unless defined $vals[0];
  945.   $args{'-varbindlist'} = @vals;
  947.   if ($Net_SNMP_util::Version == 1) {
  948.     $ret = $session->trap_request(%args);
  949.   } else {
  950.     $ret = $session->snmpv2_trap(%args);
  951.   }
  953.   if (!$ret) {
  954.     $ret = join(' ', @enoid);
  955.     $oid = $session->error();
  956.     carp "SNMPTRAP Problem for $ret on $host : $oid"
  957.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  958.   }
  959.   return $ret;
  960. }
  962. =head2 snmpmaptable() - walk OBJECT IDENTIFIER tree(s) on the remote agent
  964.     $result = snmpmaptable(
  965. [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
  966. &function,
  967. [%param_hash],
  968. @oids
  969.     );
  971. This function performs a sequence of SNMP get-next-request or get-bulk-request
  972. (if the SNMP version is 2 or higher) queries to gather data from the remote
  973. agent on the host specified.  The initial message is built using the list of
  974. OBJECT IDENTIFIERs passed as an array.  Each OBJECT IDENTIFIER is placed into a
  975. single SNMP GetNextRequest-PDU in the same order that it held in the original
  976. list.  Queries continue until all the returned OBJECT IDENTIFIERs are no longer
  977. a child of the base OBJECT IDENTIFIERs.  The OBJECT IDENTIFIERs must correspond
  978. to column entries for a conceptual row in a table.  They may however be columns
  979. in different tables as long as each table is indexed the same way.
  981. =over
  983. =item *
  985. The B<&function> argument will be called once per row of the table.  It
  986. will be passed the row index as a partial OBJECT IDENTIFIER in dotted notation,
  987. e.g. "1.3" or "10.0.1.34", and the values of the requested table columns in
  988. that row.
  990. =back
  992. The number of rows in the table is returned on success.  The undefined value
  993. is returned when a failure has occurred.
  995. =cut
  997. #
  998. # walk a table, calling a user-supplied function for each
  999. # column of a table.
  1000. #
  1001. sub snmpmaptable($$@) {
  1002.   my($host, $fun, @vars) = @_;
  1003.   return snmpmaptable4($host, $fun, 0, @vars);
  1004. }
  1006. =head2 snmpmaptable4() - walk OBJECT IDENTIFIER tree(s) on the remote agent
  1008.     $result = snmpmaptable4(
  1009. [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
  1010. &function,
  1011. $maxrepetitions,
  1012. [%param_hash],
  1013. @oids
  1014.     );
  1016. This function performs a sequence of SNMP get-next-request or get-bulk-request
  1017. (if the SNMP version is 2 or higher) queries to gather data from the remote
  1018. agent on the host specified.  The initial message is built using the list of
  1019. OBJECT IDENTIFIERs passed as an array.  Each OBJECT IDENTIFIER is placed into a
  1020. single SNMP GetNextRequest-PDU in the same order that it held in the original
  1021. list.  Queries continue until all the returned OBJECT IDENTIFIERs are no longer
  1022. a child of the base OBJECT IDENTIFIERs.  The OBJECT IDENTIFIERs must correspond
  1023. to column entries for a conceptual row in a table.  They may however be columns
  1024. in different tables as long as each table is indexed the same way.
  1026. =over
  1028. =item *
  1030. The B<&function> argument will be called once per row of the table.  It
  1031. will be passed the row index as a partial OBJECT IDENTIFIER in dotted notation,
  1032. e.g. "1.3" or "10.0.1.34", and the values of the requested table columns in
  1033. that row.
  1035. =item *
  1037. The B<$maxrepetitions> argument specifies the number of rows to be returned
  1038. by a single get-bulk-request.  If it is null or undefined, the default value
  1039. of 12 is used.
  1041. =back
  1043. The number of rows in the table is returned on success.  The undefined value
  1044. is returned when a failure has occurred.
  1046. =cut
  1048. sub snmpmaptable4($$$@) {
  1049.   my($host, $fun, $max_reps, @vars) = @_;
  1050.   my($session, @enoid, %args, $ret);
  1051.   my($oid, $soid, $toid, $inst, @row, $nr);
  1053.   $session = &snmpopen($host, 0, @vars);
  1054.   if (!defined($session)) {
  1055.     carp "SNMPMAPTABLE Problem for $hostn"
  1056.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  1057.     return undef;
  1058.   }
  1060.   @enoid = toOID(@vars);
  1061.   return undef unless defined $enoid[0];
  1063.   if ($Net_SNMP_util::Version > 1) {
  1064.     $max_reps = $Net_SNMP_util::MaxRepetitions if ($max_reps <= 0);
  1065.     $args{'-maxrepetitions'} = $max_reps;
  1066.   }
  1067.   if ($Net_SNMP_util::Version > 2) {
  1068.     $args{'-contextengineid'} = $Net_SNMP_util::ContextEngineID
  1069.       if (defined($Net_SNMP_util::ContextEngineID));
  1070.     $args{'-contextname'} = $Net_SNMP_util::ContextName
  1071.       if (defined($Net_SNMP_util::ContextName));
  1072.   }
  1074.   $args{'-columns'} = @enoid;
  1076.   $ret = $session->get_entries(%args);
  1078.   if ($ret) {
  1079.     $soid = $enoid[0];
  1080.     $nr = 0;
  1081.     foreach $oid (&Net::SNMP::oid_lex_sort(keys %$ret)) {
  1082.       if (&Net::SNMP::oid_base_match($soid, $oid)) {
  1083. $inst = substr($oid, length($soid)+1);
  1084. undef @row;
  1085. foreach $toid (@enoid) {
  1086.   push @row, $ret->{$toid . "." . $inst};
  1087. }
  1088. &$fun($inst, @row);
  1089. $nr++;
  1090.       } else {
  1091. return($nr) if ($nr > 0);
  1092.       }
  1093.     }
  1094.     return($nr);
  1095.   } else {
  1096.     $ret = join(' ', @vars);
  1097.     $oid = $session->error();
  1098.     carp "SNMPMAPTABLE Problem for $ret on $host : $oidn"
  1099.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  1100.     return undef;
  1101.   }
  1102. }
  1104. =head2 snmpwalkhash() - send a SNMP get-next-request to the remote agent
  1106.     @result = snmpwalkhash(
  1107. [community@]host[:port[:timeout[:retries[:backoff[:version]]]]],
  1108. &function(),
  1109. [%param_hash],
  1110. @oids,
  1111. [%hash]
  1112.     );
  1114. This function performs a sequence of SNMP get-next-request or get-bulk-request
  1115. (if the SNMP version is 2 or higher) queries to gather data from the remote
  1116. agent on the host specified.  The message is built using the list of
  1117. OBJECT IDENTIFIERs passed as an array.  Each OBJECT IDENTIFIER is placed into a
  1118. single SNMP GetNextRequest-PDU in the same order that it held in the original
  1119. list.  Queries continue until all the returned OBJECT IDENTIFIERs are outside
  1120. of the tree specified by the initial OBJECT IDENTIFIERs.
  1122. The B<&function> is called once for every returned value.  It is passed a
  1123. reference to a hash, the hostname, the textual OBJECT IDENTIFIER, the
  1124. dotted-numberic OBJECT IDENTIFIER, the instance, the value and the requested
  1125. textual OBJECT IDENTIFIER.  That function can customize the result so the
  1126. values can be extracted later by hosts, by oid_names, by oid_numbers,
  1127. by instances... like these:
  1129.     $hash{$host}{$name}{$inst} = $value;
  1130.     $hash{$host}{$oid}{$inst} = $value;
  1131.     $hash{$name}{$inst} = $value;
  1132.     $hash{$oid}{$inst} = $value;
  1133.     $hash{$oid . '.' . $ints} = $value;
  1134.     $hash{$inst} = $value;
  1135.     ...
  1137. If the last argument to B<snmpwalkhash> is a reference to a hash, that hash
  1138. reference is passed to the passed-in function instead of a local hash
  1139. reference.  That way the function can look up other objects unrelated
  1140. to the current invocation of B<snmpwalkhash>.
  1142. The snmpwalkhash routine returns the hash.
  1144. =cut
  1146. #
  1147. # Walk the MIB, putting everything you find into hashes.
  1148. #
  1149. sub snmpwalkhash($$@) {
  1150. #  my($host, $hash_sub, @vars) = @_;
  1151.   return(&snmpwalk_flg( @_ ));
  1152. }
  1155. =head2 snmpmapOID() - add texual OBJECT INDENTIFIER mapping
  1157.     snmpmapOID(
  1158. $text1, $oid1,
  1159. [ $text2, $oid2 ...]
  1160.     );
  1162. This routine adds entries to the table that maps textual representation of
  1163. OBJECT IDENTIFIERs to their dotted notation.  For example, 
  1165.     snmpmapOID('ciscoCPU', '1.3.6.1.4.1.9.9.109.1.1.1.1.5.1');
  1167. allows the string 'ciscoCPU' to be used as an OBJECT IDENTIFIER in any SNMP
  1168. query routine.
  1170. This routine doesn't return anything.
  1172. =cut
  1174. #
  1175. #  Add passed-in text, OID pairs to the OID mapping table.
  1176. #
  1177. sub snmpmapOID(@)
  1178. {
  1179.   my(@vars) = @_;
  1180.   my($oid, $txt, $ind);
  1182.   $ind = 0;
  1183.   while($ind <= $#vars) {
  1184.     $txt = $vars[$ind++];
  1185.     next unless($txt =~ /^(([a-zA-Z][a-zA-Zd-]*.)*([a-zA-Z][a-zA-Zd-]*))$/);
  1187.     $oid = $vars[$ind++];
  1188.     next unless($oid =~ /^((d+.)*d+)$/);
  1190.     $Net_SNMP_util::OIDS{$txt} = $oid;
  1191.     $RevNeeded = 1;
  1192.     print "snmpmapOID: $txt => $oidn" if $Net_SNMP_util::Debug;
  1193.   }
  1195.   return undef;
  1196. }
  1198. =head2 snmpLoad_OID_Cache() - Read a file of cached OID mappings
  1200.     $result = snmpLoad_OID_Cache(
  1201. $file
  1202.     );
  1204. This routine opens the file named by the B<$file> argument and reads it.
  1205. The file should contain text, OBJECT IDENTIFIER pairs, one pair
  1206. per line.  It adds the pairs as entries to the table that maps textual
  1207. representation of OBJECT IDENTIFIERs to their dotted notation.
  1208. Blank lines and anything after a '#' or between '--' is ignored.
  1210. This routine returns 0 on success and -1 if the B<$file> could not be opened.
  1212. =cut
  1214. #
  1215. # Open the passed-in file name and read it in to populate
  1216. # the cache of text-to-OID map table.  It expects lines
  1217. # with two fields, the first the textual string like "ifInOctets",
  1218. # and the second the OID value, like "1.3.6.1.2.1.2.2.1.10".
  1219. #
  1220. # blank lines and anything after a '#' or between '--' is ignored.
  1221. #
  1222. sub snmpLoad_OID_Cache ($) {
  1223.   my($arg) = @_;
  1224.   my($txt, $oid);
  1226.   if (!open(CACHE, $arg)) {
  1227.     carp "snmpLoad_OID_Cache: Can't open $arg: $!"
  1228.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  1229.     return -1;
  1230.   }
  1232.   while(<CACHE>) {
  1233.     s/#.*//;
  1234.     s/--.*--//g;
  1235.     s/--.*//;
  1236.     next if (/^$/);
  1237.     next unless (/s/);
  1238.     chop;
  1239.     ($txt, $oid) = split(' ', $_, 2);
  1240.     &snmpmapOID($txt, $oid);
  1241.   }
  1242.   close(CACHE);
  1243.   return 0;
  1244. }
  1246. =head2 snmpMIB_to_OID() - Read a MIB file for textual OID mappings
  1248.     $result = snmpMIB_to_OID(
  1249. $file
  1250.     );
  1252. This routine opens the file named by the B<$file> argument and reads it.
  1253. The file should be an SNMP Management Information Base (MIB) file
  1254. that describes OBJECT IDENTIFIERs supported by an SNMP agent.
  1255. per line.  It adds the textual representation of the OBJECT IDENTIFIERs
  1256. to the text-to-OID mapping table.
  1258. This routine returns the number of entries added to the table or -1 if
  1259. the B<$file> could not be opened.
  1261. =cut
  1263. #
  1264. # Read in the passed MIB file, parsing it
  1265. # for their text-to-OID mappings
  1266. #
  1267. sub snmpMIB_to_OID ($) {
  1268.   my($arg) = @_;
  1269.   my($quote, $buf, $var, $code, $val, $tmp, $tmpv, $strt);
  1270.   my($ret, $pass, $pos, $need2pass, $cnt, %prev);
  1271.   my(%Link) = (
  1272.     'org' => 'iso',
  1273.     'dod' => 'org',
  1274.     'internet' => 'dod',
  1275.     'directory' => 'internet',
  1276.     'mgmt' => 'internet',
  1277.     'mib-2' => 'mgmt',
  1278.     'experimental' => 'internet',
  1279.     'private' => 'internet',
  1280.     'enterprises' => 'private',
  1281.   );
  1283.   if (!open(MIB, $arg)) {
  1284.     carp "snmpMIB_to_OID: Can't open $arg: $!"
  1285.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  1286.     return -1;
  1287.   }
  1288.   print "snmpMIB_to_OID: loading $argn" if $Net_SNMP_util::Debug;
  1289.   $ret = 0;
  1290.   $pass = 0;
  1291.   $need2pass = 1;
  1292.   $cnt = 0;
  1293.   $pos = tell(MIB);
  1294.   while($need2pass) {
  1295.     while(<MIB>) {
  1296.       s/--.*--//g; # throw away comments (-- anything --)
  1297.       s/--.*//; # throw away comments (-- anything EOL)
  1298.       if ($quote) {
  1299. next unless /"/;
  1300. $quote = 0;
  1301.       }
  1302.       chop;
  1303. #
  1304. # $buf = "$buf $_";
  1305. # Previous line removed (and following replacement)
  1306. # suggested by Brian Reichert, reichert@numachi.com
  1307. #
  1308.       $buf .= ' ' . $_;
  1309.       $buf =~ s/s+/ /g;
  1311.       if ($buf =~ / DEFINITIONS ::= BEGIN/) {
  1312. if ($pass == 0 && $need2pass) {
  1313.   seek(MIB, $pos, 0);
  1314.   $buf = "";
  1315.   $pass = 1;
  1316.   $need2pass = 0;
  1317.   $cnt = 0;
  1318.   next;
  1319. }
  1320. $need2pass = 0;
  1321. $pass = 0;
  1322. $pos = tell(MIB);
  1323. undef %Link;
  1324. undef %prev;
  1325. %Link = (
  1326.   'org' => 'iso',
  1327.   'dod' => 'org',
  1328.   'internet' => 'dod',
  1329.   'directory' => 'internet',
  1330.   'mgmt' => 'internet',
  1331.   'mib-2' => 'mgmt',
  1332.   'experimental' => 'internet',
  1333.   'private' => 'internet',
  1334.   'enterprises' => 'private',
  1335. );
  1336. $buf = "";
  1337. next;
  1338.       }
  1340.       $buf =~ s/OBJECT-TYPE/OBJECT IDENTIFIER/;
  1341.       $buf =~ s/OBJECT-IDENTITY/OBJECT IDENTIFIER/;
  1342.       $buf =~ s/OBJECT-GROUP/OBJECT IDENTIFIER/;
  1343.       $buf =~ s/MODULE-IDENTITY/OBJECT IDENTIFIER/;
  1344.       $buf =~ s/ IMPORTS .*;//;
  1345.       $buf =~ s/ SEQUENCE {.*}//;
  1346.       $buf =~ s/ SYNTAX .*//;
  1347.       $buf =~ s/ [w-]+ ::= OBJECT IDENTIFIER//;
  1348.       $buf =~ s/ OBJECT IDENTIFIER .* ::= {/ OBJECT IDENTIFIER ::= {/;
  1349.       $buf =~ s/".*"//;
  1350.       if ($buf =~ /"/) {
  1351. $quote = 1;
  1352.       }
  1354.       if ($buf =~ / ([w-]+) OBJECT IDENTIFIER ::= {([^}]+)}/) {
  1355. $var = $1;
  1356. $buf = $2;
  1357. undef $val;
  1358. $buf =~ s/ +$//;
  1359. ($code, $val) = split(' ', $buf, 2);
  1361. if (!defined($val) || (length($val) <= 0)) {
  1362.   $Net_SNMP_util::OIDS{$var} = $code;
  1363.   $cnt++;
  1364.   print "'$var' => '$code'n" if $Net_SNMP_util::Debug;
  1365. } else {
  1366.   $strt = $code;
  1367.   while($val =~ / /) {
  1368.     ($tmp, $val) = split(' ', $val, 2);
  1369.     if ($tmp =~ /([w-]+)((d+))/) {
  1370.       $tmp = $1;
  1371.       if (exists($Net_SNMP_util::OIDS{$strt})) {
  1372. $tmpv = "$Net_SNMP_util::OIDS{$strt}.$2";
  1373.       } else {
  1374. $tmpv = $2;
  1375.       }
  1376.       $Link{$tmp} = $strt;
  1377.       if (!exists($prev{$tmp}) && exists($Net_SNMP_util::OIDS{$tmp})) {
  1378. if ($tmpv ne $Net_SNMP_util::OIDS{$tmp}) {
  1379.   $strt = "$strt.$tmp";
  1380.   $Net_SNMP_util::OIDS{$strt} = $tmpv;
  1381.   $cnt++;
  1382. }
  1383.       } else {
  1384. $prev{$tmp} = 1;
  1385. $Net_SNMP_util::OIDS{$tmp} = $tmpv;
  1386. $cnt++;
  1387. $strt = $tmp;
  1388.       }
  1389.     }
  1390.   }
  1392.   if (!exists($Net_SNMP_util::OIDS{$strt})) {
  1393.     if ($pass) {
  1394.       carp "snmpMIB_to_OID: $arg: "$strt" prefix unknown, load the parent MIB first.n"
  1395. unless ($Net_SNMP_util::SuppressWarnings > 1);
  1396.     } else {
  1397. $need2pass = 1;
  1398.     }
  1399.   }
  1400.   $Link{$var} = $strt;
  1401.   if (exists($Net_SNMP_util::OIDS{$strt})) {
  1402.     $val = "$Net_SNMP_util::OIDS{$strt}.$val";
  1403.   }
  1404.   if (!exists($prev{$var}) && exists($Net_SNMP_util::OIDS{$var})) {
  1405.     if ($val ne $Net_SNMP_util::OIDS{$var}) {
  1406.       $var = "$strt.$var";
  1407.     }
  1408.   }
  1410.   $Net_SNMP_util::OIDS{$var} = $val;
  1411.   $prev{$var} = 1;
  1412.   $cnt++;
  1414.   print "'$var' => '$val'n" if $Net_SNMP_util::Debug;
  1415. }
  1416. undef $buf;
  1417.       }
  1418.     }
  1419.     if ($pass == 0 && $need2pass) {
  1420.       seek(MIB, $pos, 0);
  1421.       $buf = "";
  1422.       $pass = 1;
  1423.       $cnt = 0;
  1424.     } else {
  1425.       $ret += $cnt;
  1426.       $need2pass = 0;
  1427.     }
  1428.   }
  1429.   close(MIB);
  1430.   $RevNeeded = 1;
  1431.   return $ret;
  1432. }
  1434. =head2 snmpQueue_MIB_File() - queue a MIB file for reading "on demand"
  1436.     snmpQueue_MIB_File(
  1437. $file1,
  1438. [$file2, ...]
  1439.     );
  1441. This routine queues the list of SNMP MIB files for later processing.
  1442. Whenever a text-to-OBJECT IDENTIFIER lookup fails, the list of queued MIB
  1443. files is consulted.  If it isn't empty, the first MIB file in the list is
  1444. removed and passed to B<snmpMIB_to_OID()>.  The lookup is attempted again,
  1445. and if that still fails the next MIB file in the list is removed and passed
  1446. to B<snmpMIB_to_OID()>. This process continues until the lookup succeeds
  1447. or the list is exhausted.
  1449. This routine doesn't return anything.
  1451. =cut
  1453. #
  1454. # Save the passed-in list of MIB files until an OID can't be
  1455. # found in the existing table.  At that time the MIB file will
  1456. # be loaded, and the lookup attempted again.
  1457. #
  1458. sub snmpQueue_MIB_File (@) {
  1459.   my(@files) = @_;
  1460.   my($file);
  1462.   foreach $file (@files) {
  1463.     push(@Net_SNMP_util::MIB_Files, $file);
  1464.   }
  1465. }
  1467. # [private methods] -------------------------------------
  1469. #
  1470. # Start an snmp session
  1471. #
  1472. sub snmpopen ($$$) {
  1473.   my($host, $type, $vars) = @_;
  1474.   my($nhost, $port, $community, $lhost, $lport, $nlhost);
  1475.   my($timeout, $retries, $backoff, $version, $v4onlystr);
  1476.   my($opts, %args, $tmp, $sess);
  1477.   my($debug, $maxmsgsize);
  1479.   $type = 0 if (!defined($type));
  1480.   $community = "public";
  1481.   $nlhost = "";
  1483.   ($community, $host) = ($1, $2) if ($host =~ /^(.*)@([^@]+)$/);
  1485.   # We can't split on the : character because a numeric IPv6
  1486.   # address contains a variable number of :'s
  1487.   if( ($host =~ /^([.*]):(.*)$/) || ($host =~ /^([.*])$/) ) {
  1488.     # Numeric IPv6 address between []
  1489.     ($host, $opts) = ($1, $2);
  1490.   } else {
  1491.     # Hostname or numeric IPv4 address
  1492.     ($host, $opts) = split(':', $host, 2);
  1493.   }
  1494.   ($port, $timeout, $retries, $backoff, $version, $v4onlystr)
  1495.     = split(':', $opts, 6) if(defined($opts) && (length $opts > 0) );
  1497.   undef($timeout) if (defined($timeout) && length($timeout) <= 0);
  1498.   undef($retries) if (defined($retries) && length($retries) <= 0);
  1499.   undef($backoff) if (defined($backoff) && length($backoff) <= 0);
  1500.   undef($version) if (defined($version) && length($version) <= 0);
  1502.   $v4onlystr = "" unless defined $v4onlystr;
  1504.   if (defined($port) && ($port =~ /^([^!]*)!(.*)$/)) {
  1505.     ($port, $lhost) = ($1, $2);
  1506.     $nlhost = $lhost;
  1507.     ($lhost, $lport) = ($1, $2) if ($lhost =~ /^(.*)!(.*)$/);
  1508.     undef($lport) if (defined($lport) && (length($lport) <= 0));
  1509.   }
  1510.   undef($port) if (defined($port) && length($port) <= 0);
  1512.   if (ref $vars->[0] eq 'HASH') {
  1513.     undef($debug);
  1514.     undef($maxmsgsize);
  1515.     $opts = shift @$vars;
  1516.     foreach $type (keys %$opts) {
  1517.       if ($type =~ /^-?return_array_refs$/i) {
  1518. $Net_SNMP_util::ReturnArrayRefs = $opts->{$type};
  1519.       } elsif ($type =~ /^-?return_hash_refs$/i) {
  1520. $Net_SNMP_util::ReturnHashRefs = $opts->{$type};
  1521.       } elsif ($type =~ /^-?contextengineid$/i) {
  1522. $Net_SNMP_util::ContextEngineID = $opts->{$type};
  1523.       } elsif ($type =~ /^-?contextname$/i) {
  1524. $Net_SNMP_util::ContextName = $opts->{$type};
  1525.       } elsif ($type =~ /^-?maxrepetitions$/i) {
  1526. $Net_SNMP_util::MaxRepetitions = $opts->{$type};
  1527.       } elsif ($type =~ /^-?default_max_repetitions$/i) {
  1528. $Net_SNMP_util::MaxRepetitions = $opts->{$type};
  1529.       } elsif ($type =~ /^-?version$/i) {
  1530. $version = $opts->{$type};
  1531.       } elsif ($type =~ /^-?port$/i) {
  1532. $port = $opts->{$type};
  1533.       } elsif ($type =~ /^-?localaddr$/i) {
  1534. $lhost = $opts->{$type};
  1535.       } elsif ($type =~ /^-?community$/i) {
  1536. $community = $opts->{$type};
  1537.       } elsif ($type =~ /^-?timeout$/i) {
  1538. $timeout = $opts->{$type};
  1539.       } elsif ($type =~ /^-?retries$/i) {
  1540. $retries = $opts->{$type};
  1541.       } elsif ($type =~ /^-?maxmsgsize$/i) {
  1542. $maxmsgsize = $opts->{$type};
  1543.       } elsif ($type =~ /^-?debug$/i) {
  1544. $debug = $opts->{$type};
  1545.       } elsif ($type =~ /^-?backoff$/i) {
  1546. next; # XXXX not implemented in Net::SNMP
  1547.       } elsif ($type =~ /^-?avoid_negative_request_ids$/i) {
  1548. next; # XXXX not implemented in Net::SNMP
  1549.       } elsif ($type =~ /^-?lenient_source_/i) {
  1550. next; # XXXX not implemented in Net::SNMP
  1551.       } elsif ($type =~ /^-?use_16bit_request_ids$/i) {
  1552. next; # XXXX not implemented in Net::SNMP
  1553.       } elsif ($type =~ /^-?use_getbulk$/i) {
  1554. next; # XXXX not implemented in Net::SNMP
  1555.       } else {
  1556. $tmp = $type;
  1557. $tmp = '-' . $tmp unless ($tmp =~ /^-/);
  1558. $args{$tmp} = $opts->{$type};
  1559.       }
  1560.     }
  1561.   }
  1563.   $port = 162 if ($type == 1 && !defined($port));
  1564.   $nhost = "$community@$host";
  1565.   $nhost .= ":" . $port if (defined($port));
  1566.   undef($lhost) if (defined($lhost) && (length($lhost) <= 0));
  1568.   $version = '1' unless defined $version;
  1569.   if ($version =~ /1/) {
  1570.     $version = 1;
  1571.   } elsif ($version =~ /2/) {
  1572.     $version = 2;
  1573.   } elsif ($version =~ /3/) {
  1574.     $version = 3;
  1575.   }
  1576.   if ((!defined($Net_SNMP_util::Session))
  1577.     || ($Net_SNMP_util::Host ne $nhost)
  1578.     || ($Net_SNMP_util::Version ne $version)
  1579.     || ($Net_SNMP_util::LHost ne $nlhost)
  1580.     || ($Net_SNMP_util::IPv4only ne $v4onlystr)) {
  1581.     if (defined($Net_SNMP_util::Session)) {
  1582.       $Net_SNMP_util::Session->close();    
  1583.       undef $Net_SNMP_util::Session;
  1584.       undef $Net_SNMP_util::Host;
  1585.       undef $Net_SNMP_util::Version;
  1586.       undef $Net_SNMP_util::LHost;
  1587.       undef $Net_SNMP_util::IPv4only;
  1588.       undef $Net_SNMP_util::ContextEngineID;
  1589.       undef $Net_SNMP_util::ContextName;
  1590.     }
  1592.     $args{'-hostname'} = $host;
  1593.     $args{'-port'} = $port if (defined($port));
  1594.     $args{'-localaddr'} = $lhost if (defined($lhost));
  1595.     $args{'-localport'} = $lport if (defined($lport));
  1596.     $args{'-version'} = $version;
  1597.     $args{'-domain'} = "udp/ipv4" if (length($v4onlystr) > 0);
  1598.     $args{'-timeout'} = $timeout if (defined($timeout));
  1599.     $args{'-retries'} = $retries if (defined($retries));
  1600.     $args{'-maxmsgsize'} = $maxmsgsize if (defined($maxmsgsize));
  1601.     $args{'-debug'} = $debug if (defined($debug));
  1602.     $args{'-community'} = $community unless ($community eq "public");
  1603.     delete $args{'-community'} if ($version == 3);
  1605.     ($sess, $tmp) = Net::SNMP->session(%args);
  1607.     if (defined($sess)) {
  1608.       $Net_SNMP_util::Session = $sess;
  1609.       $Net_SNMP_util::Host = $nhost;
  1610.       $Net_SNMP_util::Version = $version;
  1611.       $Net_SNMP_util::LHost = $nlhost;
  1612.       $Net_SNMP_util::IPv4only = $v4onlystr;
  1613.     } else {
  1614.       carp "SNMPopen failed: $tmp"
  1615. unless ($Net_SNMP_util::SuppressWarnings > 1);
  1616.       return(undef);
  1617.     }
  1618.     return $Net_SNMP_util::Session;
  1619.   } else {
  1620.     $Net_SNMP_util::Session->timeout($timeout)
  1621.       if (defined($timeout) && (length($timeout) > 0));
  1622.     $Net_SNMP_util::Session->retries($retries)
  1623.       if (defined($retries) && (length($retries) > 0));
  1624.     $Net_SNMP_util::Session->maxmsgsize($maxmsgsize)
  1625.       if (defined($maxmsgsize) && (length($maxmsgsize) > 0));
  1626.     $Net_SNMP_util::Session->debug($debug)
  1627.       if (defined($debug) && (length($debug) > 0));
  1628.   }
  1629.   return $Net_SNMP_util::Session;
  1630. }
  1632. #
  1633. #  Given an OID in either ASN.1 or mixed text/ASN.1 notation, return an OID.
  1634. #
  1635. sub toOID(@) {
  1636.   my(@vars) = @_;
  1637.   my($oid, $var, $tmp, $tmpv, @retvar);
  1639.   undef @retvar;
  1640.   foreach $var (@vars) {
  1641.     ($oid, $tmp) = &Check_OID($var);
  1642.     if (!$oid && $Net_SNMP_util::CacheLoaded == 0) {
  1643.       $tmp = $Net_SNMP_util::SuppressWarnings;
  1644.       $Net_SNMP_util::SuppressWarnings = 1000;
  1646.       &snmpLoad_OID_Cache($Net_SNMP_util::CacheFile);
  1648.       $Net_SNMP_util::CacheLoaded = 1;
  1649.       $Net_SNMP_util::SuppressWarnings = $tmp;
  1651.       ($oid, $tmp) = &Check_OID($var);
  1652.     }
  1653.     while (!$oid && $#Net_SNMP_util::MIB_Files >= 0) {
  1654.       $tmp = $Net_SNMP_util::SuppressWarnings;
  1655.       $Net_SNMP_util::SuppressWarnings = 1000;
  1657.       snmpMIB_to_OID(shift(@Net_SNMP_util::MIB_Files));
  1659.       $Net_SNMP_util::SuppressWarnings = $tmp;
  1661.       ($oid, $tmp) = &Check_OID($var);
  1662.       if ($oid) {
  1663. open(CACHE, ">>$Net_SNMP_util::CacheFile");
  1664. print CACHE "$tmpt$oidn";
  1665. close(CACHE);
  1666.       }
  1667.     }
  1668.     if ($oid) {
  1669.       $var =~ s/^$tmp/$oid/;
  1670.     } else {
  1671.       carp "Unknown SNMP var $var"
  1672.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  1673.       next;
  1674.     }
  1675.     while ($var =~ /"([^"]*)"/) {
  1676.       $tmp = sprintf("%d.%s", length($1), join(".", map(ord, split(//, $1))));
  1677.       $var =~ s/"$1"/$tmp/;
  1678.     }
  1679.     print "toOID: $varn" if $Net_SNMP_util::Debug;
  1680.     push(@retvar, $var);
  1681.   }
  1682.   return @retvar;
  1683. }
  1685. #
  1686. # Check to see if an OID is in the text-to-OID cache.
  1687. # Returns the OID and the corresponding text as two separate
  1688. # elements.
  1689. #
  1690. sub Check_OID ($) {
  1691.   my($var) = @_;
  1692.   my($tmp, $tmpv, $oid);
  1694.   if ($var =~ /^(([a-zA-Z][a-zA-Zd-]*.)*([a-zA-Z][a-zA-Zd-]*))/)
  1695.   {
  1696.     $tmp = $&;
  1697.     $tmpv = $tmp;
  1698.     for (;;) {
  1699.       last if exists($Net_SNMP_util::OIDS{$tmpv});
  1700.       last if !($tmpv =~ s/^[^.]*.//);
  1701.     }
  1702.     $oid = $Net_SNMP_util::OIDS{$tmpv};
  1703.     if ($oid) {
  1704.       return ($oid, $tmp);
  1705.     } else {
  1706.       return undef;
  1707.     }
  1708.   }
  1709.   return ($var, $var);
  1710. }
  1712. sub snmpwalk_flg ($$@) {
  1713.   my($host, $hash_sub, @vars) = @_;
  1714.   my($session, %args, @enoid, @poid, $toid, $oid, $got);
  1715.   my($val, $ret, %soid, @retvals, $tmp);
  1716.   my(%rethash, $h_ref, @tmprefs);
  1718.   $session = &snmpopen($host, 0, @vars);
  1719.   if (!defined($session)) {
  1720.     carp "SNMPWALK Problem for $hostn"
  1721.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  1722.     return undef;
  1723.   }
  1725.   $h_ref = (ref $vars[$#vars] eq "HASH") ? pop(@vars) : %rethash;
  1727.   @enoid = toOID(@vars);
  1728.   return undef unless defined $enoid[0];
  1730.   #
  1731.   # Create/Refresh a reversed hash with oid -> name
  1732.   #
  1733.   if (defined($hash_sub) && ($RevNeeded)) {
  1734.       %revOIDS = reverse %Net_SNMP_util::OIDS;
  1735.       $RevNeeded = 0;
  1736.   }
  1738.   #
  1739.   # Create temporary array of refs to return values
  1740.   #
  1741.   foreach $oid (0..$#enoid)  {
  1742.     my $tmparray = [];
  1743.     $tmprefs[$oid] = $tmparray;
  1744.   }
  1746.   $got = 0;
  1747.   @poid = @enoid;
  1749.   if ($Net_SNMP_util::Version > 1) {
  1750.     $args{'-maxrepetitions'} = $Net_SNMP_util::MaxRepetitions;
  1751.   }
  1752.   if ($Net_SNMP_util::Version > 2) {
  1753.     $args{'-contextengineid'} = $Net_SNMP_util::ContextEngineID
  1754.       if (defined($Net_SNMP_util::ContextEngineID));
  1755.     $args{'-contextname'} = $Net_SNMP_util::ContextName
  1756.       if (defined($Net_SNMP_util::ContextName));
  1757.   }
  1759.   do {
  1760.     $args{'-varbindlist'} = @poid;
  1761.     if (($Net_SNMP_util::Version > 1)
  1762.     && ($Net_SNMP_util::MaxRepetitions > 1)) {
  1763.       $ret = $session->get_bulk_request(%args);
  1764.     } else {
  1765.       $ret = $session->get_next_request(%args);
  1766.     }
  1767.     last if (!defined($ret));
  1769.     undef %soid;
  1770.     foreach $oid (&Net::SNMP::oid_lex_sort(keys %$ret)) {
  1771.       $got = 1;
  1772.       $tmp = -1;
  1773.       foreach $toid (@enoid) {
  1774. $tmp++;
  1775. if (&Net::SNMP::oid_base_match($toid, $oid)) {
  1776.   $soid{$toid} = $oid;
  1777.   if (defined($hash_sub)) {
  1778.     #
  1779.     # extract name of the oid, if possible, the rest becomes the
  1780.     # instance
  1781.     #
  1782.     my $inst = "";
  1783.     my $upo = $toid;
  1784.     while (!exists($revOIDS{$upo}) && length($upo)) {
  1785.       $upo =~ s/(.d+?)$//;
  1786.       if (defined($1) && length($1)) {
  1787. $inst = $1 . $inst;
  1788.       } else {
  1789. $upo = "";
  1790. last;
  1791.       }
  1792.     }
  1793.     if (length($upo) && exists($revOIDS{$upo})) {
  1794.       $upo = $revOIDS{$upo} . $inst;
  1795.     } else {
  1796.       $upo = $toid;
  1797.     }
  1799.     my $qoid = $oid;
  1800.     my $tmpo;
  1801.     $inst = "";
  1802.     while (!exists($revOIDS{$qoid}) && length($qoid)) {
  1803.       $qoid =~ s/(.d+?)$//;
  1804.       if (defined($1) && length($1)) {
  1805. $inst = $1 . $inst;
  1806.       } else {
  1807. $qoid = "";
  1808. last;
  1809.       }
  1810.     }
  1811.     if (length($qoid) && exists($revOIDS{$qoid})) {
  1812.       $tmpo = $qoid;
  1813.       $qoid = $revOIDS{$qoid};
  1814.     } else {
  1815.       $qoid = $oid;
  1816.       $tmpo = $toid;
  1817.       $inst = substr($oid, length($tmpo)+1);
  1818.     }
  1819.     #
  1820.     # call hash_sub
  1821.     #
  1822.     &$hash_sub($h_ref, $host, $qoid, $tmpo, $inst, $ret->{$oid}, $upo);
  1823.   } else {
  1824.     my $tmpo;
  1825.     my $tmpv = $ret->{$oid};
  1826.     $tmpo = substr($oid, length($toid)+1);
  1827.     push @{$tmprefs[$tmp]}, "$tmpo:$tmpv";
  1828.   }
  1829. }
  1830.       }
  1831.     }
  1832.     undef @poid;
  1833.     @poid = values %soid;
  1834.   } while($#poid >= 0);
  1835.   if ($got) {
  1836.     if (defined($hash_sub)) {
  1837. return ($h_ref) if ($Net_SNMP_util::ReturnHashRefs);
  1838.      return (%$h_ref);
  1839.     } elsif ($Net_SNMP_util::Return_array_refs)  {
  1840.       return (@tmprefs);
  1841.     } else {
  1842.       do {
  1843. $got = 0;
  1844. foreach $toid (0..$#enoid) {
  1845.   next if (scalar(@{$tmprefs[$toid]}) <= 0);
  1846.   $got = 1;
  1847.   $oid = shift(@{$tmprefs[$toid]});
  1848.   if ($#enoid > 0) {
  1849.     ($oid, $val) = split(':', $oid, 2);
  1850.     $oid = $enoid[$toid] . '.' . $oid;
  1851.     push(@retvals, "$oid:$val");
  1852.   } else {
  1853.     push(@retvals, $oid);
  1854.   }
  1855. }
  1856.       } while($got);
  1857.       return (@retvals);
  1858.     }
  1859.   } else {
  1860.     $ret = join(' ', @vars);
  1861.     $oid = $session->error();
  1862.     carp "SNMPWALK Problem for $ret on $host : $oidn"
  1863.       unless ($Net_SNMP_util::SuppressWarnings > 1);
  1864.     return undef;
  1865.   }
  1866. }
  1868. #
  1869. # When passed a string, return the ASN.1 type that corresponds to the
  1870. # string.
  1871. #
  1872. sub ASNtype($) {
  1873.   my($type) = @_;
  1875.   $type =~ tr/A-Z/a-z/;
  1876.   if ($type eq "int") {
  1877.     $type = 0x02;
  1878.   } elsif ($type eq "integer") {
  1879.     $type = 0x02;
  1880.   } elsif ($type eq "string") {
  1881.     $type = 0x04;
  1882.   } elsif ($type eq "octetstring") {
  1883.     $type = 0x04;
  1884.   } elsif ($type eq "octet string") {
  1885.     $type = 0x04;
  1886.   } elsif ($type eq "oid") {
  1887.     $type = 0x06;
  1888.   } elsif ($type eq "object id") {
  1889.     $type = 0x06;
  1890.   } elsif ($type eq "object identifier") {
  1891.     $type = 0x06;
  1892.   } elsif ($type eq "ipaddr") {
  1893.     $type = 0x40;
  1894.   } elsif ($type eq "ip address") {
  1895.     $type = 0x40;
  1896.   } elsif ($type eq "timeticks") {
  1897.     $type = 0x43;
  1898.   } elsif ($type eq "uint") {
  1899.     $type = 0x47;
  1900.   } elsif ($type eq "uinteger") {
  1901.     $type = 0x47;
  1902.   } elsif ($type eq "uinteger32") {
  1903.     $type = 0x47;
  1904.   } elsif ($type eq "unsigned int") {
  1905.     $type = 0x47;
  1906.   } elsif ($type eq "unsigned integer") {
  1907.     $type = 0x47;
  1908.   } elsif ($type eq "unsigned integer32") {
  1909.     $type = 0x47;
  1910.   } elsif ($type eq "counter") {
  1911.     $type = 0x41;
  1912.   } elsif ($type eq "counter32") {
  1913.     $type = 0x41;
  1914.   } elsif ($type eq "counter64") {
  1915.     $type = 0x46;
  1916.   } elsif ($type eq "gauge") {
  1917.     $type = 0x42;
  1918.   } elsif ($type eq "gauge32") {
  1919.     $type = 0x42;
  1920.   } elsif (($type <= 0) || ($type > 255)) {
  1921.     return undef;
  1922.   }
  1923.   return $type;
  1924. }
  1926. # [documentation] ------------------------------------------------------------
  1928. =head1 EXPORTS
  1930. The Net_SNMP_util module uses the F<Exporter> module to export useful
  1931. constants and subroutines.  These exportable symbols are defined below and
  1932. follow the rules and conventions of the F<Exporter> module (see L<Exporter>).
  1934. =over
  1936. =item Exportable
  1938. &snmpget, &snmpgetnext, &snmpgetbulk, &snmpwalk, &snmpset, &snmptrap,
  1939. &snmpmaptable, &snmpmaptable4, &snmpwalkhash, &snmpmapOID, &snmpMIB_to_OID,
  1940. &snmpLoad_OID_Cache, &snmpQueue_MIB_File
  1942. =back
  1944. =head1 EXAMPLES
  1946. =head2 1. SNMPv1 get-request for sysUpTime
  1948. This example gets the sysUpTime from a remote host.
  1950.     #! /usr/local/bin/perl
  1951.     use strict;
  1952.     use Net_SNMP_util;
  1953.     my ($host, $ret)
  1954.     $host = shift || 'localhost';
  1955.     $ret = snmpget($host, 'sysUpTime');
  1957.     print("sysUpTime for $host is $retn");
  1959.     exit 0;
  1961. =head2 2. SNMPv3 set-request of sysContact
  1963. This example sets the sysContact information on the remote host to 
  1964. "Help Desk x911".  The parameters passed to the snmpset function are for
  1965. the demonstration of syntax only.  These parameters will need to be
  1966. set according to the SNMPv3 parameters of the remote host used by the script. 
  1968.     #! /usr/local/bin/perl
  1969.     use strict;
  1970.     use Net_SNMP_util;
  1971.     my($host, %v3hash, $ret);
  1972.     $host = shift || 'localhost';
  1973.     $v3hash{'-version'} = 'snmpv3';
  1974.     $v3hash{'-username'} = 'myv3Username';
  1975.     $v3hash{'-authkey'} = '0x05c7fbde31916f64da4d5b77156bdfa7';
  1976.     $v3hash{'-authprotocol'} = 'md5';
  1977.     $v3hash{'-privkey'} = '0x93725fd3a02a48ce02df4e065a1c1746';
  1979.     $ret = snmpset($host, %v3hash, 'sysContact', 'string', 'Help Desk x911');
  1981.     print "sysContact on $host is now $retn";
  1982.     exit 0;
  1984. =head2 3. SNMPv2c walk for ifTable
  1986. This example gets the contents of the ifTable by sending get-bulk-requests
  1987. until the responses are no longer part of the ifTable.  The ifTable can also
  1988. be retrieved using C<snmpmaptable>.
  1990.     #! /usr/local/bin/perl
  1991.     use strict;
  1992.     use Net_SNMP_util;
  1993.     my($host, @ret, $oid, $val);
  1994.     $host = shift || 'localhost';
  1996.     @ret = snmpwalk($host . ':::::2', 'ifTable');
  1997.     foreach $val (@ret) {
  1998. ($oid, $val) = split(':', $val, 2);
  1999. print "$oid => $valn";
  2000.     }
  2001.     exit 0;
  2003. =head2 4. SNMPv2c maptable collecting ifDescr, ifInOctets, and ifOutOctets.
  2005. This example collects a table containing the columns ifDescr, ifInOctets, and
  2006. ifOutOctets.  A printing function is called once per row.
  2008.     #! /usr/local/bin/perl
  2009.     use strict;
  2010.     use Net_SNMP_util;
  2012.     sub printfun($$$$) {
  2013. my($inst, $desc, $in, $out) = @_;
  2014. printf "%3d %-52.52s %10d %10dn", $inst, $desc, $in, $out;
  2015.     }
  2017.     my($host, @ret);
  2018.     $host = shift || 'localhost';
  2020.     printf "%-3s %-52s %10s %10sn", "Int", "Description", "In", "Out";
  2021.     @ret = snmpmaptable($host . ':::::2', &printfun,
  2022. 'ifDescr', 'ifInOctets', 'ifOutOctets');
  2024.     exit 0;
  2026. =head1 REQUIREMENTS
  2028. =over
  2030. =item *
  2032. The Net_SNMP_util module uses syntax that is not supported in versions of Perl 
  2033. earlier than v5.6.0. 
  2035. =item *
  2037. The Net_SNMP_util module uses the F<Net::SNMP> module, and as such may depend
  2038. on other modules.  Please see the documentaion on F<Net::SNMP> for more
  2039. information.
  2041. =back
  2043. =head1 AUTHOR
  2045. Mike Mitchell <Mike.Mitchell@sas.com>
  2047. =head1 ACKNOWLEGEMENTS
  2049. The original concept for this module was based on F<SNMP_Session.pm> written
  2050. by Simon Leinen <simon@switch.ch>
  2052. =head1 COPYRIGHT
  2054. Copyright (c) 2005 Mike Mitchell.  All rights reserved.  This program 
  2055. is free software; you may redistribute it and/or modify it under the same
  2056. terms as Perl itself.
  2058. =cut
  2060. # ======================================================================
  2061. 1; # [end Net_SNMP_util]