Skip Headers
Oracle® Enterprise Manager Cloud Control Upgrade Guide
12c Release 2 (12.1.0.2)
E22625-16
  Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

5 Upgrading Oracle Management Agents

This chapter describes how you can upgrade your Enterprise Manager Cloud Control 12c Release 1 (12.1.0.1) or later Oracle Management Agents. This chapter contains the following sections:

Overview

If you are using Enterprise Manager Cloud Control 12c Release 2 to manage your enterprise, Oracle strongly recommends that you upgrade all your Oracle Management Agents (Management Agents) to 12c Release 2 (12.1.0.2).

To upgrade your Management Agents, use the Upgrade Agents page, which is a part of the Enterprise Manager Cloud Control console.

The Upgrade Agents page acts as a single-window solution to mass-upgrade your existing Management Agents to the latest version for which the software is available in Oracle Software Library. To access this page, from the Setup menu, select Manage Cloud Control, then select Upgrade Agents.

Clicking Not Upgradable Agents on the Upgrade Agents page displays the Management Agents that cannot be upgraded, and other details about these Management Agents, such as why they cannot be upgraded, what you can do to upgrade them, and so on. For more information on these Management Agents, see Viewing Management Agents That Cannot Be Upgraded.

Clicking Agent Upgrade Results displays the Management Agent upgrade jobs that succeeded, the upgrade jobs that failed, and the upgrade jobs that are presently running. For more information on Management Agent upgrade jobs, see Viewing Management Agent Upgrade Jobs and Viewing Management Agent Upgrade Job Status and Progress.

Figure 5-1 shows the Upgrade Agents page.

Figure 5-1 Upgrade Agents Page

Surrounding text describes Figure 5-1 .

Using the Upgrade Agents page, you can also:

Upgrading a Management Agent modifies its installation base directory structure. The following is an example of the Management Agent installation base directory structure before and after upgrading it to 12c Release 2 (12.1.0.2):

Before Upgrade

<agent_base_directory>
    |_____sbin
    |_____core
         |_____12.1.0.1.0
    |_____plugins
    |_____plugins.txt
    |_____plugins.txt.status
    |_____agent_inst
    |_____agentimage.properties

After Upgrade

<agent_base_directory>
    |_____sbin
    |_____backup_<TIMESTAMP>
    |_____core
         |_____12.1.0.1.0
         |_____12.1.0.2.0
    |_____plugins
    |_____plugins.txt
    |_____plugins.txt.status
    |_____plugins_upgrade.txt
    |_____plugins_upgrade.txt.status
    |_____agent_inst
    |_____agentimage.properties

Note:

  • When you upgrade a Management Agent, you cannot change the location of the agent base directory.

  • When you upgrade a Management Agent, the plug-ins installed on the Management Agent host are also upgraded by default, as long as the latest versions of these plug-ins exist in Oracle Software Library (Software Library). If the latest versions of these plug-ins do not exist in the Software Library, their old versions are retained.

  • If you upgrade a 12c Release 1 (12.1.0.1) Management Agent installed on a Microsoft Windows host to 12c Release 2 (12.1.0.2), and you want to install another Management Agent on the same host, ensure that you install the Management Agent after downloading the Management Agent software, and specifying the s_agentSrvcName parameter, as described in the Oracle Enterprise Manager Cloud Control Advanced Installation and Configuration Guide.


Before You Begin

Before you upgrade your Management Agents, you must be aware of the following:

Prerequisites

Before you upgrade your Management Agents, meet the following prerequisites:

Upgrade Procedure

This section describes the actions involved in upgrading Management Agents. It consists of the following:

Upgrading Management Agents

