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 5 Management Agent, when it is upgraded to 24ai Release 1:

Before Upgrade

<agent_base_directory>
    |agent_13.5.0.0.0
    		|sbin
    		|_____plugins
    |_____agent_inst
    |_____agentimage.properties
    .
    .
    .

After Upgrade

<agent_base_directory>
		|_____backup_agtup
		|_____agent_24.1.0.0.0
				|_____sbin
				|_____plugins
		|_____agent_inst
		|_____agentimage.properties
    .
    .
    .

1. From the Setup menu, select Manage Enterprise Manager, then select Upgrade Agents.
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 consist of alphanumeric and special characters, and can begin with either of these.

3. Click Add to select the Management Agents you want to upgrade.

   In the Upgradable Agents window, search for the Management Agents you want to upgrade, using the Agent, Installed Version, Platform, and Group fields.

   Select the Management Agents you want to upgrade. Click OK.

   Important:

   • In this release, you can only upgrade your 13c Release 5 Management Agents to 24ai Release 1, and not to any other version.

   • If you select a Management Agent that is part of a particular group for upgrade, the other Management Agents of the group are not selected for upgrade by default. If you want to upgrade the other Management Agents of the group, you must select them in the Upgradable Agents window.

4. (Optional) For Pre-upgrade Script and Post-upgrade Script, enter the absolute path of the script that 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 (on all the OMS hosts in case of a multi-OMS environment), 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.

   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 installed on different platforms 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. If you want to specify multiple additional parameters, separate them using a space.

   Refer to Additional Parameters for 24ai Release 1 Management Agent Upgrade for a list of parameters you can specify.

6. For Stage Location, accept the default stage location, or enter a custom location. The stage location is used to store temporary Management Agent upgrade files.

   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. If the stage location you specify and the agent base directory of the Management Agent you want to upgrade are present on the same disk, then ensure that the disk has at least 3 GB of free space. If they are present on different disks, ensure that the stage directory has at least 2.1 GB of free space, and the agent base directory has at least 750 MB of free space.

   If you want to use a different stage location other than /tmp, you must pass the SCARTCHPATH value in the additional parameter in Agent Upgrade Console.

   For example, SCRATCHPATH=/u01/app/stage.

7. Click Submit.

   Once you click Submit, a Management Agent upgrade job is created, which is sent to the Enterprise Manager job system. You are automatically taken to the Agent Upgrade Status page for the job, which displays the details of the job steps.

   To view a summary of all the submitted Management Agent upgrade jobs, or search for and view a particular set of Management Agent upgrade jobs, use the Agent Upgrade Results page of the Agent Upgrade Console. To access this page, from the Setup menu, select Manage Enterprise Manager, then select Upgrade Agents. Click Agent Upgrade Results.

   To revisit the Agent Upgrade Status page for a Management Agent upgrade job, click the name of the job on the Agent Upgrade Results page.

   If you encounter an error during the Management Agent upgrade process, or if the Management Agent upgrade fails, refer to Troubleshooting 24ai Release 1 Management Agent Upgrade.

8. If the root.sh step was skipped, or if this step failed, log in to the Management Agent host as the root user, navigate to $<AGENT_BASE_DIR>/agent_24.1.0.0.0/ and run the root.sh script on the host manually.

   After root.sh is run, you can clean up your old Management Agents, as described in Performing Postupgrade Cleanup of Old Management Agents.

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

   For example,

   /u01/software/em24/middleware/oms_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.

2. Synchronize EM CLI:

   $<ORACLE_HOME>/bin/emcli sync

   For example,

   /u01/software/em24/middleware/oms_home/bin/emcli sync

3. Run the get_upgradable_agents verb to obtain a list of the Management Agents that can be upgraded:

   emcli get_upgradable_agents
                         [-agents="agent_name_search_pattern"]
                         [-platforms="platform_search_pattern"]
                         [-versions="version_search_pattern"]
                         [-groups="group_search_pattern"]
                         [-output_file="output_file_location"]
   

   Note that the parameters mentioned in [ ] are optional.

   For example,

   /u01/software/em24/middleware/oms_home/bin/emcli get_upgradable_agents -agents="abc%,xyz.example.com:1243" -platforms="Linux x86,Microsoft Windows x64 (64-bit)" -versions="24.1.0.0.0" -output_file="/scratch/agents_file.txt"

   Use the -output_file option to copy the list of upgradable Management Agents into a file. This file can be used later as an input parameter for the upgrade_agents verb.

   To view more information on the syntax and the usage of the get_upgradable_agents verb, run the following command:

   $<ORACLE_HOME>/bin/emcli/help get_upgradable_agents

