2
Installation and Configuration

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

• Installing the Intelligent Agent on Windows NT

• Controlling Operations of the NT Agent

• Installing the Oracle Intelligent Agent on UNIX

• Configuring SNMP for UNIX or Windows NT

• Oracle Intelligent Agent and Oracle Names

• Roles and Users Required by the Agent

• Auto-Discovery

Installing the Intelligent Agent on Windows NT

Intelligent Agents are shipped with the database and installed on remote, managed machines under an ORACLE_HOME environment. The Agent runs as a service.

The convention used to construct the service name is:

Oracle<ORACLE_HOME_NAME>Agent

where ORACLE_HOME_NAME is the name of the ORACLE_HOME you specified during installation.

For more information on installing the Intelligent Agent, please refer to the Oracle Enterprise Manager Installation (CD-ROM insert).

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.

Configuring a Domain User as Your 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.

5. Fill in the "List Names From" field: (choose your domain)

6. Click Show Users button.

7. In the listbox, choose the domain user.

8. Click Add.

9. Click OK.

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

Controlling Operations of the NT Agent

This section contains information on controlling the Agent through Windows NT and the DOS prompt. It also contains a section on troubleshooting the Agent.

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.

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.

Installing the Oracle Intelligent Agent on UNIX

Install the Oracle Intelligent Agent from the Oracle CD-ROM as per the Oracle Enterprise Manager Installation Guide. The Intelligent Agent is a separate component to select.

Running the root.sh Shell Script

After you have successfully installed the Agent, the Oracle 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.

If the Agent is not a setuid program, all Enterprise Manager jobs are run with the permissions of the user who started the Agent.

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-xr-x   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-xr-x are the permissions, then root.sh had been run successfully.

Controlling Operations of the UNIX Agent

On UNIX, the lsnrctl command is used to start and stop the Agent. The relevant lsnrctl commands are listed in the table below.

If you want to...	Enter the command...
Start the Agent on UNIX platforms	lsnrctl dbsnmp_start
Stop the Agent on the UNIX platform	lsnrctl dbsnmp_stop
Verify status of the Agent	lsnrctl dbsnmp_status

For additional information or restrictions for your platform, see the Intelligent Agent readme in ORACLE_HOME/network/agent/doc/readme.wri.

Configuring SNMP for UNIX or Windows NT

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 since the SNMP configuration differs from platform to platform.

Configuring the Version 8.1.7 Agent for Use with Multiple Network Cards

Beginning with version 8.1.7 of the Intelligent Agent, users will 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. 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.

Also please note that similar options will apply to the Agent Data Gatherer.

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.

When a node running an Intelligent Agent has multiple network cards, each with its own IP address, the Intelligent Agent can listen and accept incoming requests on the primary network interface, on a specific IP address, or on any of the multiple IP addresses, depending on the Intelligent Agent configuration parameters.

Agent Behavior when Using Multiple Network Cards

1. No Listening Address is Specified

   By default, the Agent listens for connections on the primary network interface card of the Agent machine. 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. 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. The existing parameters dbsnmp.address and dbsnmp.spawnaddress are used to specify the Agent listening address.

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

   1. Set the dbsnmp.address and dbsnmp.spawnaddress parameters to "HOST=<IP address of the network card>" (refer to Appendix A for more information)

   2. Start the Agent

3. 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. The existing parameters dbsnmp.address and dbsnmp.spawnaddress are used to specify hostname in the Intelligent Agent listening address.

   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 Agent to all network interface cards on a host:

   1. Set the dbsnmp.address....with "HOST=<name of the 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.

5. Configuring the Data Gatherer to Use Multiple Network Cards

For the Data Gatherer the parameter is vpp.node_address. This parameter should be specified in the SQLNET.ORA file located in the /ORACLE_HOME/network/admin directory, or the directory specified by the TNS_ADMIN environment variable.

