24 Upgrading Oracle Management Agent Using Agent Upgrade Wizard

This chapter describes how you can upgrade an existing Oracle Management Agent 10g Release 4 or 5 (10.2.0.4.0 or 10.2.0.5.0) to Oracle Management Agent 11g Release 1 (11.1.0.1.0) using the Agent Upgrade Wizard. In particular, this chapter covers the following:

Overview
Before You Begin
Prerequisites
Upgrade Procedure
After You Upgrade

Overview

You can upgrade an existing Oracle Management Agent 10g Release 4 or 5 (10.2.0.4.0 or 10.2.0.5.0) to Oracle Management Agent 11g Release 1 (11.1.0.1.0) using the Agent Upgrade Wizard that is built into Enterprise Manager Grid Control. The Agent Upgrade Wizard offers GUI-rich, interactive screens, and can be accessed from the Enterprise Manager Grid Control console.

IMPORTANT:

Agent Upgrade Wizard does not help you migrate from one patch release to another. For example, you cannot use this wizard to move from Oracle Management Agent 10g Release 4 (10.2.0.4.0) to Oracle Management Agent 10g Release 5 (10.2.0.5.0). This type of migration is called Patching and patching is done using patch sets that are released periodically by Oracle.

Although the Agent Upgrade Wizard can be used for upgrading one, single Oracle Management Agent, the wizard is best suited for upgrading multiple Oracle Management Agents at a time, and is particularly useful when you want to upgrade remotely.

The Agent Upgrade Wizard gives you the flexibility to select multiple hosts on which Oracle Management Agent needs to be upgraded. This helps you when you want to upgrade Oracle Management Agent on several hosts, in one attempt.

Before You Begin

Before you begin, keep these points in mind:

If you are upgrading a Management Agent whose software binaries were used for installing shared Management Agents, that is, either using the Shared Agent Deployment Wizard or the nfsagentinstall script, then before proceeding any further, read Chapter 27, "Upgrading Shared Oracle Management Agent".
If you want to view the status of an upgrade session that was previously run, click Agent Installation Status in the Deployments screen. However, do not attempt to view the installation status until the installation is complete. If you do, you will see an error.
On Microsoft Windows, do not open the agentpush.properties file using Microsoft Word software. Open it using other text editors such as VIM or Notepad.
For accessing the Enterprise Manager Grid Control console, ensure that you use only certified browsers as mentioned in My Oracle Support note 412431.1

Prerequisites

Before upgrading the Management Agent, ensure that you meet the following prerequisites.

If you want, you can print out this section and write 'Yes' or 'No' against each prerequisite. This will help you to track the prerequisites you have met and the prerequisites you have not met.

Table 24-1 Prerequisites for Upgrading Oracle Management Agent Using Agent Upgrade Wizard

