net-snmp 0.1.7 → 0.2.0

data/Gemfile

@@ -4,6 +4,8 @@ source "http://rubygems.org"
 gemspec
 
 gem 'nice-ffi'
+gem 'ffi-inliner'
+#gem 'ffi-libc'
 #group :development, :test do
 # gem 'eventmachine', '1.0.0.beta.3'
 #end

data/README.rdoc

@@ -9,6 +9,7 @@ It provides classes for sessions, pdus, varbinds, and more.
 
 * Supports SNMP versions 1, 2c, and 3
 * Supports both synchronous and asynchronous calls
+* 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
 
@@ -44,31 +45,48 @@ functions are defined in Net::SNMP::Wrapper.  You can call them like so:
 == NOTES
 You must call Session.close when you're done with a session to avoid leaking memory
 
-== EXAMPLES
+== ERROR HANDLING
+    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.
+    
 
+== EXAMPLES
 
 A simple synchronous SNMP-GET
 
   session = Net::SNMP::Session.open(:peername => "test.net-snmp.org", :community => "demopublic" )
-  result = session.get("sysDescr.0")
-  puts result.varbinds.first.value
+  begin
+    pdu = session.get("sysDescr.0")
+    puts pdu.varbinds.first.value
+  rescue Net::SNMP::Error => e
+    puts e.message
+  end
   session.close
 
 An asynchronous SNMP-GET
     session = Net::SNMP::Session.open(:peername => 'test.net-snmp.org', :community => 'demopublic') do |session|
-      session.get(["sysDescr.0", "sysContact.0"]) do |result|
-        puts result.varbinds[0].value
+      session.get(["sysDescr.0", "sysContact.0"]) do |status, pdu|
+        if status == :success
+          puts pdu.varbinds[0].value
+        else
+          puts "something went wrong.  status is #{status}"
+        end
       end
     end
-    Net::SNMP::Dispatcher.poll(false)  #Setting timeout to false causes dispatcher to block until data is ready
+    Net::SNMP::Dispatcher.select(false)  #Setting timeout to false causes dispatcher to block until data is ready
     session.close
 
 Running the dispatcher from eventmachine
     EM.run do
       Net::SNMP::Dispatcher.em_loop
       session = Net::SNMP::Session.open(:peername => 'test.net-snmp.org', :community => 'demopublic') do |session|
-        session.get("sysDescr.0") do |result|
-          puts result.varbinds[0].value
+        session.get("sysDescr.0") do |status, pdu|
+          if status == :success
+            puts pdu.varbinds[0].value
+          else
+            puts "something went wrong.  status is #{status}"
+          end
         end
       end
       EM.add_timer(2) do
@@ -82,8 +100,12 @@ Using synchronous style with eventmachine in ruby 1.9
       Net::SNMP::Dispatcher.fiber_loop
       Fiber.new {
         session = Net::SNMP::Session.open(:peername => 'test.net-snmp.org', :community => 'demopublic')
-        result = session.get("sysDescr.0")
-        puts result.varbinds[0].value
+        begin
+          pdu = session.get("sysDescr.0")
+          puts pdu.varbinds[0].value
+        rescue Net::SNMP::Error => e
+          puts e.message
+        end
         session.close
         EM.stop
       }.resume
@@ -105,14 +127,15 @@ You can also explicitly add MIBs using the MIB api.  For example:
   Net::SNMP::MIB.add_mibdir("/usr/local/share/mibs")
   Net::SNMP::MIB.read_mib("RFC1213-MIB.txt")
 
-Having the appropriate MIBs loaded will allow you to pass names instead of numeric oids to net-snmp methods.  To translate a single oid,
-you can call Net::SNMP.get_oid("sysDescr.0").  For more complex MIB parsing needs, see smi-ffi[http://github.com/mixtli/smi-ffi]
-
+Having the appropriate MIBs loaded will allow you to pass names instead of numeric oids to net-snmp methods.  You can also pass
+Net::SNMP::OID objects.  For example
 
-== BUGS
-Right now, snmpv3 is only working  using synchronous API.   Asynchronous calls seem to miss packets.
-I have no idea why it would be different for v3 vs v1/v2.  If anyone knows, tell me ;)
+    oid = Net::SNMP::OID.new('sysDescr.0') # or Net::SNMP::OID.new("1.3.6.1.2.1.1.1.0")
+    puts oid.to_s  --> '1.3.6.1.2.1.1.1.0'
+    puts oid.label --> 'sysDescr.0'
+    pdu = session.get([oid])
 
