Setting Up Oracle SNMP Agent on a Managed Node

To integrate Oracle SNMP Agent into your management framework, you need to set up the Oracle SNMP Agent software on the managed node and on the management framework. The following sections describe the procedure for setting up the Oracle SNMP Agent on the managed node:

•	Directory Structure

•	Oracle SNMP Agent Configuration Files

•	Oracle SNMP Agent Configuration

•	Oracle SNMP Agent Advanced Configuration

•	Starting Oracle SNMP Agent

•	Stopping Oracle SNMP Agent

•	Oracle Tuxedo Master and Non-Master Nodes

Directory Structure

The Oracle SNMP Agent files reside in the directories shown in Figure 3‑1.

Figure 3‑1 Directory Structure

Note:

tux_prod_dir represents the directory in which the Oracle Tuxedo 10.0 distribution is installed.

Oracle SNMP Agent Configuration Files

Oracle SNMP Agent provides the following two configuration files: beamgr.conf and beamgr_snmpd.conf. The beamgr.conf file, also known as the “Oracle SNMP Agent configuration file,” contains the user-defined operational configurations read by the Tuxedo SNMP agent (tux_snmpd) and the Oracle SNMP Agent Integrator (snmp_integrator) at startup.

The beamgr_snmpd.conf file, also known as the “Oracle SNMP Agent passwords configuration file,” contains the user-defined password configurations (SNMP community names, SMUX password) read by tux_snmpd and snmp_integrator at startup. The default read-only community name is public, and the default read-write community name is iview. The default SMUX password is no password.

For more information about the Oracle SNMP Agent configuration files, see “Configuration Files” on page 8‑1.

Oracle SNMP Agent Configuration

To configure Oracle SNMP Agent, follow these steps:

1.	Install the Oracle SNMP Agent on the Oracle Tuxedo server nodes to be managed.

The Tuxedo SNMP agent tux_snmpd is installed one at a time. On a Windows system, if you do not install Oracle Tuxedo first, you do not get the option to install tux_snmpd. For detailed information about how to install Oracle SNMP Agent, see Installing the Oracle Tuxedo System.

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 Oracle SNMP agent local to the same machine. To access managed objects that are only accessible locally, you must install Oracle SNMP agents on each machine where these resources reside, or install an Oracle SNMP agent on the master node and execute it with the -c option, which enables you to run the agent only on the master node but to still gather information from all machines.

2.	Set up access to Tuxedo shared binaries.

•	On a Windows system:

If Oracle SNMP Agent is not installed in the same directory as the Oracle Tuxedo application, make sure that the bin directory of the appropriate Tuxedo installation precedes any other Tuxedo installations in the PATH system environment variable. This directory order in PATH enables Oracle SNMP Agent to have access to the correct Tuxedo dynamic link libraries (DLLs).

•	On a UNIX system:

Make sure the search path for shared libraries includes $TUXDIR/lib. The search path for shared libraries is:

SHLIB_PATH on HP-UX, LIBPATH on AIX, and LIBRARY_PATH on all other UNIX systems.

3.	Install the Oracle SNMP Agent configuration file.

•	On a Windows system:

Open a command-line shell and copy the Oracle SNMP Agent configuration file beamgr.conf to the C:\etc directory:

prompt> md c:\etc
prompt> copy tux_prod_dir\udataobj\snmp\etc\beamgr.conf
           c:\etc

•	On a UNIX system:

Log in as root and copy the Oracle SNMP Agent configuration file beamgr.conf to the /etc directory:

prompt> su
prompt> Password:
prompt> cp tux_prod_dir/udataobj/snmp/etc/beamgr.conf /etc

4.	Set your PATH to include the location of the Oracle SNMP Agent executables. This step applies to both Windows and UNIX systems.

All users of the installed Oracle SNMP Agent products need to update their PATH environment variable to include the location of the Oracle SNMP Agent executable files. The following is a UNIX example in C shell:

prompt> set path = ( $PATH tux_prod_dir/bin )

5.	If you are running the Oracle SNMP agent as an SNMP multiplexing (SMUX) subagent, set your master agent timeout. The SMUX protocol is defined in RFC 1227.

