snmp4em 0.2.0

data/Manifest

@@ -0,0 +1,16 @@
+README
+Rakefile
+lib/snmp4em.rb
+lib/snmp4em/common.rb
+lib/snmp4em/handler.rb
+lib/snmp4em/requests/snmp_get_request.rb
+lib/snmp4em/requests/snmp_getbulk_request.rb
+lib/snmp4em/requests/snmp_getnext_request.rb
+lib/snmp4em/requests/snmp_set_request.rb
+lib/snmp4em/requests/snmp_walk_request.rb
+lib/snmp4em/snmp_connection.rb
+lib/snmp4em/snmp_request.rb
+lib/snmp4em/snmp_v1.rb
+lib/snmp4em/snmp_v2.rb
+snmp4em.gemspec
+Manifest

data/README

@@ -0,0 +1,156 @@
+= SNMP Library for EventMachine
+
+== Summary
+
+This library extends the Ruby-SNMP[http://snmplib.rubyforge.org] to use the asynchronous EventMachine[http://rubyeventmachine.com] library for added performance and scalability. This allows code to scale monitoring applications to access a very high number of devices without the need for complex asynchronous I/O handling.
+
+
+== Features
+
+The initial version 0.1.0 of this software supports:
+
+* SNMP v1 and v2 only
+* SNMP Get, GetNext, GetBulk (v2 only), Set, and Walk requests.
+* Ability to query/set/walk multiple OIDs in parallel.
+
+Future revisions of this library may support:
+
+* Ability to act as an SNMP agent, responding to external queries.
+* Ability to send/receive SNMP traps
+
+There are no plans to support SNMP v3.
+
+
+== Acknowledgements
+
+* The SNMP packet processing is handled by the Ruby-SNMP[http://snmplib.rubyforge.org] library, by David Halliday
+* EventMachine[http://rubyeventmachine.com], by Francis Cianfrocca and Aman Gupta
+* All the helpful folks on the Freenode #eventmachine channel
+
+
+== Examples
+
+A few definitions:
+
+  OID_SYSTEM = "1.3.6.1.2.1.1"
+  OID_SYSNAME = "1.3.6.1.2.1.1.5.0"
+  OID_SYSLOCATION = "1.3.6.1.2.1.1.6.0"
+
+A simple SNMP-GET:
+
+  EM::run do
+	  snmp = SNMP4EM::SNMPv1.new(:host => "192.168.1.1")
+  
+	  request = snmp.get([OID_SYSNAME, OID_SYSLOCATION])
+  
+	  request.callback do |response|
+	    puts "System name = #{response[OID_SYSNAME]}"
+	    puts "System location = #{response[OID_SYSLOCATION]}"
+	  end
+  
+	  request.errback do |error|
+	    puts "GET got error #{error}"
+	  end
+	end
+
+A simple SNMP-GETNEXT:
+
+  EM::run do
+    snmp = SNMP4EM::SNMPv1.new(:host => "192.168.1.1")
+
+    request = snmp.getnext([OID_SYSNAME])
+
+    request.callback do |response|
+      r = response[OID_SYSNAME]
+      puts "The next OID is #{r[0]}, the next value is #{r[1]}"
+    end
+
+    request.errback do |error|
+      puts "GET got error #{error}"
+    end
+  end
+
+A simple SNMP-SET:
+
+  EM::run do
+    snmp = SNMP4EM::SNMPv1.new(:host => "192.168.1.1")
+
+    request = snmp.set({OID_SYSNAME => "My System Name", OID_SYSLOCATION => "My System Location"})
+
+    request.callback do |response|
+      if (response[OID_SYSNAME] == true)
+        puts "System name set successful"
+      else
+        puts "System name set unsuccessful: #{response[OID_SYSNAME]}"
+      end
+
+      if (response[OID_SYSLOCATION] == true)
+        puts "System location set successful"
+      else
+        puts "System location set unsuccessful: #{response[OID_SYSLOCATION]}"
+      end
+    end
+
+    request.errback do |error|
+      puts "GET got error #{error}"
+    end
+  end
+
+A simple SNMP-WALK:
+
+  EM::run do
+    snmp = SNMP4EM::SNMPv1.new(:host => "192.168.1.1")
+
+    request = snmp.walk([OID_SYSTEM])
+
+    request.callback do |response|
+      if (response[OID_SYSTEM].is_a? Array)
+        response[OID_SYSTEM].each do |vb|
+          puts "#{vb[0]} = #{vb[1]}"
+        end
+      else
+        puts "Got error: #{response[OID_SYSTEM]}"
+      end
+    end
+
+    request.errback do |error|
+      puts "GET got error #{error}"
+    end
+  end
+
+A simple SNMP-GET-BULK:
+
+  EM::run do
+    snmp = SNMP4EM::SNMPv2.new(:host => "192.168.1.1")
+
+    request = snmp.getbulk([OID_SYSTEM])
+
+    request.callback do |response|
+      if (response[OID_SYSTEM].is_a? Array)
+        response[OID_SYSTEM].each do |vb|
+          puts "#{vb[0]} = #{vb[1]}"
+        end
+      else
+        puts "Got error: #{response[OID_SYSTEM]}"
+      end
+    end
+
+    request.errback do |error|
+      puts "GET got error #{error}"
+    end
+  end
+
+== Change Log
+
+Version 0.1.0:
+
+* Initial deployment, ability to run get/getnext/set/walk requests in parallel
+
+Version 0.2.0:
+
+* Added support for SNMPv2, including GET-BULK operations
+
+== Developer Contact Information
+
+Norman Elton
+normelton@gmail.com

data/lib/snmp4em/common.rb

@@ -0,0 +1,39 @@
+module SNMP #:nodoc:
+  class Null #:nodoc:
+    class << self
+      def rubify
+        nil
+      end
+    end
+  end
+  
+  class OctetString #:nodoc:
+    alias :rubify :to_s
+  end
+  
+  class Integer #:nodoc:
+    alias :rubify :to_i
+  end
+  
+  class ObjectId #:nodoc:
+    alias :rubify :to_s
+  end
+  
+  class IpAddress #:nodoc:
+    alias :rubify :to_s
+  end
+  
+  class ResponseError
+    attr_reader :error_status
+    alias :rubify :error_status #:nodoc:
+    
+    def initialize(error_status) #:nodoc:
+      @error_status = error_status
+    end
+    
+    # String representation of this error
+    def to_s
+      @error_status.to_s
+    end
+  end
+end

data/lib/snmp4em/handler.rb

@@ -0,0 +1,18 @@
+module SNMP4EM
+  module Handler #:nodoc:
+    def receive_data(data)
+      begin
+        message = SNMP::Message.decode(data)
+      rescue Exception => err
+        return
+      end
+      
+      response = message.pdu
+      request_id = response.request_id
+      
+      if (request = SnmpConnection.pending_requests.select{|r| r.snmp_id == request_id}.first)
+        request.handle_response(response)
+      end
+    end
+  end
+end

data/lib/snmp4em/requests/snmp_get_request.rb

@@ -0,0 +1,76 @@
+module SNMP4EM
+  
+  # Returned from SNMP4EM::SNMPv1.get(). This implements EM::Deferrable, so you can hang a callback()
+  # or errback() to retrieve the results.
+
+  class SnmpGetRequest < SnmpRequest
+    attr_reader :snmp_id
+
+    # For an SNMP-GET request, @pending_oids will be a ruby array of SNMP::ObjectNames that need to be fetched. As
+    # responses come back from the agent, this array will be pruned of any error-producing OIDs. Once no errors
+    # are returned, the @responses hash will be populated and returned.
+
+    def initialize(sender, oids, args = {}) #:nodoc:
+      @sender = sender
+      
+      @timeout_timer = nil
+      @timeout_retries = @sender.retries
+      @error_retries = oids.size
+      
+      @version = args[:version] || :SNMPv1
+      @return_raw = args[:return_raw] || false
+      
+      @responses = Hash.new
+      @pending_oids = SNMP::VarBindList.new(oids).collect{|r| r.name}
+
+      init_callbacks
+      send
+    end
+    
+    def handle_response(response) #:nodoc:
+      if (response.error_status == :noError)
+        # No errors, populate the @responses object so it can be returned
+        response.each_varbind do |vb|
+          request_oid = @pending_oids.shift
+          @responses[request_oid.to_s] = vb.value
+        end
+      
+      else
+        # Got an error, remove that oid from @pending_oids so we can try again
+        error_oid = @pending_oids.delete_at(response.error_index - 1)
+        @responses[error_oid.to_s] = SNMP::ResponseError.new(response.error_status)
+      end
+      
+      if (@pending_oids.empty? || @error_retries.zero?)
+        until @pending_oids.empty?
+          error_oid = @pending_oids.shift
+          @responses[error_oid.to_s] = SNMP::ResponseError.new(:genErr)
+        end
+        
+        @responses.each_pair do |oid, value|
+          @responses[oid] = value.rubify if (!@return_raw && value.respond_to?(:rubify))
+        end
+        
+        # Send the @responses back to the requester, we're done!
+        succeed @responses
+      else
+        @error_retries -= 1
+        send
+      end
+    end
+
+    private
+
+    def send
+      # Send the contents of @pending_oids
+
+      @snmp_id = generate_snmp_id
+
+      vb_list = SNMP::VarBindList.new(@pending_oids)
+      request = SNMP::GetRequest.new(@snmp_id, vb_list)
+      message = SNMP::Message.new(@version, @sender.community_ro, request)
+
+      super(message)
+    end
+  end  
+end

data/lib/snmp4em/requests/snmp_getbulk_request.rb

@@ -0,0 +1,103 @@
+module SNMP4EM
+  
+  # Returned from SNMP4EM::SNMPv1.get(). This implements EM::Deferrable, so you can hang a callback()
+  # or errback() to retrieve the results.
+
+  class SnmpGetBulkRequest < SnmpRequest
+    attr_reader :snmp_id
+
+    # For an SNMP-GETBULK request, @pending_oids will be a ruby array of SNMP::ObjectNames that need to be fetched. As
+    # responses come back from the agent, this array will be pruned of any error-producing OIDs. Once no errors
+    # are returned, the @responses hash will be populated and returned.
+
+    def initialize(sender, oids, args = {}) #:nodoc:
+      @sender = sender
+      
+      @timeout_timer = nil
+      @timeout_retries = @sender.retries
+      @error_retries = oids.size
+      
+      @version = args[:version] || :SNMPv2c
+      @return_raw = args[:return_raw] || false
+      
+      @nonrepeaters = args[:nonrepeaters] || 0
+      @maxrepetitions = args[:maxrepetitions] || 10
+      
+      @responses = Hash.new
+      @pending_oids = SNMP::VarBindList.new(oids).collect{|r| r.name}
+
+      init_callbacks
+      send
+    end
+    
+    def handle_response(response) #:nodoc:
+      if (response.error_status == :noError)
+        # No errors, populate the @responses object so it can be returned
+
+        @nonrepeaters.times do |i|
+          request_oid = @pending_oids.shift
+          response_vb = response.vb_list[i]
+
+          @responses[request_oid.to_s] = [[response_vb.name, response_vb.value]]
+        end
+
+        (@nonrepeaters ... response.vb_list.size).each do |i|
+          request_oid = @pending_oids[(i - @nonrepeaters) % @pending_oids.size]
+          response_vb = response.vb_list[i]
+          
+          @responses[request_oid.to_s] ||= Array.new
+          @responses[request_oid.to_s] << [response_vb.name, response_vb.value]
+        end
+        
+        @pending_oids.clear
+        
+      else
+        # Got an error, remove that oid from @pending_oids so we can try again
+        error_oid = @pending_oids.delete_at(response.error_index - 1)
+        @responses[error_oid.to_s] = SNMP::ResponseError.new(response.error_status)
+      end
+      
+      if (@pending_oids.empty? || @error_retries.zero?)
+        until @pending_oids.empty?
+          error_oid = @pending_oids.shift
+          @responses[error_oid.to_s] = SNMP::ResponseError.new(:genErr)
+        end
+        
+        if (!@return_raw)
+          @responses.each_pair do |search_oid, values|
+            values.collect! do |oid_value|
+              oid_value[1] = oid_value[1].rubify if oid_value[1].respond_to?(:rubify)
+              oid_value
+            end
+          
+            @responses[search_oid] = values
+          end
+        end
+        
+        # Send the @responses back to the requester, we're done!
+        succeed @responses
+      else
+        @error_retries -= 1
+        send
+      end
+    end
+
+    private
+
+    def send
+      # Send the contents of @pending_oids
+
+      @snmp_id = generate_snmp_id
+
+      vb_list = SNMP::VarBindList.new(@pending_oids)
+      request = SNMP::GetBulkRequest.new(@snmp_id, vb_list)
+      
+      request.max_repetitions = @maxrepetitions
+      request.non_repeaters = @nonrepeaters
+      
+      message = SNMP::Message.new(@version, @sender.community_ro, request)
+
+      super(message)
+    end
+  end  
+end

data/lib/snmp4em/requests/snmp_getnext_request.rb

@@ -0,0 +1,80 @@
+module SNMP4EM
+
+  # Returned from SNMP4EM::SNMPv1.getnext(). This implements EM::Deferrable, so you can hang a callback()
+  # or errback() to retrieve the results.
+
+  class SnmpGetNextRequest < SnmpRequest
+    attr_reader :snmp_id
+
+    # For an SNMP-GETNEXT request, @pending_oids will be a ruby array of SNMP::ObjectNames that need to be fetched. As
+    # responses come back from the agent, this array will be pruned of any error-producing OIDs. Once no errors
+    # are returned, the @responses hash will be populated and returned. The values of the hash will consist of a
+    # two-element array, in the form of [OID, VALUE], showing the next oid & value.
+
+    def initialize(sender, oids, args = {}) #:nodoc:
+      @sender = sender
+      
+      @timeout_timer = nil
+      @timeout_retries = @sender.retries
+      @error_retries = oids.size
+      
+      @return_raw = args[:return_raw] || false
+      
+      @responses = Hash.new
+      @pending_oids = SNMP::VarBindList.new(oids).collect{|r| r.name}
+
+      init_callbacks
+      send
+    end
+    
+    def handle_response(response) #:nodoc:
+      if (response.error_status == :noError)
+        # No errors, populate the @responses object so it can be returned
+        response.each_varbind do |vb|
+          request_oid = @pending_oids.shift
+          @responses[request_oid.to_s] = [vb.name, vb.value]
+        end
+      
+      else
+        # Got an error, remove that oid from @pending_oids so we can try again
+        error_oid = @pending_oids.delete_at(response.error_index - 1)
+        @responses[error_oid.to_s] = SNMP::ResponseError.new(response.error_status)
+      end
+      
+      if (@pending_oids.empty? || @error_retries.zero?)
+        until @pending_oids.empty?
+          error_oid = @pending_oids.shift
+          @responses[error_oid.to_s] = SNMP::ResponseError.new(:genErr)
+        end
+
+        @responses.each_pair do |oid, value|
+          if value.is_a? Array
+            @responses[oid][1] = value[1].rubify if (!@return_raw && value[1].respond_to?(:rubify))
+          else
+            @responses[oid] = value.rubify if (!@return_raw && value.respond_to?(:rubify))
+          end
+        end
+        
+        # Send the @responses back to the requester, we're done!
+        succeed @responses
+      else
+        @error_retries -= 1
+        send
+      end
+    end
+
+    private
+    
+    def send #:nodoc:
+      # Send the contents of @pending_oids
+
+      @snmp_id = generate_snmp_id
+
+      vb_list = SNMP::VarBindList.new(@pending_oids)
+      request = SNMP::GetNextRequest.new(@snmp_id, vb_list)
+      message = SNMP::Message.new(:SNMPv1, @sender.community_ro, request)
+      
+      super(message)
+    end
+  end  
+end

data/lib/snmp4em/requests/snmp_set_request.rb

@@ -0,0 +1,90 @@
+module SNMP4EM
+
+  # Returned from SNMP4EM::SNMPv1.set(). This implements EM::Deferrable, so you can hang a callback()
+  # or errback() to retrieve the results.
+
+  class SnmpSetRequest < SnmpRequest
+    attr_reader :snmp_id
+
+    # For an SNMP-SET request, @pending_varbinds will by an SNMP::VarBindList, initially populated from the
+    # provided oids hash. Variables can be passed as specific types from the SNMP library (i.e. SNMP::IpAddress)
+    # or as ruby native objects, in which case they will be cast into the appropriate SNMP object. As responses
+    # are returned, the @pending_varbinds object will be pruned of any error-producing varbinds. Once no errors
+    # are produced, the @responses object is populated and returned.
+
+    def initialize(sender, oids, args = {}) #:nodoc:
+      @sender = sender
+      
+      @timeout_timer = nil
+      @timeout_retries = @sender.retries
+      @error_retries = oids.size
+      
+      @return_raw = args[:return_raw] || false
+      
+      @responses = Hash.new
+      @pending_varbinds = SNMP::VarBindList.new()
+      
+      oids.each_pair do |oid,value|
+        if value.is_a? Integer
+          snmp_value = SNMP::Integer.new(value)
+        elsif value.is_a? String
+          snmp_value = SNMP::OctetString.new(value)
+        end
+        
+        @pending_varbinds << SNMP::VarBind.new(oid,snmp_value)
+      end
+
+      init_callbacks
+      send
+    end
+    
+    def handle_response(response) #:nodoc:
+      if (response.error_status == :noError)
+        # No errors, set any remaining varbinds to true
+        response.each_varbind do |vb|
+          response_vb = @pending_varbinds.shift
+          @responses[response_vb.name.to_s] = true
+        end
+      
+      else
+        # Got an error, remove that varbind from @pending_varbinds so we can try again
+        error_vb = @pending_varbinds.delete_at(response.error_index - 1)
+        @responses[error_vb.name.to_s] = SNMP::ResponseError.new(response.error_status)
+      end
+      
+      if (@pending_varbinds.empty? || @error_retries.zero?)
+        until @pending_varbinds.empty?
+          error_vb = @pending_varbinds.shift
+          @responses[error_vb.name.to_s] = SNMP::ResponseError.new(:genErr)
+        end
+
+        unless @return_raw
+          @responses.each_pair do |oid, value|
+            @responses[oid] = value.rubify if value.respond_to?(:rubify)
+          end
+        end
+        
+        # Send the @responses back to the requester, we're done!
+        succeed @responses
+      else
+        @error_retries -= 1
+        
+        send
+      end
+    end
+
+    private
+    
+    def send
+      # Send the contents of @pending_varbinds
+      
+      @snmp_id = generate_snmp_id
+
+      vb_list = SNMP::VarBindList.new(@pending_varbinds)
+      request = SNMP::SetRequest.new(@snmp_id, vb_list)
+      message = SNMP::Message.new(:SNMPv1, @sender.community_rw, request)
+      
+      super(message)
+    end
+  end  
+end

data/lib/snmp4em/requests/snmp_walk_request.rb

@@ -0,0 +1,104 @@
+module SNMP4EM
+
+  # Returned from SNMP4EM::SNMPv1.walk(). This implements EM::Deferrable, so you can hang a callback()
+  # or errback() to retrieve the results.
+
+  class SnmpWalkRequest < SnmpRequest
+    attr_reader :snmp_id
+
+    # For an SNMP-WALK request, @pending_oids will be a ruby array of SNMP::ObjectNames that need to be walked.
+    # Note that this library supports walking multiple OIDs in parallel. Once any error-producing OIDs are removed,
+    # a series of SNMP-GETNEXT requests are sent. Each response OID is checked to see if it begins with the walk OID.
+    # If so, the incoming OID/value pair is appended to the @response hash, and will be used in subsequent GETNEXT
+    # requests. Once an OID is returned that does not begin with the walk OID, that walk OID is removed from the
+    # @pending_oids array.
+
+    def initialize(sender, oids, args = {}) #:nodoc:
+      @sender = sender
+      
+      @timeout_timer = nil
+      @timeout_retries = @sender.retries
+      @error_retries = oids.size
+      
+      @return_raw    = args[:return_raw]    || false
+      @max_results   = args[:max_results]   || nil
+      
+      @responses = Hash.new
+      @pending_oids = SNMP::VarBindList.new(oids).collect{|r| r.name}
+
+      init_callbacks
+      send
+    end
+    
+    def handle_response(response) #:nodoc:
+      oids_to_delete = []
+
+      if (response.error_status == :noError)
+        response.varbind_list.each_index do |i|
+          walk_oid = @pending_oids[i]
+          response_vb = response.varbind_list[i]
+          
+          # Initialize the responses array if necessary
+          @responses[walk_oid.to_s] ||= Array.new
+          
+          # If the incoming response-oid begins with the walk-oid, then append the pairing
+          # to the @response array. Otherwise, add it to the list of oids ready to delete
+          if (response_vb.name[0,walk_oid.length] == walk_oid)
+            @responses[walk_oid.to_s] << [response_vb.name, response_vb.value]
+          else
+            # If we were to delete thid oid from @pending_oids now, it would mess up the
+            # @pending_oids[i] call above.
+            oids_to_delete << walk_oid
+          end
+        end
+      
+        @max_results -= 1 unless @max_results.nil?
+      
+      else
+        error_oid = @pending_oids[response.error_index - 1]
+        oids_to_delete << error_oid
+        
+        @responses[error_oid.to_s] = SNMP::ResponseError.new(response.error_status)
+        @error_retries -= 1
+      end
+      
+      oids_to_delete.each{|oid| @pending_oids.delete oid}
+      
+      if (@pending_oids.empty? || (@error_retries < 0) || (@max_results.to_i < 0))
+        @responses.each_pair do |oid, value|
+          @responses[oid] = value.rubify if (!@return_raw && value.respond_to?(:rubify))
+        end
+        
+        # Send the @responses back to the requester, we're done!
+        succeed @responses
+      else
+        send
+      end
+    end
+
+    private
+    
+    def send
+      @snmp_id = generate_snmp_id
+
+      # This oids array will consist of all the oids that need to be getnext'd
+      oids = Array.new
+      
+      @pending_oids.each do |oid|
+        # If there's already a response for this walk-oid, then use the last returned oid, otherwise
+        # start with the walk-oid.
+        if @responses.has_key?(oid.to_s)
+          oids << @responses[oid.to_s].last.first
+        else
+          oids << oid
+        end
+      end
+
+      vb_list = SNMP::VarBindList.new(oids)
+      request = SNMP::GetNextRequest.new(@snmp_id, vb_list)
+      message = SNMP::Message.new(:SNMPv1, @sender.community_ro, request)
+      
+      super(message)
+    end
+  end  
+end

data/lib/snmp4em/snmp_connection.rb

@@ -0,0 +1,43 @@
+# The SNMP4EM library 
+
+module SNMP4EM
+  class SnmpConnection
+    @pending_requests = []
+    @socket = nil
+    
+    class << self
+      attr_reader :pending_requests
+      attr_reader :socket
+      
+      def init_socket #:nodoc:
+        if @socket.nil?
+          @socket = EM::open_datagram_socket("0.0.0.0", 0, Handler)
+        end
+      end
+    end
+    
+    attr_reader :host, :port, :timeout, :retries
+    
+    # Creates a new object to communicate with SNMPv1 agents. Optionally pass in the following parameters:
+    # *  _host_ - IP/hostname of remote agent (default: 127.0.0.1)
+    # *  _port_ - UDP port on remote agent (default: 161)
+    # *  _community_ - Community string to use (default: public)
+    # *  _community_ro_ - Read-only community string to use for get/getnext/walk operations (default: public)
+    # *  _community_rw_ - Read-write community string to use for set operations (default: public)
+    # *  _timeout_ - Number of seconds to wait before a request times out (default: 1)
+    # *  _retries_ - Number of retries before failing (default: 3)
+    
+    def initialize(args = {})
+      @host         = args[:host]         || "127.0.0.1"
+      @port         = args[:port]         || 161
+      @timeout      = args[:timeout]      || 1
+      @retries      = args[:retries]      || 3
+      
+      self.class.init_socket
+    end
+    
+    def send(message) #:nodoc:
+      self.class.socket.send_datagram message.encode, @host, @port
+    end
+  end
+end

data/lib/snmp4em/snmp_request.rb

@@ -0,0 +1,40 @@
+module SNMP4EM
+  class SnmpRequest #:nodoc:
+    include EM::Deferrable
+    
+    def generate_snmp_id
+      begin
+        snmp_id = rand(1073741823)  # Largest Fixnum
+      end until (SnmpConnection.pending_requests.select{|r| r.snmp_id == snmp_id}.empty?)        
+
+      return snmp_id
+    end
+
+    def init_callbacks
+      self.callback do
+        SnmpConnection.pending_requests.delete_if {|r| r.snmp_id == @snmp_id}
+        @timeout_timer.cancel
+      end
+      
+      self.errback do
+        SnmpConnection.pending_requests.delete_if {|r| r.snmp_id == @snmp_id}
+        @timeout_timer.cancel
+      end
+    end
+
+    def send(msg)
+      @sender.send msg
+
+      @timeout_timer.cancel if @timeout_timer.is_a?(EM::Timer)
+
+      @timeout_timer = EM::Timer.new(@sender.timeout) do
+        if (@timeout_retries > 0)
+          send
+          @timeout_retries -= 1
+        else
+          fail("timeout")
+        end
+      end
+    end
+  end
+end

data/lib/snmp4em/snmp_v1.rb

@@ -0,0 +1,82 @@
+# The SNMP4EM library 
+
+module SNMP4EM
+  class SNMPv1 < SnmpConnection
+    attr_reader :community_ro, :community_rw
+    
+    # Creates a new object to communicate with SNMPv1 agents. Optionally pass in the following parameters:
+    # *  _host_ - IP/hostname of remote agent (default: 127.0.0.1)
+    # *  _port_ - UDP port on remote agent (default: 161)
+    # *  _community_ - Community string to use (default: public)
+    # *  _community_ro_ - Read-only community string to use for get/getnext/walk operations (default: public)
+    # *  _community_rw_ - Read-write community string to use for set operations (default: public)
+    # *  _timeout_ - Number of seconds to wait before a request times out (default: 1)
+    # *  _retries_ - Number of retries before failing (default: 3)
+    
+    def initialize(args = {})
+      super(args)
+      
+      @community_ro = args[:community_ro] || args[:community] || "public"
+      @community_rw = args[:community_rw] || args[:community] || "public"
+    end
+    
+    # Sends an SNMP-GET request to the remote agent for all OIDs specified in the _oids_ array. Returns a SnmpGetRequest object,
+    # which implements EM::Deferrable. From there, implement a callback/errback to fetch the result. On success, the result will be
+    # a hash, mapping requested OID values to results.
+    # 
+    # Optional arguments can be passed into _args_, including:
+    # *  _return_raw_ - Return objects and errors as their raw SNMP types, such as SNMP::Integer instead of native Ruby integers, SNMP::OctetString instead of native Ruby strings, etc. (default: false)
+ 
+    def get(oids, args = {})
+      request = SnmpGetRequest.new(self, oids, args.merge(:version => :SNMPv1))
+      SnmpConnection.pending_requests << request
+      return request
+    end
+
+    # Sends an SNMP-GETNEXT request to the remote agent for all OIDs specified in the _oids_ array. Returns a SnmpGetRequest object,
+    # which implements EM::Deferrable. From there, implement a callback/errback to fetch the result. On success, the result will be
+    # a hash, mapping requested OID values to two-element arrays consisting of [_next_oid_ , _next_value_]. Any values that produced an
+    # error will map to a symbol representing the error.
+    # 
+    # Optional arguments can be passed into _args_, including:
+    # *  _return_raw_ - Return objects and errors as their raw SNMP types, such as SNMP::Integer instead of native Ruby integers, SNMP::OctetString instead of native Ruby strings, etc. (default: false)
+
+    def getnext(oids, args = {})
+      request = SnmpGetNextRequest.new(self, oids, args.merge(:version => :SNMPv1))
+      SnmpConnection.pending_requests << request
+      return request
+    end
+
+    # Sends an SNMP-SET request to the remote agent for all OIDs specified in the _oids_ hash. The hash must map OID values to requested
+    # values. Values can either be specified as Ruby native strings/integers, or as SNMP-specific classes (SNMP::IpAddress, etc).
+    # Returns a SnmpSetRequest object, which implements EM::Deferrable. From there, implement a callback/errback to fetch the result.
+    # On success, the result will be a hash, mapping requested OID values to the returned value from the agent. Any values that were stored
+    # successfully will map to _true_, otherwise, the value will map to a symbol representing the error.
+    # 
+    # Optional arguments can be passed into _args_, including:
+    # *  _return_raw_ - Return error objects as SNMP::ResponseError instead of a symbol
+
+    def set(oids, args = {})
+      request = SnmpSetRequest.new(self, oids, args.merge(:version => :SNMPv1))
+      SnmpConnection.pending_requests << request
+      return request
+    end
+
+    # Sends a series of SNMP-GETNEXT requests to simulate an SNMP "walk" operation. Given an OID prefix, the library will keep requesting the
+    # next OID until that returned OID does not begin with the requested prefix. This gives the ability to retrieve entire portions of the
+    # SNMP tree in one "operation". Multiple OID prefixes can be passed into the _oids_ array, and will be fetched in parallel. The function returns
+    # a SnmpWalkRequest object, which implements EM::Deferrable. From there, implement a callback/errback to fetch the result. On success, the
+    # result will be a hash, mapping requested OID prefixes to the returned value. Successful walks will be mapped to an array of two-element arrays,
+    # each of which consists of [_oid_ , _value_]. Unsuccessful walks will be mapped to a symbol representing the error.
+
+    # Optional arguments can be passed into _args_, including:
+    # *  _return_raw_ - Return objects and errors as their raw SNMP types, such as SNMP::Integer instead of native Ruby integers, SNMP::OctetString instead of native Ruby strings, etc. (default: false)
+    # *  _max_results_ - Maximum number of results to be returned for any single OID prefix (default: nil = unlimited)
+
+    def walk(oids, args = {})
+      request = SnmpWalkRequest.new(self, oids, args.merge(:version => :SNMPv1))
+      SnmpConnection.pending_requests << request
+      return request
+    end
+  end
+end

data/lib/snmp4em/snmp_v2.rb

@@ -0,0 +1,104 @@
+# The SNMP4EM library 
+
+module SNMP4EM
+  class SNMPv2 < SnmpConnection
+    attr_reader :community_ro, :community_rw
+    
+    # Creates a new object to communicate with SNMPv1 agents. Optionally pass in the following parameters:
+    # *  _host_ - IP/hostname of remote agent (default: 127.0.0.1)
+    # *  _port_ - UDP port on remote agent (default: 161)
+    # *  _community_ - Community string to use (default: public)
+    # *  _community_ro_ - Read-only community string to use for get/getnext/walk operations (default: public)
+    # *  _community_rw_ - Read-write community string to use for set operations (default: public)
+    # *  _timeout_ - Number of seconds to wait before a request times out (default: 1)
+    # *  _retries_ - Number of retries before failing (default: 3)
+    
+    def initialize(args = {})
+      super(args)
+      
+      @community_ro = args[:community_ro] || args[:community] || "public"
+      @community_rw = args[:community_rw] || args[:community] || "public"
+    end
+    
+    # Sends an SNMP-GET request to the remote agent for all OIDs specified in the _oids_ array. Returns a SnmpGetRequest object,
+    # which implements EM::Deferrable. From there, implement a callback/errback to fetch the result. On success, the result will be
+    # a hash, mapping requested OID values to results.
+    # 
+    # Optional arguments can be passed into _args_, including:
+    # *  _return_raw_ - Return objects and errors as their raw SNMP types, such as SNMP::Integer instead of native Ruby integers, SNMP::OctetString instead of native Ruby strings, etc. (default: false)
+ 
+    def get(oids, args = {})
+      request = SnmpGetRequest.new(self, oids, args.merge(:version => :SNMPv2c))
+      SnmpConnection.pending_requests << request
+      return request
+    end
+
+    # Sends an SNMP-GETNEXT request to the remote agent for all OIDs specified in the _oids_ array. Returns a SnmpGetRequest object,
+    # which implements EM::Deferrable. From there, implement a callback/errback to fetch the result. On success, the result will be
+    # a hash, mapping requested OID values to two-element arrays consisting of [_next_oid_ , _next_value_]. Any values that produced an
+    # error will map to a symbol representing the error.
+    # 
+    # Optional arguments can be passed into _args_, including:
+    # *  _return_raw_ - Return objects and errors as their raw SNMP types, such as SNMP::Integer instead of native Ruby integers, SNMP::OctetString instead of native Ruby strings, etc. (default: false)
+
+    def getnext(oids, args = {})
+      request = SnmpGetNextRequest.new(self, oids, args.merge(:version => :SNMPv2c))
+      SnmpConnection.pending_requests << request
+      return request
+    end
+
+    # Sends an SNMP-SET request to the remote agent for all OIDs specified in the _oids_ hash. The hash must map OID values to requested
+    # values. Values can either be specified as Ruby native strings/integers, or as SNMP-specific classes (SNMP::IpAddress, etc).
+    # Returns a SnmpSetRequest object, which implements EM::Deferrable. From there, implement a callback/errback to fetch the result.
+    # On success, the result will be a hash, mapping requested OID values to the returned value from the agent. Any values that were stored
+    # successfully will map to _true_, otherwise, the value will map to a symbol representing the error.
+    # 
+    # Optional arguments can be passed into _args_, including:
+    # *  _return_raw_ - Return error objects as SNMP::ResponseError instead of a symbol
+
+    def set(oids, args = {})
+      request = SnmpSetRequest.new(self, oids, args.merge(:version => :SNMPv2c))
+      SnmpConnection.pending_requests << request
+      return request
+    end
+
+    # Sends a series of SNMP-GETNEXT requests to simulate an SNMP "walk" operation. Given an OID prefix, the library will keep requesting the
+    # next OID until that returned OID does not begin with the requested prefix. This gives the ability to retrieve entire portions of the
+    # SNMP tree in one "operation". Multiple OID prefixes can be passed into the _oids_ array, and will be fetched in parallel. The function returns
+    # a SnmpWalkRequest object, which implements EM::Deferrable. From there, implement a callback/errback to fetch the result. On success, the
+    # result will be a hash, mapping requested OID prefixes to the returned value. Successful walks will be mapped to an array of two-element arrays,
+    # each of which consists of [_oid_ , _value_]. Unsuccessful walks will be mapped to a symbol representing the error.
+
+    # Optional arguments can be passed into _args_, including:
+    # *  _return_raw_ - Return objects and errors as their raw SNMP types, such as SNMP::Integer instead of native Ruby integers, SNMP::OctetString instead of native Ruby strings, etc. (default: false)
+    # *  _max_results_ - Maximum number of results to be returned for any single OID prefix (default: nil = unlimited)
+
+    def walk(oids, args = {})
+      request = SnmpWalkRequest.new(self, oids, args.merge(:version => :SNMPv2c))
+      SnmpConnection.pending_requests << request
+      return request
+    end
+    
+    # Sends an SNMPv2 GET-BULK request to fetch multiple OID-value pairings simultaneously. This produces similar results to an SNMP-WALK using a single
+    # request/response transaction (SNMP-WALK is actually an inefficient series of GET-NEXTs). Multiple OIDs can be passed into the _oids_ array. Two
+    # additional parameters control how this list is processed. Setting the parameter _nonrepeaters_ to value _N_ indicates that the first _N_ OIDs will
+    # fetch a single value. This is identical to running a single GET-NEXT for the OID. Any remaining OIDs will fetch multiple values. The number of values
+    # fetched is controlled by the parameter _maxrepetitions_. The function returns a SnmpGetBulkRequest object, which implements EM::Deferrable. From there,
+    # implement a callback/errback to fetch the result. On success, the result will be a hash, mapping requested OID prefixes to the returned value.
+    # Successful fetches will be mapped to an array of two-element arrays, each of which consists of [_oid_ , _value_]. Unsuccessful fetches will be mapped to a
+    # symbol representing the error.
+    
+    # For more information, see http://tools.ietf.org/html/rfc1905#section-4.2.3
+    
+    # Optional arguments can be passed into _args_, including:
+    # *  _return_raw_ - Return objects and errors as their raw SNMP types, such as SNMP::Integer instead of native Ruby integers, SNMP::OctetString instead of native Ruby strings, etc. (default: false)
+    # *  _nonrepeaters_ - Number of OIDs passed to which exactly one result will be returned
+    # *  _maxrepetitions_ - Number of OID-value pairs to be returned for each OID
+
+    def getbulk(oids, args = {})
+      request = SnmpGetBulkRequest.new(self, oids, args.merge(:version => :SNMPv2c))
+      SnmpConnection.pending_requests << request
+      return request
+    end
+  end
+end

data/lib/snmp4em.rb

@@ -0,0 +1,15 @@
+$:.unshift File.expand_path(File.dirname(File.expand_path(__FILE__)))
+
+require 'eventmachine'
+require 'snmp'
+require 'snmp4em/common'
+require 'snmp4em/handler'
+require 'snmp4em/snmp_connection'
+require 'snmp4em/snmp_v1'
+require 'snmp4em/snmp_v2'
+require 'snmp4em/snmp_request'
+require 'snmp4em/requests/snmp_get_request'
+require 'snmp4em/requests/snmp_getbulk_request'
+require 'snmp4em/requests/snmp_getnext_request'
+require 'snmp4em/requests/snmp_set_request'
+require 'snmp4em/requests/snmp_walk_request'

data/snmp4em.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{snmp4em}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Norman Elton"]
+  s.date = %q{2010-05-16}
+  s.description = %q{A high-performance SNMP engine built on EventMachine and Ruby-SNMP, supporting SNMPv1 and SNMPv2 operations}
+  s.email = %q{normelton@gmail.com}
+  s.extra_rdoc_files = ["README"]
+  s.files = ["lib/snmp4em.rb", "lib/snmp4em/common.rb", "lib/snmp4em/handler.rb", "lib/snmp4em/requests/snmp_get_request.rb", "lib/snmp4em/requests/snmp_getbulk_request.rb", "lib/snmp4em/requests/snmp_getnext_request.rb", "lib/snmp4em/requests/snmp_set_request.rb", "lib/snmp4em/requests/snmp_walk_request.rb", "lib/snmp4em/snmp_request.rb", "lib/snmp4em/snmp_connection.rb", "lib/snmp4em/snmp_v1.rb", "lib/snmp4em/snmp_v2.rb", "snmp4em.gemspec", "Manifest"]
+  s.homepage = %q{http://github.com/normelton/snmp4em}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Snmp4em", "--main", "README"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{snmp4em}
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{A high-performance SNMP engine built on EventMachine and Ruby-SNMP}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: snmp4em
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Norman Elton
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-16 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: A high-performance SNMP engine built on EventMachine and Ruby-SNMP, supporting SNMPv1 and SNMPv2 operations
+email: normelton@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- lib/snmp4em.rb
+- lib/snmp4em/common.rb
+- lib/snmp4em/handler.rb
+- lib/snmp4em/requests/snmp_get_request.rb
+- lib/snmp4em/requests/snmp_getbulk_request.rb
+- lib/snmp4em/requests/snmp_getnext_request.rb
+- lib/snmp4em/requests/snmp_set_request.rb
+- lib/snmp4em/requests/snmp_walk_request.rb
+- lib/snmp4em/snmp_request.rb
+- lib/snmp4em/snmp_connection.rb
+- lib/snmp4em/snmp_v1.rb
+- lib/snmp4em/snmp_v2.rb
+- snmp4em.gemspec
+- Manifest
+- README
+has_rdoc: true
+homepage: http://github.com/normelton/snmp4em
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Snmp4em
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "1.2"
+  version: 
+requirements: []
+
+rubyforge_project: snmp4em
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A high-performance SNMP engine built on EventMachine and Ruby-SNMP
+test_files: []
+