2
Installing the Intelligent Agent

This chapter covers generic setup and configuration procedures for the Intelligent Agent. The following topics are discussed:

• Installing the Intelligent Agent

• Controlling Operations of the NT Agent

• Configuring SNMP Windows NT and Windows 2000

• Controlling Operations of the UNIX Agent

• Configuring SNMP for UNIX

• Configuring the 9i Agent for Use with Multiple Network Cards (NIC)

• Agent Behavior when Using Multiple Network Cards

• Oracle Intelligent Agent and Oracle Names

• Roles and Users Required by the Intelligent Agent

• Auto-Discovery

• Service Discovery Process

• Upgrading from 8.0.6/8.1.6/8.1.7 Intelligent Agents to 9.0

Installing the Intelligent Agent

The Intelligent Agent is shipped with the database and can be installed on remote, managed machines under an ORACLE_HOME environment. Using the Oracle Universal Installer, the Agent can be selected for installation from one of two locations: the Enterprise Manager tree list or the database server tree list (this option installs the database and the Agent). To install the Intelligent Agent as a standalone service, select the Agent from the Enterprise Manager tree list.

Controlling Operations of the NT Agent

The following procedures are used to control the operation of the Intelligent Agent on Microsoft Windows NT system.

Starting the Intelligent Agent on Windows NT

To start the Agent on Windows NT, perform the following steps:

1. Double-click the Services icon in the Control Panel folder.

2. Select the Oracle<ORACLE_HOME_NAME>Agent service.

   The Startup Type is set to Manual, which allows the Agent to be started by a user. If you want the Agent to start automatically whenever you start the system, set the Startup Type to Automatic.

   1. Click the Startup push-button. A Service Startup dialog box appears.

   2. Choose Automatic under the Startup Type.

   3. Click OK on the Service Startup dialog box.

3. Click the Start push-button to start the Agent.

net start oracle<ORACLE_HOME_NAME>agent

Stopping the Intelligent Agent on Windows NT

To stop the Agent on Windows NT, perform the following steps:

1. Double-click the Services icon in the Control Panel folder.

2. Select the OracleAgent service.

3. Click the Stop push-button to stop the Agent.

   Note: You can also stop the Agent from the command line by typing the following: net stop oracle<ORACLE_HOME_NAME>agent

Verifying that the Agent is Running

To verify that the Agent is running, look for its status in the control panel services or type net start at a command prompt. OracleAgent should appear in the list of running services.

You may also view the NT Task Manager to see the dbsnmp process information.

Creating a Windows NT User Account for Running Jobs

In order for the Agent to execute jobs on a managed node

• an NT user account must exist that has the advanced user privilege, "logon as batch job." The privilege can be assigned to an existing local or domain user, or a new NT user.

• the preferred credentials for the node must be set for that user in the Oracle Enterprise Manager console. For more information on setting preferred credentials, see the Oracle Enterprise Manager Administrator's Guide.

• the user that starts the Agent must have read/write permissions to ORACLE_HOME\network directory as well as write permissions to the TEMP directory or the ORACLE_HOME directory.

• the user must have administrator privileges in order to start up and shut down Windows NT services, such as databases and listeners.

Please follow one of the procedures listed below.

Creating a New NT User Account

To create a new Windows NT user account on the local NT machine and grant the "log in as batch jobs" privilege to this user, perform the procedure below.

1. Select the User Manager from the Administrative Tools program group. See the Windows NT documentation for information on this tool.

2. Select New User from the User menu and check for the following:
   • The "User Must Change Password at the Next Logon" option box is not checked

   • "SYSTEM" or "system" is not used for the user name.

3. Under the Policies menu of the User Manager NT utility, select the User Rights option.

4. Check the "Show Advanced User Rights" box.

5. Select "Logon as a batch job" from the list of privileges.

6. Give the selected user this privilege.

Assigning Privileges to an Existing NT User Account

To assign privileges to an existing local user account, perform the following steps.