Configure the timeout of your SMUX master, if any (such as snmp_integrator), and of your SNMP manager, to at least 30 seconds. For snmp_integrator, you can set this timeout by adding an INTEGRATOR_TIMEOUT entry to the Oracle SNMP Agent beamgr.conf configuration file as follows:

INTEGRATOR_TIMEOUT 30

6.	When Oracle SNMP Agent is installed on a Windows system, ensure that a match exists between the TCP/IP host name and the computer name.

Check that the host name specified in Start->Settings->Control Panel->Network->Identification is all UPPERCASE and matches the host name specified in Start->Settings->Control Panel->Network->Protocols->TCP/IP-> Properties->DNS, which should also be all UPPERCASE.

7.	Specify the destination for traps.

The default destination for SNMP trap notifications is localhost. To send traps to other destinations, use a text editor to modify the TRAP_HOST entry in the Oracle SNMP Agent beamgr.conf configuration file 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 is the host machine where the SNMP management framework is located. Some management frameworks use distributed trap daemons that “collect” SNMP trap notifications for forwarding to management stations. In that case, the machine with the trap daemon should be the destination.

For more information, see “Configuration Files” on page 8‑1.

8.	Identify the domain to be managed.

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

a.	The TMAGENT entry in the Oracle SNMP Agent configuration file. This entry is of the form:

TMAGENT logical_agent_name tuxdir tuxconfig_path

For more information, see “Configuration Files” on page 8‑1.

b.	TUXCONFIG and TUXDIR environment variables

9.	Ensure that the Oracle Tuxedo EventBroker is configured.

Oracle SNMP Agent cannot receive Tuxedo event notifications unless the Tuxedo EventBroker server (TMSYSEVT) is running. To enable forwarding of Tuxedo events as SNMP traps, ensure that the Tuxedo EventBroker servers are running. For information on the Tuxedo EventBroker, see “About the EventBroker” in Administering an Oracle Tuxedo Application at Run Time and reference page TMSYSEVT(5) in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

10.	If you are using only Oracle SNMP agents, start the Tuxedo SNMP agents on the managed nodes where your Tuxedo resources reside. For more information, see “Starting Oracle SNMP Agent” on page 3‑8.

If you are using the Oracle SNMP Agent Integrator, follow the instructions in “Setting Up the Oracle SNMP Agent Integrator” on page 5‑1 and set up the Oracle SNMP agents and then the Oracle SNMP Agent Integrator.

11.	Integrate Oracle SNMP Agent with your SNMP management framework. See “Integrating Oracle SNMP Agent with a Management Framework” on page 4‑1.

Oracle SNMP Agent Advanced Configuration

If you want to customize Oracle SNMP Agent for tasks such as managing multiple Oracle Tuxedo domains concurrently or using nondefault ports for communication with the system manager, perform the following additional steps:

1.	Define logical agent names if you want to manage multiple Tuxedo domains concurrently.

To manage multiple Tuxedo domains on a managed node at the same time, add a TMAGENT entry to the Oracle SNMP Agent configuration file for each agent. The TMAGENT entry is of the following form:

TMAGENT logical_agent_name tuxdir tuxconfig_path

To manage multiple domains on a managed node, run a separate Tuxedo agent for each domain being monitored. These agents must be run as SMUX subagents under the Oracle SNMP Agent Integrator.

When multiple agents running as SMUX subagents are running on the same node, SNMP manager Set or Get requests to a particular agent must be addressed using a community of the form:

community@logical_agent_name

where 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 Set or Get requests.

2.	Define Tuxedo event filters to be used.

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 Oracle SNMP Agent configuration file to define a subset of Tuxedo event notifications that are to be forwarded as SNMP trap notifications. For more information, see “Configuration Files” on page 8‑1. MIB objects corresponding to Tuxedo event filters are described in “Core MIB” in Oracle Tuxedo SNMP Agent MIB Reference.

3.	Specify non-default SNMP communities and SMUX password.

