6.8 Updating Standalone Management Agents Using an Agent Gold Image Version

Important:

Before updating standalone Management Agents using an Agent Gold Image, ensure that the standalone Management Agents subscribe to the gold image. For information on how to subscribe standalone Management Agents to an Agent Gold Image, see Subscribing Management Agents to an Agent Gold Image.

You cannot update a central agent with an Agent Gold Image. A central agent is a Management Agent that is installed by default with every OMS installation.

Note:

You cannot install, update, or upgrade a Shared Agent (NFS Agent) using an Agent Gold Image. For information about Shared Agents, see Oracle Enterprise Manager Cloud Control Advanced Installation and Configuration Guide.

Note:

To view a visual demonstration of how you update Oracle Management Agents using Agent Gold Images, access the following URL and click Begin Video.

https://apexapps.oracle.com/pls/apex/f?p=44785:24:0:::24:P24_CONTENT_ID,P24_PREV_PAGE:12796,1

To update your standalone Management Agents using an Agent Gold Image version, use either of the following methods:

6.8.1 Updating Standalone Management Agents Using Agent Gold Image Version Using Gold Agent Images Home Page

To update your Management Agents using an Agent Gold Image version, follow these steps:

Note:

Before updating a standalone Management Agent using an Agent Gold Image version, meet the hardware requirements as described in the hardware requirements chapter of the Oracle Enterprise Manager Cloud Control Basic Installation Guide.

Note:

When you have to update a set of related Management Agents to an Agent Gold Image, it is mandatory to update all the related agents. However, there is an option to override this in case if you want to update only a selected few Agents to the Agent Gold Image. To achieve this, you have to set the parameter closureRelated to false in the EM_GI_MASTER_INFO table.

From the Setup menu, select Manage Cloud Control, then select Gold Agent Images.
Click the name of the required Agent Gold Image.
Click Manage Image Versions and Subscriptions.
Select the Subscriptions tab. Select the Management Agents that you want to update, select Update, then select To Current Version, or To Restricted Version.
Accept the default job name for the Management Agent update job. You can change this, if required.

If you have not included certain Management Agents in the previous step and want to include them in the update operation now, select Add, then specify the additional Management Agents.

If there is any change to the sbin directory, particularly for a complete agent upgrade or when there is an sbin-specific patch, after updating the Management Agent, the preferred privileged credentials of the Management Agent host are used for running the root.sh script on the Management Agent.

If these credentials are not already set, then click Override Preferred Credentials and enter the credentials you want to use instead.

Click Next.
By default, Image Version Pre Staged is not selected, in this case provide a stage location that is local to the destination host. However, if you select the Image version Pre Staged, provide a shared, NFS-mounted stage location that is accessible by all the Management Agents.

Also, specify a method for Management Agent deployment. If you select the default option Push, the OMS transfers the Management Agent software to all the hosts that are selected for the update operation. However, if you want the Management Agent present on each destination host to retrieve the Management Agent software from the OMS instead, select Pull.
In the Additional Inputs section, specify any scripts that you want to run before the update operation and after the update operation. Ensure that you select Script on OMS Host if the script exists on the OMS host. Also, specify any additional parameters that you want to use for the update operation. Table 6-2 gives a list of additional parameters used for upgrade.
In the Schedule section, specify values for the following:
- Batch Size: A Management Agent update activity runs in a way that the Management Agents are updated in batches. The batch size represents the number of Management Agents present in a batch.
- Job Frequency: The time (in minutes) after which the application checks whether the current batch is complete or not.
- Success Rate: The percentage of the total number of Management Agents (that is, the Management Agents that are a part of the current update batch and the Management Agents that were a part of the previous update batches) that must have been updated once a batch is complete, before the next batch is allowed to begin.
  
  For example, if there are 1000 Agents deployed in your enterprise and the batch size is set to 100, the batch success rate is set to 90, and the Agents are updated in batches of 100. In this case, once a batch is complete, the application moves to the next batch only if 90 per cent of the total number of Management Agents are updated successfully.