4. Run the upgrade_agents verb to upgrade your Management Agents:

   emcli upgrade_agents
   -agents="names_of_agent_targets" |
   -input_file="agents_file:location_of_input_file"
                         [-allowMd5="true|false"]
                         [-validate_only]
                         [-pre_script_loc="location_of_pre_script"]
                         [-pre_script_on_oms]
                         [-post_script_loc="location_of_post_script"]
                         [-post_script_on_oms]
                         [-job_name="custom_job_name"]
                         [-override_credential="named_credential"]
                         [-additional_parameters]
                         [-stage_location="custom_stage_location"]
   

   Note that the parameters mentioned in [ ] are optional.

   Ensure that you specify all the Management Agents that you want to upgrade by using either -agents, or -input_file="agents_file:<file_name>", or by specifying agents in a response file, and then using -input_file="response_file:<absolute_location>".

   For example,

   /u01/software/em24/middleware/oms_home/bin/emcli upgrade_agents -agents="abc%,xyz.example.com:1243" -input_file="agents_file:/scratch/agents_file.txt" -input_file="response_file:/scratch/agent.rsp" -stage_location=/tmp

   The parameters that you specify with the verb override the parameters that you specify in the response file.

   To view more information on the syntax and the usage of the upgrade_agents verb, run the following command:

   $<ORACLE_HOME>/bin/emcli help upgrade_agents
   

   If you encounter an error during the Management Agent upgrade process, or if the Management Agent upgrade fails, refer to Troubleshooting 24ai Release 1 Management Agent Upgrade.

5. To view the status of the submitted Management Agent upgrade jobs, run the get_agent_upgrade_status verb:

   $<ORACLE_HOME>/bin emcli get_agent_upgrade_status
                         [-agent]
                         [-job_name]
                         [-status]
   

   Note that the parameters mentioned in [ ] are optional.

   For example,

   /u01/software/em24/middleware/oms_home/bin/emcli get_agent_upgrade_status -status="Running" will display all the Management Agent upgrade jobs that are in progress.

   You can view the detailed job step status of a particular Management Agent that was part of a particular upgrade job by using the get_agent_upgrade_status verb with the -agent and the -job_name options.

   For example,

   /u01/software/em24/middleware/oms_home/bin/emcli get_agent_upgrade_status -agent=abc.example.com:1243 -job_name=UPGRADE_AGT_13603

   If a particular Management Agent upgrade job failed, check the inputs and run the upgrade_agents verb again. If you want to specify a custom job name (using the -job_name parameter) while retrying the verb, ensure that you provide a unique job name, and not the name of the job that failed. For Management Agent upgrade troubleshooting tips, see Troubleshooting 24ai Release 1 Management Agent Upgrade.

   To view more information on the syntax and the usage of the get_agent_upgrade_status verb, run the following command:

   $<ORACLE_HOME>/bin/emcli/help get_agent_upgrade_status

6. If the root.sh step was skipped, or if this step failed, log in to the Management Agent host as the root user, navigate to $<AGENT_BASE_DIR>/agent_24.1.0.0.0/ and run the root.sh script on the host manually.

   After root.sh is run, you can clean up your old Management Agents, as described in Performing Postupgrade Cleanup of Old Management Agents.

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

• Verifying Your 24ai Release 1 Management Agent Upgrade

• Moving Central Agent Base Directory Outside Oracle Middleware Home (After Upgrading 13c Central Agent)

• Performing Postupgrade Cleanup of Old Management Agents

• Viewing 13c Management Agent Upgrade Cleanup Jobs

1. From the Setup menu, select Manage Enterprise Manager, then select Gold Agent Images.
2. Click Manage All Images.
3. Click Create.
4. Specify the gold image name, a description (optional), and the platform of the source Management Agent that you want to use to create the Agent Gold Image versions. Ensure that you use only a standalone Management Agent as the source, and not a central agent.
5. Click Submit.

