# Chapter 2. Setting Up the Agents

The Agent Connection facilitates TUXEDO and M3 system management from any SNMP-compliant management platform. Integrating the Agent Connection into your management system requires set-up tasks on both the managed node and on the management system. This chapter describes the procedure for setting up the Agent Connection on the managed node. Integration into the management system is described in Chapter 3, "Integrating Agent Connection with a Management System."

## Setting Up the Agent Connection

Preparing the Agent Connection for TUXEDO or M3 system management requires the following steps on Windows NT systems:

1. Make sure TUXEDO or M3 is installed.

2. Install the Agent Connection on the managed nodes.

   Agent Connection can be installed on a managed node from the BEA Manager CD. The BEA Manager CD contains an installation script for installing the agents on UNIX systems and an installation program for installing the agents on Windows NT machines. For detailed information about how to install the Agent Connection, refer to the BEA Manager Installation Guide.

   Some attributes of TUXEDO resources are accessible globally (that is, no matter which TUXEDO node they are on) while others are accessible only by an SNMP agent local to the same machine. If you want to access managed objects that are only accessible locally, you must install TUXEDO SNMP agents on each machine where these resources reside. See "Local and Global TUXEDO Information" for more information.

   Both the M3 version of the agent (`m3_snmpd`) and the TUXEDO version (`tux_snmpd`) are installed when you install Agent Connection.

3. Set up access to M3 or TUXEDO shared binaries.

   - On Windows NT systems:

   If the Agent Connection was not installed in the same directory as the TUXEDO or M3 application, you need to make sure that the `bin` directory of the appropriate TUXEDO or M3 installation is prior to any other TUXEDO or M3 installations in the PATH system environment variable. This is to ensure that the Agent Connection has access to the correct TUXEDO or M3 DLLs.

   - On UNIX systems:

     `LD_LIBRARY_PATH` (`SHLIB_PATH` on HP-UX or `LIBPATH` on AIX)
       Defines the search path for shared libraries. This variable should include `$TUXDIR/lib`.

4. Install the BEA Manager configuration file.

   - On Windows NT systems:

   Copy the BEA Manager configuration file (`beamgr.conf`):

       md c:\etc
       copy installation-directory\etc\beamgr.conf c:\etc

   - On UNIX systems:

   Log in as root and copy the BEA Manager configuration file `beamgr.conf` from `installation_directory``/etc` to the `/etc` directory.

       %su
       Password:
       # cp installation_directory/etc/beamgr.conf /etc

5. Set your PATH to include the location of the BEA Manager executables (on UNIX systems).

   All users of the installed BEA Manager products will need to update their PATH environment variable to include the location of the BEA Manager executable files. The following is an example in C shell:

       % set path = ( $PATH installation_directory/bin )

6. Set your master agent timeout if you are running the agent as a subagent with TUXEDO 6.3 or later, or with M3.

   If you are using TUXEDO 6.3 or later, or M3, you need to configure the timeout of your SMUX master, if any (e.g., `snmp_integrator`), and of your SNMP manager, to at least 30 seconds. For `snmp_integrator`, this can be done by adding a INTEGRATOR_TIMEOUT entry to the BEA Manager configuration file (`beamgr.conf`) as follows:

   `INTEGRATOR_TIMEOUT 30`