- Start: The time when you want to start the update operation, and the time when you want the update operation to end. By default, the time set is Immediately. In this context, it is the OMS time that is considered.
- Duration: The duration until which you want the update operation to run.
In the Notify section, specify the email addresses to which you want the notifications about the update job progress to be sent.
In the Shell Profile section, select Update Shell Profile, and specify the location of your shell profile, if you want your shell profile to be updated with the new Management Agent Oracle home location.

By default, this is not selected, and is optional.
In the Cleanup options section, select:
- Pre-Cleanup to clean up the old or inactive agent homes prior to updating the Management Agents.
- Post-Cleanup to clean up the old or inactive agent homes after updating the Management Agents.
  
  Note:
  
  If the cleanup operation is not performed at this point, it can be done at a later time using the Agent Upgrade Console. For more information, see Performing Postupgrade Cleanup of Old Management Agents.
A job that updates the Management Agents is submitted to the Enterprise Manager job system. You can view the status of this job on the Gold Agent Image Activities page, in the Update Activities tab.
Click Update.

A job that updates the Management Agents is submitted to the Enterprise Manager job system. You can view the status of this job on the Gold Agent Image Activities page, in the Update Activities tab.

When you create an image version and update a Management Agent with it, Enterprise Manager Cloud Control uses the image version name you provide here to create a subdirectory in the agent base directory for the Management Agent being updated.

For example, if the agent base directory of the Management Agent being updated is /u01/software/em13c/agentbasedir, and the agent home is /u01/software/em13c/agentbasedir/agent_13.2.0.0.0, and if you provide OPB_BP1 as the image version name, then when you update the Management Agent with the image version, a new subdirectory /u01/software/em13c/agentbasedir/GoldImage_OPB_BP1/agent_13.2.0.0.0 is created.

6.8.2 Updating Management Agents Using Agent Gold Image Version Using EM CLI

To update Management Agents using an Agent Gold Image version, using EM CLI, follow these steps:

Note:

Log in to EM CLI from the /bin directory present within the Oracle home of the OMS:
```
$<ORACLE_HOME>/bin/emcli login -username=<user_name>
```
Once you run this command, EM CLI will prompt you for a password. Enter the password for the user name you specified.
Synchronize EM CLI:
```
$<ORACLE_HOME>/bin/emcli sync
```

Run the get_updatable_agents verb to display the Management Agents that can be updated using a particular Agent Gold Image version or Agent Gold Image:

$<ORACLE_HOME>/bin/emcli get_updatable_agents
-version_name  | -image_name
[-agents="Full Agent Name"]
[-versions="List of Versions"]
[-groups="List of group names"]
[-output_file="Location of the output file"]

Note that the parameters mentioned in [ ] are optional.

Note:

It is mandatory to specify the -version_name parameter or the -image_name parameter. If you specify both, a union of the outputs (when each of these parameters is specified individually) is displayed.

Note:

To view a list of Management Agents that cannot be updated, run the get_not_updatable_agents verb:

emcli get_not_updatable_agents 
        [-version_name  | -image_name]

The parameters mentioned in [ ] are optional.

Table 6-5 lists and describes the supporting parameters for displaying the Management Agents that can be updated using a particular Management Agent image version.

Table 6-5 Supported Parameters for Displaying Management Agents That Can Be Updated

Parameter	Description
`-version_name`	Specify this option to display the Management Agents that can be updated using the specified Agent Gold Image version.
`-image_name`	Specify this option to display the Management Agents that can be updated using the specified Agent Gold Image.
`-versions`	Specify this option to display the Management Agents that can be updated, and are of the specified versions.
`-agents`	Specify this option to display the Management Agents that can be updated, and whose name matches the specified name pattern.
`-groups`	Specify this option to display the Management Agents that can be updated, and are a part of those groups whose name matches the specified name pattern.
`-output_file`	Specify this option to add the displayed list of Management Agents that can be updated to an output file.

Examples:

