Oracle Intelligent Agent Release 9.2.0



  1. Installing the Intelligent Agent
  2. Controlling Operations of the UNIX Agent
  3. Configuring SNMP for UNIX
  4. Configuring the 9i Agent for Use with Multiple Network Cards (NIC)
  5. Agent Behavior when Using Multiple Network Cards
  6. Oracle Intelligent Agent and Oracle Names
  7. Roles and Users Required by the Intelligent Agent
  8. Auto-Discovery
  9. Service Discovery Process
  10. Upgrading from 8.0.6/8.1.6/8.1.7 Intelligent Agents to 9.x


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

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


Running the Shell Script

After you have successfully installed the Agent, the Oracle Universal Installer prompts you to run, 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 as a setuid program. If 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 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 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). will force the user to set the preferred credentials at the Oracle Enterprise Manager Console for any job on the Agent.


Verifying that has been run successfully

To verify that 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 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.

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

Start the Agent and dbsnmpwd.

agentctl start agent

Stop the Agent and dbsnmpwd.

agentctl stop agent

Verify status of the Agent

agentctl status agent

Restart (bounce) the Agent.

agentctl retart agent



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.

Environmental variables should not be set within the snmp_rw.ora file.

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_ABNORMALEXIT / 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.



Blackouts allow Enterprise Manager users to suspend any or all management and/or data collection activity on one or more managed targets. This capability permits maintenance or emergency operations to be performed

Specifically, blackouts can suspend:

Events All events registered on a target will not be evaluated or triggered for the duration of the blackout.
Jobs All jobs submitted to a target will not be scheduled or run for the duration of the blackout. Job skipped notifications will be sent to the Enterprise Manager Console for regular interval jobs scheduled during a blackout on a target.
Data Collections All current historical data collection activities for a target are stopped. However, loading of data collected for a target prior to the blackout will continue as long as the database is up. New collections can be submitted but will not proceed unless the blackout ends.


Defining Blackouts

Blackouts must be created at the target-level, i.e., they must be defined on the node where the Intelligent Agent resides. Blackouts are controlled with a command line interface. The blackout subsytem associates any command line request with a special type of Agent user called the CLI user. Only one immediate blackout can be set at a time. Multiple target blackouts can exists simultaneously.

Once in effect, blackouts cannot be modified. To change the status of a particular blackout, first delete the existing blackout and then re-create a new blackout with the desired changes.

A blackout can only be cancelled by the user who originally set it.


Blackout Command Line Interface

The blackout command line tool exists on the node where the Agent resides and can be used by administrators to set/cancel blackouts. The Intelligent Agent must be running in order to set a blackout. User commands are as follows:


Blackout Commands

Action Command
Define agentctl start blackout [-d [DD] HH:MM] [target_name]
Remove agentctl stop blackout [target_name]
Display status agentctl show blackout


Command Line Examples

The following examples illustrate how to use the blackout command line utility under different situations and the output generated.

Situation 1: You want to start a blackout on the target for 10 minutes.

$ agentctl start blackout -d 0:10
Blackout registered on database

Situation 2: You want to stop any blackout set by (the CLI user) effective on target Blackouts set by other Agent users are not cancelled.

$ agentctl stop blackout
Blackout canceled on database

Situation 3: You want to start blackouts on all managed targets for an indefinite length of time. This is equivalent to blacking out the entire Agent.

$ agentctl start blackout
Do you wish to blackout the entire agent (Y/N) ? [N] y
All targets on the agent are blacked out.

Situation 4: You want to stop blackouts on all registered targets.

$ agentctl stop blackout
Do you wish to cancel blackout on all targets (Y/N) ? [N] y
Blackout canceled on all targets.

Situation 5: You want to know the status of blackouts on a target.

$ agentctl status blackout is blacked out. Blackout will end in 2 hours.

Situation 6: You want to set a blackout on a target whose name matches another target of a different type. In this case, the command line interface allows you to interactively select the desired target.

$ agentctl start blackout payroll 
Following targets matching "payroll" have been found.
1.  payRoll ( Database )
2.  payRoll ( Listener )
Choose the target to blackout [1] : 2
Blackout registered on "payroll" listener


Configuring SNMP for UNIX

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

    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, stop it.

  1. cd $ORACLE_HOME/network/snmp/peer

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

  3. su root

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

  5. Exit from root

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

    • The SNMP configuration differs from platform to platform, check the platform documentation (the Installation and
    • Configuration Guides usually have this information)
    • Some UNIX platform do NOT offer SNMP support; check the platform documentation

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