1. Choose the user on the User Manager panel and check for the following:
   • The "User Must Change Password at the Next Logon" option box should not be checked

   • "SYSTEM" or "system" is not used for the user name.

2. Under the Policies menu of the User Manager NT utility, select the User Rights option.

3. Check the "Show Advanced User Rights" box.

4. Select "Logon as a batch job" from the list of privileges.

5. Add the advanced user right to this user.

Creating a New Windows 2000 User Account

To create a new user account on the local Windows 2000 machine and grant the "log in as batch jobs" privilege to this user, perform the procedure below.

1. Control Panel-->Administrative Tools-->Local Security Policy-->LocalPolicies-->User Rights Assignment (On the right hand side, highlight "Log on as bacth job".

2. Right click on "Log on as batch job" and select Security.

3. Click on Add and select a user to add.

4. Click on Add after selecting user and click OK)

Configuring a Domain User as the Agent User

To configure a repository user as your Agent user, perform the following steps.

1. Under the Policies menu of the User Manager NT utility, select the User Rights option.

2. Check the "Show Advanced User Rights" box.

3. Select "Logon as a batch job" from the list of privileges.

4. Click the Add button.
   1. Fill in the "List Names From" field: (choose your domain)

   2. Click Show Users button.

   3. In the listbox, choose the domain user.

   4. Click Add.

   5. Click OK.

5. In the User Rights Policy window, click OK.

Configuring SNMP Windows NT and Windows 2000

The following procedure explains how to configure the SNMP master agent to support the sub agents on Windows NT and Windows 2000:

1. Go to the drive that contains your services file say

   x:\winnt\system32\drivers\etc\services.

   Change the snmp entries to:

   snmp 1161/udp

   snmp-trap 1162/udp

2. Go to the Peer SNMP Master Agent config file MASTER.CFG under the

   ORACLE_HOME\network\admin
   

   directory and edit the config file to add the following:

   1. A transport entry as follows:

      TRANSPORT ordinary SNMP
      OVER UDP SOCKET
      AT PORT 1161
      

   2. An entry to indicate the community and the machine (example: dlsun1000.us.oracle.com or an IP address) that should receive the snmp traps:

      COMMUNITY   public
      ALLOW ALL OPERATIONS
      USE NO ENCRYPTION
      
      MANAGER dlsun1000.us.oracle.com
      SEND ALL TRAPS
      WITH COMMUNITY PUBLIC
      

3. Start the Peer SNMP Master Agent and the encapsulator from the Services Panel in the Control Panel.

   Please note that the encapsulator is only needed when multiple sub-agents are installed and configured on the machine. The Peer SNMP Master Agent executable is ORACLE_HOME\bin\agent.exe and the encapsulator executable is ORACLE_HOME\bin\encaps.exe.

4. Start the sub-agent (Oracle Intelligent Agent) through the Services Panel under Control Panel. The sub-agent starts and registers itself with the master agent.

   The way to test Oracle's SNMP is by using a third party application which uses snmp to communicate with the Oracle SNMP master agent and query Oracle specific data.

Third party applications that support SNMP are listed in the Oracle SNMP Support Reference Guide

Controlling Operations of the UNIX Agent

The following procedures are used to control the operation of the Intelligent Agent on UNIX systems.

Running the root.sh Shell Script

After you have successfully installed the Agent, the Oracle Universal Installer prompts you to run root.sh.

root.sh, which is a shell script, updates/creates an oratab file. The oratab file is the file where the user will place references to all databases to be discovered by the Agent and controlled by the Oracle Enterprise Manager. For each database created, the entry is of the form: <SID>:<$ORACLE_HOME>:[Y/N]

The Agent is normally configured by root.sh as a setuid program. If root.sh was successful, the Agent will have been installed as setuid root so that the Agent can run jobs as the users whose name and password are given in the Preferred Credentials for that host.

