# Chapter 1. Agent Integrator Overview

The Agent Integrator is designed to facilitate management of today's increasingly complex and heterogeneous distributed systems. Agent Integrator is based on the Internet-standard Simple Network Management Protocol (SNMP). The Agent Integrator is an intelligent master agent that enables you to:

- Use multiple "peer" SNMP agents on a single network node.

The Integrator acts as a local proxy for the SNMP manager, fanning out requests from the manager to the "peer" agents.

- Offload polling from the management station to reduce network traffic and reduce load on the network manager.

  User-defined rules enable the Agent Integrator to check for the occurrence of significant system events and send alarms or execute programs when the events are detected. Communication over the network occurs only when an event is detected or when starting or stopping polling activity from the manager.

- Manage system resources using multiple SNMP Multiplex (SMUX) subagents (such as those built using the BEA Manager Agent Development Kit).

  The Integrator "speaks" SMUX to the subagents and fans out requests from an SNMP-compliant system or network management station to the appropriate subagent.

- Manage system resources using any other master agent/subagent protocol, such as Desktop Program Interface (DPI), where the master agent responds to SNMP management requests.

  The DPI master agent "speaks" Simple Network Management Protocol (SNMP) to management stations and is thus managed by Agent Integrator in the same manner as any other "peer" SNMP agent.

- Coordinate communication between an SNMP manager and multiple SNMP agents on multiple network nodes.

  This feature is particularly useful when offloading polling to the Agent Integrator for management of a distributed system whose components are spread over a number of computers. To the Agent Integrator, the managed resources appear as if they were on a single computer.

This chapter provides a general introduction to SNMP concepts and the Agent Integrator software. It includes the following sections:

- "The Manager-Agent Model," gives a brief overview of the SNMP manager-agent model and Agent Integrator capabilities.

- "Polling," gives an overview of the Agent Integrator's ability to offload threshold-checking from the management station.

- "Object Identifiers," gives an overview of the tree structure that defines access to managed objects within the Management Information Base (MIB). The MIB provides a shared definition of managed resources that enables managers and agents to cooperate in management tasks.

- "Directory Structure," describes the BEA Manager Agent Integrator directory structure.

- "Environment Variables," summarizes the BEA Manager Agent Integrator environment variables.

## The Manager-Agent Model

The Agent Integrator software is based on the manager/agent model described in the network management standards defined by the International Organization for Standardization (ISO). In this model, a network manager exchanges monitoring and control information about network and system resources with distributed software processes called agents.

Any system or network resource that is manageable through this exchange of information is a managed resource. This could be a software resource, such as a message queue or TUXEDO application, or a hardware resource, such as a router or NFS file server.

Agents function as "collection devices" that typically gather and send data about the managed resource in response to a request from a manager. In addition, agents often have the ability to issue unsolicited reports to managers when they detect certain predefined thresholds or events on a managed resource. In SNMP terminology, these unsolicited event reports are called trap notifications.

A manager relies upon a database of definitions and information about the properties of managed resources and the services the agents support - this comprises the Management Information Base (MIB). When new agents are added to extend the management domain of a manager, the manager must be provided with a new MIB component that defines the manageable features of the resources managed through that agent. The manageable features of resources, as defined in an SNMP-compliant MIB, are called managed objects. Defining the heterogeneous components of an enterprise's distributed systems within a common MIB on the management station provides a unified perspective and single access point for managing system and network resources.

### Master Agents and Subagents

In the SNMP architecture, each managed object can be managed through only one SNMP agent, and each host may have only one agent communicating with an SNMP manager. The original SNMP management solution allowed for only a single, monolithic agent to carry out all management responsibilities on a given network node (IP address). This solution was soon discovered to be too inflexible to provide for effective management of increasingly complex systems. In addition to the agents typically provided by computer manufacturers for hardware and operating system information, agents are also being produced by vendors of other products, such as agents for SQL database systems. Complex and heterogeneous systems thus require the ability to accommodate multiple agents on a single network node.

The SNMP architecture was thus extended to allow a single master agent to communicate with subagents, allowing multiple agents to cooperate in managing diverse hardware and software components on a single host. This master agent functionality is provided by the BEA Manager Agent Integrator software. The extended SNMP Manager/Agent model is illustrated in Figure 1-1.

> Figure 1-1 SNMP Architecture

A typical protocol used for communication between an SNMP master agent and subagents is the SNMP Multiplex (SMUX) protocol, defined in RFC 1227.

