net-snmp2 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3b281e88b9dc311d024200f3c6a1490a275aeeb2
+  data.tar.gz: 7d0fd5cf86fd4bd509458de1bc0ce77fbcc03dcf
+SHA512:
+  metadata.gz: 2de1bdd8d99a79ed0849d4546c8af674fed288657c08dfff5631b41c23237ac87ac454f81d5059f4f579c4819da75659a3c324f304246b023ae9375df44cd3a1
+  data.tar.gz: 86dfd53cd984247500282b01108d96addac69ef79229edc8ea26c1eca4d05861e733c97a81b637ef4ccfe57c95904d6bcc64751bfd0b196cf86696a69ba8c371

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/
+*DS_Store

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in net-snmp2.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 mixtli
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,28 @@
+net-snmp2
+=========
+
+(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.
+  + Implemented on top of [Pry](http://pryrepl.org/), so it inherits all of Pry's goodness.
+- **mib2rb**
+  + A [mib2c](http://www.net-snmp.org/wiki/index.php/Mib2c) like tool that uses ERB files to format and display the system MIB.
+  + mib2rb has a default template that prints the MIB details in a human-readable format, providing functionality similar to [snmptranslate](http://www.net-snmp.org/wiki/index.php/TUT:snmptranslate).
+
+Features
+--------
+
+* 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
+* MIB support
+* Convenience methods such as session.walk, session.get_columns, and session.table
+* SNMP Agent support

data/Rakefile

@@ -0,0 +1,24 @@
+require 'bundler'
+require 'pry'
+Bundler::GemHelper.install_tasks
+
+task :console do
+  require 'pry'
+  require 'logger'
+  $: << 'lib'
+  require 'net-snmp2'
+  Net::SNMP::Debug.logger = Logger.new(STDOUT)
+  Net::SNMP::Debug.logger.level = Logger::INFO
+  include Net::SNMP
+  ARGV.clear
+
+  current_prompt = nil
+  Pry.config.prompt = [
+    proc { |obj, level|
+      current_prompt = "[net-snmp2 (#{obj}) (#{level})] "
+    }, proc {
+      "[#{'.' * (current_prompt.length - 3)}] "
+    }
+  ]
+  Net::SNMP.pry
+end

data/TODO.md

@@ -0,0 +1,6 @@
+TODO
+====
+
+- Need to write tests to perform many requests of each type and check for memory leaks.
+  + So far v1 & v2 traps for TrapSession seem fine, as does the TrapHandler class.
+- [DONE] Finish implementing Agent's get_bulk feature (this is the last thing outstanding)

data/bin/mib2rb

@@ -0,0 +1,129 @@
+#! /usr/bin/env ruby
+
+$: << "#{File.dirname(__FILE__)}/../lib"
+require 'logger'
+require 'optparse'
+require 'erb'
+require 'net-snmp2'
+
+Net::SNMP.init
+Templates = Net::SNMP::MIB::Templates
+
+usage = <<USAGE
+
+Usage: mib2rb [OPTION]... ROOT_NODE [ERB_FILE]
+
+Description
+  Prints a mib subtree according to the ERB_FILE.
+  Within the ERB file, the `root` variable contains the
+  Net::SNMP::Node object corresponding to ROOT_NODE, and
+  `nodes` is a collection of the root & all descendants.
+
+Options
+  -h,          Prints this usage information.
+
+               Aliases:   --help
+
+  -l LEVEL     Set the log level.
+               Logs are piped to STDERR, so you can redirect
+               STDOUT to a file without worrying about logs
+               getting into the output.
+
+               Values:   debug, info, warn, error, fatal, none
+               Default:  none
+               Aliases:  --log-level
+
+  -f FORMAT    Select the output format.
+               If this option is supplied with an ERB file,
+               the option is ignored and the file is used instead.
+
+               Values:   [d]efault, [j]son
+               Default:  default
+               Aliases:  --format
+
+Arguments
+  ROOT_NODE    [Required] The root node of the mib tree to translate.
+               May be specified as numeric oid or mib name.
+
+  ERB_FILE     [Optional] The template file to use for output.
+
+               Default:  Builtin template specifying human readable output.
+                         (See below)
+
+Default ERB_FILE Template
+-------------------------
+
+#{Templates::DESCRIBE}
+USAGE
+
+root_node = nil
+erb_template = nil
+
+OptionParser.new do|opts|
+  opts.on( '-h', '--help') do
+    puts usage
+    exit
+  end
+
+  opts.on('-l', '--log-level LEVEL') do |level|
+    break if level =~ /none/i
+
+    Net::SNMP::Debug.logger = Logger.new(STDERR)
+    Net::SNMP::Debug.logger.level = case level
+      when /debug/i
+        Logger::DEBUG
+      when /info/i
+        Logger::INFO
+      when /warn/i
+        Logger::WARN
+      when /error/i
+        Logger::ERROR
+      when /fatal/i
+        Logger::FATAL
+      else
+        puts "Invalid log level: #{level}"
+        puts
+        puts usage
+        exit(1)
+    end
+  end
+
+  opts.on('-f', '--format FORMAT') do |format|
+    case format
+    when /^d(efault)?$/i
+      erb_template = Templates::DESCRIBE
+    when /^j(son)?$/i
+      erb_template = Templates::JSON
+    else
+      puts "Invalid format: #{format}"
+      puts
+      puts usage
+      exit(1)
+    end
+  end
+
+end.parse!
+
+case ARGV.length
+when 1
+  root_node = Net::SNMP::MIB.get_node(ARGV[0])
+  # If format wasn't set by -f option, default it here
+  erb_template ||= Templates::DESCRIBE
+when 2
+  root_node = Net::SNMP::MIB.get_node(ARGV[0])
+  erb_template = File.read(ARGV[1])
+else
+  puts "Invalid arguments..."
+  puts
+  puts usage
+  exit(1)
+end
+
+def render(node, erb_template)
+  root = node
+  nodes = [root] + root.descendants.to_a
+  erb = ERB.new(erb_template, nil, '-')
+  puts erb.result binding
+end
+
+render(root_node, erb_template)

data/bin/net-snmp2

@@ -0,0 +1,64 @@
+#! /usr/bin/env ruby
+
+$: << "#{File.dirname(__FILE__)}/../lib"
+require 'logger'
+require 'optparse'
+require 'erb'
+require 'pry'
+require 'net-snmp2'
+require 'net/snmp/repl/manager_repl'
+
+usage = '
+Usage: net-snmp2 [-v VERSION] [-c COMMUNITY] [HOST[:PORT]]
+'.sub("\n", "")
+
+# Default option values
+options = {
+  :version => '2c',
+  :community => 'public',
+  :peername => 'localhost',
+  :port => '161'
+}
+
+OptionParser.new do |opt|
+  opt.on("-v VERSION") do |version|
+    case version
+    when /^1$/
+      options[:version] = '1'
+    when /^2c?$/i
+      options[:version] = '2c'
+    when /^3$/
+      options[:version] = '3'
+    else
+      puts "Invalid version: #{version}"
+      puts
+      puts usage
+    end
+  end
+
+  opt.on("-c COMMUNITY") do |community|
+    options[:community] = community
+  end
+
+  opt.on('-h') do
+    puts usage
+    exit
+  end
+
+end.parse!
+
+session = nil
+if ARGV.length > 0
+  peername = ARGV[0]
+  m = peername.match /^([^:]*)(:([0-9]*))?$/
+  options[:peername] = m[1]
+  options[:port] = m[3] unless m[3].nil? || m[3].empty?
+  session = Net::SNMP::Session.open(options)
+end
+
+Net::SNMP::Debug.logger = Logger.new(STDOUT)
+Net::SNMP::Debug.logger.level = Logger::INFO
+ARGV.clear
+
+Net::SNMP.init
+Net::SNMP::ManagerRepl.start(session)

data/examples/agent.rb

@@ -0,0 +1,104 @@
+$: << '../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
+
+agent = Net::SNMP::Agent.new
+
+# If the program gets the interrupt signal, tell the agent
+# to stop so the program can exit.
+trap(:INT) {
+  agent.stop
+}
+
+# Using an in-memory Hash to represent our MIB storage
+mib = {
+  '1.3.1.1' => 1,
+  '1.3.1.2' => "I'm a string"
+}
+
+# The `provide` function creates a provider the Agent can
+# delegate to when a request has a varbind that lives under
+# the given OID. (Or, for all requests if given `:all`,
+# which is the default)
+#
+# Notes: All get/set handlers are called
+# once for each varbind, not once per message. This means
+# the agent may call multiple providers to satisfy a single
+# message. It also means that the code for iterating over
+# a request's varbinds, setting errindex values, etc, is
+# encapsulated in the Agent code, and you do not have to
+# implement it yourself.
+agent.provide '1.3' do
+
+  get do
+    # `oid` is provided by the DSL as the OID object for the current varbind
+    #
+    # Note: The ProviderDsl (in which all agent handlers are run)
+    # includes Net::SNMP::Debug, so you can use the info, warn, debug,
+    # error, and fatal logging methods.
+    info "Got a get request for #{oid}"
+
+    if mib.has_key? oid_str
+      # `reply` is provided by the DSL to set the response for the current varbind.
+      # For a GetBulk request, you can use it's alias `add`, which is more natural
+      # in that context, when you may be setting multiple response varbinds for a
+      # single requested OID.
+      #
+      # `oid_str` is alo provided, and is the same as `oid.to_s`
+      reply(mib[oid_str])
+    else
+      # `no_such_object` can be used to indicate that the variable requested
+      # does not exist in the MIB on this machine. See also: `no_such_instance`
+      no_such_object
+    end
+  end
+
+  set do
+    info "Get a set request for #{oid} = #{value}"
+
+    # Randomly fail 20% of the time
+    if rand > 0.8
+      info "Decided to fail... Sending WRONGTYPE errstat"
+      # `error` sets the error status of the reply to the given integer.
+      # The Agent code handles setting the error index behind the scenes,
+      # so you don't have to set it here.
+      error Net::SNMP::Constants::SNMP_ERR_WRONGTYPE
+      next
+    end
+
+    if mib.has_key? oid_str
+      # Saving the set value in our MIB storage
+      mib[oid_str] = value
+      # `ok` copies the current varbind to the response,
+      # indicating success to the manager. (Aliased as `echo`)
+      ok
+    else
+      no_such_object
+    end
+  end
+
+  # Note that the `get_next` handler is also used for varbinds
+  # 1..non_repeaters from the request pdu of a get_bulk
+  get_next do
+    puts "get_next called for #{oid_str}"
+    reply(oid: oid_str + '.0', value: 'get_next value')
+  end
+
+  # `get_bulk` handler serves all varbinds in a get_bulk request
+  # after the non_repeaters have been served by `get_next`
+  get_bulk do
+    puts "get_bulk called for #{oid_str}"
+    (0..max_repetitions).each do |i|
+      add(oid: "#{oid_str}.#{i}", value: "Bulk value ##{i}")
+    end
+  end
+
+end
+
+# Start the agent's run loop, listening to port 161
+# Aliases: `run`, `start`
+agent.listen(161)

data/examples/manager.rb

@@ -0,0 +1,11 @@
+$: << '../lib'
+
+require 'net-snmp2'
+t_start = Time.now
+pdu = nil
+#Net::SNMP.init # Uncomment this to go real slow
+Net::SNMP::Session.open(:peername => "localhost", :community => "public" ) do |session|
+  pdu = session.get(["1.3.6.1.4.1.290.6.7.3.1.3.6.0", '1.3.6.1.4.1.290.6.7.3.1.3.7.0'])
+end
+t_end = Time.now
+puts "Got #{pdu.varbinds[0].value} & #{pdu.varbinds[1].value} in #{(t_end - t_start) * 1000} ms"

data/examples/trap_handler.rb

@@ -0,0 +1,46 @@
+$: << '../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
+
+handler = Net::SNMP::TrapHandler.new do
+  v1 do
+    info <<-EOF
+
+
+    Got V1 Trap
+    -----------
+
+    Enterprise OID: #{enterprise}
+    Trap Type: #{general_trap_type}
+    Specific Type: #{specific_trap_type}
+    Agent Address: #{agent_address}
+    Uptime: #{uptime}
+    Varbinds: #{varbinds.map {|vb| "#{vb.oid.label}(#{vb.oid}) = #{vb.value}"}.join(', ')}
+    EOF
+  end
+
+  v2 do
+    info <<-EOF
+
+
+    Got V2 Trap
+    -----------
+
+    Trap OID: #{trap_oid}
+    Uptime: #{uptime}
+    Varbinds: #{varbinds.map {|vb| "#{vb.oid.label}(#{vb.oid}) = #{vb.value}"}.join(', ')}
+    EOF
+  end
+end
+
+# If the program gets the interrupt signal, tell the trap handler
+# to stop so the program can exit.
+trap(:INT) {
+  handler.stop
+}
+
+handler.listen(162)