7. Ensure match between TCP/IP host name and computer name on Windows NT systems

   When Agent Connection is installed on a Windows NT system, make sure that the host name specified in the TCP/IP Properties window, under DNS (Control Panel'Network'Protocols'TCP/IP'Properties'DNS) is the same as specified in the Computer Name field on the Network window, under Identification (Control Panel'Network'Identification). The name should be in all uppercase in both places.

8. Specify the destination for traps (if desired).

   The default destination for SNMP trap notifications is `localhost`. If you want traps to be sent to some other destination, use your favorite text editor to modify the BEA Manager configuration file (`beamgr.conf`) `TRAP_HOST` entry to specify the host name of the target destination machine for SNMP trap notifications, and the port number and community name to use in sending traps.

   Typically the destination will be the host machine where the SNMP management system is located. Some management systems use distributed trap daemons that "collect" SNMP trap notifications for forwarding to management stations. In that case, the machine with the trap daemon would be the destination.

   For more information refer to the "Configuration Files" chapter in the Agent Integrator Reference Manual.

9. Identify the domain to be managed.

   The identity of the TUXEDO application to be managed can be specified in two ways. Agent Connection uses the following sources in the indicated order of precedence:

   1. The TMAGENT entry in the BEA Manager configuration file. This entry is of the form:

       TMAGENT logical_agent_name tuxdir tuxconfig_path

   For more information refer to the "Configuration Files" chapter in the Agent Integrator Reference Manual.

   2. TUXCONFIG and TUXDIR environment variables

10. Ensure that the TUXEDO Event Broker is configured.

    The TUXEDO Agent Connection will not receive TUXEDO event notifications unless the TUXEDO Event Broker servers (`TMSYSEVT` and `TMUSREVT`) are running. To enable forwarding of TUXEDO events as SNMP traps, ensure that the TUXEDO Event Broker servers are running. Information on the TUXEDO Event Broker can be found in the "Programmed Administration" chapter of the BEA TUXEDO Administrator's Guide and in Section 5 of the BEA TUXEDO Reference Manual.

11. Integrate the Agent Connection with your SNMP management system.

    The steps for integrating Agent Connection into your management system are described in the next chapter, Chapter 3, "Integrating Agent Connection with a Management System."

12. Start the TUXEDO or M3 SNMP agents.

    Now you can start the SNMP agents on the managed nodes where your TUXEDO or M3 resources are present. Refer to "Starting and Stopping the SNMP Agents."

## Advanced Configuration

There are additional steps that you may want to take to customize Agent Connection to your needs, such as monitoring multiple TUXEDO domains concurrently or using nondefault ports for communication with the system manager. The following lists a number of optional configuration steps:

1. Define logical agent names if you want to monitor multiple TUXEDO domains concurrently.

To monitor multiple TUXEDO domains at the same time, add a TMAGENT entry to the BEA Manager configuration file for each agent. The TMAGENT entry is of the following form:

    TMAGENT logical_agent_name tuxdir tuxconfig_path

Monitoring of multiple domains is done by running a separate TUXEDO or M3 agent for each domain being monitored. These agents must be run as subagents under the Agent Integrator.

When multiple agents are running on the same node, then SNMP manager SET or GET requests to an agent must be addressed using a community of the form:

`community`@`logical_agent_name`

`logical_agent_name` identifies the agent to which the SNMP request is forwarded. For example:

    public@simpapp_agent

If only one agent is running on a node, `logical_agent_name` is optional in specifying the community in GET or SET requests.

2. Define TUXEDO event filters to use (if desired).

TUXEDO event filters can define a subset of TUXEDO events to be received by the agent for each domain being monitored. You can use TMEVENT_FILTER entries in the BEA Manager configuration file to define a subset of TUXEDO event notifications that are to be forwarded as SNMP trap notifications. For more information refer to the "Configuration Files" chapter in the Agent Integrator Reference Manual. MIB objects corresponding to TUXEDO event filters are described in Chapter 4, "TUXEDO Core MIB."

3. Specify non-default SNMP communities and SMUX password (if desired).

   By default, BEA Manager agents (such as the Agent Integrator, or `tux_snmpd` or `m3_snmpd` when running as an SNMP agent) use `public` as the read-only community and `iview` as the write-read community when communicating with SNMP managers. If you want to specify different community names to be used by BEA Manager SNMP agents, this is specified in the BEA Manager passwords file. The passwords file can also be used to specify a password to be used by Agent Integrator for authenticating connection requests from SMUX subagents. To set up the passwords file, do the following:

   1. Copy the BEA Manager passwords file (`beamgr_snmpd.conf`) to `c:\etc`. For example, on Windows NT issue the following command:

       copy installation-directory\etc\beamgr_snmpd.conf c:\etc

   2. Now you can modify the SNMP communities in this file. The keywords used in this file are:

   - SMUX_PASSWD

   - COMMUNITY_RO

   - COMMUNITY_RW

   - DISABLE_SET

   3. If you want to set the agent to be read-only, specify a DISABLE_SET entry in the passwords file as follows:

   DISABLE_SET YES

   If there is no DISABLE_SET entry in the passwords file, the agent has both SET and GET capability.

   For more information refer to the "Configuration Files" chapter in the Agent Integrator Reference Manual.

4. Specify a SMUX password (if desired) when using Agent Connection as a subagent under a SMUX master agent (such as Agent Integrator).

   The environment variable `BEA_SMUX_PASSWD` specifies the password that the SNMP agents (`tux_snmpd` or `m3_snmpd`) use when registering with a SMUX master agent (such as Agent Integrator). This environment variable is required only if the SMUX master agent expects a password. If this environment variable is not set, no password is specified by `tux_snmpd` or `m3_snmpd` when registering.

5. How to use nonstandard ports.

   By default, BEA Manager agents assume the following port numbers as specified by SNMP and SMUX standards:

       snmp         161/udp
       snmp-trap    162/udp
       smux         199/tcp

   The default port assignments may be sufficient for your needs. If necessary, you can define these services on other ports, or use the appropriate command-line options when starting BEA Manager agents to assign them to nondefault ports.

   - On Windows NT systems:

   To modify or define the services, add the appropriate lines in the `NT-root-directory\system32\drivers\etc\services` file. You may wish to consult your system administrator.

   - On UNIX systems:

     To modify or define the services, do the following:

     1. Determine if the NIS is running. You can use the `ypwhich` command to determine if an NIS server or map master is available. For example:

         % ypwhich
         zort.kremvax.com

     2. If an NIS server is available, you can use the `ypcat` command to determine if the services are available.

         % ypcat services | grep snmp
         snmp-trap    162/udp    snmptrap
         snmp         161/udp

     3. If an NIS server is not available and services are provided on the local host, you can examine the `/etc/services` file instead.

         % cat /etc/services | grep snmp
         snmp-trap    162/udp    snmptrap
         snmp         161/udp

   Refer to your UNIX system documentation, or consult your UNIX system administrator, for instructions specific to your UNIX platform to establish the SNMP services if necessary.

## Starting and Stopping the SNMP Agents

To enable management access to the TUXEDO or M3 resources represented in the BEA MIBs, you need to start the TUXEDO or M3 SNMP agents.

To monitor multiple TUXEDO or M3 domains, you can run multiple SNMP agents on the same node. Each agent can monitor only one domain. To monitor multiple domains, you must have the BEA Manager Agent Integrator running and the agents must be started as subagents.

On startup, a TUXEDO or M3 SNMP agent checks for a `TMAGENT` entry in the BEA Manager configuration file that matches its logical agent name. A `TMAGENT` entry provides a path to the TUXEDO or M3 domain to be monitored. If no matching `TMAGENT` entry is found, the agent connects to the TUXEDO domain specified in the TUXCONFIG and TUXDIR environment variables. The agent exits if the TUXCONFIG or TUXDIR environment variable is not defined and no appropriate `TMAGENT` entry is found in the BEA Manager configuration file. For more information refer to the "Configuration Files" chapter in the Agent Integrator Reference Manual.

### Starting the SNMP Agents on UNIX Platforms

To start the SNMP agents on a UNIX system, type the TUXEDO or M3 SNMP startup command at the command-line prompt.

For the TUXEDO SNMP agent, the syntax of the startup command is:

>     tux_snmpd  [-l logical_agent_name] [-d]  [-n]  [-s]  [-p  snmp_port]
>     [-r  smux_port] [-m  hostname] [-h]

For the M3 SNMP agent, the syntax of the startup command is:

>     m3_snmpd  [-l logical_agent_name] [-d]  [-n]  [-s]  [-p  snmp_port]
>     [-r  smux_port]  [-m  hostname] [-h]

#### Startup Options

The command options have the following interpretation:

`-l` `logical_agent_name`
  Separate logical agent names must be assigned if you want to run multiple instances of the agent on the same node. If the `-l` option is not specified, the name of the executable is used as the logical agent name.

  `logical_agent_name` is a string that associates an agent with a TUXEDO domain as defined by a TMAGENT entry in the BEA Manager configuration file (`beamgr.conf`). The logical agent name can be a maximum of 32 characters in length. The format of the TMAGENT entry is as follows:

  `TMAGENT` `logical_agent_name` `tuxdir` `tuxconfig
  `

  This entry assigns the agent started with `logical_agent_name` to the indicated TUXEDO domain. Refer to the "Configuration Files" chapter in the Agent Integrator Reference Manual.

`-d`
  This option dumps to standard output the SNMP or SMUX packets received and sent by the agent.

`-n`
  If the agent/subagent is run with this option, it does not become a daemon. This option is normally used if `tux_snmpd` (or `m3snmpd`) is to be started by `init` using the inittab table with the respawn option.

`-s`
  Specifies `tux_snmpd` or `m3_snmpd` to run as an SNMP agent. If this option is not specified, `tux_snmpd` or `m3_snmpd` runs as a SMUX subagent.

`-p` `snmp_port`
  `snmp_port` designates the UDP port on which `tux_snmpd` or `m3_snmpd` listens for incoming SNMP packets. This option allows running the `tux_snmpd` or `m3_snmpd` on a port other than the standard SNMP port 161. This option is meaningful only when `tux_snmpd` or `m3_snmpd` is running as an SNMP agent.

`-r` `smux_port`
  This option specifies the TCP port to use to connect to a SMUX master agent. (The default is port 199.) This option is meaningful only when `tux_snmpd` or `m3_snmpd` is running as a SMUX subagent.

`-m` `hostname`
  `hostname` is the name of the machine where the SMUX master agent (such as the Agent Integrator) is running. This option is used only when you want `tux_snmpd` or `m3_snmpd` to register with a SMUX master agent on a remote machine.

`-h`
  Causes the agent to print the syntax for the `tux_snmpd` command.

#### Description of tux_snmpd and m3_snmpd Commands

The `tux_snmpd` binary is the TUXEDO SNMP agent which supports the TUXEDO MIB. For a description of the supported MIB groups and objects, please refer to chapters 4 through 11 in this manual.

The `m3_snmpd` binary is the M3 SNMP agent which supports the TUXEDO MIB with M3 extensions. For a description of the supported M3-specific MIB groups and objects, refer to Chapter 6, "M3 MIB Groups."

This agent is capable of running as an SNMP agent or as an SMUX subagent.

When the `tux_snmpd` or `m3_snmpd` starts up as an SNMP agent, it generates a coldStart trap. The destination host, port, and community used when sending traps are as specified in the `TRAP_HOST` entry in the BEA Manager configuration file (`beamgr.conf`).

SNMP read-write and read-only communities supported by the `tux_snmpd` or `m3_snmpd` can be specified in the BEA Manager passwords file (`beamgr_snmpd.conf`). By default, the read-only community is `public` and the read-write community is `iview`. Community is meaningful only when the agent is running as an SNMP agent.

When running as an SMUX subagent, `tux_snmpd` or `m3_snmpd` specifies a password to the SMUX master agent at the time of registration if the environment variable BEA_SMUX_PASSWD has been defined. In that case, the value of BEA_SMUX_PASSWD is used as the password by `tux_snmpd` or `m3_snmpd`. If BEA_SMUX_PASSWD has not been defined, `tux_snmpd` or `m3_snmpd` does not specify a password to the master agent when registering.

`tux_snmpd` and `m3_snmpd` support the MIB-II `snmp` group when running as an SNMP agent.

Like other TUXEDO clients, `tux_snmpd` needs access to the TUXEDO shared libraries. For M3 environments, `m3_snmpd` needs access to the M3 shared libraries. For UNIX platforms, the user should make sure that the environment variable `LD_LIBRARY_PATH` is defined appropriately. (For HP-UX users, the variable name is `SHLIB_PATH`. For AIX users, the variable name is `LIBPATH`.)

### Starting the SNMP Agents on Windows NT Systems

To start SNMP agents on a Windows NT system, do the following:

1. Install additional Windows NT services, if you want to run multiple agents on a single node.

The installation program for Windows NT installs the SNMP agent as a single Windows NT service. If you want to run multiple instances of the agent to monitor multiple M3 or TUXEDO domains, you will need to install additional Windows NT services for the additional agents. Run the following commands for each additional TUXEDO SNMP agent:

    instsrv logical_agent_name
    install_directory\bin\tux_snmpd.exe

Alternatively, run the following commands for each additional M3 SNMP agent:

    instsrv logical_agent_name
    install_directory\bin\m3_snmpd.exe

Separate logical agent names must be assigned if you want to run multiple instances of the agent on the same node. To use multiple agents to monitor multiple TUXEDO or M3 domains, `logical_agent_name` is a string that associates an agent with a TUXEDO domain as defined by a TMAGENT entry in the BEA Manager configuration file (`beamgr.conf`). The format of the TMAGENT entry is as follows:

    TMAGENT logical_agent_name tuxdir tuxconfig

This entry assigns the agent started with `logical_agent_name` to the indicated TUXEDO or M3 domain. Refer to the "Configuration Files" chapter in the Agent Integrator Reference Manual.

2. Start the TUXEDO or M3 SNMP agent from the Services control panel.

On the Windows taskbar, choose Start'Settings'Control Panel. In the Control Panel window, double-click on the Services applet (as shown in Figure 2-1).

> Figure 2-1 Selecting Services from the Control Panel

In the list of Services, locate and select the installed service (`tux_snmpd` or `m3_snmpd`) and click Start to start it (as shown in Figure 2-2. There may be a short delay as the service is initiated.

> Figure 2-2 Starting a Service from the Services Applet

#### Startup Options

`-d`
  If this option is specified, the SNMP or SMUX packets received and sent by the agent are dumped to the Windows NT Event Log.

`-s`
  Specifies `tux_snmpd` or `m3_snmpd` to run as an SNMP agent. If this option is not specified, `tux_snmpd` or `m3_snmpd` runs as a SMUX subagent. If a SMUX master agent (e.g., `snmp_integrator`) is not running, the user must provide `-s` as a start-up parameter before selecting the Start button.

`-p` `snmp_port`
  `snmp_port` designates the UDP port on which `tux_snmpd` or `m3_snmpd` listens for incoming SNMP packets. This option allows running the `tux_snmpd` or `m3_snmpd` on a port other than the standard SNMP port 161. This option is meaningful only when `tux_snmpd` or `m3_snmpd` is running as an SNMP agent.

`-r` `smux_port`
  This option specifies the TCP port to use to connect to a SMUX master agent. (The default is port 199.) This option is meaningful only when `tux_snmpd` or `m3_snmpd` is running as a SMUX subagent.

`-m` `hostname`
  `hostname` is the name of the machine where the SMUX master agent (such as the Agent Integrator) is running. This option is used only when you want `tux_snmpd` or `m3_snmpd` to register with a SMUX master agent on a remote machine.

### Stopping the Agents

The following command is used to stop one or more BEA Manager agents:

>     stop_agent logical_agent_name | all [logical_agent_name]

For example,

>     stop_agent tux_snmpd

If you specify `all`, all BEA Manager agents (including any agents built using the BEA Manager Agent Development Kit) will be stopped. The name of the executable is the default logical agent name.

## TUXEDO Master and Non-Master Nodes

The TUXEDO SNMP agent may be installed on both TUXEDO master and non-master nodes. If the TUXEDO application is down on the non-master node, SNMP GET requests addressed to the SNMP agent on the non-master node may not have the latest information. This would be the case, for example, if the requested information has been updated on a master node after the application on the non-master node went down.

Also, SET requests to a non-master node are not allowed if the TUXEDO application is down on the local node.

### Local and Global TUXEDO Information

Some MIB groups in the TUXEDO MIB return values for all TUXEDO nodes whereas other MIB groups return data only for the local node. Thus, if you want to manage objects whose values are local to a particular machine, you must install a copy of the TUXEDO SNMP agent on that machine.

The following MIB groups or tables return only values local to the managed node:

- `tuxTwshTbl` - This table represents runtime attributes of workstation handler (WSH) client processes.

- `tuxTmachineActive` group - This group represents runtime statistics on a machine where some component of the TUXEDO application is active.

- `tuxTmsgTable` - This table represents runtime attributes of the TUXEDO System/T UNIX system message tables.

- `tuxTqueueTable` - This table represents runtime attributes of queues in an application.

- `tuxTAppQTbl` - This table represents attributes of application queues.

- `tuxTAppQmsgTbl` - This table represents attributes of messages stored in application queues.

- `tuxTQspaceTbl` - This table represents attributes of application queue spaces.

- `tuxTQtransTbl` - This table represents runtime attributes of transactions associated with application queue spaces.

- `tuxTBridgeTbl` - This table represents status and statistics pertaining to connections between machines making up an application.

- `tuxTclientTbl` - This table represents runtime attributes of active clients within an application.

- `tuxTconnTable` - This table represents runtime attributes of active conversations within an application.

- `tuxTdeviceTbl` - This table represents configuration and runtime attributes of raw disk slices or UNIX system files being used to store TUXEDO System/T device lists.

- `tuxTsrvrTblExt` - This table, an extension of `tuxTsrvrTbl`, represents attributes of servers within an application.

- `tuxTsvcGrp` - This group represents configuration attributes of services within an application.

- `tuxTranTbl` - This table represents runtime attributes of active transactions within the application.

- `m3LclIfQueueTable` - This table represents the local runtime attributes of an interface for a particular server queue.

- `m3LclInterfaceTable` - This table represents configuration and runtime attributes of CORBA interfaces for the local host on which the Agent Connection is running.

### Updating MIB Objects

Some objects in the BEA SNMP MIB for TUXEDO systems can be set (updated) only under certain states of the TUXEDO system. If you get an error while trying to set read-write objects in this MIB, please refer to the `ULOG` file. For details refer to `TM_MIB`(5) in the TUXEDO Reference Manual.

### Disabling SET Access

Access of a TUXEDO or M3 SNMP agent to managed resources can be made read-only, regardless of the community (password) used in SNMP requests, by disabling SET access. To do so, add the following line to the BEA Manager passwords file (`beamgr_snmpd.conf`):

DISABLE_SET YES

The default is for SET access to be enabled. This will take effect only if the change is made prior to starting the agent, or prior to re-initializing the agent using the `reinit_agent` command.