SNMP Development Kit

Version 1.0

 

1. Introduction

2. Browsers

3. Basic Operations

4. Development Procedures

5. Library Reference

 

 

1. Introduction

 

The SNMP development kit needs a special license installed. It consists of:

 

snmplib.a

SNMP library for V1, V2c and V3

snmpd.c

sample SNMP agent

snmpio.c

sample conversion module between serial IO interface and SNMP request / response.

demo.mib

sample MIB

 

Simple Network Management Protocol (SNMP), in practical, is not really "simple". On contrary, it may be one of the most complicated network applications. To implement a full featured SNMP agent, take for example, the net-snmp project, takes more than 300,000 lines of C source codes.

 

To make life easier, our SNMP development kit supports only a subset of full-featured SNMP by limiting  the variable size and the dimension of table objects. With this modeling, a SNMP agent can be easily implemented with only 8 library functions which will greatly free the loading of software developers.

 

If you are new to SNMP, lots of readings should be digested first. The following links may be useful for you as a starting point:

 

Wikipedia - SNMP

 

Official documents can also be found online:

 

*         RFC 1155 — Structure and Identification of Management Information for the TCP/IP-based Internets

*         RFC 1156 — Management Information Base for Network Management of TCP/IP-based internets

*         RFC 1157 — A Simple Network Management Protocol (SNMP)

*         RFC 1441 — Introduction to version 2 of the Internet-standard Network Management Framework

*         RFC 1213 — Management Information Base for Network Management of TCP/IP-based internets: MIB-II

*         RFC 3410 (Informational) — Introduction and Applicability Statements for Internet Standard Management Framework

*         RFC 3411 (Standard 62) — An Architecture for Describing Simple Network Management Protocol (SNMP) Management Frameworks

*         RFC 3412 (Standard 62) — Message Processing and Dispatching for the Simple Network Management Protocol (SNMP)

*         RFC 3413 (Standard 62) — Simple Network Management Protocol (SNMP) Application

*         RFC 3415 (Standard 62) — View-based Access Control Model (VACM) for the Simple Network Management Protocol (SNMP)

*         RFC 3416 (Standard 62) — Version 2 of the Protocol Operations for the Simple Network Management Protocol (SNMP)

*         RFC 3417 (Standard 62) — Transport Mappings for the Simple Network Management Protocol (SNMP)

*         RFC 3418 (Standard 62) — Management Information Base (MIB) for the Simple Network Management Protocol (SNMP)

 

 

2. SNMP Browser

 

To build a SNMP-ready product, the first thing you need is a SNMP browser which is usually not included in operating systems like Windows or Linux. The following browsers have been tested by us:

 

SnmpB

 

This browser is a freeware under GPL license, and can be downloaded from http://sourceforge.net/projects/snmpb/.

 

Being in pre-alpha stage, the current release V0.5 has limited functions. One of the major problems of it is that it does not support the SNMP SET command. That is, all entries in the MIBs are read-only, because there's no way to change them with SnmpB.

 

To load our sample MIB into SnmpB:

*         rename 'demo.mib' to DEMO-MIB

*         copy DEMO-MIB to 'mibs' sub directory of SnmpB (C:\Program Files\SnmpB\mibs)

*         load it from SnmpB

 

 

MG-SOFT MIB Browser

 

MG-SOFT's MIB browser, compiler and builder, in professional quality, provide all the functions needed in the SNMP world. A 30-day evaluation version can be downloaded from http://www.mg-soft.com/mgMibBrowserPE.html.

 

 

 

To load our sample MIB into browser:

*         compile 'demo.mib' to 'demo.smidb'

*         load it from browser

 

 

3. Basic Operations

 

Walk: Walk through entire MIB by GetNext or GetBulk.

 

 

Get: Get value of current MIB entry.

 

 

Get Next: Get value of next MIB entry.

 

 

Get Bulk: Get values of next 10 MIB entries.

 

 

Set: Set value of current MIB entry.

 

 