Requirement	Description	Yes/No
Hardware Requirements	Ensure that you meet the hard disk space and physical memory requirements as described in Appendix A, "Meeting Hardware Requirements".
Operating System Requirements	Ensure that you install the Management Agent only on certified operating systems as mentioned in My Oracle Support note 412431.1.
Package Requirements	Ensure that you install all the platform-specific packages as described in Appendix B, "Meeting Package, Kernel Parameter, and Library Requirements ".
User and Operating System Group Requirement	Ensure that the destination host where you want to upgrade the Management Agent has the appropriate users and operating system groups created. For information about creating operating system groups and users, see Appendix C, "Creating Operating System Groups and Users Requirements".
Temporary Directory Space Requirements	Ensure that you allocate 400 MB of space for a temporary directory where the executables can be copied. For example, `/tmp` on UNIX hosts and `c:\Temp` on Microsoft Windows hosts.
Central Inventory Requirements	Ensure that you allocate 100 MB of space for the central inventory directory. Also ensure that the central inventory directory is not on a shared file system. If it is already on a shared file system, then switch over to a non-shared file system by following the instructions outlined in My Oracle Support note 1092645.1.
Installation Base Directory Requirements	Ensure that the installation base directory you specify is empty and has write permission.
Software Availability Requirements	By default, the software for Oracle Management Agent 11g Release 1 is available on the host where Oracle Management Service 11g Release 1 is running. Note that this Management Agent software is for the platform on which the OMS is running. Therefore, if you want to upgrade to Oracle Management Agent 11g Release 1 on a platform that is the same as the one on which the OMS is running, then you already meet this prerequisite; you do not have to take any action. However, if you want to upgrade to Oracle Management Agent 11g Release 1 on a platform that is different from the one on which the OMS is running, then ensure that you download the software for that platform. For more information about downloading the Management Agent software, see Procuring Oracle Management Agent Software.
File Deletion Requirements	If you are upgrading Oracle Management Agent 10g Release 4 (10.2.0.4.0) or higher, which was upgraded from Oracle Management Agent 10g Release 1, then ensure that you remove the following file from the Oracle home of the 10.2.0.4.0 or 10.2.0.5.0 Management Agent: `$<ORACLE_HOME>/bin/emctl.upgrade.backup`
Accessibility Requirements	If there are multiple OMSes in your environment and if you have staged the Management Agent software in a non-default location (not on the OMS host), then ensure that the non-default location is accessible by all the OMSes.
Path Validation Requirements	Validate the path to all command locations. For more information, see Appendix E, "Validating Command Locations".
Host List Requirements	Ensure that you identify the hosts where you want to upgrade the Management Agent. Otherwise, maintain a host list file that contains a list of hosts as described in What Is a Host List File?. Ensure that all hosts have the same operating system credentials and file system structure. If you are upgrading the Management Agents of a cluster, then ensure that the nodes are part of the same cluster.
`/etc/hosts` File Requirements	If the destination host and the host on which OMS is running belong to different network domains, then ensure that you update the `/etc/hosts` file on the destination host to add a line with the IP address of that host, the fully-qualified name of that host, and the short name of the host. For example, if the fully-qualified host name is `mypc.cn.company.com` and the short name is `mypc`, then add the following line in the `/etc/hosts` file: `12.123.123.12 mypc.cn.company.com mypc`
Preinstallation/Postinstallation Scripts Requirements	Ensure that the preinstallation and postinstallation scripts, which you want to run along with the upgrade procedure, are available on all the destination hosts.
Installing User Requirements	If the central inventory owner and the user installing the Management Agent are different, then ensure that they are part of the same group. Also ensure that the inventory owner and the group to which the owner belongs have read and write permissions on the inventory directory. For example, if the inventory owner is user1, and user installing the Management Agent is user2, then ensure that user1 and user2 belong to the same group, and they have read and write access to the inventory.
Permission Requirements	Ensure that you have read, write, and execute permissions on `oraInventory` on all remote hosts. If you do not have these permissions on the default inventory (typically at `/etc/oraInst.loc`) on any remote host, then you can specify the path to an alternative inventory location by using one of the following options in the Additional Parameters section of the Agent Deployment Wizard: On the Installation Details page, if you select Default, from Management Server location, which means the software is on the OMS host, then use the `-i <location>` option. On the Installation Details page, if you select Another Location, which means the software is in any other location other than the OMS host, then use the `-invPtrLoc` option. Ensure that you have write permission on the Installation Base Directory and the temporary directory where the executables will be copied. For example, `/tmp` or `c:\Temp`.
Oracle Inventory Location Requirements	Ensure that the Oracle Inventory (`oraInventory`) is not in a shared location. When you use the `oraInst.loc` file, ensure that the inventory location specified there is not pointing to a shared location. If it is, change it to a non-shared location.
SUDO Privilege Requirement	Ensure that you have SUDO privileges to run `root.sh` and `/bin/sh` (UNIX platforms only). The Agent Upgrade Wizard uses SUDO to run the root.sh script. You must specify the invoking user's password here. To verify whether you have SUDO privileges to run these files, access the `/etc/sudoers` file and check whether you have a similar entry as shown below. If you do not see a similar entry, then add one. `<user> <hostname>=PASSWD: /home/em/agent11010/agent11g/root.sh, /bin/sh` If you do not have SUDO privileges and if you do NOT want to run `root.sh` and `/bin/sh` yourself at the time of upgrade, then request your Administrator who has SUDO privileges to manually run the scripts after the installation ends. To understand how and where the scripts need to be run from, see After You Upgrade.
SUDOERS File Configuration Requirements	Ensure that you configure /etc/sudoers file so that while running a command using SUDO, you are always prompted for a password. If /etc/sudoers file is configured in such a way that SUDO never prompts for a password, then a directory with the host password as the title gets created in the invoking users home directory.
Default SSH Port Requirements	Ensure that the SSH daemon is running on the default port (that is, 22) on all the destination hosts. If the port is a non-default port, that is, any port other than 22, then update the SSH_PORT property in the following file that is present in the OMS Instance Base: `<INSTANCE_HOME>/sysman/prov/resources/Paths.properties`
PubkeyAuthentication Parameter Requirements	Ensure that the `PubkeyAuthentication` parameter is enabled in the `sshd_config` file. To verify the value of this parameter, run the following command: `grep PubkeyAuthentication <SSH_Install_Location>/sshd_config` For example, grep PubkeyAuthentication /etc/ssh/sshd_config The result of this command must be Yes. If the result is No, then edit the `sshd_config` file, set the PubkeyAuthentication value to Yes, and restart the SSH daemon.
PATH Environment Variable Requirements	On the host where OMS is running and on the host where you want to install the Management Agent, ensure the following: (For Microsoft Windows) Ensure that the cygwin software location appears before other software locations in the `PATH` environment variable. After making it the first entry, restart the SSH daemon (sshd) on both the hosts. (For UNIX) Ensure that the SCP binaries (for example, /usr/local/bin/scp) are in the `PATH` environment variable.
SSH Setup Requirements (For Microsoft Windows)	(For Microsoft Windows) If you are upgrading the Management Agent on a Microsoft Windows-based platform, then ensure that you set up the SSH connectivity between the host running OMS and the host where the Management Agent needs to be installed, as described in Appendix D, "Setting Up SSH Connectivity".
Agent User Account Permissions and Rights (For Microsoft Windows)	(For Microsoft Windows) If you are upgrading the Management Agent on a Microsoft Windows-based platform, then ensure that the agent user account has permissions and rights to perform the following: Act as part of the operating system. Increase quotas. Replace process level token. Log in as a batch job. To verify whether the agent user has these rights, follow these steps: Launch the Local Security Settings. From the Start menu, click Settings and then select Control Panel. From the Control Panel window, select Administrative Tools, and from the Administrative Tools window, select Local Security Settings. In the Local Security Settings window, from the tree structure, expand Local Policies, and then expand User Rights Assignment.
Permissions for cmd.exe (For Microsoft Windows)	(For Microsoft Windows) If you are upgrading the Management Agent on a Microsoft Windows-based platform, then ensure that you grant the `Cmd.exe` program Read and Execute permissions for the user account that the batch job runs under. This is a restriction from Microsoft. For more information on this restriction and to understand how you can grant these permissions, access the following URL to Microsoft Web site: `http://support.microsoft.com/kb/867466/en-us`

