Class: SNMP::Manager

Inherits:
Object
  • Object
show all
Defined in:
lib/snmp/manager.rb

Overview

This class provides a manager for interacting with a single SNMP agent.

Example

require 'snmp'

manager = SNMP::Manager.new(:host => 'localhost', :port => 1061)
response = manager.get(["1.3.6.1.2.1.1.1.0", "1.3.6.1.2.1.1.2.0"])
response.each_varbind {|vb| puts vb.inspect}
manager.close

Symbolic Object Names

Symbolic names for SNMP object IDs can be used as parameters to the APIs in this class if the MIB modules are imported and the names of the MIBs are included in the MibModules configuration parameter.

See MIB.varbind_list for a description of valid parameter formats.

The following modules are loaded by default: “SNMPv2-SMI”, “SNMPv2-MIB”, “IF-MIB”, “IP-MIB”, “TCP-MIB”, “UDP-MIB”. All of the current IETF MIBs have been imported and are available for loading.

Additional modules may be imported using the MIB class. The current implementation of the importing code requires that the external ‘smidump’ tool is available in your PATH. This tool can be obtained from the libsmi website at www.ibr.cs.tu-bs.de/projects/libsmi/ .

Example

Do this once:

SNMP::MIB.import_module(MY_MODULE_FILENAME, MIB_OUTPUT_DIR)

Include your module in MibModules each time you create a Manager:

SNMP::Manager.new(:host => 'localhost', :mib_dir => MIB_OUTPUT_DIR,
                  :mib_modules => ["MY-MODULE-MIB", "SNMPv2-MIB", ...])

Defined Under Namespace

Classes: Config

Constant Summary collapse

@@request_id = 
RequestId.new

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Manager

Creates a Manager. The following are valid options and their default values.

Note: The upper-case options supported in previous versions of this library are deprecated, but still supported for now. Use at your own risk.

Option              Default Value
--------------------------------------
:host               'localhost'
:port               161
:trap_port          162
:community          'public'
:write_community    Same as :community
:version            :SNMPv2c
:timeout            1 (timeout units are seconds)
:retries            5
:transport          UDPTransport
:max_recv_bytes     8000 bytes
:mib_dir            MIB::DEFAULT_MIB_PATH
:mib_modules        SNMPv2-SMI, SNMPv2-MIB, IF-MIB, IP-MIB, TCP-MIB, UDP-MIB
:use_IPv6           false, unless :host is formatted like an IPv6 address
:ignore_oid_order   false

Use => :SNMPv1 for SNMP v1. SNMP v3 is not supported.



192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/snmp/manager.rb', line 192

def initialize(options = {})
  if block_given?
    warn "SNMP::Manager.new() does not take block; use SNMP::Manager.open() instead"
  end
  config = Config.new(options)
  @host = config.host
  @port = config.port
  @trap_port = config.trap_port
  @community = config.community
  @write_community = config.write_community
  @snmp_version = config.version
  @timeout = config.timeout
  @retries = config.retries
  @transport = config.create_transport
  @max_bytes = config.max_recv_bytes
  @mib = MIB.new
  @mib_dir = config.mib_dir
  load_modules(config.mib_modules, @mib_dir)
  @ignore_oid_order = config.ignore_oid_order
  @config = config.applied_config
end

Instance Attribute Details

#config ⇒ Object (readonly)

Retrieves the current configuration of this Manager.



160
161
162
 
# File 'lib/snmp/manager.rb', line 160

def config
  @config
end

#mib ⇒ Object (readonly)

Retrieves the MIB for this Manager.



165
166
167
 
# File 'lib/snmp/manager.rb', line 165

def mib
  @mib
end

Class Method Details

.open(config = {}) ⇒ Object

Creates a Manager but also takes an optional block and automatically closes the transport connection used by this manager after the block completes.



219
220
221
222
223
224
225
226
227
228
 
# File 'lib/snmp/manager.rb', line 219

def self.open(config = {})
  manager = Manager.new(config)
  if block_given?
    begin
      yield manager
    ensure
      manager.close
    end
  end
end

Instance Method Details

#close ⇒ Object

Close the transport connection for this manager.



233
234
235
 
# File 'lib/snmp/manager.rb', line 233

def close
  @transport.close
end

#create_trap_vb_list(sys_up_time, trap_oid, object_list) ⇒ Object

Helper method for building VarBindList for trap and inform requests.



390
391
392
393
394
395
 
# File 'lib/snmp/manager.rb', line 390

