Implementing Multiple Instances of a Module

For some types of modules, multiple instances of the module can be run simultaneously on a single host. For example, consider a module that monitors the status of a single printer. For a system with several printers, the printer-monitoring module must be loaded multiple times, once for each printer. In that scenario, several separate instances of the printer module must be running simultaneously. For such modules, you must distinguish the different instances that are loaded and running.

SNMPv2 introduced the concept of contexts to identify MIB modules that can have multiple instances. Each SNMP context is represented by a separate MIB subtree.

In SMA, you can implement multiple instances of a module only when the agent is configured to use SNMPv3. You need to specify an SNMPv3 user and password when loading and unloading modules. You specify an instance name by assigning a string to the contextName member of the netsnmp_handler_registration struct in the module.

The following procedure tells you how to implement multiple-instance modules. The procedure uses examples from demo_module_6, which you can adapt to your own module.

How To Implement Multiple Instance Modules

1. As root, stop the agent if the agent is already running.

   # svcadm disable -t svc:/application/management/sma:default

2. Set up an SNMPv3 user.

   For example, set up user name myuser with password mypassword as follows:

   # $ /usr/sfw/bin/net-snmp-config --create-snmpv3-user myuser Enter authentication pass-phrase: mypassword Enter encryption pass-phrase: [press return to reuse the authentication pass-phrase]

3. Edit the module to register context names that the module handles.

   Find the init_module routine in the module. Add code to register context names that the module handles.

   For example, you might add the following code:

   void 
   init_filesize(void) 
   { 
   // Declare the OID
   static oid filesize_oid[] = { 1,3,6,1,4,1,42,2,2,4,4,6,1,1,0 };
   
   
   // Declare a registration handler
   netsnmp_handler_registration *myreg1; 
   
   // Declare pointers to character arrays initialized
   // to the context name strings
   char *filexcon = "fileX"; 
   char *fileycon = "fileY"; 
   
   // Create a registration handler for the OID. 
   // filesize is the name of handler.
   // get_filesize is the function to call when an SNMP 
   // request for the OID is received, filesize_oid is the 
   // OID for which the handler is registered,
   // OID_LENGTH(filesize_oid) passes the length of the 
   // OID array to the agent.
   // HANDLER_CAN_RONLY is a constant that specifies that 
   // this handler only handles get requests.
   myreg1 = netsnmp_create_handler_registration 
   ("filesize", get_filesize, 
                filesize_oid, OID_LENGTH(filesize_oid), 
                HANDLER_CAN_RONLY);
                         
   // Assign the string fileX to the contextName member of the 
   // netsnmp_handler_registration struct
   myreg1->contextName=filexcon; 
   
   // Register the netsnmp_handler_registration struct with the
   // agent.  netsnmp_register_read_only is a helper function
   // that notifies the agent that this module only handles snmp 
   // get requests. 
   netsnmp_register_read_only_instance(myreg1);
   }
    

demo_module_6 Code Example for Multiple Instance Modules

The demo_module_6 code is located by default in /usr/demo/sma_snmp/demo_module_6. The README_demo_module_6 file within that directory contains instructions that describe how to perform the following tasks:

• Compile source files to generate a shared library object that implements a module

• Set up the agent with an SNMPv3 user

• Set up the agent to dynamically load the module

• Test the module with snmp commands to show that the module is functioning as expected

The demo_module_6 example shows how to write a module that registers an object in two different contexts. The example also shows how to check for the contextName in a request and return a different value depending on the value of the contextName.

demo_module_6 registers one object, filesize, in two different contexts, fileX, and fileY. The OIDs are registered by using a read-only instance handler helper. The OIDs do not need to be read-only. You could also register the OIDs using any of the SMA instance handler helper APIs.

The function get_filesize() is registered to handle GET requests for instances of the filesize object. The get_filesize() function checks the contextName in the reginfo structure that is passed to the function by the SMA. If the value of contextName is fileX, the function returns fileX_data, which has been set to the integer 111. If the value of contextName is fileY, the function returns fileY_data, which has been set to the integer 999.