|Oracle Intelligent Agent Users Guide
This chapter covers generic setup and configuration procedures for the Intelligent Agent. The following topics are discussed:
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:
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).
In order for the agent to execute jobs on a managed node
ORACLE_HOME\NET80directory as well as write permissions to the
TEMPdirectory or the
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.
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.
To assign privileges to an existing local user account, perform the following steps.
To configure a repository user as your agent user, perform the following steps.
If you have both a local and a domain user with the same name, the local user takes precedence.
This section contains information on controlling the agent through Windows NT and the DOS prompt. It also contains a section on troubleshooting the agent.
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.
To start the agent on Windows NT, perform the following steps:
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.
You can also start the agent from the command line by typing the following:
To stop the agent on Windows NT, perform the following steps:
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.
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.
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:
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 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.
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).
To verify that root.sh had been run successfully, check the file permissions on dbsnmp.
This changes the directory to the $ORACLE_HOME/bin directory where the agent executable resides.
This lists all relevant details about dbsnmp.
The output of the ls -al command for dbsnmp should be in the form
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.
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
Stop the agent on the UNIX platform
Verify status of the agent
For additional information or restrictions for your platform, see the Intelligent Agent readme in
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.
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.
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.
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:
To determine whether the SNMPAGENT role exists in a database, enter the following SQL command:
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.
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:
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.
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
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
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
(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.