snmp4em 0.3 → 1.0.0

data/README.rdoc

@@ -7,20 +7,29 @@ This gem extends Ruby-SNMP[http://snmplib.rubyforge.org] to use the asynchronous
 
 == Features
 
-Version 0.2.1 supports:
+Version 1.0.0 supports:
 
-* SNMP v1 and v2 only
-* SNMP Get, GetNext, GetBulk (v2 only), Set, and Walk requests.
+* SNMP v1 and v2 
+* SNMP Get, GetNext, Set, and Walk requests. For SNMPv2 clients, GetBulk and WalkBulk
 * 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.
 
 
+== Backwards compatibility
+
+Version 1.0.0 tweaks the return values of a few functions. Please test code thoroughly before upgrading to 1.0.0 in production!
+
+
+== Running tests
+
+This library now includes a full suite of functional tests. They communicate with an SNMP daemon running on the localhost. The library comes with the necessary configuration, but it's much easier to fire up the provided rake task (`rake server`), running in a separate terminal window, before running `rspec`. This works fine on a Mac OS X machine using homebrew (`brew install net-snmp`).
+
+
 == Acknowledgements
 
 * The SNMP packet processing is handled by the Ruby-SNMP[http://snmplib.rubyforge.org] library, by David Halliday
@@ -39,7 +48,7 @@ A few definitions:
 A simple SNMP-GET:
 
   EM.run {
-    snmp = SNMP4EM::Manager.new(:host => "192.168.1.1", :version => :SNMPv1)
+    snmp = SNMP4EM::Manager.new(:host => "192.168.1.1")
   
     request = snmp.get([OID_SYSNAME, OID_SYSLOCATION])
   
@@ -104,12 +113,8 @@ A simple SNMP-WALK:
     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]}"
+      response[OID_SYSTEM].each do |oid, value|
+        puts "#{oid} = #{value}"
       end
     end
 
@@ -118,6 +123,24 @@ A simple SNMP-WALK:
     end
   }
 
+A simple SNMP-BULKWALK:
+
+  EM.run {
+    snmp = SNMP4EM::Manager.new(:host => "192.168.1.1")
+
+    request = snmp.bulkwalk(OID_SYSTEM)
+
+    request.callback do |response|
+      response[OID_SYSTEM].each do |oid, value|
+        puts "#{oid} = #{value}"
+      end
+    end
+
+    request.errback do |error|
+      puts "BULK-WALK got error #{error}"
+    end
+  }
+
 A simple SNMP-GET-BULK:
 
   EM.run {
@@ -126,12 +149,8 @@ A simple SNMP-GET-BULK:
     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]}"
+      response[OID_SYSTEM].each do |oid, value|
+        puts "#{oid} = #{value}"
       end
     end
 
@@ -140,8 +159,17 @@ A simple SNMP-GET-BULK:
     end
   }
 
+
 == Change Log
 
+Version 1.0.0:
+
+* Added SNMPv2 BULKWALK support
+* Added ability to receive SNMP traps / informs
+* Added functional tests (finally!)
+* Moved documentation to Yard
+* Lots of code cleanup
+
 Version 0.2.1:
 
 * Code cleanups, speed boosts

data/lib/snmp4em/extensions/snmp/integer.rb

@@ -1,6 +1,6 @@
-module SNMP #:nodoc:
+module SNMP
 
-  class Integer #:nodoc:
+  class Integer  # @private
     alias :rubify :to_i
   end
 

data/lib/snmp4em/extensions/snmp/ip_address.rb

@@ -1,6 +1,6 @@
-module SNMP #:nodoc:
+module SNMP
 
-  class IpAddress #:nodoc:
+  class IpAddress  # @private
     alias :rubify :to_s
   end
 

data/lib/snmp4em/extensions/snmp/null.rb

@@ -1,6 +1,6 @@
-module SNMP #:nodoc:
+module SNMP
 