def create_trap_vb_list(sys_up_time, trap_oid, object_list)
  vb_args = @mib.varbind_list(object_list, :KeepValue)
  uptime_vb = VarBind.new(SNMP::SYS_UP_TIME_OID, TimeTicks.new(sys_up_time.to_int))
  trap_vb = VarBind.new(SNMP::SNMP_TRAP_OID_OID, @mib.oid(trap_oid))
  VarBindList.new([uptime_vb, trap_vb, *vb_args])
end

#get(object_list) ⇒ Object

Sends a get request for the supplied list of ObjectId or VarBind objects.

Returns a Response PDU with the results of the request.



243
244
245
246
247
 
# File 'lib/snmp/manager.rb', line 243

def get(object_list)
  varbind_list = @mib.varbind_list(object_list, :NullValue)
  request = GetRequest.new(@@request_id.next, varbind_list)
  try_request(request)
end

#get_bulk(non_repeaters, max_repetitions, object_list) ⇒ Object

Sends a get-bulk request. The non_repeaters parameter specifies the number of objects in the object_list to be retrieved once. The remaining objects in the list will be retrieved up to the number of times specified by max_repetitions.



289
290
291
292
293
294
295
296
297
 
# File 'lib/snmp/manager.rb', line 289

def get_bulk(non_repeaters, max_repetitions, object_list)
  varbind_list = @mib.varbind_list(object_list, :NullValue)
  request = GetBulkRequest.new(
      @@request_id.next,
      varbind_list,
      non_repeaters,
      max_repetitions)
  try_request(request)
end

#get_next(object_list) ⇒ Object

Sends a get-next request for the supplied list of ObjectId or VarBind objects.

Returns a Response PDU with the results of the request.



277
278
279
280
281
 
# File 'lib/snmp/manager.rb', line 277

def get_next(object_list)
  varbind_list = @mib.varbind_list(object_list, :NullValue)
  request = GetNextRequest.new(@@request_id.next, varbind_list)
  try_request(request)
end

#get_value(object_list) ⇒ Object

Sends a get request for the supplied list of ObjectId or VarBind objects.

Returns a list of the varbind values only, not the entire response, in the same order as the initial object_list. This method is useful for retrieving scalar values.

For example:

SNMP::Manager.open(:host => "localhost") do |manager|
  puts manager.get_value("sysDescr.0")
end



263
264
265
266
267
268
269
 
# File 'lib/snmp/manager.rb', line 263

def get_value(object_list)
  if object_list.respond_to? :to_ary
    get(object_list).vb_list.collect { |vb| vb.value }
  else
    get(object_list).vb_list.first.value
  end
end

#inform(sys_up_time, trap_oid, object_list = []) ⇒ Object

Sends an inform request using the supplied varbind list.

sys_up_time: An integer respresenting the number of hundredths of a second that this system has been up.

trap_oid: An ObjectId or String with the OID identifier for this inform request.

object_list: A list of additional varbinds to send with the inform.



381
382
383
384
385
 
# File 'lib/snmp/manager.rb', line 381

def inform(sys_up_time, trap_oid, object_list=[])
  vb_list = create_trap_vb_list(sys_up_time, trap_oid, object_list)
  request = InformRequest.new(@@request_id.next, vb_list)
  try_request(request, @community, @host, @trap_port)
end

#load_module(name, mib_dir = @mib_dir) ⇒ Object 



490
491
492
 
# File 'lib/snmp/manager.rb', line 490

def load_module(name, mib_dir = @mib_dir)
  @mib.load_module(name, mib_dir)
end

#load_modules(module_list, mib_dir = @mib_dir) ⇒ Object 



494
495
496
 
# File 'lib/snmp/manager.rb', line 494

def load_modules(module_list, mib_dir = @mib_dir)
  module_list.each { |m| load_module(m, mib_dir) }
end

#next_request_id=(request_id) ⇒ Object

Set the next request-id instead of letting it be generated automatically. This method is useful for testing and debugging.



486
487
488
 
# File 'lib/snmp/manager.rb', line 486

def next_request_id=(request_id)
  @@request_id.force_next(request_id)
end

#set(object_list) ⇒ Object

Sends a set request using the supplied list of VarBind objects.

Returns a Response PDU with the results of the request.



304
305
306
307
308
 
# File 'lib/snmp/manager.rb', line 304

def set(object_list)
  varbind_list = @mib.varbind_list(object_list, :KeepValue)
  request = SetRequest.new(@@request_id.next, varbind_list)
  try_request(request, @write_community)
end

#trap_v1(enterprise, agent_addr, generic_trap, specific_trap, timestamp, object_list = []) ⇒ Object