To upgrade 12c Management Agents to the latest available version, follow these steps:

  1. From My Oracle Support, download and apply Patch 14785561 on your 12.1.0.2.0 OMS. This patch contains bug fixes for known issues encountered while upgrading your Management Agents. For instructions on how to apply this patch, refer to the patch readme. If you are in the middle of upgrading your Management Agents, you can still apply this patch to your 12.1.0.2.0 OMS, and then continue to upgrade the rest of your Management Agents.

    After applying the patch, set the ORACLE_HOME environment variable, navigate to the location where you unzipped the patch contents, and run the post_deploy.sh script (post_deploy.bat for Microsoft Windows operating systems).

  2. From the Setup menu, select Manage Cloud Control, then select Upgrade Agents. Click Add, select the Management Agents you want to upgrade, then click Select.

  3. On the Upgrade Agents page, do the following:

    1. Click Add to add Management Agents for the upgrade job.

    2. For Job Name, accept the default job name, or enter a unique job name.

      A unique job name enables you to identify the upgrade job, know details of its execution, and track its progress on the Agent Upgrade Status page.

      The job name can have a maximum length of 64 characters. It can contain alphabets, numerals, and special characters, and can begin with any of these.

    3. For Stage Location, accept the default stage location, or enter a custom location.

      For example, /tmp/software/oracle/EMStage.

      Ensure that the Management Agent install user has write permissions on the custom location you enter. The custom location you enter can be a shared, NFS-mounted location.


      Note:

      Ensure that the Management Agent host user has write permission in the custom location.

      The stage location is used to store temporary Management Agent upgrade files.

    4. (Optional) For Pre-upgrade Script and Post-upgrade Script, enter the absolute path of the script you want to run before and after the upgrade, respectively.

      For example, /scratch/software/oracle/configure.sh.

      The scripts you want to run must be present at the location you specify, on the Oracle Management Service (OMS) host, or on all the Management Agent hosts selected for upgrade. They can reside in a shared, NFS-mounted location accessible by the Management Agent hosts selected for upgrade.

      If the script you want to run is present only on the OMS host, and not on the Management Agent hosts selected for upgrade, then select Script on OMS Host. The scripts you specify are first copied to the stage location you specified earlier, then run, and then deleted from the stage location.


      Note:

      • You can specify only one pre-upgrade script and one post-upgrade script per session.

      • Only shell scripts (.sh) and batch (.bat) scripts are supported. You should run only shell scripts while upgrading Management Agents installed on Unix platforms, and only batch scripts while upgrading Management Agents installed on Microsoft Windows platforms.

      • If you want to upgrade a Management Agent installed on a Unix platform and a Management Agent installed on a Microsoft Windows platform in the same session, ensure that you do not specify a pre-upgrade or a post-upgrade script. If you want to specify a pre-upgrade or a post-upgrade script for upgrading these Management Agents, upgrade the Management Agents in different sessions.


    5. (Optional) For Additional Parameters, enter the additional options you want to use for the upgrade.

      For example, specify -ignorePrereqs to skip running the prerequisite checks, and directly perform the Management Agent upgrade.

      Refer Additional Parameters for Management Agent Upgrade for a list of parameters you can specify.

  4. Click Submit.


Note:

If you encounter an error which mentions that Root.sh cannot be run for the following agents, and specifies the reason as Oracle Home Property Missing, do one of the following:
  • Click OK. After the upgrade, log in to the Management Agent host as the root user, and run the $<AGENT_BASE_DIR>/core/12.1.0.2.0/root.sh script on the host. After running this script, run the $<AGENT_BASE_DIR>/core/12.1.0.2.0/replacebins.sh script on the host.

  • Click Cancel, then do the following:

    1. Run the following command on the Management Agent host from <AGENT_INSTANCE_HOME>/bin:

      emctl control agent runCollection <ORACLE_HOME_TARGET_NAME>:oracle_home oracle_home_config

      To obtain <ORACLE_HOME_TARGET_NAME>, refer the targets.xml file present in <AGENT_INSTANCE_HOME>/sysman/emd.

    2. Upgrade the Management Agent using the Upgrade Agents page.



Note:

If you encounter an error which mentions that Root.sh cannot be run for the following agents, and specifies the reason as Preferred Credentials for Oracle Home not set, do one of the following:
  • Click OK. After the upgrade, log in to the Management Agent host as the root user, and run the $<AGENT_BASE_DIR>/core/12.1.0.2.0/root.sh script on the host. After running this script, run the $<AGENT_BASE_DIR>/core/12.1.0.2.0/replacebins.sh script on the host.

  • Click Cancel, then do the following:

    1. Set the preferred privileged credentials for the Oracle Home target of the Management Agent.

      For information on how to set the preferred privileged credentials for the Oracle Home target of a Management Agent, refer to Oracle Enterprise Manager Cloud Control Administrator's Guide.

    2. Configure privilege delegation settings on the Management Agent host.

      For information on how to configure privilege delegation settings on the Management Agent host, refer to the Setting Up Database as a Service chapter of the Oracle Enterprise Manager Cloud Administration Guide.

    3. Upgrade the Management Agent using the Upgrade Agents page.

    If you do not want to set the preferred privileged credentials for the Oracle Home target of the Management Agent, click Cancel, and do the following:

    1. Select Override Privileged Credentials, and create a new credential by clicking the displayed icon. If the credential you create is not a root credential, select Sudo or PowerBroker for Run Privilege, and enter root for Run as.

    2. Configure privilege delegation settings on the Management Agent host.

    3. Upgrade the Management Agent using the Upgrade Agents page.

    If the root.sh job step fails after the upgrade, log in to the Management Agent host as the root user, and run the $<AGENT_BASE_DIR>/core/12.1.0.2.0/root.sh and $<AGENT_BASE_DIR>/core/12.1.0.2.0/replacebins.sh scripts manually.



