Solaris System Management Agent Developer's Guide

Chapter 10 Migration of Solstice Enterprise Agents to the System Management Agent

This chapter contains information for developers who want to migrate a subagent from Solstice Enterprise Agents to use in the System Management Agent. The chapter uses demo_module_12 to illustrate procedures. The following topics are discussed:

Why Migrate to SMA?

Support for the Solstice Enterprise Agents software might be discontinued in a future Solaris release. For this reason, any Solstice Enterprise Agents subagents that you have created must be migrated to use the SMA. In this Solaris release, you can run the Solstice Enterprise Agents software and associated subagents concurrently with the SMA.

The Solstice Enterprise Agents product includes mibiisa, a subagent that implements MIB-II and the Sun MIB. In SMA, the functionality of mibiisa is implemented by the MIB-II portion of the SMA agent and a new Sun extensions subagent. By default, the mibiisa subagent is disabled in this Solaris release.

Requests for MIB-II are handled by the SMA agent directly. Requests for the extensions in the Sun MIB are handled by the seaExtensions module, if that module has been loaded. Requests for the Solstice Enterprise Agents master agent, which implements the snmpdx.mib, are handled by the seaProxy module if that module has been loaded.

The seaProxy module generates dynamic proxies based on static and dynamic Solstice Enterprise Agents subagent registrations. The proxies are not statically defined in snmpd.conf. Note that the seaProxy module does not generate proxies for the mibiisa subagent itself. After the dynamic proxies are generated, the agent's proxy mechanism handles the forwarding of those requests to the Solstice Enterprise Agents master agent.

Solstice Enterprise Agents subagents can still be used with the Solstice Enterprise Agents master agent, and thus with SMA by using the seaProxy module, as explained in Solaris System Management Agent Administration Guide. However, SMA support of the Solstice Enterprise Agents software is for a limited transitional time. You should migrate any Solstice Enterprise Agents subagents that you have implemented to use the SMA as early as possible.

Solstice Enterprise Agents Migration Strategy Overview

The general process for implementing a Solstice Enterprise Agents subagent as an SMA module is as follows:

Obtain the MIB that was used to create the Solstice Enterprise Agents subagent.
Make a copy of the MIB. Name the MIB file according to the guidelines in MIB File Names, if necessary.

Modify the copy of the MIB for compatibility with mib2c. Use the SUN-SEA-EXTENSIONS-MIB.txt as a model for modifying the MIB. Pay particular attention to the format of the MODULE-IDENTITY group.
Use the mib2c tool to generate C code for SMA module templates from the modified MIB.
Use the Solstice Enterprise Agents mibcodegen tool to generate C code header and stub files for Solstice Enterprise Agents modules from the original MIB.
Compare the template code that mib2c produced to the template code that mibcodegen produced. Examine the instrumentation code from the Solstice Enterprise Agents subagent to determine what you need for instrumentation in the SMA module.
Modify the SMA templates to use the appropriate functions to implement similar instrumentation code.

The following section uses an example MIB in demo_module_12 to illustrate this migration process.

Migrating Solstice Enterprise Agent Subagents to SMA

The SMA does not provide a comprehensive tool to migrate a Solstice Enterprise Agents subagent to an SMA module. A Solstice Enterprise Agents subagent uses two types of API functions. One type of API function is used for interaction with the master agent, and the other type is used for custom implementation. The functions for interaction with the master agent are common among all subagents. No tool is available that can separate the two types of functions, and put only the custom implementation code automatically into the corresponding place in the mib2c-generated code.

The simplest way to migrate a Solstice Enterprise Agents subagent is first to use the MIB tools of each environment to create code templates for each environment.

The following table compares aspects of the SMA mib2c tool and the Solstice Enterprise Agents mibcodegen tool. This comparison might help you to understand the code templates that each tool produces.

Table 10–1 Comparison of MIB Tools in SMA and Solstice Enterprise Agents Software


	SMA `mib2c` tool	Solstice Enterprise Agents `mibcodegen` tool
