Difference between revisions of "SNMP MIB Implementation"

From OpenCircuits
Jump to navigation Jump to search
Line 1: Line 1:
This wiki describe how to generate a MIB (Management Information Base) for SNMP agent.
+
==[http://www.rane.com/note161.html=Build SNMP's PDU using BER]==
 
 
==Steps==
 
# Create a ASN.1 MIB script '''foo.mib''' (an ASCII text file) for the tree structure.
 
# Convert foo.mib to binary file using '''mib2bin'''
 
# Build [http://www.rane.com/note161.html SNMP's PDU using BER (Base encoding rules)] encoder and decoder library to process data that's transfer between NMS and agents.
 
# Build SNMP API use [http://www.sics.se/~adam/uip/index.php/Main_Page uIP-stack] to communicate between NMS and Agents (open two ports: The manager speak to agents on one port, the agent responds manager on the other port).
 
# Build binary MIB file reader library.
 
# Build functions service oid tree.
 
# Merge MIB ANS.1 file to NMS.
 
 
 
 
 
==Create ASN.1 MIB Script==
 
* Build MIB file's written in [http://www.itu.int/ITU-T/studygroups/com17/languages/X.680-0207.pdf ANS.1 notation].
 
* Tutorial: [http://www.scribd.com/doc/276412/Understanding-SNMP-Stack Understanding SNMP Stack] to create ASN.1 MIB Script.
 
* Tools to create ASN.1 MIB Script
 
** [http://www.asnlab.com/asndt/installing.html ASN.1 Editor plugin for Eclipse] (Now using).
 
** [http://packages.ubuntu.com/karmic/asn1-mode Emacs mode for editing ASN.1 files].
 
 
 
===Abstract Syntax Notation===
 
*Each MIB variable contains several attributes, such as data type, access type and object identifier.
 
*Abstract Syntax Notation version 1 (ASN.1) is a language to define these attributes in SNMP.
 
 
 
 
 
==Convert MIB to Binary File==
 
* mib2bin tool is modified from [http://net-snmp.sourceforge.net/ net-snmp] to convert ASN.1 format file to three files, because the microchip '''mib2bib''' converter only supports upto 255 OIDs.
 
                                MIB compiler tools: '''mib2bin'''
 
  [http://www.modtronix.com/products/sbc44ec/00870a.pdf foo.mib] (ANS.1 format)  -----------------------------------> foo.bin + foo_trap.bin + foo.h + foo_data.h
 
 
 
* Syntax to use mib2bin tool:
 
  '''mib2bin <MIBfile>...
 
* where MIBfile file is ASN.1 format file. MIBfile = <name>.<type>
 
** '''<name>.bin''' is the binary file storing information of OID tree. This file can be placed on an SD media card to be read by the FAT16 file system.
 
** '''<name>_trap.bin''' is the binary file storing information of TRAP of MIB. This file can be placed on an SD media card to be read by the FAT16 file system.
 
** '''<name>_data.h''' is C header file storing information of OID tree.  This file is generated by converting mchip.bin file to the C header file.
 
It's only used when a system don't have system file and place on program memory.
 
** '''<name>.h''' is C header file storing ID that's reference to function service of OID.
 
* Note:
 
** Subfolder '''mibs''' containing the basics MIB files (e.g.: RFC1155-SMI, RFC1213-MIB, RFC-1215, SNMPv2-MIB ... for us MIB file), must be present under the directory of execution.
 
** If the three files exist, mib2bin tool will overwrite the files.
 
 
 
===Binary File Format <name>.bin===
 
* The binary file is an image of MIB file. It is generated by mib2bin tool. Agents will read binary file to respond NMS request.
 
* In the binary file, A parent is stored first, followed by its first-child to last-child. Next, the structure of next this parent is stored. This structure is repeated until the entire tree is stored.
 
* A parent or child is a record. Single record of binary file have format:
 
  <oid>, <nodeInfo>,
 
  [id], [siblingOffset]/[distantSiblingOffset], [dataType], [dataLen], [data],
 
  [{<IndexNumber>}, {<IndexCount>, <IndexNodeInfo>, <IndexDataType>} ...]
 
* where:
 
** fields indicated by angle brackets (< >) are always present
 
** fields in square brackets ([ ]) are optional depending on characteristics of the current node.
 
** fields in braces ({ }) are optional but always occur together.
 
 
 
====<oid> field====
 
* The microchip format only supports OIDs upto 255. The following is an workaround to store OID greater than 255.
 
* Format of OID:
 
      An OID is a series of (one or more) octets. Bit 8 of each octet indicates whether it is the last in the series: bit 8 of the last octet is zero;
 
  bit 8 of each preceding octet is one. Bits 7 to 1 of the octets in the series collectively encode the OID. Conceptually, these groups of bits are
 
  concatenated to form an unsigned binary number whose most significant bit is bit 7 of the first octet and whose least significant bit is bit 1 of
 
  the last octet. The OID shall be encoded in the fewest possible octets, that is, the leading octet of the OID shall not have the value 0x80.
 
 
 
* Example:
 
    The OID              encode of OID in binary file (hex)
 
      4                        BYTE(0x04)
 
      1                        BYTE(0x01)
 
    36061                      BYTE(0x80+ 0x02) BYTE(0x80 + 0x19) BYTE(0x5D)
 
    The OID = 36061 is decoded by 0x02*0x80*0x80 + 0x19*0x80 + 0x5D
 
 
 
====<nodeInfo> field====
 
* information of node
 
  bit        when (set = 1)
 
  0          Node has sibling node
 
  1          Node has default data
 
  2          Node is sequence
 
  3          Node is readable
 
  4          Node is a parent
 
  5          Node is writable
 
  6          Node is able to modify
 
  7          Node has sibling field (in IndexNodeInfo this bit indicate that Indexes is imply)
 
 
 
====[id] field====
 
* If this record is leaf, id that's reference to function services the record.
 
 
 
====[distantSiblingOffset] field====
 
* If this record is a node [distantSiblingOffset] is enabled. Point to next node sibling.
 
* In little-endian format.
 
* The last node's distant offset is set to 0x00000000.
 
 
 
====[siblingOffset] field====
 
* If this record is a leaf [siblingOffset] is enabled. Point to next leaf sibling.
 
  siblingOffset and distantSiblingOffset in this format is same function (point to next node sibling).
 
  They're only differences:
 
      siblingOffset use with leaf node.
 
      distantSiblingOffset use with node.
 
  so it's same value.
 
 
 
====[dataType] field====
 
*If this record is a leaf
 
** [dataType] is type of leaf's data.
 
* The tool supports the following base data types defined in SNMPv1:
 
** '''INTEGER''': The integer data type is a signed integer in the range of -2,147,483,648 to 2,147,483,647.
 
** '''OCTETSTRING''': Octet strings are ordered sequences of 0 to 65,535 octets.
 
** '''Gauge''': Nonnegative integers that can increase or decrease but retain the maximum value reached. The limit of 2^32 -1.
 
** '''TimeTicks''': A hundredth of a second since some event. The limit of 2^32 -1.
 
** '''Counter''': Nonnegative integers that increase until they reach a maximum value (2^32 -1); then, the integers return to zero.
 
** '''DisplayString''': a special case of the octet string type where all the bytes are printable ASCII characters, include formatting characters such as CR and LF, and the C programming language string terminator character zero.
 
** '''IpAddress''': A four byte octet string in network order.
 
** '''NetworkAddress''': Used to indicate an address choice from one of the possible protocol families. Currently, only IP addresses are supported.
 
** '''Opaque''': An arbitrary encoding that is used to pass arbitrary information strings that do not conform to the strict data typing used by the mib.
 
** '''SEQUENCE''': An ordered list of objects, somewhat like a struct in the C language. Type of objects in sequence is same type of node.
 
 
 
====[dataLen], [data] fields====
 
* If this record is a leaf and has default data
 
** [dataLen] is length of data.
 
** [data] is data on string.
 
 
 
====[{<IndexNumber>}] and [{<IndexCount>, <IndexNodeInfo>, <IndexDataType>}] fields====
 
* If this record is sequence (an order list of objects),
 
** <IndexNumber> is the number of INDEXes in sequence.
 
** <IndexCount>: is id of index node in table
 
** <IndexNodeInfo>: is info of index node
 
** <IndexDataType>: is data type of index node
 
* See [http://www.simpleweb.org/w/images/9/91/Tutorial_Slides_Smi.pdf example] of accessing data in a table
 
* Example:
 
** '''trap''' node is a sequence to inform the NMS of a significant event (an extraordinary event has occurred at an agent) asynchronously. This sequence has two INDEXes, so we have:
 
      <IndexNumber> = 0x02
 
      with the 1st INDEX:
 
          <IndexCount> = 0x05
 
          <IndexNodeInfo> = 0x28
 
          <IndexDataType> = 0x02
 
      with the 2nd INDEX:
 
          <IndexCount> = 0x08
 
          <IndexNodeInfo> = 0xA4
 
          <IndexDataType> = 0x04
 
  In this example, '''trap''' is a table which has 4 columns:
 
      <font color=blue>trapReceiverNumber (1)</font>, trapEnabled (2), trapReceiverIPAddress (3), <font color=blue>trapCommunity(4)</font>.
 
      <font color=blue>trapReceiverNumber (1)</font>, trapEnabled (2), trapReceiverIPAddress (3), <font color=blue>trapCommunity(4)</font>.
 
      <font color=blue>trapReceiverNumber (1)</font>, trapEnabled (2), trapReceiverIPAddress (3), <font color=blue>trapCommunity(4)</font>.
 
  Each significant event will be a row defined in the '''trap''' table.
 
 
 
  This example has two INDEXes: the 1st INDEX node is trapCommunity (4) and the 2nd INDEX node trapReceiverNumber (1)
 
  Each INDEX is a node, so it has OID, info, data type.
 
  The 1st INDEX node is trapCommunity, which has id = 5, info is 0x28 and data type is INTEGER (0x02). so
 
          IndexCount = 0x04
 
          IndexNodeInfo = 0x28
 
          IndexDataType = 0x02
 
  The 2nd INDEX node is trapReceiverNumber, which has id = 8, info is 0xA4 and data type is DisplayString (0x04). so
 
          IndexCount = 0x01
 
          IndexNodeInfo = 0xA4
 
          IndexDataType = 0x04
 
 
 
===Binary File Format <name>_trap.bin===
 
* The binary file store TRAP information. It is generated by mib2bin tool. Agents will read binary file to get information of TRAP when something bad occurs.
 
* In the binary file, A enterprise OID is stored first, followed by its first specific trap number and ID (this ID is match with ID of leaf in <name>.bin) data bindings to be included in this trap to last specific trap number and ID data bindings to be included it. Next, the structure of next this enterprise is stored. This structure is repeated until all enterprise in MIB file is stored.
 
* The format of enterprise in <name>_trap.bin
 
  <enterprise_oid><sibling_enterprise><enterprise_index>[specific_trap_number][sibling_specific_trap][number_varbinds][id_varbind]...
 
* where:
 
** fields indicated by angle brackets (< >) are always present.
 
** fields in square brackets ([ ]) are optional depending on characteristics of the trap.
 
 
 
====<enterprise_oid> field====
 
* Enterprise oid is full oid of enterprise trap that want to send in MIB file.
 
* The format of enterprise oid.
 
  <sub_oid> <info_sub_oid> ...
 
* where:
 
**  <font color=red><sub_oid>:</font> is same format of <oid> field in MIB file.
 
**  <font color=red><info_sub_oid>:</font> Information of sub_oid.
 
  <info_sub_oid> format:
 
      bit        when (set = 1)
 
      0          the first sub_oid in enterprise
 
      1          no use
 
      2          no use
 
      3          no use
 
      4          sub_oid is a parent
 
      5          no use
 
      6          no use
 
      7          the last sub_oid in enterprise
 
* If <sub_oid> == BYTE (0x00) and <info_sub_oid> == BYTE(0xFF), this is the end of infomation traps.
 
 
 
====<sibling_enterprise> field====
 
* Point to next enterprise OID.
 
* In little-endian format.
 
====<enterprise_index> field====
 
* Index of enterprise OID traps in <name>_trap.bin file.
 
* Size of <enterprise_index> is 1 byte.
 
====[specific_trap_number] field====
 
* If the trap is sent is specific trap, specific trap number is a number indicting specific trap.
 
* specific trap number is integer in little-endian format.
 
====[sibling_specific_trap] field====
 
* Point to next specific trap.
 
* In little-endian format.
 
====[number_varbinds] field====
 
* A number of data bindings to be included in the specific trap.
 
* Size of [number_varbinds] is 1 byte.
 
====[id_varbind] field====
 
* [id_varbind] define data bindings (OID and value of OID leaf) that is included specific trap.
 
* [id_varbind] is reference to id of the leaf oid in <name>.bin.
 
* In little-endian format.
 
 
 
===Example===
 
 
 
====OID Tree====
 
* An example OID tree is given below:
 
[[File:Snmp mib oid tree example.jpg | thumb | center | 900px]]
 
 
 
====Binary File <name>.bin====
 
* The corresponding binary file is <name>.bin and it has data describe in  table below:
 
** '''oid''' is <oid> fields.
 
** '''info''' is <nodeInfo> fields.
 
** '''dist''' is [distantSiblingOffset]/[siblingOffset] fields.
 
** '''id''' is [id] fields.
 
** '''type''' is [dataType] fields.
 
** '''index''' is index fields of sequence, include [{index_number} , {<IndexCount>, <IndexNodeInfo>, <indexDataType>, ...}].
 
 
 
[[File:Snmp mib binary example.jpg | thumb | center | 900px]]
 
 
 
* The detail description of <name>.bin is illustrated in the diagram below:
 
** The black arrow lines represent the OID tree structure.
 
** The red and green lines represent pointers to data.
 
** The dist field points to next sibling record. After parent record is it's children.
 
[[File:Snmp mib binary detail example.jpg | thumb | center | 900px]]
 
 
 
====Binary File <name>_trap.bin====
 
* The corresponding binary file is <name>_trap.bin and it has data describe in  table below:
 
** '''enterp''' is <enterprise_oid> fields.
 
** '''sibl_ep''' is <sibling_enterprise> fields.
 
** '''index_ep''' is <enterprise_index> fields.
 
** '''spec_id''' is [specific_trap_number] fields.
 
** '''sibl_sid''' is [sibling_specific_trap] fields.
 
** '''num_var''' is [number_varbinds] fields.
 
** '''id_var''' is [id_varbind] fields.
 
[[File:Snmp mib binary trap example.jpg | thumb | center | 900px]]
 
 
 
==Build SNMP's PDU using BER==
 
 
* SNMP is the protocol that allows communicate between NMS and agents by exchanging SNMP messages. the SNMP message is a single field, of the Sequence type. SNMP message use data types specified by ASN.1 and use Basic Encoding Rules (BER) to encode data. The entire SNMP message is a Sequence of three smaller fields: the SNMP Version (Integer), the SNMP Community String (Octet String), and the SNMP PDU.  
 
* SNMP is the protocol that allows communicate between NMS and agents by exchanging SNMP messages. the SNMP message is a single field, of the Sequence type. SNMP message use data types specified by ASN.1 and use Basic Encoding Rules (BER) to encode data. The entire SNMP message is a Sequence of three smaller fields: the SNMP Version (Integer), the SNMP Community String (Octet String), and the SNMP PDU.  
 
* The SNMP's PDU is reference to SNMP version 1 (SNMPv1) PDU.
 
* The SNMP's PDU is reference to SNMP version 1 (SNMPv1) PDU.
Line 243: Line 10:
 
** ASN.1 complex data types are used to build SNMP message are Sequence type, Sequence-of type.
 
** ASN.1 complex data types are used to build SNMP message are Sequence type, Sequence-of type.
  
===Basic Encoding Rules (BER)===
+
===[http://www.google.com/url?sa=t&source=web&cd=1&ved=0CBgQFjAA&url=http%3A%2F%2Fwww.itu.int%2FITU-T%2Fstudygroups%2Fcom17%2Flanguages%2FX.690-0207.pdf&rct=j&q=x.690-0207&ei=cde_TcrvJouMvQOm5-jABA&usg=AFQjCNGYmD4USBwcWoeHoRFZ3zdP39kosw&cad=rja=Basic Encoding Rules (BER)]===
 
* BER has three parts: Type, Length and Data field.
 
* BER has three parts: Type, Length and Data field.
 
   BER format:  
 
   BER format:  
Line 319: Line 86:
 
       | 0x02 | 0x81 0x01 | 0x64  |
 
       | 0x02 | 0x81 0x01 | 0x64  |
 
       +------+-----------+-------+
 
       +------+-----------+-------+
===GetRequest PDU, GetNextRequest PDU, GetResponse PDU, SetRequest PDU Format===
+
===SNMP Message Format===
===Trap PDU Format===
+
* SNMP Message is a Sequence of three smaller fields: the SNMP Version (Integer), the SNMP Community String (Octet String), and the SNMP PDU.
 +
  SNMP Message Format use BER.
 +
      +------------------------------------------------------------------------+
 +
      |                      SNMP Message (Sequence type)                      |
 +
      +------+-----------------------------------------------------------------+
 +
      | Type | Length of Data |                      Data                      |
 +
      +------+----------------+-------------+-----------------------+----------+
 +
      | 0x30 |    Length    |SNMP Version | SNMP Community String | SNMP PDU |                     
 +
      |      |                |  (Integer)  |    (Octet String)    |          |
 +
      +------+----------------+-------------+-----------------------+----------+
 +
* Length is bytes of Data field (SNMP Version, SNMP Community String and SNMP PDU).
 +
* SNMP Version is an integer that identifies the version of SNMP, SNMP version 1 = 0.
 +
* SNMP Community String is an Octet String to add security to Agents.
 +
* SNMP PDU is SNMP verion 1 (SNMPv1) PDU.
 +
 
 +
===SNMPv1 PDU Format===
 +
====GetRequest PDU, GetNextRequest PDU, GetResponse PDU, SetRequest PDU Format====
 +
====Trap PDU Format====

Revision as of 08:08, 3 May 2011

SNMP's PDU using BER

  • SNMP is the protocol that allows communicate between NMS and agents by exchanging SNMP messages. the SNMP message is a single field, of the Sequence type. SNMP message use data types specified by ASN.1 and use Basic Encoding Rules (BER) to encode data. The entire SNMP message is a Sequence of three smaller fields: the SNMP Version (Integer), the SNMP Community String (Octet String), and the SNMP PDU.
  • The SNMP's PDU is reference to SNMP version 1 (SNMPv1) PDU.
  • SNMPv1 PDU have five different PDU types:GetRequest, GetNextRequest, GetResponse, SetRequest and Trap.
  • Get Request, GetNext Request, Get Response, Set Request are same format PDU. Trap use other format PDU.

ASN.1 data types

  • ASN.1 data types fall into two categories: primitive and complex.
  • ASN.1 data types is used to build SNMP messages.
    • ASN.1 primitive data types include Integer, Octet (byte, character) String, Null, Boolean and Object Identifier.
    • ASN.1 complex data types are used to build SNMP message are Sequence type, Sequence-of type.

Encoding Rules (BER)

  • BER has three parts: Type, Length and Data field.
  BER format: 
     +------+--------+------+
     | Type | Length | Data |
     +------+--------+------+
  • Type field is single byte identifier.
  Constructing byte Data type.
  Format of byte Data type
     +--+-+-----+
     |  | |     +
     +--+-+-----+
      2  1   5
  Bits 8 and 7 shall be encoded to represent the class of Data type follow table:
     +------------------+-------+-------+
     |      Class       | Bit 8 | Bit 7 |
     +------------------+-------+-------+
     | Universal        |   0   |   0   |
     | Application      |   0   |   1   |
     | Context-specific |   1   |   0   |
     | Private          |   1   |   1   |
     +------------------+-------+-------+
  Bit 6 is encoded data is Primitive or Constructed follow table:
     +-------+-------------+
     | Bit 6 |   Type      |
     +-------+-------------+
     |   0   | Primitive   |
     |   1   | Constructed |
     +-------+-------------+ 
  Bits 5 to 1 encode the number of Data type as a integer number.     
  Data type identifier in SNMP
     Data type                 Identifier      Note
     Integer                      0x02         Primitive ASN.1 types
     Octet String                 0x04         Primitive ASN.1 types  
     Null                         0x05         Primitive ASN.1 types
     Object identifier            0x06         Primitive ASN.1 types
     Sequence                     0x30         Constructed ASN.1 types
     IpAddress                    0x40         Primitive SNMP application types
     Counter                      0x41         Primitive SNMP application types
     Gauge                        0x42         Primitive SNMP application types
     TimeTicks                    0x43         Primitive SNMP application types 
     Opaque                       0x44         Primitive SNMP application types
     NsapAddress                  0x45         Primitive SNMP application types
     GetRequest PDU               0xA0         Context-specific Constructed SNMP types
     GetNextRequest PDU           0xA1         Context-specific Constructed SNMP types
     GetResponse PDU              0xA2         Context-specific Constructed SNMP types
     SetRequest PDU               0xA3         Context-specific Constructed SNMP types
     Trap PDU                     0xA4         Context-specific Constructed SNMP types
  • Length field is the number of bytes in Data field.
    • Length field is used either the short form or the long form as a option depend on Data field.
      • The short form, Length field is a single octet in which bit 8 is zero and bits 7 to 1 encode the number of bytes in Data field, as an unsigned binary integer with bit 7 as the most significant bit.
      • The long form, Length field shall consists of an initial octet and one or more subsequent octets.
        • The initial octet is encoded as follows:
          • Bit 8 shall be one.
          • Bits 7 to 1 shall encode the number of subsequent octets in the length field, as an unsigned binary integer with bit 7 as the most significant bit.
          • The value 0xFF shall not be used.
        • Subsequent octets:
          • From the first subsequent octet to the last subsequent octet, shall be the encoding of an unsigned binary integer equal to the number bytes in Data field, with bit 8 of the first subsequent octet as the most significant bit.
  • Data field is actual data content.
  • Example:
  Actual Data is an integer, the value 100 can be encode as:
  The short form:
     +------+--------+-------+
     | Type | Length | Data  |
     +------+--------+-------+
     | 0x02 |  0x01  | 0x64  |
     +------+--------+-------+
  The long form:
     +------+-----------+-------+
     | Type |  Length   | Data  |
     +------+-----------+-------+
     | 0x02 | 0x81 0x01 | 0x64  |
     +------+-----------+-------+

SNMP Message Format

  • SNMP Message is a Sequence of three smaller fields: the SNMP Version (Integer), the SNMP Community String (Octet String), and the SNMP PDU.
  SNMP Message Format use BER.
     +------------------------------------------------------------------------+
     |                      SNMP Message (Sequence type)                      |
     +------+-----------------------------------------------------------------+
     | Type | Length of Data |                      Data                      |
     +------+----------------+-------------+-----------------------+----------+
     | 0x30 |     Length     |SNMP Version | SNMP Community String | SNMP PDU |                      
     |      |                |  (Integer)  |    (Octet String)     |          |
     +------+----------------+-------------+-----------------------+----------+
  • Length is bytes of Data field (SNMP Version, SNMP Community String and SNMP PDU).
  • SNMP Version is an integer that identifies the version of SNMP, SNMP version 1 = 0.
  • SNMP Community String is an Octet String to add security to Agents.
  • SNMP PDU is SNMP verion 1 (SNMPv1) PDU.

SNMPv1 PDU Format

GetRequest PDU, GetNextRequest PDU, GetResponse PDU, SetRequest PDU Format

Trap PDU Format