SNMP Tools and APIs in Net+OS V5+

1. SNMP Tools and APIs in Net+OS V5+ SNMP Overview SNMP Tools SMICng Compiler MIBMAN Code Generator SNMP Agent and SNMP Extensions

2. Supported RFCs SNMP V1 & V2 RFC 1155, 1157, 1212, and 1213 RFC 1901-1906

3. SNMP Basic Management Content from http://bbcr.uwaterloo.ca/~rboutaba/cs756M/Lecture-5.pdf

4. SNMP Formats

5. Relevant Aside: What’s an Object ID (OID)? • A series of numbers, separated by periods, representing an object or object classification. • A hierarchy of increasing detail from left to right. • Example from the Internet (1.3.6.1): • 1 iso • 1.3 org • 1.3.6 dod (US Defense Dept – origin of the Internet) • 1.3.6.1 internet • 1.3.6.1.1 directory • 1.3.6.1.2 mgmt • 1.3.6.1.2.1 mib-2 • … and lots more (see RFC 1700)

6. SNMPv2 Decentralized Management

7. SNMP Tools

8. What do these tools do? • Help customers implement MIBs. • Makes MIB objects visible to MIB browsers. • Ties MIB objects into Management Database • Makes MIB objects available to the Web Server.

9. What is a MIB? • Management Information Base. • Describes objects (variables) visible to MIB browsers. • Users can read and sometimes write to them. • Objects usually report current status of the device and can be used to control it. • Recommended Reference: “Understanding SNMP MIBs” by David Perkins.

10. MIB Implementation SMICng Compiler Create MIBs Start Edit C Source Code for special Functions & Tables MIBMAN Code Generator Regular Build Process Build Application End

11. NAMIB Example Application • Example application that demonstrates how to create a new MIB with the tools. • Demonstrates how to use SMICng and MIBMAN. • Demonstrates how to implement MIB tables. • Demonstrates how to implement special features. • Step by step guide in manual and readme file.

12. Use SMI version 2 • The SMI defines the data types used in a MIB. • In SMIv1, data types were defined in MIMs that also defined objects. This caused problems if another MIB tried to use those data types. • SMIv2 is the corrected version. • SMIv2 defines data types in separate files in RFCs 1902, 1903, and 1904.

13. SMICng • Performs extensive syntax checking of MIBs. • Converts them into intermediate code. • Binaries are in NETOSx\bin. • Online manual and working sample MIBs in NETOSx\snmpinfo.

14. SMICng Authentication Key • SMICng requires an authentication key. • Obtain from License_admin@netsilicon.com . • You must set the environment variable SMICAUTH to the key value. • Key is valid for duration of the support contract.

15. Standard MIBs • Many MIBs use elements from standard MIBs defined in RFCs. • You must import these MIBs into your own. • Standard MIBs and their include files are available in NETOSx\smicng\mibs.

16. SMICng Include Files • You must create an include file for each MIB you compile with SMICng. • Lists all the MIBs that are imported in the one to be compiled. • Also sets syntax checking options. • Use example in NETOSx\smicng\mibs as starting point.

17. Example Include File #condInclude “rfc1902.inc” #condInclude “rfc1903.inc” #condInclude “rfc1904.inc” #pushOpt #removeOpt “C W 7 R S B” #addOpt “I” #condInclude “example.mib” #popOpt

18. Running SMICng • Set environment variable SMICINCL to MIB directory. • Command line: smicng –z myMib.inc > myMib.out • -z = create intermediate file • myMib.inc = name of MIB include file • myMib.out = name of intermediate file

19. SMICng and Syntax • SMICng performs an extensive syntax check of the MIB. • Will report errors that other MIB compilers miss, however… • these are real errors that should be corrected.

20. Next Step: MIBMAN • SMICng creates the Intermediate files. • MIBMAN converts the intermediate files into C source and header files. • Creates code to register MIB with management API. • Creates template code for tables and special objects.

21. MIBMAN is a Java 2 Application! • You must install Java 2. • Download for free and install J2SE or J2EE from http://java.sun.com/.

22. MIBMAN Configuration Files • Must create one if MIB contains tables. • Used to specify table index information. • May create one to set up special objects, set special variable names and other options. • Configuration files effect code generation for a particular MIB.

23. Format of Configuration File Options • All options are one line long and take one of the following two forms: • Keyword value • Keyword OID = value • Example: Cfilename mib.c

24. Files Generated by MIBMAN • The “C File” contains the data structures used to define the MIB objects as management variables and register them with the SNMP agent. • The “H File” contains declarations for the data structures in the C File. • The “Action File” contains template code that implements action routines for SNMP tables and for special SNMP scalar objects. • Mibman.c contains the code to start everything.

25. Configuration File Options: Setting Filenames • Set name of generated Cfile with: Cfilename <filename> • Set name of generated H file with: Hfilename <filename> • Sets name of generated action file with: ActionFilename <filename>

26. Configuration File Options: Setting Comments in Files • Set Author name with: Author <name> • Set name of module with: ModuleName <name> • Set description text with: Description <text> • Set Edit Information with: Edit <edit id>=<edit text>

27. Configuration File Options: Controlling Management Variable creation • You might not want to create management variables for some MIB objects. • For example the agent may need to synthesize the variable “isApplicationXHealthy” when it is read. • Prevent a variable from being created with: DontCreateVariable <oid>

28. Configuration File Options: Setting Variable Identifiers • All management variables have a unique identifier. • By default, SNMP objects use the OID, but this can be overridden with: SetVariableIdentifier <oid>=<name>