By default the Data Gatherer binds to the primary network card. To use a network card other than primary card, set vpp.node_address to the IP address of the network card. To bind the Data Gatherer to all network cards, set vpp.node_address to the hostname.

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 8.0.4 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 Agent

The necessary dbsnmp user account (with password "dbsnmp") and the SNMPAGENT role for the Intelligent Agent is contained in catsnmp.sql. The catsnmp.sql script is installed with the database. When an Oracle database is installed, the catsnmp.sql script is automatically run by catalog.sql

For security reasons, the customer may need to change the user/password for the Intelligent Agent's database logon. The default account is dbsnmp and the default password is dbsnmp. To change the user name and password to something other than dbsnmp/dbsnmp, you need to open, edit, and rerun catsnmp.sql for your own user and password. You will then need to edit snmp_rw.ora, adding the following parameters:

SNMP.CONNECT.<svcname>.NAME = <USERNAME>
SNMP.CONNECT.<svcname>.PASSWORD = <password> 

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

Beginning with 7.3.3, 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.

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.

Beginning with 7.3.4 and 8.0.3, 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 Net80 TCP/IP must be present, and the necessary files must be created, prior to launching the Intelligent Agent. The only required SQL*Net (or Net8) 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 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. Based on the Oracle Homes values found in oratab, the Agent searches for the listener.ora files to determine which databases are serviced by which listeners.

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 the Intelligent Agent

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. As an integral part of your Enterprise Manager environment, certain steps must be followed to make sure the transition to a newer Agent does not affect your Enterprise Manager jobs and/or events.

Agent Upgrade Guidelines for Enterprise Manager Version 2

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.

Migrating Enterprise Manager Jobs/Events from an 8.1.5 or 8.1.6 Agent to an 8.1.7 Agent

If you have existing jobs/events submitted against an 8.1.5/8.1.6 Intelligent Agent, and want to upgrade to an 8.1.7 Agent without having to re-submit jobs or re-register events, you must migrate all existing jobs/events using the following procedure.

1. Install the 8.1.7 Agent in a separate ORACLE_HOME.

2. Type lsnrctl dbsnmp_stop at the command line to stop the older 8.1.x Agent.

3. Copy all files ( *.q files, *.inp files, tcl* files) from the older Agent's ORACLE_HOME/network/agent directory to the 8.1.7 Agent's ORACLE_HOME/network/agent directory. Do not copy the directories. These files should now be owned by the user who installed the 8.1.7 Agent. Check the ownership of these files in the newer Agent's directory.

4. Type lsnrctl dbsnmp_start to start the 8.1.7 Agent.

5. Make sure that the services (databases, listeners etc.) discovered by the new Agent are identical to those discovered by the older Agent.

   A quick comparative check between service names and definitions in the older Agent's ORACLE_HOME/network/agent/services.ora file and that of the newer Agent, is highly recommended.

6. From the Enterprise Manager Console, refresh the Agent's node.

After migration, all previous jobs/events should continue to run as before.

Configuring the Data Gatherer

The Data Gatherer, which collects performance data used by the Oracle Capacity Planner and the new Java-based Oracle Performance Manager, is installed along with the Intelligent Agent. You must configure the Oracle Data Gatherer after it is installed on a host.

The Oracle Data Gatherer, by default, tries to use the username/password account set up as the preferred credentials for the database to locate the Data Gatherer. If the preferred credentials are incorrect or if the Data Gatherer is not located on that host the client will prompt you for the location of the Data Gatherer.

You may want to set up the preferred credentials for the database before starting the client applications (Performance Manager and Capacity Planner).

The TNSNAMES.ORA file on the host where the Oracle Data Gatherer is installed must include entries for:

• the target database

• the repository for Oracle Capacity Planner and Oracle Performance Manager. The repository location was defined using the Oracle Configuration Assistant.

Upgrading From a Previous Version of the Data Gatherer when You Install the New Data Gatherer into a Different Oracle Home

It is possible to install the new version of the Oracle Data Gatherer into a different Oracle Home than the previous version. If you plan to do this, follow these steps:

1. Stop the previous version of the Oracle Data Gatherer. See Controlling Operations of the NT and UNIX Data Gathering Service on page 2-21 for more information on stopping the Oracle Data Gatherer.

2. Install the new version of the Oracle Data Gatherer, but do not start it.

3. Move the Capacity Planning configuration files (state files) and data files associated with the previous version of Oracle Data Gatherer to the Oracle Home where you have installed the new version of Oracle Data Gatherer.

   The Oracle Data Gatherer state and data files are located in the $ORACLE_HOME/odg/reco directory. You need to copy the files into the new $ORACLE_HOME/odg/reco directory before you use Oracle Capacity Planner to connect to the new version of the Oracle Data Gatherer and set up any new collections.

   If you do not move these files, the following problems will occur:

   1. Binary data is not loaded.

      Any binary data files created by Oracle Data Gatherer which have not yet been loaded into the Capacity Planner database will not be loaded.

   2. Data collection definitions are not maintained.

      You will need to redefine your Capacity Planner data collections.

   If you have installed the new version of Oracle Data Gatherer into the same Oracle Home as the previous version or if you do not currently use the Oracle Capacity Planner, do not move the state and data files.

4. Start the new version of the Oracle Data Gatherer. See Controlling Operations of the NT and UNIX Data Gathering Service on page 2-21 for more information about starting the Oracle Data Gatherer.

Migrating Collection Data to Agent Data Gatherer Version 8.1.7

The utility NMUMIGRATE allows you to migrate existing database collections being performed by an existing Agent Data Gatherer to the new format recognized by the 8.1.7 Agent Data Gatherer. This is the migration from the pre-8.1.7 ODB cartridge to the new DBA cartridge. The new DBA cartridge provides performance and collection enhancements.

Check the following prior to migrating collection data:

• Install the 8.1.7 Intelligent Agent.

• Make sure that the ORACLE_HOME environment variable is set to the ORACLE_HOME of the 8.1.7 Intelligent Agent.

• Make sure that no Data Gatherer is running.

Type the following at the command prompt:

nmumigrate <old ORACLE_HOME>

This utility gets installed under the 8.1.7 ORACLE_HOME/bin directory and will migrate the database collections in the old ORACLE_HOME to the new format recognized by the 8.1.7 Agent Data Gatherer in the new ORACLE_HOME. It will create new collection state files in this new ORACLE_HOME. The utility will use the ORACLE_HOME environment variable to obtain the new ORACLE_HOME. If the user has upgraded to the 8.1.7 Agent Data Gatherer within the old ORACLE_HOME, then the user need not specify the ORACLE_HOME when running this utility. For collection cartridges other than the database collection cartridge, the utility will check if the cartridge is installed in the 8.1.7 ORACLE_HOME and if so, it will copy corresponding collection files from the old ORACLE_HOME to the 8.1.7 ORACLE_HOME.

After performing the migration, check the 8.1.7 ORACLE_HOME/odg/log/migration.log file for migration details.

AFTER MIGRATION

You can check the $ORACLE_HOME/odg/log/migration.log file for explicit details of the migration.

How the NMUMIGRATE Utility Works

NMUMIGRATE performs the following tasks during the migration:

1. Check that the Data Gatherer is not running. If the Data Gatherer is running, NMUMIGRATE cannot access the state file which Data Gatherer is writing to.

2. Get $ORACLE_HOME from your current ORACLE_HOME setting

3. Read the message catalog file

   $ORACLE_HOME/odg/mesg/vpxodbus.msb
   $ORACLE_HOME/odg/mesg/vpxdbaus.msb
   

4. Create/Append a log file to record what is being migrated.

   $ORACLE_HOME/odg/log/migration.log
   

5. Get a list of state files need to be migrated from

   $OLD_ORACLE_HOME/odg/reco
   

directory, these files will begin with 'S' or 'R'

vppdc -console -debug

vppdc -console -debug > trace.txt