+For more complex MIB parsing needs, see smi-ffi[http://github.com/mixtli/smi-ffi]
 
 == CAVEATS/DISCLAIMER
 
@@ -128,13 +151,11 @@ break this gem.  Please let me know if you find bugs or missing features.  Or be
 
 
 == TODO
-
-* Better error handling.
+* Implement walk and get_table convenience methods.
 * SNMPv3 support needs testing for various security models
 * Better documentation
 * More tests
-* Cleanup cruft and unused code
-* Implement SNMP traps/informs?
+
 
 == Note on Patches/Pull Requests
  

data/lib/net-snmp.rb

@@ -1,10 +1,14 @@
 require 'forwardable'
 require 'nice-ffi'
 require 'fiber'
-
-%w(snmp snmp/version snmp/constants snmp/utility snmp/oid snmp/error snmp/pdu snmp/wrapper snmp/session snmp/varbind snmp/mib snmp/mib/node snmp/dispatcher).each do |f|
+require 'ffi-inliner'
+#require 'ffi/libc'
+%w( snmp snmp/debug snmp/wrapper snmp/version snmp/inline snmp/constants snmp/utility snmp/oid snmp/error snmp/pdu snmp/session snmp/trap_session snmp/varbind snmp/mib snmp/mib/node snmp/dispatcher).each do |f|
   require "#{File.dirname(__FILE__)}/net/#{f}"
 end
+
+
+
 Net::SNMP::MIB.init
 Net::SNMP::MIB.read_all_mibs
 Net::SNMP.init

data/lib/net/snmp.rb

@@ -2,15 +2,18 @@ require 'net/snmp/constants'
 module Net
   module SNMP
     include Net::SNMP::Constants
-
-
+    @thread_safe = false
     def self.init(tag="snmp")
       Wrapper.init_snmp(tag)
     end
 
+    def self.thread_safe=(val)
+      @thread_safe = val
+    end
 
-
-
+    def self.thread_safe
+      @thread_safe
+    end
 
   end
 end

data/lib/net/snmp/constants.rb

@@ -2,10 +2,18 @@ module Net
   module SNMP
     module Constants
       MAX_OID_LEN = 128
+
+      # Return values of various send functions
+      STAT_SUCCESS        = 0
+      STAT_ERROR          = 1
+      STAT_TIMEOUT        = 2
+
+      # SNMP versions
       SNMP_VERSION_1 = 0
       SNMP_VERSION_2c = 1
       SNMP_VERSION_3 = 3
 
+      # PDU variable types
       ASN_BOOLEAN         = 0x01
       ASN_INTEGER         = 0x02
       ASN_BIT_STR         = 0x03
@@ -34,13 +42,17 @@ module Net
       ASN_UNSIGNED    = (ASN_APPLICATION | 2)   # RFC 1902 - same as GAUGE
       ASN_TIMETICKS   = (ASN_APPLICATION | 3)
       ASN_OPAQUE      = (ASN_APPLICATION | 4)
+      ASN_NSAP        = (ASN_APPLICATION | 5)  # historic - don't use
+      ASN_COUNTER64   = (ASN_APPLICATION | 6)
+      ASN_UINTEGER    = (ASN_APPLICATION | 7)   # historic - don't use
 
-      #define ASN_NSAP        (ASN_APPLICATION | 5)   /* historic - don't use */
-      #define ASN_COUNTER64   (ASN_APPLICATION | 6)
-      #define ASN_UINTEGER    (ASN_APPLICATION | 7)   /* historic - don't use */
-
+      # 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)
 
 
+      # PDU types
       SNMP_MSG_GET        = (ASN_CONTEXT | ASN_CONSTRUCTOR | 0x0)
       SNMP_MSG_GETNEXT    = (ASN_CONTEXT | ASN_CONSTRUCTOR | 0x1) 
       SNMP_MSG_RESPONSE   = (ASN_CONTEXT | ASN_CONSTRUCTOR | 0x2) 
@@ -51,64 +63,15 @@ module Net
       SNMP_MSG_TRAP2      = (ASN_CONTEXT | ASN_CONSTRUCTOR | 0x7)
       SNMP_MSG_REPORT     = (ASN_CONTEXT | ASN_CONSTRUCTOR | 0x8)
       
+
+      # Callback status codes
       NETSNMP_CALLBACK_OP_RECEIVED_MESSAGE  =  1
       NETSNMP_CALLBACK_OP_TIMED_OUT         =  2
       NETSNMP_CALLBACK_OP_SEND_FAILED       =  3
       NETSNMP_CALLBACK_OP_CONNECT           =  4
       NETSNMP_CALLBACK_OP_DISCONNECT        =  5
       
-
-
-      USM_AUTH_KU_LEN = 32
-      USM_PRIV_KU_LEN = 32
-
-      SNMP_SEC_LEVEL_NOAUTH = 1
-      SNMP_SEC_LEVEL_AUTHNOPRIV = 2
-      SNMP_SEC_LEVEL_AUTHPRIV = 3
-
-      SNMP_DEFAULT_COMMUNITY_LEN = 0
-      SNMP_DEFAULT_RETRIES = -1
-      SNMP_DEFAULT_TIMEOUT = -1
-      SNMP_DEFAULT_REMPORT = 0
-      SNMP_DEFAULT_REQID = -1
-      SNMP_DEFAULT_MSGID = -1
-      SNMP_DEFAULT_ERRSTAT = -1
-      SNMP_DEFAULT_ERRINDEX = -1
-      SNMP_DEFAULT_ADDRESS = 0
-      SNMP_DEFAULT_ENTERPRISE_LENGTH = 0
-      SNMP_DEFAULT_TIME = 0
-      SNMP_DEFAULT_VERSION = -1
-      SNMP_DEFAULT_SECMODEL = -1
-      SNMP_DEFAULT_CONTEXT = 
-
-      SNMP_MAX_MSG_SIZE = 1472
-      SNMP_MAX_MSG_V3_HDRS = (4+3+4+7+7+3+7+16)
-      SNMP_MAX_ENG_SIZE = 32
-      SNMP_MAX_SEC_NAME_SIZE = 256
-      SNMP_MAX_CONTEXT_SIZE = 256
-      SNMP_SEC_PARAM_BUF_SIZE = 256
-      SNMPV3_IGNORE_UNAUTH_REPORTS = 0
-      SNMP_SESS_NONAUTHORITATIVE = 0
-      SNMP_SESS_AUTHORITATIVE = 1
-      SNMP_SESS_UNKNOWNAUTH = 2
-      REPORT_STATS_LEN = 9
-      REPORT_snmpUnknownSecurityModels_NUM = 1
-      REPORT_snmpInvalidMsgs_NUM = 2
-      REPORT_usmStatsUnsupportedSecLevels_NUM = 1
-      REPORT_usmStatsNotInTimeWindows_NUM = 2
-      REPORT_usmStatsUnknownUserNames_NUM = 3
-      REPORT_usmStatsUnknownEngineIDs_NUM = 4
-      REPORT_usmStatsWrongDigests_NUM = 5
-      REPORT_usmStatsDecryptionErrors_NUM = 6
-      SNMP_DETAIL_SIZE = 512
-      SNMP_FLAGS_RESP_CALLBACK = 0x400
-      SNMP_FLAGS_USER_CREATED = 0x200
-      SNMP_FLAGS_DONT_PROBE = 0x100
-      SNMP_FLAGS_STREAM_SOCKET = 0x80
-      SNMP_FLAGS_LISTENING = 0x40
-      SNMP_FLAGS_SUBSESSION = 0x20
-      SNMP_FLAGS_STRIKE2 = 0x02
-      SNMP_FLAGS_STRIKE1 = 0x01
+      # SNMP Errors
       SNMPERR_SUCCESS = (0)
       SNMPERR_GENERR = (-1)
       SNMPERR_BAD_LOCPORT = (-2)
@@ -178,6 +141,60 @@ module Net
       SNMPERR_MAX = (-65)
 
 
+
+      USM_AUTH_KU_LEN = 32
+      USM_PRIV_KU_LEN = 32
+
+      # SNMPv3 Security Levels
+      SNMP_SEC_LEVEL_NOAUTH = 1
+      SNMP_SEC_LEVEL_AUTHNOPRIV = 2
+      SNMP_SEC_LEVEL_AUTHPRIV = 3
+
+      SNMP_DEFAULT_COMMUNITY_LEN = 0
+      SNMP_DEFAULT_RETRIES = -1
+      SNMP_DEFAULT_TIMEOUT = -1
+      SNMP_DEFAULT_REMPORT = 0
+      SNMP_DEFAULT_REQID = -1
+      SNMP_DEFAULT_MSGID = -1
+      SNMP_DEFAULT_ERRSTAT = -1
+      SNMP_DEFAULT_ERRINDEX = -1
+      SNMP_DEFAULT_ADDRESS = 0
+      SNMP_DEFAULT_ENTERPRISE_LENGTH = 0
+      SNMP_DEFAULT_TIME = 0
+      SNMP_DEFAULT_VERSION = -1
+      SNMP_DEFAULT_SECMODEL = -1
+      SNMP_DEFAULT_CONTEXT = 
+
+      SNMP_MAX_MSG_SIZE = 1472
+      SNMP_MAX_MSG_V3_HDRS = (4+3+4+7+7+3+7+16)
+      SNMP_MAX_ENG_SIZE = 32
+      SNMP_MAX_SEC_NAME_SIZE = 256
+      SNMP_MAX_CONTEXT_SIZE = 256
+      SNMP_SEC_PARAM_BUF_SIZE = 256
+      SNMPV3_IGNORE_UNAUTH_REPORTS = 0
+      SNMP_SESS_NONAUTHORITATIVE = 0
+      SNMP_SESS_AUTHORITATIVE = 1
+      SNMP_SESS_UNKNOWNAUTH = 2
+      REPORT_STATS_LEN = 9
+      REPORT_snmpUnknownSecurityModels_NUM = 1
+      REPORT_snmpInvalidMsgs_NUM = 2
+      REPORT_usmStatsUnsupportedSecLevels_NUM = 1
+      REPORT_usmStatsNotInTimeWindows_NUM = 2
+      REPORT_usmStatsUnknownUserNames_NUM = 3
+      REPORT_usmStatsUnknownEngineIDs_NUM = 4
+      REPORT_usmStatsWrongDigests_NUM = 5
+      REPORT_usmStatsDecryptionErrors_NUM = 6
+      SNMP_DETAIL_SIZE = 512
+      SNMP_FLAGS_RESP_CALLBACK = 0x400
+      SNMP_FLAGS_USER_CREATED = 0x200
+      SNMP_FLAGS_DONT_PROBE = 0x100
+      SNMP_FLAGS_STREAM_SOCKET = 0x80
+      SNMP_FLAGS_LISTENING = 0x40
+      SNMP_FLAGS_SUBSESSION = 0x20
+      SNMP_FLAGS_STRIKE2 = 0x02
+      SNMP_FLAGS_STRIKE1 = 0x01
+
+
       STAT_SNMPUNKNOWNSECURITYMODELS = 0
       STAT_SNMPINVALIDMSGS = 1
       STAT_SNMPUNKNOWNPDUHANDLERS = 2

data/lib/net/snmp/debug.rb

@@ -0,0 +1,17 @@
+module Net
+  module SNMP
+    module Debug
+      @@debug = false
+
+      def self.debug=(val)
+        @@debug = val
+      end
+
+      def debug(msg)
+        if @@debug
+          puts msg
+        end
+      end
+    end
+  end
+end

data/lib/net/snmp/dispatcher.rb

@@ -1,89 +1,62 @@
 class Net::SNMP::Dispatcher
+  # A class with convenience methods for polling multiple open sessions
   class << self
-
-    # timeout = nil  no block(poll),  timeout = false block forever, timeout = int, block int seconds
-#    def poll(timeout = nil)
-#        fdset = Net::SNMP::Wrapper.get_fd_set
-#        num_fds = FFI::MemoryPointer.new(:int)
-#        tv_sec = timeout ? timeout.round : 0
-#        tv_usec = timeout ? (timeout - timeout.round) * 1000000 : 0
-#        tval = Net::SNMP::Wrapper::TimeVal.new(:tv_sec => tv_sec, :tv_usec => tv_usec)
-#        block = FFI::MemoryPointer.new(:int)
-#
-#        if timeout.nil?
-#          block.write_int(0)
-#        else
-#          block.write_int(1)
-#        end
-#        #puts "calling snmp_select_info"
-#        Net::SNMP::Wrapper.snmp_select_info(num_fds, fdset, tval.pointer, block )
-#        #puts "done snmp_select_info."
-#        num_ready = 0
-#        #puts "block = #{block.read_int}"
-#
-#        #puts "numready = #{num_fds.read_int}"
-#        #puts "tv = #{tval[:tv_sec]} #{tval[:tv_usec]}"
-#        #puts "timeout = #{timeout}"
-#        tv = (timeout == false ? nil : tval)
-#        #puts "calling select"
-#        #puts "tv = #{tv.inspect}"
-#        #puts "calling select with #{num_fds.read_int}"
-#        #num_ready = RubyWrapper.rb_thread_select(num_fds.read_int, fdset, nil, nil, tv)
-#        num_ready = Net::SNMP::Wrapper.select(num_fds.read_int, fdset, nil, nil, tv)
-#        #puts "done select.  num_ready = #{num_ready}"
-#        if num_ready > 0
-#          Net::SNMP::Wrapper.snmp_read(fdset)
-#        elsif num_ready == 0
-#          # timeout.  do something here?  or just return 0?
-#        elsif num_ready == -1
-#          # error.  check snmp_error?
-#        else
-#          # uhhh
-#        end
-#        #puts "done snmp_read"
-#        num_ready
-#    end
-
-
-    def poll(timeout = nil)
-      #puts "Dispatcher.poll #{Net::SNMP::Session.sessions.size}"
+    # Loop through all sessions, calling select on each.
+    def select(timeout = nil)
       total = 0
       t = timeout
       t = nil if t == false
       catch :got_data do
         loop do
-          Net::SNMP::Session.lock.synchronize {
-            Net::SNMP::Session.sessions.each do |k, sess|
-              #puts "polling session"
-              total += sess.poll(t)
+          if Net::SNMP.thread_safe
+            Net::SNMP::Session.lock.synchronize {
+              Net::SNMP::Session.sessions.each do |k, sess|
+                total += sess.select(t)
+              end
+            }
+          else
+           Net::SNMP::Session.sessions.each do |k, sess|
+              total += sess.select(t)
             end
-          }
+          end
+
           throw :got_data if total > 0
           throw :got_data unless timeout == false
         end
       end
-      #puts "Done Dispatcher.poll"
       total
     end
+    alias :poll :select
 
+    # Start a poller loop.  Behavior depends upon whether
+    # you are running under eventmachine and whether fibers
+    # are available.
+    # +options+
+    # * :timeout Number of seconds to block on select. nil effects a poll.  false blocks forever (probably not what you want).
+    # * :sleep Number of seconds to sleep if no data is available.  Gives other fibers/threads a chance to run.
     def run_loop(options = {})
       if defined?(EM) && EM.reactor_running?
-        fiber_loop(options)
+        if defined?(Fiber)
+          fiber_loop(options)
+        else
+          em_loop(options)
+        end
       else
         thread_loop(options)
       end
     end
 
-    # You should not pass nil to this as it will peg your cpu
+    # Start a poller loop in a seperate thread.  You
+    # should first call Net::SNMP.thread_safe = true.
+    # +options+
+    # * :timeout Number of seconds to block on select. Will not block other threads.
+    # * :sleep Number of seconds to sleep if no data is available.  Allows other threads to run. Default 0.2
     def thread_loop(options = {})
-
-      timeout = options[:timeout] || 0.1
-      sleep_time = options[:sleep] || 0.1
+      timeout = options[:timeout] || 0.2
+      sleep_time = options[:sleep] || 0.2
       Thread.new do
         loop do
-          #puts "polling"
-          num_ready = poll(timeout)
-          #puts "num_ready = #{num_ready}"
+          num_ready = select(timeout)
           if num_ready == 0
             sleep(sleep_time) if sleep_time
           end
@@ -91,14 +64,16 @@ class Net::SNMP::Dispatcher
       end
     end
 
-
+    # Start a loop in eventmachine (no fibers)
+    # +options+
+    # * :sleep Number of seconds to sleep if no data available.  So we don't peg the reactor. Default 0.2
     def em_loop(options = {})
       timeout = options[:timeout]
-      sleep_time = options[:sleep_time] || 0.1
+      sleep_time = options[:sleep] || 0.2
       myproc = Proc.new do
         EM.next_tick do
           while(true) do
-            num_ready = poll(timeout)
+            num_ready = select(timeout)
             break if num_ready == 0
           end
           EM.add_timer(sleep_time) do
@@ -109,9 +84,12 @@ class Net::SNMP::Dispatcher
       myproc.call
     end
 
+    # Start a loop using eventmachine and fibers
+    # +options+
+    # * :sleep Number of seconds to sleep if no data available, so we don't peg the reactor. Default 0.2
     def fiber_loop(options = {})
       timeout = options[:timeout]
-      sleep_time = options[:sleep] || 0.1
+      sleep_time = options[:sleep] || 0.2
       Fiber.new {
         loop do
           num_handled = poll(timeout)