The user who submits node jobs to the UNIX Agent should have read/write access to the Agent's ORACLE_HOME. If the root.sh does not have setuid set, then any job submitted to the Agent will run with the privileges of the user who owns the Agent executable (dbsnmp.exe). root.sh will force the user to set the preferred credentials at the Oracle Enterprise Manager Console for any job on the Agent.

Verifying that root.sh has been run successfully

To verify that root.sh had been run successfully, check the file permissions on dbsnmp.

1. Enter cd $ORACLE_HOME/bin

   This changes the directory to the $ORACLE_HOME/bin directory where the Agent executable resides.

2. Enter ls -al dbsnmp

   This lists all relevant details about dbsnmp.

The output of the ls -al command for dbsnmp should be in the form

-rwsr-s---   1 root     g651     1497980 Jun 12 21:04 dbsnmp

root is the owner. dbsnmp is the Agent executable. In this example, the name of the group is g651. If root is the owner and -rwsr-s--- are the permissions, then root.sh had been run successfully.

Starting and Stopping the Agent on UNIX Platforms

On UNIX, the agentctl utility is used to start and stop the Agent. In addition, dbsnmpwd is run. dbsnmpwd is a UNIX watchdog script that is responsible for automatically restarting the Intelligent Agent if the Agent goes down. This assures that the Agent is up an running at all times unless explicitly shut down.

The relevant agentctl commands are listed in the table below.

DBSNMPWD

Dbsnmpwd is UNIX watchdog script which ensures that dbsnmp (Intelligent Agent) process is always present on monitored targets. It restarts the agent when it exits abnormally i.e. exits with an unexpected return code.

The behavior of the watchdog script can be configured using the following environmental variables. These variable are contained within the script itself.

DBSNMP_WDLOGFILE - Logfile where startup messages are written. It defaults to $ORACLE_HOME/network/log/dbsnmp.nohup

DBSNMP_RESTART - To disable the automatic restart mechanism set this environmental variable to 0. Default is set to 1.

DBSNMP_MAX_ABNORMAL_EXIT / DBSNMP_TIME_DELTA - These two variables help the watchdog script to determine when it would be safe to assume that the agent is thrashing (the process of starting and immediately exiting because initial conditions to start the agent successfully are not met). The default values are 3 and 60 respectively. It means if the agent exits more than 3 times within 60 seconds then it would be safe to assume that the agent is thrashing and the watchdog would not restart it.

Configuring SNMP for UNIX

On UNIX systems, when you install the Oracle Intelligent Agent (IA), the SNMP files are also automatically. To configure SNMP:

1. Install the Intelligent Agent.

   Make sure there is no SNMP master agent already running (snmpd) on the

                ps -ef | grep snmp 
   

   If there is an snmpd (snmpd.cfddi on Solaris) process running, kill it.

2. cd $ORACLE_HOME/network/snmp/peer

3. Edit the config.master script with the IP address of the machine that is running the SNMP Console in the same directory, verify that a script start_peer exists.

4. su root

5. start_peer -a (starts the Master Peer agent, the encapsulator and the native SNMP daemon)

6. Exit from root

7. From the Enterprise Manager Console, register an event and check the box: "Enable Notifications to External Services (SNMP traps by Agent)". Traps will be sent to the SNMP Master Console for each EM event that triggers.

Third-party systems management applications use the SNMP Master Agent to communicate with the Intelligent Agent. The SNMP Master Agent and the Oracle Intelligent Agent must be configured correctly before the Oracle Intelligent Agent can communicate over SNMP to the Master Agent.

For the general procedures for configuring SNMP for Oracle databases and the Management Server, refer to the Oracle SNMP Support Reference Guide.

For more comprehensive configuration information, see the installation or configuration guide specific to your platform. SNMP configuration may differ depending on the platform.

Configuring the 9i Agent for Use with Multiple Network Cards (NIC)

As with version 8.1.7 of the Intelligent Agent, 9i Intelligent Agent users have three options to configure the Agent on a machine with multiple network cards. By default the Agent will bind to the primary NIC on its machine ('le0' on UNIX platforms and 'network0' on Windows NT platforms). The other two options are:

1. Ability to bind to a NIC specified by the user.

2. Ability to bind to all NICs on the machine. This option should not be used if it is not desirable to have the Agent listening on all NICs.

The Agent will also have the capability of discovering services (listeners etc.) that are listening on an ip address/NIC that's different from the ip address/NIC being used by the Agent.

Agent Behavior when Using Multiple Network Cards

1. If no Listening Address is Specified

   When no explicit listening address directives are in snmp_rw.ora, the Agent listens for connections via the Agent machine's primary network interface card.

2. If a listening IP Address is Specified

   When an explicit listening address is specified in snmp_rw.ora, the Agent listens for connections on only that address.

   To bind the 9i Intelligent Agent to a specific network interface card, other than the primary network card:

   1. Set the dbsnmp.hostname parameter.

      dbsnmp.hostname=<IPaddress of the network card>
      
      

   2. Start the Agent by entering the following at the command line.

      >agentctl start agent
      
      

3. If a hostname is Specified

   If the hostname is specified in snmp_rw.ora, the Agent listens for connections on all the machine's network interface cards.

   For pre-8.1.7 versions of the Agent (8.1.5 or higher) this is the default behavior of the Agent (since it is the default behavior of the network layer code used by the Agent) .

   To bind the 9i Intelligent Agent to all network interface cards on a host:

   1. Set the dbsnmp.hostname

      dbsnmp.hostname=<name of host>
      

   2. Start the Agent

4. A Windows NT FailSafe Configuration is Used

   In the Windows NT FailSafe configuration, the Agent listens for connections on the IP address stored in the NT registry for the FailSafe Agent

   The Agent discovers each target on a machine, regardless of which of the machine names or IP addresses is used in the target's configuration files.

Oracle Intelligent Agent and Oracle Names

If you are running Oracle Names on a machine managed by an Oracle Intelligent Agent, it is assumed that the databases have already been registered with a Names Server and their aliases are defined by the GLOBAL_DBNAME parameters in the listener.ora files.

The Intelligent Agent does not use Oracle Names to discover services it manages. It uses GLOBAL_DBNAME parameters in listener.ora files to determine which databases that listener services. This name appears in the Enterprise Manager Console Navigator as the database name to be managed.

The GLOBAL_DBNAME parameter typically describes the name of the database as it is registered with the Names Server, for example, the name and domain of the database as given in the database initialization parameter file. Values of the GLOBAL_DBNAME parameters must be unique.

When running jobs or monitoring events in this environment, the Intelligent Agent does not resolve database aliases via Oracle Names, the Agent will generate its own TNS connect string using the Bequeath Protocol.

Roles and Users Required by the Intelligent Agent

The default database username/password for the Agent is dbsnmp/dbsnmp. The catsnmp.sql script is installed with the database. The database roles and privileges assigned to the Agent user using the catsnmp.sql script. When an Oracle database is installed, the catsnmp.sql script is automatically run by catalog.sql

The customer may need to change the user/password for the Intelligent Agent's database logon. To change the user name and password to something other than dbsnmp/dbsnmp, you need to edit snmp_rw.ora, adding the following parameters:

snmp.connect.<svcname>.name = <username>
snmp.connect.<svcname>.password = <password> 

To grant the requisite roles and users privileges to the new Agent user, run the SQL commands specified in catsnmp.sql referring to the new Agent user. You can use Server Manager or SQL Plus. Do not edit the catsnmp.sql script for this purpose.

To determine whether the SNMPAGENT role exists in a database, enter the following SQL command:

SELECT * FROM dba_roles;

If the SNMPAGENT role does not appear, run the catsnmp.sql script on the database.

If you already have several versions of the database running, you must run the catsnmp.sql script on each of these database in order to have the correct setup for all the grants and views the Agent needs to contact.

To run the script, you must log in as SYS or INTERNAL.