-  class Null #:nodoc:
+  class Null  # @private
     class << self
       def rubify
         nil

data/lib/snmp4em/extensions/snmp/object_id.rb

@@ -1,6 +1,6 @@
-module SNMP #:nodoc:
+module SNMP
 
-  class ObjectId #:nodoc:
+  class ObjectId  # @private
     alias :rubify :to_s
   end
 

data/lib/snmp4em/extensions/snmp/octet_string.rb

@@ -1,6 +1,6 @@
-module SNMP #:nodoc:
+module SNMP
 
-  class OctetString #:nodoc:
+  class OctetString   # @private
     alias :rubify :to_s
   end
 

data/lib/snmp4em/extensions/snmp/response_error.rb

@@ -1,11 +1,16 @@
-module SNMP #:nodoc:
+module SNMP
 
   class ResponseError
     attr_reader :error_status
-    alias :rubify :error_status #:nodoc:
+    alias :rubify :error_status
     
-    def initialize(error_status) #:nodoc:
-      @error_status = error_status
+    # Accepts either a string (from SNMP::PDU.error_status) or one of SNMP::EndOfMibView, SNMP::NoSuchObject, or SNMP::NoSuchInstance
+    def initialize(error)
+      if [SNMP::EndOfMibView, SNMP::NoSuchObject, SNMP::NoSuchInstance].include? error
+        @error_status = error.asn1_type.to_sym
+      else
+        @error_status = error.to_sym
+      end
     end
     
     # String representation of this error

data/lib/snmp4em/handler.rb

@@ -1,5 +1,5 @@
 module SNMP4EM
-  class Handler < EventMachine::Connection #:nodoc:
+  class Handler < EventMachine::Connection  # @private
     def receive_data(data)
       begin
         message = SNMP::Message.decode(data)
@@ -10,7 +10,6 @@ module SNMP4EM
       end
       
       response = message.pdu
-      request = Manager.pending_requests[response.request_id]
 
       #
       # in the event of a timeout retry, the request will have been 
@@ -18,8 +17,7 @@ module SNMP4EM
       # request, ignore it.
       #
 
-      if request
-        request.timeout_timer.cancel
+      if request = Manager.pending_requests[response.request_id]
         request.handle_response(response)
       end
     end

data/lib/snmp4em/manager.rb

@@ -1,8 +1,14 @@
 # The SNMP4EM library 
 
 module SNMP4EM
+  # Provides access to send and receive SNMP messages via a UDP socket.
+  #
+  # _Note_ - The methods for actually sending requests are documented in {SNMP4EM::SNMPCommonRequests} and, for
+  # those specific to SNMPv2, {SNMP4EM::SNMPv2cRequests}.
   class Manager
-    include SNMP4EM::CommonRequests
+    include SNMP4EM::SNMPCommonRequests
+
+    MAX_INDEX = 2**31  # @private Largest SNMP Signed INTEGER 
 
     #
     # @pending_requests maps a request's id to its SnmpRequest
@@ -14,21 +20,24 @@ module SNMP4EM
       attr_reader :pending_requests
       attr_reader :socket
       
-      def init_socket #:nodoc:
-        # When the socket is in error state, close the socket and re-open a new one.
+      # Initializes the outgoing socket. Checks to see if it's in an error state, and if so closes and reopens the socket
+      def init_socket
         if !@socket.nil? && @socket.error?
-                @socket.close_connection
-                @socket = nil
+          @socket.close_connection
+          @socket = nil
         end
 
+        @next_index ||= rand(MAX_INDEX)
         @socket ||= EM::open_datagram_socket("0.0.0.0", 0, Handler)
       end
 
+      # Assigns an SNMP ID to an outgoing request so that it can be matched with its incoming response
       def track_request(request)
         @pending_requests.delete(request.snmp_id)
 
         begin