Upgrade Procedure

To upgrade a Management Agent, follow these steps:

In Grid Control, click Deployments.
On the Deployments page, from the Agent Installation section, click Install Agent.
On the following page, click Upgrade Agent.
On the Installation Details page, in the Version section, select the version of the Management Agent to which you want to upgrade. The values available in this list depend on the software staged on the OMS host.

For example, if you upgrading Oracle Management Agent 10g Release 5 (10.2.0.5.0) to Oracle Management Agent 11g Release 1 (11.1.0.1.0), then select 11.1.0.1.0.
In the Hosts section, do the following:
1. From the Platform list, select the operating system on which you want to upgrade the Management Agent.
2. For Provide Host List, specify the host names or IP addresses of the hosts on which you want to upgrade the Management Agent.You can use a comma (,) or a white space as a separator when specifying multiple hosts.
  
  Alternatively, if you already have a list maintained in a file, then click Get Host Names From File and select that file.
  
  For information about host list file, see What Is a Host List File?.
3. If the hosts specified in the previous step are part of the same cluster, then select Cluster Upgrade.
In the OS Credentials section, do the following:
1. Specify the appropriate operating system user credentials. The operating system credentials you specify here must be the same for all the selected hosts.
2. Select Run root.sh (for UNIX) if you want the application to run this script.
  
  The root.sh script runs after the configuration assistants are run and before the postinstallation scripts (if any) are run. If you do not select this option here, you must run root.sh on each node manually.
