Oracle Intelligent Agent User's Guide
Release 8.1.6

A75686-01

Library

Product

Contents

Index

Prev Next

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

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


Note:

If you do not set up the "logon as batch job" privilege, you will receive the "Failed to authenticate user" message when you run jobs on the node. 


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


Note:

Domain users are not supported with 7.3.3 and earlier versions of the Agent. 


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.

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


Note:

If you have both a local and a domain user with the same name, the local user takes precedence. 


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.


Note:

Oracle Enterprise Manager and the Agent use Net8 to communicate with the databases in question. Please verify that Net8 can connect to every SID in question before attempting to use 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.


Note:

You can also start the Agent from the command line by typing the following:

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.

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.


Note:

The Agent being set to setuid root does not have the same effect as having the root user start the Agent. Having the root user start the Agent may cause security problems. Consult your platform documentation for exact details on setuid programs. 


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.


Note:

Please be aware that only one intelligent Agent can be run on one UNIX machine although more than one Oracle Home can exist. The Agent communicates with the Management server on a dedicated port (1748). 


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.

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.


Note:

If you are planning to manage two or more Oracle databases on the same node, make sure the GLOBAL_DBNAME parameter in your listener.ora file is different for each database. 


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.


Note:

The location of catsnmp.sql varies based on the database version you are running and the platform. For example, on NT for an Oracle 8.x database, the script is located at

ORACLE_HOME\rdbms8x\admin. Please note that there is no harm in running the catsnmp.sql script more than once.  


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:


Note:

Please refer to Appendix A, "Configuration Files" for more information on parameters used in these files. 


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

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.


Note:

In 7.3.3 and earlier versions, the Agent does not use the GLOBAL_DBNAME. 



Note:

If multiple aliases exist for the same instance in the tnsnames.ora, the Agent uses the one listed first. If you prefer to use a different alias, reorder the tnsnames.ora entries and restart the Agent.  



Note:

If you have more than one database instance on a machine and you are using GLOBAL_DBNAME parameter in the listener.ora file, these instances need to have a unique GLOBAL_DBNAME in the listener.ora. You may have to do edit the listener.ora manually.  


Pre-requisites for Auto-Discovery

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.


Note:

If multiple aliases exist for the same instance in the TNSNAMES.ORA file, the Agent will use the one listed first. If you prefer to use a different alias, re-order the TNSNAMES.ORA file entries and restart the Agent.

If a database or any other new service is installed on the node where the Agent resides, the Agent must be restarted to add the new service to the Agent configuration files. This procedure also applies to UNIX versions of the Intelligent Agent. 


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 V2

  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.


Note:

If you have events registered against multiple targets, use the Create Like menu option to create individual events for each target and save these events to the the Event Library. 


  1. From the Enterprise Manager Console, deregister any existing events and remove any active jobs scheduled against the node on which you ar upgrading the agent.

  2. Shut down the old Agent.

  3. Start the new Agent

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

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

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 reprompt 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:


Note:

If you are not using either the Oracle Capacity Planner or the Oracle Performance Manager, you do not need to configure or start the Oracle Data Gatherer. 


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-16 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-16 for more information about starting the Oracle Data Gatherer.

Controlling Operations of the NT and UNIX Data Gathering Service

On UNIX and NT, Oracle Enterprise Manager uses the vppcntl command to manage the data gathering service. The vppcntl executable is located in ORACLE_HOME/bin.

Commands to control Oracle Data Gatherer are listed in the table below:

If you want to...  Enter the command... 

Start Oracle Data Gatherer 

vppcntl -start 

Stop Oracle Data Gatherer 

vppcntl -stop 

Verify that Oracle Data Gatherer is running 

vppcntl -ping 

Identify the version of Oracle Data Gatherer 

vppcntl -version 


Note:

You can only run one version of the Data Gatherer on a host at a time; therefore, you do not need more than one Data Gatherer on a host. It is recommended that you deinstall the previous version of the Data Gatherer. If you try to start more than one Data Gatherer on a host, you will get an error. 


Oracle Enterprise Manager Versions  Data Gatherer Version 

Enterprise Manager 1.5.5 and 1.6.0 clients 

Runs with 8.0.4 and 8.0.5 Data Gatherer

Does not run with 8.1.5 Data Gatherer  

Data Gatherer 2.0.4 clients 

Runs with 8.0.4, 8.0.5, or 8.1.5 Data Gatherer 

Additional Methods for Controlling Operations on Windows NT

This section contains information on controlling the Oracle Data Gatherer through Windows NT.

By default, you start the Oracle Data Gatherer manually on a host. To start Oracle Data Gatherer automatically through the Control Panel on Windows NT, perform the following steps:

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

  2. Select the name of the Oracle Data Gatherer service you want to start.

    If the host has one Oracle Home, then the name of the Oracle Data Gatherer service is OracleDataGatherer.

    If the host has multiple Oracle Homes and the Oracle Data Gatherer has been installed into more than one Oracle Home, then multiple data gatherer services are displayed. When the Oracle Data Gatherer is installed into multiple Oracle Homes, the names of the data gathering services use the naming convention Oracle<Oracle_Home_name>DataGatherer. For example, suppose a host has two Oracle Homes, named 804 and 805, and the data gathering service has been installed both homes. The Oracle Data Gathering services for those Oracle Homes are named Oracle804DataGatherer and Oracle805DataGatherer, respectively.

    The Startup Type is set to Manual, which allows the data gathering service to be started by a user. If you want Oracle Data Gatherer to start automatically whenever you start the system, set the Startup Type for 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 data gathering service.

To stop Oracle Data Gatherer through the Control Panel on Windows NT, perform the following steps:

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

  2. Select the name of the Oracle Data Gatherer service that you want to stop.

  3. Click the Stop push-button to stop the data gathering service.

Verify Data Gathering Service is Running

On Windows NT, there are several ways to determine if the Oracle Data Gatherer is running by checking the:

Oracle recommends that you use the vppcntl -ping command because it tells you if the Oracle Data Gatherer is running and also performs a test to determine whether it is responsive and running properly.

The data gathering service's alert/warning log is ORACLE_HOME\odg\bin\alert_dg.log.

On UNIX, use vppcntl -ping to verify if Oracle Data Gatherer is running. The data gathering service's alert/warning log is $ORACLE_HOME/odg/bin/alert_dg.log.

Obtaining Trace Information on the Oracle Data Gatherer

You can also obtain trace information on the Oracle Data Gatherer. To obtain this information, you must run the Oracle Data Gatherer from the Oracle Enterprise Manager console.

To view the Oracle Data Gatherer trace information on the screen, type the following command at the DOS prompt or UNIX command line:

vppdc -console -debug

To send the Oracle Data Gatherer trace information to a file, type the following command at the DOS prompt or UNIX command line:

vppdc -console -debug > trace.txt

If the above command is used, the trace file is named trace.txt. If you prefer, you can specify a different name for the trace file.


Note:

If you want to run the Data Gatherer in debug mode and a Data Gatherer is already running, you must stop the Data Gatherer, and then run it from the command line as shown above using the -debug flag. 



Prev Next
Oracle
Copyright © 2000 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index