Auto-Discovery

The Intelligent Agent has a built-in auto-discovery feature that automatically generates the needed configuration files containing information about services to be managed, each time the process is started. The following three files are created/appended during the discovery process:

• $ORACLE_HOME/network/admin/snmp_ro.ora

  The snmp_ro.ora file is a read-only file created by the Agent and contains information on services monitored by the Agent.

• $ORACLE_HOME/network/admin/snmp_rw.ora

  The snmp_rw.ora file contains index information of the managed services used internally by the Agent and it also allows users to specify variables, such as tracing.

• $ORACLE_HOME/network/agent/services.ora

  The services.ora file contains aliases for all services the Agent has to monitor. Only services listed in this file are monitored by the Agent. The content of this file are then sent to the console during discovery. With version 9.0, this file also contains information about the type of operating system and the operating system version of the environment in which the Agent is running.

When the Agent is started, the auto-discovery process reads configuration parameters from the following sources:

• oratab (on Unix nodes)

• Windows NT Registry (on Windows NT nodes)

• listener.ora

• tnsnames.ora (if one exists)

The discovery process extracts the services installed on that node and compiles the configuration files listed previously.

The Agent compiles SID information for each ORACLE_HOME, either from the ORATAB file (UNIX) or the NT registry. The Agent then parses the listener.ora files for related SID and listener information. If the listener.ora contains a GLOBAL_DBNAME section, the Agent sets the database service name to the GLOBAL_DBNAME variable. If the variable does not exist, the Agent looks for a tnsnames.ora that contains a valid service name for the SIDs on that machine. If the Agent cannot find one, a service name called <SID>_<HOSTNAME> is created for each SID.

Pre-requisites for Auto-Discovery

• SQL*Net V2 or Oracle Net TCP/IP must be present, and the necessary files must be created, prior to launching the Intelligent Agent. The only required SQL*Net (or Oracle Net) file is listener.ora, but tnsnames.ora and sqlnet.ora should be configured correctly for particular service discovery. The Agent searches for these files in the $ORACLE_HOME/network/admin directory.

• TNS_ADMIN variable usage during Agent Discovery:

  (UNIX) All versions of the Unix discovery script allow the use of the TNS_ADMIN variable to locate input configuration files (listener.ora and tnsnames.ora). Only post-8.0.3/7.3.4 versions correctly write the output files (snmp_ro.ora and snmp_rw.ora) into TNS_ADMIN, if this environment variable is set. If the TNS_ADMIN variable is not set, then the Agent will write the output files to its $ORACLE_HOME/network/admin directory.

  (NT) In addition to the above, beginning with 8.0.5, the discovery script also reads the TNS_ADMIN value from the NT Registry. This variable is located as follows:

  • (NT) TNS_ADMIN variable in Control Panel -> System -> Environment

  • (NT) TNS_ADMIN key in the NT Registry

Service Discovery Process

When you start the Agent, the first operation it must perform is to discover what services exist on the node that it monitors. The following "discovery" algorithms document the service discovery process for the two most common platforms on which the Agent runs.

Agent Discovery Process for NT

At Intelligent Agent startup, a script is executed which reads configuration parameters from the Windows NT registry, the listener.ora file, and the tnsnames.ora file (if it exists).

The Agent discovers new services on the machine where it is installed and creates/rewrites/appends to its configuration files: snmp_ro.ora, snmp_rw.ora, and services.ora.

To determine what services are available on its machine (services that the Agent will manage), the Agent uses the following discovery algorithm:

1. The Agent records the ORACLE_SID and ORACLE_HOME information for each database service found in the Windows NT Registry.

2. Based on the values found in the Windows NT registry, the Agent reads the listener.ora files to determine which listeners service which databases. The location of the listener.ora configuration files is based on the SQL*Net configuration file locations. For example, the TNS_ADMIN environment variable and the location of the $ORACLE_HOME/network/admin directory are based on the ORACLE_HOME information found in the Windows NT registry.

