Management Information Base (MIB) Interface

Management Information Base (MIB) Interface.

Management Information Base (MIB) Interface.

The database controlled by the SNMP Agent is referred to as the Management Information Base (MIB). It is a standard set of statistical and control values. SNMP allows the extension of these standard values with values specific to a particular agent through the use of private MIBs.

The definitions of MIB variables supported by a particular agent are incorporated in descriptor files, written in Abstract Syntax Notation (ASN.1) format, made available to network management client programs so that they can become aware of these MIB variables and their usage.

The MIB variables are referred to as MIB Object Identifiers (OIDs). OID names are hierarchy structured and unique. SNMP uses the OID to identify objects on each network element (device running SNMP agent) that can be managed using SNMP.

The SNMP Agent manages MIB variables that are located in the SNMP_Agent_MIB.c template file. To add the file to your project, simply right-click on the Source group, select Add New Item to Group, then click on User Code Template and scroll in the template files list until you find the SNMP Agent template. The SNMP_Agent_MIB.c file has implemented a scaled-down MIB-II Management Information Base. Only the System MIB is defined by default. The user might expand this table by adding his own MIB variables.

The user can register a callback function with a MIB variable. This function gets called, when the SNMP Manager accesses the MIB variable. This concept allows the SNMP Manager to control the SNMP Agent system. For example to change LED outputs, to write text on embedded LCD module, to read push buttons or analog inputs, etc.

MIB Entry

The SNMP MIB entry information structure NET_SNMP_MIB_INFO describes the MIB variable. The SNMP Agent uses this description to process local MIB variables. This structure is defined as follows:

typedef struct net_snmp_mib_info {
  uint8_t  type;                        // Object Type
  uint8_t  oid_len;                     // Object ID length
  uint8_t  oid[NET_SNMP_MIB_OID_SIZE];  // Object ID value
  uint8_t  var_size;                    // Size of a variable
  void     *var;                        // Pointer to a variable
  void     (*cb_func)(int32_t mode);    // Write/Read event callback function
} const NET_SNMP_MIB_INFO;

The components of NET_SNMP_MIB_INFO structure are:

• the type defines the MIB variable type:

  MIB Type	Description	Size
  NET_SNMP_MIB_INTEGER	Signed Integer	1, 2 or 4 bytes
  NET_SNMP_MIB_OCTET_STR	Octet String entry	max. 110 characters
  NET_SNMP_MIB_BYTE_STR	Byte String entry	max. 110 bytes
  NET_SNMP_MIB_OBJECT_ID	Object Identifier entry	max. 17 bytes
  NET_SNMP_MIB_IP_ADDR	IP Address entry	4 bytes
  NET_SNMP_MIB_COUNTER	Counter entry	1, 2 or 4 bytes
  NET_SNMP_MIB_GAUGE	Gauge entry	1, 2 or 4 bytes
  NET_SNMP_MIB_TIME_TICKS	Time Ticks entry	4 bytes

  The type component may be OR-ed with the NET_SNMP_MIB_ATR_RO read-only attribute. A read-only variable can not be changed by the SNMP Manager.
• the OID specifies the Object Identification Name of the variable. It is length encoded:
  • oid_len specifies the length of the oid[] array.
  • oid[NET_SNMP_MIB_OID_SIZE] array specifies the OID name - a length encoded binary array.
• var specifies the Pointer to the variable and its Size:
  • var_size specifies the size of var variable.
  • var is a pointer to the actual variable.
• the cb_func specifies a callback function which is called, when the variable is accessed by SNMP Manager. The callback function is not registered, when the value of cb_func is NULL. The argument mode of the callback function specifies the access mode of SNMP Manager:

  Mode	Type of Access
  NET_SNMP_MIB_READ	Reads a MIB variable.
  NET_SNMP_MIB_WRITE	Writes to a MIB variable.

MIB Table

The MIB Table table is defined as an array. The components of this array are of type NET_SNMP_MIB_INFO.

static const NET_SNMP_MIB_INFO mib_table[] = {
// ---------- System MIB ----------- 
  // SysDescr Entry
  { NET_SNMP_MIB_OCTET_STR | NET_SNMP_MIB_ATR_RO,
    8, {NET_SNMP_MIB_OID0(1,3), 6, 1, 2, 1, 1, 1, 0},
    NET_SNMP_MIB_STR("Embedded System SNMP V1.0"),
    NULL },
  // SysObjectID Entry
  { NET_SNMP_MIB_OBJECT_ID | NET_SNMP_MIB_ATR_RO,
    8, {NET_SNMP_MIB_OID0(1,3), 6, 1, 2, 1, 1, 2, 0},
    NET_SNMP_MIB_STR("\x2b\x06\x01\x02\x01\x01\x02\x00"),
    NULL },
  // SysUpTime Entry
  { NET_SNMP_MIB_TIME_TICKS | NET_SNMP_MIB_ATR_RO,
    8, {NET_SNMP_MIB_OID0(1,3), 6, 1, 2, 1, 1, 3, 0},
    4, &snmp_SysUpTime,
    NULL },
    ..
}