-          request.snmp_id = rand(2**31)  # Largest SNMP Signed INTEGER
+          @next_index = (@next_index + 1) % MAX_INDEX
+          request.snmp_id = @next_index
         end while @pending_requests[request.snmp_id]
 
         @pending_requests[request.snmp_id] = request
@@ -37,14 +46,15 @@ module SNMP4EM
     
     attr_reader :host, :port, :timeout, :retries, :version, :community_ro, :community_rw
     
-    # Creates a new object to communicate with SNMPv1 agents. Optionally pass in the following parameters:
+    # Creates a new object to communicate with SNMP 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)
+    # *  _community_ - Community string to use for all operations (default: public)
+    # *  _community_ro_ - Read-only community string to use for read-only operations (default: public)
+    # *  _community_rw_ - Read-write community string to use for read-write operations (default: public)
     # *  _timeout_ - Number of seconds to wait before a request times out (default: 1)
     # *  _retries_ - Number of retries before failing (default: 3)
+    # *  _version_ - SNMP version, either :SNMPv1 or :SNMPv2c (default: :SNMPv2c)
     
     def initialize(args = {})
       @host    = args[:host]    || "127.0.0.1"
@@ -61,7 +71,7 @@ module SNMP4EM
       self.class.init_socket
     end
     
-    def send(message) #:nodoc:
+    def send(message) # @private
       self.class.socket.send_datagram message.encode, @host, @port
     end
 

data/lib/snmp4em/notification_handler.rb

@@ -0,0 +1,27 @@
+module SNMP4EM
+  class NotificationHandler < EventMachine::Connection  # @private
+    attr_accessor :callbacks
+
+    def post_init
+      @callbacks = []
+    end
+
+    def receive_data(data)
+      source_port, source_ip = Socket.unpack_sockaddr_in(get_peername)
+
+      begin
+        message = SNMP::Message.decode(data)
+      rescue Exception => err
+        return
+      end
+
+      trap = message.pdu
+
+      return unless trap.is_a?(SNMP::SNMPv1_Trap) || trap.is_a?(SNMP::SNMPv2_Trap)
+
+      trap.source_ip = source_ip
+
+      @callbacks.each { |callback| callback.yield(message.pdu) }
+    end
+  end
+end

data/lib/snmp4em/notification_manager.rb

@@ -0,0 +1,23 @@
+module SNMP4EM
+  # Provides access to receive SNMP traps (SNMPv1) and notifications (SNMPv2)
+  class NotificationManager
+    attr_reader :host, :port, :timeout, :retries, :version, :community_ro, :community_rw
+
+    # Creates a new object to communicate with SNMP agents. Optionally pass in the following parameters:
+    # *  _host_ - IP/hostname of local interface on which to listen (default: 127.0.0.1)
+    # *  _port_ - UDP port on which to listen (default: 162)
+    def initialize(args = {})
+      @host    = args[:host]      || "127.0.0.1"
+      @port    = args[:port]      || 162
+
+      @socket = EM::open_datagram_socket(@host, @port, NotificationHandler)
+    end
+
+    # Register a callback that is upon reception of a trap/notification. Multiple callbacks can be
+    # registered. Each will be passed the trap/notification object. It is important to determine whether
+    # it is a SNMP::SNMPv1_Trap or SNMP::SNMPv2_Trap, as each behaves slightly differently.
+    def on_trap &block
+      @socket.callbacks << block
+    end
+  end
+end

data/lib/snmp4em/requests/snmp_bulkwalk_request.rb

