This chapter discusses the following topics:

• "Introduction," lists recommended reading, and gives a brief overview of the manager/agent model, the concept of a managed object, object identifiers, and SNMP traps.

• "Anatomy of SNMP Agents," describes the components of SNMP agents built using the Agent Development Kit: agent core, agent hooks, and the access functions.

• "Directory Structure," describes the Agent Development Kit directory structure.

Introduction

This manual explains how to:

• Create an agent that uses Simple Network Management Protocol (SNMP) to enable management of a resource defined in a private management information base (MIB).

• Create a subagent that provides manageability of a resource by plugging into an SNMP master agent using SNMP Multiplex (SMUX) protocol.

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 Manager/Agent Model

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.

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 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).

Figure 2-1 SNMP Architecture

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.

Managed Objects and Object Identifiers

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 .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

All standard MIBs reside under 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

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, bea is a MIB group that is a member of the private.enterprises MIB group.

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:

• MIB group a contains a group of objects, b, c, and d

• MIB group e contains a group of objects, f, i, and j

• MIB group f contains a group of objects, g and h

Scalar Objects and Tabular Objects

A managed object has both a type (defined in ASN.1) and a value. For example, the SNMP system group object sysLocation for the node blueberry has the type DisplayString and might have the value "Server Room 1242, Bldg. 11."

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 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

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 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

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 .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

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:

mgmt.mib.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.1.sysDescr

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:

.iso.org.dod.internet.mgmt.mib.system.sysDescr

All Agent Development Kit programs and utilities prepend the value .iso.org.dod.internet. to any relative object identifiers.

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.

Object Identifier Instance Indexes

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 0 in:

.iso.3.dod.1.mgmt.mib.1.sysUpTime.0

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.

SNMP Traps

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.

Figure 2-5 SNMP Trap Protocol Data Unit (PDU)

The fields have the following meaning:

• PDU type identifies the packet as a trap notification.

• enterprise is the vendor identification (OID) for the network management subsystem that generated the trap.

• agent address is the IP address of the node where the trap was generated.

• generic trap type is an integer in the range of 0 to 6. These values have the meanings indicated in Table 2-1.

• specific trap type is a number that further specifies the nature of the event that generated the trap in the case of traps of generic type 6 (enterpriseSpecific). The interpretation of this code is vendor-specific.

• timestamp is the length of time between the last re-initialization of the agent that issued the trap and the time at which the trap was issued.

• variable bindings provide additional information pertaining to the trap. This field consists of name/value pairs. The significance of this field is vendor-specific.

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_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

SNMP agents or subagents built using the Agent Development Kit software are composed of the following components:

Agent core

This layer contains the code to do SNMP and SMUX protocol handling and is independent of the specifics of the MIB supported by the agent. This layer contains the SNMP/SMUX protocol stack, the functions for traversing the OID tree, and the ASN.1 encoding and decoding functions.

Agent hooks

This layer provides the mapping between the agent core layer and the access functions layer. Hooks map an SNMP or SMUX protocol request for a managed object to the appropriate access function.

Access functions

This layer is independent of the SMUX and SNMP protocols and is very dependent on the specific features of the supported MIB. These are functions that retrieve and change the values of attributes of the managed resource represented by MIB objects, thus providing the backend work to support SNMP GET and SET requests. The Agent Development Kit code generator creates skeletons of these functions which are then completed by the agent developer.

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

How the Agent Works

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:

1. The SNMP manager sends an SNMP packet to the agent. This packet contains an encoded request (such as a request to GET the value, or SET the value, of a specific managed object).

2. When the agent core receives the request, it parses the SNMP packet (ASN.1 decoding) to determine the type of request (i.e., GET or SET) and the MIB group, and invokes the appropriate agent hook.

3. The agent hook invokes the function associated with the SNMP MIB group to which the object belongs. The agent hook then invokes the access function corresponding to the object within the MIB group.

4. The access function does the actual work of retrieving the object's current value (for a GET request) or modifying the object's value (for a SET request). The method used to perform the GET or SET depends on where the managed object resides (i.e., UNIX kernel, shared memory, file, or in another process) and does not involve SNMP. If the object resides in another process, you can use shared memory or a proprietary protocol, such as Sun RPC/XDR or DCE RPC.

   Depending on the value received from the access function, the agent hook layer returns one of the following responses to the agent core:

   • A value from a GET function

   • An OK from a SET function

   • An ERROR, if an error occurred

5. The agent core receives the response from the agent hook and builds the SNMP packet (ASN.1 encoding). It then sends the response packet to the SNMP manager.

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.

Core Libraries

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.