However, you may still wish to use one or more old-style monolithic agents that do not allow for a master agent/subagent architecture. Yet no standardized solution has emerged for the coexistence of non-SMUX SNMP agents on a single host. Master agents that "speak" SMUX protocol to subagents are typically able to communicate only with SMUX-compliant subagents, and cannot coexist with non-SMUX SNMP agents running on the same host.

However, the Agent Integrator can run on the same node with SNMP agents and SMUX subagents. The Agent Integrator can run on the same node with other master agent/subagent architectures, such as Distributed Program Interface (DPI) or EMANATE, so long as the master agent uses SNMP to respond to management requests, thus allowing multiple agents and subagents from any vendor to cooperate in the management of system components. The DPI master agent simply appears to the Agent Integrator as another SNMP agent. The multiple SNMP agents, SMUX subagents, and other subagents communicate with SNMP managers through the Agent Integrator and appear as a single SNMP agent to any SNMP manager.

In its communication with SMUX subagents (and DPI master agents and monolithic SNMP agents), the Agent Integrator acts as a proxy for the manager. The Agent Integrator distributes requests from the manager to specific SNMP agents or subagents, and receives the responses from the individual agents and forwards those responses back to the manager (as illustrated in Figure 1-1).

In Figure 1-2, the Agent Integrator master agent controls two master agents (one SMUX master agent and one DPI master agent) each controlling two subagents. It also directly controls one monolithic SNMP agent and a SMUX subagent.

> Figure 1-2 Agent Integrator Master/Subagent Architecture

## Polling

Managers can request the current values of managed objects at periodic intervals; this is called polling. To track faults in critical system components or applications, management systems use polling to determine whether attributes of the managed resource have crossed some significant threshold. However, direct polling by a management station becomes increasingly inefficient as the number of components being polled increases - the load on network bandwidth increases as does the load on the management station itself.

The Agent Integrator allows you to offload polling from the management station to the Agent Integrator. In other words, the Agent Integrator can be configured to check for a specified condition on its own. This feature expands your system management capacity by reducing the load on the management station and network bandwidth caused by threshold-checking activity.

The user can specify the threshold to check, and polling can be activated during Agent Integrator startup or by an SNMP SET request from the management station. The Agent Integrator sends an enterprise-specific SNMP trap when the threshold is crossed. To indicate the cause of the alarm, the user can configure a specific-trap type number to be sent in the trap generated when a given threshold is crossed. Communication between the manager and Integrator occurs only when the manager sends a SET request to de-activate (or re-activate) the polling, or when the Agent Integrator sends an SNMP trap if it detects the specified event in the managed resource. The Integrator can also be configured to execute a script or program when a threshold is crossed.

The polling capability of the Agent Integrator is described in more detail in Chapter 4, "Using Agent Integrator for Polling."

## Object Identifiers

An SNMP management system sees the data it manages as a collection of managed objects. The managed objects make up the Management Information Base (MIB). Each object in the MIB has an object identifier (OID), which the manager uses to request its value from the agent.

To make use of the Agent Integrator polling feature, described in the previous section, OIDs are used to identify the managed objects whose values are retrieved by the Agent Integrator when checking for the occurrence of events in the managed resource.

The OID is a sequence of integers that uniquely identify a managed object by defining a path to that object through a tree-like structure, which is often called the OID tree or registration tree. When an SNMP agent wishes to access a specific object, it traverses the OID tree to find the object.

Figure 1-3 illustrates the OID tree for the BEA private MIB. Each BEA private MIB object that the SNMP agent software manages uses a prefix of `.1.3.6.1.4.1.140` to identify it as an object in the BEA private MIB. This number sequence defines the path to this branch of the OID tree as illustrated in Figure 1-3.

> Figure 1-3 Object Identification Scheme

### Relative and Absolute Object Identifiers

Absolute OIDs specify a path to an attribute from the root of the OID tree (as in Figure 1-3). Relative OIDs specify a path to the attribute relative to some node in the OID tree. For example, `2.1.1.7` specifies the `sysContact` object in the `system` group, relative to the Internet node in the OID tree.

Absolute OID names always begin with a dot and must specify every node of the OID tree from the top-most node to the specific managed object; for example:

>     .1.3.6.1.2.1.1.1

### Specifying Object Identifiers