@@ -0,0 +1,86 @@
+module SNMP4EM
+
+  # The result of calling {SNMPv2cRequests#bulkwalk}.
+
+  class SnmpBulkWalkRequest < SnmpRequest
+    attr_accessor :snmp_id
+
+    # Used to register a callback that is triggered when the query result is ready. The resulting object is passed as a parameter to the block.
+    def callback &block
+      super
+    end
+
+    # Used to register a callback that is triggered when query fails to complete successfully.
+    def errback &block
+      super
+    end
+
+    def on_init args  # @private
+      @oids.each{|oid| oid.merge!({:next_oid => oid[:requested_oid], :responses => {}})}
+    end
+
+    def handle_response(response)  # @private
+      super
+
+      if response.error_status == :noError
+        vb_list = response.vb_list
+        vb_index = 0
+        curr_pending_oids = pending_oids
+
+        while response_vb = vb_list.shift
+          oid = curr_pending_oids[vb_index % curr_pending_oids.count]
+          response_oid = response_vb.name
+
+          next unless oid[:state] == :pending
+
+          if response_vb.value == SNMP::EndOfMibView
+            oid[:state] = :complete
+
+          elsif ! response_oid.subtree_of?(oid[:requested_oid])
+            oid[:state] = :complete
+          else
+            oid[:responses][response_oid.to_s] = format_value(response_vb)
+            oid[:next_oid] = response_oid
+          end
+
+          vb_index += 1
+        end
+
+      else
+        error_oid = pending_oids[response.error_index - 1]
+        error_oid[:state] = :error
+        error_oid[:error] = SNMP::ResponseError.new(response.error_status)
+      end
+
+      if pending_oids.empty? || (@max_results && @oids.collect{|oid| oid[:responses].count}.max >= @max_results)
+        result = {}
+
+        @oids.each do |oid|
+          requested_oid = oid[:requested_string]
+          result[requested_oid] = oid[:error] || oid[:responses]
+        end
+
+        succeed result
+        return
+      end
+
+      send
+    end
+
+    private
+    
+    def send
+      Manager.track_request(self)
+
+      vb_list = SNMP::VarBindList.new(pending_oids.collect{|oid| oid[:next_oid]})
+      request = SNMP::GetBulkRequest.new(@snmp_id, vb_list)
+      
+      request.max_repetitions = 10
+      request.non_repeaters = 0
+
+      message = SNMP::Message.new(@sender.version, @sender.community_ro, request)
+
+      super(message)
+    end
+  end  
+end

data/lib/snmp4em/requests/snmp_get_request.rb

@@ -1,39 +1,48 @@
 module SNMP4EM
   
-  # This implements EM::Deferrable, so you can hang a callback() or errback() to retrieve the results.
+  # The result of calling {SNMPCommonRequests#get}.
 
   class SnmpGetRequest < SnmpRequest
     attr_accessor :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.
+    # Used to register a callback that is triggered when the query result is ready. The resulting object is passed as a parameter to the block.
+    def callback &block
+      super
+    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
-          value = @return_raw || !vb.value.respond_to?(:rubify) ? vb.value : vb.value.rubify
+    # Used to register a callback that is triggered when query fails to complete successfully.
+    def errback &block
+      super
+    end
 
-          @responses[request_oid.to_s] = value
+    def handle_response(response)  # @private
+      super
+      
+      if response.error_status == :noError
+        pending_oids.zip(response.varbind_list).each do |oid, response_vb|
+          oid[:response] = format_value(response_vb)
+          oid[:state] = :complete
         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)
+        error_oid = pending_oids[response.error_index - 1]
+        error_oid[:state] = :error
+        error_oid[:error] = SNMP::ResponseError.new(response.error_status)
       end
 
-      if @error_retries < 0
-        fail "exhausted all retries"
-      elsif @pending_oids.empty?
-        # Send the @responses back to the requester, we're done!
-        succeed @responses
-      else
-        @error_retries -= 1
-        send
+      if pending_oids.empty?
+        result = {}
+
+        @oids.each do |oid|
+          requested_oid = oid[:requested_string]
+          result[requested_oid] = oid[:error] || oid[:response]
+        end
+
+        succeed result
+        return
       end
+    
+      send
     end
 
     private
@@ -41,9 +50,9 @@ module SNMP4EM
     def send
       Manager.track_request(self)
 
