Chapter 6 Deploying Modules

This chapter discusses the ways to deploy your module. The chapter provides information to help you decide whether you should use a subagent or a dynamically loaded module. Examples of deploying demonstration modules as subagents and dynamically loaded modules are included.

This chapter contains the following topics:

• Overview of Module Deployment

• Choosing Dynamic Modules or Subagents

• Loading Modules Dynamically

• Using Subagents

• Deploying a Module as a Subagent

Overview of Module Deployment

With the System Management Agent, you have the following choices for deploying a module:

• Load the module dynamically.

  When you load a module dynamically, the module is included within the SNMP agent without the need to recompile and relink the agent binary. This method is the only supported way to load a module into the System Management Agent. You cannot recompile the agent.

  Details of the module to load are specified in the configuration file. At runtime, the agent reads the configuration file. The agent locates the module files that are listed in the configuration file. The agent then merges the modules into the agent process image.

• Implement the module as an AgentX subagent.

  When you use a subagent, the module is embedded in an external application. The external application contains code to set up the application to run as an AgentX subagent. The SNMP agent's configuration file specifies that the agent is the AgentX master agent. When the external application starts, the module's OIDs are registered with the SNMP agent. The subagent application and the agent use the AgentX protocol to communicate.

These deployment methods have advantages and disadvantages, which are discussed in Choosing Dynamic Modules or Subagents. However, the way that you develop your module and the content of your module have no bearing on how you deploy your module. You can use the same module, without modification, with either deployment method.

Choosing Dynamic Modules or Subagents

In general, when you are first developing and testing your module, you should dynamically load the module in the master agent. This method reduces the complexity while you work out any problems in the module. When you are ready to deploy a module, you should compile the module in a subagent instead of dynamically loading into the master agent. By using subagents, you can more easily isolate problems in the module.

However, sometimes a subagent is not the optimal deployment method. Use the following criteria to determine when to load a module into a master agent instead of a subagent:

• If more than five requests per second are targeted to the module's MIB, you should consider loading the module into the master agent.

• If your module queries the SYSTEM group often, and queries the IP branch very rarely, load the module into the master agent.

• If your module queries the IP branch of the MIB very often, load the module in the subagent. The IP group of the module MIB is six times more computationally costly compared to the SYSTEM group.

The following table summarizes the primary advantages and disadvantages of dynamically loaded modules and subagents.

Loading Modules Dynamically

The simplest way to load modules dynamically is to restart the agent after you add entries to the configuration file. Dynamic loading is the best method to use while you are developing and testing a module. Most of the demonstration modules in /usr/demo/sma_snmp use dynamic loading. You should use the procedure How to Dynamically Load a Module and Restart the Agent during the development and testing phase.

When you are using the module in a production environment, that environment might require you not to restart the agent. If you want to load modules without restarting the agent, you should use the procedure How to Dynamically Load a Module Without Restarting the Agent.

How to Dynamically Load a Module and Restart the Agent

1. Copy the module shared library object to a lib directory.

   You should keep your .so files in a directory that is writable by non-root users.

2. As root, edit the agent's configuration file to enable the agent to dynamically load the module.

   In the /etc/sma/snmp/snmpd.conf file, add a line that is similar to the following, where testmodule is the name of the module.

   dlmod testmodule /home/username/snmp/lib/testmodule.so

3. As root, restart the snmpd agent by typing the following command.

   # svcadm restart svc:/application/management/sma:default

   The module should now be loaded. You can use snmpget and snmpset commands to access the module's data to confirm that the module is loaded. You should make sure your MIB can be located by the snmpget and snmpset commands by setting your MIBDIRS and MIBS environment variables, as described in Setting MIB Environment Variables.

   ---

   Tip –

   To unload a module, you would remove the dlmod line from the snmpd.conf file and restart the agent.

   ---

How to Dynamically Load a Module Without Restarting the Agent

The UCD-DLMOD-MIB provides MIB entries for the module name, path, and status. By setting these MIB entries, you can cause the agent to load or unload the module without restarting the agent.

This procedure causes the module to be loaded only for the current session of the agent. If you want the module to be loaded each time the agent starts, you should add a dlmod line to the snmpd.conf file. The process of adding the line is described in Step 2 of the previous procedure. Do not restart the agent after adding the line.