Note:

If the Management Agent upgrade fails for some reason, you can diagnose the problem by following these steps:
  1. View the output logs of the failed Management Agent upgrade job steps.

    To view the output log of a Management Agent upgrade job step, on the Upgrade Agents page, click Agent Upgrade Results. Click the name of the Management Agent upgrade job, and select the required Management Agent. Click the name of the required job step.

  2. View the Management Agent deployment log available at the following location:

    $<AGENT_BASE_DIRECTORY>/core/12.1.0.2.0/cfgtoollogs/agentDeploy/agentDeploy_<TIMESTAMP>.log
    
  3. View the plug-in upgrade configuration log available at the following location:

    $<AGENT_INSTANCE_HOME>/install/logs/agentplugindeploy_<TIMESTAMP>.log
    

Additional Parameters for Management Agent Upgrade

Table 5-1 describes the additional parameters you can enter while upgrading 12c Management Agents. You can enter more than one parameter, using a whitespace as a separator.

Table 5-1 List of Additional Parameters for Management Agent Upgrade

Parameter Description

-ignorePrereqs

Skips running the prerequisite checks.

Specify this parameter when you have already verified the prerequisites, and only want to perform the rest of the upgrade process.

-debug

Logs debug messages useful for debugging and resolving errors.


Viewing Management Agents That Cannot Be Upgraded

You may not be able to upgrade certain Management Agents using the Upgrade Agents page. Table 5-2 describes the reasons for this.

Table 5-2 Why Some Management Agents Cannot Be Upgraded

Reason Description and Recommended Action

Latest Agent Software Missing

The latest Management Agent software is not available in Oracle Software Library.

To upgrade a Management Agent for which the latest Management Agent software is not available, you need to first download and apply the latest software using the Self Update console, then use the Upgrade Agents page.

To access the Self Update Console, from the Setup menu, select Extensibility, then select Self Update. To download the latest Management Agent software, click Agent Software, select the required software, then click Download. For more information on using the Self Update console to download and apply the latest Management Agent software, see Oracle Enterprise Manager Cloud Control Basic Installation Guide.

Agent Unsecured

The Management Agent is not secure.

To upgrade a Management Agent which is not secure, you need to first secure the Management Agent, then use the Upgrade Agents page.

To secure the Management Agent, from the Setup menu, select Manage Cloud Control, then select Agents. Click the required Management Agent name. From the Agent menu, click Secure.

You can also run the following command to secure the Management Agent:

<EMSTATE>/bin/emctl secure agent

Agent Unreachable

The Management Agent is not reachable, that is, the Oracle Management Service (OMS) cannot communicate with the Management Agent.

A Management Agent is generally unreachable when it is down, when it is blocked by the OMS, or when the Management Agent host is down. A Management Agent may also be unreachable due to network problems or certain other issues.

To upgrade a Management Agent that is unreachable, you need to first ensure that the Management Agent is reachable, then use the Upgrade Agents page.

To restore communication between the OMS and the Management Agent, from the Setup menu, select Manage Cloud Control, then select Agents. Click the required Management Agent name to navigate to the Management Agent home page. Click the Agent Unreachable icon, and perform the recommended actions.

Agent Pending Activation

The Management Agent version is not 12c Release 1 (12.1.0.1) or later.

You cannot upgrade 10g or 11g Management Agents using the Upgrade Agents page. Deinstall these Management Agents and install fresh Management Agents on the hosts.

For information on deinstalling Management Agents, refer to Oracle Enterprise Manager Cloud Control Advanced Installation and Configuration Guide. For information on installing fresh Management Agents, refer to Oracle Enterprise Manager Cloud Control Basic Installation Guide.


You can use the Not Upgradable Agents page to search for and view a set of Management Agents that currently cannot be upgraded. To search for and view these Management Agents, follow these steps:

  1. From the Setup menu, select Manage Cloud Control, then select Upgrade Agents.

  2. Click Not Upgradable Agents.

  3. Enter or select values for parameters you want to use to search for Management Agents. You can search for Management Agents using the Management Agent name, version, platform, and the reason why the Management Agent cannot be upgraded.

  4. For Match, select All or Any to search for results that match all the search parameters, or any of the search parameters, respectively.

  5. Click Search.