-      # Send the contents of @pending_oids
+      query_oids = @oids.select{|oid| oid[:state] == :pending}.collect{|oid| oid[:requested_oid]}
 
-      vb_list = SNMP::VarBindList.new(@pending_oids)
+      vb_list = SNMP::VarBindList.new(query_oids)
       request = SNMP::GetRequest.new(@snmp_id, vb_list)
       message = SNMP::Message.new(@sender.version, @sender.community_ro, request)
 

data/lib/snmp4em/requests/snmp_getbulk_request.rb

@@ -1,71 +1,73 @@
 module SNMP4EM
   
-  # This implements EM::Deferrable, so you can hang a callback() or errback() to retrieve the results.
+  # The result of calling {SNMPv2Requests#getbulk}.
 
   class SnmpGetBulkRequest < SnmpRequest
     attr_accessor :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.
+    # Used to register a callback that is triggered when the query result is ready. The resulting object is passed as a parameter to the block.
+    def callback &block
+      super
+    end
 
-    def initialize(sender, oids, args = {}) #:nodoc:
-      @nonrepeaters = args[:nonrepeaters] || 0
-      @maxrepetitions = args[:maxrepetitions] || 10
-      
+    # Used to register a callback that is triggered when query fails to complete successfully.
+    def errback &block
       super
     end
+
+    def on_init args  # @private
+      @oids.each_index do |i|
+        @oids[i][:responses] = {}
+        @oids[i][:method] = (i < (args[:non_repeaters] || 0) ? :non_repeating : :repeating)
+      end
+
+      @max_results ||= 10
+    end
     
-    def handle_response(response) #:nodoc:
+    def handle_response(response)  # @private
+      super
+      
+      pending_repeating_oids = pending_oids.select{|oid| oid[:method] == :repeating}
+      pending_non_repeating_oids = pending_oids.select{|oid| oid[:method] == :non_repeating}
+
       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]
+        vb_list = response.vb_list
+        vb_index = 0
 
-          @responses[request_oid.to_s] = [[response_vb.name, response_vb.value]]
+        pending_non_repeating_oids.each do |oid|
+          response_vb = vb_list.shift
+          oid[:responses][response_vb.name.to_s] = format_value(response_vb)
+          oid[:state] = :complete
         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]
+        while response_vb = vb_list.shift
+          oid = pending_repeating_oids[vb_index % pending_repeating_oids.count]
+          oid[:responses][response_vb.name.to_s] = format_value(response_vb) unless response_vb.value == SNMP::EndOfMibView
+          oid[:state] = :complete
+          vb_index += 1
         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)
+        error_oid = pending_oids[response.error_index - 1]
+        error_oid[:state] = :error
+        error_oid[:error] = 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
+      if pending_oids.empty?
+        result = {}
+
+        @oids.each do |oid|
+          requested_oid = oid[:requested_string]
+          result[requested_oid] = oid[:error] || oid[:responses]
         end
-        
-        # Send the @responses back to the requester, we're done!
-        succeed @responses
-      else
-        @error_retries -= 1
-        send
+
+        succeed result
+        return
       end
+
+      send
     end
 
     private
@@ -73,13 +75,11 @@ module SNMP4EM
     def send
       Manager.track_request(self)
 
-      # Send the contents of @pending_oids
-
-      vb_list = SNMP::VarBindList.new(@pending_oids)
+      vb_list = SNMP::VarBindList.new(pending_oids.collect{|oid| oid[:requested_oid]})
       request = SNMP::GetBulkRequest.new(@snmp_id, vb_list)
       
-      request.max_repetitions = @maxrepetitions
-      request.non_repeaters = @nonrepeaters
+      request.max_repetitions = @max_results
+      request.non_repeaters = pending_oids.select{|oid| oid[:method] == :non_repeating}.count
       
       message = SNMP::Message.new(@sender.version, @sender.community_ro, request)