Class: SNMP::Manager

### Home Classes Methods

### In Files

- lib/snmp/manager.rb

### Parent

Object

### Namespace

- CLASS SNMP::Manager::Config

### Methods

- ::new
- ::open
- #close
- #create_trap_vb_list
- #get
- #get_bulk
- #get_next
- #get_value
- #inform
- #load_module
- #load_modules
- #next_request_id=
- #set
- #trap_v1
- #trap_v2
- #walk

### Files

- README.rdoc

### Class/Module Index

Quicksearch

- SNMP
- SNMP::BER
- SNMP::Counter32
- SNMP::Counter64
- SNMP::EndOfMibView
- SNMP::Gauge32
- SNMP::GetBulkRequest
- SNMP::GetNextRequest
- SNMP::GetRequest
- SNMP::InformRequest
- SNMP::Integer
- SNMP::Integer32
- SNMP::InvalidErrorStatus
- SNMP::InvalidGenericTrap
- SNMP::InvalidIpAddress
- SNMP::InvalidPduTag
- SNMP::InvalidTrapVarbind
- SNMP::IpAddress
- SNMP::MIB
- SNMP::MIB::ModuleNotLoadedError
- SNMP::Manager
- SNMP::Manager::Config
- SNMP::Message
- SNMP::NoSuchInstance
- SNMP::NoSuchObject
- SNMP::Null
- SNMP::ObjectId
- SNMP::ObjectName
- SNMP::OctetString
- SNMP::Opaque
- SNMP::PDU
- SNMP::ParseError
- SNMP::RequestId
- SNMP::RequestTimeout
- SNMP::Response
- SNMP::SNMPv1_Trap
- SNMP::SNMPv2_Trap
- SNMP::SetRequest
- SNMP::TimeTicks
- SNMP::TrapListener
- SNMP::TrapListener::Config
- SNMP::UDPServerTransport
- SNMP::UDPTransport
- SNMP::Unsigned32
- SNMP::UnsignedInteger
- SNMP::UnsupportedPduTag
- SNMP::UnsupportedValueTag
- SNMP::UnsupportedVersion
- SNMP::VarBind
- SNMP::VarBindList
- Fixnum
- Object

No matching classes.

# SNMP::Manager

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", ...])

### Attributes

config[R]

Retrieves the current configuration of this Manager.

mib[R]

Retrieves the MIB for this Manager.

### Public Class Methods

new(options = {}) click to toggle source

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

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

    # File lib/snmp/manager.rb, line 176
    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
      load_modules(config.mib_modules, config.mib_dir)
      @config = config.applied_config
    end

open(config = {}) click to toggle source

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

    # File lib/snmp/manager.rb, line 201
    def self.open(config = {})
      manager = Manager.new(config)
      if block_given?
        begin
          yield manager
        ensure
          manager.close
        end
      end
    end

### Public Instance Methods

close() click to toggle source

Close the transport connection for this manager.

    # File lib/snmp/manager.rb, line 215
    def close
      @transport.close
    end

create_trap_vb_list(sys_up_time, trap_oid, object_list) click to toggle source

Helper method for building VarBindList for trap and inform requests.

    # File lib/snmp/manager.rb, line 376
    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) click to toggle source

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

Returns a Response PDU with the results of the request.

    # File lib/snmp/manager.rb, line 229
    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) click to toggle source

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.

    # File lib/snmp/manager.rb, line 275
    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) click to toggle source

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

Returns a Response PDU with the results of the request.

    # File lib/snmp/manager.rb, line 263
    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) click to toggle source

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

    # File lib/snmp/manager.rb, line 249
    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=[]) click to toggle source

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.

    # File lib/snmp/manager.rb, line 367
    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) click to toggle source

    # File lib/snmp/manager.rb, line 219
    def load_module(name)
      @mib.load_module(name)
    end

load_modules(module_list, mib_dir) click to toggle source

    # File lib/snmp/manager.rb, line 476
    def load_modules(module_list, mib_dir)
      module_list.each { |m| @mib.load_module(m, mib_dir) }
    end

next_request_id=(request_id) click to toggle source

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

    # File lib/snmp/manager.rb, line 472
    def next_request_id=(request_id)
      @@request_id.force_next(request_id)
    end

set(object_list) click to toggle source

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

Returns a Response PDU with the results of the request.

    # File lib/snmp/manager.rb, line 290
    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=[]) click to toggle source

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

    # File lib/snmp/manager.rb, line 329
    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=[]) click to toggle source

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.

    # File lib/snmp/manager.rb, line 350
    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) click to toggle source

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.

    # File lib/snmp/manager.rb, line 416
    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 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

[Validate]

Generated with the Darkfish Rdoc Generator 2.