net-snmp2 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3b281e88b9dc311d024200f3c6a1490a275aeeb2
-  data.tar.gz: 7d0fd5cf86fd4bd509458de1bc0ce77fbcc03dcf
+  metadata.gz: 764e833cea5160e1dcd90749dc1e34497bc19cd7
+  data.tar.gz: dab11ed0e33675f7d37848b71a9eea33f94584e8
 SHA512:
-  metadata.gz: 2de1bdd8d99a79ed0849d4546c8af674fed288657c08dfff5631b41c23237ac87ac454f81d5059f4f579c4819da75659a3c324f304246b023ae9375df44cd3a1
-  data.tar.gz: 86dfd53cd984247500282b01108d96addac69ef79229edc8ea26c1eca4d05861e733c97a81b637ef4ccfe57c95904d6bcc64751bfd0b196cf86696a69ba8c371
+  metadata.gz: 9af6ba3d026772a98ee3d08d988859324b53f7e552e938ec400509f59a8fd0598c2716290af3a21b1c1374d8ff81c5b64f3905d21540b17ca5b46edf79b3d67d
+  data.tar.gz: 232ffa5c7ffdbe94a06cae89a545bc8795dfaf9f9ba0011c81edd6c85ebdefaa6ca4ab84bbcf20236aa18c5f2375efe76f48ff3ee93ee63e0b1ecce5c3d6404e

data/README.md

@@ -1,12 +1,15 @@
 net-snmp2
 =========
 
