Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
ruby library for snmp. uses ffi to connect to net-snmp libs
Ruby C
Tag: v0.1.7

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
interface
lib
spec
.document
.gitignore
.rspec
Gemfile
LICENSE
README.rdoc
Rakefile
net-snmp.gemspec

README.rdoc

net-snmp

DESCRIPTION

net-snmp is a Ruby object oriented wrapper around the C netsnmp libraries. It provides classes for sessions, pdus, varbinds, and more.

FEATURES

  • Supports SNMP versions 1, 2c, and 3

  • Supports both synchronous and asynchronous calls

  • Integrates well with eventmachine, or can be used standalone.

  • In Ruby 1.9, uses fibers behind the scenes to emulate synchronous calls asynchronously

USAGE

You must have the net-snmp libraries installed and available on the system. Check to make sure they are available in your library path. If necessary, add them to your shell like so:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/local/lib/net-snmp

You can use the library in two styles: synchronously or asynchronously. If you use the synchronous style, calls will block until a result is returned or the request times out. If you use the asynchronous style, you must provide a block to the client methods, which will be called when the data is ready.

In order for your callbacks to fire, you must call Net::SNMP::Dispatcher.poll You may pass a timeout argument to the dispatcher. If you pass false, the call will block forever until data is ready. If you pass an integer, it will block for <timeout> seconds. If you pass nil (the default), it will do a poll and return immediately. In that case, you will have to arrange for the dispatcher to run periodically. This can be done in your main event loop or in a seperate thread. There are convenience class methods in Net::SNMP::Dispatcher called run_loop, fiber_loop, em_loop, thread_loop and so on for setting up various polling loops. Or, you can roll your own loop.

If you like eventmachine, it's very easy to set up the dispatcher to run periodically in the adaptor. If you're using eventmachine with ruby 1.9, the library uses fibers behind the scenes to turn your synchronous calls into asynchronous calls, while allowing you to use a synchronous calling style. Examples of all these scenarios are below.

FFI

This library uses ruby-ffi to access the net-snmp libraries. If you want to use the C library directly, the wrapper functions are defined in Net::SNMP::Wrapper. You can call them like so:

Net::SNMP::Wrapper.snmp_perror("some_error")

NOTES

You must call Session.close when you're done with a session to avoid leaking memory

EXAMPLES

A simple synchronous SNMP-GET

session = Net::SNMP::Session.open(:peername => "test.net-snmp.org", :community => "demopublic" )
result = session.get("sysDescr.0")
puts result.varbinds.first.value
session.close

An asynchronous SNMP-GET

session = Net::SNMP::Session.open(:peername => 'test.net-snmp.org', :community => 'demopublic') do |session|
  session.get(["sysDescr.0", "sysContact.0"]) do |result|
    puts result.varbinds[0].value
  end
end
Net::SNMP::Dispatcher.poll(false)  #Setting timeout to false causes dispatcher to block until data is ready
session.close

Running the dispatcher from eventmachine

EM.run do
  Net::SNMP::Dispatcher.em_loop
  session = Net::SNMP::Session.open(:peername => 'test.net-snmp.org', :community => 'demopublic') do |session|
    session.get("sysDescr.0") do |result|
      puts result.varbinds[0].value
    end
  end
  EM.add_timer(2) do
    session.close
    EM.stop
  end
end

Using synchronous style with eventmachine in ruby 1.9

EM.run do
    Net::SNMP::Dispatcher.fiber_loop
    Fiber.new {
      session = Net::SNMP::Session.open(:peername => 'test.net-snmp.org', :community => 'demopublic')
      result = session.get("sysDescr.0")
      puts result.varbinds[0].value
      session.close
      EM.stop
    }.resume
end

In the last example, note that you must wrap your code in Fiber.new {}.resume. You could instead use the em-synchrony gem, and wrap your loop with EM.synchrony{}. Note that even though it appears you are making a blocking call, waiting for a return value, actually in the background, control is passed back to the reactor fiber to process other requests. get() will return once the data is available. This is all seemless to you, the developer. Behold the power of fibers!

MIBs

By default, net-snmp loads all of your system MIBS. You can add additional mibs by adding them to your MIBS environment variable. You can also explicitly add MIBs using the MIB api. For example:

Net::SNMP::MIB.add_mibdir("/usr/local/share/mibs")
Net::SNMP::MIB.read_mib("RFC1213-MIB.txt")

Having the appropriate MIBs loaded will allow you to pass names instead of numeric oids to net-snmp methods. To translate a single oid, you can call Net::SNMP.get_oid(“sysDescr.0”). For more complex MIB parsing needs, see smi-ffi

BUGS

Right now, snmpv3 is only working using synchronous API. Asynchronous calls seem to miss packets. I have no idea why it would be different for v3 vs v1/v2. If anyone knows, tell me ;)

CAVEATS/DISCLAIMER

THIS GEM COULD CRASH YOUR SYSTEM AND EAT YOUR CHILDREN!

You have been warned.

The API is subject to change.

This is very much alpha software. For more information on usage, take a look at the specs. Currently it's only tested against net-snmp 5.5. The net-snmp api seems pretty stable, but if anything changes, it could break this gem. Please let me know if you find bugs or missing features. Or better yet, send a pull request.

TODO

  • Better error handling.

  • SNMPv3 support needs testing for various security models

  • Better documentation

  • More tests

  • Cleanup cruft and unused code

  • Implement SNMP traps/informs?

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.

Copyright

Copyright © 2010 mixtli. See LICENSE for details.

Something went wrong with that request. Please try again.