After You Upgrade

This section describes the various tasks you can perform after upgrading your Management Agents. It consists of the following:

Viewing Management Agent Upgrade Jobs

You use the Upgrade Agents page to mass-upgrade your Management Agents. Once you enter the required upgrade details on this page and click Submit, a Management Agent upgrade job is created, which is sent to the Enterprise Manager job system.

You can use the Agent Upgrade Results page to search for and view a particular set of Management Agent upgrade jobs. To search for and view these jobs, follow these steps:

  1. From the Setup menu, select Manage Cloud Control, then select Upgrade Agents.

  2. Click Agent Upgrade Results.

  3. Enter or select values for parameters you want to use to search for Management Agent upgrade jobs. You can search for Management Agent upgrade jobs using the job name, the Management Agents that were upgraded by the job, the status of the job, and the date when the job was started.

  4. For Match, select All or Any to search for results that match all the search parameters, or any of the search parameters, respectively.

  5. Click Search.

You can view the status and progress of a Management Agent upgrade job by accessing the Agent Upgrade Status page. To access this page from the Agent Upgrade Results page, click the required job name. For information on this page, refer Viewing Management Agent Upgrade Job Status and Progress.

Viewing Management Agent Upgrade Job Status and Progress

A Management Agent upgrade job consists of a series of job steps. The Agent Upgrade Status page informs you about the job steps that succeeded, failed, and are in progress for a particular Management Agent. To view the progress of the job steps involved in upgrading a particular Management Agent, do the following:

  1. From the Setup menu, select Manage Cloud Control, then select Upgrade Agents.

  2. Click Agent Upgrade Results.

  3. Enter or select values for parameters you want to use for the Management Agent upgrade job search. You can search for Management Agent upgrade jobs using the job name, the Management Agents that were upgraded by the job, the date when the job was started, and the status of the job.

  4. For Match, select All or Any to search for results that match all the search parameters, or any of the search parameters, respectively. Click Search.

  5. Click the name of the required Management Agent upgrade job.

  6. Click the Management Agent name.

On this page, you can select a Management Agent and click on a job step to view the output log for the Management Agent upgrade job step. Output logs are useful for diagnosing Management Agent upgrade failures.

Performing Postupgrade Verification Tasks

After you upgrade your Management Agents, follow these methods to verify the upgrade:

  • From the Setup menu, select Manage Cloud Control, then select Upgrade Agents. Click Agent Upgrade Results. Verify that the job you created to upgrade the Management Agents succeeded.

  • From the Setup menu, select Manage Cloud Control, then select Agents. Click the name of a Management Agent you have upgraded, and verify the Management Agent version. The version number must be higher than what it was before the upgrade.

Freeing the Disk Space Occupied by the Old Management Agent

To free the disk space occupied by the 12.1.0.1 Management Agent software, delete only the contents of the $<AGENT_BASE_DIR>/core/12.1.0.1.0 directory. Ensure that the empty directory still exists. Do not delete it.


Important:

Ensure that you free the disk space occupied by the old Management Agent only after the Management Agent is upgraded successfully. For a Master Agent, ensure that you free the disk space occupied by the old Master Agent only after the Master Agent and the associated Shared Agents are upgraded successfully.

Moving Central Agent Base Directory Outside Oracle Middleware Home

The agent base directory of the central agent (that is, the Management Agent installed on the OMS host) resides within the Oracle Middleware home. For information on moving the agent base directory of the central agent outside the old Oracle Middleware home, refer the My Oracle Support note 1520010.1 available at the following URL:

https://support.us.oracle.com/oip/faces/secure/km/DocumentDisplay.jspx?id=1520010.1


Important:

Moving the agent base directory is recommended only for the central agent, and not for the other Management Agents.

Troubleshooting

This section describes how to troubleshoot certain errors you may encounter while upgrading your Management Agents.

You may encounter the following error while upgrading your Management Agents:

The Management Agent cannot be upgraded as the 32-bit Management Agent software for the host platform is not present in Oracle Software Library.

You may encounter this error while upgrading Management Agents that run on the Oracle Enterprise Linux 4.x, Red Hat Enterprise Linux 4.x, and SUSE Linux Enterprise 10 64-bit platforms. If you encounter this error, click OK. Download and apply the latest 32-bit Management Agent software for these platforms, using the Self Update console, then upgrade the Management Agent using the Upgrade Agents page.

For information on using the Self Update console to download and apply the latest Management Agent software, refer to Oracle Enterprise Manager Cloud Control Basic Installation Guide.