In the Existing Agent Information section, specify the full path to the Oracle home of the existing Management Agent that you want to upgrade. Ensure that the path you specify here is the same on all the hosts.
In the Destination section, specify the full path to the Installation Base Directory. This directory is created on all the specified hosts, and the Oracle home of the Management Agent is created as a subdirectory under this directory.

For information about installation base directory, see What Is Installation Base Directory?.
In the Additional Parameters section, specify any additional parameters that you want to pass during installation. To understand the possible parameters that can be passed here, see Table 24-2.

Oracle recommends you to specify only those parameters that you want to run in addition to the general parameters you have already provided on this page for installation. For example, in Step (8), you are specifying the installation base directory. Therefore, for Additional Parameters, try to avoid specifying the installation base directory again. If you still do so, then the value you specified in Step (8) will be ignored and the value you specified here will be used instead.

And note that if you are specifying more than one parameter, then separate them with a white space. For example, -i /etc/oraInst.loc -p /home/config/staticports.ini.
In the Management Server Security section, specify a password that can be used for authenticating new Management Agents that join the Enterprise Manager Grid Control system, and for permitting only secure Management Agents to communicate with the OMS, which is in locked state, via HTTPS protocol.

Alternatively, after the installation is complete, the super administrator can approve the addition of new Management Agents to the Enterprise Manager Grid Control system.

Note:
For security reasons, Oracle strongly recommends you to change the OMS password specified here After the installation is complete.
In the Additional Scripts section, do the following:
1. Specify any preinstallation and/or postinstallation scripts that you want to run.
2. Select Run as Superuser if you want to run these scripts as root.
Note:
The preinstallation and/or postinstallation scripts that you specify must be available on all the hosts. These files are not copied onto the hosts from the software source location during installation.
Click Continue.
On the My Oracle Support Details page, do the following:
- If the host where the Management Agent is being upgraded has a direct connection to the Internet, then specify an e-mail address and My Oracle Support password.
  
  An e-mail address is required so that security updates and install updates can be sent. You can specify any e-mail address, but Oracle recommends you to specify the My Oracle Support user name. For example, john.mathew@xyz.com.
- If the host where the Management Agent is being upgraded has an indirect connection to the Internet, that is, through a proxy server, then specify an e-mail address and My Oracle Support password, and then in the Connection Details section, specify the proxy server details.
  
  Note:
  You can change the proxy server settings any time after the installation or patching process ends. To do so, run the configCCR command from the ccr/bin/ directory within the Oracle home of the Management Agent.
- If the host where the Management Agent is being upgraded does not have a direct or indirect connection to the Internet, then specify the e-mail address and leave the other fields blank.
  
  In this case, after you complete the upgrade process, manually collect the configuration information and upload it to My Oracle Support.
  
  Note:
  If you see any errors on this page, then check whether you (the user installing the Management Agent) have the necessary write permissions on crontab. If you do not, then create an entry for your user account in the cron.allow file.
For information about Oracle Configuration Manager, see What Is Oracle Configuration Manager?. For information about manually collecting and uploading configuration information, see Manually Collecting and Uploading Configuration Information.
Click Continue.

As part of this process, the Agent Upgrade Wizard performs some prerequisite checks before proceeding with the upgrade process. When all the prerequisite checks are complete, the application displays the results. You can choose to either retry the prerequisite check on all those failed hosts, or ignore the result and proceed to upgrade the Management Agent.
Note:
- After the installation and configuration phase, the Agent Upgrade Wizard runs the root.sh script.
- If the upgrade operation fails, then click Recover to recover the previous release of the Management Agent that you were trying to upgrade. On clicking Recover, you return to the Installation Details page of the Agent Upgrade Wizard. On the Installation Details page, in the OS Credentials section, specify the appropriate operating system user credentials and click Continue. Proceed and submit the operation again to recover the previous release of the Management Agent.