Table View: Get all values in current table.

 

 

Trap Console: Display traps received.

 

 

 

4. Development Procedures

 

Define MIBs

 

The SNMP MIB Data Definition Language has complicated syntax rules. Instead of writing MIB from scratch, it is better to modify it from existing MIBs.

 

DEMO-MIB DEFINITIONS ::= BEGIN

 

IMPORTS

     MODULE-IDENTITY,OBJECT-TYPE,Gauge32,mib-2,

     NOTIFICATION-TYPE,Integer32,TimeTicks,

     Counter32, enterprises

         FROM SNMPv2-SMI

     DisplayString

         FROM SNMPv2-TC;

 

myCompany MODULE-IDENTITY

      LAST-UPDATED "200805070000Z"

      ORGANIZATION "metavert"

      CONTACT-INFO

           "demo"

      DESCRIPTION

           "demo"

      REVISION    "200805070000Z"

      DESCRIPTION

          "demo"

      ::= {enterprises 123456 }

 

myProduct   OBJECT IDENTIFIER ::= { myCompany 1 }

 

Or, use tools, for example, MG-SOFT MIB-Builder:

 

 

 

Initialize SNMP Agent Settings

 

// Initialize settings

// Documentary information

SnmpInit("sysDescr",    "My System");

SnmpInit("sysContact",  "My Contact");

SnmpInit("sysName",     "My Name");

SnmpInit("sysLocation", "My Location");

SnmpInit("sysServices", "6");

// Community strings (act as simple passwords)

SnmpInit("getCommunity", "public");

SnmpInit("setCommunity", "private");

..

..

 

Define MIB Entries and Handling Functions

 

// MIB entries

//   The following entries should be arranged in ascending order

//   of OIDs.

// myStatus MIB entries (simple object, read-only)

SnmpMib(myMIB,"1.1",myString,0,0);         // string type demo

SnmpMib(myMIB,"1.2",myInteger,0,0);        // integer type demo

SnmpMib(myMIB,"1.3",myInteger32,0,0);      // integer32 type demo

SnmpMib(myMIB,"1.4",myGauge32,0,0);        // gauge32 type demo

SnmpMib(myMIB,"1.5",myCounter,0,0);        // counter type demo

SnmpMib(myMIB,"1.6",myTimeTicks,0,0);      // timeticks type demo..

..

 

Run SnmpAgent()

 

// Run SNMP agent service

SnmpAgent();

 

 

5. Library Reference

 

 

5.1 Initialization:

 

void SnmpInit(const char *sName, const char *sVal);

 

Documentary strings (iso.org.dod.internet.mgmt.mib-2.system)

sysDescr

A textual description of the entity.

sysContact

The textual identification of the contact person for this managed node

sysName

An administratively-assigned name for this managed node.

sysLocation

