SNMP Library for EventMachine ↑

Summary ↑

This gem extends Ruby-SNMP to use the asynchronous EventMachine library for added performance and scalability. This allows code to scale monitoring applications to access a very high number of devices without the need for complex asynchronous I/O handling.

Features ↑

The library currently supports:

Future revisions of this library may support:

There are no plans to support SNMP v3 or the parsing of MIB files.

Options ↑

You may set the following options:

SNMP4EM::Manager.new(
  :version => :SNMPv2c,
  :host => "127.0.0.1",
  :port => 161,
  :community => "public",      # Shorthand for setting both :community_ro and :community_rw
  :community_ro => "public",
  :community_rw => "public",
  :fiber => false,
  :timeout => 1,
  :retries => 3                # Can also be specified as an array of individual timeouts
                               # For instance, [0.5, 1, 2.5] would send three requests with increasing timeout values
)

These options may also be passed to an individual query method, for instance:

snmp = SNMP4EM::Manager.new(...)
snmp.get(OID, :retries => 2, :timeout => 1)

And when receiving traps:

SNMP4EM::NotificationManager.new(
  :host => "127.0.0.1",        # Local interface on which to listen for traps. By default, localhost only!
  :port => 161                 # Port on which to listen for traps.
)

Backwards compatibility ↑

Version 1.0.0 tweaks the return values of a few functions. Please test code thoroughly before upgrading to 1.0.0 in production!

Running tests ↑

This library now includes a full suite of functional tests. They communicate with an SNMP daemon running on the localhost. The library comes with the necessary configuration, but it's much easier to fire up the provided rake task (`rake server`), running in a separate terminal window, before running `rspec`. This works fine on a Mac OS X machine using homebrew (`brew install net-snmp`).

Acknowledgements ↑

Examples ↑

A few definitions:

OID_SYSTEM = "1.3.6.1.2.1.1"
OID_SYSNAME = "1.3.6.1.2.1.1.5.0"
OID_SYSLOCATION = "1.3.6.1.2.1.1.6.0"

A simple SNMP-GET:

EM.run {
  snmp = SNMP4EM::Manager.new(:host => "192.168.1.1")

  request = snmp.get([OID_SYSNAME, OID_SYSLOCATION])

  request.callback do |response|
    puts "System name = #{response[OID_SYSNAME]}"
    puts "System location = #{response[OID_SYSLOCATION]}"
  end

  request.errback do |error|
    puts "GET got error #{error}"
  end
}

A simple SNMP-GETNEXT:

EM.run {
  snmp = SNMP4EM::Manager.new(:host => "192.168.1.1")

  request = snmp.getnext(OID_SYSNAME)

  request.callback do |response|
    r = response[OID_SYSNAME]
    puts "The next OID is #{r[0]}, the next value is #{r[1]}"
  end

  request.errback do |error|
    puts "GETNEXT got error #{error}"
  end
}

A simple SNMP-SET:

EM.run {
  snmp = SNMP4EM::Manager.new(:host => "192.168.1.1")

  request = snmp.set({OID_SYSNAME => "My System Name", OID_SYSLOCATION => "My System Location"})

  request.callback do |response|
    if (response[OID_SYSNAME] == true)
      puts "System name set successful"
    else
      puts "System name set unsuccessful: #{response[OID_SYSNAME]}"
    end

    if (response[OID_SYSLOCATION] == true)
      puts "System location set successful"
    else
      puts "System location set unsuccessful: #{response[OID_SYSLOCATION]}"
    end
  end

  request.errback do |error|
    puts "SET got error #{error}"
  end
}

A simple SNMP-WALK:

EM.run {
  snmp = SNMP4EM::Manager.new(:host => "192.168.1.1")

  request = snmp.walk(OID_SYSTEM)

  request.callback do |response|
    response[OID_SYSTEM].each do |oid, value|
      puts "#{oid} = #{value}"
    end
  end

  request.errback do |error|
    puts "WALK got error #{error}"
  end
}

A simple SNMP-BULKWALK:

EM.run {
  snmp = SNMP4EM::Manager.new(:host => "192.168.1.1")

  request = snmp.bulkwalk(OID_SYSTEM)

  request.callback do |response|
    response[OID_SYSTEM].each do |oid, value|
      puts "#{oid} = #{value}"
    end
  end

  request.errback do |error|
    puts "BULK-WALK got error #{error}"
  end
}

A simple SNMP-GET-BULK:

EM.run {
  snmp = SNMP4EM::Manager.new(:host => "192.168.1.1")

  request = snmp.getbulk(OID_SYSTEM)

  request.callback do |response|
    response[OID_SYSTEM].each do |oid, value|
      puts "#{oid} = #{value}"
    end
  end

  request.errback do |error|
    puts "GET-BULK got error #{error}"
  end
}

Handling traps:

EM.run {
  manager = SNMP4EM::NotificationManager.new

  manager.on_trap do |trap|
    if trap.is_a? SNMP::SNMPv1_Trap
      puts "Got a SNMPv1_Trap"
    elsif trap.is_a? SNMP::SNMPv2_Trap
      puts "Got a SNMPv2_Trap"
    end
  end
}

Fiber Support ↑

If your Ruby supports it, you can pass enable fibers, either per-manager or per-request. This unwinds much of the complexity in writing event-driven code. Instead of receiving an object on which to hang callbacks, the current fiber will be suspended until the response is available. If an error occurs, it will be returned as a SNMP::RequestTimeout. Unfortunately, there is no way to raise this error, you are responsible for manually checking whether the returned object is an error or not.

For example:

EM.run {
  snmp = SNMP4EM::Manager.new(:host => "192.168.1.1")

  f = Fiber.new do
    response = snmp.get([OID_SYSNAME, OID_SYSLOCATION])

    if response.is_a? SNMP::RequestTimeout
      puts "Uh oh!"
    else
      puts "System name = #{response[OID_SYSNAME]}"
      puts "System location = #{response[OID_SYSLOCATION]}"
    end
  end
}

Change Log ↑

Version 1.1.5:

Version 1.1.5:

Version 1.1.2:

Version 1.1.0:

Version 1.0.2:

Version 1.0.1:

Version 1.0.0:

Version 0.2.1:

Version 0.2.0:

Version 0.1.0:

Credits ↑

Author: Norman Elton normelton@gmail.com