The following example lists the Management Agents that can be updated using the latest Agent Gold Image OPC_AGT_ADC_POD:
```
<ORACLE_HOME>/bin/emcli get_updatable_agents -image_name="OPC_AGT_ADC_POD"
```
The following example lists the Management Agents that can be updated using the Agent Gold Image version OPC_AGT_ADC_POD_JUNE:
```
<ORACLE_HOME>/bin/emcli get_updatable_agents -version_name="OPC_AGT_ADC_POD_JUNE"
```
The following example lists the Management Agents that are of version 12.1.0.4.0, 12.1.0.5.0, or 13.1.0.0.0 and can be updated using the Agent Gold Image version OPC_AGT_ADC_POD_JUNE:
```
<ORACLE_HOME>/bin/emcli get_updatable_agents -version_name="OPC_AGT_ADC_POD_JUNE" -versions=" 12.1.0.4.0,12.1.0.5.0, 13.1.0.0.0"
```
The following example lists the Management Agents that belong to GROUP1 or GRP2, and can be updated using the Agent Gold Image version OPC_AGT_ADC_POD_JUNE:
```
<ORACLE_HOME>/bin/emcli get_updatable_agents -version_name="OPC_AGT_ADC_POD_JUNE" -groups="GROUP1,GRP2"
```
The following example lists the Management Agents that can updated using the Agent Gold Image OPC_AGT_ADC_POD_JUNE, and adds the list to the output file /scratch/agents_file.txt:
```
<ORACLE_HOME>/bin/emcli get_updatable_agents -image_name="OPC_AGT_ADC_POD_JUNE" -output_file="/scratch/agents_file.txt"
```

Run the update_agents verbs to prepare the environment for updating your Management Agents and to submit the Management Agent update job:

<ORACLE_HOME>/bin/emcli update_agents 
        -version_name | -image_name  
        -agents="agent_names" | -input_file="agents_file:input_file_location" 
        [-pre_script_loc="location_of_pre_script"]
        [-pre_script_on_oms]
        [-post_script_loc="location_of_post_script"]
        [-post_script_on_oms]
        [-op_name="custom_operation_name"]
        [-override_credential="named_credential"]
        [-additional_parameters]
        [-stage_location="custom_stage_location"]
        [-is_staged="true|false"]
        [-stage_action="push|pull"]
        [-batch_size]
        [-start_time]
        [-end_time]
        [-frequency]<
        [-success_rate] 
        [-runPrecleanup]
        {-runPostcleanup]
        [-email]
        [-update_profile]
        [-profile_path]

Note that the parameters mentioned in [ ] are optional.

Note:

It is mandatory to specify the -version_name parameter or the -image_name parameter. Also, it is mandatory to specify the -agents parameter or the -input_file parameter. If you specify both -agents and -input_file, a union of the outputs (when each of these parameters is specified individually) is displayed.

All parameters can be passed in a response file, using the -input_file parameter. For example, -input_file="response_file:/scratch/response_file.txt".

In the response file, each parameter must be specified on a new line, and in name value pairs. For example, op_name=UPDATE_AGT_121020

If the same parameter is passed both on the command line and in the response file, the value of the command line parameter is given precedence.

Table 6-6 lists and describes the supporting parameters for updating Management Agents using an Agent Gold Image version.

Table 6-6 Supported Parameters for Updating Management Agents Using Agent Gold Image Version