29. Configuration File Options: Setting Index Information • You must provide an Index function for SNMP tables. • Specify the Index function with: SetIndexFunction <OID> = <function> • Optionally specify data passed to function with: SetIndexInfo <OID>=<info>

30. Configuration File Options: Protecting Variables With Semaphores • Management variables can be protected with semaphores. User must create the semaphores and specify which ones are used to protect each variable. • Protect all variables in a MIB with: SetGlobalSemaphore <semaphore> • Protect a specific variable with: SetSemaphore <OID> = <semaphore>

31. Configuration File Options: Forcing Generation of Action Functions • Normally Scalar Objects don’t need action functions, but you can force MIBMAN to create them if desired. • Generate a read action function with: GenerateReadActionFunction <OID> • Generate a write action function with: GenerateWriteActionFunction <OID>

32. What are Action Routines? • Action routines are called by the SNMP agent to do the actual reads and writes to SNMP objects. • Reads and Writes to standard scalar objects are handled by internal action routines. • Reads and Writes to special scalar objects and columnar objects are handled by action routines that MIBMAN generates and that developers must complete.

33. Configuration File Options: Setting Accessor Functions • Sometimes MIB objects will reflect the state of hardware or external devices. In this case, it may be desirable to use accessor functions to represent the variables. • Specify an accessor function with: AccessorFunction <OID>=<function name>

34. Configuration File Options: Setting Include files • Include files can be used to declare accessor functions, index functions, and semaphores. • Specify an include file with: Include <filename>

35. Example MIBMAN Config File GenerateWriteActionRoutine 1.3.6.1.4.1.901.999.1.1.1 GenerateWriteActionRoutine 1.3.6.1.4.1.901.999.1.1.2 SetIndexFunction 1.3.6.1.4.1.901.999.1.2.1 = tableIndexFn Include table.h

36. Running MIBMAN • Create a list file that lists all the MIBs to process. • Command: java –jar mibman.jar listfile configDir • listfile = name of list file • configDir = directory with configuration files

37. MIBMAN Output • Generates C source and header files for MIB. • Normal scalar objects are completely implemented. • Template action routines are generated for special scalar objects identified in configuration file. • Template action routines are also generated for columnar objects in tables.

38. Relationship to API’s MIBMAN- Generated code uses SNMP Agent Extensions (Chapter 7) Advanced Web Server API (Chapter 2) uses Management API (Chapter 15)

39. Special Scalar Objects • Some scalar objects require special processing. • For example an object might represent the state of an LED. In this case, you would write the code that actually turns the LED on and off.

40. Scalar Action Routine • Developer sets options in configuration file to make MIBMAN generate template functions. • Template handles reading and writing the variable in the database. • Developer must add code to perform special functions. • NAMIB demonstrates how to do this for LEDs.

41. Example Template Action Routine int greenLedOnWrite (int actionCode, struct varBind *info) { int result = SNMP_ERR_NOERROR; if (actionCode == SNMP_SET_ACTION) { result = snmpWriteObject(info->vp, &info->setTo, info->setToLen); } else if (actionCode == SNMP_SET_UNDO) { result = snmpWriteObject(info->vp, &info->val, info->valLen); } return result; }

42. Finished Action Routine int greenLedOnWrite (int actionCode, struct varBind *info) { int result = SNMP_ERR_NOERROR; int ledOn; if (actionCode == SNMP_SET_ACTION) { result = snmpWriteObject(info->vp, &info->setTo, info->setToLen); ledOn = info->setTo.intVal; } else if (actionCode == SNMP_SET_UNDO) { result = snmpWriteObject(info->vp, &info->val, info->valLen); ledOn = info->val.intVal; }

43. Finished Action Routine continued if ( (result == SNMP_ERR_NOERROR) && ((actionCode == SNMP_SET_ACTION) || (actionCode == SNMP_SET_UNDO))) { if (ledOn == 1) /* if turning LED on*/ { NALedGreenOn(); } else { NALedGreenOff(); } } return result; }

44. Tables and Columnar Objects • Columnar objects are just objects in tables. • Unlike scalar objects, columnar objects can have many instances. • Columnar objects are grouped together in rows. • A table consists of rows of columnar objects. • Similar to a one dimensional array of C structures.

45. How are Tables Represented? • MIBMAN represents tables as linked lists of C structures. • Each field in the structure represents one columnar object. • Each list element represents one row in the table.

46. Table Indexes • Rows are identified by index values. • Indexes can be simple or complex. • SNMP allows database search key like indexes. • Recommended : keep table indexes simple. • Developer writes the code that implements the index algorithm.

47. Index Functions • When a console reads a columnar object, it passes index values for that row in the table. • The MIBMAN template code extracts the index values. • Developers must write a function that takes these index values and compares them against a row in a table. • Function returns a value that indicates if row comes before, at, or after the index. • Index function for table must be specified in MIBMAN configuration file.

48. Example of Simple Index Scheme int tableIndexFn (void *index, void *row, void *indexInfo) { simpleTableType *tableRow = (simpleTableType *) row; int *indexValue = (int *) index; return (tableRow->index - *indexValue); }

49. Table Read Functions • One read function is shared by every object in the table. • Template code does almost everything. • Customer has to implement code that handles the index information. • Sections that customer needs to change are marked with “To Do” comments. • Example in NAMIB.

50. Table Read Action Code Example snmpIndexType *snmpIndex = snmpExtractIndices(vp, name, *length, IS_READ, 13); … … … /* * The raw SNMP indices are stored in snmpIndex. The * algorithm for using these indices should be described * somewhere in the MIB's RFC. * * To Do: Write code to initialize manIndex. For a GET * manIndex must be the exact index of the row to * read. It must be one past it for a GET-NEXT. */