Scope of action on MIB	`mib2c` is run against individual nodes in a MIB, such as a subtree that contains scalars or a table. Running `mib2c` against individual tables rather than a parent subtree or group is advantageous. You can generate code templates that are customized according to the way you plan to implement each table in SMA. For example, you can generate templates for a table differently if the table is internal or external to the agent.	`mibcodegen` is run against the whole MIB.
Code generated	`mib2c` generates code for the implementation of a module that can be used in SNMP agent or AgentX subagent frameworks. Well-defined APIs are used to expose the functionality.	`mibcodegen` generates code to make the output represent a standalone subagent. SNMP is used to communicate between the master agent and the subagent.

`demo_module_12` Code Example for Solstice Enterprise Agents Subagent Migration

The demo_module_12 demonstrates how to implement a Solstice Enterprise Agents subagent as an SMA module.

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

Generate SMA template code from the EXAMPLE-MIB, by running the runmib2c script
Generate Solstice Enterprise Agents template code from the EXAMPLE-MIB, by running the runmibcodegen script

You should perform the procedures in demo_module_12 to produce the templates that are analyzed in the following section.

Analysis of the `demo_module_12` Solstice Enterprise Agents Templates

The mibcodgen tool produced several files. The following table describes and analyzes the files.

Table 10–2 Comparison of Solstice Enterprise Agents Templates to SMA Templates


Template File Name	Content	Comparison to SMA Templates
`example_tree.c`	Contains the type or storage definition for the MIB information.	Only the OID and column definitions contained in this file are also used in templates generated by `mib2c`. The agent or AgentX frameworks handle the rest for you.
`example_stub.h`	Contains `extern` function definitions for all `get`, `set`, and `free` functions that implement the variables in the MIB.	For each SNMP group, `mib2c` generates an include file that defines `extern`s for similar functions for both scalars and tables.
`example_stub.c`	Contains all `get`, `set`, and `free` functions that implement the scalar variables in the MIB.	For each SNMP group, `mib2c` generates a source code file. The file implements code for similar functions for the data types that the group contains, scalars, or tables. `mib2c` also generates the registration code that is invoked at initialization time. The registration code makes the agent aware of the OIDs that are supported. The registration code also identifies the `get` and `set` functions.
`example_rwTableEntry.c`	Contains all `get`, `set`, and `free` functions that implement the column variables for `rwTableEntry` in the MIB.	An equivalent file, `tableType.c` in the example, is generated by `mib2c` with one of the table configuration options. The `mib2c`-generated file contains similar functions but uses very different index handling. `mibcodegen` generates a `get` method that is passed a parameter to indicate whether to perform a `get` or `getnext` request. With `mib2c`, however, the index handling is performed prior to invoking the `get` method to handle a `getnext` request. A `get_first` method is exposed to the SMA agent so that the agent can find the first item in a table. A `get_next` method handles getting the next row in the table. When the correct row is found, the `get` or `set` method is called with the column to manipulate. This process applies to getting the correct row for `get`, `getnext`, or `set` functions when the data is external to the agent. If the data is held by the SMA master agent, table registration involves populating the table. After the table is populated, requests to the table would be handled directly by the SMA master agent.
`example_trap.c`	Contains trap definitions.	`mib2c` does not generate equivalent code. Traps can be generated by calling `send_enterprise_trap_vars()`.
`example_appl.c`	Contains code to support subagent.	`mib2c` does not generate equivalent code because such code is not needed. The SMA agent or AgentX framework handles the overhead and invokes the code through API functions.

Modifying the SMA Instrumentation Code

After you generate and analyze the templates, the task then is to extract the core SNMP get, getnext, and set processing out of the Solstice Enterprise Agents subagent code, and move it to the get and set handler and get_first/get_next methods defined in the SMA module approach.

The index handling is removed from each get and set function in Solstice Enterprise Agents code to be handled by the SMA. Special methods are used for tables. Context fields are used to store the current index information so that advancing in the table is relatively simple.