# Chapter 1. Overview

The BEA Manager Agent Connection for M3 and TUXEDO Systems enables TUXEDO and M3 applications to be managed from network management platforms (such as HP OpenView). The Agent Connection allows you to incorporate core TUXEDO and M3 information into your management platform. This TUXEDO and M3 information can then be easily viewed and managed by network management platforms that support the Simple Network Management Protocol (SNMP). SNMP is the de facto network management standard for networks based on the Internet (TCP/IP) network protocols.

## Benefits of Network Management Integration

The Agent Connection provides the SNMP link from TUXEDO and M3 applications to an SNMP-compliant network management platform for monitoring, control, and alarm notification. With this SNMP link, the network administrator can correlate fault and performance data collected by different sources. For example, certain database inserts may fail because the file system on which the database is residing has become full. This, in turn, may cause a TUXEDO service to fail. For a management platform to correlate this failure information with other aspects of system information and thus enable a pro-active management of the system, all pieces of management information need to be available from the same management console.

To achieve this level of correlation, you need a standardized way of communicating management information. SNMP is an open network management standard that provides a unified way of representing information about the manageable features of the heterogeneous components of large distributed systems.

Why provide an SNMP link to SNMP-compliant management platforms? The main reason is that TUXEDO or M3 applications are part of an overall organization or business middleware solution. It is not the only application that will be running on your network. Integrating TUXEDO or M3 applications with SNMP allows you to effectively manage all of your large-scale applications using the SNMP-compliant network management tool of your choice. Since most of the management platforms support SNMP today, SNMP agents for TUXEDO and M3 applications can be integrated into virtually every management framework. Examples of such management platforms include:

- HP OpenView

- IBM NetView/6000

- Tivoli

- Sun Domain/SunNet/Site Manager

- CA Unicenter

These management platforms help the network or system administrator to manage and control systems, databases, applications, and user access from a centralized management console. The tools available from the management platform enable the automation and delegation of routine and complex system tasks.

SNMP manageability of TUXEDO and M3 applications provides the following benefits:

- Enables you to move towards a single management console and thus provide integrated systems management of M3 or TUXEDO based applications.

- Enables you to hook TUXEDO or M3 applications into popular management platforms such as HP OpenView, Sun SunNet Manager, IBM NetView/6000. This makes the management of TUXEDO or M3 applications more effective by providing a whole-system perspective instead of piecemeal solutions.

- Helps preserve your investment in standard, compliant (SNMP-capable) management frameworks.

- Enables you to benefit by the experience of a large community of SNMP users.

- Opens up a way for providers of management applications to write management applications for TUXEDO or M3 customers, as SNMP is an open standard.

## SNMP Overview

The Simple Network Management Protocol (SNMP) provides a standard system for classifying system information about hardware, software, and other aspects of a distributed client/server system. The basic SNMP standard for system management is defined in the Network Working Group (NWG) RFC 1157.

SNMP network and systems management 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 (also termed management variables or variables). Examples of managed objects include the state of a TUXEDO domain, the number of users currently logged on to a system, the number of physical network interfaces on a router, or a global static variable in an application. 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 system and network resources.

The data types and the representations of resources within a MIB, as well as the structure of a particular MIB, are defined in a standard called the Structure of Management Information (SMI). This standard is described in the NWG RFC 1155.

A formal language, known as the ISO Abstract Syntax Notation One (ASN.1), is used to describe MIB data independently of any encoding technique used. SNMP uses a subset of the ASN.1 language to represent a MIB.

As illustrated in Figure 1-1, under the SNMP paradigm, there is a management platform that provides operators access to management information from a management console. At the management console, the systems administrator issues management commands to SNMP agents to collect the values of various management variables which are defined in that platform's Management Information Base. The SNMP protocol is based on asynchronous request/response commands. A management station sends a GET or GET-NEXT command to request values of MIB variables from an agent, or a SET request to modify the value of a variable. Once the data is collected, management platforms can present views or graphs of the information or take action in response to the information provided by SNMP agents.