By default, an SNMP agent (such as the Oracle SNMP Agent Integrator or tux_snmpd when running as an SNMP agent) uses public as the read-only community and iview as the read-write community when communicating with SNMP managers. To define additional community names, specify them in the Oracle SNMP Agent passwords file. You can also use the passwords file to specify a password for the Oracle SNMP Agent Integrator to use for authenticating connection requests from SMUX subagents.

a.	To set up the passwords file:

On a Windows system:

Open a command-line shell and copy the Oracle SNMP Agent beamgr_snmpd.conf passwords file to c:\etc. For example:

prompt> copy tux_prod_dir\udataobj\snmp\etc\beamgr_snmpd.conf
           c:\etc

On a UNIX system:

Copy the Oracle SNMP Agent beamgr_snmpd.conf passwords file to the /etc directory and make the copy readable and writable only by root. For example:

prompt> cp tux_prod_dir/udataobj/snmp/etc/beamgr_snmpd.conf
           /etc
prompt> chmod 600 /etc/beamgr_snmpd.conf

b.	Modify the SNMP communities in this file. The keywords used in this file are:

SMUX_PASSWD

COMMUNITY_RO

COMMUNITY_RW

DISABLE_SET

c.	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, see “Configuration Files” on page 8‑1.

4.	Specify a SMUX password when using the Oracle SNMP agent component as a SMUX subagent under a SMUX master agent, such as the Oracle SNMP Agent Integrator.

The environment variable BEA_SMUX_PASSWD specifies the password that the SNMP agent uses when registering with a SMUX master agent, such as the Oracle SNMP Agent Integrator. This environment variable is required only if the SMUX master agent expects a password. If this environment variable is not set, a password is not specified by tux_snmpd when registering.

5.	Define different port numbers.

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

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

If the default port assignments are not sufficient for your needs, you can define these services on other ports, or use the appropriate command-line options when starting SNMP agents to assign them to nondefault ports.

•	On a Windows system:

To modify or define the services, add the appropriate lines in the root_directory\system32\drivers\etc\services file. For example:

snmp 161/udp snmp
snmp-trap 162/udp snmp

Consult your Windows system administrator for the default settings used for your SNMP-related services.

•	On a UNIX system:

To modify or define the services, perform these steps:

a.	Determine if the NIS server is running. Use the ypwhich command to determine if an NIS server or map master is available. For example:

prompt> ypwhich
zort.kremvax.com

b.	If an NIS server is available, use the ypcat command to determine if the services are available.

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

c.	If an NIS server is not available and services are provided on the local host, examine the /etc/services file.

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

To establish the SNMP services, refer to your UNIX system documentation as needed for instructions specific to your UNIX platform.

Starting Oracle SNMP Agent

To manage multiple Oracle Tuxedo domains, you can run multiple Oracle SNMP agents on the same node. Each agent can manage only one domain. To manage multiple domains, you must have the Oracle SNMP Agent Integrator running and the agents must be started as SMUX subagents.

On startup, a Tuxedo SNMP agent checks for a TMAGENT entry in the Oracle SNMP Agent configuration file that matches its logical agent name. A TMAGENT entry provides a path to the Tuxedo 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 Oracle SNMP Agent configuration file. For more information, see “Configuration Files” on page 8‑1.

Oracle SNMP Agent Processes

The tux_snmpd binary is the Tuxedo SNMP agent that supports the Tuxedo SNMP MIB. For a description of the supported MIB groups and objects, see Oracle Tuxedo SNMP Agent MIB Reference.

The Oracle SNMP agent can run as an SNMP agent or as a SMUX subagent.

When the Oracle SNMP agent 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 Oracle SNMP Agent beamgr.conf configuration file. For more information, see “Oracle SNMP Agent Configuration” on page 3‑3.

When running as a SMUX subagent, the Oracle SNMP agent 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 Oracle SNMP agent uses the value of BEA_SMUX_PASSWD as the password; if BEA_SMUX_PASSWD has not been defined, the Oracle SNMP agent does not specify a password to the master agent when registering.

The tux_snmpd supports the MIB-II snmp group when running as the SNMP agent.

Starting Oracle SNMP Agent on a Windows System

To start Oracle SNMP agents on a Windows system, follow these steps:

1.	On the Windows taskbar, choose Start->Settings->Control Panel->Services (or Start->Programs->Administrative Tools->Services on a Windows 2003 system) to display the Services window.

2.	In the list of Services, locate and select the installed service named tux81_snmpd and click Start to start it, as shown in Figure 3‑2. There may be a short delay as the service is initiated.

Figure 3‑2 Starting a Service

 

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

The installation program for Windows installs the SNMP agent as a single Windows service. If you want to run multiple instances of the agent to monitor multiple Tuxedo domains, you need to install additional Windows services for the additional agents.

To install additional Windows services for Tuxedo SNMP agents, open a command-line shell and run the following command for each additional Tuxedo SNMP agent:

prompt> instsrv logical_agent_name
           tux_prod_dir\bin\tux_snmpd.exe

Assign separate logical agent names to run multiple instances of the agent on the same node. To use multiple agents to monitor multiple Tuxedo domains, logical_agent_name is a string that associates an agent with a Tuxedo domain as defined by a TMAGENT entry in the Oracle SNMP Agent beamgr.conf configuration file. For format information, see “Oracle SNMP Agent Advanced Configuration” on page 3‑5.

This entry assigns the agent started with logical_agent_name to the indicated Tuxedo domain. See “Configuration Files” on page 8‑1.

Windows Startup Options

Enter the desired startup options in the Startup Parameters field in the Services window.

-d

Dumps the SNMP or SMUX packets received and sent by the agent to the Windows Event Log.

-s

Specifies that the Oracle SNMP agent is to run as an SNMP agent. If you do not specify this option, the Oracle SNMP agent runs as a SMUX subagent. If a SMUX master agent (for example, snmp_integrator) is not running, you must provide -s as a startup parameter before selecting Start.

-p snmp_port

The snmp_port option specifies the UDP port on which the Oracle SNMP agent listens for incoming SNMP packets. The -p option enables you to run the Oracle SNMP agent on a port other than the standard SNMP port 161. This option is meaningful only when the Oracle SNMP agent is running as an SNMP agent.

-r smux_port

Specifies the TCP port to connect to a SMUX master agent. (The default is port 199.) This option is meaningful only when tux_snmpd is running as a SMUX subagent.

-m hostname

The name of the machine where the SMUX master agent, such as the Oracle SNMP Agent Integrator, is running. This option is used only when you want tux_snmpd to register with a SMUX master agent on a remote machine.

-c

Enables you to run the agent only on the master node but to still gather information from all machines. This results in a more manageable solution because it requires you to run one agent process per domain instead of one per node. In addition, it enables you to gather SNMP information from nodes with operating systems not supporting the current SNMP Agent.

When using this option, you must ensure that only one agent is started on the domain; otherwise, the results are unpredictable.

Starting Oracle SNMP Agent on a UNIX System

To start Oracle SNMP agents on a UNIX system, enter the Tuxedo SNMP agent startup command at the command-line prompt:

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

UNIX Startup Options

The command line options are:

-l logical_agent_name

The logical_agent_name string associates an agent with an Oracle Tuxedo domain as defined by a TMAGENT entry in the Oracle SNMP Agent beamgr.conf configuration file. The logical agent name can be a maximum of 32 characters long. For format information, see “Oracle SNMP Agent Advanced Configuration” on page 3‑5.

Assign separate logical agent names to run multiple instances of the agent on the same node. If you do not specify the -l option, the Oracle SNMP agent uses the name of the executable as the logical agent name.

-d

Dumps the SNMP or SMUX packets received and sent by the agent to standard output.

-n

If the agent/subagent is run with this option, it does not become a daemon. Use this option to start the Oracle SNMP agent with the init command.

-s

Specifies that the Oracle SNMP agent is to run as an SNMP agent. If you do not specify this option, the Oracle SNMP agent runs as a SMUX subagent.

-c

Enables you to run the agent only on the master node but to still gather information from all machines. This results in a more manageable solution because it requires you to run one agent process per domain instead of one per node. In addition, it enables you to gather SNMP information from nodes with operating systems not supporting the current SNMP Agent.