1. View the UCD-DLMOD-MIB.txt file in /etc/sma/snmp/mibs.

   Look for the DlmodEntry and dlmodStatus entries, which appear as follows:

   DlmodEntry ::= SEQUENCE {
        dlmodIndex  Integer32,
        dlmodName   DisplayString,
        dlmodPath   DisplayString,
        dlmodError  DisplayString,
        dlmodStatus INTEGER
    }
    
    dlmodStatus OBJECT-TYPE
        SYNTAX      INTEGER {
                        loaded(1),
                        unloaded(2),
                        error(3),
                        load(4),
                        unload(5),
                        create(6),
                        delete(7)
                    }
        MAX-ACCESS  read-write
        STATUS      current
        DESCRIPTION
            "The current status of the loaded module."
        ::= { dlmodEntry 5 }

   DlmodEntry defines a row in a table of dynamically loaded modules. A table row describes an instance by defining an index, name, path, error code, and status code. You need to set the name, path, and status of the first empty row of the table.

2. Type the following command to check the first row of the table. The command can tell you whether an instance of a dynamically loaded module already exists in the table.

   $ /usr/sfw/bin/snmpget -v 1 -c public localhost UCD-DLMOD-MIB::dlmodStatus.1 Error in packet Reason: (noSuchName) There is no such variable name in this MIB. Failed object: UCD-DLMOD-MIB::dlmodStatus.1

   This response indicates that no other dynamic module is defined as instance 1. If you get back a positive response, examine dlmodStatus.2 with the same command.

3. Create an instance for your module in the table by typing the following command:

   $ /usr/sfw/bin/snmpset -v 1 -c private localhost \ UCD-DLMOD-MIB::dlmodStatus.1 i create UCD-DLMOD-MIB::dlmodStatus.1 = INTEGER: create(6)

4. Repeat the snmpget command to show the status of the first instance.

   $ /usr/sfw/bin/snmpget -v 1 -c public localhost \ UCD-DLMOD-MIB::dlmodStatus.1 UCD-DLMOD-MIB::dlmodStatus.1 = INTEGER: unloaded(2)

   The instance now exists, but the module is unloaded currently.

5. Set the name and path to the module that you want to load. Type a command that is similar to the following:

   $ /usr/sfw/bin/snmpset -v 1 -c private localhost \ UCD-DLMOD-MIB::dlmodName.1 s "testmodule" \ UCD-DLMOD-MIB::dlmodPath.1 s "/home/username/lib/testmodule.so" UCD-DLMOD-MIB::dlmodName.1 = STRING: testmodule UCD-DLMOD-MIB::dlmodPath.1 = STRING: /home/username/lib/testmodule.so

   testmodule is the name of your module.

6. Load the module by typing the following command:

   $ /usr/sfw/bin/snmpset -v 1 -c private localhost \ UCD-DLMOD-MIB::dlmodStatus.1 i load UCD-DLMOD-MIB::dlmodStatus.1 = INTEGER: load(4)

   This command sets the dlmodStatus.1 variable to load.

7. Confirm that the module was loaded by typing the following command:

   $ /usr/sfw/bin/snmpget -v 1 -c public localhost \ UCD-DLMOD-MIB::dlmodStatus.1 UCD-DLMOD-MIB::dlmodStatus.1 = INTEGER: loaded(1)

   The response indicates that the module is loaded.

8. (Optional) Unload the module by typing the following command:

   $ /usr/sfw/bin/snmpset -v 1 -c private localhost \ UCD-DLMOD-MIB::dlmodStatus.1 i unload UCD-DLMOD-MIB::dlmodStatus.1 = INTEGER: unload(5)

9. (Optional) Confirm that the module was unloaded by typing the following command:

   $ /usr/sfw/bin/snmpget -v 1 -c public localhost \ UCD-DLMOD-MIB::dlmodStatus.1 Timeout: No Response from localhost.

   The lack of response from localhost indicates that the module is unloaded.

Using Subagents

Using subagents with an extensible SNMP agent avoids the problem of having one very large SNMP agent. Before subagents were devised, an SNMP agent had to be recompiled to add new management objects in MIBs. The subagent approach provides the ability to dynamically add management objects to an agent without recompiling the agent. The need to standardize the way in which agents and subagents work together led to the development of the AgentX protocol.