> Figure 1-1 SNMP Management and SNMP Agent Interaction

Typically, management platforms save the collected data to a repository for historical reporting. They also commonly include various tools and utilities to analyze the management data. The management framework enables the network administrator to automate responses to event-based operations, change access privileges, update application information, and tune application parameters.

The Agent Connection provides several key features for TUXEDO and M3 applications management:

Monitor
  SNMP monitoring allows any supported SNMP-capable management station to monitor the state of the TUXEDO or M3 system. Also, appropriate actions may be triggered, once a variable crosses a predefined threshold.

Control
  Using SNMP SET commands, an SNMP-capable management station can modify the value of TUXEDO or M3 control and configuration parameters.

Alarm Notification
  The TUXEDO or M3 system generates certain system-wide events in case of exceptions (for example, a TUXEDO node going down). These events are trapped and sent as a SNMP trap notification to the management station.

## The TUXEDO MIB for SNMP

The TUXEDO system includes management tools and a classification system that identifies its application items in a hierarchy of information known as a TUXEDO Management Information Base (TMIB). Although the term "MIB" is also used to designate the definition of the manageable features of managed resources within the SNMP standard, the TUXEDO TMIB is not compliant with the SNMP standard MIB format. (For more information, refer to "Differences Between the TUXEDO MIB and the SNMP TUXEDO MIB.")

The Agent Connection for TUXEDO and M3 provides the following components to incorporate TUXEDO and M3 information within an SNMP management framework:

- An SNMP translation of the TUXEDO and M3 MIB (TMIB), thus making manageable features of TUXEDO components recognizable within an SNMP management framework

- An agent, `tux_snmpd`, that "speaks" SNMP in order to respond to requests from SNMP managers and to generate SNMP trap notifications for TUXEDO system events

- `m3_snmpd`, a separate version of the SNMP agent for use with M3 applications

  Note: If an M3 application is not installed, the M3 specific objects included in the BEA TUXEDO MIB (`bea.asn1`) will not return values.

### MIB Object Identifiers

A MIB structure includes the idea of a hierarchical relationship between managed objects. Inclusive of the overall SNMP standard is a tree hierarchy (MIB tree) for defining groups of managed objects. Each managed object in the MIB is assigned a unique number called an object identifier (OID). As illustrated in Figure 1-2, an object identifier consists of a left-to-right sequence of integers known as sub-identifiers. The sequence defines the location of the object within a MIB tree. By specifying a path to the object through the MIB tree (also known as the registration tree), the OID allows the object to be identified uniquely. As shown in Figure 1-2, each node in the path defined in an OID has both a number and a name associated with it. The digits below the `enterprise` OID in the tree can be any sequence of user-defined numbers chosen by an organization to represent its private MIB groups and managed objects.

The following figure shows an example of the format of the bea object identifiers.

> Figure 1-2 MIB Object Identifier Hierarchy and Format

In this hierarchy, each BEA private MIB object that the SNMP agent software manages has a unique object identifier. The BEA TUXEDO object uses a prefix of `.1.3.6.1.4.1.140` to identify it as an object in the BEA private MIB.

For more information about the MIB, refer to chapters 4 through 11 of this manual. For a complete listing of objects in the BEA private MIB in ASN.1 notation, read the file `bea.asn1` in the SNMP Agent Connection product.

### ASN.1 File

An ASN.1 file is a standard SNMP file that defines the objects that make up an SNMP- compliant MIB. Each object in the file is defined in compliance with the SNMP standard. The Agent Connection provides the ASN.1 file `bea.asn1` for defining the TUXEDO MIB (with M3 extensions) for SNMP (and other BEA private MIBs).

Note: The TUXEDO and M3 MIB definitions are written in concise MIB in accordance with RFC 1212, as required by the SNMP standard.

### MIBs Supported by the SNMP Agent Connection

