snmp 0.5.1 → 0.6.0

data/README

@@ -9,16 +9,13 @@ that Ruby can run.
 
 See snmplib.rubyforge.org[http://snmplib.rubyforge.org/] for more info.
 
-Version 0.5.1 fixes bugs #2054 and #2164.  Responses were ignored if they did
-not come back from the same host that the request was sent to.  This behavior
-causes problems for some multi-homed hosts.
+Version 0.6.0 of this software supports the following:
 
-Version 0.5.0 of this software supports the following:
-
-* The GetRequest, GetNextRequest, GetBulkRequest, SetRequest, and Response
-  PDUs
+* The GetRequest, GetNextRequest, GetBulkRequest, SetRequest, Response
+  SNMPv1_Trap, SNMPv2_Trap, and Inform PDUs
 * All of the ASN.1 data types defined by SNMPv1 and SNMPv2c
-* Trap handling for both v1 and v2 traps
+* Sending informs and v1 and v2 traps
+* Trap handling for v1 and v2 traps
 * Symbolic OID values (ie. "ifTable" instead of "1.3.6.1.2.1.2.2") as   
   parameters to the SNMP.Manager API
 * Includes symbol data files for all current IETF MIBs 
@@ -28,8 +25,26 @@ examples below for more details.
 
 == Changes
 
-Changes from version 0.4.0:
-
+Changes for version 0.6.0:
+
+* Added support for sending informs and traps for SNMPv2c and traps for
+  SNMPv1
+* Improved SNMP::Manager#walk so that it can handle missing varbinds
+  when reading tables.  The indexes for a table row read by #walk are now
+  guaranteed to match. 
+* Added to_oid methods to SNMP::OctetString, SNMP::Integer, and
+  SNMP::IpAddress (feature request #2486)
+* Fixed some problems with retrying requests that caused annoying "Request ID
+  mismatch" warnings and caused too few retries to be attempted
+* Thanks to Mark Cotner, Dan Hamlin, Tim Howe, Diana Eichert, Ery Lee,
+  Jan �ge Johnsen, and Jeff Foster for their help and suggestions (and
+  apologies in advance if I have forgotten someone).
+
+Changes for version 0.5.1:
+
+* Fixed bugs #2054 and #2164.  Responses were ignored if they did
+  not come back from the same host that the request was sent to.  This
+  behavior causes problems for some multi-homed hosts.
 * Fixed bugs #1679 (NameError in Manager.get_response()) and #1736 
   (Notifications not included in YAML output).
 * Added Manager.get_value convenience method to get a list of values for a 
@@ -40,7 +55,7 @@ Changes from version 0.4.0:
 * Break out of Manager.walk instead of looping forever if OIDs returned by the 
   remote host are not in ascending order.
 
-Changes from version 0.3.0:
+Changes for version 0.4.0:
 
 * Added support for loading MIBs and using symbolic OID values.
 * Enhanced Manager.walk
@@ -50,7 +65,7 @@ Changes from version 0.3.0:
       processing of results.
 * Some minor improvements to code structure and error messages.
 
-Changes from version 0.2.0:
+Changes for version 0.3.0:
 
 * Added SNMPv1_Trap and SNMPv2_Trap classes
 * Added TrapListener class for receiving v1 and v2 traps
@@ -59,7 +74,7 @@ Changes from version 0.2.0:
 * Defined IpAddress.== and IpAddress.eql? so that IpAddress objects can be
   compared by value
 
-Changes from version 0.1.0:
+Changes for version 0.2.0:
 
 * Added GetBulkRequest
 * Added open and close methods to the Manager class to ensure that
@@ -82,22 +97,21 @@ formats.
 From the .gem file you can install using
 RubyGems[http://rubyforge.org/projects/rubygems].
 
-  gem install snmp-0.5.0.gem
+  gem install snmp-0.6.0.gem
 
 From the .tgz or .zip file you can install using
 setup.rb[http://i.loveruby.net/en/prog/setup.html].  Uncompress the archive
 and then run setup.
 
-  cd snmp-0.5.0
+  cd snmp-0.6.0
   ruby setup.rb (may require root privilege)  
 
 == Testing
 
 This library has received limited testing:
-* The unit tests have been executed with Ruby 1.8.2 on Mac OS X 10.4 and
-  Windows XP.
+* The unit tests have been executed with Ruby 1.8.3 on Mac OS X 10.4.
 * Basic interoperability testing has been done with the
-  net-snmp[http://www.net-snmp.org/] tools, but not much beyond that.
+  net-snmp[http://www.net-snmp.org/] tools.
 
 I'm very interested in hearing about successes or failures on other platforms.
 

data/Rakefile

@@ -9,13 +9,14 @@ Rake::TestTask.new do |test|
 end
 
 # package target
-PKG_VERSION = '0.5.1'
+PKG_VERSION = '0.6.0'
 PKG_FILES = FileList[
     'Rakefile',
     'README',
     'setup.rb',
     'lib/**/*.rb',
     'test/**/test*.rb',
+    'test/**/*.yaml',
     'examples/*.rb',
     'data/**/*.yaml']
 
@@ -39,7 +40,7 @@ end
 
 Rake::GemPackageTask.new(spec) do |package|
     package.need_zip = true
-    package.need_tar = true
+#    package.need_tar = true
 end
 
 # rdoc, clobber_rdoc, rerdoc targets

data/lib/snmp/manager.rb

@@ -22,18 +22,16 @@ class RequestTimeout < RuntimeError; end
 # using other transport types (e.g. TCP)
 #
 class UDPTransport
-    def initialize(host, port)
+    def initialize
         @socket = UDPSocket.open
-        @host = host
-        @port = port
     end
 
     def close
         @socket.close
     end
 
-    def send(data)
-        @socket.send(data, 0, @host, @port)
+    def send(data, host, port)
+        @socket.send(data, 0, host, port)
     end
 
     def recv(max_bytes)
@@ -94,9 +92,9 @@ end
 #
 # See MIB.varbind_list for a description of valid parameter formats.
 #
-# The following modules are loaded by default: "SNMPv2-MIB", "IF-MIB",
-# "IP-MIB", "TCP-MIB", "UDP-MIB".  All of the current IETF MIBs have been
-# imported and are available for loading.
+# The following modules are loaded by default: "SNMPv2-SMI", "SNMPv2-MIB",
+# "IF-MIB", "IP-MIB", "TCP-MIB", "UDP-MIB".  All of the current IETF MIBs
+# have been imported and are available for loading.
 #
 # Additional modules may be imported using the MIB class.  The
 # current implementation of the importing code requires that the
@@ -125,6 +123,7 @@ class Manager
     DefaultConfig = {
         :Host => 'localhost',
         :Port => 161,
+        :TrapPort => 162,
         :Community => 'public',
         :WriteCommunity => nil,
         :Version => :SNMPv2c,
@@ -133,7 +132,7 @@ class Manager
         :Transport => UDPTransport,
         :MaxReceiveBytes => 8000,
         :MibDir => MIB::DEFAULT_MIB_PATH,
-        :MibModules => ["SNMPv2-MIB", "IF-MIB", "IP-MIB", "TCP-MIB", "UDP-MIB"]}
+        :MibModules => ["SNMPv2-SMI", "SNMPv2-MIB", "IF-MIB", "IP-MIB", "TCP-MIB", "UDP-MIB"]}
 
     @@request_id = RequestId.new
     
@@ -153,13 +152,16 @@ class Manager
         end
         @config = DefaultConfig.merge(config)
         @config[:WriteCommunity] = @config[:WriteCommunity] || @config[:Community]
+        @host = @config[:Host]
+        @port = @config[:Port]
+        @trap_port = @config[:TrapPort]
         @community = @config[:Community]
         @write_community = @config[:WriteCommunity]
         @snmp_version = @config[:Version]
-        @max_bytes = @config[:MaxReceiveBytes]
         @timeout = @config[:Timeout]
         @retries = @config[:Retries]
-        @transport = @config[:Transport].new(@config[:Host], @config[:Port])
+        @transport = @config[:Transport].new 
+        @max_bytes = @config[:MaxReceiveBytes]
         @mib = MIB.new
         load_modules(@config[:MibModules], @config[:MibDir])
     end
@@ -264,6 +266,93 @@ class Manager
         try_request(request, @write_community)
     end
 
+    ##
+    # Sends an SNMPv1 style trap.
+    #
+    # enterprise: The enterprise OID from the IANA assigned numbers
+    # (http://www.iana.org/assignments/enterprise-numbers) as a String or
+    # an ObjectId.
+    #
+    # agent_addr: The IP address of the SNMP agent as a String or IpAddress.
+    #
+    # generic_trap: The generic trap identifier.  One of :coldStart,
+    # :warmStart, :linkDown, :linkUp, :authenticationFailure,
+    # :egpNeighborLoss, or :enterpriseSpecific 
+    #
+    # specific_trap: An integer representing the specific trap type for
+    # an enterprise-specific trap.
+    #
+    # timestamp: An integer respresenting the number of hundredths of
+    # a second that this system has been up.
+    #
+    # object_list: A list of additional varbinds to send with the trap. 
+    #
+    # For example:
+    #
+    #   Manager.open(:Version => :SNMPv1) do |snmp|
+    #     snmp.trap_v1(
+    #       "enterprises.9",
+    #       "10.1.2.3",
+    #       :enterpriseSpecific,
+    #        42,
+    #       12345,
+    #       [VarBind.new("1.3.6.1.2.3.4", Integer.new(1))])
+    #  end
+    #
+    def trap_v1(enterprise, agent_addr, generic_trap, specific_trap, timestamp, object_list=[])
+        vb_list = @mib.varbind_list(object_list, :KeepValue)
+        ent_oid = @mib.oid(enterprise)
+        agent_ip = IpAddress.new(agent_addr)
+        specific_int = Integer(specific_trap)
+        ticks = TimeTicks.new(timestamp)
+        trap = SNMPv1_Trap.new(ent_oid, agent_ip, generic_trap, specific_int, ticks, vb_list)
+        send_request(trap, @community, @host, @trap_port)
+    end
+    
+    ##
+    # Sends an SNMPv2c style trap.
+    #
+    # sys_up_time: An integer respresenting the number of hundredths of
+    # a second that this system has been up.
+    #
+    # trap_oid: An ObjectId or String with the OID identifier for this
+    # trap.
+    #
+    # object_list: A list of additional varbinds to send with the trap. 
+    #
+    def trap_v2(sys_up_time, trap_oid, object_list=[])
+        vb_list = create_trap_vb_list(sys_up_time, trap_oid, object_list)
+        trap = SNMPv2_Trap.new(@@request_id.next, vb_list)
+        send_request(trap, @community, @host, @trap_port)
+    end
+                
+    ##
+    # Sends an inform request using the supplied varbind list. 
+    #
+    # sys_up_time: An integer respresenting the number of hundredths of
+    # a second that this system has been up.
+    #
+    # trap_oid: An ObjectId or String with the OID identifier for this
+    # inform request.
+    #
+    # object_list: A list of additional varbinds to send with the inform. 
+    #
+    def inform(sys_up_time, trap_oid, object_list=[])
+        vb_list = create_trap_vb_list(sys_up_time, trap_oid, object_list)
+        request = InformRequest.new(@@request_id.next, vb_list)
+        try_request(request, @community, @host, @trap_port)
+    end
+    
+    ##
+    # Helper method for building VarBindList for trap and inform requests.
+    #
+    def create_trap_vb_list(sys_up_time, trap_oid, object_list)
+        vb_args = @mib.varbind_list(object_list, :KeepValue)
+        uptime_vb = VarBind.new(SNMP::SYS_UP_TIME_OID, TimeTicks.new(sys_up_time.to_int))
+        trap_vb = VarBind.new(SNMP::SNMP_TRAP_OID_OID, @mib.oid(trap_oid))
+        VarBindList.new([uptime_vb, trap_vb, *vb_args])
+    end
+    
     ##
     # Walks a list of ObjectId or VarBind objects using get_next until
     # the response to the first OID in the list reaches the end of its
@@ -288,31 +377,65 @@ class Manager
     #     end
     #   end
     #
-    def walk(object_list)
+    # The index_column identifies the column that will provide the index
+    # for each row.  This information is used to deal with "holes" in a
+    # table (when a row is missing a varbind for one column).  A missing
+    # varbind is replaced with a varbind with the value NoSuchInstance.
+    #
+    # Note: If you are getting back rows where all columns have a value of
+    # NoSuchInstance then your index column is probably missing one of the
+    # rows.  Choose an index column that includes all indexes for the table.
+    # 
+    def walk(object_list, index_column=0)
         raise ArgumentError, "expected a block to be given" unless block_given?
-        varbind_list = @mib.varbind_list(object_list, :NullValue)
-        start_oid = varbind_list.first.name
+        vb_list = @mib.varbind_list(object_list, :NullValue)
+        raise ArgumentError, "index_column is past end of varbind list" if index_column >= vb_list.length
+        is_single_vb = object_list.respond_to?(:to_str) ||
+                       object_list.respond_to?(:to_varbind)
+        start_list = vb_list
+        start_oid = vb_list[index_column].name
         last_oid = start_oid
         loop do
-            varbind_list = get_next(varbind_list).varbind_list
-            first_vb = varbind_list.first
-            break if EndOfMibView == first_vb.value 
-            stop_oid = first_vb.name
+            vb_list = get_next(vb_list).vb_list
+            index_vb = vb_list[index_column]
+            break if EndOfMibView == index_vb.value 
+            stop_oid = index_vb.name
             if stop_oid <= last_oid
                 warn "OIDs are not increasing, #{last_oid} followed by #{stop_oid}"
                 break
             end
             break unless stop_oid.subtree_of?(start_oid)
             last_oid = stop_oid
-            if object_list.respond_to?(:to_str) ||
-               object_list.respond_to?(:to_varbind)
-            then
-                yield first_vb
+            if is_single_vb
+                yield index_vb
             else
-                yield varbind_list
+                vb_list = validate_row(vb_list, start_list, index_column)
+                yield vb_list
+            end
+        end
+    end
+    
+    ##
+    # Helper method for walk.  Checks all of the VarBinds in vb_list to
+    # make sure that the row indices match.  If the row index does not
+    # match the index column, then that varbind is replaced with a varbind
+    # with a value of NoSuchInstance.
+    #
+    def validate_row(vb_list, start_list, index_column)
+        start_vb = start_list[index_column]
+        index_vb = vb_list[index_column]
+        row_index = index_vb.name.index(start_vb.name)
+        vb_list.each_index do |i|
+            if i != index_column
+                expected_oid = start_list[i].name + row_index 
+                if vb_list[i].name != expected_oid
+                    vb_list[i] = VarBind.new(expected_oid, NoSuchInstance)
+                end
             end
         end
+        vb_list
     end
+    private :validate_row
     
     ##
     # Set the next request-id instead of letting it be generated
@@ -334,10 +457,10 @@ class Manager
         module_list.each { |m| @mib.load_module(m, mib_dir) }
     end
     
-    def try_request(request, community=@community)
-        @retries.times do |n|
+    def try_request(request, community=@community, host=@host, port=@port)
+        (@retries + 1).times do |n|
+            send_request(request, community, host, port)
             begin
-                send_request(request, community)
                 timeout(@timeout) do
                     return get_response(request)
                 end
@@ -350,18 +473,22 @@ class Manager
         raise RequestTimeout, "host #{@config[:Host]} not responding", caller
     end
     
-    def send_request(request, community)
+    def send_request(request, community, host, port)
         message = Message.new(@snmp_version, community, request)
-        @transport.send(message.encode)
+        @transport.send(message.encode, host, port)
     end
     
+    ##
+    # Wait until response arrives.  Ignore responses with mismatched IDs;
+    # these responses are typically from previous requests that timed out
+    # or almost timed out.
+    #
     def get_response(request)
-        data = @transport.recv(@max_bytes)
-        message = Message.decode(data)
-        response = message.pdu
-        if (request.request_id != response.request_id)
-            raise RuntimeError, "Request ID mismatch: expected #{request.request_id}, got #{response.request_id}", caller
-        end
+        begin
+            data = @transport.recv(@max_bytes)
+            message = Message.decode(data)
+            response = message.pdu
+        end until request.request_id == response.request_id
         response
     end
 end

data/lib/snmp/pdu.rb

@@ -23,6 +23,9 @@ class InvalidErrorStatus < RuntimeError; end
 class InvalidTrapVarbind < RuntimeError; end
 class InvalidGenericTrap < RuntimeError; end
 
+SYS_UP_TIME_OID = ObjectId.new("1.3.6.1.2.1.1.3.0")
+SNMP_TRAP_OID_OID = ObjectId.new("1.3.6.1.6.3.1.1.4.1.0")
+
 class Message
     attr_reader :version
     attr_reader :community
@@ -68,6 +71,9 @@ class Message
             when GetBulkRequest_PDU_TAG
                 raise InvalidPduTag, "get-bulk not valid for #{version.to_s}" if version != :SNMPv2c
                 pdu = PDU.decode(GetBulkRequest, pdu_data)
+            when InformRequest_PDU_TAG
+                raise InvalidPduTag, "inform not valid for #{version.to_s}" if version != :SNMPv2c
+                pdu = PDU.decode(InformRequest, pdu_data)
             when SNMPv2_Trap_PDU_TAG
                 raise InvalidPduTag, "SNMPv2c-trap not valid for #{version.to_s}" if version != :SNMPv2c
                 pdu = PDU.decode(SNMPv2_Trap, pdu_data)
@@ -253,9 +259,8 @@ class SNMPv2_Trap < PDU
     # Throws InvalidTrapVarbind if the sysUpTime varbind is not present.
     #
     def sys_up_time
-        sys_up_time_oid = ObjectId.new("1.3.6.1.2.1.1.3.0")
         varbind = @varbind_list[0]
-        if varbind && (varbind.name == sys_up_time_oid)
+        if varbind && (varbind.name == SYS_UP_TIME_OID)
             return varbind.value
         else
             raise InvalidTrapVarbind, "Expected sysUpTime.0, found " + varbind.to_s
@@ -268,9 +273,8 @@ class SNMPv2_Trap < PDU
     # Throws InvalidTrapVarbind if the snmpTrapOID varbind is not present.
     #
     def trap_oid
-        snmp_trap_oid_oid = ObjectId.new("1.3.6.1.6.3.1.1.4.1.0")
         varbind = @varbind_list[1]
-        if varbind && (varbind.name == snmp_trap_oid_oid)
+        if varbind && (varbind.name == SNMP_TRAP_OID_OID)
             return varbind.value
         else
             raise InvalidTrapVarbind, "Expected snmpTrapOID.0, found " + varbind.to_s 
@@ -278,6 +282,16 @@ class SNMPv2_Trap < PDU
     end
 end
 
+##
+# The PDU class for SNMPv2 Inform notifications.  This class is identical
+# to SNMPv2_Trap.
+#
+class InformRequest < SNMPv2_Trap
+    def encode
+        encode_pdu(InformRequest_PDU_TAG)
+    end
+end
+
 ##
 # The PDU class for traps in SNMPv1.
 #
@@ -294,6 +308,8 @@ class SNMPv1_Trap
     attr_accessor :timestamp
     attr_accessor :varbind_list
     
+    alias :vb_list :varbind_list
+    
     def self.decode(pdu_data)
         oid_data, remainder = decode_object_id(pdu_data)
         enterprise = ObjectId.new(oid_data)