When using this option, you must ensure that only one agent is started on the domain; otherwise, the results are unpredictable.

-p snmp_port

The snmp_port option specifies the UDP port on which the Oracle SNMP agent listens for incoming SNMP packets. The -p option enables you to run the Oracle SNMP agent on a port other than the standard SNMP port 161. This option is meaningful only when the Oracle SNMP agent is running as an SNMP agent.

-r smux_port

Specifies the TCP port to connect to a SMUX master agent. The default is port 199. This option is meaningful only when the Oracle SNMP agent is running as a SMUX subagent.

-m hostname

The name of the machine where the SMUX master agent, such as the Oracle SNMP Agent Integrator, is running. This option is used only when you want the Oracle SNMP agent to register with a SMUX master agent on a remote machine.

-h

Displays the syntax for the tux_snmpd command.

Stopping Oracle SNMP Agent

On a Windows system, you stop Oracle SNMP agents and the optional Oracle SNMP Agent Integrator via the Services window. On a UNIX system, you stop Oracle SNMP agents and the optional Oracle SNMP Agent Integrator by entering the stop_agent command at the command-line prompt.

Stopping Oracle SNMP Agent on a Windows System

To stop one or more Oracle SNMP agents on a Windows system, follow these steps:

1.	On the Windows taskbar, choose Start->Settings->Control Panel->Services (or Start->Programs->Administrative Tools->Services on a Windows 2003 system) to display the Services window.

2.	In the list of Services, locate and select the installed service and click Stop to stop it.

Stopping Oracle SNMP Agent on a UNIX System

To stop one or more Oracle SNMP agents on a UNIX system, issue the following command:

prompt> stop_agent logical_agent_name | all [logical_agent_name]

For example,

prompt> stop_agent tux_snmpd

If you specify all, all SNMP agents are stopped. The name of the executable is the default logical agent name.

Oracle Tuxedo Master and Non-Master Nodes

The Tuxedo SNMP agent can be installed on both Tuxedo master and non-master nodes. If the Oracle Tuxedo application is down on the non-master node, SNMP Get requests addressed to the Oracle SNMP agent on the non-master node may not have the latest information. For example, this would be true if the requested information was updated on a master node after the application on the non-master node went down. Set requests to a non-master node are not permitted if the Oracle Tuxedo application is down on the local node.

Some MIB groups in the Tuxedo SNMP MIB return values for all Tuxedo nodes, whereas other MIB groups return data only for the local node, as shown in the following table. Thus, if you want to manage objects whose values are local to a particular machine, you must install a copy of the Oracle SNMP agent on that machine or start the Oracle SNMP agent with the -c option on the master machine.

 

MIB Table/Group	Description
tuxTwshTbl	Run-time attributes of workstation handler (WSH) client processes.
tuxTulogTable	Run-time attributes of userlog files within an application.
tuxTmsgTable	Run-time attributes of the Tuxedo system message tables.
tuxTqueueTable	Run-time attributes of queues in an application.
tuxTAppQTbl	Attributes of application queues.
tuxTAppQmsgTbl	Attributes of messages stored in application queues.
tuxTQspaceTbl	Attributes of application queue spaces.
tuxTQtransTbl	Run-time attributes of transactions associated with application queue spaces.
tuxTBridgeTbl	Status and statistics pertaining to connections between machines making up an application.
tuxTclientTbl	Run-time attributes of active clients within an application.
tuxTconnTable	Run-time attributes of active conversations within an application.
tuxTdeviceTbl	Configuration and run-time attributes of raw disk slices or UNIX system files being used to store Tuxedo system device lists.
tuxTsrvrTblExt	Attributes of servers within an application. It is an extension of tuxTsrvrTbl.
tuxTranTbl	Run-time attributes of active transactions within the application.
tuxTsvcGrp	Configuration attributes of services within an application.
tuxLclIfQueueTable	Local run-time attributes of an interface for a particular CORBA server queue.
tuxLclInterfaceTable	Configuration and run-time attributes of CORBA interfaces for the local host on which Oracle SNMP Agent is running.
tuxTAppQctrl	A control MIB that enables controlled access to all application queue-related MIB groups.