Within the `bea.asn1` file are definitions for TUXEDO and M3 objects that are SNMP compliant. The Agent Connection supports the following MIBs:

- TUXEDO Core MIB. This MIB supplies the definitions for controlling the operation and configuration of the TUXEDO middleware system. This MIB contains the main information groups for TUXEDO applications, including domains, machines, queues, servers, routing, clients, and services.

- BEA Domain List MIB. This MIB group represents information about the M3 or TUXEDO domains that the agent is monitoring.

- M3 MIB. An extension of the core MIB that incorporates definitions for management of M3 factories and CORBA interfaces.

- Access Control List MIB. This MIB allows you to define and control your application security options.

- Workstation or /WS MIB. This MIB specifies information about TUXEDO client workstations including workstation listeners and handlers.

- Application Queue MIB. This MIB provides the administrative control required for managing access to application queues. The objects in this MIB include items for managing queue spaces, queues, messages, and transactions.

- Event Broker MIB. This MIB represents event subscriptions registered with the Event Broker for receiving event notifications.

- Event Traps MIB. This MIB defines all the trap notifications that will be generated by the Agent Connection and the objects passed in the variable bindings for these traps.

TUXEDO managed object names within the MIBs for SNMP are usually prefixed with the letters `tux`. M3 managed object names within the SNMP MIB are usually prefixed with `m3`. For example, the TUXEDO Core MIB contains a group termed Machine. Within this group are managed objects such as the following:

`tuxTmachinePmid`
  Represents a physical machine identifier

`tuxTmachineLmid`
  Represents the logical machine identifier

All TUXEDO objects apply to M3 applications also.

### Structure of the MIB Definitions

Chapters 4 through 11 of this manual contain the definitions of the TUXEDO MIBs (with M3 extensions) and serve as a reference for the material in the SNMP Agent Connection `bea.asn1` file. The definitions that make up the TUXEDO MIBs for SNMP are grouped by MIB (Access Control List, Application Queues, Traps, etc.), with the M3 extensions in a separate chapter.

#### MIB Object Definitions Format

Chapters 4 through 11 specify the definitions of managed objects supported by the Agent Connection. The following keywords are used to define MIB managed objects:

Syntax
  Defines the abstract data structure corresponding to that object type. The ASN.1 language is used for this purpose. However, the SMI purposely restricts the ASN.1 constructs that may be used. These restrictions are made expressly for simplicity.

Access
  Defines whether the object value can only be retrieved but not modified (read-only) or whether it can also be modified (read-write).

Note: For tabular objects, a read-write object in some cases can only be set during creation of a new row. When this is true, this will be noted in the Description section for that MIB object.

Description
  Contains a textual definition of that object type, which provides all semantic definitions necessary for interpretation. This clause typically contains information of the sort that would be communicated in any ASN.1 commentary annotations associated with the object.

Note: Each row in a table is an instance of the Entry object under that table. The Description section for the Entry object under a table (such as `tuxTmachineTable`) contains information on the columnar values that are minimally necessary for creation of a row, how a new row is created, whether the values pertain only to the local machine, and other pertinent information about the table objects.

#### MIB Event Trap Definitions Format

Traps are also defined in the `bea.asn1` file. These traps are defined in accordance with RFC 1215, Trap definitions. Chapter 11, "TUXEDO Traps MIB," specifies the list of traps generated by the TUXEDO or M3 SNMP agent. The following keywords are used to define a trap:

Enterprise
  An object identifier that specifies the management enterprise under whose registration authority this trap is defined. All the traps generated by the TUXEDO or M3 SNMP agent have an enterprise field set to the TUXEDO object identifier. The TUXEDO object identifier is `.1.3.6.1.4.1.140.300`. This value is passed in the `enterprise` field of the trap packet (Protocol Data Unit - PDU).

Variables
  Defines the ordered sequence of MIB objects, which are contained within every instance of the trap type. Each variable is placed, in order, inside the variable-bindings field of the SNMP trap packet (PDU).

Description
  Contains a textual definition of the trap type.