Parameter	Description
`-version_name`	Agent Gold Image version to which the Management Agents should be updated.
`-image_name`	Agent Gold Image to which the Management Agents should be updated.
`-agents`	Names of all the Management Agents that should be updated.
`-input_file`	Absolute path to the file that lists the Management Agents to be updated.
`-pre_script_loc`	Absolute path to a script that should be run before updating the Management Agents.
`-pre_script_on_oms`	Indicates that the pre-script is present on the OMS host.
`-post_script_loc`	Absolute path to a script that should be run after updating the Management Agents.
`-post_script_on_oms`	Indicates that the post-script is present on the OMS host.
`-op_name`	Custom operation name for the Management Agent update.
`-override_credential`	Overrides the preferred credentials with different named credentials. Typically, the preferred credentials of the Oracle home of the Management Agent are used to run root.sh on certain Management Agents after the update. But passing this option overrides those preferred credentials.
`-additional_parameters`	Additional parameters to be passed for the Management Agent update.
`-stage_location`	Custom stage location for the Management Agent update. Minimum free space required is 1 GB if image is not already staged. Ensure that this location is accessible from all the Management Agents being updated if image is prestaged.
`-is_staged`	Set to 'true' if you have already staged the Agent Gold Image.
`-stage_action`	Set to 'pull' if you want the Management Agents to be updated to pull the Agent Gold Image. Typically, If the Agent Gold Image has not already been staged, by default the Agent Gold Image is pushed to the Management Agents to be updated. Setting to 'pull' pulls the Agent Gold Image instead.
`-batch_size`	Number of Management Agents present in an update batch. Default value is 100.
`-start_time`	Start time for the update job. Specify in \" yyyy-mm-dd hh:mm:ss\" format.
`-end_time`	End time for the update job. Specify in \" yyyy-mm-dd hh:mm:ss\" format.
`-frequency`	Time (in minutes) after which the application should check whether or not the current batch is complete, and should schedule the next batch for update. Default value is.
`-success_rate`	Percentage of the total number of Management Agents that must have been successfully updated in previous batches, before the next batch is allowed to begin. Default value is 90.
`-runPrecleanup`	Cleans up the old agent homes before updating the Management Agents.
`-runPostcleanup`	Cleans up the old agent homes after updating the Management Agents.
`-email`	Email IDs separated by a comma (,) to which notifications should be sent once the batch completes.
`-update_profile`	Indicates that a profile is set with agent Oracle home.
`-profile_path`	Absolute path to user profiles separated by a comma (,) if the update profile option is selected.

Examples:

The following example updates xyz.domain.com:1243 using the latest Agent Gold Image in the series OPC_AGT_ADC_POD:
```
<ORACLE_HOME>/bin/emcli update_agents -gold_image_series="OPC_AGT_ADC_POD" -agents="xyz.domain.com:1243"
```

The following example updates xyz.domain.com:1243 using the Agent Gold Image OPC_AGT_ADC_POD_JUNE:

<ORACLE_HOME>/bin/emcli update_agents -gold_image_name="OPC_AGT_ADC_POD_JUNE" -agents="xyz.domain.com:1243"

The following example updates all the Management Agents present in the input file /scratch/agents_file.txt using the Agent Gold Image OPC_AGT_ADC_POD_JUNE:
```
<ORACLE_HOME>/bin/emcli update_agents -gold_image_name="OPC_AGT_ADC_POD_JUNE" -input_file="agents_file:/scratch/agents_file.txt"
```

The following example runs /scratch/pre_script, then updates xyz.domain.com:1243 using the Agent Gold Image OPC_AGT_ADC_POD_JUNE:

<ORACLE_HOME>/bin/emcli update_agents -gold_image_name="OPC_AGT_ADC_POD_JUNE" -agents="xyz.domain.com:1243" -pre_script_loc="/scratch/pre_script"

The following example updates xyz.domain.com:1243 using the Agent Gold Image OPC_AGT_ADC_POD_JUNE, then runs /scratch/post_script:

<ORACLE_HOME>/bin/emcli update_agents -gold_image_name="OPC_AGT_ADC_POD_JUNE" -agents="xyz.domain.com:1243" -post_script_loc="/scratch/post_script"

The following example updates xyz.domain.com:1243 (creates an update job UPDATE_JOB123) using the Agent Gold Image OPC_AGT_ADC_POD_JUNE:

<ORACLE_HOME>/bin/emcli update_agents -gold_image_name="OPC_AGT_ADC_POD_JUNE" -agents="xyz.domain.com:1243" -op_name="UPDATE_JOB123"

The following example updates xyz.domain.com:1243 using the Agent Gold Image OPC_AGT_ADC_POD_JUNE, and uses NAMED_CRED123 to run root.sh after the update:
```
<ORACLE_HOME>/bin/emcli update_agents -gold_image_name="OPC_AGT_ADC_POD_JUNE" -agents="xyz.domain.com:1243" -override_credential="NAMED_CRED123"
```