Sends an SNMPv1 style trap.

enterprise: The enterprise OID from the IANA assigned numbers (www.iana.org/assignments/enterprise-numbers) as a String or an ObjectId.

agent_addr: The IP address of the SNMP agent as a String or IpAddress.

generic_trap: The generic trap identifier. One of :coldStart, :warmStart, :linkDown, :linkUp, :authenticationFailure, :egpNeighborLoss, or :enterpriseSpecific

specific_trap: An integer representing the specific trap type for an enterprise-specific trap.

timestamp: An integer respresenting the number of hundredths of a second that this system has been up.

object_list: A list of additional varbinds to send with the trap.

For example:

 Manager.open(:Version => :SNMPv1) do |snmp|
   snmp.trap_v1(
     "enterprises.9",
     "10.1.2.3",
     :enterpriseSpecific,
      42,
     12345,
     [VarBind.new("1.3.6.1.2.3.4", Integer.new(1))])
end



343
344
345
346
347
348
349
350
351
 
# File 'lib/snmp/manager.rb', line 343

def trap_v1(enterprise, agent_addr, generic_trap, specific_trap, timestamp, object_list=[])
  vb_list = @mib.varbind_list(object_list, :KeepValue)
  ent_oid = @mib.oid(enterprise)
  agent_ip = IpAddress.new(agent_addr)
  specific_int = Integer(specific_trap)
  ticks = TimeTicks.new(timestamp)
  trap = SNMPv1_Trap.new(ent_oid, agent_ip, generic_trap, specific_int, ticks, vb_list)
  send_request(trap, @community, @host, @trap_port)
end

#trap_v2(sys_up_time, trap_oid, object_list = []) ⇒ Object

Sends an SNMPv2c style trap.

sys_up_time: An integer respresenting the number of hundredths of a second that this system has been up.

trap_oid: An ObjectId or String with the OID identifier for this trap.

object_list: A list of additional varbinds to send with the trap.



364
365
366
367
368
 
# File 'lib/snmp/manager.rb', line 364

def trap_v2(sys_up_time, trap_oid, object_list=[])
  vb_list = create_trap_vb_list(sys_up_time, trap_oid, object_list)
  trap = SNMPv2_Trap.new(@@request_id.next, vb_list)
  send_request(trap, @community, @host, @trap_port)
end

#walk(object_list, index_column = 0) ⇒ Object

Walks a list of ObjectId or VarBind objects using get_next until the response to the first OID in the list reaches the end of its MIB subtree.

The varbinds from each get_next are yielded to the given block as they are retrieved. The result is yielded as a VarBind when walking a single object or as a VarBindList when walking a list of objects.

Normally this method is used for walking tables by providing an ObjectId for each column of the table.

For example:

SNMP::Manager.open(:host => "localhost") do |manager|
  manager.walk("ifTable") { |vb| puts vb }
end

SNMP::Manager.open(:host => "localhost") do |manager|
  manager.walk(["ifIndex", "ifDescr"]) do |index, descr|
    puts "#{index.value} #{descr.value}"
  end
end

The index_column identifies the column that will provide the index for each row. This information is used to deal with “holes” in a table (when a row is missing a varbind for one column). A missing varbind is replaced with a varbind with the value NoSuchInstance.

Note: If you are getting back rows where all columns have a value of NoSuchInstance then your index column is probably missing one of the rows. Choose an index column that includes all indexes for the table.

Raises:

  • (ArgumentError) 


430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
 
# File 'lib/snmp/manager.rb', line 430

def walk(object_list, index_column=0)
  raise ArgumentError, "expected a block to be given" unless block_given?
  vb_list = @mib.varbind_list(object_list, :NullValue)
  raise ArgumentError, "index_column is past end of varbind list" if index_column >= vb_list.length
  is_single_vb = object_list.respond_to?(:to_str) ||
      object_list.respond_to?(:to_varbind)
  start_list = vb_list
  start_oid = vb_list[index_column].name
  last_oid = start_oid
  loop do
    vb_list = get_next(vb_list).vb_list
    index_vb = vb_list[index_column]
    break if EndOfMibView == index_vb.value
    stop_oid = index_vb.name
    if !@ignore_oid_order && stop_oid <= last_oid
      warn "OIDs are not increasing, #{last_oid} followed by #{stop_oid}"
      break
    end
    break unless stop_oid.subtree_of?(start_oid)
    last_oid = stop_oid
    if is_single_vb
      yield index_vb
    else
      vb_list = validate_row(vb_list, start_list, index_column)
      yield vb_list
    end
  end
end