Thus far we have used only a series of integers separated by dots - called "dot-dot" notation - to describe OIDs. However, an OID can also be expressed using textual symbols instead of numbers to represent nodes in the path to the object, or by a combination of both integers and textual symbols. A symbolic OID uses mnemonic keywords to specify the managed object; for example:

>     mgmt.mib-2.system.sysDescr

The following numeric OID uses integers to specify the same managed object:

>     2.1.1.1

Note that this example is a relative OID.

An OID may combine both symbolic and numeric representations of individual nodes of the OID tree; for example:

>     mgmt.mib-2.1.sysDescr

Note: When using OIDs to specify objects whose values are checked using Agent Integrator polling rules, only the numeric form of the OID may be used. For details, see Chapter 7, "Configuration Files."

### Supported MIB Objects

In order to access MIB objects that are managed by agents or subagents, the scope of the OID tree that each agent or subagent is responsible for must be defined to the Agent Integrator. For monolithic SNMP agents, and SMUX or DPI master agents, this is done by specifying an OID in one or more NON_SMUX_PEER entries in the `beamgr.conf` configuration file (as described in Chapter 3, "Using Multiple SNMP Agents"). The Agent Integrator then knows to access the managed objects in that branch of the OID tree through the specified agent.

The Agent Integrator directly accesses MIB objects in the SMUX MIB, the MIB II `system` and `snmp` groups, and the `beaIntAgtTable` MIB object in the BEA Manager agent MIB. The `beaIntAgtTable` MIB objects define the polling capability of the Agent Integrator.

Using this MIB, the Agent Integrator can be configured to perform local polling and generate SNMP trap events or execute a system command when certain conditions are met. The same effect can be achieved by defining a RULE_ACTION entry in the `beamgr.conf` file. This configuration file is described in Chapter 7, "Configuration Files."

Three SMUX subagents are also shipped with Agent Integrator to support MIB groups in the BEA Manager agent MIBs as follows:

`unix_snmpd`
  Supports the `beaSystem`, `beaUnix`, `beaSmgr`, and `beaSysPerf` MIB groups. Supported on UNIX platforms only.

`nt_snmpd`
  ``Supports the `beaSystem` and `beaNTSysPerf` MIB groups. Also supports the following subgroups within the `beaUnix` group: the host process table (`beaPsTable)`, the host file system table (`beaDfTable)`, the system statistics group, and the local file system table (`beaLclDfTable)`. Does not support the message queue (`beaMqTable`) and semaphore (`ipcs -sa`) (`beaSemTable`) tables. Also, the `beaShmTable` (UNIX shared memory table) and `beaSmgrTable` are not supported. This is the Windows NT equivalent of `unix_snmpd`.

`pm_snmpd`
  Supports the BEA Manager Log Central Process Monitor. Consult the Log Central Administrator's Guide for information on supported MIB objects.

Refer to Chapter 8, "BEA SNMP Agent MIB," for more information about the BEA Manager MIB groups. The BEA Manager agent MIBs are defined in the BEA Manager MIB file `bea.asn1`. Refer to Chapter 6, "Starting the Subagents," for more information about the subagents.

## Directory Structure

You can find the Agent Integrator files in the directories shown in Figure 1-4.

> Figure 1-4 Directory Structure

Note: The items that appear in the gray boxes are descriptions only. They are not actual file names.

## Environment Variables

The BEA Manager Agent Integrator uses the following environment variables:

BEA_SMUX_PASSWD
  Indicates the password that a SMUX subagent is to use when re-establishing communication with the Agent Integrator.

BEA_PEER_MAX_TRIES
  Indicates the number of times the Agent Integrator retries sending an SNMP request to peer SNMP agents, when no response is received within the established timeout interval.

BEA_PEER_MAX_WAIT
  Modifies the default time interval that the Agent Integrator waits for a reply to a request sent to a SMUX subagent or an SNMP peer agent. This value can also be set by adding a BEA_PEER_MAX_WAIT entry to the BEA Manager configuration file. If this environment variable is not set, and there is no BEA_PEER_MAX_WAIT entry in the configuration file, the default is three seconds. For peer SNMP agents, the default timeout value can be overridden for individual SNMP agents using the timeout parameter in NON_SMUX_PEER entries in the BEA Manager configuration file (beamgr.conf), as described in Chapter 7, "Configuration Files."

BEA_SM_BEAMGR_CONF
  Specifies the absolute path to the BEA Manager configuration file (including the file name).