Trap ID
  Specifies the enterprise-specific trap ID for the trap definition. This is passed in the specific trap ID field of the trap packet (PDU).

Note: The value of the generic trap ID field in traps is always set to 6, indicating an enterprise-specific trap.

## Differences Between the TUXEDO MIB and the SNMP TUXEDO MIB

If you are familiar with the TUXEDO MIB (TMIB), the primary difference to note when using the SNMP-based MIB is a difference in terms and a few additional MIB items in the SNMP-based MIB.

The TUXEDO MIB identifies an abstract structure for TUXEDO resources. In a TUXEDO system, a MIB is the classification of information in a TUXEDO application. However, instead of referring to groups and managed objects as is common in SNMP terminology, the TUXEDO MIB defines application resources as classes and attributes. Classes are the administrative class definitions that make up the TUXEDO MIB. Each class has a set of attributes that identify individual items in the class. Examples of TUXEDO classes are:

`T_MACHINE`
  The class definition for a machine

`T_SERVICE`
  The class definition for TUXEDO services

Attributes for these classes are identified by the prefix TA_ followed by the attribute name. A few examples for the T_MACHINE class are:

`TA_PMID`
  Represents a physical machine name

`TA_LMID`
  Represents the logical machine name

For more information about the standard TUXEDO MIB (TMIB), refer to the TUXEDO Reference Manual.

In contrast to all this; in SNMP the features of manageable resources are called objects rather than attributes, and objects fall under MIB groups rather than classes.

### Managing M3 and TUXEDO Applications Using the SNMP MIB

The M3 and TUXEDO systems identify application items in a hierarchy of information known as TUXEDO Management Information Bases (TMIB). These MIBs contain definitions that describe the components found in the M3 or TUXEDO application. Included with the Agent Connection is an SNMP version of the TMIBs. The Agent Connection SNMP MIB also includes MIB objects that represent attributes of M3 resources.

To monitor or modify values of managed objects, using your systems management platform, you will need to know which MIB objects represent the features of TUXEDO or M3 resources that are relevant to your management goals. You will also need to know the data types, default values, and access permissions for these MIB objects. Chapters 4 through 11 of this manual contain all of the reference information necessary to manage TUXEDO or M3 objects.

#### Querying Non-Existent MIB Objects

If you attempt to retrieve the value of a MIB object, and that object does not exist, either no value will be returned, or one of the following values will be returned:

- `-1` if the object is numeric

- A dash (`-`) if the object data type is `DisplayString`

### Managing TUXEDO Resources from a Management Platform

Figure 1-3 illustrates a management platform's graphical view of servers on a network, which includes the capability to identify and manage various TUXEDO servers.

> Figure 1-3 Managing TUXEDO Servers

Within most management platforms, you can set up conditions for alarm generation based on your defined event criteria. The criteria typically consists of changes in the values of certain attributes of the managed resources. These attributes are represented as MIB objects. You can also define actions to take when specified events occur, such as when a particular threshold is crossed.

The TUXEDO and M3 MIB for SNMP supports a full range of TUXEDO and M3 system and application events. These system and application events are transmitted as enterprise-specific traps. Figure 1-4 provides an example of how TUXEDO events, as well as other system events, can be selected in a management platform GUI. Chapter 11, "TUXEDO Traps MIB," contains information that may help you to interpret TUXEDO specific traps.

> Figure 1-4 Specifying Event and Event Notifications

Each management platform has its own view of the SNMP-based TUXEDO MIB information. This presentation can differ from platform to platform. However, if your management platform accepts SNMP-compliant MIBs, you can manage all the objects provided in the TUXEDO and M3 MIB for SNMP.

## Getting Started

Integrating the Agent Connection into your management system requires set-up tasks on both the managed node and on the management system. Set-up tasks for the agents on the managed node are described in Chapter 2, "Setting Up the Agents." Integration with the management system is described in Chapter 3, "Integrating Agent Connection with a Management System."