This chapter discusses the following topics:
This manual explains how to:
Introduction
The Agent Development Kit simplifies this work by providing automated code generation and additional features that allow you to build an agent quickly and reliably.
You do not need to understand the SNMP or SMUX protocol in depth to build an SNMP agent with this Agent Development Kit. We do recommend that you read the RFC documents listed below.
A necessary step in building an agent or subagent is defining the manageable features of the resource in an SNMP-compliant MIB. To do this, you should have some knowledge of Abstract Syntax Notation One (ASN.1), as defined in the International Organization for Standardization (ISO) standards. This product also presupposes that the user is familiar with the C programming language.
The Agent Development Kit is compliant with the following Internet standards:
RFC 1155 - Structure of Management Information
RFC 1157 - Simple Network Management Protocol
RFC 1212 - Concise MIB Definitions
RFC 1213 - Management Information Base (MIB II)
RFC 1227 - SNMP Multiplex (SMUX)
Information on obtaining these RFC documents can be found in the "SNMP Information" appendix in the Agent Integrator Reference Manual.
The Agent Development Kit software is based on the manager/agent model described in the ISO network management standards. 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, or "trap," 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. When the heterogeneous components of an enterprise's distributed systems are defined within a common MIB on the management station, this provides a unified perspective and single access point for managing systems made up of diverse hardware and software components from numerous vendors.
In order to provide manageability of a resource, an agent must have access to instrumentation in the managed resource. This consists of some means of obtaining current values of the manageable features of that resource, or a means of modifying those values. This might consist of operating system calls, or an application's application programming interface (API) that provides status and performance information about that application.
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 2-1.
One of the most popular protocols used for communication between an SNMP master agent and subagents is the SNMP Multiplex (SMUX) protocol, defined in RFC 1227.
However, no standardized solution has emerged for coordination of multiple 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 communicate with non-SMUX SNMP agents running on the same host.
The BEA Agent Integrator is an intelligent master agent that provides a comprehensive solution for orchestration of diverse agents and subagents.
The Agent Integrator is a master agent that can run on the same node with monolithic SNMP agents and SMUX subagents, allowing multiple agents and subagents from any vendor to cooperate in the management of system components. The multiple SNMP agents and SMUX subagents communicate with SNMP managers through the Integrator and appear as a single SNMP agent to any SNMP manager.
In its communication with SMUX subagents (and non-SMUX SNMP agents running on the same host), the master agent acts as a proxy for the manager. The master agent 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 2-1).
Refer to the Agent Integrator Reference Manual for more information on the Agent Integrator.
The Agent Development Kit is a software development kit for the creation of SMUX subagents or SNMP agents for management of system resources, as defined in private MIBs. Subagents created using the Agent Development Kit are also capable of running as a stand-alone SNMP agent. The Agent Development Kit is fully compliant with RFC 1212, Concise MIB Definitions.
The manager sees the data it manages as a collection of managed objects, represented in ASN.1 notation. The ASN.1 notation defines the data that the manager and the agent exchange. ASN.1 is a formal language described in the ISO 8824 and 8825 standards.
The managed objects comprise 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. 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.
The following diagram illustrates the OID tree for the BEA private MIB. Each BEA private MIB object that the SNMP agent software manages has a unique object identifier, using a prefix of
All standard MIBs reside under A MIB group is a collection of managed objects, and is itself represented by the name or OID of a node in the OID tree. Groups may contain other groups. For example, The nodes in the OID tree that are not groups - the base level of the OID tree - are the "leaves" of the OID tree. For example, in the following diagram:
The Manager/Agent Model
Master Agents and Subagents
Figure 2-1 SNMP Architecture
Managed Objects and Object Identifiers
.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, represented by dashed lines in Figure 2-2.
Figure 2-2 Object Identification Scheme
mgmt
(.1.3.6.1.2
) in this diagram - for example, MIB II (.1.3.6.1.2.1
). The distinction between the standard and private MIBs is that of control over the object definitions. Standard MIBs are those that have been approved by the Internet Activities Board (IAB). MIBs defined unilaterally by equipment and software vendors are initially defined as private MIBs under private.enterprises
. A branch within the private.enterprises
subtree is allocated to each vendor that registers for an enterprises object identifier. For a complete listing of objects in the BEA private MIB in ASN.1 notation, read the file bea.asn1
in the Agent Development Kit distribution.
MIB Groups
bea
is a MIB group that is a member of the private.enterprises
MIB group.
a
contains a group of objects, b
, c
, and d
A managed object has both a type (defined in ASN.1) and a value. For example, the SNMP system group object Managed objects, in SNMP, are of two types: scalar objects and tabular objects. A managed object that always has a single instance is called a scalar object. Tabular objects, on the other hand, have multiple instances, such as the rows of a table. For example, the MIB II
Tables in SNMP are two-dimensional objects defined as an ASN.1 type called SEQUENCE OF, which allows 0 or more members. Each element of the sequence is an entry (row) in the table, which is itself a sequence of scalar-valued objects. SNMP does not allow tables to be nested within tables.
For example, the MIB II
The examples of object identifiers discussed thus far all specify a path to the attribute from the root of the OID tree. For example, the BEA object identifier Until now 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 symbolically, or by a combination of both integers and textual symbols. A symbolic OID uses mnemonic keywords to specify the managed object; for example:
The following numeric OID uses integers to specify the same managed object:
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:
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:
All Agent Development Kit programs and utilities prepend the value The Agent Development Kit automatically generates a sorted cross-reference of numeric OIDs to MIB object names whenever an agent executable is built. Refer to Chapter 4, "Developing an SNMP Agent," for more information.
To use the Agent Development Kit utilities, such as snmpget, to obtain values of objects, it is necessary to specify the instance of the object. The instance of an object is specified by appending an instance index to the object identifier. For example, the last is the instance index. An instance index of "0" (zero) specifies the first instance, "1" specifies the second instance, and so on. Since sysUpTime is a scalar object, it has only one instance. Therefore, an instance index of zero is always specified when retrieving the value of a scalar object. An instance index higher than 0 can only be used in the case of columnar objects, which can have multiple instances.
In addition to retrieving data from the managed resource in response to requests from a management station, agents typically also have the ability to send unsolicited messages to managers when they detect some significant event. An unsolicited message of this sort is called a trap notification. The fields that comprise the SNMP trap packet occur in the order shown in Figure 2-5.
The fields have the following meaning:
Scalar Objects and Tabular Objects
sysLocation
for the node blueberry has the type DisplayString and might have the value "Server Room 1242, Bldg. 11."
system
group has seven "leaf" objects under it, as illustrated in Figure 2-3. Each of these objects is a scalar object. For example, the value of sysUpTime is the length of time since re-initialization of a system's network management software (SNMP agent), measured in hundredths of a second.
Figure 2-3 A Group of Scalar Objects
at
group (illustrated in Figure 2-4) contains simply one tabular object, the atTable
, which contains one row for each of a system's physical interfaces. Each row in the table is an instance of the object atEntry
. Each row contains instances of the scalar-valued leaf objects atIfIndex
, atPhysAddress
, and atNetAddress
. The leaf objects are called columnar objects since the instances of each such object constitute one column in the table. Although these objects have scalar-valued instances, they are not scalar objects because they can have multiple instances.
Figure 2-4 A Group Containing a Tabular Object
Relative and Absolute Object Identifiers
.1.3.6.1.4.1.140
specifies the path from the root of the tree. (The root does not have a name or a number but the initial 1 in this OID is directly below root.) These are called absolute OIDs. However, a path to the attribute may be specified 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. This is called a relative OID.
Specifying Object Identifiers Symbolically
mgmt.mib.system.sysDescr
2.1.1.1
mgmt.mib.1.sysDescr
.iso.org.dod.internet.mgmt.mib.system.sysDescr
.1.3.6.1.2.1.1.1
.iso.3.dod.1.mgmt.mib.1.sysDescr
.iso.org.dod.internet.
to any relative object identifiers.
Object Identifier Instance Indexes
0
in:
.iso.3.dod.1.mgmt.mib.1.sysUpTime.0
SNMP Traps
Figure 2-5 SNMP Trap Protocol Data Unit (PDU)
The interpretation of generic trap types is described in Table 2-1.
The Agent Development Kit provides an application programming interface (API) for generating traps from within your agent. The library of functions comprising this API are described in Chapter 3, "Tools and Functions."
A sample program, SNMP agents or subagents built using the Agent Development Kit software are composed of the following components:
snmp_appl.c
, illustrating the use of the SNMP trap API, is provided in the $RELEASE_ROOT/agentsrc/agentlib/
directory. A sample makefile, sample.mk
, is also provided in the same directory to compile the sample program.
Anatomy of SNMP Agents
Because the Agent Development Kit builds the agent hooks and agent core layers for you, you need only be concerned with filling in the access function skeletons to retrieve or modify the values of the resource represented by the managed objects. The Agent Development Kit builds code for you that does the necessary SNMP and SMUX protocol handling and ASN.1 decoding and encoding, and mapping of SNMP requests to your custom access functions.
Figure 2-6 illustrates how these components fit together to process requests from, and send responses to, SNMP managers.
Figure 2-6 Data Flow to and from the Agent
An agent built using the Agent Development Kit communicates with an SNMP manager, on the one hand, and the managed resource, on the other hand, in the following way:
GET
function
You can find the Agent Development Kit files in the $RELEASE_ROOT
directory. Most customer development files will be found in the agentlib
directory.
Figure 2-7 Directory Structure
Note: The items that appear in the gray boxes are descriptions only. They are not actual file names.
You need to include the core libraries and include files from the release when you build the SNMP agent or SMUX subagent. The code and declarations that accomplish this have already been included in the makefiles provided with this release. You will normally be working under the $RELEASE_ROOT/agent_src/agentlib
directory.