AgentX Protocol

The AgentX protocol enables subagents to connect to the master agent. The protocol also enables the master agent to distribute received SNMP protocol messages to the subagents.

The AgentX protocol defines an SNMP agent to consist of one master agent entity and other subagent entities. The master agent runs on the SNMP port, and sends and receives SNMP messages as specified by the SNMP framework documents. The master agent does not access the subagents' management information directly. The subagents do not handle SNMP messages, but subagents do access their management information. In short, the master agent handles SNMP for the subagents, and only handles SNMP. The subagent handles manipulation of management data but does not handle SNMP messages. The responsibilities of each type of agent are strictly defined. The master agent and subagents communicate through AgentX protocol messages. AgentX is described in detail by RFC 2741. See http://www.ietf.org/rfc/rfc2741.txt

The SMA performs in the role of the master agent. Subagents that you create can add management objects to the agent.

Functions of a Subagent

An AgentX subagent performs the following functions:

• Initiates AgentX sessions with the master agent

• Registers MIB regions with the master agent

• Instantiates managed objects

• Binds object IDs (OIDs) within its registered MIB regions to actual variables

• Performs management operations on variables

• Initiates notifications, or traps

Deploying a Module as a Subagent

You can embed a MIB module that was written for the SMA into an external application. This application can be run either as an SNMP master agent or an AgentX subagent. Generally, you should run the SMA as the master agent, and set up your application as a subagent. The subagent attaches to the master agent, and registers its MIB with the master agent. By running the SMA as the master agent, you can easily add and remove subagents while the master agent continues to run. In this way, the agent can continue to communicate with network management applications.

SMA provides Net-SNMP API functions that enable you to embed an SNMP agent or AgentX subagent into an external application. In your application code, you must initialize your module, the SNMP library, and the SNMP agent library. This initialization is done slightly differently depending on whether the application is to run as a master agent or an AgentX subagent.

The functions that you use in the agent application include:

• init_agent(char *name)

  Initializes the embedded agent. This function must be called before the init_snmp() call. The name is used to specify what configuration file to read when init_snmp() is called later. See the API documentation at /usr/sfw/doc/sma_snmp/html/group__library.html for more information.

• init_module()

  Initializes your module. This function must be called after the agent is initialized.

• init_snmp(char *name)

  Initializes the SNMP library, which causes the agent to read the application's configuration file. The configuration file can be used to configure access control, for instance. See the snmp_config(4) and snmpd.conf(4) man pages for more information about configuration files.

• snmp_shutdown(char *name)

  Shuts down the subagent, saving any needed persistent data. See the API documentation at /usr/sfw/doc/sma_snmp/html/group__library.html for more information.

You must also link against the Net-SNMP libraries in your subagent application. The command

net-snmp-config --agent-libs

displays a list of libraries you need.

The demo_module_8 code example shows you how to create a subagent that calls a module that returns load averages.

demo_module_8 Code Example for Implementing a Subagent

The demo_module_8 code example demonstrates how to deploy a module in a subagent. The demo is by default located in the directory /usr/demo/sma_snmp/demo_module_8. The README_demo_module_8 file within that directory includes procedures for building and running the sample module and subagent program.

Subagent Security Guidelines

You must be aware of the following security considerations in writing subagents that use the AgentX protocol:

• The AgentX protocol does not contain a mechanism for authorizing or refusing to initiate sessions. Access control between subagents and master agent must be done at a lower layer, such as the transport layer.

  The SMA supports only UNIX domain sockets for communication between the master agent and subagents. As a result, the master agent and subagents must run on the same host.

  In open source Net-SNMP, the master agent and subagent can be on different hosts. The agents must then use UDP and TCP ports for the AgentX communication. Currently, the AgentX protocol provides no inherent security when using UDP and TCP ports. To reduce security risks, the SMA does not allow subagents to use UDP and TCP ports.

• The AgentX protocol does not define any access control mechanism. The protocol also does not contain a mechanism for authorizing or refusing sessions.

• A subagent can register any subtree. Potentially, a malicious subagent could register an unauthorized subtree of sensitive information. That subagent could then see modification requests to those objects in the tree. A malicious subagent might also give answers to SNMP manager queries. These answers might cause the manager to perform an action that leads to information disclosure or other damage.