Chapter 2. Getting Started

This chapter describes the tasks that you need to perform after installing the Agent Integrator software on the managed node where you want the master agent to run. These tasks differ somewhat depending upon whether you are using the software on a UNIX system or a Windows NT system. For information about installing the software, please consult the BEA Manager Installation Guide.

Administrative Tasks on UNIX Systems

After the software is installed, there are additional tasks that must be carried out before the BEA Manager products can be used. This section describes post-installation tasks that are common to all BEA Manager products. To begin with, perform the following tasks:

Set your PATH to point to the BEA Manager executables

All users of the installed BEA Manager products 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 )
```
Copy the configuration file:

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
```
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. For more information refer to Chapter 7, "Configuration Files."
Specify non-default SNMP communities and SMUX password, if desired

By default, BEA Manager agents (such as the Agent Integrator or tux_snmpd when running as an SNMP agent) use public as the read-only community and iview as the read-write 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:
Advertise services if you need to use non-standard 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 non-default ports.
To modify or define the services, 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
```
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
```
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.

Administrative Tasks on Windows NT Systems

After the software is installed, there are additional tasks that must be carried out before the BEA Manager products can be used. To begin with, perform the following tasks:

Install the BEA Manager configuration file

Copy the BEA Manager configuration file (beamgr.conf):
```
md c:\etc
copy installation-directory\etc\beamgr.conf c:\etc
```
Specify the destination for traps, if desired

The default destination for SNMP trap notifications is localhost. If you want to specify some other destination for SNMP traps, 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. For more information refer to Chapter 7, "Configuration Files."
Specify non-default SNMP communities and SMUX password, if desired

By default, BEA Manager agents (such as the Agent Integrator or tux_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:
Advertise services if you need to use non-standard 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 non-default ports.
To modify or define the service locally, add the appropriate lines in the NT-root-directory\system32\drivers\etc\services file. You may wish to consult your system administrator.

Setting Up the Agent Integrator

This section assumes that you have performed the post-installation administrative tasks described in the preceding sections. Setting up the Agent Integrator involves the following additional tasks:

Indicating the managed objects that are available from "peer" SNMP agents, if any

The peer SNMP agents can be on the same managed node (IP address) as the Agent Integrator, or they can be on remote nodes. Access to the objects managed by the peer SNMP agents is defined through NON_SMUX_PEER entries in the beamgr.conf configuration file. Each entry defines or moves a branch of the OID tree that is accessible via that agent. This task is described in Chapter 3, "Using Multiple SNMP Agents."
Indicating the managed objects that are available through Distributed Program Interface (DPI) master agents, if any

Since a DPI master agent speaks SNMP, it appears to the Agent Integrator as just another peer SNMP agent. Setting up access to DPI subagents is thus done the same way as setting up access to peer SNMP agents, as described in step 1.
Modifying the management scope of SMUX subagents, if desired

You can modify a SMUX subagent's management scope - to avoid conflicts with other agents, for example - by specifying OID_CLASS entries in the beamgr.conf configuration file. By default, a SMUX subagent automatically indicates which section of the OID tree it is responsible for when it registers with the Agent Integrator master agent. The syntax for OID_CLASS entries is defined in Chapter 7, "Configuration Files."
Defining local polling rules and the actions to be taken by the Agent Integrator if user-defined thresholds are crossed

This task is necessary only if you want to use the Agent Integrator to offload polling from the management station. Polling rules are defined through RULE_ACTION entries in the beamgr.conf configuration file. Polling is automatically active when the Agent Integrator starts. Agent Integrator local polling can be de-activated or re-activated from a management station using SNMP SET commands. Agent Integrator polling rules, and how to start and stop polling, are described in Chapter 4, "Using Agent Integrator for Polling."
Configuring your SNMP management system for Agent Integrator

This involves two steps:
1. Loading the BEA MIB into the management system
  
  The BEA MIB definitions are contained in the file bea.asn1, included with the Agent Integrator. By default, this file is installed in the installation_directory/etc directory. This MIB must be compiled into the management database of your management platform. Some management platforms refer to this process as importing or loading a MIB. The exact set of steps required varies depending upon the management system used. Consult your management system documentation for specific instructions.
2. Configuring the management system for Agent Integrator traps
  
  Some configuration will be required on your SNMP-compliant management system to make use of SNMP trap notifications that are generated by Agent Integrator. The exact set of steps you need to perform vary depending upon which management system you are using. Typically some configuration or mapping is required to get the management system to perform a desired action (such as turning an icon red) when a trap is received. Consult your management system documentation for specific instructions.
Modify other entries in the configuration file (if desired)

You may need to modify the following fields in the BEA Manager configuration file (beamgr.conf):
These entries correspond to MIB objects in the beaSystem MIB group supported by the nt_snmpd subagent on Windows NT systems and supported by the unix_snmpd subagent on UNIX systems. For information on these objects, refer to the Chapter 3, "Using Multiple SNMP Agents."

Starting and Stopping the Agents

If you are using tux_snmpd or m3_snmpd as a subagent to manage TUXEDO 6.3 or 6.4 applications, you need to configure the Agent Integrator timeout to at least 30 seconds. This can be done by adding a BEA_PEER_MAX_WAIT entry to the BEA Manager configuration file (beamgr.conf) as follows:

BEA_PEER MAX_WAIT 30

Alternatively, you could set this timeout value by setting the environment variable BEA_PEER_MAX_WAIT to 30. For C shell on UNIX platforms, use the following command:

# setenv BEA_PEER_MAX_WAIT 30

Note: All NON_SMUX_PEERS (if any) should be started before the Agent Integrator.

Starting the Agents on UNIX Systems

To start the Agent Integrator and subagents, log in as root and start the following programs in the specified order:

# snmp_integrator 
# unix_snmpd

Note: Users of legacy products from earlier versions of BEA Manager may also wish to start the em_snmpd subagent. In addition, other SMUX agents may now be started. For more information refer to Chapter 5, "Agent Integrator Commands," and Chapter 6, "Starting the Subagents."

Starting the Agents on Windows NT Systems

Start the agents from the Windows NT service panel:

The Agent Integrator is installed as a Windows NT service (snmp_integrator).
A system subagent is installed as a Windows NT service (nt_snmpd).

The Integrator and agents must be started from the Services control panel. Expose the Windows TaskBar and select the Start Button. Select Settings from the menu, and open the Control Panel. Double-click on the Services applet. (In other words, select TaskBar'Start'Settings'Control Panel'Services.)

Locate each of the installed services. The Agent Integrator (snmp_integrator) should be started before the subagents. Click Start to start each service. There may be a short delay as each service is initiated.

Additionally, you can now start other SMUX subagents.

Stopping the Agents

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

stop_agents logical_agent_name | all [logical_agent_name]

For example,

stop_agents unix_snmpd

For all BEA Manager agents other than tux_snmpd and m3_snmpd, the logical agent name is always the name of the executable. If you specify all, all BEA Manager agents (including any agents built using the BEA Manager Agent Development Kit) will be stopped.