The Agent binds to an ip address and uses that address, to listen for all incoming requests for executing EM jobs, events, and data collection requests.

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

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.


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


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


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.

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 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: = 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, 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, log in as SYS or INTERNAL.



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.

The Agent compiles SID information for each ORACLE_HOME, either from the ORATAB file. 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.

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.

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

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

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

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

    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.

    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.


Real Application Cluster Environments

In Real Application Cluster environments, multiple instances of the Intelligent Agent (one per node) must share a single ORACLE_HOME. In order to support this, we need to allow files written by the agent (queue files, logs and traces, CS recovery files, config files) to be placed in an alternate directory, outside the ORACLE_HOME.

The following transaction supports an environment variable,

ORA_OEMAGENT_DIR, which overrides the location of all the

above-mentioned files.


Upgrading from 8.0.6/8.1.6/8.1.7 Intelligent Agents to 9.x

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.x version of the Intelligent Agent.


nmumigr8 [-source_home source ORACLE_HOME] [-verbose]

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.


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.


Best Practices: Agent Installation and Configuration

Several database products can be installed on a single machine, all of different core versions, and any of which can be upgraded or patched independently. Because the Intelligent Agent can manage multiple products, adhering to Agent implementation, upgrade and mainentance best practices will optimize Agent performance and ensure trouble-free operation.


Agent Installation


Install Only One Agent Per Machine

Although it is possible to have several versions of the Intelligent Agent installed on a single machine, only one of these versions can be active at any time. It is recommended that you only install one version of the Intelligent Agent per machine. When several versions of the Agent are present on one machine, there is a danger that the wrong Agent will be started, causing all job and event registrations and notifications to be cross-sent to different versions of the Agent. This situation will lead to synchronization problems between the Management Server and the Intelligent Agent. The only solution at this point is to drop the node from the navigator, and clean-start the Intelligent Agent to re-synchronize the information. See "Clean Starting the Intelligent Agent" for more information


Create a Separate Agent User

