= SNMP Library for Ruby

== Summary

This library implements SNMP (the Simple Network Management Protocol).  It is
implemented in pure Ruby, so there are no dependencies on external libraries
like net-snmp[http://www.net-snmp.org/].  You can run this library anywhere
that Ruby can run.

See snmplib.rubyforge.org[http://snmplib.rubyforge.org/] for more info.

Version 0.5.0 of this software supports the following:

* The GetRequest, GetNextRequest, GetBulkRequest, SetRequest, and Response
  PDUs
* All of the ASN.1 data types defined by SNMPv1 and SNMPv2c
* Trap handling for both v1 and v2 traps
* Symbolic OID values (ie. "ifTable" instead of "1.3.6.1.2.1.2.2") as   
  parameters to the SNMP.Manager API
* Includes symbol data files for all current IETF MIBs 

See the SNMP.Manager, SNMP.TrapListener, and SNMP.MIB classes and the
examples below for more details.

== Changes

Changes from version 0.4.0:

* Fixed bugs #1679 (NameError in Manager.get_response()) and #1736 
  (Notifications not included in YAML output).
* Added Manager.get_value convenience method to get a list of values for a 
  list of OIDs instead of the full VarBindList list like Manager.get.
* Added vb_list alias for PDU.varbind_list.
* Changed how Manager.walk yields to it's block.  It is now more consistent 
  about yielding a list if a list is provided as an argument.
* Break out of Manager.walk instead of looping forever if OIDs returned by the 
  remote host are not in ascending order.

Changes from version 0.3.0:

* Added support for loading MIBs and using symbolic OID values.
* Enhanced Manager.walk
    * It can now take an OID list as a parameter.  (Thanks to Simon
      Barnes for the suggestion.)
    * Takes a block instead of returning a list to allow incremental
      processing of results.
* Some minor improvements to code structure and error messages.

Changes from version 0.2.0:

* Added SNMPv1_Trap and SNMPv2_Trap classes
* Added TrapListener class for receiving v1 and v2 traps
* Added Manager.walk
* Fixed a problem with IpAddress encoding
* Defined IpAddress.== and IpAddress.eql? so that IpAddress objects can be
  compared by value

Changes from version 0.1.0:

* Added GetBulkRequest
* Added open and close methods to the Manager class to ensure that
  sockets can be properly released.
* Made SNMP::OctetString and SNMP::Integer behave more like Ruby's String and 
  Fixnum
* Fixed a problem with encoding/decoding the object id "0.0"

== Installation

You can use RubyGems [http://rubyforge.org/projects/rubygems] to
install the latest version of the SNMP library remotely.

  gem install --remote snmp

The SNMP Library can be downloaded from
RubyForge[http://rubyforge.org/projects/snmplib/] in several different
formats.

From the .gem file you can install using
RubyGems[http://rubyforge.org/projects/rubygems].

  gem install snmp-0.5.0.gem

From the .tgz or .zip file you can install using
setup.rb[http://i.loveruby.net/en/prog/setup.html].  Uncompress the archive
and then run setup.

  cd snmp-0.5.0
  ruby setup.rb (may require root privilege)  

== Testing

This library has received limited testing:
* The unit tests have been executed with Ruby 1.8.2 on Mac OS X 10.4 and
  Windows XP.
* Basic interoperability testing has been done with the
  net-snmp[http://www.net-snmp.org/] tools, but not much beyond that.

I'm very interested in hearing about successes or failures on other platforms.

Send me an email at snmp at halliday.ca.

== Examples

=== Get Request

Retrieve a system description.

  require 'snmp'
  
  SNMP::Manager.open(:Host => 'localhost') do |manager|
      response = manager.get(["sysDescr.0", "sysName.0"])
      response.each_varbind do |vb|
          puts "#{vb.name.to_s}  #{vb.value.to_s}  #{vb.value.asn1_type}"
      end
  end

=== Set Request

Create a varbind for setting the system name.

  require 'snmp'
  include SNMP

  manager = Manager.new(:Host => 'localhost')
  varbind = VarBind.new("1.3.6.1.2.1.1.5.0", OctetString.new("My System Name"))
  manager.set(varbind)
  manager.close

=== Table Walk

Walk the ifTable.

  require 'snmp'

  ifTable_columns = ["ifIndex", "ifDescr", "ifInOctets", "ifOutOctets"]
  SNMP::Manager.open(:Host => 'localhost') do |manager|
      manager.walk(ifTable_columns) do |row|
          row.each { |vb| print "\t#{vb.value}" }
          puts
      end
  end

=== Get-Next Request

A more difficult way to walk the ifTable.
 
  require 'snmp'
  include SNMP

  Manager.open(:Host => 'localhost') do |manager|
      ifTable = ObjectId.new("1.3.6.1.2.1.2.2")
      next_oid = ifTable
      while next_oid.subtree_of?(ifTable)
          response = manager.get_next(next_oid)
          varbind = response.varbind_list.first
          next_oid = varbind.name
          puts varbind.to_s
      end
  end

=== Get-Bulk Request

Get interface description and admin status for 10 rows of the ifTable.

  require 'snmp'
  include SNMP

  ifDescr_OID = ObjectId.new("1.3.6.1.2.1.2.2.1.2")
  ifAdminStatus_OID = ObjectId.new("1.3.6.1.2.1.2.2.1.7")
  MAX_ROWS = 10
  Manager.open(:Host => 'localhost') do |manager|
      response = manager.get_bulk(0, MAX_ROWS, [ifDescr_OID, ifAdminStatus_OID])
      list = response.varbind_list
      until list.empty?
          ifDescr = list.shift
          ifAdminStatus = list.shift
          puts "#{ifDescr.value}    #{ifAdminStatus.value}"
      end
  end

=== Trap Handling

Log traps to STDOUT.

  require 'snmp'
  require 'logger'

  log = Logger.new(STDOUT)
  m = SNMP::TrapListener.new do |manager|
      manager.on_trap_default do |trap|
          log.info trap.inspect
      end
  end
  m.join
   
== License

This SNMP Library is Copyright (c) 2004,2005 by David R. Halliday.  It is free
software.  Redistribution is permitted under the same terms and conditions as
the standard Ruby distribution.  See the COPYING file in the Ruby distribution
for details.