-(Checkout the [wiki](https://github.com/jbreeden/net-snmp2/wiki))
+[![Gem Version](https://badge.fury.io/rb/net-snmp2.svg)](http://badge.fury.io/rb/net-snmp2)
+
+Just getting started? Checkout the [wiki](https://github.com/jbreeden/net-snmp2/wiki)
 
 An object oriented Ruby wrapper around the C [netsnmp](http://www.net-snmp.org) libraries.
 It provides classes for manager sessions, agents, pdus, varbinds, MIB inspection, and more.
 
 The gem also includes some useful executables including:
+
 - **net-snmp2**
   + An interactive REPL for inspecting the MIB, and acting as an SNMP manager.
   + Supports managing multiple agents at once.
@@ -18,6 +21,7 @@ The gem also includes some useful executables including:
 Features
 --------
 
+* Improved Windows support over original net-snmp gem
 * Supports SNMP versions 1, 2c, and 3
 * Supports both synchronous and asynchronous calls
 * Supports sending of snmpv1 traps and snmpv2 traps/informs using TrapSession
@@ -26,3 +30,16 @@ Features
 * MIB support
 * Convenience methods such as session.walk, session.get_columns, and session.table
 * SNMP Agent support
+* Trap handler support
+
+Notes
+-----
+
+- TrapHandler & Agent support doesn't work on default Windows build of net-snmp libraries, due to certain functions not being exported in the dll.
+  + There is a [net-snmp-clone](https://github.com/jbreeden/net-snmp-clone) repo with the fixes made if you'd like to build this from source.
+  + Or, you can try my [pre-built DLL](https://github.com/jbreeden/net-snmp-clone/raw/master/win32/bin/release/netsnmp.dll) from the same repo.
+  + I've submitted this as a [feature request](https://sourceforge.net/p/net-snmp/feature-requests/181/) & patch to the net-snmp team. If it works for you, please go make a comment indicating that on the feature request to help it get pulled into the core library.
+- Original gem was using a different comment format... I've opted for markdown. The generated rdocs are probably garbage.
+  + The [wiki](https://github.com/jbreeden/net-snmp2/wiki) has the best documentation for now.
+  + All the specs are passing, so that's another good place to go for information.
+  + There is also the built-in net-snmp2 program you can run. This is an interactive Pry shell that is very useful for digging around the code and getting a feel for how to do things.

data/examples/agent.rb

@@ -1,4 +1,5 @@
 $: << '../lib'
+
 require 'net-snmp2'
 
 # Initialize SNMP and give it a logger

data/examples/inform.rb

@@ -0,0 +1,23 @@
+$: << '../lib'
+require 'net-snmp2'
+
+# Initialize SNMP and give it a logger
+Net::SNMP.init
+Net::SNMP::Debug.logger = Logger.new(STDOUT)
+Net::SNMP::Debug.logger.level = Logger::INFO
+
+session = Net::SNMP::TrapSession.open(:peername => 'localhost', :version => '2c', :community => 'public')
+
+extend Net::SNMP::Debug
+
+100000.times do |i|
+  time "Inform ##{i}" do
+    puts "Inform #{i}: " + session.inform(
+      oid: '1.3.1.1',
+      uptime: 1000,
+      varbinds: [
+        {oid: '1.3.2.2', value: 'test'}
+      ]
+    ).to_s
+  end
+end

data/examples/trap_handler.rb

@@ -35,6 +35,21 @@ handler = Net::SNMP::TrapHandler.new do
     Varbinds: #{varbinds.map {|vb| "#{vb.oid.label}(#{vb.oid}) = #{vb.value}"}.join(', ')}
     EOF
   end
+
+  inform do
+    info <<-EOF
+
+
+    Got Inform
+    ----------
+
+    Trap OID: #{trap_oid}
+    Uptime: #{uptime}
+    Varbinds: #{varbinds.map {|vb| "#{vb.oid.label}(#{vb.oid}) = #{vb.value}"}.join(', ')}
+    EOF
+
+    ok
+  end
 end
 
 # If the program gets the interrupt signal, tell the trap handler

data/examples/{v1_trap_session.rb → v1_trap.rb}

@@ -6,19 +6,14 @@ Net::SNMP.init
 Net::SNMP::Debug.logger = Logger.new(STDOUT)
 Net::SNMP::Debug.logger.level = Logger::DEBUG
 
-puts "Opening session"
 session = Net::SNMP::TrapSession.open(:peername => 'localhost', :version => '1', :community => 'public')
 
-puts "Sending trap"
-
 100000.times do |i|
-  session.trap(
+  puts "#{i + 1}: " + session.trap(
     enterprise: '1.3.1',
     trap_type: 6,
     specific_type: 1,
     uptime: 1000,
     agent_addr: '127.0.0.1'
-  )
+  ).to_s
 end
-
-sleep 20

data/examples/{v2_trap_session.rb → v2_trap.rb}

@@ -6,16 +6,11 @@ Net::SNMP.init
 Net::SNMP::Debug.logger = Logger.new(STDOUT)
 Net::SNMP::Debug.logger.level = Logger::DEBUG
 
-puts "Opening session"
 session = Net::SNMP::TrapSession.open(:peername => 'localhost', :version => '2c', :community => 'public')
 
-puts "Sending trap"
-
 100000.times do |i|
-  puts session.trap_v2(
+  puts "#{i + 1}: " + session.trap_v2(
     oid: '1.3.1.1',
     uptime: 1000
-  )
+  ).to_s
 end
-
-sleep 20

data/history.md

@@ -0,0 +1,17 @@
+History
+=======
+
+Version 0.3.1
+-------------
+
+- Internal changes
+  + Adding source_address & source_port to message object
+    * Changes the callback signature for Listener#on_message
+  + Adding Message#respond method
+    * Used for creating a one-off session for responding to a message
+      and sending a single pdu over it. (Used in TrapHandler & Agent)
+
+Version 0.3.0
+-------------
+
+- First gem release as net-snmp2

data/lib/net-snmp2.rb

@@ -21,6 +21,7 @@ require 'logger'
   snmp/trap_handler/trap_handler
   snmp/trap_handler/v1_trap_dsl
   snmp/trap_handler/v2_trap_dsl
+  snmp/trap_handler/v2_inform_dsl
   snmp/mib/mib
   snmp/mib/node
   snmp/mib/module
@@ -29,7 +30,6 @@ require 'logger'
   snmp/agent/agent
   snmp/agent/provider
   snmp/agent/provider_dsl
-  snmp/agent/request_dispatcher
   snmp/message
 ).each do |f|
   require "#{File.dirname(__FILE__)}/net/#{f}"

data/lib/net/snmp/agent/agent.rb

@@ -1,10 +1,8 @@
 module Net::SNMP
 
-#  - Manages the request/response cycle for incoming messages
-#    + Listens for incoming requests
-#    + Parses request packets into Message objects
-#    + Dispatches the messages to (sub) Agents
-#    + Serializes the response from the subagents and sends it to the caller
+# Agents delegate messages from the Net::SNMP::Listener to
+# providers, which supply the actual responses to the varbinds
+# in the request. See Net::SNMP::ProviderDsl
 
   class Agent
     include Debug
@@ -19,10 +17,16 @@ module Net::SNMP
       @listener.on_message(&method(:process_message))
     end
 
+    # This method is called with a block to define a provider
+    # for some subtree of the MIB. When a request comes in with varbinds
+    # in that providers subtree, the provider's handlers will be called
+    # to generate the varbind to send back in the response PDU.
+    #
+    # Arguments
+    #
+    # - oid: The root OID of the MIB subtree this provider is responsible for.
+    # - &block: A block, to be instance_evaled on the new Provider.
     def provide(oid = :all, &block)
-      # Need a trailing dot on the oid so we can avoid
-      # considering 1.3.22 a child of 1.3.2
-      oid = (oid.to_sym == :all || oid.end_with?('.')) ? oid : "#{oid}."
       provider = Provider.new(oid)
       provider.instance_eval(&block)
 
@@ -35,13 +39,40 @@ module Net::SNMP
 
     private
 
-    def process_message(message, from_address, from_port)
-      response_pdu = RequestDispatcher.dispatch(message, providers)
-      if response_pdu
-        Session.open(peername: from_address, port: from_port, version: message.version_name) do |sess|
-          sess.send_pdu response_pdu
+    # The callback given to the Listener object for handling an SNMP message.
+    # Calls `dispatch`, then sends the response PDU, if one is returned.
+    def process_message(message)
+      # TODO: May want to ignore some messages (say, if the community string is wrong)
+      message.respond(dispatch(message))
+    end
+
+    # Collects responses for the given message from the available providers
+    def dispatch(message)
+      response_pdu = message.make_response_pdu
+      context = ProviderDsl.new
+      context.message = message
+      context.response_pdu = response_pdu
+      message.pdu.varbinds.each_with_index do |vb, index|
+        context.varbind = vb
+        provider = providers.find { |p| p.provides?(vb.oid) }
+        if provider
+          if message.pdu.command == Constants::SNMP_MSG_GETBULK && index < message.pdu.non_repeaters
+            handler = provider.handler_for(Constants::SNMP_MSG_GETNEXT)
+          else
+            handler = provider.handler_for(message)
+          end
+          if handler
+            context.instance_exec(&handler)
+          else
+            warn "No handler for command: #{message.pdu.command} @ #{vb.oid}"
+            context.no_such_object
+          end
+        else
+          warn "No provider for oid: #{vb.oid}"
+          context.no_such_object
         end
       end
+      response_pdu
     end
 
   end

data/lib/net/snmp/agent/provider.rb

@@ -5,6 +5,39 @@ module Net::SNMP
 # of the subtree provided, and handlers for the various request types.
 # The handlers are executed for each varbind of the incoming message
 # individually in the context of a ProviderDsl object.
+#
+# Clients do not create Providers directly. Instead, they call `provide` on
+# an Agent, passing in a block. Within the block they use the `get`, `get_next`,
+# `get_bulk`, and `set` methods to configure handlers for these request types.
+# Within these handlers, the DSL methods from the ProviderDsl class can be
+# used to inspect the current request.
+#
+# Example
+#
+#     require 'net-snmp2'
+#     agent = Net::SNMP::Agent.new
+#     agent.provide :all do
+#
+#       get do
+#         reply get_value_somehow(oid)
+#       end
+#
+#       set do
+#         reply set_value_somehow(oid)
+#       end
+#
+#       get_next do
+#         reply get_next_value_somehow(oid)
+#       end
+#
+#       get_bulk do
+#         (0..max_repetitions).each do |i|
+#           add get_bulk_vlue_somehow(oid, i)
+#         end
+#       end
+#
+#     end
+#     agent.listen(161)
 
   class Provider
     attr_accessor :oid,
@@ -13,10 +46,26 @@ module Net::SNMP
       :get_next_handler,
       :get_bulk_handler
 
+    # Creates a new Provider with `oid` as the root of its subtree
     def initialize(oid)
-      @oid = oid
+      if oid.kind_of?(Symbol)
+        unless oid == :all
+          raise "Cannot provide symbol '#{oid}'. (Did you mean to use :all?)"
+        end
+        @oid = oid
+      else
+        # Guarantee OID is in numeric form
+        @oid = OID.new(oid).to_s
+      end
     end
 
+    # Gets the handler for the given command type from this provider.
+    #
+    # Arguments
+    #
+    # - command
+    #   + As an integer, specifies the command type a handler is needed for.
+    #   + May also be a Message or PDU object, from which the command type is read.
     def handler_for(command)
       # User might be tempted to just pass in the message, or pdu,
       # if so, just pluck the command off of it.
@@ -40,6 +89,12 @@ module Net::SNMP
       end
     end
 
+    # Returns a boolean indicating whether this provider provides
+    # the given `oid`
+    def provides?(oid)
+      self.oid == :all || oid.to_s =~ %r[#{self.oid.to_s}(\.|$)]
+    end
+
     [:get, :set, :get_next, :get_bulk].each do |request_type|
       self.class_eval %Q[
         def #{request_type}(&proc)

data/lib/net/snmp/agent/provider_dsl.rb

@@ -38,6 +38,11 @@ module Net::SNMP
       varbind.oid
     end
 
+    # The MIB variable name of the current varbind
+    def variable
+      oid.label
+    end
+
     # The OID of the current varbind being processed as a string.
     def oid_str
       varbind.oid.to_s
@@ -101,6 +106,12 @@ module Net::SNMP
       add_varbind(oid: oid, type: Constants::SNMP_NOSUCHINSTANCE)
     end
 
+    # Adds a varbind to the response indicating that the END OF MIB has been reached
+    def end_of_mib
+      oid ||= varbind.oid
+      add_varbind(oid: oid, type: Constants::SNMP_ENDOFMIBVIEW)
+    end
+
     # Adds a varbind to the response PDU.
     # MUST use this method (or one that delegates to it)
     # to set response varbinds on the response_pdu to make sure

data/lib/net/snmp/debug.rb

@@ -5,31 +5,22 @@ module Debug
     attr_accessor :logger
   end
 
-  def debug(msg)
-    Debug.logger.debug msg if Debug.logger
-  end
-
-  def info(msg)
-    Debug.logger.info msg if Debug.logger
-  end
-
-  def warn(msg)
-    Debug.logger.warn msg if Debug.logger
-  end
-
-  def error(msg)
-    Debug.logger.error msg if Debug.logger
-  end
-
-  def fatal(msg)
-    Debug.logger.fatal msg if Debug.logger
+  [:debug, :info, :warn, :error, :fatal].each do |log_level|
+    self.module_eval %Q{
+      def #{log_level}(msg = nil, &block)
+        if Debug.logger && (Debug.logger.level <= Logger::#{log_level.upcase})
+          Debug.logger.send(:#{log_level}, msg)
+          block[] if block_given?
+        end
+      end
+    }
   end
 
   def time(label, &block)
     t_start = Time.now
     block[]
     t_end = Time.now
-    info "#{label}: #{(t_end - t_start)*1000}ms"
+    debug "#{label}: #{(t_end - t_start)*1000}ms"
   end
 
   def print_packet(packet)

data/lib/net/snmp/error.rb

@@ -1,6 +1,8 @@
 module Net
   module SNMP
     class Error < RuntimeError
+      include Debug
+
       attr_accessor :status, :errno, :snmp_err, :snmp_msg
       def initialize(opts = {})
         @status = opts[:status]
@@ -14,12 +16,17 @@ module Net
       end
 
       def print
-        puts "SNMP Error: #{self.class.to_s}"
-        puts "message = #{message}"
-        puts "status = #{@status}"
-        puts "errno = #{@errno}"
-        puts "snmp_err = #{@snmp_err}"
-        puts "snmp_msg = #{@snmp_msg}"
+        message = <<-EOF
+
+        SNMP Error: #{self.class.to_s}
+        message = #{message}
+        status = #{@status}
+        errno = #{@errno}
+        snmp_err = #{@snmp_err}
+        snmp_msg = #{@snmp_msg}
+        EOF
+
+        error(message.gsub /^\s*/, '')
       end
     end
 

data/lib/net/snmp/listener.rb

@@ -37,13 +37,11 @@ module Net::SNMP
     #
     # The block provided will be called back for each message as follows:
     #
-    #   block[message, from_address, from_port]
+    #   block[message]
     #
     # Where
     #
     # - `message` is the parsed Net::SNMP::Message object
-    # - `from_address` is a string representing the address of the host sending the request
-    # - `from_port` is the port the host sent the request from
     def on_message(&block)
       @callback = block
     end
@@ -62,7 +60,7 @@ module Net::SNMP
           return if @killed
           time "Message Processing" do
             message = Message.parse(@packet)
-            @callback[message, @packet[1][3], @packet[1][1]] if @callback
+            @callback[message] if @callback
           end
         rescue Timeout::Error => timeout
           next