Solstice Enterprise Agents 1.0 User Guide

Chapter 3 SNMP-Based Master/Subagent

3.1 SNMP-Based Master/Subagent Overview

The Master Agent is the main component of Solstice Enterprise Agent technology. It runs as a daemon process and listens to User Datagram Protocol (UDP) port 161 for SNMP requests. The Master Agent also opens another port to receive SNMP trap notifications from various subagents. These traps are forwarded to various managers, as determined by the configuration files.

3.1.1 Invoking the Master Agent

A system startup script file invokes the Master Agent when the system is initially booted. Upon the Master Agent's invocation, it reads its various configuration files and appropriate actions are performed by activating subagents, determining the subtree OID for various subagents, populating its own MIBs. The Master Agent provides the following functionality:

Invokes subagents
Communicates with subagents
Registers subagents
Sends requests to subagents
Receives responses from subagents
Traps notifications from subagents

Note -

If you have snmpd (part of Domain Manager) or some other SNMP agent using port 161 running, the Solstice Enterprise Agents cannot run.

3.1.2 Invoking the Subagent

A subagent can be invoked in the following ways:

By the Master Agent - the Master Agent may invoke all agents with the agent resource file existing under SEA_SNMPConfiguration_Directory. The agents are invoked as specified in the Master Agent resource file. If the Master Agent successfully invokes a subagent, it creates a row entry in the subagent table and fills in the MIB variables with appropriate values for that subagent. A subagent is then registered with the Master Agent and is then ready to receive SNMP requests from the Master Agent.
Manually or automatically at boot time - system administrators/users may manually invoke subagents that have no agent resource file; or, startup scripts can invoke the subagents when the system is booted. Such agents can be invoked only after the Master Agent has been invoked. Additionally, these agents must have been created using the Solstice Enterprise Agent Software Development Kits (SDKs) and linked with the appropriate libraries. This allows the subagents to register dynamically with the Master Agent.

3.1.3 Communicating With the Subagent

Any communication from subagents to the Master Agent is done through UDP port 161. The topic of sending traps to the Master Agent from the subagents is discussed in "3.1.6 Trap Notification".

Note -

The Master Agent communicates on separate ports for each subagent.

The Master Agent also checks to be sure that registered subagents are up and running, based on the following conditions:

Time-out mechanism for each Get, Get Next, and Set request is sent to each subagent by the Master Agent.
No activity between the Master Agent and the subagents. The Master Agent (based on watch_dog time as defined in the agent resource file) is used to determine whether a particular subagent is active. This is accomplished by sending an SNMP Get request to the subagent if there has been no activity between the subagent and the Master Agent for some specific configured period of time.

3.1.4 Registering the Subagent

To register the subagent, the Master Agent binds it to the MIB. The Master Agent then determines its present location, using one of the following methods:

Static method - The Master Agent reads agent resource files. This resource file contains an entry for each subagent.
Dynamic method - The Master Agent receives the information from the subagents. The subagent sends a SET request containing the MIB objects needed to register with the Master Agent, through the use of the registration API.

The binding policy relates to the registration of SNMP object identifiers (OIDs). It involves decision-making on the part of the Master Agent when dispatching SNMP requests to various subagents. The Master Agent supports the binding policy, as shown in Table 3-1.

Table 3-1 Binding Policy


Type of Registration	Method of Registration
Individual variable registration	A subagent can manage individual variables
Row registration	A subagent can manage each row or multiple rows
Table registration	A subagent can register full and partial tables; partial table registration means that some columns of a table can be registered; for example, if a table has columns c1-c5, a subagent can then register a partial table managing c3 and c5 columns (only) of that table
Duplicate registration	NOT allowed
Overlapping registration	In the case of overlapped registration, the Master Agent dispatches requests on the basis of best OID match

3.1.5 Sending Requests

The Master Agent supports the forwarding of SNMP requests (Get, Get Next, and Set) in two modes. The mode is indicated by providing an optional argument with the command-line invocation. These modes are:

Group mode - Multiple variables can be included in each request from the Master Agent to the subagents. This results in one send-request per agent.
Split mode - Each variable in the incoming request results in one send-request to each subagent.

Following is a list of allowable send requests.