Create a user at the Operating System level that will own the Agent installation and will control (start and stop) the Agent. The username (not necessarily its password) should be the same on all managed nodes (for example, oramon). The Agent owner needs to be a member of the `dba' group for all monitored databases on its node, although none of them has to be its primary group.

The profile of the Agent Owner should set the following environment variables. The example of Listing 1 assumes that csh is the default shell of the Agent owner and lists the contents of the .cshrc file. A similar-looking structure should be used in the .profile file if the Bourne Shell or Korn Shell are used as the default shell of the Agent Owner.


Example 2-1 Profile of the ORAMON Operating System User

umask 002
# provide the appropriate value for ORACLE_HOME
setenv ORACLE_HOME /oracle
setenv PATH ${ORACLE_HOME}/bin:/usr/ccs/bin:${PATH}
setenv TCL_LIBRARY ${ORACLE_HOME}/network/agent/tcl

unsetenv ORACLE_SID
unsetenv NLS_LANG

# if a central location for net8 config files exist, 
# set it here otherwise, make sure TNS_ADMIN is not set
# setenv TNS_ADMIN /usr/local/oracle/admin
unsetenv TNS_ADMIN

# point ORATAB to an OEM-specific oratab file if such exists
if ( -e ${ORACLE_HOME}/network/agent/oratab.oem ) then
  setenv ORATAB ${ORACLE_HOME}/network/agent/oratab.oem

The TNS_ADMIN environment variable should point to the central location of all Oracle Net configuration files, if such a location exists. If not, make sure that the TNS_ADMIN variable is not set.


Install the Agent in Its Own ORACLE_HOME

In order to avoid conflicts during maintenance upgrades of the various pieces of software, and to be able to upgrade an individual product independently, it is recommended that you install the Intelligent Agent in its own ORACLE_HOME.

It is also recommended that the standard operating system user, "oramon" be used to install the Agent on all machines in your environment. You need to change both the owner of the directory and the group to which the directory belongs. To do this:

  1. Create a new ORACLE_HOME directory.

    mkdir oemagent_9.2.0

  2. Change the owner to 'oramon'.

    chown oramon oemagent_9.2.0

  3. Change the group to 'oramon'.

    chgrp oramon oemagent_9.2.0

Starting from Oracle 8.1.5, the Universal Installer is used to install the Oracle software. To install the Intelligent Agent using the Universal Installer, perform the following steps:

  1. In the Installer's File Location window, specify a new ORACLE_HOME name, and a new physical location.

  2. Perform a 'Custom Install'

  3. In the product list, select the following products:

    Oracle Enterprise Manager Products | Oracle Intelligent Agent

  4. Deselect all other products. Expand all elements of the product list to make sure only the Intelligent Agent is being installed. Deselecting only the top level entry for a product does not guarantee lower-level elements have been deselected.

  5. Finish the installation, and perform the OS specific post-install tasks, such as running the script on UNIX.

  6. If you decide to install the Agent in an Oracle Home which has an Oracle Database Server, make sure that the version of the Agent matches the database version. It is NOT required to shutdown a database while the Agent is being installed. If you decide to de-install the Agent, this will NOT remove any components that the Oracle Database Server is dependent on.


Use Symbolic Links to the Agent Agent Home

A standard Agent ORACLE_HOME should be used on all machines, such that the ORACLE_HOME is a symbolic link to the location of the current Agent. Thus, when an Agent is upgraded to another version, the link will then point to the location of the latest Agent. This will help maintain a consistent ORACLE_HOME for the Agent on every machine at all times.

For example, if using version 9.2.0 of the Agent, set ORACLE_HOME to point to the directory /u01/app/oracle/product/oemagent which is a symbolic link to the directory /u01/app/oracle/product/oemagent_9.2.0.

ln -s  /u01/app/oracle/product/oemagent /u01/app/oracle/product/oemagent_9.2.0


Agent Configuration


Disable Unused Agents

To prevent accidental starting of an older Agent, rename the DBSNMP executable of all older versions of the Agent. This will prevent someone from accidentally starting the wrong Intelligent Agent.


Auto-Start the Agent Upon Machine Startup

Your Agent should be configured to start automatically upon machine startup/reboot. Include a script like the one listed below in your boot up procedures so that the Intelligent Agent is started automatically at machine bootup time.


Example 2-2 Sample Agent Boot Time Startup Script (UNIX)

 PATH=/usr/bin:/usr/sbin:/sbin; export PATH
 # modify the next line to point to the agent's ORACLE_HOME
 # find the agent owner by looking at file ownership
 USERID=`ls -ld $ORACLE_HOME/bin | awk '{print $3}'`
 case $1 in
 'start'| '')
         su - $USERID -c "$ORACLE_HOME/scripts/oemagent start"
         "Starting OEM agent"
         su - $USERID -c "$ORACLE_HOME/scripts/oemagent stop"
         "Stopping OEM agent"
         echo "usage: $0 {start|stop}"


Agent Compatibility

To ensure Agent-Enterprise Manager-RDBMS compatibility, and to access all features available for a given version of the Enterprise Manager framework, we recommended using the Intelligent Agent that matches the version of the framework. The following table lists Agent version compatibility.


Table 2-2 Agent Compatibility

Database Version Enterprise Manager Version Agent Version
7.3.4.x 1.3.4 7.3.4.x
8.0.5.x, 7.3.4.x 1.6.0 8.0.5.x
8.0.6.x, 8.0.5.x, 7.3.4.x 1.6.5 8.0.6.x
8.1.5.x, 8.0.6.x, 8.0.5.x, 7.3.4.x 2.0.4 8.1.5.x
8.1.6.x, 8.1.5.x, 8.0.6.x, 8.0.5.x, 7.3.4.x 2.1 8.1.6.x
8.1.7.x, 8.1.6.x, 8.1.5.x, 8.0.6.x, 8.0.5.x, 7.3.4.x 2.2 8.1.7.x
9.2.0, 9.0.1, 8.1.7.x 9.2.0 9.2.0

After Agent installation is completed, the SQL*Net/Oracle Net files for the Intelligent Agent (SQLNET.ORA and TNSNAMES.ORA) have to be created/updated, to be able to contact all the databases the Agent needs to manage. Also, by default the Agent will use the ORATAB file (unless the TNS_ADMIN environment variable is set) on its machine to find the ORACLE_HOMES and discover services. If you want the Agent to find a subset of ORACLE_HOMES and discover corresponding services, we recommend creating another file that contains this subset. The ORATAB environment variable should be set in the Agent's environment and should point to this file prior to starting the Agent.


General Agent-Enterprise Manager Upgrade Process

  1. Install the latest Intelligent Agent under a new Oracle Home. See above. 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.

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

  3. 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 Event Library.

  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.