3. The name of the discovered databases is based on the GLOBAL_DBNAME parameter defined in the listener.ora file for that database.

4. If GLOBAL_DBNAME parameters are not found in listener.ora, the Agent searches for a tnsnames.ora file using the same search methodology used to find the listener.ora file.

5. If the tnsnames.ora file is not found, the database alias, <SID>_<hostnames>, is assigned to a database service. The service will be known to the Agent by this alias, and it will be visible as such at the Oracle Enterprise Manager Console.

Agent Discovery Process for UNIX

At startup, the Agent discovers new services on the machine where it is installed and creates its configuration files: snmp_ro.ora, snmp_rw.ora, and services.ora.

To determine what services are available on its machine (services that the Agent will manage), the Agent uses the following discovery algorithm

1. The Agent reads the oratab file for values of all the Oracle Homes and SIDs. Depending on the platform, the oratab file can be located in either of the following locations:
   • /etc

   • /var/opt/oracle

2. The Agent searches for the listener.ora file:
   • If the tns_admin environment variable is set, the Agent searches for the listener.ora file in this directory

   • If the tns_admin environment variable is not set, the Agent searches for the listener.ora file in /etc or /var/opt/oracle

   • If neither directory (/etc or /var/opt/oracle) exists, the agent searches for the listener.ora file in the /network/admin directories of the ORACLE_HOMEs listed in oratab file.

3. The name of the discovered databases is based on the GLOBAL_DBNAME parameter defined in the listener.ora file for that database.

4. If GLOBAL_DBNAME parameters are not found in listener.ora, the Agent searches for a tnsnames.ora file using the same search methodology used to find the listener.ora file.

5. If the tnsnames.ora file is not found, the database alias, <SID>_<hostnames>, is assigned to a database service. The service will be known to the Agent by this alias, and it will be visible as such at the Oracle Enterprise Manager Console.

Upgrading from 8.0.6/8.1.6/8.1.7 Intelligent Agents to 9.0

Each release of the Intelligent Agent improves Agent performance, functionality, and reliability. We therefore recommend upgrading your Intelligent Agent to the latest version available for your platform. To make sure the transition to a newer Agent preserves your existing Enterprise Manager jobs, events, and data collections, you can use the NMUMIGR8 utility found in $ORACLE_HOME/bin. This utility allows you to migrate existing jobs, events, and data collections to a format recognized by 9.0 version of the Intelligent Agent.

Usage:

nmumigr8 [-source_home <source ORACLE_HOME>] [-password <password>] [-verbose]

Parameters

-source_home

Source Oracle Home that contains an existing Intelligent Agent queue and data collection files. If source_home is not supplied then the value defaults to the destination Oracle Home that is the value of the ORACLE_HOME environment variable.

-password

A password used by the Intelligent Agent to encrypt its queue files. If not supplied, the default encryption password is used.

-verbose

This flag indicates that detailed migration information should be written to the trace file nmumigr8.trc located under the Agent's ORACLE_HOME/network/trace directory. If this flag is not set, only summary information is written to the trace file.

Users upgrading from earlier versions of the Intelligent Agent to the version 9.0 Intelligent Agent should follow the guidelines described in the next section.

Intelligent Agent Upgrade Guidelines

1. Install the latest Intelligent Agent under a new Oracle Home.

2. Make sure that any jobs or events you wish to keep have been saved in the job or event library respectively. To add a job/event to a job/event library, select the job/event from the job/event pane, click on the desired entry using the right mouse button and select Copy to Library from the context-sensitive menu.

3. Move any event alerts to event history. You can save the contents of the history pane or clear them.

4. From the Enterprise Manager Console, de-register any existing events and remove any active jobs scheduled against the node on which you ar upgrading the agent.

5. Shut down the old Agent.

6. Start the new Agent

7. From the OEM Console, refresh the node in the Navigator.

8. Resubmit the saved jobs and events to the new Agent.