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

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\NET80 directory as well as write permissions to the TEMP directory or the ORACLE_HOME directory.

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.

Select the User Manager from the Administrative Tools program group. See the Windows NT documentation for information on this tool.
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.
Under the Policies menu of the User Manager NT utility, select the User Rights option.
Check the "Show Advanced User Rights" box.
Select "Logon as a batch job" from the list of privileges.
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.

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.
Under the Policies menu of the User Manager NT utility, select the User Rights option.
Check the "Show Advanced User Rights" box.
Select "Logon as a batch job" from the list of privileges.
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.

Under the Policies menu of the User Manager NT utility, select the User Rights option.
Check the "Show Advanced User Rights" box.
Select "Logon as a batch job" from the list of privileges.
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.
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:

Double-click the Services icon in the Control Panel folder.
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.
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:

Double-click the Services icon in the Control Panel folder.
Select the OracleAgent service.
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.

Enter cd $ORACLE_HOME/bin

This changes the directory to the $ORACLE_HOME/bin directory where the agent executable resides.
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

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:

$ORACLE_HOME/network/admin/snmp_ro.ora

$ORACLE_HOME/network/admin/snmp_rw.ora

$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.

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.

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

An example of snmp_ro.ora from an 8.0.3 Agent on NT:

        snmp.visibleservices = (LISTENER, sanfran.us.oracle.com) 
        snmp.shortname.LISTENER = LISTENER 
        snmp.longname.LISTENER = LISTENER_HOTATE 
        snmp.configfile.LISTENER = C:\ORANT\Net80\admin istener.ora 
        snmp.SID.sanfran.us.oracle.com = ORCL 
        snmp.oraclehome.sanfran.us.oracle.com = C:\ORANT 
        snmp.address.sanfran.us.oracle.com = (DESCRIPTION =(ADDRESS_LIST 
=(ADDRESS
        =(COMMUNITY = TCP.world)(PROTOCOL = TCP)(Host = 
hotate.us.oracle.com)(Port =
        1526)))(CONNECT_DATA =(SID = ORCL)(GLOBAL_NAME = 
sanfran.us.oracle.com))) 
        ifile = C:\ORANT\net80\admin mp_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.

An example of snmp_rw.ora from a 8.0.3 Agent on NT:

        snmp.contact.LISTENER = "" 
        snmp.index.LISTENER = 1 
        snmp.contact.sanfran.us.oracle.com = "" 
        snmp.index.sanfran.us.oracle.com = 2

For more information about enabling tracing, refer to Tracing the Intelligent Agent

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 following directories and order:

1. $(if such an environment variable exists for the user starting the Agent)

1a. (NT) TNS_ADMIN variable in Control Panel -> System -> Environment

1b. (NT) TNS_ADMIN key in the NT Registry

2. on UNIX systems, in the /etc or /var/opt/oracle

3. $ORACLE_HOME/network/admin

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 it is set.

(NT) In addition to the above, beginning with 8.0.5, the discovery script also reads the TNS_ADMIN value from the NT Registry.

2 Installation and Configuration