GET and GETNEXT - Sends requests to subagents.
SET - The set is implemented in a multi-phase fashion. First, all the varbinds in the set request are retrieved using a Get request. If successful, a Set request is sent to the respective subagents. If the Set request succeeds, a SUCCESS response is sent to the manager. If the Set request does not succeed, another Set request is sent to the subagents, with original values. This cancels the failed Set request. Any other SNMP requests being processed are completed before the Set request can be initiated.
GET RESPONSE - Receives responses from subagents.
TRAP - Receives notifications from subagents.

3.1.6 Trap Notification

The subagents send the traps to the Master Agent; the Master Agent the decides which managers will receive the trap. This decision is configurable.

3.2 Description of the Subagent

Subagents do not interact with the network manager directly. Instead, they communicate with the Master Agent. The management responsibility of the subagent can be offered to the Master Agent; however, it is up to the Master Agent to accept or ignore the offers.

After the subagents have registered with the Master Agent, they wait for the SNMP requests from the Master Agent. If a request is received, it sends the appropriate response. Additionally, the subagents can send SNMP traps.

The subagent is composed of four major components: the SNMP driver, Service API stack, subagent application, and MIB database. The Master Agent is responsible for receiving and sending the SNMP Protocol Data Units (PDUs). It also encodes and decodes the PDUs. The SP (Stack) dispatches the received requests appropriately or calls the applicable call back functions.

The system interface module is the implementation of the call back) of all the variables managed by the subagent. The MIB compiler automatically generates this information.

Except for the system dependent interface and the MIB database, the other components are reusable by other subagents and are provided in a library.

3.2.1 Establishment

This step involves the effort by the subagents to announce their presence and describe how to communicate with them. The transport used is UDP. The port on which the subagents listen for the SNMP request is configurable, as mentioned in "4.4 Agents Access Control File" on "4.4 Agents Access Control File". This establishment can also be done dynamically through a handshaking protocol.

3.2.2 Maintenance

The subagent periodically checks for existence of the Master Agent. The dynamic subagents (not invoked by the Master Agent) periodically determine whether the Master Agent is active. The runtime library reregisters the subagent's subtree with the Master Agent in the event of any interruptions.

3.2.3 Termination

Termination involves the effort to inform the Master Agent that the dynamic agent is about to exit. The Master Agent can then remove the row entry from its subagent table in the memory.

3.3 Using the Master Agent

snmpdx [-h] [-p port_number] [-r filename]

[-a filename] [-c dirname] [-i filename] [-o filename] [-y]

[-m GROUP|SPLIT] [-d debug_level]

The command line arguments are shown in Table 3-2.

Table 3-2 Master Agent Command Line Arguments


Argument	Description
`-a` `filename`	A full path (default) of the access control file is: `/etc/snmp/conf/snmdx.acl`; see "4.4 Agents Access Control File" for more information
`-c` `dirname`	The full path of the (default) directory containing the agent resource files; the default directory is: `/etc/snmp/conf`
`-d` `debug_level`	Used for debugging purposes; depending on the `debug_level` (0-4), it prints a specific amount of information; the default `debug_level` is 0
`-h`	Command usage
`-i` `filename`	The full path of the PID used by the Master Agent for recovery after a crash; it contains tuples of the UNIX process ID, port number, resource name, and agent name (default files) is: `/var/snmp/snmpdx.st`
`-o` `filename`	This file contains the tuple (`enterprise_name`, `oid`); for example, (`Sun Microsystems,1.3.1.6.1.4.32`); the file (default) is used as a base for lookup in the trap-filtering and forwarding process is: `/etc/snmp/conf/enterprises.oid`
`-m GROUP \| SPLIT`	The forwarding of SNMP requests mode; the default is `GROUP`; see "3.1.5 Sending Requests"for a description of the two modes
`-p` `port_number`	The port number; the default port number is 161; for example, `-p 1234`
`-r` `filename`	The full path of the resource file name used by the Master Agent; stores information about the subagents that the Master Agent invokes and manages; the default resource file is `/etc/snmp/conf/snmpdx.rsrc`; see "4.2 Agents Resource Configuration Files"for more information
`-y`	A recovery indicator signals when invoking the Master Agent process and then invokes the recovery module; the recovery process discovers which subagents in the previous session are still active; those subagents not active are re-spawned by the Master Agent