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.

  4. Install the BEA Manager configuration file.

  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:

    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.

    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:

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.