This chapter describes how you can upgrade your central agent and one of your standalone Management Agents to 13c using the Agent Upgrade Console or EM CLI, and how you can create an Agent Gold Image and upgrade all your other standalone Management Agents using that gold image. In particular, this chapter covers the following:
Overview of Upgrading Management Agents Using Agent Gold Images
Setting a Particular Agent Gold Image Version as the Current Version
Updating Standalone Management Agents Using an Agent Gold Image Version
Upgrading Hybrid Cloud Gateway Agents and Hybrid Cloud Agents
WARNING:
You cannot directly subscribe a Shared Agent (NFS Agent) to an Agent Gold Image. To subscribe to an Agent Gold Image, you must first convert the Shared Agent to a standalone Management Agent, and then subscribe to an Agent Gold Image.
Note:
Do not discover any Oracle ZFS Storage Appliance target in 13c environment.
Starting with 13c Release 1, Enterprise Manager Cloud Control offers Agent Gold Images, in addition to the Agent Upgrade Console and EM CLI, to upgrade your Management Agents. Oracle recommends that you use Agent Gold Images to upgrade all your Management Agents, although you can use other upgrade approaches.
To understand what an Agent Gold Image is, what it contains, and how you benefit by using it to upgrade your Management Agents, see Oracle Enterprise Manager Cloud Control Basic Installation Guide.
Oracle recommends that you use Agent Gold Images to upgrade all your Management Agents, although you can use other upgrade approaches. However, to update your Management Agents using a gold image, you need a gold image that is based on a 13c standalone Management Agent. You cannot create a gold image using a 13c central agent.
Therefore, if you are upgrading your Enterprise Manager system from 12c, then after upgrading Oracle Management Service (OMS) to 13c, use the Agent Upgrade Console or EM CLI to upgrade your central agent and one of your standalone Management Agents to 13c. Then, create a gold image using the standalone Management Agent that is upgraded to 13c, and finally update all other standalone Management Agents using that gold image. Once you have updated some of your Management Agents to 13c using the gold image, you can use those updated Management Agents to create several other gold images.
The following is the agent base directory structure before and after the update operation:
Before Update
<agent_base_directory>
|_____agentimage.properties
|_____agentInstall.rsp
|_____agent_inst
|___agent_13.1.0.0.0
After Update
<agent_base_directory>
|_____agentimage.properties
|_____agentInstall.rsp
|_____agent_inst
|_____agent_13.1.0.0.0
|_____GoldImage_<Image Version Name>
|_____agent_13.2.0.0.0
|_____agentimage.properties
|_____agentInstall.rsp
|_____plugins.txt
|_____plugins.txt.status
This section describes how you can upgrade standalone Management Agents to 13c Release 1 or higher using the Agent Upgrade Console or EM CLI. In particular, this section covers the following:
The Agent Upgrade Console 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 (Software Library). When you upgrade a Management Agent using the Agent Upgrade Console, the structure of the installation base directory is modified suitably. The following is an example of the installation base directory structure of a 13c Release 1 Management Agent, when it is upgraded to 13c Release 2:
Before Upgrade
<agent_base_directory>
|agent_13.1.0.0.0
|sbin
|_____plugins
|_____agent_inst
|_____agentimage.properties
.
.
.
After Upgrade
<agent_base_directory>
|_____backup_agtup
|_____agent_13.2.0.0.0
|_____sbin
|_____plugins
|_____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.
(For Microsoft Windows hosts) If you upgrade a 13.2.0.x Management Agent and you want to install another Management Agent on the same host, which points to a different OMS, ensure that you specify the s_agentSrvcName parameter while installing the Management Agent, as described in the Oracle Enterprise Manager Cloud Control Advanced Installation and Configuration Guide.
Before you upgrade your Oracle Management Agents to 13c Release 1 or higher, keep the following points in mind:
You must upgrade the central agent installed along with the old Oracle Management Service (OMS).
Management Agents, including the central agent installed on the OMS host, are not upgraded automatically while you upgrade your OMS to 13c Release 2. Ensure that you upgrade the central agent installed on the OMS host immediately after upgrading the old OMS to 13c Release 2.
Oracle recommends that you upgrade your central agent immediately after upgrading your OMS instances. However, for some reason if you are unable to upgrade your central agent immediately after upgrading the OMS instances, then ensure that you apply the JDK 1.6u95 patch on your central agent. Otherwise, the targets of the GC WLS domain will not be monitored in the Enterprise Manager Cloud Control Console. This issue will not occur once the central agent is upgraded.
You can use the Agent Upgrade Console or EM CLI to upgrade the central agent of only 12c Release 4 (12.1.0.4), 12c Release 5 (12.1.0.5), or 13 c Release 1.
You can upgrade a Management Agent using the Agent Upgrade Console or EM CLI even when you do not have preferred privileged credentials or non-privileged credentials set, or are not aware of the Management Agent credentials. Privileged credentials are only required to run the root.sh script post-upgrade.
If you upgrade a Management Agent as a user who does not have root privileges, or you upgrade a Management Agent without having preferred privileged credentials, a warning appears. You can ignore this warning during the upgrade. Later, you can log in to the Management Agent host as the root user, and run the $<AGENT_BASE_DIR>/agent_13.2.0.0.0/root.sh script.
In some cases, the deployed version of a plug-in may not be supported on the upgraded version of a Management Agent. In these cases, ensure that you either undeploy the plug-ins that are not supported on the upgraded version of the Management Agent, or deploy versions of the plug-ins that are supported on the upgraded Management Agent.
For more information, seehow to undeploy and deploy a plug-in in the Oracle Enterprise Manager Cloud Control Administrator's Guide..
In Enterprise Manager Cloud Control 13c Release 2, you can save the Management Agent one-off patches that you want to apply on a particular version of the Management Agent software, such that these patches are automatically applied on the software whenever a new Management Agent of the same version is deployed, or an old Management Agent is upgraded to that version.
For information on how to do this, see Applying Patches to Oracle Management Agents While Deploying or Upgrading Them in the Oracle Enterprise Manager Cloud Control Advanced Installation and Configuration Guide.
Also, you can apply one-off patches on a plug-in and create a custom patched plug-in, such that this custom patched plug-in is deployed on all the new Management Agents that you deploy, and all the old Management Agents that you upgrade.
For information on how to do this, see Downloading, Deploying, and Upgrading Plug-Ins in the Oracle Enterprise Manager Cloud Control Administration Guide.
Upgrading Management Agents does not require Cygwin, PsExec, or any SSH connectivity tools, as Enterprise Manager uses the existing Management Agent - OMS communication channels to perform the upgrade.
You cannot specify a custom inventory location while upgrading Management Agents. The upgraded Management Agent uses the inventory location of the old Management Agent.
If you select a Management Agent installed on a cluster, or a shared Management Agent for upgrade, the set of related Management Agents, that is, the other Management Agents of the cluster or the shared Oracle Home are selected for upgrade automatically.
You cannot upgrade a Management Agent in the following scenarios:
The Management Agent is not up and running
The Management Agent is not secure
The Management Agent is not reachable
The new Management Agent software (of the same version as the OMS version) is not present in Oracle Software Library (Software Library)
The Management Agent Oracle home property is missing
The Management Agent is already undergoing an upgrade
The Management Agent is in blackout state
Upgrading a lower release of Solaris by applying a kernel patch or a patch bundle is not equivalent to installing the actual Solaris 5.10 Update 10+. Oracle Management Agent 13c Release 2 was built, tested, and certified on a minimum update version of Solaris 5.10 Update 10+, so Oracle recommends that you install Oracle Management Agent only on Solaris 5.10 Update 10+, and not on any release that was upgraded using patches.
You may not be able to upgrade certain Management Agents using the Agent Upgrade Console or EM CLI. Table 6-1 describes the reasons for this.
Table 6-1 Why Some Management Agents Cannot Be Upgraded
| Reason | Description and Recommended Action |
|---|---|
|
Latest Agent Software Missing |
The latest Management Agent software of the OMS version 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, see Self Update console to download and apply the latest Management Agent software, in the 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:
|
|
Oracle Home Property Missing |
The Oracle Home property for the Management Agent is missing. This property is required to obtain the platform of the Management Agent that you want to upgrade. For upgrading Shared Agents, this property plays a key role in maintaining the relationship between the Shared Agent and the Master Agent. It is also required for certain essential Management Agent lifecycle operations, such as patching. To upgrade a Management Agent for which the Oracle Home property is missing, first run the OMS collections on the Management Agent. To do so, do one of the following:
|
|
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 restore communication between the OMS and the Management Agent. 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 displayed error icon, and perform the recommended actions. |
|
Agent Pending Activation |
The Management Agent version is not 12c Release 2 (12.1.0.2) or later. You cannot upgrade 10g, 11g, or 12c Release 1 (12.1.0.1) Management Agents using the Upgrade Agents page. Deinstall these Management Agents and install fresh Management Agents on the hosts. For more information, see deinstalling Management Agents, in the Oracle Enterprise Manager Cloud Control Advanced Installation and Configuration Guide. For more information, see installing fresh Management Agents, in the 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:
From the Setup menu, select Manage Cloud Control, then select Upgrade Agents.
Click Not Upgradable Agents.
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.
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.
Before you upgrade your Management Agents to 13c Release 1 or higher, meet the following prerequisites:
If you want to upgrade a Management Agent running on a platform different from the OMS host platform, ensure that the latest Management Agent software for the platform is downloaded and applied in Software Library, using Self Update.
To access Self Update, from the Setup menu, select Extensibility, then select Self Update. To check whether the latest Management Agent software for a platform is downloaded and applied, click Agent Software, then check the Version and the Status columns for the required platform. The software version for the platform must be the same as the OMS version. The status must read Applied.
If the latest software is not downloaded and applied, select the software, then click Download to download it. After downloading the software, click Apply to apply the software. If the software has been downloaded, but not applied, click Apply to apply the software.
For more information, see using Self Update to download and apply the latest Management Agent software for a platform in the Oracle Enterprise Manager Cloud Control Basic Installation Guide.
Ensure that the Management Agents you want to upgrade are up and running.
To verify if a Management Agent is up and running, from the Setup menu, select Manage Cloud Control, then select Agents. Check the Status column of the required Management Agent.
If the Management Agent is unreachable, click the Management Agent name to navigate to the Management Agent home page. Click the Agent Unreachable icon, and perform the recommended actions.
Ensure that the Management Agents you want to upgrade are secure.
To verify if a Management Agent is secure, from the Setup menu, select Manage Cloud Control, then select Agents. Check the Secure Upload column of the required Management Agent.
If the Management Agent is not secure, from the Agent menu, select Secure to secure it.
Also, you can run the following command to verify if a Management Agent is secure:
<EMSTATE>/bin/emctl status agent
<EMSTATE> refers to the Management Agent instance directory, that is, <AGENT_BASE_DIRECTORY>/agent_inst
If the Management Agent is secure, the Management Agent URL displayed is a HTTPS URL. However, if the Management Agent URL displayed is a HTTP URL, secure the Management Agent by running the following command:
<EMSTATE>/bin/emctl secure agent
Ensure that Oracle home collections are run on all the Management Agents that you want to upgrade.
If Oracle home collections are not run on some Management Agents, they are not upgradable. These Management Agents are displayed on the Not Upgradable Agents page, with the reason displayed as Oracle Home Property Missing. For information on how to access this page, see Table 6-1.
To run Oracle home collections for all the Management Agent that you want to upgrade, run the following command from the Management Agent host:
<EMSTATE>/bin/emctl control agent runCollection <TARGET_NAME>:oracle_home oracle_home_config
<EMSTATE> refers to the Management Agent instance directory, that is, <AGENT_BASE_DIRECTORY>/agent_inst
<TARGET_NAME> refers to the Management Agent home listed as oracle_home in the <EMSTATE>/sysman/emd/targets.xml file. You can also verify using the emctl config agent listtargets command.
Ensure that the old Management Agent does not come up during the Management Agent upgrade process.
You may have scheduled certain cron jobs, or configured certain notification managers that start up a Management Agent when it is down. The old Management Agent is shut down as part of the upgrade process. Ensure that this Management Agent is not brought up.
Ensure that the install user has read permissions on all the files present in Oracle Inventory, and write permissions on the Oracle Inventory directory.
To grant read permissions on all the files present in Oracle Inventory, run the following command as the install user:
chmod -R +r $<INVENTORY_LOCATION>
To grant write permissions on the Oracle Inventory directory, run the following command as the install user:
chmod +rw $<INVENTORY_LOCATION>
Ensure that you meet the hardware requirements described in the Oracle Enterprise Manager Cloud Control Basic Installation Guide.
To upgrade your Management Agents to 13c Release 1 or higher using the Agent Upgrade Console, follow these steps:
Table 6-2 describes the additional parameters you can use while upgrading 13c Management Agents using Agent Upgrade Console, or EM CLI. You can enter more than one parameter, using a whitespace as a separator.
Table 6-2 List of Additional Parameters for 13c 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. |
|
SCRATCHPATH |
Specify this parameter if you do not have enough space on |
To upgrade your Management Agents to 13c Release 1 or higher using EM CLI, follow these steps:
Note:
For more information on how to use the EM CLI verbs mentioned in this section, see Using Basic Operational Verbs in the Oracle Enterprise Manager Command Line Interface Guide.
This section describes the various tasks you can perform after upgrading your Management Agents. It consists of the following:
This section describes how to verify the 13c Management Agent upgrade. It consists of the following sections:
After you upgrade your Management Agents, follow these methods to verify the upgrade using the Enterprise Manager console:
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 that you want to verify the upgrade for, and verify the Management Agent version. The Management Agent version after the upgrade must be the same as the OMS version.
Also, on the Agents page, verify that the Management Agent is up and running, is not blocked, and is not under blackout.
From the Setup menu, select Manage Cloud Control, then select Agents. Click the name of the Management Agent that you want to verify the upgrade for. From the Agent menu, select Configuration, then select Latest. In the Configuration Properties tab, ensure that none of the configuration properties mention the old Management Agent home.
After you upgrade your Management Agents, follow these methods to verify the upgrade using EM CLI:
Run the get_agent_upgrade_status verb to verify that the job you created to upgrade the Management Agents succeeded. This is described in detail in Step 5 of Upgrading Central Agents or Standalone Management Agents to 13c Release 2 Using EM CLI.
Run the get_agent_properties verb to verify the version of the Management Agent and its configuration properties after the upgrade:
$<ORACLE_HOME>/bin/emcli get_agent_properties -format=csv -agent_name=<agent_host_name>:<agent_port>
For example,
/u01/software/em13c/oraclehome/bin/emcli get_agent_properties -format=csv -agent_name=abc.example.com:1872
Run the get_targets verb to verify the status of the Management Agent (it should be up and running, and not be blocked, under blackout, etc.):
$<ORACLE_HOME>/bin/emcli get_targets -format="name:csv" -targets=<agent_host_name>:<agent_port>:oracle_emd -alerts
For example,
/u01/software/em13c/oraclehome/bin/emcli get_targets -format="name:csv" -targets=abc.example.com:3872:oracle_emd -alerts
After you upgrade your Management Agents to 13c Release 1 or higher, the old agent homes, old Oracle Home targets, and backup directories of the old Management Agents remain, and are not deleted automatically. To delete these post upgrade and free up disk space, you can clean up the old Management Agents using Agent Upgrade Console or EM CLI.
Important:
Ensure that you perform clean up only on those Management Agents that were upgraded successfully. For information on verifying whether a Management Agent was upgraded successfully, see Verifying Your 13c Management Agent Upgrade.
This section describes the methods you can use to clean up 13.2.0.x Management Agents after upgrading them. It consists of the following:
To clean up the old directories of your old Management Agents using the Clean Up Agents page of the Agent Upgrade Console, follow these steps:
To clean up the old directories of your old Management Agents using EM CLI, follow these steps:
Note:
For more information on how to use the EM CLI verbs mentioned in this section, see Using Basic Operational Verbs in the Oracle Enterprise Manager Command Line Interface Guide.
After upgrading the central agent, if the agent base directory of the upgraded central agent resides within the Oracle Middleware home, and you want to move it outside the Oracle Middleware home, then see Moving the Central Agent Base Directory Outside Oracle Middleware Home.
Important:
Moving the agent base directory is recommended only for central agents (on all platforms, including Microsoft Windows), and not recommended for standalone Management Agents.
You can use the Clean Up Agents page or EM CLI to delete the old agent homes, old Oracle Home targets, and backup directories of your old Management Agents, after upgrading them. Once you select the Management Agents you want to clean up and click Submit on the Clean Up Agents page, or run the signoff_agents EM CLI verb, a Management Agent clean up job is created, which is sent to the Enterprise Manager job system. You can use the Clean Up Agent Results page, or the get_signoff_status EM CLI verb to search for and view a particular set of Management Agent clean up jobs.
This section describes the methods you can use to view a particular set of Management Agent clean up jobs. It consists of the following:
To view a particular set of Management Agent clean up jobs using the Clean Up Agent Results page of the Agent Upgrade Console, follow these steps:
To view a particular set of Management Agent clean up jobs using EM CLI, follow these steps:
Note:
For more information on how to use the EM CLI verbs mentioned in this section, see Using Basic Operational Verbs in the Oracle Enterprise Manager Command Line Interface Guide.
Table 6-3 describes how to troubleshoot certain errors you may encounter while upgrading your Management Agents.
Table 6-3 Troubleshooting Oracle Management Agent Upgrade
| Problem | Troubleshooting Tip |
|---|---|
|
When you click Submit on the Upgrade Agents page, you encounter an error mentioning that |
Do one of the following:
|
|
When you click Submit on the Upgrade Agents page, you encounter an error mentioning that |
Do one of the following:
|
|
When you click Submit on the Upgrade Agents page, you encounter an error mentioning that |
Do one of the following:
|
|
When you click Submit on the Upgrade Agents page, the Upgrade Agents step fails. |
Diagnose the problem by following these steps:
|
|
The Management Agent cannot be upgraded as the 32-bit Management Agent software for the host platform is not present in 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. For more information see, using the Self Update console to download and apply the latest Management Agent software in the Oracle Enterprise Manager Cloud Control Basic Installation Guide . |
|
The links on the Agent Upgrade Status page or the Agent Upgrade Results page are not working. |
Diagnose the problem by viewing the following logs:
|
|
A job step in the Management Agent upgrade process hangs or is executed multiple times. |
Diagnose the problem by viewing the following log:
|
|
EM CLI log in or synchronization fails. |
Diagnose the problem by viewing the following log:
|
|
The upgraded Management Agent is blocked. |
Raise an Oracle Support service request. Do not resynchronize the Management Agent. |