The physical location of this node (e.g., `telephone closet, 3rd floor').

sysServices

A value which indicates the set of services that  this entity primarily offers. Normally = 6

 

System settings

getCommunity

Community string for get command. Normally = 'public'

setCommunity

Community string for set command. Normally = 'private'

SnmpVersion1

"1" accept. "0" reject

SnmpVersion2

"1" accept. "0" reject

sysObjectID

User's MIB root

PacketFilter

User's packet filter routine

 

 

5.2 OID (OBJECT IDENTIFIER) and Instance

 

The OID of SNMP object consists of up to 128 digits. Each digit can be 1 to the maximum value of an unsigned 32 bit integer. Zero (0) is reserved for indicating an instance. Most user developed MIB will be put under iso(1).org(3).dod(6).internet(1).private(4).enterprises(1), or simply "1.3.6.1.4.1".

 

An instance is the unique representation of the object:

 

Object Type

Instance

Example

Simple Object

OID.0

1.3.6.1.4.1.123456.1.0

Table Object

OID.(index)

1.3.6.1.4.1.123456.2.1

1.3.6.1.4.1.123456.2.2

1.3.6.1.4.1.123456.2.3

…

 

 

5.3 MIB Definition

 

void SnmpMib(const char *sRoot, const char *sOid, MIB_SUB Func, int Flag, int Arg);

 

sRoot

User's MIB root. e.g. "1.3.6.1.4.1.123456.1"

sOid

OID of this entry. e.g. "1.1"

Func

Handling routine for this entry

Flag

SN_RW - allow write operation

Arg

Extra argument. Normally used in table object.

 

To specify a table object, the OID must end with a letter 'T':

 

1.1.1

Simple object

1.2.T

Table object

 

 

5.4 User MIB Handling Function

 

When the SNMP engine receive a command from remote host for a specific MIB entry, it calls the handling function provided by user with a pointer pointing to SNMP_REQ data structure.

 

/* ------------------------------------------------------------------

   String type demo

   ------------------------------------------------------------------*/

int myString(SNMP_REQ *p)

{   static char Str[32]="My Product";

 

    // data written from SNMP

    if(p->Code==SN_WRITE)

    {  // check data type and size

       if(p->valType!=SN_STR || p->valSize>=31)

       {   SnmpError(SN_ERR_VALUE);

           return false;

       }

       // save the value

       strcpy(Str,p->valData);

    }

    // response to read or write request from SNMP

    SnmpOutVar(SN_STR,Str,strlen(Str));

 

    return true;

}

 

typedef struct

{  int  Code;           // operation code

   int  Arg;            // optional argument

   int  Indx;           // index for table object

   int  valType;        // variable type

   int  valSize;        // variable size in bytes

   char valData[128];   // variable data

} SNMP_REQ;

 

Code

SNMP operation code

SN_WRITE = write command

SN_READ = read command

SN_FIND = find instance in table

SN_NEXT = next instance in table

Arg

The argument specified in SnmpMIB () function

for table operation

Indx

32 bit integer index

instance of table object

valType

data type (write command)

 

SN_INT = integer,

SN_STR = string

SN_COUNTER = counter

SN_GAUGE = gauge

SN_TIMETICK = timeticks

valSize

data size (write command)

1 - 256

valData

data (write command)

1 - 256 bytes

 

 

5.5 Trap Generation

 

void SnmpTrap(SNMP_TRAP *p);

 

To generate a SNMP trap is simple. Just fill the 4 arguments required and pass them to SnmpTrap() function.

 

// SNMP Trap

typedef struct

{  char *DestAddr;      // host address (e.g. "192.168.1.8")

   char *TrapObject;     // Trap OID (e.g. "1.3.6.1.4.1.123456.1.3.1.3")

   char *Community;    // community (e.g. "public")

   char *Message;      // message to be sent (e.g. "Channel 13 Overvoltage !")

} SNMP_TRAP;

 

The SNMP engine generates V2 traps if the parameter 'SnmpVersion2' is set to '1', otherwise, it generates V1 traps.

 

 

5.6 Error Reporting

 

void SnmpError(int Code);

 

The following constants are defined in RFC 1157. To maintain the compatibility to SNMP V1, only 1 to 5 are used.

   

SN_ERR_BIG=1

Too big

SN_ERR_NAME=2

No such name

SN_ERR_VALUE=3

Bad value

SN_ERR_RO=4

Read only

SN_ERR_GEN=5

Generic error

 

 

5.7 System Management

 

int SnmpAgent(void);

Start SNMP agent service

void SnmpClose();

Stop SNMP agent service

 

 

5.8 Input / Out Functions

 

void SnmpOutVar

(int nType, void *pData, int dSize);

Output the variable in response.

 

nType specifies the data type:

SN_INT = integer,

SN_STR = string

SN_COUNTER = counter

SN_GAUGE = gauge

SN_TIMETICK = timeticks

pData - pointer to variable

dSize - data size

int SnmpGetInt

(SNMP_REQ *p);

Decode integer data from SNMP write command. Can be used for:

SN_INT = integer,

SN_COUNTER = counter

SN_GAUGE = gauge

SN_TIMETICK = timeticks