File: README

# README

Path: | README
Last Update: | Tue Aug 10 17:58:25 -0600 2010

# 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. You can run this library anywhere that Ruby can run.

See snmplib.rubyforge.org for more info.

Version 1.0.2 of this software supports the following:

- The GetRequest, GetNextRequest, GetBulkRequest, SetRequest, Response SNMPv1_Trap, SNMPv2_Trap, and Inform PDUs
- All of the ASN.1 data types defined by SNMPv1 and SNMPv2c
- Sending informs and v1 and v2 traps
- Trap handling for informs and 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
- Compatibility with both Ruby 1.8 and Ruby 1.9

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

## Changes

Changes for version 1.0.2:

- Internal code changes to make this library compatible with both Ruby 1.8 and Ruby 1.9. Note that an ord() method is now added to the Fixnum class for Ruby 1.8. See the ber.rb file for details.

Changes for version 1.0.1:

- Made the host configurable for the TrapListener. Previously defaulted to ‘localhost’.

Changes for version 1.0.0:

- Added to_s method to TimeTicks. Displays time in human-readable form instead of just a number. The to_i method can still be used to get the number of ticks.

Changes for version 0.6.1:

- Made decoding of unsigned integers more liberal, so that they are interpreted as positive integers even if the high bit is set.
- Added support for receiving InformRequest PDUs from the TrapListener class.

Changes for version 0.6.0:

- Added support for sending informs and traps for SNMPv2c and traps for SNMPv1
- Improved SNMP::Manager#walk so that it can handle missing varbinds when reading tables. The indexes for a table row read by walk are now guaranteed to match.
- Added to_oid methods to SNMP::OctetString, SNMP::Integer, and SNMP::IpAddress (feature request 2486)
- Fixed some problems with retrying requests that caused annoying "Request ID mismatch" warnings and caused too few retries to be attempted
- Thanks to Mark Cotner, Dan Hamlin, Tim Howe, Diana Eichert, Ery Lee, Jan Åge Johnsen, and Jeff Foster for their help and suggestions (and apologies in advance if I have forgotten someone).

Changes for version 0.5.1:

- Fixed bugs 2054 and 2164. Responses were ignored if they did not come back from the same host that the request was sent to. This behavior causes problems for some multi-homed hosts.
- 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 for version 0.4.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 for version 0.3.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 for version 0.2.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 [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 in several different formats.

From the .gem file you can install using RubyGems.

      gem install snmp-1.0.2.gem

From the .tgz or .zip file you can install using setup.rb. Uncompress the archive and then run setup.

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

## Testing

This library has received limited testing:

- The unit tests have been executed with both Ruby 1.8.6 and Ruby 1.9.0 on Mac OS X 10.5.
- Basic interoperability testing has been done with the net-snmp tools.

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

Send me an email at hallidave at gmail.com.

## 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-2007 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.

[Validate]