net-snmp 0.2.0 → 0.2.1

data/README.rdoc

@@ -12,7 +12,8 @@ It provides classes for sessions, pdus, varbinds, and more.
 * Supports sending of snmpv1 traps and snmpv2 traps/informs using TrapSession
 * Integrates well with eventmachine, or can be used standalone.
 * In Ruby 1.9, uses fibers behind the scenes to emulate synchronous calls asynchronously
-
+* MIB support
+* Convenience methods such as session.walk, session.get_columns, and session.table
 
 == USAGE
 
@@ -49,7 +50,7 @@ You must call Session.close when you're done with a session to avoid leaking mem
     In the synchronous versions, all session methods raise Net::SNMP:Error on any error.  Timeouts raise Net::SNMP::TimeoutError.
     In the asynchronous versions, the first argument to your callback will be the return status.  Possible values include :success, :timeout, and :send_error.
     If you need the underlying net-snmp session errors, you can call session.errno, session.snmp_err, and session.error_message.
-    
+    PDU errors can be retreived with pdu.errstat, pdu.errindex giving the index of the offending varbind.  See constants.rb for possible errors.
 
 == EXAMPLES
 
@@ -137,6 +138,13 @@ Net::SNMP::OID objects.  For example
 
 For more complex MIB parsing needs, see smi-ffi[http://github.com/mixtli/smi-ffi]
 
+== EXPERIMENTAL THREAD SUPPORT
+If you intent to use threads, you should set:
+
+   Net::SNMP.thread_safe = true
+
+Thread support is experimental and may be dropped.  Let me know if you're using this feature.
+
 == CAVEATS/DISCLAIMER
 
 THIS GEM COULD CRASH YOUR SYSTEM AND EAT YOUR CHILDREN!
@@ -166,7 +174,8 @@ break this gem.  Please let me know if you find bugs or missing features.  Or be
 * Commit, do not mess with rakefile, version, or history.
   (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
+* Bug reports including a failing rspec get priority treatment
 
-== Copyright
+ == Copyright
 
 Copyright (c) 2010 mixtli. See LICENSE for details.

data/lib/net/snmp/constants.rb

@@ -49,7 +49,7 @@ module Net
       # Exception values for SNMPv2 and SNMPv3
       SNMP_NOSUCHOBJECT   = (ASN_CONTEXT | ASN_PRIMITIVE | 0x0)
       SNMP_NOSUCHINSTANCE = (ASN_CONTEXT | ASN_PRIMITIVE | 0x1)
-      SNMP_ENDOFVIEW      = (ASN_CONTEXT | ASN_PRIMITIVE | 0x2)
+      SNMP_ENDOFMIBVIEW      = (ASN_CONTEXT | ASN_PRIMITIVE | 0x2)
 
 
       # PDU types
@@ -71,6 +71,35 @@ module Net
       NETSNMP_CALLBACK_OP_CONNECT           =  4
       NETSNMP_CALLBACK_OP_DISCONNECT        =  5
       
+
+      # Error codes (the value of the field error-status in PDUs)
+
+      # in SNMPv1, SNMPsec, SNMPv2p, SNMPv2c, SNMPv2u, SNMPv2*, and SNMPv3 PDUs
+      SNMP_ERR_NOERROR               = (0)     # XXX  Used only for PDUs?
+      SNMP_ERR_TOOBIG                = (1)
+      SNMP_ERR_NOSUCHNAME            = (2)
+      SNMP_ERR_BADVALUE              = (3)
+      SNMP_ERR_READONLY              = (4)
+      SNMP_ERR_GENERR                = (5)
+
+      # in SNMPv2p, SNMPv2c, SNMPv2u, SNMPv2*, and SNMPv3 PDUs
+      SNMP_ERR_NOACCESS               = (6)
+      SNMP_ERR_WRONGTYPE              = (7)
+      SNMP_ERR_WRONGLENGTH            = (8)
+      SNMP_ERR_WRONGENCODING          = (9)
+      SNMP_ERR_WRONGVALUE             = (10)
+      SNMP_ERR_NOCREATION             = (11)
+      SNMP_ERR_INCONSISTENTVALUE      = (12)
+      SNMP_ERR_RESOURCEUNAVAILABLE    = (13)
+      SNMP_ERR_COMMITFAILED           = (14)
+      SNMP_ERR_UNDOFAILED             = (15)
+      SNMP_ERR_AUTHORIZATIONERROR     = (16)
+      SNMP_ERR_NOTWRITABLE            = (17)
+
+      # in SNMPv2c, SNMPv2u, SNMPv2*, and SNMPv3 PDUs
+      SNMP_ERR_INCONSISTENTNAME       = (18)
+
+
       # SNMP Errors
       SNMPERR_SUCCESS = (0)
       SNMPERR_GENERR = (-1)

data/lib/net/snmp/mib/node.rb

@@ -8,7 +8,7 @@ module Net::SNMP
       class << self
         def get_node(oid)
           if oid.kind_of?(String)
-            oid = Net::SNMP::OID.new(oid)
+            oid = OID.new(oid)
           end
           struct = Wrapper.get_tree(oid.pointer, oid.length_pointer.read_int, Wrapper.get_tree_head().pointer)
           new(struct.pointer)
@@ -30,7 +30,7 @@ module Net::SNMP
 
       def oid
         return @oid if @oid
-        @oid = Net::SNMP::OID.new(label)
+        @oid = OID.new(label)
       end
 
       # actually seems like list is linked backward, so this will retrieve the previous oid numerically

data/lib/net/snmp/oid.rb

@@ -52,6 +52,22 @@ module Net
         node.label + "." + index
       end
    
+      def <=>(o)
+        a = self._packed
+        b = o._packed
+        a <=> b
+      end
+
+      def _packed
+        i = self.to_s.dip
+        i.sub!(/^\./,'')
+        i.gsub!(/ /, '.0')
+        i.replace(i.split('.').map(&:to_i).pack('N*'))
+      end
+
+      def parent_of?(o)
+        o.to_s =~ /^#{self.to_s}\./
+      end
     end
   end
 end

data/lib/net/snmp/pdu.rb

@@ -82,7 +82,6 @@ module Net
       # * +type+ The data type.  Possible values include Net::SNMP::ASN_OCTET_STR, Net::SNMP::ASN_COUNTER, etc.  See constants.rb
       # * +value+  The value of the varbind.  default is nil.
       def add_varbind(options)
-        #puts "adding varbind #{options.inspect}"
         options[:type] ||= case options[:value]
           when String
             Constants::ASN_OCTET_STR
@@ -125,7 +124,7 @@ module Net
             end
         end
 
-        oid = options[:oid].kind_of?(Net::SNMP::OID) ? options[:oid] : Net::SNMP::OID.new(options[:oid])
+        oid = options[:oid].kind_of?(OID) ? options[:oid] : OID.new(options[:oid])
         var_ptr = Wrapper.snmp_pdu_add_variable(@struct.pointer, oid.pointer, oid.length_pointer.read_int, options[:type], value, value_len)
         varbind = Varbind.new(var_ptr)
         #Wrapper.print_varbind(varbind.struct)
@@ -142,6 +141,9 @@ module Net
         Wrapper::snmp_errstring(self.errstat)
       end
 
+      def print_errors
+        puts "errstat = #{self.errstat}, index = #{self.errindex}, message = #{self.error_message}"
+      end
       # Free the pdu
       def free
         Wrapper.snmp_free_pdu(@struct.pointer)

data/lib/net/snmp/session.rb

@@ -33,9 +33,7 @@ module Net
         # * +retries+ - snmp retries.  default = 5
         # Returns:
         # Net::SNMP::Session
-
         def open(options = {})
-          #puts "building session"
           session = new(options)
           if Net::SNMP::thread_safe
             Net::SNMP::Session.lock.synchronize {
@@ -52,7 +50,6 @@ module Net
       end
 
       def initialize(options = {})
-        #puts "in initialize"
         @timeout = options[:timeout] || 1
         @retries = options[:retries] || 5
         @requests = {}
@@ -189,20 +186,17 @@ module Net
         end
       end
 
-
-
-
       def default_max_repeaters
         # We could do something based on transport here.  25 seems safe
         25
       end
 
-
-
       # Raise a NET::SNMP::Error with the session attached
       def error(msg, options = {})
         #Wrapper.snmp_sess_perror(msg, @sess.pointer)
-        raise Error.new({:session => self}.merge(options)), msg
+        err =  Error.new({:session => self}.merge(options))
+        err.print
+        raise err, msg
       end
       
 
@@ -247,6 +241,90 @@ module Net
       alias :poll :select
 
 
+      # Issue repeated getnext requests on each oid passed in until
+      # the result is no longer a child.  Returns a hash with the numeric
+      # oid strings as keys.
+      # XXX work in progress.   only works synchronously (except with EM + fibers).
+      # Need to do better error checking and use getbulk when avaiable.
+      def walk(oidlist)
+        oidlist = [oidlist] unless oidlist.kind_of?(Array)
+        oidlist = oidlist.map {|o| o.kind_of?(OID) ? o : OID.new(o)}
+        all_results = {}
+        base_list = oidlist
+        while(!oidlist.empty? && pdu = get_next(oidlist))
+          debug "==============================================================="
+          debug "base_list = #{base_list}"
+          prev_base = base_list.dup
+          oidlist = []
+          print_errors
+          pdu.print_errors
+          pdu.varbinds.each_with_index do |vb, i|
+            if prev_base[i].parent_of?(vb.oid) && vb.object_type != Constants::SNMP_ENDOFMIBVIEW
+              # Still in subtree.  Store results and add next oid to list
+              debug "adding #{vb.oid} to oidlist"
+              all_results[vb.oid.to_s] = vb.value
+              oidlist << vb.oid
+            else
+              # End of subtree.  Don't add to list or results
+              debug "End of subtree"
+              base_list.delete_at(i)
+              debug "not adding #{vb.oid}"
+            end
+            # If get a pdu error, we can only tell the first failing varbind,
+            # So we remove it and resend all the rest
+            if pdu.error? && pdu.errindex == i + 1
+              oidlist.pop  # remove the bad oid
+              debug "caught error"
+              if pdu.varbinds.size > i+1
+                # recram rest of oids on list
+                ((i+1)..pdu.varbinds.size).each do |j|
+                  debug "j = #{j}"
+                  debug "adding #{j} = #{prev_list[j]}"
+                  oidlist << prev_list[j]
+                end
+                # delete failing oid from base_list
+                base_list.delete_at(i)
+              end
+              break
+            end
+          end
+        end
+        if block_given?
+          yield all_results
+        end
+        all_results
+      end
+
+
+      # Given a list of columns (e.g ['ifIndex', 'ifDescr'], will return a hash with
+      # the indexes as keys and hashes as values.
+      #   puts sess.get_columns(['ifIndex', 'ifDescr']).inspect
+      #   {'1' => {'ifIndex' => '1', 'ifDescr' => 'lo0'}, '2' => {'ifIndex' => '2', 'ifDescr' => 'en0'}}
+      def columns(columns)
+        columns = columns.map {|c| c.kind_of?(OID) ? c : OID.new(c)}
+        walk_hash = walk(columns)
+        results = {}
+        walk_hash.each do |k, v|
+          oid = OID.new(k)
+          results[oid.index] ||= {}
+          results[oid.index][oid.node.label] = v
+        end
+        if block_given?
+          yield results
+        end
+        results
+      end
+
+      # table('ifEntry').  You must pass the direct parent entry.  Calls columns with all
+      # columns in +table_name+
+      def table(table_name, &blk)
+        column_names = MIB::Node.get_node(table_name).children.collect {|c| c.oid }
+        results = columns(column_names)
+        if block_given?
+          yield results
+        end
+        results
+      end
 
       # Send a PDU
       # +pdu+  The Net::SNMP::PDU object to send.  Usually created by Session.get, Session.getnext, etc.
@@ -280,10 +358,9 @@ module Net
       #     puts e.message
       #   end
       def send_pdu(pdu, &callback)
-        #puts "send_pdu #{Fiber.current.inspect}"
         if block_given?
           @requests[pdu.reqid] = callback
-          puts "calling async_send"
+          debug "calling async_send"
           if Wrapper.snmp_sess_async_send(@struct, pdu.pointer, sess_callback, nil) == 0
             error("snmp_get async failed")
           end
@@ -346,11 +423,14 @@ module Net
         get_error
         @snmp_msg
       end
-      
+
+      def print_errors
+        puts "errno: #{errno}, snmp_err: #{@snmp_err}, message: #{@snmp_msg}"
+      end
       private
       def sess_callback
         @sess_callback ||= FFI::Function.new(:int, [:int, :pointer, :int, :pointer, :pointer]) do |operation, session, reqid, pdu_ptr, magic|
-          #puts "in callback #{operation.inspect} #{session.inspect}"
+          debug "in callback #{operation.inspect} #{session.inspect}"
           op = case operation
             when Constants::NETSNMP_CALLBACK_OP_RECEIVED_MESSAGE
               :success
@@ -386,86 +466,7 @@ module Net
           @snmp_msg = msg_ptr.read_pointer.read_string
       end
 
-      public
-      # XXX This needs work.  Need to use getbulk for speed, guess maxrepeaters, etc..
-      # Also need to figure out how we can tell column names from something like ifTable
-      # instead of ifEntry.  Needs to handle errors, there are probably offset problems
-      # in cases of bad data, and various other problems.  Also need to add async support.
-      # Maybe return a hash with index as key?
-      def get_table(table_name, options = {})
-        column_names = options[:columns] || MIB::Node.get_node(table_name).children.collect {|c| c.label }
-        results = []
-
-#        repeat_count = if @version.to_s == '1' || options[:no_getbulk]
-#            1
-#          elsif options[:repeat_count]
-#            options[:repeat_count]
-#          else
-#            (1000 / 36 / (column_names.size + 1)).to_i
-#        end
-#
-#        res = if @version.to_s != '1' && !options[:no_getbulk]
-#          get_bulk(column_names, :max_repetitions => repeat_count)
-#        else
-#          get_next(column_names)
-#        end
-
-
-        first_result = get_next(column_names)
-        oidlist = []
-        good_column_names = []
-        row = {}
-
-        first_result.varbinds.each_with_index do |vb, idx|
-          oid = vb.oid
-          if oid.label[0..column_names[idx].length - 1] == column_names[idx]
-            oidlist << oid.label
-            good_column_names << column_names[idx]
-            row[column_names[idx]] = vb.value
-          end
-        end
-        results << row
-
-        catch :break_main_loop do
-          while(result = get_next(oidlist))
-            oidlist = []
-            row = {}
-            result.varbinds.each_with_index do |vb, idx|
-              #puts "got #{vb.oid.label} #{vb.value.inspect}, type = #{vb.object_type}"
-              row[good_column_names[idx]] = vb.value
-              oidlist << vb.oid.label
-              if vb.oid.label[0..good_column_names[idx].length - 1] != good_column_names[idx]
-                throw :break_main_loop
-              end
-            end
-            results << row
-          end
-        end
-        results
-      end
-
 
-#      def get_entries_cb(pdu, columns, options)
-#        cache = {}
-#        row_index = nil
-#        varbinds = pdu.varbinds.dup
-#        while(varbinds.size > 0)
-#          row = {}
-#          columns.each do |column|
-#            vb = varbinds.shift
-#            if vb.oid.to_s =~ /#{column.to_s}\.(\d+(:?\.\d+)*)/
-#              index = $1
-#            else
-#              last_entry = true
-#              next
-#            end
-#            row_index = index unless row_index
-#            index_cmp = Net::SNMP.oid_lex_cmp(index, row_index)
-#            if(index_cmp == 0)
-#            end
-#          end
-#        end
-#      end
     end
   end
 end

data/lib/net/snmp/version.rb

@@ -1,5 +1,5 @@
 module Net
   module SNMP
-    VERSION = "0.2.0"
+    VERSION = "0.2.1"
   end
 end

data/spec/sync_spec.rb

@@ -1,4 +1,5 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require 'pp'
 
 describe "synchronous calls" do
   # To test sets, you have to have a local snmpd running with write permissions
@@ -65,29 +66,39 @@ describe "synchronous calls" do
       end
     end
 
-    it "get_table should work with multiple columns" do
-      #pending
-      session = Net::SNMP::Session.open(:peername => "localhost", :version => '1')
-      table = session.get_table("ifTable", :columns => ["ifIndex", "ifDescr", "ifName"])
-      table[0]['ifName'].should eql("lo0")
-      table[1]['ifName'].should eql("gif0")
-    end
-
     it "get_table should work" do
-      pending "not yet implemented"
+      #pending "not yet implemented"
       session = Net::SNMP::Session.open(:peername => "localhost", :version => '1')
-      table = session.get_table("ifTable", :columns => ['ifIndex', 'ifDescr'])
-      table[0]['ifIndex'].should eql(1)
-      table[1]['ifIndex'].should eql(2)
+      table = session.table("ifEntry")
+      table['1']['ifIndex'].should eql(1)
+      table['2']['ifIndex'].should eql(2)
     end
 
     it "walk should work" do
-      pending "not yet implemented"
-      session = Net::SNMP::Session.open(:peername => 'test.net-snmp.org', :version => 1)
+      #pending "not yet implemented"
+      session = Net::SNMP::Session.open(:peername => 'test.net-snmp.org', :version => 1, :community => 'demopublic')
       results = session.walk("system")
       results['1.3.6.1.2.1.1.1.0'].should match(/test.net-snmp.org/)
     end
 
+    it "walk should work with multiple oids" do
+      Net::SNMP::Session.open(:peername => 'localhost', :version => 1) do |sess|
+        sess.walk(['system', 'ifTable']) do |results|
+          pp results
+          results['1.3.6.1.2.1.1.1.0'].should match(/Darwin/)
+          results['1.3.6.1.2.1.2.2.1.1.2'].should eql(2)
+          results.size.should eql(186)
+        end
+      end
+    end
+
+    it "get_columns should work" do
+      Net::SNMP::Session.open(:peername => 'localhost') do |sess|
+        table = sess.columns(['ifIndex', 'ifDescr', 'ifType'])
+        table['1']['ifIndex'].should eql(1)
+        table['2']['ifDescr'].should eql('gif0')
+      end
+    end
   end
 
   context "version 2" do

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 2
-  - 0
-  version: 0.2.0
+  - 1
+  version: 0.2.1
 platform: ruby
 authors: 
 - Ron McClain
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-30 00:00:00 -05:00
+date: 2011-05-01 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency