snmp 0.4.0

data/lib/snmp/mib.rb

@@ -0,0 +1,259 @@
+#
+# Copyright (c) 2004 David R. Halliday
+# All rights reserved.
+#
+# This SNMP library 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.
+#
+
+require 'snmp/varbind'
+require 'rbconfig'
+require 'fileutils'
+require 'yaml'
+
+module SNMP
+
+class MIB
+
+    #:stopdoc:
+    share_path = File.join(Config::CONFIG["datadir"], "ruby", "snmp", "mibs")
+    data_path = File.expand_path(
+        File.join(File.dirname(__FILE__), "..", "..", "data", "ruby", "snmp", "mibs")
+    )
+    if (File.exist?(share_path) && File.exist?(data_path))
+        warn "Found two MIB directories:\n  #{share_path}\n  #{data_path}\n" +
+             "Using MIB::DEFAULT_MIB_PATH=#{data_path}"
+        DEFAULT_MIB_PATH = data_path
+    elsif (File.exist?(data_path))
+        DEFAULT_MIB_PATH = data_path
+    elsif (File.exist?(share_path))
+        DEFAULT_MIB_PATH = share_path
+    else
+        warn "Could not find default MIB directory, tried:\n  #{share_path}\n  #{data_path}"
+        DEFAULT_MIB_PATH = nil 
+    end
+    #:startdoc:
+    
+    MODULE_EXT = 'yaml'
+    
+    class ModuleNotLoadedError < RuntimeError; end
+    
+    class << self
+        ##
+        # Import an SMIv2 MIB file for later loading.  A module only needs to
+        # be installed once.
+        #
+        #   module_file - the filename of the module to be imported
+        #   mib_dir - the output directory for the serialized MIB data
+        #
+        # NOTE: This implementation requires that the 'smidump' tool is available
+        # in the PATH.  This tool can be obtained from the libsmi website at
+        # http://http://www.ibr.cs.tu-bs.de/projects/libsmi/ .
+        #
+        # ALSO NOTE: The file format in future releases is subject to
+        # change.  For now, it is a simple YAML hash with the MIB symbol
+        # as the key and the OID as the value.  These files could be
+        # generated manually if 'smidump' is not available.
+        #
+        # Here is an example of the contents of an output file:
+        #
+        #   --- 
+        #   ipDefaultTTL: 1.3.6.1.2.1.4.2
+        #   ipForwDatagrams: 1.3.6.1.2.1.4.6
+        #   ipOutRequests: 1.3.6.1.2.1.4.10
+        #   ipOutNoRoutes: 1.3.6.1.2.1.4.12
+        #   ipReasmTimeout: 1.3.6.1.2.1.4.13
+        #   icmpInDestUnreachs: 1.3.6.1.2.1.5.3
+        #
+        def import_module(module_file, mib_dir=DEFAULT_MIB_PATH)
+            raise "smidump tool must be installed" unless import_supported?
+            FileUtils.makedirs mib_dir
+            mib_hash = `smidump -f python #{module_file}`
+            mib = eval_mib_data(mib_hash)
+            if mib
+                module_name = mib["moduleName"]
+                raise "#{module_file}: invalid file format; no module name" unless module_name
+                if mib["nodes"]
+                    oid_hash = {}
+                    mib["nodes"].each { |key, value| oid_hash[key] = value["oid"] }
+                    File.open(module_file_name(module_name, mib_dir), 'w') do |file|
+                        YAML.dump(oid_hash, file)
+                    end
+                    module_name
+                else
+                    warn "*** No nodes defined in: #{module_file} ***"
+                    nil
+                end
+            else
+                warn "*** Import failed for: #{module_file} ***"
+                nil
+            end
+        end
+
+        ##
+        # Returns the full filename of the imported MIB file for the given
+        # module name.
+        #
+        def module_file_name(module_name, mib_dir=DEFAULT_MIB_PATH)
+            File.join(mib_dir, module_name + "." + MODULE_EXT)
+        end
+
+        ##
+        # The MIB.import_module method is only supported if the external
+        # 'smidump' tool is available.  This method returns true if a
+        # known version of the tool is available.
+        #
+        def import_supported?
+            `smidump --version` =~ /^smidump 0.4/  && $? == 0 
+        end
+
+        ##
+        # Returns a list of MIB modules that have been imported.  All of
+        # the current IETF MIBs should be available from the default
+        # MIB directory. 
+        #
+        # If a regex is provided, then the module names are matched
+        # against that pattern.
+        #
+        def list_imported(regex=//, mib_dir=DEFAULT_MIB_PATH)
+            list = []
+            Dir["#{mib_dir}/*.#{MODULE_EXT}"].each do |name|
+                module_name = File.basename(name, ".*")
+                list << module_name if module_name =~ regex
+            end
+            list
+        end
+        
+        private 
+        
+        def eval_mib_data(mib_hash)
+            ruby_hash = mib_hash.
+                gsub(':', '=>').                  # fix hash syntax
+                gsub('(', '[').gsub(')', ']').    # fix tuple syntax
+                sub('FILENAME =', 'filename =').  # get rid of constants
+                sub('MIB =', 'mib =')
+            mib = nil
+            eval(ruby_hash)
+            mib
+        end
+    end # class methods
+    
+    def initialize
+        @by_name = {}
+        @by_module_by_name = {}
+    end
+    
+    ##
+    # Loads a module into this MIB.  The module must be imported before it
+    # can be loaded.  See MIB.import_module .
+    #
+    def load_module(module_name, mib_dir=DEFAULT_MIB_PATH)
+        oid_hash = nil
+        File.open(MIB.module_file_name(module_name, mib_dir)) do |file|
+            oid_hash = YAML.load(file.read)
+        end
+        @by_name.merge!(oid_hash) do |key, old, value|
+            warn "warning: overwriting old MIB name '#{key}'"
+        end
+        @by_module_by_name[module_name] = {}
+        @by_module_by_name[module_name].merge!(oid_hash)
+    end
+
+    ##
+    # Returns a VarBindList for the provided list of objects.  If a
+    # string is provided it is interpretted as a symbolic OID.
+    #
+    # This method accepts many different kinds of objects:
+    # - single string object IDs e.g. "1.3.6.1" or "IF-MIB::ifTable.1.1"
+    # - single ObjectId
+    # - list of string object IDs
+    # - list of ObjectIds
+    # - list of VarBinds
+    # 
+    def varbind_list(object_list, option=:KeepValue)
+        vb_list = VarBindList.new
+        if object_list.respond_to? :to_str
+            vb_list << oid(object_list).to_varbind
+        elsif object_list.respond_to? :to_varbind
+            vb_list << apply_option(object_list.to_varbind, option)
+        else
+            object_list.each do |item|
+                if item.respond_to? :to_str
+                    varbind = oid(item).to_varbind
+                else
+                    varbind = item.to_varbind
+                end
+                vb_list << apply_option(varbind, option)
+            end
+        end
+        vb_list
+    end
+
+    def apply_option(varbind, option)
+        if option == :NullValue
+            varbind.value = Null
+        elsif option != :KeepValue
+            raise ArgumentError, "invalid option: #{option.to_s}", caller
+        end
+        varbind
+    end
+    private :apply_option
+    
+    ##
+    # Returns a VarBind object for the given name and value.  The name
+    # can be a String, ObjectId, or anything that responds to :to_varbind.
+    #
+    # String names are in the format <ModuleName>::<NodeName>.<Index> with
+    # ModuleName and Index being optional.
+    #
+    def varbind(name, value=Null)
+        if name.respond_to? :to_str
+            vb = VarBind.new(oid(name), value)
+        else
+            vb = name.to_varbind
+            vb.value = value
+        end
+        vb
+    end
+    
+    ##
+    # Returns an ObjectId for the given name.  Names are in the format
+    # <ModuleName>::<NodeName>.<Index> with ModuleName and Index being
+    # optional.
+    # 
+    def oid(name)
+        module_parts = name.to_str.split("::")
+        if module_parts.length == 1
+            parse_oid(@by_name, name.to_str)
+        elsif module_parts.length == 2
+            module_name = module_parts[0]
+            oid = module_parts[1]
+            module_hash = @by_module_by_name[module_name]
+            if module_hash
+                parse_oid(module_hash, oid)
+            else
+                raise ModuleNotLoadedError, "module '#{module_name}' not loaded"
+            end
+        else
+            raise ArgumentError, "invalid format: #{name.to_str}"
+        end
+    end
+
+    def parse_oid(node_hash, name)
+        oid_parts = name.split(".")
+        first_part = oid_parts.shift
+        oid_string = node_hash[first_part]
+        if oid_string
+            oid_array = oid_string.split(".")
+        else
+            oid_array = [first_part]
+        end
+        oid_array.concat(oid_parts)
+        ObjectId.new(oid_array)
+    end
+    private :parse_oid
+    
+end
+
+end # module SNMP

data/lib/snmp/pdu.rb

@@ -0,0 +1,363 @@
+#
+# Copyright (c) 2004 David R. Halliday
+# All rights reserved.
+#
+# This SNMP library 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.
+#
+
+require 'snmp/ber'
+require 'snmp/varbind'
+
+include SNMP::BER
+
+module SNMP
+
+# Exceptions thrown during message/pdu decoding
+class UnsupportedVersion < RuntimeError; end
+class UnsupportedPduTag < RuntimeError; end
+class InvalidPduTag < RuntimeError; end
+class ParseError < RuntimeError; end
+class InvalidErrorStatus < RuntimeError; end
+class InvalidTrapVarbind < RuntimeError; end
+class InvalidGenericTrap < RuntimeError; end
+
+class Message
+    attr_reader :version
+    attr_reader :community
+    attr_reader :pdu
+    
+    class << self
+        def decode(data)
+            message_data, remainder = decode_sequence(data)
+            assert_no_remainder(remainder)
+            version, remainder = decode_version(message_data)
+            community, remainder = decode_octet_string(remainder)
+            pdu, remainder = decode_pdu(version, remainder)
+            assert_no_remainder(remainder)
+            Message.new(version, community, pdu)
+        end
+
+        def decode_version(data)
+            version_data, remainder = decode_integer(data)
+            if version_data == SNMP_V1
+                version = :SNMPv1
+            elsif version_data == SNMP_V2C
+                version = :SNMPv2c
+            else
+                raise UnsupportedVersion, version_data.to_s
+            end
+            return version, remainder
+        end
+        
+        def decode_pdu(version, data)
+            pdu_tag, pdu_data, remainder = decode_tlv(data)
+            case pdu_tag
+            when GetRequest_PDU_TAG
+                pdu = PDU.decode(GetRequest, pdu_data)
+            when GetNextRequest_PDU_TAG
+                pdu = PDU.decode(GetNextRequest, pdu_data)
+            when Response_PDU_TAG
+                pdu = PDU.decode(Response, pdu_data)
+            when SetRequest_PDU_TAG
+                pdu = PDU.decode(SetRequest, pdu_data)
+            when SNMPv1_Trap_PDU_TAG
+                raise InvalidPduTag, "SNMPv1-trap not valid for #{version.to_s}" if version != :SNMPv1
+                pdu = SNMPv1_Trap.decode(pdu_data)
+            when GetBulkRequest_PDU_TAG
+                raise InvalidPduTag, "get-bulk not valid for #{version.to_s}" if version != :SNMPv2c
+                pdu = PDU.decode(GetBulkRequest, pdu_data)
+            when SNMPv2_Trap_PDU_TAG
+                raise InvalidPduTag, "SNMPv2c-trap not valid for #{version.to_s}" if version != :SNMPv2c
+                pdu = PDU.decode(SNMPv2_Trap, pdu_data)
+            else
+                raise UnsupportedPduTag, pdu_tag.to_s
+            end
+            return pdu, remainder
+        end
+    end
+    
+    def initialize(version, community, pdu)
+        @version = version
+        @community = community
+        @pdu = pdu
+    end
+    
+    def response
+        Message.new(@version, @community, Response.from_pdu(@pdu))
+    end
+    
+    def encode_version(version)
+        if version == :SNMPv1
+            encode_integer(SNMP_V1)
+        elsif version == :SNMPv2c
+            encode_integer(SNMP_V2C)
+        else
+            raise UnsupportedVersion, version.to_s
+        end
+    end
+    
+    def encode
+        data = encode_version(@version)
+        data << encode_octet_string(@community)
+        data << @pdu.encode
+        encode_sequence(data)
+    end
+end
+
+class PDU
+    attr_accessor :request_id
+    attr_accessor :error_index
+    attr_accessor :varbind_list
+    
+    def self.decode(pdu_class, pdu_data)
+        request_id, remainder = decode_integer(pdu_data)
+        error_status, remainder = decode_integer(remainder)
+        error_index, remainder = decode_integer(remainder)
+        varbind_list, remainder = VarBindList.decode(remainder)
+        assert_no_remainder(remainder)
+        pdu_class.new(request_id, varbind_list, error_status, error_index)
+    end
+
+    ERROR_STATUS_NAME = {
+         0 => :noError,
+         1 => :tooBig,
+         2 => :noSuchName,
+         3 => :badValue,
+         4 => :readOnly,
+         5 => :genErr,
+         6 => :noAccess,
+         7 => :wrongType,
+         8 => :wrongLength,
+         9 => :wrongEncoding,
+        10 => :wrongValue,
+        11 => :noCreation,
+        12 => :inconsistentValue,
+        13 => :resourceUnavailable,
+        14 => :commitFailed,
+        15 => :undoFailed,
+        16 => :authorizationError,
+        17 => :notWritable,
+        18 => :inconsistentName
+    }
+    
+    ERROR_STATUS_CODE = ERROR_STATUS_NAME.invert
+    
+    def initialize(request_id, varbind_list, error_status=0, error_index=0)
+        @request_id = request_id
+        self.error_status = error_status
+        @error_index = error_index.to_int
+        @varbind_list = varbind_list
+    end
+    
+    def error_status=(status)
+        @error_status = ERROR_STATUS_CODE[status]
+        unless @error_status
+            if status.respond_to?(:to_int) && ERROR_STATUS_NAME[status.to_int]
+                @error_status = status
+            else
+                raise InvalidErrorStatus, status.to_s
+            end
+        end
+    end
+    
+    def error_status
+        ERROR_STATUS_NAME[@error_status]
+    end
+    
+    def encode_pdu(pdu_tag)
+        pdu_data = encode_integer(@request_id)
+        pdu_data << encode_integer(@error_status)
+        pdu_data << encode_integer(@error_index)
+        pdu_data << @varbind_list.encode
+        encode_tlv(pdu_tag, pdu_data)
+    end
+    
+    def each_varbind(&block)
+        @varbind_list.each(&block)
+    end
+end
+
+class GetRequest < PDU
+    def encode
+        encode_pdu(GetRequest_PDU_TAG)
+    end
+end
+
+class GetNextRequest < PDU
+    def encode
+        encode_pdu(GetNextRequest_PDU_TAG)
+    end
+end
+
+class SetRequest < PDU
+    def encode
+        encode_pdu(SetRequest_PDU_TAG)
+    end
+end
+
+class GetBulkRequest <  PDU
+    alias max_repetitions error_index
+    alias max_repetitions= error_index=
+    
+    def encode
+        encode_pdu(GetBulkRequest_PDU_TAG)
+    end
+    
+    def non_repeaters=(number)
+        @error_status = number
+    end
+    
+    def non_repeaters
+        @error_status
+    end
+end
+
+class Response < PDU
+    class << self
+        def from_pdu(request)
+            Response.new(request.request_id, request.varbind_list,
+                request.error_status, request.error_index)
+        end
+    end
+    
+    def encode
+        encode_pdu(Response_PDU_TAG)
+    end
+end
+
+##
+# The PDU class for traps in SNMPv2c.  Methods are provided for retrieving
+# the values of the mandatory varbinds: the system uptime and the OID of the
+# trap.  The complete varbind list is available through the usual varbind_list
+# method.  The first two varbinds in this list will always be the uptime
+# and trap OID varbinds.
+#
+class SNMPv2_Trap < PDU
+    def encode
+        encode_pdu(SNMPv2_Trap_PDU_TAG)
+    end
+
+    ##
+    # Returns the source IP address for the trap, usually derived from the
+    # source IP address of the packet that delivered the trap.
+    # 
+    attr_accessor :source_ip
+    
+    ##
+    # Returns the value of the mandatory sysUpTime varbind for this trap.
+    #
+    # Throws InvalidTrapVarbind if the sysUpTime varbind is not present.
+    #
+    def sys_up_time
+        sys_up_time_oid = ObjectId.new("1.3.6.1.2.1.1.3.0")
+        varbind = @varbind_list[0]
+        if varbind && (varbind.name == sys_up_time_oid)
+            return varbind.value
+        else
+            raise InvalidTrapVarbind, "Expected sysUpTime.0, found " + varbind.to_s
+        end
+    end
+
+    ##
+    # Returns the value of the mandatory snmpTrapOID varbind for this trap.
+    #
+    # Throws InvalidTrapVarbind if the snmpTrapOID varbind is not present.
+    #
+    def trap_oid
+        snmp_trap_oid_oid = ObjectId.new("1.3.6.1.6.3.1.1.4.1.0")
+        varbind = @varbind_list[1]
+        if varbind && (varbind.name == snmp_trap_oid_oid)
+            return varbind.value
+        else
+            raise InvalidTrapVarbind, "Expected snmpTrapOID.0, found " + varbind.to_s 
+        end
+    end
+end
+
+##
+# The PDU class for traps in SNMPv1.
+#
+class SNMPv1_Trap
+    ##
+    # Returns the source IP address for the trap, usually derived from the
+    # source IP address of the packet that delivered the trap.
+    # 
+    attr_accessor :source_ip
+
+    attr_accessor :enterprise
+    attr_accessor :agent_addr
+    attr_accessor :specific_trap
+    attr_accessor :timestamp
+    attr_accessor :varbind_list
+    
+    def self.decode(pdu_data)
+        oid_data, remainder = decode_object_id(pdu_data)
+        enterprise = ObjectId.new(oid_data)
+        ip_data, remainder = decode_ip_address(remainder)
+        agent_addr = IpAddress.new(ip_data)
+        generic_trap, remainder = decode_integer(remainder)
+        specific_trap, remainder = decode_integer(remainder)
+        time_data, remainder = decode_timeticks(remainder)
+        timestamp = TimeTicks.new(time_data)
+        varbind_list, remainder = VarBindList.decode(remainder)
+        assert_no_remainder(remainder)
+        SNMPv1_Trap.new(enterprise, agent_addr, generic_trap, specific_trap,
+            timestamp, varbind_list)
+    end
+
+    def initialize(enterprise, agent_addr, generic_trap, specific_trap, timestamp, varbind_list)
+        @enterprise = enterprise
+        @agent_addr = agent_addr
+        self.generic_trap = generic_trap
+        @specific_trap = specific_trap
+        @timestamp = timestamp
+        @varbind_list = varbind_list 
+    end
+    
+    # Name map for all of the generic traps defined in RFC 1157.
+    GENERIC_TRAP_NAME = {
+        0 => :coldStart,
+        1 => :warmStart,
+        2 => :linkDown,
+        3 => :linkUp,
+        4 => :authenticationFailure,
+        5 => :egpNeighborLoss,
+        6 => :enterpriseSpecific
+    }
+    
+    # Code map for all of the generic traps defined in RFC 1157.
+    GENERIC_TRAP_CODE = GENERIC_TRAP_NAME.invert
+    
+    def generic_trap=(trap)
+        @generic_trap = GENERIC_TRAP_CODE[trap]
+        unless @generic_trap
+            if trap.respond_to?(:to_i) && GENERIC_TRAP_NAME[trap.to_i]
+                @generic_trap = trap
+            else
+                raise InvalidGenericTrap, trap.to_s
+            end
+        end
+    end
+    
+    def generic_trap
+        GENERIC_TRAP_NAME[@generic_trap]
+    end
+    
+    def encode
+        pdu_data = @enterprise.encode <<
+                   @agent_addr.encode <<
+                   encode_integer(@generic_trap) <<
+                   encode_integer(@specific_trap) <<
+                   @timestamp.encode <<
+                   @varbind_list.encode
+        encode_tlv(SNMPv1_Trap_PDU_TAG, pdu_data)
+    end
+    
+    def each_varbind(&block)
+        @varbind_list.each(&block)
+    end
+end
+
+end