Additional Parameters You Can Specify for Agent Upgrade

The following are the additional parameters you can specify while using the Agent Upgrade Wizard to upgrade an existing Management Agent:

Table 24-2 Additional Parameters Supported for Agent Upgrade

Parameters	Description
-t	Do NOT start the Agent after installation/upgrade. No value required.
-b	Specify installation Base Dir location. For example, `-b /home/OracleHomes/agent/`
-d	Do not initiate automatic target discovery. No value required.
-i	Specify inventory pointer location file. For example, `-i /etc/oraInst.loc`
-o	Specify existing agent home to upgrade. For example, `-o /home/OracleHomes/oldAgent/`
-p	Specify file location for static port for Agent. For example, `-p /home/config/staticports.ini`
-z	Specify the timezone environment variable value (`-z <timezone>`). For example, `-z PST8PDT`.

Note:

If the parameters that you specify here are also specified independently through command-line options, the value of the parameters that you specify here will take precedence over the others. For example, if installation Base Dir has been specified independently, and the -b option is specified here, the value of the latter (-b) will be used during the upgrade.

After You Upgrade

After you upgrade the Management Agent, follow these steps:

Verify the installation:
1. Navigate to the Oracle home of the Management Agent and run the following command to see a message that confirms that the Management Agent is up and running:
  
  $<ORACLE_HOME>/bin/emctl status agent
  
  Note:
  If the status of the Management Agent is down for some reason, then manually start the Management Agent by running the following command from its Oracle home:
  $<ORACLE_HOME>/bin/emctl start agent
2. Navigate to the Oracle home of the Management Agent and run the following command to see a message that confirms that EMD upload completed successfully:
  
  $<ORACLE_HOME>/bin/emctl upload
Note:
(For UNIX operating systems) Before running the emctl command to start the Management Agent, ensure that the environment variable NLS_LANG is set with a value that is compatible with the operating system default locale setting and the character set of the Oracle Database, which houses the Management Repository.
(Only for UNIX Operating Systems) If you had NOT selected Run Root.sh in the OS Credentials section, then manually run the root.sh script as a root user from the Oracle home of the Management Agent:

<Oracle_Home>/root.sh

For example, if you are using SUDO to change to a root user, then you will run the following command:

/usr/local/bin/sudo /scratch/OracleHomes/agent11g/root.sh

If you do not have SUDO privileges, then request your Administrator who has the privileges to run these scripts.
(Optional) If you have not secured the communications between the Management Agent and the OMS, then secure it by running the following command from the Oracle home of the Management Agent:

$<ORACLE_HOME>/bin/emctl secure agent

Note:
Even after securing the Management Agent, some data might still be transferred over the network without being encrypted.
If the PATH environment variable is set to the agent10g directives, then manually updated them to agent11g path. Manually delete the agent10g files from the file system. Also, manually disable and remove the Oracle agent10g Windows Services (The agent11g services are created and started automatically, but old 10g services remain.)
(Optional) If you want to discover the newly installed targets, if you want to convert the standalone Management Agent to a cluster-based Management Agent, if you want to discover the targets on the new nodes of the cluster, or if you want to reconfigure the cluster-based Management Agent, you must run the agentca script to reconfigure and discover all new targets.

For information about the agentca script, see What Is Agent Configuration Assistant Used For?.

For information about reconfiguring the Management Agent and discovering all new targets, see Appendix I, "Reconfiguring Oracle Management Agent and Discovering New Targets".
(Optional) If you want to enable the Request Monitoring feature for tracing transaction requests in WLS, you need JVM Diagnostics as well as Application Dependency and Performance (ADP) managers and agents configured against the target to be monitored.

For information about installing JVM Diagnostics and enabling the Request Monitoring feature, refer to the Oracle Enterprise Manager Administration Guide.

For information about enabling the ADP feature in Enterprise Manager Grid Control, refer to the Oracle Enterprise Manager Getting Started with Management Pack Plus for SOA.

Both these guides are available at:

http://www.oracle.com/technology/documentation/oem.html