The following example updates xyz.domain.com:1243 using the Agent Gold Image OPC_AGT_ADC_POD_JUNE, passing two additional parameters:

<ORACLE_HOME>/bin/emcli update_agents -gold_image_name="OPC_AGT_ADC_POD_JUNE" -agents="xyz.domain.com:1243" -additional_parameters="-ignorePrereqs -newParameter"

The following example updates xyz.domain.com:1243 using the latest Agent Gold Image in the series OPC_AGT_ADC_POD, passing two additional parameters:

<ORACLE_HOME>/bin/emcli update_agents -gold_image_series="OPC_AGT_ADC_POD" -agents="xyz.domain.com:1243" -additional_parameters="-ignorePrereqs -newParameter"

The following example updates xyz.domain.com:1243 using the latest Agent Gold Image in the series OPC_AGT_ADC_POD, without staging the gold image:
```
<ORACLE_HOME>/bin/emcli update_agents -gold_image_series="OPC_AGT_ADC_POD" -agents="xyz.domain.com:1243" -is_staged="true"
```
The following example updates xyz.domain.com:1243 using the latest Agent Gold Image in the series OPC_AGT_ADC_POD, and the gold image is pulled by xyz.domain.com:1243:
```
<ORACLE_HOME>/bin/emcli update_agents -gold_image_series="OPC_AGT_ADC_POD" -agents="xyz.domain.com:1243" -stage_action="pull"
```
The following example runs the Management Agent update with maximum of 150 Management Agents getting updated in each batch:
```
<ORACLE_HOME>/bin/emcli update_agents -image_name="OPC_AGT_ADC_POD" -agents="xyz.domain.com:1243" -batch_size=150
```
The following example runs the Management Agent update with maximum of 150 Management Agents getting updated in each batch:

Note:

The next batch gets scheduled only if 80% of the Management Agents are successfully updated in the previous batches.
```
<ORACLE_HOME>/bin/emcli update_agents -image_name="OPC_AGT_ADC_POD" -agents="xyz.domain.com:1243" -batch_size=150 success_rate=80
```

The following example schedules the agent update job starting at May 7, 10:00:00 AM and ending at May 8, 10:00:00 AM:

<ORACLE_HOME>/bin/emcli update_agents -image_name="OPC_AGT_ADC_POD" -agents="xyz.domain.com:1243" -start_time="2014-05-07 10:00:00" -end_time="2014-05-08 10:00:00"

Run the get_agent_update_status verb to displays the update results of the Management Agent:

<ORACLE_HOME>/bin/emcli get_agent_update_status 
        -version_name | -op_name 
        [-agent="agent_name_pattern"] 
        [-severity="ERROR|WARNING"] 
        [-severity_id="severity_id"] 
        [-status="PendingUpdateInprogress|Updatable|NotUpdatable|NotExecuted|Success|Inprogress|Failed"]

Note that the parameters mentioned in [ ] are optional.

Note:

It is mandatory to specify the -op_name parameter or the -version_name parameter. If you have specified -severity or -severity_id, ensure that you do not specify -version_name or -status.

Table 6-7 lists and describes the supporting parameters for displaying the update status of the Management Agent.

Table 6-7 Supported Parameters for Displaying Update Status of the Management Agent

Parameter	Description
`-version_name`	Displays the details of the update operation submitted for the specified Agent Gold Image version name.
`-op_name`	Displays the details of the specified update operation.
`-agent`	Displays the details of the operations submitted for Management Agents that have the specified name pattern.
`-status`	Displays the details of the update operations that have the specified status.
`-severity`	Displays the details of the update operations that have the specified severity level.
`-severity_id`	Displays the details of the update operations that have the specified severity ID

Examples:

The following example displays the details of the update operations submitted for the Agent Gold Image version OPC_AGT_ADC_POD_JUNE:
```
<ORACLE_HOME>/bin/emcli get_agent_update_status -version_name="OPC_AGT_ADC_POD_JUNE"
```
The following example displays the details of the update operations submitted for the Agent Gold Image OPC_AGT_ADC_POD_JUNE, for the Management Agent xyz.domain.com:1243:
```
<ORACLE_HOME>/bin/emcli get_agent_update_status -version_name="OPC_AGT_ADC_POD_JUNE" -agent="xyz.domain.com:1243"
```
The following example displays the details of the update operations submitted for the Agent Gold Image OPC_AGT_ADC_POD_JUNE, for the Management Agent xyz.domain.com:1243, that have their status as Failed:
```
<ORACLE_HOME>/bin/emcli get_agent_update_status -version_name="OPC_AGT_ADC_POD_JUNE" -agent="xyz.domain.com:1243" -status="Failed"
```
The following example displays the details of the update operation UPDATE_JOB123:
```
<ORACLE_HOME>/bin/emcli get_agent_update_status  -op_name="UPDATE_JOB123"
```
The following example displays the details of the update operation UPDATE_JOB123, for the Management Agent xyz.domain.com:1243:
```
<ORACLE_HOME>/bin/emcli get_agent_update_status -op_name="UPDATE_JOB123" -agent="xyz.domain.com:1243"
```
The following example displays the details of the update operation UPDATE_JOB123, for Management Agents having the status Failed:
```
<ORACLE_HOME>/bin/emcli get_agent_update_status -op_name="UPDATE_JOB123" -status="Failed"
```
The following example displays the details of the update operation UPDATE_JOB123 for the Management Agent xyz.domain.com:1243, having the status Failed:
```
<ORACLE_HOME>/bin/emcli get_agent_update_status -op_name="UPDATE_JOB123" -status="Failed" -agent="xyz.domain.com:1243"
```
The following example displays the Management Agents of the update operation UPDATE_JOB123, for which severity is ERROR:
```
<ORACLE_HOME>/bin/emcli get_agent_update_status  -op_name="UPDATE_JOB123" -severity="ERROR"
```
The following example displays the Management Agents of the update operation UPDATE_JOB123, for which severity is WARNING, and severity ID is ROOT_RUN_CHECK:
```
<ORACLE_HOME>/bin/emcli get_agent_update_status  -op_name="UPDATE_JOB123" -severity="WARNING" -severity_id="ROOT_RUN_CHECK"
```
The following example displays the Management Agents of the update operation UPDATE_JOB123, for which severity ID is ROOT_RUN_CHECK:
```
<ORACLE_HOME>/bin/emcli get_agent_update_status  -op_name="UPDATE_JOB123" -severity_id="ROOT_RUN_CHECK"
```
The following example displays the details of the update operation UPDATE_JOB123 for the Management Agent xyz.domain.com:1243, with severity as ERROR:
```
<ORACLE_HOME>/bin/emcli get_agent_update_status  -op_name="UPDATE_JOB123" -severity="ERROR"  -agent="xyz.domain.com:1243"      
```
The following example displays the details of the update operation UPDATE_JOB123 for the Management Agent xyz.domain.com:1243, with severity ID as ROOT_RUN_CHECK:
```
<ORACLE_HOME>/bin/emcli get_agent_update_status  -op_name="UPDATE_JOB123" -severity_id="ROOT_RUN_CHECK"  -agent="xyz.domain.com:1243"
```
The following example displays the details of the update operation UPDATE_JOB123 for the Management Agent xyz.domain.com:1243, with severity as WARNING and severity ID as ROOT_RUN_CHECK:
```
<ORACLE_HOME>/bin/emcli get_agent_update_status  -op_name="UPDATE_JOB123" -severity="WARNING" -severity_id="ROOT_RUN_CHECK"  -agent="xyz.domain.com:1243"
```
The following example displays the Management Agents of the update operation UPDATE_JOB123, for which severity is ERROR:
```
<ORACLE_HOME>/bin/emcli get_agent_update_status  -op_name="UPDATE_JOB123" -severity="ERROR"
```