In the following example, we will construct a MIB variable entry LedOut. It will allow the SNMP Manager to control LEDs on an evaluation board.

The MIB variable type is Integer. An uint8_t variable is sufficient, because the LED port is 8-bit:

// LedOut Entry
{ NET_SNMP_MIB_INTEGER,

The OID reference is 1.3.6.1.3.1.0. It is defined in the Experimental MIB branch of the MIB tree:

6, {NET_SNMP_MIB_OID0(1,3), 6, 1, 3, 1, 0},

• the first byte defines the length of the OID name,
• macro NET_SNMP_MIB_OID0 calculates the first byte of OID value from 1st and 2nd address byte,
• the value of an OID address byte must be less than 128, otherwise an extended encoding must be used.

The variable size and location is described with the help of NET_SNMP_MIB_INT macro:

NET_SNMP_MIB_INT(LedOut),

The following macros are defined:

Macro	Variable Definition
NET_SNMP_MIB_STR	Octet or Byte String size and location.
NET_SNMP_MIB_INT	Signed or Unsigned Integer size and location.
NET_SNMP_MIB_IP	IP Address size and location.

The write_leds is specified as callback function. It gets called when the LedOut is written:

write_leds },

Finally we need the actual variable definition:

static uint8_t LedOut;

For the LedOut control we actually need the following parts of code to be defined in SNMP_Agent_MIB.c module:

static uint8_t LedOut;
static void write_leds (int32_t mode);
 
const NET_SNMP_MIB_INFO snmp_mib[] = {
    ..
  // LedOut Entry
  { NET_SNMP_MIB_INTEGER,
    6, {NET_SNMP_MIB_OID0(1,3), 6, 1, 3, 1, 0},
    NET_SNMP_MIB_INT(LedOut),
    write_leds },
    ..
}
 
static void write_leds (int32_t mode) {
  // No action on read access.
  if (mode == NET_SNMP_MIB_WRITE) {
    LED_SetOut (LedOut);
  }
}

String Handling

Two types of read/write strings are supported:

Type	Description
OCTET_STRING	An 0-terminating ascii string.
BYTE_STRING	Length-encoded binary string.

The OCTET_STRING is treated as an 0-terminating ascii string, the last character in the string is a zero character. When the ascii string is written in the SET request, a 0-termination is added. The position of the zero character specifies the length of the data encoded in the GET response.

static char ascii_str[20];
    ..
  strcpy (ascii_str, "embedded");
    ..
 
const NET_SNMP_MIB_INFO snmp_mib[] = {
    ..
  // Ascii String Entry
  { NET_SNMP_MIB_OCTET_STR,
    6, {NET_SNMP_MIB_OID0(1,3), 6, 1, 3, 2, 0},
    NET_SNMP_MIB_STR(ascii_str),
    NULL },
    ..
}

The BYTE_STRING is treated as a length-encoded binary string. The first byte in the string is the length of the string. The contents of the string are stored from the second byte onwards. When the byte string is written in the SET request, the len is updated. The len specifies the length of the data encoded in the GET response.

static uint8_t byte_str[20];
    ..
  NET_SNMP_BYTE_STR *bp = (NET_SNMP_BYTE_STR *)&byte_str;
  bp->len = 4;
  bp->data[0] = 0;
  bp->data[1] = 2;
  bp->data[2] = 0;
  bp->data[3] = 0;
    ..
 
const NET_SNMP_MIB_INFO snmp_mib[] = {
    ..
  // Byte String Entry
  { NET_SNMP_MIB_BYTE_STR,
    6, {NET_SNMP_MIB_OID0(1,3), 6, 1, 3, 3, 0},
    NET_SNMP_MIB_STR(byte_str),
    NULL },
    ..
}

Extended OID Encoding

The value of OID address byte must be less than 128. If it is not, an OID address must be encoded in extended format. This is because the high bit of an address byte is an address extension bit.

For example, the OID address 1.3.6.1.4.1.311.0 is encoded as:

8, {NET_SNMP_MIB_OID0(1,3), 6, 1, 4, 1, 130, 55, 0},

The address value for the highlighted numbers is calculated as:

(130-128) * 128 + 55 = 311

The OID address 1.3.6.1.4.1.31036.50.1.1.0 is encoded as:

12, {NET_SNMP_MIB_OID0(1,3), 6, 1, 4, 1, 129, 242, 60, 50, 1, 1, 0},

where the value 31036 is calculated as:

(129-128) * 128 * 128 + (242-128) * 128 + 60 = 31036