1. From the Setup menu, select Manage Enterprise Manager, then select Gold Agent Images.
2. Click the name of the required Agent Gold Image.
3. Click Manage Image Versions and Subscriptions.
4. Select the Versions and Drafts tab, then from the Actions menu, select Create.
5. Specify an image version name, and a description for the image version, if required.

   The word limit for the image version name is 20 characters.

6. If you want to create the gold image version using a source Management Agent, for Create image by, select Selecting a source agent, then specify the source Management Agent that you want to use. In this case, you can also specify the following:

   • Work Directory: The working directory that must be used to create the Agent Gold Image. The default working directory is $AGENT_INSTANCE_HOME/install. Ensure that you have minimum 750MB space in this location.

   • Configuration Properties: The Management Agent configuration properties separated by a semicolon (;) that must be captured while creating the Agent Gold Image. The names of these properties can be found in the $AGENT_INSTANCE_HOME/sysman/config/emd.properties file.

   • Exclude Files: The list of files separated by ';' that must be excluded from the gold agent image version. For example, agent_24.1.0.0.0/cfgtoollogs/agentDeploy/*;agent_24.1.0.0.0/oui/*. Ensure that you provide only the relative path to the files and directories and not the absolute path.

   However, if you want to create the gold image version by importing an existing gold image version, for Create image by, select Importing an image, then specify the location of the gold image version that you want to import. In order to be able to import an image, the image should already be staged. If you have not already staged the image for this purpose, then stage it as described in the Oracle Enterprise Manager Advanced Installation and Configuration Guide.

   Note:

   The image can be created from a test system and staged. Also, the stage location should be accessible from the OMS.

7. Click OK.

   A job that creates the Agent Gold Image version 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 Image Activities tab.

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

2. Synchronize EM CLI:

   $<ORACLE_HOME>/bin/emcli sync
   

3. Run the create_gold_agent_image verb to create an Agent Gold Image using the specified source Management Agent or by importing an already created image from another Enterprise Management System:

   $<ORACLE_HOME>/bin/emcli create_gold_agent_image
           -image_name="gold_image_name"
           -version_name="gold_image_version_name"
           -source_agent|-import_location="source_agent|import_location"
           [-gold_image_description="gold_image_description"]
           [-working_directory="working_directory_location"]
           [-config_properties= " agent_configuration_properties"]
           [-exclude_files= "list_of_files_directories_to_exclude"]
   

   Note that the parameters mentioned in [ ] are optional.

   Table 6-4 lists and describes the parameters supported for creating an Agent Gold Image version using EM CLI.

   Table 6-4 Supported Parameters for Creating an Agent Gold Image Version

   Parameter	Description
   -image_name	Agent Gold Image name to which the created Agent Gold Image must be added.
   -version_name	Version name of the Agent Gold Image. When you create an image version and update a Management Agent with it, Enterprise Manager 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/em24/agentbasedir, and the agent home is /u01/software/em24/agentbasedir/agent_24.1.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/em24/agentbasedir/GoldImage_OPB_BP1/agent_24.1.0.0.0 is created. The word limit for the image version name is 20 characters.
   -source_agent	Management Agent to be used as the source to create the Agent Gold Image. To view a list of the Management Agents that can be used as a source to create a gold image, run emcli get_targets -target="oracle_emd".
   -import_location	Location where the Agent Gold Image is staged for creating the gold agent image version. This location is accessible from all the OMS instances.
   -gold_image_description	Description of the Agent Gold Image.
   -working_directory	Working directory to be used to create the Agent Gold Image. The default working directory is $AGENT_INSTANCE_HOME/install. Minimum free space required is 1 GB.
   -config_properties	Management Agent configuration properties separated by \";\" that must be captured while creating the Agent Gold Image. For example, MaxThread;GracefulShutdown.
   -exclude_files	List of files or directories separated by \";\" that must be excluded from the gold agent image version. For example, agent_24.1.0.0.0/cfgtoollogs/agentDeploy;agent_24.1.0.0.0/oui. Ensure that you provide only the relative path to the files and directories and not the absolute path.

   Examples:

   • The following example creates an Agent Gold Image OPC_AGI_DB_JUL_13, using example.com:3872 as the source Management Agent, and adds the gold image version to the gold image OPC_DB_MONITORING:

     $<ORACLE_HOME>/bin/emcli create_gold_agent_image -source_agent=example.com:3872 -version_name=OPC_AGI_DB_JUL_13 -image_name=OPC_DB_MONITORING 
     

   • The following example creates an Agent Gold Image OPC_AGI_DB_JUL_13, using example.com:3872 as the source Management Agent, /tmp as the working directory, and adds the gold image version to the gold image OPC_DB_MONITORING:

     $<ORACLE_HOME>/bin/emcli create_gold_agent_image -source_agent=example.com:3872 -version_name=OPC_AGI_DB_JUL_13 -image_name=OPC_DB_MONITORING -working_directory=/tmp
     

   • The following example creates an Agent Gold Image OPC_AGI_DB_JUL_13 using gold image software staged at import location /abc/stage:

     $<ORACLE_HOME>/bin/emcli create_gold_agent_image -import_location=/abc/stage -version_name=OPC_AGI_DB_JUL_13 -image_name=OPC_DB_MONITORING

1. From the Setup menu, select Manage Enterprise Manager, then select Gold Agent Images.
2. Click the name of the required Agent Gold Image.
3. Click Manage Image Versions and Subscriptions.
4. Select the Versions and Drafts tab. Select the gold image version that you want to set as the current version, then click Set Current Version.

   A job that promotes the Agent Gold Image draft version to the current version 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 Image Activities tab.

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

2. Synchronize EM CLI:

   $<ORACLE_HOME>/bin/emcli sync
   

3. Run the promote_gold_agent_image verb to promote the Agent Gold Image version to the Current maturity level:

   $<ORACLE_HOME>/bin/emcli promote_gold_agent_image         
   -version_name="gold_image_version_name"       
    -maturity="Current/Restricted/Draft"
    

   The -version_name parameter defines the Agent Gold Image that you want to promote.

   The -maturity parameter defines the gold image maturity level.

   For example, to promote the Agent Gold Image OPC_AGI_DB_JUL_13 to the Current maturity level, run the following:

   $<ORACLE_HOME>/bin/emcli promote_gold_agent_image  -version_name=OPC_AGI_DB_JUL_13 -maturity=Current

To set a draft or active version of a Agent Gold Image as the restricted version, follow these steps:

1. From the Setup menu, select Manage Enterprise Manager, then select Gold Agent Images.

2. Click the name of the required Agent Gold Image.

3. Click Manage Image Versions and Subscriptions.

4. Select the Versions and Drafts tab. Select the gold image version that you want to set as the restricted version, then click Set Restricted Version.

1. Log in to EM CLI from the /bin directory present within the OMS home:

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

2. Synchronize EM CLI:

   $<ORACLE_HOME>/bin/emcli sync
   

3. Run the promote_gold_agent_image verb to promote the Agent Gold Image version to the Restricted maturity level:

   $<ORACLE_HOME>/bin/emcli promote_gold_agent_image -version_name="gold_image_version_name" -maturity="Current/Restricted/Draft"
    

   The -version_name parameter defines the Agent Gold Image version that you want to promote.

   The -maturity parameter defines the gold image maturity level.

   For example, to promote the Agent Gold Image OPC_AGI_DB_JUL_13 to the Restricted maturity level, run the following:

   $<ORACLE_HOME>/bin/emcli promote_gold_agent_image -version_name=OPC_AGI_DB_JUL_13 -maturity=Restricted

1. From the Setup menu, select Manage Enterprise Manager, then select Gold Agent Images.
2. Click the name of the required Agent Gold Image.
3. Click Manage Image Versions and Subscriptions.
4. Select the Subscriptions tab. Click Subscribe.
5. Search for and select the required Management Agents, then click Select.

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

2. Synchronize EM CLI:

   $<ORACLE_HOME>/bin/emcli sync
   

3. Run the subscribe_agents verb to subscribe the specified Management Agent to a specific Agent Gold Image:

   $<ORACLE_HOME>/bin/emcli subscribe_agents 
            -image_name="Image Name" 
            [-agents="agent_name_pattern"] 
            [-groups="group_name"]
   

   Note that the parameters mentioned in [ ] are optional.

   The -image_name parameter subscribes the Management Agents to the specified Agent Gold Image.

   The -agents parameter subscribes only the Management Agents that match the specified name pattern.

   The -groups parameter subscribes only the Management Agents that belong to the specified groups.

   Examples:

   • The following example subscribes the Management Agents that match the name pattern abc% or xyz.example.com:1243 to the Agent Gold Image OPC_AGT_ADC_POD:

     $<ORACLE_HOME>/bin/emcli subscribe_agents -image_name="OPC_AGT_ADC_POD" -agents="abc%,xyz.example.com:1243"
     

   • The following example subscribes all the Management Agents to the Agent Gold Image OPC_AGT_ADC_POD:

     $<ORACLE_HOME>/bin/emcli subscribe_agents -image_name="OPC_AGT_ADC_POD"
     

   • The following example subscribes all the Management Agents that belong to the group GROUP1 or GRP2 to the Agent Gold Image OPC_AGT_ADC_POD:

     $<ORACLE_HOME>/bin/emcli subscribe_agents -image_name="OPC_AGT_ADC_POD" -groups="GROUP1,GRP2"

1. From the Setup menu, select Manage Enterprise Manager, then select Gold Agent Images.
2. Click the name of the required Agent Gold Image.
3. Click Manage Image Versions and Subscriptions.
4. Select the Subscriptions tab. Select the Management Agents that you want to update, select Update, then select To Current Version, or To Restricted Version.
5. 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.

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

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

9. In the Notify section, specify the email addresses to which you want the notifications about the update job progress to be sent.
10. 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.

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

12. 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 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/em24/agentbasedir, and the agent home is /u01/software/em24/agentbasedir/agent_24.1.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/em24/agentbasedir/GoldImage_OPB_BP1/agent_24.1.0.0.0 is created.

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

2. Synchronize EM CLI:

   $<ORACLE_HOME>/bin/emcli sync

3. 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 13.2.0.0.0, 13.3.0.0.0, 13.4.0.0.0, 13.5.0.0.0 or 24.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=" 13.2.0.0.0, 13.3.0.0.0, 13.4.0.0.0, 13.5.0.0.0, 24.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"

4. 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.example.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.example.com:1243"
     

   • The following example updates xyz.example.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.example.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.example.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.example.com:1243" -pre_script_loc="/scratch/pre_script"
     

   • The following example updates xyz.example.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.example.com:1243" -post_script_loc="/scratch/post_script"
     

   • The following example updates xyz.example.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.example.com:1243" -op_name="UPDATE_JOB123"
     

   • The following example updates xyz.example.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.example.com:1243" -override_credential="NAMED_CRED123"
     

   • The following example updates xyz.example.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.example.com:1243" -additional_parameters="-ignorePrereqs -newParameter"
     

   • The following example updates xyz.example.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.example.com:1243" -additional_parameters="-ignorePrereqs -newParameter"
     

   • The following example updates xyz.example.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.example.com:1243" -is_staged="true"
     

   • The following example updates xyz.example.com:1243 using the latest Agent Gold Image in the series OPC_AGT_ADC_POD, and the gold image is pulled by xyz.example.com:1243:

     <ORACLE_HOME>/bin/emcli update_agents -gold_image_series="OPC_AGT_ADC_POD" -agents="xyz.example.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.example.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.example.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.example.com:1243" -start_time="2019-05-07 10:00:00" -end_time="2019-05-08 10:00:00"
     

5. 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.example.com:1243:

     <ORACLE_HOME>/bin/emcli get_agent_update_status -version_name="OPC_AGT_ADC_POD_JUNE" -agent="xyz.example.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.example.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.example.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.example.com:1243:

     <ORACLE_HOME>/bin/emcli get_agent_update_status -op_name="UPDATE_JOB123" -agent="xyz.example.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.example.com:1243, having the status Failed:

     <ORACLE_HOME>/bin/emcli get_agent_update_status -op_name="UPDATE_JOB123" -status="Failed" -agent="xyz.example.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.example.com:1243, with severity as ERROR:

     <ORACLE_HOME>/bin/emcli get_agent_update_status  -op_name="UPDATE_JOB123" -severity="ERROR"  -agent="xyz.example.com:1243"	
     

   • The following example displays the details of the update operation UPDATE_JOB123 for the Management Agent xyz.example.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.example.com:1243"
     

   • The following example displays the details of the update operation UPDATE_JOB123 for the Management Agent xyz.example.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.example.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"