SNMP Agent

Simple Network Management Protocol (SNMP) is mainly used in network management systems to monitor network-attached devices for conditions that warrant administrative attention. It is the most popular network management protocol in the TCP/IP protocol suite.

SNMP is a simple request/response protocol that communicates management information between two types of SNMP software entities: SNMP managers and SNMP agents. The following picture shows an exemplary setup:

In summary, SNMP performs the following operations:

• The GET operation receives a specific value about a managed object, such as the available hard disk space from the agent's MIB.
• The GET-NEXT operation returns the "next" value by traversing the MIB tree of managed object variables.
• The SET operation changes the value of a managed object's variable. Only variables whose object definition allows read/write access can be changed.
• The Trap operation sends a message to the Management Station when a change occurs in a managed object, and that change is important enough to send an alert message.

The SNMP Agent validates each request from a SNMP manager before responding to the request, by verifying that the manager belongs to a SNMP community with access privileges to the agent. A SNMP community is a logical relationship between a SNMP agent and one or more SNMP managers. The community has a name, and all members of a community have the same access privileges: either read-only or read-write.

The SNMP Agent in the Network Component is an optimized and compact implementation for embedded systems. Check: Currently it implements SNMP version 1.

The following functions are included in the Network Component library rl_net.h:

• snmp_trap - send a trap to the manager.
• snmp_set_community - change SNMP community to a new community.

MIB Database

The data base controlled by the SNMP Agent is referred to as the SNMP 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.

MIB Interface

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 Net Item to Group, then click on User Code Template and scroll in the template files list until you find the SNMP Agent template (you will find a listing here). 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 snmp_mib describes the MIB variable. The SNMP Agent uses this description to process local MIB variables. This structure is defined as follows:

typedef struct snmp_mib {
  uint8_t  Type;                        // Object Type
  uint8_t  OidLen;                      // Object ID length
  uint8_t  Oid[MIB_OID_SIZE];           // Object ID value
  uint8_t  ValSz;                       // Size of a variable
  void     *Val;                        // Pointer to a variable
  void     (*cb_func)(int mode);        // Write/Read event callback function
} const SNMP_MIB;

The components of MIB_ENTRY structure are:

• the Type defines the MIB variable type:

  MIB Type	Description	Size
  MIB_INTEGER	Signed Integer	1, 2 or 4 bytes
  MIB_OCTET_STR	Octet String entry	max. 110 characters
  MIB_OBJECT_ID	Object Identifier entry	max. 17 bytes
  MIB_IP_ADDR	IP Address entry	4 bytes
  MIB_COUNTER	Counter entry	1, 2 or 4 bytes
  MIB_GAUGE	Gauge entry	1, 2 or 4 bytes
  MIB_TIME_TICKS	Time Ticks entry	4 bytes

  The Type component may be OR-ed with the 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:
  • OidLen specifies the length of the Oid[] array.
  • Oid[MIB_OID_SIZE] array specifies the OID name - a length encoded binary array.
• Val specifies the Pointer to the variable and its Size:
  • ValSz specifies the size of Val variable.
  • Val 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
  MIB_READ	Reads a MIB variable.
  MIB_WRITE	Writes to a MIB variable.

MIB Table

The snmp_table table is defined as an array. The components of this array are of type snmp_mib.

const snmp_mib snmp_mib[] = {
  // ---------- System MIB -----------
  // SysDescr Entry
  { MIB_OCTET_STR | MIB_ATR_RO,
    8, {MIB_OID0(1,3), 6, 1, 2, 1, 1, 1, 0},
    MIB_STR("Embedded System SNMP V1.0"),
    NULL },
  // SysObjectID Entry
  { MIB_OBJECT_ID | MIB_ATR_RO,
    8, {MIB_OID0(1,3), 6, 1, 2, 1, 1, 2, 0},
    MIB_STR("\x2b\x06\x01\x02\x01\x01\x02\x00"),
    NULL },
  // SysUpTime Entry
  { MIB_TIME_TICKS | MIB_ATR_RO,
    8, {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
{ 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, {MIB_OID0(1,3), 6, 1, 3, 1, 0},

• the first byte defines the length of the OID name,
• macro 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 MIB_INT macro:

MIB_INT(LedOut),

The following macros are defined:

Macro	Variable Definition
MIB_STR	Octet String size and location.
MIB_INT	Signed or Unsigned Integer size and location.
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_MIB.c module:

static uint8_t LedOut;
static void write_leds (int mode);

const snmp_mib snmp_mib[] = {
    ..
  // LedOut Entry
  { MIB_INTEGER,
    6, {MIB_OID0(1,3), 6, 1, 3, 1, 0},
    MIB_INT(LedOut),
    write_leds },
    ..
}

static void write_leds (int mode) {
  // No action on read access.
  if (mode == MIB_WRITE) {
    LED_out (LedOut);
  }
}

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, {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, {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

SNMP Agent Configuration

SNMP Agent Configuration File

The SNMP agent configuration file Net_Config_SNMP_Agent.h contains the following settings:

• Community Name specifies the SNMP Community where an SNMP message is destined for. Only the members of the same community can communicate with each other using SNMP protocol. Default Community name is public.
• Port Number specifies the listening UDP port number. The default SNMP Agent listening port is 161.
• Trap Port Number specifies the UDP port number for Trap operations. The default SNMP Agent trap port is 162.
• Trap Server specifies the IP address of the Trap Server which receives Trap messages. This IP address is used when the Trap Server IP is not specified in snmp_trap() function parameter.