1. Cloud Control Database Lifecycle Management Administrator's Guide
  2. Patch Management
  3. Database Fleet Maintenance

20 Database Fleet Maintenance

This chapter describes the procedure to standardize database environments by automatically patching and upgrading a large number of databases with minimal downtime.

It covers the following sections:

About Database Fleet Maintenance

Database Fleet Maintenance allows administrators to maintain groups or pools of Oracle Homes and associated databases by applying database updates that include interim one-off patches including quarterly security patch updates (SPUs/CPUs), Patchset Updates (PSUs), Release Updates (RUs) and Release Update Revisions (RURs).

Any new database patches and updates are made available in the form of images. An image (also referred to as gold image or software end-state) represents the software binary that is patched to the required level. Each newly created image from a new patch for a specific database version is a new version. For example, an image for Oracle Database version 18.3 contains gold images (such as Ver. 1, Ver. 2, and so on) at different patch levels.

There are three main variations of patching:
  1. Patch a specific Oracle Database.
  2. Patch a Container Database (CDB) and it's Pluggable Databases (PDB) together.
  3. Patch PDBs independently by relocating them to a new CDB running from a patched Oracle home.
Database fleet maintenance can be used for:
  • Single Instance Oracle Homes and associated databases.

    Note:

    Starting with Enterprise Manager 13.4 Release Update 9 Fleet Maintenance will support Single Instance patching for Windows platforms.
  • RAC Oracle Homes and associated databases.
  • Grid Infrastructure Homes and associated Grid Instances.
  • Oracle Restart Homes (Grid Infrastructure for Standalone Server) and associated databases.
  • Standby databases (Single Instance and RAC).
  • RAC One Node.
Fleet maintenance involves the following steps:
  • Identifying configuration pollution using the Software Standardization Advisor.
  • Creating reference environments. Reference environment is a prerequisite for Gold Image creation. During each patching cycle, reference environment is patched with desired set of patches to be rolled to the target DBs.
  • Creating gold images using reference environments and versioning them for additional changes.
  • Subscribing databases and clusters to a gold image on which the appropriate patches have been applied.
  • Deploying the image and switching associated targets from the old Oracle Home to the new Oracle Home.
This maintenance activity can be performed as and when a new version of the gold image is available.

Note:

  • Oracle provides latest updates and best practices about Database patching and upgrade with Fleet Maintenance on the My Oracle Support Web site at https://support.oracle.com, My Oracle Support Note ID 2435251.1.
  • From the 12.2 release onward, classic patching using Lifecycle Management Graphical User Interface is deprecated. You now must use the Database Fleet Maintenance feature to patch database and GI environment.

Getting Started with Fleet Maintenance

The following figure lists the steps required to perform database fleet maintenance. It covers various configurations such as RAC and Single Instance databases with or without Data Guard, Oracle Restart, RAC One-Node, and Grid Infrastructure Homes.

Figure 20-1 Fleet Maintenance Operations Lifecycle Overview

Fleet Maintenance Operations Lifecycle Overview

The video Patch Oracle Databases Using Oracle Enterprise Manager Fleet Maintenance, gives an overview of Oracle Database patching and features examples for single instance database patching:

Meeting the Prerequisites

Before you begin Fleet Maintenance operations, you must ensure that the following prerequisites are met:

  • The Enterprise Manager Software Library has been setup and configured, see Getting Started with Setting Up Your Infrastructure.
  • The database and cluster targets to be patched have been discovered in Enterprise Manager, see: Discover Autonomous Databases and Discovering and Adding Database Targets .
  • A reference environment (Database and Oracle Home) representing the target state has been discovered in Enterprise Manager. This reference environment is required to create the gold image. For more information on creating reference environments see, Creating a Gold Image.
  • Space is available on the hosts where the patching is to be carried out.
  • The Agent Port on the OMS server needs to be open, allowing for communication between the target server and OMS server.
Starting with Enterprise Manager 13.4 Single Instance Database Fleet Maintenance operations can now be performed on Windows based deployments. To review specific Windows prerequisites see: Prerequisites for performing Fleet Maintenance on Windows.
Prerequisites for performing Fleet Maintenance on Windows

Starting with Enterprise Manager 13.4 Release Update 9 Fleet Maintenance operations can now be performed on Windows based deployments. This section covers specific prerequisites needed only when using Fleet Maintenance on Windows deployments.

  • To perform Fleet Maintenance operations like: deploy, migrate, upgrade and/or rollback; you will need to use the same user account and credentials that the source database is using. For more information see: Setting Credentials for the Job System to Work with Oracle Enterprise Manager in Oracle Database Installation Guide 18c for Microsoft Windows.
  • User details are passed to Fleet Maintenance EM CLI operations via Enterprise Manager Named Credentials. There are two typical user configuration cases:
    • Installations where there is a single installation owner that is also the Oracle Home owner. This single owner's credentials will be passed to the fleet operations at the destination database.
    • Installations where there is an installation owner (local administrator) and there is a second local user with no administrator privileges who owns the Oracle Home. Both user's credentials will be passed to the fleet operations at the destination database.
  • The Operating System users (mentioned above) need to be granted specific Windows OS level privileges on the specific host or hosts for Fleet Maintenance operations to properly function. For more information see: Creating Operating System Groups and Users for Enterprise Manager Cloud Control in Oracle Enterprise Manager Cloud Control Basic Installation Guide.
  • CYGWIN needs to be installed for Gold Image creation in a Windows deployment. For more information see: Installing Cygwin and Starting the SSH Daemon in Oracle Enterprise Manager Cloud Control Basic Installation Guide.

User Roles and Privileges for Fleet Maintenance

This topic cover roles and privileges a user will need to have in order to be able to execute all Fleet Maintenance Operations.

The main role needed for Fleet Maintenance operations is: EM_PATCH_OPERATOR, to grant this role navigate from Enterprise Manager to Setup, select Security and finally select Administrators. Click on the Create button and provide a user name and password.

Table 20-1 User Roles and Privileges for Different Oracle Homes

Type of Oracle Home Role Target Privilege Resource Privilege
Single Instance Database EM_PATCH_OPERATOR Listener Privileges:
  • Configure Target
  • Blackout Target
Used for: Database and listener on the destination targets. 		View Credential for normal and privileged credentials that will be used for operations.
Oracle Restart (HAS) EM_PATCH_OPERATOR Listener Privileges:
  • Configure Target
  • Blackout Target
Used for: Automatic storage management and Oracle High Availability Service targets running from the Oracle Home being patched. 		View Credential for normal and privileged credentials that will be used for operations.
RAC Database EM_PATCH_OPERATOR Listener Privileges:
  • Configure Target
  • Blackout Target
Used for RAC database instances and listener targets running from the Oracle Home being patched. 		View Credential for normal and privileged credentials that will be used for operations.
Grid Infrastructure Cluster EM_PATCH_OPERATOR Listener Privileges:
  • Configure Target
  • Blackout Target
Used for: Automatic Storage Management, Cluster and Oracle High Availability Service targets for the destination targets. 		View Credential for normal and privileged credentials that will be used for operations.

Discovering Configuration Pollution

Patching is one of the most challenging phases in the product lifecycle. With multiple patch cycles and various database configurations, different patch plans are required to satisfy the patching needs of the users. To address this, administrators must first identify their specific database configuration needs and select the standard configurations that are to be enforced in their environment.

With the Enterprise Manager Oracle Database plug-in, administrators can use the Software Standardization Advisor that scans the database configuration across all targets and generates a report (on-demand) of the existing environment. The report identifies the number of unique configurations (Platform + Version + Database-Type + Patches) and lists the Oracle Homes and databases for each configuration.

For example, in a 12.1.0.2 Linux-64 2-node RAC environment, three distinct groups of patches may have been applied. Each of these groups may have multiple Oracle Homes and databases associated with them. To meet this requirement, the administrator can define a standard configuration that can help simplify the environment.

The Software Standardization Advisor also recommends a list of standardized configurations and lists all the Oracle Homes on which the configurations should be applied. Oracle recommends that administrators run this report quarterly to understand the state of their database configurations. This list becomes the basis of fleet maintenance.

To use the Software Standardization Advisor , follow these steps:
  1. Login to the Enterprise Manager Console with administrative privileges.
  2. From the Targets menu, select Databases.
  3. From the Administration menu, select Software Standardization Advisor.
  4. Choose the relevant tab, Database or Grid Infrastructure and click run/re-run to run the analysis.
  5. Click Generate Report to generate a report as a spreadsheet.

A sample environment is shown below:
Software Standardization Advisor

The current system configuration is as follows:

Product Release Platform No of Oracle Homes Current Patch Configuration No of Databases Database
OracleDatabase12c 12.1.0.2.0 Linuxx86-64 2 19769480;20299023;20415564. 1 SI:[salesCDB.localdomain]
OracleDatabase12c 12.1.0.2.0 Linuxx86–64 3 19769480;20299023. 2 SI:[fm1.oracle.com;HRdb0000]
OracleDatabase12c 12.1.0.2.0 Linuxx86–64 3 No patches applied 3 SI:[fm2.oracle.com;db01;FINdb000]

The recommended system configuration is as follows:

Product Release Platform No of Oracle Homes Current Patch Configuration No of Databases Database
OracleDatabase12c 12.1.0.2.0 Linuxx86-64 8 19769480;20299023;20415564. 6 SI:[HRdb0000;fm2.oracle.com;salesCDB.localdomain;fm1.oracle.com;FINdb000;db01]

Custom Pre and Post Scripts for Fleet Operations

In order to support automated maintenance activities for different Fleet Maintenance operations, the support for configuring Pre and Post scripts for different operations is implemented. Pre and Post scripts need to be uploaded as EM Software Library Entity (Directive) prior to their usage with Fleet Maintenance operations. Pre and Ppost script usage is supported with DEPLOY, UPDATE, CLEANUP and ROLLBACK operations.

Creating and Using Custom Pre/Post Scripts:

  1. To develop your pre/post script, see: Custom Script Considerations.
  2. To upload custom scripts to the Software Library, see: Software Library Entity For Uploading The Script.
  3. Capture the URN for the Software Library Entity, see: How to Get URN for SWLIB Entity.
  4. Specify the Pre and Post script Software Library URN entity in the EMCLI input file., see: Pre/Post Script Usage.
Custom Script Considerations

Customer provided script will be invoked during Fleet Maintenance operations by passing a single argument absolute path to an input parameter file containing several parameters as key value pairs. This input parameter file (scriptInputFile.txt) is generated as part of the procedure activity and relevant DP variables are added to this file. These key value pair can be read from this file in the Pre and Post script and are intended to be used for maintenance operation being automated by the custom script. Input parameter file contains parameter values such as current oracle home, new oracle home etc.

Additionally, you can run Pre and Post scripts as normal by setting the RUN_PRE_SCRIPT_AS_ROOT=true and RUN_POST_SCRIPT_AS_ROOT=true flags respectively within the input_file. These flags are by default set to false and can be left out if not needed. These flags will only be honored if passed along with flags: CUSTOM_PRE_SCRIPTS_URN and CUSTOM_POST_SCRIPTS_URN respectively. The Pre and Post flags can be used for DEPLOY, UPDATE, ROLLBACK and CLEANUP Fleet Maintenance operations.

Sample input parameter file provided below:

Sample Code for CLEANUP_SOFTWARE

MAINTENANCE_PURPOSE=CLEANUP_SOFTWARE 
CUSTOM_PRE_SCRIPTS_URN=oracle:defaultService:em:provisioning:1:cmp:COMP_Directives:none:74A730047930C5FDE053DF0FC40A3E69:0.1 
ORACLE_HOME_TARGET_DETAILS=abc01def.example.com:/scratch/cuser/app/cuser/product/13.4.1/dbhome_1; 
CUSTOM_POST_SCRIPTS_URN=oracle:defaultService:em:provisioning:1:cmp:COMP_Directives:none:74A730047935C5FDE053DF0FC40A3E69:0.1 
DEPLOY_TYPE=SIDB 
ORACLE_HOME_NORMAL_CRED_NAME=CUSER:SYSMAN 
SOURCE_HOST=abc01def.example.com 
ORACLE_HOME_ROOT_CRED_NAME=ORACLE_ROOT:SYSMAN
RUN_PRE_SCRIPT_AS_ROOT=true

Sample Code for DEPLOY_DB_SOFTWARE

MAINTENANCE_PURPOSE=DEPLOY_DB_SOFTWARE 
SOURCE_HOME_LOCATION=/scratch/cuser/app/cuser/product/12.2.0/dbhome_2 
target_type=oracle_database 
target_name=sidb122
NOT_WINDOWS=true 
ORACLE_HOME_NORMAL_CREDSET_NAME=HostCredsNormal 
DISPATCHER_LOC=/tmp 
GOLD_IMAGE_URN=oracle:defaultService:em:provisioning:1:cmp:COMP_Component:SUB_OracleDB:74AA263BE602CF3BE053DF0FC40A2ED6:0.1 
ROOT_SCRIPT_LOC=/tmp/1311624666555972//MASSDB-194177ce43d441b89a504584d146aafb 
CUSTOM_PRE_SCRIPTS_URN=oracle:defaultService:em:provisioning:1:cmp:COMP_Directives:none:74A730047930C5FDE053DF0FC40A3E69:0.1 
CUSTOM_POST_SCRIPTS_URN=oracle:defaultService:em:provisioning:1:cmp:COMP_Directives:none:74A730047935C5FDE053DF0FC40A3E69:0.1 
ORACLE_HOME_TARGET_DETAILS=den01nre.example.com:OraDB12Home2_4_den01nre.example.com_3012; 
WORK_DIR_LOC=/tmp/1311624666555972//1311626758529303/ 
DEPLOY_TYPE=SIDB 
CREDSET_TARGET_TYPE=OracleHome 
ORACLE_HOME_ROOT_CREDSET_NAME=HostCredsPriv 
RUN_POST_SCRIPT_AS_ROOT=true
NEW_ORACLE_HOME_LIST=/scratch/cuser/app/cuser/product/13.4.1/dbhome_Dep2
Software Library Entity For Uploading The Script

Create a Software Library entity of type Directive (for uploading the custom scripts to EM).

  1. Select Enterprise > Provisioning and Patching > Software Library.
  2. Select the directory where you want to create the Software Library entity.
  3. Click Actions > Create Entity > Directives.
  4. Provide all the basic details on the Directive screen.
  5. Click Add under Command Line Arguments on the Configure screen.
  6. The INPUT_FILE to be added as mentioned in the list below. Click OK.
    • Argument Prefix="
    • Argument Suffix="
    • Property Name=INPUT_FILE
  7. Click Next.
  8. Click Add in Specify Source and select the script files to upload the custom script on the Select File screen. Choose the driver script as the main file.
  9. Click Next.
  10. Click Save and Upload.
  11. An entity is created successfully in a Software Library.
How to Get URN for SWLIB Entity

To get URN for the SWLIB through EMCLI:

$OMS_HOME/bin/emcli list_swlib_entities -show_entity_rev_id -name="<Name of SWLIB entity>"

To get URN for the SWLIB through EM UI:

  1. Select Enterprise > Provisioning and Patching > Software Library.
  2. Click View > Columns > Internal ID. Select this option.
  3. Go to the uploaded entity and copy the Internal ID for the uploaded entity. The internal ID is the URN.
Pre/Post Script Usage

To execute the Custom Scripts, use <-input_file> option with fleet command and provide the URN for the pre/post script SWLIB entity created earlier. 

emcli db_software_maintenance 
-performOperation -name="Deploy 12.2 Home”
-purpose="DEPLOY_DB_SOFTWARE"
-target_type=oracle_database
-target_list="DB122" 
-normal_credential="ORACLE:SYSMAN" 
-privilege_credential="ORACLE_ROOT:SYSMAN" 
-input_file="data:/scratch/input_dbOH.prop"
Contents of input_dbOH.prop file:
NEW_ORACLE_HOME_LIST=/scratch/cuser/app/cuser/product/12.1.0/dbhome_Dep1
CUSTOM_PRE_SCRIPTS_URN=oracle:defaultService:em:provisioning:1:cmp:COMP_Directives:none:74A730047930C5FDE053DF0FC40A3E69:0.1
CUSTOM_POST_SCRIPTS_URN=oracle:defaultService:em:provisioning:1:cmp:COMP_Directives:none:74A730047935C5FDE053DF0FC40A3E69:0.1

Image and Subscription Tasks

Once you have verified the prerequisites and are ready to begin with Fleet Management, you will need to perform the following Image and Subscription tasks to get your environment ready.

Please follow the steps outlined in the following topics in order to successfully start using Fleet Maintenance:
Creating a Gold Image
The standard configuration described in the Discovering Configuration Pollution section is referred to as a gold image. It is the end of state software definition that contains information about the base software version plus the additional patches. The 'end-state definition' is the logical term; the physical software binary component that represents the end-state is called as a gold image. (Gold is the qualifier signifying the ideal standard or the level for the software configuration.)The following figure shows how a gold image can be created:

Figure 20-2 Creating a Gold Image

Creating an Image
You can create an image for a database or grid infrastructure home using the EM CLI command shown below. This image is stored in the Enterprise Manager Software Library and used for provisioning.
Prerequisites:
  • The Enterprise Manager Software Library has been setup and configured.
  • The database and cluster targets to be patched have been discovered in Enterprise Manager.
  • Reference environment (Database and Oracle Home) representing the target state must have been discovered in Enterprise Manager. This reference environment is required to create the gold image.

db_software_maintenance sample:

emcli db_software_maintenance -createSoftwareImage -input_file="data:/tmp/create_gldimg.properties

Where the create_gldimg.properties input file contains the variables explained below. For a complete description of input variables for db_software_maintenance family of verbs, see db_software_maintenance in the Enterprise Manager Command Line Reference Guide.

Description of the Input Variables

The input variables are described below:
  • IMAGE_NAME: The name of the Gold Image. This name must be unique across images.
  • IMAGE_DESCRIPTION: A description of the image.
  • REF_TARGET_NAME: The Oracle home target that will be used to create this Gold Image. This is the Database or Grid Infrastructure Oracle Home from the existing environment on which the desired set of patches have been applied. For example, if we intend to patch our 18c Fleet of databases with the latest Release Update (RU), we need to specify the Oracle Home target name for a reference Oracle Home where 18c RU has already been applied. To find the reference target name, enter the following query on the Enterprise Manager repository:
    SELECT distinct target_name FROM mgmt$target_properties WHERE target_name IN
SELECT target_name FROM mgmt_targets WHERE target_type='oracle_home' AND host_name=<Host Name of this Oracle Home> 
AND property_name='INSTALL_LOCATION' AND property_value=<path of Oracle Home>
  • IMAGE_SWLIB_LOC: Path in software library where the payload of the Gold Image will be stored.
  • REF_HOST_CREDENTIALS: This is applicable for Database Gold Image only. This must be entered in the format <Named Credential: Credential Owner> where:
    • <Named Credential>: Is the named credentials for the host on which the reference Oracle Home is located. This user must be the owner of Oracle home.
    • <Credential Owner>: Is the Enterprise Manager user who owns this Named Credential.

      Note:

      The REF_HOST_CREDENTIALS parameter is applicable for database gold images only. For Grid Infrastructure or Oracle Restart Homes, this parameter is listed as REF_GI_CREDENTIALS.
  • WORKING_DIRECTORY: The temporary location on the host of reference Oracle home target.
  • STORAGE_TYPE_FOR_SWLIB: The Software Library storage type. This can be OMS Shared or OMS Agent File system.
  • STORAGE_NAME_FOR_SWLIB: The storage name for the Software Library. To retrieve this storage name, from the Enterprise menu, select Provisioning and Patching, then select Software Library. In the Software Library page, from the Actions menu, select Administration. On this page, check the value in the Name column to retrieve the storage name for the Software Library.
  • VERSION_NAME: An image can have multiple versions. A default version of the image is created and more versions can be added.

Sample Output

The following output is displayed:
'Create Gold Image Profile deployment procedure has been submitted successfully with the instance name: 'CreateGoldImageProfile_TESTSUPERADMIN_12_08_2015_05_09_AM' and execution_guid='25F92D9A00164A45E053D903C40A9B4B

The operation is performed using a deployment procedure, and user needs to wait for its completion before performing next steps. Status of the Gold Image creation can be checked using the following command:

emcli get_instance_status -exec=25F92D9A00164A45E053D903C40'

Creating Gold Images by Patching Oracle Homes

You can also create Gold Images by patching Oracle Homes. Once the patch list is identified and downloaded, you as administrator can create a Gold Image version of the in one of the following scenarios:
  1. Create a new version from an existing deployment. As the administrator you have an existing test environment in which has deployed all the required patches. You point to a prepared Oracle home that contains all desired patches, and copies them into a new Gold Image Oracle Home.
    To begin, point to a prepared Oracle home that contains all desired patches:
    emcli db_software_maintenance -createSoftwareImage -input_file="data:/home/user/input_file"
    In this use case input_file must contain the following:
    IMAGE_ID=<ID of existing Gold Image in which a new version is to be created>
REF_TARGET_NAME=<ORACLE_HOME source target>
IMAGE_SWLIB_LOC=<Image Location>
REF_HOST_CREDENTIALS=USER:TESTSUPERADMIN 
WORKING_DIRECTORY=/tmp
DESTN_SAME_AS_SRC=<True/False>
STORAGE_TYPE_FOR_SWLIB=OmsShared
STORAGE_NAME_FOR_SWLIB=swlib
PATCH_LIST=<List of patches to deploy, comma separated>
VERSION_NAME=Version1
  2. In this use case, you as the administrator do not want to the modify the test environment. For this use case you will have to clone the home, apply patches and then create a Gold Image. The original test environment home is NOT modified. In this use case, the task is to clone the test environment, apply the patches and then create the Gold Image.
    To begin, point to a prepared Oracle home that contains all desired patches:
    emcli db_software_maintenance -createSoftwareImage -input_file="data:/home/user/input_file"
    For this use case two examples for the input_file will be given, one for RAC and one for GRID:
    • Input file for cloning, patching and creating Gold Image for a RAC home :
      IMAGE_NAME=<Unique name to identify operation>
IMAGE_DESCRIPTION=<Description of image>
REF_TARGET_NAME=<Oracle_Home source target>
IMAGE_SWLIB_LOC=<Image Location>
REF_HOST_CREDENTIALS=USER:TESTSUPERADMIN 
REF_HOST_ROOT_CREDENTIALS=USER_ROOT:TESTSUPERADMIN 
WORKING_DIRECTORY=/tmp
STORAGE_TYPE_FOR_SWLIB=OmsShared
STORAGE_NAME_FOR_SWLIB=sl
VERSION_NAME=<Patch version name>
PATCH_LIST=<List of patches to deploy, comma separated>
DESTN_HOME_LOCATION=<Location of the destination Oracle Home target>
    • Input file for cloning, patching and creating Gold Image for a GRID Home:
      IMAGE_NAME=<Unique name to identify operation>
IMAGE_DESCRIPTION=<Description of image>
REF_TARGET_NAME=<Oracle_Home source target>
REF_GI_CREDENTIALS=USER:TESTSUPERADMIN
IMAGE_SWLIB_LOC=<Image Location>
REF_HOST_CREDENTIALS=USER:TESTSUPERADMIN
REF_HOST_ROOT_CREDENTIALS=USER_ROOT:TESTSUPERADMIN
WORKING_DIRECTORY=/tmp
STORAGE_TYPE_FOR_SWLIB=OmsShared
STORAGE_NAME_FOR_SWLIB=sl
VERSION_NAME=<Patch version name>
DESTN_HOME_LOCATION=<Location of the destination Oracle Home target>
PATCH_LIST=<List of patches to deploy, comma separated>
  3. Modify the test environment itself. In this case, you as the administrator will have to apply patches to specified home and then create the Gold Image.
    To begin, point to an Oracle home that will be patched with the new patches to create the new Gold Image
    emcli db_software_maintenance -createSoftwareImage -input_file="data:/home/user/input_file"
    Input file where both source and destination will be modified:
    IMAGE_NAME=<Unique name to identify operation>
IMAGE_DESCRIPTION=<Description of image>
REF_TARGET_NAME=<Oracle_Home source target>
IMAGE_SWLIB_LOC=<Image Location>
REF_HOST_CREDENTIALS=USER:TESTSUPERADMIN
REF_HOST_ROOT_CREDENTIALS=USER_ROOT:TESTSUPERADMIN
WORKING_DIRECTORY=/tmp
STORAGE_TYPE_FOR_SWLIB=OmsShared
STORAGE_NAME_FOR_SWLIB=sl
VERSION_NAME=<Patch version name>
PATCH_LIST=<List of patches to deploy, comma separated>
DESTN_SAME_AS_SRC=true
  4. Enterprise Manager deployments that have no exclusive Stage or Test environments. In this use case you will deploy the CURRENT (default) version of the image, apply patches and then create a Gold Image.
    To begin, point to a prepared Oracle home that contains all desired patches:
    emcli db_software_maintenance -createSoftwareImage -input_file="data:/home/user/input_file"
    Input file sample for a no test environment use case:
    IMAGE_ID=<ID of existing Gold Image in which a new version is to be created>
DESTN_HOME_LOCATION=<Location of the destination Oracle Home target>
DESTN_HOST=<host target name> 
DISPATCHER_LOCATION=<Dispatch location of the scripts>                         
SKIP_PREREQUISITE_CHECKS=<true/false>
SKIP_CVU_CHECK=<true/false>                                            
REF_HOST_CREDENTIALS=USER:SUPERADMIN
WORKING_DIRECTORY=/tmp
IMAGE_SWLIB_LOC=<Image Location>
STORAGE_TYPE_FOR_SWLIB=OmsShared
STORAGE_NAME_FOR_SWLIB=swlib
VERSION_NAME=<Patch version name>
PATCH_LIST=<List of patches to deploy, comma separated>
Migrating Fleet Maintenance Gold Images between Enterprise Manager Deployments

With Fleet Maintenance you can send updates, software images and their meta data across separate Enterprise Manager installations by migrating the Gold Images between fleet deployments. This use case is especially useful when having two Enterprise Manager installations, one for Development and Production. You can test patching and software images on the development instance and once satisfied, move all the Software Images and their meta data to the production Enterprise Manager, avoiding having to recreate all the software images again for the production Enterprise Manager. Creating software images from installed homes can be a time-consuming affair.

Steps to Migrate Fleet Maintenance Gold Images

Migrating a Fleet Maintenance Gold image, its software images and metadata, can be broken down into 3 main steps:
  1. Export the Gold Image with the Export Gold Image command from the source Enterprise Manager Software Library to a staging location.
  2. Optionally copy the Gold Image to a location accessible by the destination Enterprise Manager agent.
  3. Run Import Gold Image command to import the Gold Image files to the software library in the destination Enterprise Manager. The corresponding meta data written to the fleet bookkeeping tables and views.

Prerequisites for Exporting and Importing Fleet Maintenance Gold Images

Before starting to migrate Gold Images between Enterprise Manager installations, review the following:
  • Make sure that the given origin and destination host are Enterprise Manager visible targets.
  • Make sure that the destination host provided is a managed target within Enterprise Manager .
  • Make sure the given storage location is valid.

Steps to Export and Import Fleet Maintenance Gold Image Fleet files

  1. First you will need to create the export_gldimg.prop file with the following parameters:
    • IMAGE_NAME: Name of the image needs to be exported.
    • IMAGE_ID: ID of the image needs to be exported.

      Note:

      IMAGE_NAME or IMAGE_ID are mandatory.
    • VERSION_NAME: Name of the image version needs to be exported (Required).
    • VERSION_ID: ID of the image version needs to be exported (Optional).
    • DEST_HOST_NAME: Host name where to store the gold image bundle (Required).
    • DEST_HOST_CRED: Host normal credential (Required).
    • GOLD_IMAGE_BUNDLE_LOCATION: Location to store the gold image bundle (Required).
    • GOLD_IMAGE_BUNDLE_NAME: Name of the gold image bundle (Optional).
    • WORKING_DIRECTORY: By default, /tmp is the working directory (Optional).

    Note:

    Destination host name, destination host credential , Image Id or Image Name, Gold Image Bundle Location are mandatory parameters. These parameters are checked at run time and will return an error if they are Empty or Null.
    A sample of the export_gldimg.prop file would look like this:
    IMAGE_ID=8BBCE9315DEB1C27E05388947B0AF101
IMAGE_NAME=18.3 patched SI Home
VERSION_ID=8BBCC9E029AF7B18E05388947B0AB627
DEST_HOST_NAME=example.sample.com
DEST_HOST_CRED=USER1:SYSMAN
GOLD_IMAGE_BUNDLE_LOCATION=/scratch/<file_path>/goldimage
GOLD_IMAGE_BUNDLE_NAME=ExportGoldImage.zip
  2. Once the export_gldimg.prop has been created run the db_software_maintenance EM CLI verb with the exportSoftwareImageflag. See the following example:
    emcli db_software_maintenance -exportSoftwareImage
    -input_file=”data:<file_path>/export_gldimg.prop”

    Note:

    It is recommended that you use short file paths on Windows Fleet Maintenance operations to avoid issues. You can pass a work directory location within the input file with a short file path like WORK_DIR_LOC=C:\temp.
    Once completed, the Fleet Maintenance Gold Image has been successfully exported.
  3. To start the import first you will need to create an import_gldimg.prop file with the following parameters:
    • IMAGE_NAME: Gold Image name to be used for the imported image (Required).
    • HOST_NAME: Host name where gold image bundle is stored (Required).
    • HOST_CREDENTIAL: Host normal credential (Required ).
    • GOLD_IMAGE_BUNDLE_NAME: Gold image zip file bundle name (Required).
    • GOLD_IMAGE_BUNDLE_LOCATION: Location of the gold image bundle (Required).
    • IMAGE_DESCRIPTION: Imported Image description (Optional).
    • IMAGE_SWLIB_LOC: Image component location in the Software Library (Required).
    • WORKING_DIRECTORY: By default, /tmp is the working directory, required if path is different (Optional).
    • STORAGE_TYPE_FOR_SWLIB: Storage type for the Software Library (Required).
    • STORAGE_NAME_FOR_SWLIB: Storage name for the Software Library (Required).
    • VERSION_NAME: Imported image version name (Optional).

    Note:

    Gold Image Bundle name, location, host name and credential, storage name, type and location, working directory are mandatory parameters. These parameters are checked at run time and will return an error if they are Empty or Null.
    A sample of the import_gldimg.prop file would look like this:
    IMAGE_NAME=18.3 SI Home import1
HOST_NAME=example.sample.com
HOST_CREDENTIAL=USER1:SYSMAN
GOLD_IMAGE_BUNDLE_LOCATION=/scratch/<file_path>/goldimage183
GOLD_IMAGE_BUNDLE_NAME=ExportGoldImage183.zip
IMAGE_DESCRIPTION=Gold Image for 18.3 SI Home - import
IMAGE_SWLIB_LOC=Database ProvisioningProfiles/<db version>/linux_x64
WORKING_DIRECTORY=/tmp
STORAGE_TYPE_FOR_SWLIB=OmsShared
STORAGE_NAME_FOR_SWLIB=swlib
VERSION_NAME=18.3 SI home-import1
  4. Once the import_gldimg.prop has been created run the db_software_maintenance EM CLI verb with the importSoftwareImage flag. See the following example:
    emcli db_software_maintenance -importSoftwareImage
    -input_file=”data:<file_path>/import_gldimg.prop”
    Once completed, the Fleet Maintenance Gold Image has been successfully imported.
Retrieving a List of Available Gold Images

Note:

To format the output of the EM CLI commands listed below, set the emctl property - oracle.sysman.dbprov.gis.emcli.verbs.tableLength to the width of the terminal.

For example:

emctl set property -name oracle.sysman.dbprov.gis.emcli.verbs.tableLength -value 160
When the image has been successfully created, you can get a list of images that are available with the following command: 
$ emcli db_software_maintenance -getImages [-columnName=<Comma-separated variable list>]
Image Id Image Name Description 
Version 
72D9D7C656A11AB2E053BC3A41  RACS_12.1_RAC_12.1.0.2.180  
12.1.0.2.0 12CRACS 0A7A43

Description of the Input Variables:

  • -getImages: Shows a list of images with a Production status. To get a list of Failed or Inactive statuses use: -getImages
  • columnName: Is an optional comma-separated list parameter that can be used to limit the number of columns in the output. Supported values are image_id, image_name, image_version and image_description. For example: -columnName: image_id, image_name

Sample Output

Image Id Image Name Description

Version Platform Name Creation Date Owner Modified By

FE55AD7AB28974EFE04313B2F00AD4A0 11.2.0.4.0 RAC DB Gold Image for 112040 RAC DB Homes

11.2.0.4.0 Linux x86-64 2015-12-28 13:22:42.0 TESTSUPERADMIN TESTSUPERADMIN

Verb getImages completed successfully

Listing the Versions of an Image

After you have retrieved a list of the available images, you can view a list of versions available for a specific image with the following command:

emcli db_software_maintenance -getVersions -image_id=<image_id>
[-columnName=<column names>]

Description of the Input Variables

  • columnName: It is an optional comma-separated list parameter that can be used to limit the number of columns in the output. Supported values are image_id, image_name, image_version, and image_description.

Sample Output

*************************************************************************************************************************************
POSITION                        VERSION ID                      VERSION NAME        STATUS           DATE CREATED 
EXTERNAL ID                     HASHCODE                       
*************************************************************************************************************************************
1                               277DF28F2D30393BE053D903C40AC6  CUSTOMER 112044     VERSION ACTIVE   2015-12-22  05:54:45.0  
ORACLE:DEFAULTSERVICE:EM:PROVI  C3448035451:B1400395227         
SIONING:1:CMP:COMP_COMPONENT:S  10 
UB_ORACLEDB:277DF28F2D2C393BE0
53D903C40AC610:0.1   
************************************************************************************************************************************
2                               277E39B74D684C6BE053D903C40A59  CUSTOMER 112047     VERSION CURRENT  2015-12-22 06:14:40.0    
ORACLE:DEFAULTSERVICE:EM:PROVI  C3448035451:B3881579444         
IONING:1:CMP:COMP_COMPONENT:S   EB
UB_ORACLEDB:277E39B74D664C6BE0
53D903C40A59EB:0.1 
                                  
*************************************************************************************************************************************
TOTAL ROWS:2

Describing an Image

To view the content (patches/bugs) of an image, run the following EM CLI command. It shows the current version of the given image by default unless a specific version_id is provided.
emcli db_software_maintenance –describeImage –image_id=<Image Id> [-version_id=<version id>] [-bugs=true]

Sample Output

# PATCH# PATCH DESCRIPTION
1 23054319 OCW Patch Set Update : 11.2.0.4.160719 (23054319)
2 19769489 Database Patch Set Update : 11.2.0.4.5 (19769489)
3 21352635 Database Patch Set Update : 11.2.0.4.8 (21352635)
Verifying if Image is Applicable

This step verifies if the image can be used to patch a specified database target. This is done by comparing the bug fixes available in the current Oracle home of the database target and the image.

Sample code: 
emcli db_software_maintenance -checkApplicability -image_id=<image_id> 
-target_list=<target_list> -target_type=<target_type>
Description of Input Variables
  • target_list: List of database or grid infrastructure home or Oracle restart Home targets.
  • target_type: Refer to the table “EM CLI command inputs based on Entity type”.

Examples:

RAC Database
emcli db_software_maintenance –checkApplicability -image_id= FE55AD7AB28974EFE04313B2F00AD4A0 
-target_list=RACDB1 -target_type=rac_database
Oracle Restart
emcli db_software_maintenance –checkApplicability -image_id=2EA08B6339234B7E053BC3A410A2826 
-target_list=HAS1 -target_type=has

Grid Infrastructure

emcli db_software_maintenance -checkApplicability -image_id=72F8E4FCDE017B99E053BC3A410AF226 
-target_list=CLUSTER1 -target_type=cluster

Single Instance

emcli db_software_maintenance -checkApplicability -image_id=6E4EA63DDC00535CE0531636B10ABA1A 
-target_list=DB1 -target_type=oracle_database

Sample Output

Checking applicability for target [DB1]...
Image is applicable
This command can show one of the following results:
  • Applicable: The image and database target contain the same set of bug fixes. The image can be applied on the specified target.
  • Applicable and Image has more bug fixes: The image contains more bug fixes than those applied on the database. The list of extra bugs is displayed. The image can be applied on the specified target.
  • Not Applicable: The database contains more bug fixes than those included in the image. The list of missing bugs is displayed. The administrator has to create a new version of the image that includes the missing bugs before the database can uptake the same.
Deleting an Image or Versions of an Image

Delete a Version of an Image

To delete a version of an existing image, use the following command:

emcli db_software_maintenance –deleteVersion –version_id=<version_id> [-reportOnly=true|false]
Description of the Input Variables

The input variables are:

  • version_id: the ID of the version that needs to be deleted.
  • reportOnly: This is an optional parameter and the default value is set to false. When it is specified as true, it lists the version details that will be deleted but the operation is not carried as the name suggests. This is used as a precautionary step before actual deletion of a version.

Delete an Image

To delete an image, which will in turn delete all versions of an image and all metadata related to an image such as subscriptions and software library components, use the following command:
emcli db_software_maintenance –deleteImage –image_id=<image_id> [-reportOnly=true|false]
Description of the Input Variables

The input variables are:

  • Image_id: the ID of the version that needs to be deleted.
  • reportOnly: This is an optional parameter and the default value is set to false. When it is specified as true, it lists the version details that will be deleted but the operation is not carried as the name suggests. This is used as a precautionary step before actual deletion of a version.
Subscribing the Targets to the Selected Image

To achieve standardization, Oracle Homes must be subscribed to the image. A group of Grid Infrastructure Homes can subscribe to a image created with a reference Grid Infrastructure Home. A target should be subscribed to only one gold image at a given time.

Syntax: 
emcli db_software_maintenance -subscribeTarget -target_name=<target_name> 
-target_type=<target_type> -image_id=<image_id>
Sample:
emcli db_software_maintenance -subscribeTarget -target_name=ORCL1910.abc.sample.com  
-target_type=oracle_database -image_id=A344EFAD4A9D7

Where:

  • target_name: The name of the target that needs to be patched.
  • target_type: Type of database target to be patched, for more information on target types see: Fleet Maintenance Software Operations.
  • image_id: The ID of the gold image to which this target is to be patched. You can get the image_id by running the emcli command. For information about the command, see Retrieving a List of Available Gold Images.

Note:

If the target is a primary database, the standby database target is automatically subscribed to the same image.

Sample Output

Target 'RACDB1' subscribed successfully.
Verb subscribeTarget completed successfully
Verifying the Subscription

Syntax:

You can view a list of all targets that have been subscribed to a specific image. In a large data center, there may be several images and multiple targets subscribing to each of these images. For example, the following figure shows three images and several targets subscribed to each of these images:

emcli db_software_maintenance -getImageSubscriptions -image_id=<image_id>

Sample Output:

**************************************************************************************

TARGETNAME  TARGETTYPE   VERSIONNAME      DATESUBSCRIBED 

CLUSTER1    CLUSTER      112044 Version   2015-12-22 06:59:08.0

**************************************************************************************

Total Rows:1

To verify the subscription at the target level, use the following command:

emcli db_software_maintenance -getTargetSubscriptions -target_name=<target_name> -target_type=<target_type>

Description of the Input Variables

  • target_name: name of the target.
  • target_type: refer to table “EM CLI command inputs based on Entity type”
  • version_name: This is observed to be empty sometimes. A value is displayed when the existing Oracle Home of the target has same set of patches as any existing Gold Image version.

Sample Output

TARGET NAME TARGET TYPE IMAGE ID IMAGE NAME VERSION ID VERSION NAME PARENT NAME PARENT TYPE DATE SUBSCRIBED
=========================================================================================================================================================
DB1 oracle_database 48B75BB7B5E0462 SIDB_11204 48B78E3967D56BE PSU Jan17 <null> <null> Jan 2017-02-21

To verify the subscription of the container databases for PDB patching, use the following command:

emcli db_software_maintenance -getSubscriptionsForContainer -target_name=<CDB_TARGET_NAME> 
-target_type=<target_type> -image_id=<image_id>

Sample Output

emcli db_software_maintenance -getSubscriptionsForContainer 
TARGET NAME TAREGT TYPE IMAGE ID
==================================================================
conttarget oracle_database 73659339F2364E7CE053BC3A410A2016
Unsubscribing Targets from an Image
To unsubscribe a target from an image, use the following command:
emcli db_software_maintenance -unsubscribeTarget -target_name=<target_name> 
-target_type=<target_type> -image_id=<image_id>
Where:
  • target_name: Is the name of the RAC database target that needs to be patched.
  • target_type: Refer to the table “EM CLI command inputs based on Entity type”.
  • image_id: The ID of the gold image to which this target is to be patched. You can get the image_id by running the emcli command. For information about the command, see Retrieving a List of Available Gold Images.
Creating an Updated Version of the Image
After you have verified that all the targets have been subscribed to the selected image, a new version of the image must be created. This is the target version to which the databases are to be patched.

Syntax: emcli db_software_maintenance -createSoftwareImage -input_file=data:"<input_file_path>”

For a description of input file, see Creating Gold Image.

Example: emcli db_software_maintenance -createSoftwareImage -input_file="data:/home/user/input_rac"

For a RAC database, the input_file contents can be as follows:

IMAGE_ID=<ID of the existing gold image under which the version is to be created> 
REF_TARGET_NAME=<Oracle home target name for 112044 Oracle home>
<IMAGE_SWLIB_LOC=Oracle Home Provisioning Profiles/11.2.0.4.4/linux_x64
REF_HOST_CREDENTIALS=REF_HOST_CREDS:SYSMAN
WORKING_DIRECTORY=/tmp
STORAGE_TYPE_FOR_SWLIB=OmsShared
STORAGE_NAME_FOR_SWLIB=swlib
VERSION_NAME=PSU 112044 Version

Sample Output

Create Gold Image Profile deployment procedure has been submitted successfully with the instance name: 'CreateGoldImageProfile_SYSMAN_12_08_2015_05_09_AM' and execution_guid='25F92D9A00164A45E053D903C40A9B4B'
Changing Version Status to Current

After an updated version of the image has been created see Creating a Gold Image, this new version must be marked as "Current". This indicates that this is the target version to which the databases are to be patched at the end of the fleet operation.

emcli db_software_maintenance -updateVersionStatus -version_id=<version_id> -status=CURRENT

where version_id is the target version to which the databases are to be patched.

Sample Output

Version ID '269EA1638D1D7472E053D903C40ABF1B' updated successfully.

Verb updateVersionStatus completed successfully.

Fleet Maintenance Software Operations

With Fleet Maintenance you can perform operations on your entire fleet with simple EM CLI commands. Fleet Maintenance allows you to simplify standardizing software configurations across your environment.

The following table shows the target types that are supported and the values you need to provide for the target_type and -purpose fields in emcli commands:

Entity Target_type Deploy Operations Update Operations Rollback Operations Cleanup Software Operation
Single Instance database

Note:

Now supported on Windows platforms
oracle_database DEPLOY_DB_SOFTWARE UPDATE_DB

MIGRATE_LISTENER (For more information see: Migrating the Listeners)

ROLLBACK_DB CLEANUP_SOFTWARE
RAC database rac_database DEPLOY_RAC_SOFTWARE UPDATE_RACDB ROLLBACK_RACDB CLEANUP_SOFTWARE
Oracle Restart has DEPLOY_SIHA_SOFTWARE UPDATE_SIHA ROLLBACK_SIHA CLEANUP_SOFTWARE
Grid Infrastructure cluster DEPLOY_GI_SOFTWARE UPDATE_GI ROLLBACK_GI CLEANUP_SOFTWARE
PDB oracle_pdb DEPLOY_DB_SOFTWARE/DEPLOY_RAC_SOFTWARE/+DEPLOY_CDB/ATTACH_CDB UPDATE_PDB ROLLBACK_PDB N/A
CDB/RAC CDB oracle_database/ rac_database DEPLOY_DB_SOFTWARE/DEPLOY_RAC_SOFTWARE/+DEPLOY_CDB/ATTACH_CDB UPDATE_DB/ UPDATE_RACDB ROLLBACK_DB/ ROLLBACK_RACDB CLEANUP_SOFTWARE

Note:

All values in the table above are case sensitive.

For a detailed tutorial on patching a single instance database using Fleet Management see: Patching a Single Instance Database Using Oracle Enterprise Manager Fleet Maintenance.

db_software_maintenance General Code Layout and Information 

emcli db_software_maintenance -performOperation 
-name=<User Specified Operation>
-purpose=<Operation Type> 
-target_type=<target type> 
-target_list=<list of targets> 
-normal_credential=<credential name> 
-privilege_credential=<credential name> 
-rolling=<true/false> 
-input_file="data:<location of input file>"
  • name: This is the unique name of the operation.
  • purpose: Refer to the EM CLI Command Inputs Based on Entity Type table.
  • target_type: Refer to the EM CLI Command Inputs Based on Entity Type table.
  • target_list: This is a comma separated list of targets which need to be patched.

    Targets of homogenous types are supported in a single fleet operation.

  • normal_credential: This must be entered in the format <Named Credential: Credential Owner> where:
    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.
    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.
  • privilege_credential: This must be entered in the format <Named Credential: Credential Owner> where:
    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.
    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.
    These credentials are used to run scripts as root.
  • rolling: This is an optional flag with the default value as true. The update procedure works in "Rolling Patch" mode by default but you can override this if necessary. If the gold image has OJVM patches, you should mark this value as ‘false’ which will take all instances of RAC DB down for update. This option is applicable for DB patching only (not for Grid Infrastructure or Oracle Restart).
  • input_file: This is an optional parameter. The parameter(s) that can be specified here are: workingDir =<Name of temp directory>.
Deploy Operations
Deploy operations are performed within Fleet Maintenance, to simplify databases deployments. They can be performed in a short period of time because the Gold Image (the version of the image that is marked as ‘Current’ to indicate the current gold standard) is copied to a parallel Oracle Home which is then turned into a newly patched Oracle Home. This command is used to create the parallel Oracle Home and copy the gold image there. In other words, this command allows you to stage and deploy the new Oracle Home on the subscribing Oracle Homes. The Deploy command automatically uses the CURRENT version of the subscribed image while creating the new Oracle Home. In this topic we cover several examples of different deployment operations.

For more information on deploy operators within the EM CLI verb db_software_maintenance see db_sm_performoperation_deploy in Enterprise Manager Command Line Interface.

The general layout of a Deploy instruction is as follows:

emcli db_software_maintenance 
-performOperation
-name=<User specified Operation name>
-purpose=<Operation Type>
-target_type=<type of target>
-target_list=<list of targets>
-normal_credential=<Named Credential: Credential Owner>
-privilege_credential=<Named Credential: Credential Owner>
[-windows_sec_credential=<Named Credential: Credential Owner>]
-input_file="data:<location of input file>"
[-standbyAutoDeploy=true|false] [-procedure_name_prefix="CustomUpdate"]
  • name: This is the unique name of the operation.
  • purpose: The purpose of the instructions, in this case DEPLOY:
    • DEPLOY_DB_SOFTWARE
    • DEPLOY_RAC_SOFTWARE
    • DEPLOY_SIHA_SOFTWARE
    • DEPLOY_GI_SOFTWARE
    • DEPLOY_CBD_SOFTWARE
    .
  • target_type: The type of target on which this operation is being performed. Refer to the table EM CLI Command Inputs Based on Entity Type for valid values.
  • target_list: This is a comma separated list of targets which need to be patched.
    • Targets of homogenous types are supported in a single fleet operation.
    • Unique list of hosts based on this target list is displayed and start stage of Oracle home software on those hosts.
    • If targets running from same Oracle home are provided in this list, the stage and deploy operation will be triggered only once and not for all targets.
  • normal_credential:Unix only, this must be entered in the format <Named Credential: Credential Owner> where:
    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.
    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.
  • privilege_credential: Unix only, this must be entered in the format <Named Credential: Credential Owner> where:
    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.
    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.

    Note:

    These credentials are used to run scripts as root.
  • windows_sec_credential: Windows Single Instance database only, this must be entered in the format <Named Credential: Credential Owner> where:
    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.
    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.
    Windows credentials example: 
    emcli db_software_maintenance -performOperation -name="Deploy a Patched Home" 
-purpose=DEPLOY_DB_SOFTWARE -target_type=oracle_database -target_list="ORCL1910.abc.sample.com"  
-input_file="data:/tmp/deploywin.properties" -normal_credential="LOCALADMIN:SYSMAN"
-windows_sec_credential="LOCALUSERCRED:SYSMAN"
  • start_schedule: The date on which the stage and deploy is to be started if it is to be started in the future with the following format: "start_time:yyyy/mm/dd HH:mm". This is an optional parameter. If no date is provided, the fleet operation will start immediately.
  • standbyAutoDeploy: This is an optional parameter with default value as True. If the target is a primary database, a new Oracle home with the same gold image version as Primary is deployed automatically on the Standby host. This parameter disables the automatic deployment of software on standby host when specified as false. If this value is false, standby staging/deploy can be performed independently using the above EM CLI command.
  • procedure_name_prefix: This is an optional parameter. It is used to provide a custom name for the deployment procedure Instance name. The supported operations are DEPLOY, UPDATE, CLEANUP and ROLLBACK.
  • input_file: This file will contain the following entries:
    • NEW_ORACLE_HOME_LIST=<Absolute path to file system location for new Oracle Home>
    • workingDir=<Name of temp directory>: This is the location in which the new Oracle Home will be installed on all the hosts. The Credential Owner must have read and write access to this location.
    • dispatchLoc=<Dispatch location>: The location in which the scripts will be staged on the host. These scripts can be executed by a root user.
    • SKIP_PREREQUISITE_CHECKS=<true/false>: The default value is false.
    • SKIP_CVU_CHECK=<true|false>: The default value is false.
    • PREREQS_ONLY=<true/false>: The default value is false. This can be used for identify errors during the prerequisite checks. The actual deployment will not happen when the value is set to “true”.
    • dispatchLoc=<Absolute path to the custom location>: This parameter has been added for operations that stage and use a dispatcher location, using an existing, read-only location to use pre-staged dispatcher as well as fleet scripts. This is an added security measure to only execute as root through a custom script which is only allowed to execute a reduced number of files.
    • isRootPreStaged=<true/false>: If this flag is set to true the root components need to be pre-staged into the dispatchLoc location. This is helpful in skipping the pre-staged step when the components have already been pre-staged manually.

      In order to pre-stage root, the following components need to be previously staged and submitted:

      • Root Dispatcher component (Unix only requirement)
      • Root Scripts, requires an additional step of unzipping the scripts in the dispatchLoc location.
      • Common Root component

      For detailed instructions on how to pre-stage the Root Components, see Manually Staging the Root Components For Fleet Maintenance.

      Note:

      If the flag is set to false and the components pre-staged, the components will be overwritten
    • RUN_CVU_FROM_OH=<true/false>: The Cluster Verification Utility runs by default from the Oracle Home. Setting this flag to false will allow you to run the CVU from the Software Library used in conjunction with CUSTOM_CVU_COMPONENT. This flag will also be set to false in the following two cases:
      • Database version is 12.1 or below, Cluster Verification Utility is not part of oracle home binaries for these versions.
      • Standalone SIDB (Single Instance Database), as Cluster Verification Utility is not part of SIDB oracle home binaries.
    • CUSTOM_CVU_COMPONENT=<Path of Custom CVU in the Software Library>: This component used in conjunction with RUN_CVU_FROM_OH=false allows you to run the CVU from the Software Library instead of the Oracle home by setting a path from where your custom CVU is located.

Deploy an Oracle Home

The following example goes over the deployment of an Oracle Home. The DEPLOY_DB_SOFTWARE purpose can be used for the creation of a Single Instance Oracle Database and Pluggable Database: 

emcli db_software_maintenance 
-performOperation 
-name="Deploy Home"
-purpose="DEPLOY_DB_SOFTWARE"
-target_type= <oracle_database or oracle_pdb>
-target_list=db1221
-normal_credential="NORMAL:SYSMAN"
-privilege_credential="ROOT:SYSMAN"
-input_file="data:/deploy_OH.txt"
-attach_home=true

Note:

For Container databases and RAC Container database creation use verb DEPLOY_CDB, instead of DEPLOY_DB_SOFTWARE.

Deploy RAC Database

The following code snippet shows how to deploy an RAC Database using the DEPLOY_RAC_SOFTWARE purpose within the db_software_maintenance emcli verb
emcli db_software_maintenance 
-performOperation 
-name="Deploy Home"
-purpose="DEPLOY_RAC_SOFTWARE"
-target_type= rac_database
-normal_credential="NORMAL:SYSMAN"
-privilege_credential="ROOT:SYSMAN"
-input_file="data:/deploy_OH.txt"
-attach_home=true

Deploy an Oracle Restart


emcli db_software_maintenance 
-performOperation -name="Deploy Home"
-name="Deploy Home"
-purpose="DEPLOY_SIHA_SOFTWARE"
-target_type= has
-normal_credential="NC_HOST_CREDS:SYSMAN"
-privilege_credential="HOST_PRIV:SYSMAN"
-input_file="data:/deploy_OH.txt"
-SKIP_CVU_CHECK=<true/false>
SKIP_CVU_CHECK: This flag allows skipping the CVU check if set to true. This is an optional flag only used for DEPLOY_SIHA and DEPLOY_GI operations.

Deploy an Oracle Grid Infrastructure Database

emcli db_software_maintenance 
-performOperation 
-name="Deploy-1120407 GI Home"
-purpose=DEPLOY_GI_SOFTWARE
-target_type=input_file
-target_list="CLUSTER1"
-normal_credential="NC_HOST_CREDS:TESTSUPERADMIN"
-privilege_credential="HOST_PRIV:TESTSUPERADMIN"
-inputfile="data:/usr/oracle/deploy.txt"
SKIP_CVU_Check=<true/false>"
SKIP_CVU_CHECK: This flag allows skipping the CVU check if set to true. This is an optional flag only used for DEPLOY_SIHA and DEPLOY_GI operations.

Use DEPLOY_GI_SOFTWARE if you are planning to upgrade your grid infrastructure from 12.X to 19C or 18C. Once the new 19C or 18C home is deployed, perform UPDATE_GI. Finally use the DEPLOY_RAC_SOFTWARE to deploy the RAC home binaries of 19C or 18C

Deploy Container Databases

In case of container databases, users have flexibility to update one or more PDB at a time rather than the entire container being updated at the same time. This is made possible by creating a new container database or using an existing container on staged/patched Oracle Home and moving the PDB to the new container on demand. A new CDB is created using the structure-only template. Deploy software must be performed before a DEPLOY_CDB operation.

Note:

A PDB target may also be patched using an existing Container Database at a higher patch level, in this case ATTACH_CDB operation must be performed and DEPLOY_CDB operations must be skipped. 
emcli db_software_maintenance 
-performOperation -purpose="DEPLOY_CDB" 
-target_list="<CDB Name that is being patched>" 
-target_type="<target type>" -name="Operation Name” 
-description="Operation description" 
-db_prefix|db_name="<DB Name Prefix or DB Name>" 
-normal_credential="<credential name>" 
-privilege_credential="<credential name>" 
-database_credential=" <SYSDBA credential name>"
If a container database already exists with the required image, then the same can be attached for housing the PDB when they are updated.
emcli db_software_maintenance 
-performOperation -purpose="ATTACH_CDB" 
-target_list="<CDB Name that is being patched>"
-target_type="<target type>" 
-name="Operation Name” 
-description="Operation description" 
-destinationCDB="<Container database to which PDBs will be migrated>" 
-normal_credential="<credential name>" 
-privilege_credential="<credential name>" 
-database_credential="<SYSDBA credential name>"
Consolidate Oracle Homes

You can now use the EM CLI attach_home flag to merge homes of databases running from different Oracle Homes, on the same host. A second Oracle Home can be merged to a previously deployed Oracle Home if the two homes are patched with the same version of the Gold Image.

Note:

A PDB target may also be patched using an existing Container Database at a higher patch level, in this case ATTACH_CDB operation must be performed and deploy-software and deploy-CDB operations must be skipped.
User can pass the attach_home=true flag and provide the Oracle Home location within the input file, where an Oracle Home with the same Gold Image version has already been deployed. This will skip the actual deployment and add the required lineage to the new Oracle Home.
emcli db_software_maintenance 
-performOperation 
-name="Deploy Home"
-purpose="DEPLOY_DB_SOFTWARE" 
-target_type=oracle_database -target_list=db1221
-normal_credential="NORMAL:SYSMAN" -privilege_credential="ROOT:SYSMAN"
-input_file="data:/scratch/deploy_OH.prop" -attach_home=true
In order for the attach_home=true flag to execute successfully, two validations will be performed before moving Databases from Oracle Homes:
  • If a user provides attach_home=true flag, but the deployed version does not match between Oracle Homes, the deployment will not submit and the following message will appear: A different version is deployed at the given location, you can attach to the same version of an image deployed.
  • If a user provides attach_home=true flag, for a location where there is no deployed Oracle Home using Fleet Management; the deployment will not submit and the following message will appear: You can attach to the same version of deployed home at the given location.
For more information on EM CLI verb db_software_maintenance see db_software_maintenance in Enterprise Manager Command Line Interface.

Reorganizing your Oracle Homes can be useful in grouping databases according to location (same host) and version (same Gold Image). By consolidating Oracle Homes using attach_home=true flag you can simplify how patches are applied throughout an entire host, helping keep all databases up to date in the most efficient manner. Consolidating databases within a host can also help free space, once databases are merged into a common Oracle Home, empty Oracle Homes can be cleaned up using the Oracle Home cleanup EM CLI string. For more information see Clean Up Operations.

Update Operations
Update operations are the most common operations performed within Fleet Maintenance. There are two types of supported UPDATE scenarios: updates and upgrades. An update is a minor improvement operation, moving an Oracle Home from one patch set to another (Ex: 12.1.0.1 to 12.1.0.2) whereas an upgrade, is a major improvement, moving an Oracle Database from one major release to another (ex: 12.2.0.1 to 18.3 or 18.x to 19.x). All the steps such as Gold Image creation, image subscription and deploy image remain the same.

Note:

  • Currently we don’t support node-wise update for Upgrades. The update command for “Database Upgrade” requires database credentials to be provided as part of the command.
  • Before performing an UPDATE operation, if your listener is in a custom location, be sure to first set the TNS_ADMIN environment variable to this location . Next, restart the agent and then proceed with these operations.
  • If during a database or RAC update you need to update any static entry and your listener.ora is located in the grid Oracle Home default location ($GI_HOME/network/admin) normal credentials will not work (for example DB Home Owner). This is because the owner of the file is the Grid Home owner; make sure the file has permissions to at least group level to be modified by both Database and Grid Oracle Home Users.
  • Refer to the Oracle Database Upgrade Guide for the supported upgrade paths.

UPDATE_DB

This command moves an Oracle Database from its Oracle Home to the newly created Gold Image standard Oracle Home. 
emcli db_software_maintenance 
-performOperation -purpose=”UPDATE_DB” 
—target_list=”db1221” 
—target_type=”oracle_db” 
—name=”Operation Name” 
–description=”Operation description” 
-normal_credential="NORMAL:SYSMAN" 
-privilege_credential=”PRIV:SYSMAN” 
—database_credential=”DB_SYS_CREDS:SYSMAN”

Note:

For Windows Single Instance database update operations use windows_sec_credential="Named Credential: Credential Owner" instead of privilege_credential.
Example:
emcli db_software_maintenance -performOperation -name="Update SIDB" -purpose=UPDATE_DB 
-target_type=oracle_database -target_list="ORCL1910.abc.sample.com" -rolling=false 
-normal_credential="LOCALADMIN:SYSMAN" -windows_sec_credential="LOCALUSERCRED:SYSMAN" 
-database_credential="SYSDBA:SYSMAN"

UPDATE_PDB

Moves a Pluggable Database from its predecessor container to the newly available successor container. This can be executed only if the Attach CDB / Deploy CDB operation has been performed.
emcli db_software_maintenance 
-performOperation -purpose=”UPDATE_PDB” 
—target_list=”pdb1331” 
—target_type=”oracle_pdb” 
—name=”Operation Name” 
–description=”Operation description” 
-normal_credential="NORMAL:SYSMAN" 
-privilege_credential=”PRIV:SYSMAN” 
—database_credential=”DB_SYS_CREDS:SYSMAN”

UPDATE_GI

emcli db_software_maintenance 
-performOperation 
-name="Update Cluster" 
-purpose=UPDATE_GI 
-target_type=cluster 
-target_list= CLUSTER1 
-normal_credential="NC_HOST_CREDS:SYSMAN" 
-privilege_credential="HOST_PRIV:SYSMAN" 
-rolling=<true/false> 
-node_list="host1.example.com" 
–startupDatabase=<true/false>
-SKIP_CVU_CHECK=<true/false>
For a use case on UPDATE_GI and a detailed explanation see: Node Wise RAC Database / Cluster Update

SKIP_CVU_CHECK: This flag allows skipping the CVU check if set to true. This is an optional flag only used for UPDATE_GI and UPDATE_SIHA operations.

When performing UPDATE_GI operations and you need to pass multiple clusters in the -target_list, -node_list is not supported.

UPDATE_RACDB

The EM CLI command format for UPDATE_RACDB :
emcli db_software_maintenance -performOperation -name="Update RAC DB" 
-purpose=UPDATE_RACDB 
-target_type=<target_type> 
-target_list==<List of targets> 
-normal_credential="NC_HOST_CREDS:SYSMAN" 
-privilege_credential="HOST_PRIV:SYSMAN" 
-database_credential=<SYSDBA credentials of the database>
-rolling=<true/false> 
-node_list="host1.example.com"
-drain_timeout = <time in seconds>
  • node_list: This is a comma separated list of hosts on which the instances need to be updated.
    For example, if RACDB is running on a 4 node cluster host1, host2, host3, and host4 and you choose to update the instances only 2 hosts at a time; the value of this parameter needs to be specified as node_list="host1, host2"

    Note:

    This is an optional parameter. If no date is provided, the fleet operation will start immediately.
  • drain_timeout: This optional parameter can be used for both rolling and non rolling use cases and can be passed as an EM CLI argument or as an input_file parameter. This drain parameter is a time measure of seconds allowed in order to complete the resource draining action. By default, this parameter is not set.
For primary and standby databases, upgrades need to be done through the Rolling Upgrade user interface in Enterprise Manager. The wizard can be launched from the target database home page (either primary or standby database). On the Database home page, select Oracle Database, Provisioning, then select Upgrade Database.

Transparent Data Encryption (TDE) Support in Fleet Maintenance

Fleet Maintenance now supports updating Databases, Container Databases and Pluggable Databases that have tables encripted using TDE.

For Oracle Databases and Container Databases, using oracle_database Target_type:

  • When executing UPDATE_DB command, the database credentials should be provided using the existing flag -database_credential="DB_SYS_CREDS:SYSMAN". If the Database credentials are not provided, the preferred credentials, if set, will be used.
  • The TDE wallet password must be provided in the input file -input_file="data:/<file pathc>/input.properties" during UPDATE_DB

    Example: srcWalletPassword=welcome123.

Note:

  • If the Database credentials are not provided or if anything fails during any operation of TDE, the TDE configuration will be skipped but fleet database patching will not fail.
  • After migration you may need to manually open the Wallet file to access encrypted data in the database.

For Oracle Pluggable Databases, using oracle_pdb Target_type:

  • When executing UPDATE_PDB, the Database credentials should be provided using the existing flag -database_credential="DB_SYS_CREDS:SYSMAN". If the Database credentials are not provided, the preferred credentials, if set, will be used.
  • TDE must be already configured in the destination CDB
  • The TDE wallet source and destination passwords must be provided in the input file -input_file="data:/scratch/input.properties" during UPDATE_PDB

    Example: srcWalletPassword=welcome123, destWalletPassword=welcome123

Node Wise RAC Database / Cluster Update
A cluster update always requires that all the RAC database instances running on that node be shut down during the switch process of the cluster instance. A cluster update, followed by a RAC database update results in a database instance getting restarted twice.

There may be several situations where you as the administrator may require more control over the switch process. For example, you may choose to perform a node-wise update of the cluster and RAC databases in order to avoid multiple restarts of the database instances. You may also need to perform node specific pre and post steps.

This option provides this control by enabling you to perform the following tasks for each node:

  • Switch the cluster instance
  • Leave the RAC database instances shutdown

    For example, RAC databases RACDB_112 and RACDB_121 are running on this cluster. The instances RACDB_112_1 and RACDB_121_1 running on this specific node will continue to remain shut down after the cluster instance is switched. 

    emcli db_software_maintenance 
-performOperation 
-name="Update Cluster" 
-purpose=UPDATE_GI 
-target_type=cluster 
-target_list= CLUSTER1 
-normal_credential="NC_HOST_CREDS:SYSMAN" 
-privilege_credential="HOST_PRIV:SYSMAN" 
-rolling=true -node_list="host1.example.com" 
–startupDatabase=false
-skip_cvu_check=true
  • Switch all the RAC database instances on the same node.
  • This step will switch the instances RACDB_112_1 and RACDB_121_1 to the new home and will restart the same.

    For example, consider RAC databases RACDB_112 and RACDB_121 are running on this cluster. The instances RACDB_112_1 and RACDB_121_1 running on this specific node will continue to remain shut down after the cluster instance is switched.

  • SKIP_CVU_CHECK: This flag allows skipping the CVU check if set to true. This is an optional flag in UPDATE_GI operations.
  • When performing UPDATE_GI operations and you need to pass multiple clusters in the -target_list, -node_list is not supported.
Update Oracle Homes Using Patched Oracle Homes

The following section highlights how Oracle Homes can be switched to other patched Oracle Homes with least amount of downtime.

Database Type Steps Performed
Single Instance
  • Target is put in Blackout mode.
  • Configuration files like: spfile, password, listener.ora, sqlnet.ora, tnsnames.ora are copied over to the patched Home.
  • oratab file entries are updated
  • Instance is brought down and brought up from the patched home.
  • Target is brought of Blackout mode.
  • For pre-12c databases SQLs are run using SQL*Plus. For 12c and higher databases, the Datapatch utility is called to make data changes.
Grid Infrastructure
  • All relevant targets are put in Blackout mode.
  • Backup CRS configuration files from the source home directory: $SRC_HOME/crs/utl/crsconfig_dirs.
  • Configuration files like: spfile, password, listener.ora, sqlnet.ora, tnsnames.ora are copied over to the patched Home.
  • oratab file entries are updated
  • HAS Instance, ASM Instance, Management database instance, Scan Listeners and Grid Listeners and all database instances are brought down and brought up with Patched Home as new Oracle Homes.
  • Configuration scripts are run.
  • All targets are brought out of Blackout mode.
  • If the management database is used, pre-12c databases SQLs are run using SQL*Plus. For 12c and higher databases, the Datapatch utility is called to make data changes..
RAC Rolling Node For each node:
  • Target is put in Blackout mode.
  • Configuration files like spfile, password, listener.ora, sqlnet.ora, tnsnames.ora are copied over to the patched Home.
  • oratab file entries are updated
  • Instance is brought down and brought up with Patched Home as new Oracle Home.
  • Target is brought out of Blackout mode.
  • For pre-12c databases SQLs are run using SQL*Plus. For 12c and higher databases, the Datapatch utility is called to make data changes.
RAC Non-Rolling Node
  • All RAC nodes are put in Blackout mode.
  • Configuration files like spfile, password, listener.ora, sqlnet.ora, tnsnames.ora are copied over to the patched Home.
  • oratab file entries are updated
  • Instance is brought down and brought up with Patched Home as new Oracle Home concurrently.
  • For pre-12c databases SQLs are run using SQL*Plus. For 12c and higher databases, the Datapatch utility is called to make data changes.
Migrating the Listeners

If there are listeners running from the database home, use the following verb to migrate them to the parallel Oracle Home. You can use this command to migrate listeners running from Oracle database homes. Listeners running from Grid Infrastructure homes are automatically migrated during the GI update process.

Sample:

emcli db_software_maintenance -performOperation -name="Update Listener" -purpose=migrate_listener 
-target_type=oracle_database -target_list="DB1" -normal_credential="NC_HOST_CREDS:SYSMAN" 
-privilege_credential="HOST PRIV:SYSMAN" -start_schedule="start_time:yyyy/mm/dd HH:mm"
Where:
  • name: This is the unique name of the operation.
  • purpose: MIGRATE_LISTENER.
  • target_type: The type of target on which this operation is being performed. This can be rac_database for RAC and oracle_database for single instance databases.
  • target_list: This is a comma separated list of targets which are to be migrated.
  • normal_credential: This must be entered in the format <Named Credential: Credential Owner> where:
    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.
    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.
  • privilege_credential: This must be entered in the format <Named Credential: Credential Owner> where:
    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.
    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.

    Note:

    These credentials are used to run scripts as root.
  • start_schedule: The date on which the stage and deploy is to be started if it is to be started in the future, use format: start_time:yyyy/mm/dd HH:mm. This is an optional parameter. If no date is provided, the fleet operation will start immediately.

Note:

For Windows Single Instance database listener migrations use windows_sec_credential="Named Credential: Credential Owner" instead of privilege_credential.
Example:
emcli db_software_maintenance -performOperation -name="Update Listener" -purpose=migrate_listener
-target_type=oracle_database -target_list="ORCL1910.abc.sample.com" 
-normal_credential="LOCALADMIN:SYSMAN" -windows_sec_credential="LOCALUSERCRED:SYSMAN"

Sample Output

Processing target "CLUSTER1"...

Checking if target is already running from the current version...

Check Passed.

Checking image subscription...

Check image subscription passed.

You can monitor the patch operation status with the following command:

emcli get_instance_status -exec=25BE102DD7CB544EE053D903C40A784D -details -xml
Rollback Operations

The Rollback command is used to switch the database back to the previous Oracle Home after the Update operation has been completed.

Note:

  • Before performing a rollback operation, if your listener is in a custom location, be sure to first set the TNS_ADMIN environment variable to this location . Next, restart the agent and then proceed with these operations.
  • If during a database or RAC rollback you need to update any Static Entry and your listener.ora is located in the grid Oracle Home default location ($ GI_HOME/network/admin) normal credentials will not work (for example DB Home Owner). This is because the owner of the file is the Grid Home owner. Make sure the file has permissions to at least group level to be modified by both Database and Grid Oracle Home Users.

Sample Code for ROLLBACK_DB

emcli db_software_maintenance 
-performOperation 
-name="Rollback DB" 
-purpose=ROLLBACK_DB 
-target_type=<target type> 
-target_list=<list of targets> 
-normal_credential="NC_HOST_CREDS:SYSMAN" 
-privilege_credential="HOST_PRIV:SYSMAN" 
-rolling=[true/false] 
-node_list="host1.example.com"
  • name: This is the unique name of the operation.
  • purpose: There are standard purposes that can be performed by Fleet Operations which can be:
    • ROLLBACK_DB
    • ROLLBACK_RACDB
    • ROLLBACK_GI
  • target_type: The type of target being provided in this operation which can "rac_database" or "oracle_database”.
  • target_list: This is a comma separated list of targets which need to be patched.
    • Targets of homogenous types are supported in a single fleet operation.
    • A unique list of hosts based on this target list is displayed and start stage of Oracle home software on those hosts.
    • If targets running from the same Oracle home are provided in this list, the stage and deploy operation will be started only once and not for all targets.
  • normal_credential: This must be entered in the format <Named Credential: Credential Owner> where:
    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.
    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.
  • privilege_credential: This must be entered in the format <Named Credential: Credential Owner> where:
    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.
    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.

    These credentials are used to run scripts as root.

  • non_rolling: By default, rollback is performed on all nodes. If the non_rolling back flag is enabled, you can select the list of nodes (using the node_list command) that are to be rolled back
  • rolling: By default rollback is performed in rolling fashion. This flag is used when the current Oracle home has patches that were applied in non-rolling mode (OJVM) and need to be rolled back.
  • node_list: This is a comma separated list of hosts on which the instances need to be updated.

    For example: If RACDB is running on a 4 node cluster host1, host2, host3, and host4 and you choose to update the instances in only 2 hosts at a time, the value of this parameter needs to be specified as node_list="host1, host2".

Note:

For Windows Single Instance database rollback operations use windows_sec_credential="Named Credential:Credential Owner" instead of privilege_credential
Example: 
emcli db_software_maintenance -performOperation -name="Rollback SIDB" -purpose=ROLLBACK_DB 
-target_type=oracle_database -target_list="ORCLTDE.abc.example.com" -rolling=false
-normal_credential="LOCALADMIN:SYSMAN" -windows_sec_credential="LOCALUSERCRED:SYSMAN"
-database_credential="SYSDBA:SYSMAN"

Sample Code for ROLLBACK_RACDB

emcli db_software_maintenance 
-performOperation 
-name="Rollback RAC DB" 
-purpose=ROLLBACK_RACDB 
-target_type=<target type> 
-target_list=<list of targets> 
-normal_credential="NC_HOST_CREDS:SYSMAN" 
-privilege_credential="HOST_PRIV:SYSMAN" 
-rolling=[true/false] 
-node_list="host1.example.com"
Sample Code For ROLLBACK_GI
emcli db_software_maintenance  
-performOperation  
-name="Rollback GRID"  
-purpose=ROLLBACK_GI  
-target_type=cluster 
-target_list="sample01-cluster"  
-normal_credential="NC_HOST_CREDS:SYSMAN"  
-privilege_credential="HOST_PRIV:SYSMAN"
-SKIP_CVU_CHECK=<true/false>
SKIP_CVU_CHECK: This flag allows skipping the CVU check if set to true. This is an optional flag only used for ROLLBACK_GI operations.
Sample Code for ROLLBACK_SIHA
emcli db_software_maintenance  
-performOperation  
-name="Rollback"  
-purpose="ROLLBACK_SIHA"  
-target_type=has  
-target_list="has_abc"  
-normal_credential="NC_HOST_CREDS:SYSMAN"  
-privilege_credential="HOST_PRIV:SYSMAN"
-SKIP_CVU_CHECK=<true/false>
SKIP_CVU_CHECK: This flag allows skipping the CVU check if set to true. This is an optional flag only used for ROLLBACK_GI operations.
Non-Rolling Applicable Patches

If the gold image contains a patch that is non-rolling applicable (For example OJVM patch pre-Jan 2017 PSUs), then every update or switch must be performed with the flag set to - rolling=false. This starts the database in Upgrade mode before applying the data changes. Then the database is shut down and restarted in Normal mode.

Updating and Rolling Back Standby Databases
This section is applicable for all primary and physical standby configurations (RAC - RAC, RAC - SI, SI - SI, RAC One - RAC One). Both the primary and standby databases need to be switched to the new Oracle home in this use case. A single switch operation cannot handle both primary and standby databases.

The procedure to update and roll back standby databases varies depending on the patch type (rolling applicable or not).

From Enterprise Manager 13.4 onwards, the STANDBY_START_OPTION parameter has been introduced to set the standby database start option after patching. This parameter should be included in -input_file while patching the standby database with the UPDATE_DB EM CLI verb.
  • If STANDBY_START_OPTION is provided while patching standby databases:

    Both rolling and non rolling standby databases will be started in the specified mode set in the -input_file after patching. If the parameter value is set as READ ONLY WITH APPLY , MRP will be started up, even if the MRP was not running before patching. Otherwise, the MRP status will enabled as set in the srcvtl configuration.

  • If STANDBY_START_OPTION is not provided while patching standby database:
    • Rolling applicable patch: The standby database's existing open_mode and MRP status will be retained after patching. If unable to fetch the existing open_mode and MRP status for the standby database, it will be started in default mode and MRP status will be enabled as set in the srcvtl configuration.

      Note:

      The UPDATE_DB procedure will not stop, if any issue is detected when fetching the open_mode and MRP status. An error message will be shown in the Start DB Instance from destination home step in the UPDATE_DB procedure.
    • Non-Rolling applicable patch: Standby database will restart in a default mode and MRP status will be enabled as set in the srcvtl configuration.
For more information on the STANDBY_START_OPTION EM CLI verb see db_cloud_maintenance in Oracle Enterprise Manager Command Line Interface .

Note:

Before performing an UPDATE or ROLLBACK operation, if your listener is in a custom location, be sure to first set the TNS_ADMIN environment variable to this location . Next, restart the agent and then proceed with these operations.

For rolling applicable patches like database PSUs, follow these steps:

  • Update the standby database:

    emcli db_software_maintenance -performOperation -name=<User Specified Operation Name> -purpose=<Operation Type> 
-target_type=<Target Type> -target_list=<List of targets> -normal_credential=<credential name> 
-privilege_credential=<credential name> -database_credential=<SYSDBA credentials of the database> 
-dataguard_role=standby -input_file="data:<location of input file>"

    Description of Input Parameters

    • input_file: This is an optional parameter. The parameter(s) that can be specified here are:
      • workingDir: The location and name of the temporary directory.
      • disableDG: True/False, default value is false. This should be set to ‘true’ if the standby is managed by Data Guard.

  • Update the primary database:

    emcli db_software_maintenance -performOperation -name=<User Specified Operation Name> -purpose=<Operation Type> 
—target_type=<Target Type> -target_list=<List of targets> -normal_credential=<credential name> 
-privilege_credential=<credential name> -dataguard_role=primary [–ignoreStandbyPrereq=true|false] 
-input_file="data:<location of input file>”

    Description of Input Parameters

    • ignoreStandbyPrereq: The default value is false. This disables verification check if the Standby is on the same image version to which the Primary is being moved.
    • input_file: This is an optional parameter. The parameter(s) that can be specified here are:
      • workingDir: The location and name of the temporary directory.
      • enableDG: True/False, default value is false. This should be set to ‘true’ if the standby is managed by Data Guard.

For non-rolling applicable patches such as OJVM (pre-Jan 2017 PSUs), follow these steps:

  • Update the standby database 
    emcli db_software_maintenance -performOperation -name=<User Specified Operation Name> -purpose=<Operation Type> 
—target_type=<Target Type> —target_list=<List of targets> -normal_credential=<credential name> 
-privilege_credential=<credential name> —dataguard_role=standby —startupAfterSwitch=false 
—input_file=”data:<location of input file>”

    Description of Input Parameters

    • startupAfterSwitch: For non-rolling patches, it is necessary to bring up the Primary database first from the patched home. It will ensure that the Standby database is left in a shutdown state during the Update operation. The standby database will be started in a separate step after the Primary database is patched and started.

    • input_file: This is an optional parameter. The parameter(s) that can be specified here are:

      • workingDirThe location and name of the temporary directory.
      • disableDG True/false, the default value is false. This should be set to ‘true’ if the standby is managed by Data Guard
  • Update the primary database with dataguard_role=Primary
    emcli db_software_maintenance -performOperation -name=<User Specified Operation Name> -purpose=<Operation Type> 
-target_type=<Target Type> —target_list=<List of targets> -normal_credential=<credential name> 
-privilege_credential=<credential name> -dataguard_role=primary rolling=false -input_file="data:<location of input file>”

    Description of Input Parameters

    • input_file: This is an optional parameter. The parameter(s) that can be specified here are:
      • workingDir: Name and location of the temporary directory.
  • Start the standby database from a patched home
    emcli db_software_maintenance -performOperation -name=<User Specified Operation Name> -purpose=<Operation Type> 
-target_type=<Target Type> -target_list=<List of targets> -normal_credential=credential name> 
-privilege_credential=<credential name> -dataguard_role=standby –startupDatabase=true -skipSwitchDatabase=true 
-input_file=”data:<location of input file>”

    Description of Input Parameters

    • startupDatabase: It should always be set to true. This enables the starting of the Standby database from the patched home.
    • skipSwitchDatabase: It should be set to true. It skips the switching of database to patched home since it is already performed in earlier steps.
    • input_file: This is an optional parameter. The parameter(s) that can be specified here are:
      • workingDir: The name and location of the temporary directory.
      • enableDG: True/False, default value is false. This should be set to ‘true’ if the standby is managed by Data Guard.
      • primary_dbhost_creds: This is required because the Data Guard is enabled through the Primary Host. This can be the same as what is used in the Primary database update.

Note:

The rollback process is the same but the purpose value will be different. Refer to the EM CLI Command Inputs Based on Entity Type table for the correct value.
Rolling Back Listeners

Verb

This command is used to switch the listeners back to the old Oracle Home after the Update operation has been completed.

emcli db_software_maintenance -performOperation -name="Update Listener" -purpose=rollback_listener -target_type=oracle_database -target_list="DB1" -normal_credential="NC_HOST_CREDS:SYSMAN" -privilege_credential="HOST PRIV:SYSMAN"
where:

  • name: This is the unique name of the operation.

  • purpose: ROLLBACK_LISTENER

  • target_type: The type of target on which this operation is being performed. This can be "rac_database" for RAC and "oracle_database" for single instance databases.

  • target_list: This is a comma separated list of targets which need to be patched.

    • Targets of homogenous types are supported in a single fleet operation.

    • A unique list of hosts based on this target list is displayed and start stage of Oracle home software on those hosts.

    • If targets running from the same Oracle home are provided in this list, the stage and deploy operation will be started only once and not for all targets.

  • normal_credential: This must be entered in the format <Named Credential: Credential Owner> where:

    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.

    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.

  • privilege_credential: This must be entered in the format <Named Credential: Credential Owner> where:

    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.

    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.

    These credentials are used to run scripts as root.

Clean Up Operations

Oracle homes and Container Databases consume valuable storage space, they can be cleaned up to release space when they are no longer in use. This operation removes unused, empty no longer needed Oracle Homes or Container Databases (CDB) to help you better administrate space and resources.

Note:

If any target is associated with the given home, Cleanup will be not done for the given home. User has to provide homes on all the targets within an Oracle Home before Cleanup can be done. For RAC Database Oracle Homes, you will need to pass all nodes of Oracle Home name by comma separator value and Cleanup cannot be done from one of the nodes.

Cleaning Up Oracle Homes

There are two ways to clean up Oracle Homes:
  • A user can cleanup old Oracle Homes of recently Fleet patched databases by specifying a Database target list. The Cleanup operation will find older eligible Oracle Homers for the patched Database targets and perform a cleanup.
  • If there are any orphan homes within the lineage path, these can be cleaned up by passing a list of Oracle Homes directly to the db_software_maintenance verb.

To perform an Oracle Home cleanup, the following command string will need to be entered in EM CLI:

emcli db_software_maintenance -performOperation 
-name="cleanup"
-purpose="CLEANUP_SOFTWARE" 
-target_list=<List of home targets>
-target_type=oracle_home 
-normal_credential=NORMALCRED:SYSMAN
-privilege_credential=ROOTCRED:SYSMAN
-reportOnly=<true/false> 
-workDir=<working directory>
Description of Input Variables
  • name: This is the unique name of the operation.
  • purpose: CLEANUP_SOFTWARE, use this purpose only for Oracle Homes.
  • target_type: The type of target on which this operation is being performed.
  • target_list: This is a comma separated list of either Databases or Oracle Home targets which need to be cleaned up.
  • normal_credential: This must be entered in the format <Named Credential: Credential Owner> where:
    • <Named Credential>: Named credential for the host where Oracle home was deployed.
    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.
  • privilege_credential: This credential must have root privilege and must be entered in the format <Named Credential: Credential Owner> where:
    • <Named Credential>: Named credential for the host where Oracle home was deployed.
    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.
    These credentials are used to run scripts as root.
  • force: The default value for this optional flag is false. When set to true this flag forces an Oracle Home cleanup to occur even if there are potential conflicts, like a break within the lineage, with the databases contained within.

    In its default value of false, should conflicts arise when performing an Oracle Home cleanup the process stops and you see a warning message in the EM CLI console.

  • reportOnly: The default value is false. When set to true, it prints the eligible homes for deletion but the homes are not deleted.
Cleaning Oracle Homes on Windows Single Instance Database Example:
emcli db_software_maintenance 
-performOperation -name="Clean"
-purpose=CLEANUP_SOFTWARE -target_list=ORCLTDE.abc.example.com
-target_type=oracle_database
-normal_credential="LOCALADMIN:SYSMAN"
-workDir="C:\Users\LocalAdmin\work"

Oracle Homes can have several older versions of the same home, and these can accumulate space. You can modify how many of these previous Oracle Home versions are retained at any given point using the following EMCTL property: emctl set property -name oracle.sysman.emInternalSDK.db.gis.lineageLength -sysman_pwd $em_sysman_pwd –value <value> where <value> is the number of Oracle Homes that must be retained. The default value for how many versions are stored is 3.

For example, if there are four versions of an Oracle Home (with the target running from the fourth version), only the earliest of them can be deleted if the value is set to 3. Similarly if the value is set to 1, only the current Oracle home from which the target is running will remain and the other three homes will be deleted.

Cleaning Up Container Databases

When Fleet Maintenance patching operations occur, new Oracle Homes, and new Container Databases are deployed. As the individual PDB instances are patched, they are relocated to the newly deployed CDBs. Once all the PDBs in a CDB are patched, the old CDBs need to be deleted. The CLEANUP operation, part of the db_software_maintenance verb, automates the removal of old CDBs upon completion of a patching cycle.

Note:

Cleaning up container databases will clean all eligible homes corresponding to a CDB.
To perform an Oracle Container Database cleanup, the following command string will need to be entered in EM CLI:
emcli db_software_maintenance 
-performOperation 
-purpose="CLEANUP"
-target_list =<target CDB names> 
-target_type=oracle_pdb  
-name="Cleanup CDBs"
-normal_credential=NORMALCRED:SYSMAN  
-privilege_credential=ROOTCRED:SYSMAN 
-reportOnly=<true/false>
-workDir=<working directory>
You can cleanup lost lineage Oracle Container Databases with the following command string:
emcli db_software_maintenance 
-performOperation -purpose="CLEANUP"
-target_list =<target CDB names>  
-target_type=<oracle_database/rac_database> 
-name="Cleanup orphan CDBs" 
-normal_credential=NORMALCRED:SYSMAN
-privilege_credential=ROOTCRED:SYSMAN  
-reportOnly=true
-workDir=<working directory>
Description of Input Variables for Cleaning Container Databases
  • name: This is the unique name of the operation.
  • purpose: CLEANUP, use this purpose only for CDB cleanup.
  • target_type: The type of target on which this operation is being performed.
  • target_list: This is a comma separated list of targets which need to be cleaned up.
  • normal_credential: This must be entered in the format <Named Credential: Credential Owner> where:
    • <Named Credential>: Named credential for the Oracle Home where the CDB is deployed.
    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.
  • privilege_credential: This must be entered in the format <Named Credential: Credential Owner> where:
    • <Named Credential>: Named credential for the host where the CDB was deployed.
    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.
    These credentials are used to run scripts as root.
  • force: The default value for this optional flag is false. When set to true this flag forces an Oracle Home cleanup to occur even if there are potential conflicts, like a break within the lineage, with the databases contained within.

    In its default value of false, should conflicts arise when performing an Oracle Home cleanup the process stops and you see a warning message in the EM CLI console.

  • reportOnly: The default value is false. When set to true, it prints the eligible CDBs for deletion but the Datbasese are not deleted.

Note:

For further information on CLEANUP_SOFTWARE and database software maintenance tasks and using db_software_maintenance see the following:
Emergency Patching

You can now perform emergency patching with Fleet Maintenance. Emergency patching does not replace regular maintenance cycle patching, non-critical patches should be flagged for inclusion into the next version of the image. Emergency patched databases will be labeled as Rogue databases and will need to be reconciled in the next maintenance cycle either by rolling the changes to a new version of the image or override it with the latest version.

Emergency patching with Fleet Maintenance will not require the creation of a new version of a Gold Image. Databases that require an emergency patch will be switched out to new homes similar to the process used for scheduled maintenance. By switching the problem databases to new homes they can be isolated and patched without impacting functioning databases in the original home.

Overview of Steps For Emergency Patching

  1. Prepare a complete list of emergency patches to be applied.
    1. Identify required emergency patches.
    2. Identify and merge conflicts between patches applied and the list of patches to be applied.
    3. Request merge patches to Oracle Support (if required).
    4. Once all desired patches are available, download all patches into the software library.
  2. Deploy software along with emergency patches into a new home.
  3. Switch the emergency patched database to the new home.

Deploy Software Along with Emergency Patches

Single Instance Database
emcli db_software_maintenance 
-performOperation 
-name="Deploy - Critical one-off 12345"
-purpose=EMERGENCY_DEPLOY_DB_SOFTWARE  
-target_type='oracle_database' -target_list="DB1" 
-normal_credential="<normal credential>" 
-privilege_credential="<host privilege credential>"
-inputfile="data:/<user>/oracle/deploy.txt" 
-patch_list=<List of conflict-free patches in the software library>
Where:
  • PURPOSE must be set with EMERGENCY_DEPLOY_DB_SOFTWARE.
  • PATCH_LIST must follow the patchID:ReleaseID:PlatformID:LanguageID format. ReleaseID, PlatformID, LanguageID are optional arguments.
  • INPUTFILE must contain:
    • NEW_ORACLE_HOME_LIST=<Emergency home location>
    • DISPATCHER_LOC=<Dispatcher location>
    • PATCH_LIST=<List of conflict-free patches in the software library>
RAC Database
emcli db_software_maintenance -performOperation -name="Deploy - Critical one-off 12345"
-purpose=EMERGENCY_DEPLOY_RAC_SOFTWARE
-target_type='rac_database' -target_list="DB1"
-normal_credential="<normal credential>"
-privilege_credential="<host privilege credential>"
-inputfile="data:/<user>/oracle/deploy.txt"
-patch_list=<List of conflict-free patches in the software library>
Where:
  • PURPOSE must be set with EMERGENCY_DEPLOY_RAC_SOFTWARE.
  • patch_list Can be either passed as command line argument or as the input file parameter. In case of input file parameter the parameter should be defined in upper case.

Switch Database to Emergency Home

To switch database you will need to run an UPDATE_DB command, this will move the database to be patched to the new empty home.
emcli db_software_maintenance -performOperation -name="Update DB"
-purpose=UPDATE_DB  
-target_type=oracle_database 
-target_list="DB1"
-normal_credential="<normal credential>"
-privilege_credential="<host privilege credential>"
-destinationOracleHomeLocation=<path of the new Oracle Home Location>
-force=<true/false>
The force flag is by default set to false. The flag is mandatory if the target is subscribed to an image and you still want to switch the database to the emergency home.

Publish The New Version of the Image

The uploaded image is in DRAFT by default. As the administrator you have to explicitly mark it CURRENT in order to publish it. This is achieved by the following command:
emcli db_software_maintenance 
-updateVersionStatus
-version_id=<version_id> 
-status=CURRENT
Where
  • version_id is the target version to which the databases are to be patched.

Rollback Emergency Patches

Should a rollback be required, the database moves back into its original untouched home. This avoids any confusion whether the rollback correctly reverted the software and its file permissions or not. 
emcli db_software_maintenance 
-performOperation -purpose="ROLLBACK_DB"
-target_list="DB1" 
-target_type=oracle_database 
-name="RollbackDB"
-description="Relocates the DB from inactive CDB  to newly active CDB"
-normal_credential="<normal credential>"  
-privilege_credential="<host privilege credential>"
-database_credential="<Database credential>"

Database Fleet Maintenance - RESTful APIs

Gold Image REST APIs

Gold Image is the end of state software definition that contains information about the base software version along with the additional patches. The 'end-state definition' is the logical term; the physical software binary component that represents the end-state is called as a gold image. For more information on gold image , see the standard configuration described in Discovering Configuration Pollution.

Get a List of Software Images

Features Description
Request Method GET
URI https://<OMS_CONSOLE_HOST>:OMS_CONSOLE_PORT>/em/websvcs/restful/emws/db/goldimage/softwareimages
Request Headers

Authorization: Basic

Accept: application/json
Response 
{
		"totalResults": 2,
		"items": [
			{
				"name": "RAC121_a",
				"id": "4B7738536B6E7888E053057FB10ACF8C",
				"description": "RAC121",
				"version": "12.1.0.2.0",
				"platformName": "Linux x86-64",
				"dateCreated": "2017-03-24 15:09:21.0",
				"owner": "SYSMAN",
				"lastModifiedBy": "SYSMAN"
			},
			{
				"name": "RACImage11204",
				"id": "4B620EC24DCE61FAE053057FB10AC7D0",
				"description": "RACImage11204",
				"version": "12.1.0.2.0",
				"platformName": "Linux x86-64",
				"dateCreated": "2017-03-23 13:16:51.0",
				"owner": "SYSMAN",
				"lastModifiedBy": "SYSMAN"
			}
		]
}

Create Software Image

Features Description
Request Method POST
URI https://<OMS_CONSOLE_HOST>:OMS_CONSOLE_PORT>/em/websvcs/restful/emws/db/goldimage/softwareimages
Request Headers

Authorization: Basic

Content-Type: application/json
Playload 
{
	"imageName": "RAC121_a",
	"imageDescription": "RAC121",
	"refTargetName": "OraDB12Home1_1_example.exampledomain.com_190",
	"imageSwLibLocation": "DB Provisioning/12.1.0.2.0/goldimage",
	"refHostCredential": "NC_HOST_2017-03-18-103539:SYSMAN",
	"workingDirectory": "/tmp",
	"swLibStorageType": "OmsShared",
	"swLibStorageName": "swlib",
	"versionName": "PSUNo"
}
Response 
{
	"messages": ["Create Gold Image operation has been submitted successfully with the instance name : 
	'CreateGoldImageProfile_SYSMAN_03_27_2017_10_13_AM' and execution_guid=4BB1192C1A2F2AB3E053057FB10A792E",
	“You can track the status of operation using the following:”, 
	“EMCLI: emcli get_instance_status -exec=4BAFFB4FD4ED1B34E053057FB10A99BF”,
	"Browser:  https://blr123.example.com:111111/em/faces/core-jobs-procedureExecutionTracking?executionGUID=4BB1192C1A2F2AB3E053057FB10A792E"
	  ]
}
Description of the Input Variables in payload

  • imageName: The name of the gold image. This name must be unique across images.

  • imageDescription: A description of the image.

  • refTargetName: The Oracle home target that will be used to create this gold image. This is the database or Grid Infrastructure Oracle Home from the existing environment on which the 11.2.0.4 PSU and all the one-off patches have been applied. To find the reference target name, enter the following query on the Enterprise Manager repository:
    SELECT  distinct target_name FROM mgmt$target_properties 
WHERE target_name IN (SELECT target_name FROM mgmt_targets 
WHERE target_type='oracle_home'
AND host_name=<Host Name of this Oracle Home>
AND property_name='INSTALL_LOCATION'
AND property_value=<path of Oracle Home>)

  • imageSwLibLocation: Path in software library where the payload of the gold image will be stored.

  • refHostCredential: This is applicable for Database Gold Image only. This must be entered in the format <Named Credential: Credential Owner>

  • workingDirectory: The temporary location on the host of reference Oracle home target.

  • swLibStorageType: The Software Library storage type. This can be OMS Shared or OMS Agent File system.

  • swLibStorageName: The storage name for the Software Library. To retrieve this storage name, from the Enterprise menu, select Provisioning and Patching, then select Software Library. In the Software Library page, from the Actions menu, select Administration. On this page, check the value in the Name column to retrieve the storage name for the Software Library.

  • versionName: An image can have multiple versions. A default version of the image is created and more versions can be added.

Search Software Images

The search can be filtered using various inputs as query parameters. The allowed query parameters are:

  • Name

  • Version

  • Description

  • Owner

  • Target _type

Following is an example using query parameter “Name”:
Features Description
Request Method GET
URI https://<OMS_CONSOLE_HOST>/em/websvcs/restful/emws/db/goldimage/softwareimages/search?name=%RAC%_a
Request Headers

Authorization: Basic

Accept: application/json
Response 
{
	"totalResults": 1,
	"items": [
		{
			"name": "RAC121_a",
			"id": "4B7738536B6E7888E053057FB10ACF8C",
			"description": "RAC121",
			"version": "12.1.0.2.0",
			"platformName": "Linux x86-64",
			"dateCreated": "2017-03-24 15:09:21.0",
			"owner": "SYSMAN",
			"lastModifiedBy": "SYSMAN"
		}
	]
}

Delete a software image

Features Description
Request Method DELETE
URI https://<OMS_CONSOLE_HOST:OMS_CONSOLE_PORT>/em/websvcs/restful/emws/db/goldimage/softwareimages>
Request Headers

Authorization: Basic

Content-Type: application/json
Payload 
{
	"image_id" : "4B7738536B6E7888E053057FB10ACF8C"
)
Response 
{
		"messages" : "Image with id=4B7738536B6E7888E053057FB10ACF8C  deleted successfully"
}

Subscribing Targets to the Selected Image

Features Description
Request Method POST
URI https://<OMS_CONSOLE_HOST>:OMS_CONSOLE_PORT>/em/websvcs/restful/emws/db/goldimage/imagesubscriptions
Request Headers

Authorization: Basic

Content-Type: application/json
Payload 
{
	"imageId" : "4B620EC24DCE61FAE053057FB10AC7D0",
	"targetName" : "Examplerep_Database",
	"targetType" : "example_database"
}
Response 
{
	"messages": [
		"Target 'Examplerep_Database' subscribed successfully."
	]
}
Description of the Input Variables in payload

  • imageId: The GUID of the image.

  • targetType: The target type of the target to be subscribed to this image.

  • targetName: The name of the target.

Listing Subscriptions of an Image

Features Description
Request Method GET
URI https://<OMS_CONSOLE_HOST>:OMS_CONSOLE_PORT>/em/websvcs/restful/emws/db/goldimage/imagesubscriptions?image_id=4B620EC24DCE61FAE053057FB10AC7D0
Request Headers

Authorization: Basic

Accept: application/json
Response 
[
	{
		"imageId": "4B620EC24DCE61FAE053057FB10AC7D0",
		"targetGuid": "207B57A3FE300C86F81FE7D409F5DD1C",
		"dateSubscribed": "2017-03-24 16:01:25.0"
	}
]

UnSubscribing Targets from the Selected Image

Features Description
Request Method DELETE
URI https://<OMS_CONSOLE_HOST>:OMS_CONSOLE_PORT>/em/websvcs/restful/emws/db/goldimage/imagesubscriptions
Request Headers

Authorization: Basic

Content-Type: application/json
Payload 
{
	"imageId" : "4B620EC24DCE61FAE053057FB10AC7D0",
	"targetName" : "Examplerep_Database",
	"targetType" : "example_database"
}
Response 
{
	"messages": [
		"Target 'Examplerep_Database' unsubscribed successfully."
	]
}
Description of the Input Variables in payload

  • imageId: The GUID of the image.

  • targetType: The target type of the target to be unsubscribed from this image.

  • targetName: The name of the target.

Listing Target Subscriptions of an Image

Features Description
Request Method PUT
URI https://<OMS_CONSOLE_HOST>:OMS_CONSOLE_PORT>/em/websvcs/restful/emws/db/goldimage/targetsubscriptions
Request Headers

Authorization: Basic

Content-Type: application/json
Payload 
{
	"imageId" : "4B7738536B6E7888E053057FB10ACF8C ",
	"targetName" : "Examplerep_Database",
	"targetType" : "example_database"
}
Response 
{
	"totalResults": 1,
	"items": [
		{
			"targetName": "Examplerep_Database",
			"targetType": "example_database",
			"imageId": "4B7738536B6E7888E053057FB10ACF8C",
			"imageName": "RAC121_a",
			"subscriptionDate": "2017-03-27 10:06:00.0"
		}
	]
}
Description of the Input Variables in payload

  • imageId: The GUID of the image.

  • targetType: The target type of the target.

  • targetName: The name of the target.

Creating Version of Image

Features Description
Request Method POST
URI https://<OMS_CONSOLE_HOST>:OMS_CONSOLE_PORT>/em/websvcs/restful/emws/db/goldimage/versions
Request Headers

Authorization: Basic

Content-Type: application/json
Payload 
{
	"imageName": " 4B7738536B6E7888E053057FB10ACF8C",
	"refTargetName": "OraDB12Home1_1_slc06nag.example.com_190",
	"imageSwLibLocation": "DB Provisioning/12.1.0.2.0/goldimage",
	"refHostCredential": "NC_HOST_2017-03-18-103539:SYSMAN",
	"workingDirectory": "/tmp",
	"swLibStorageType": "OmsShared",
	"swLibStorageName": "swlib",
	"versionName": "PSUNo"
}
Response 
{
	"messages": ["Create Gold Image operation has been submitted successfully with the instance name :
	'CreateGoldImageProfile_SYSMAN_03_27_2017_10_13_AM' and execution_guid=4BB1192C1A2F2AB3E053057FB10A792E",
	“You can track the status of operation using the following:”,
	“EMCLI: emcli get_instance_status -exec=4BAFFB4FD4ED1B34E053057FB10A99BF”,
		"Browser:  https://blr123.example.oracle.com:11111/em/faces/core-jobs-procedureExecutionTracking?executionGUID=4BB1192C1A2F2AB3E053057FB10A792E"
			]
}
Description of Input parameters in payload

  • imageId: The GUID of the image.

  • refTargetName: The Oracle home target that will be used to create this gold image. This is the database or Grid Infrastructure Oracle Home from the existing environment on which the 11.2.0.4 PSU and all the one-off patches have been applied. To find the reference target name, enter the following query on the Enterprise Manager repository:
    SELECT  distinct target_name FROM mgmt$target_properties
WHERE target_name IN (SELECT target_name FROM mgmt_targets 
WHERE target_type='oracle_home'
AND host_name=<Host Name of this Oracle Home>
AND property_name='INSTALL_LOCATION'
AND property_value=<path of Oracle Home>)

  • imageSwLibLocation : Path in software library where the payload of the gold image will be stored.

  • refHostCredential: This is applicable for Database Gold Image only. This must be entered in the format<Named Credential: Credential Owner>

  • workingDirectory: The temporary location on the host of reference Oracle home target.

  • swLibStorageType: The Software Library storage type. This can be OMS Shared or OMS Agent File system.

  • swLibStorageName: The storage name for the Software Library. To retrieve this storage name, from the Enterprise menu, select Provisioning and Patching, then select Software Library. In the Software Library page, from the Actions menu, select Administration. On this page, check the value in the Name column to retrieve the storage name for the Software Library.

  • versionName: An image can have multiple versions. A default version of the image is created and more versions can be added.

Listing Versions

Features Description
Request Method GET
URI https://<OMS_CONSOLE_HOST>:OMS_CONSOLE_PORT>/em/websvcs/restful/emws/db/goldimage/versions?image_id=4B7738536B6E7888E053057FB10ACF8C
Request Headers

Authorization: Basic

Content-Type: application/json
Response 
{
	"totalResults": 1,
	"items": [
		{
			"name": "PSUNos",
			"versionId": "4BAFA861A7ED6603E053057FB10A0588",
			"imageId": "4B7738536B6E7888E053057FB10ACF8C",
			"externalId": "oracle:defaultService:em:provisioning:1:cmp:COMP_Component:SUB_OracleDB:4BAFA861A7E96603E053057FB10A0588:0.1",
			"status": "CURRENT",
			"position": "1",
			"hashCode": "C1622270664:B<NO_PATCHES>",
			"dateCreated": "2017-03-27 10:13:28.0",
			"provisioningStatus": "READY"
		}
	]
}

Deleting Versions

Features Description
Request Method DELETE
URI https://<OMS_CONSOLE_HOST>:OMS_CONSOLE_PORT>/em/websvcs/restful/emws/db/goldimage/versions
Request Headers

Authorization: Basic

Content-Type: application/json
Payload 
{
"versionId": "4BB099D42CC8671EE053057FB10A07DA"
}
Response 
{
	"messages": [
		"The following version will be deleted. 4BB099D42CC8671EE053057FB10A07DA"
		]
}

Deploy APIs

Feature Description

Request Method

POST

URI

/em/websvcs/restful/emws/db/fleetmaintenance/performOperation/deploy

Request Headers

Authorization: basic <generated credential value>

Content-Type: application/json

Body

 
{
"name": "<Operation Name>",
"targetName" : "<target name>",
"targetType" : "<Target type>",
"normalCredString" : "KKHANUJA:SYSMAN",
"privCredString" : "KKHANUJA_ROOT:SYSMAN",
"standbyAutoDeploy : "",
"skipCVUChecks" : "",
"skipPrereqs" : "",
"newOracleHomeLoc" : "/scratch/kkhanuja/oh1710"
}

Description of the Input Variables

  • name: Name of the operation.

  • targetName: Name of the target.

  • targetType: Refer to CLI Command Inputs Based on Entity Type table.

  • normalCredString: This must be entered in the format <Named Credential: Credential Owner> where:

    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.

    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.

  • privCredString: This must be entered in the format <Named Credential: Credential Owner> where:

    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.

    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.

    These credentials are used to run scripts as root.

  • standbyAutoDeploy: This is an optional parameter with default value as True. If the target is a primary database, a new Oracle home using the same gold image version as Primary is deployed automatically on the Standby host. This parameter disables the automatic deployment of software on standby host when specified as false. If this value is false, the Standby staging/deploy operation can be performed independently using the emcli command.

  • skipCVUChecks: true|false. Default value is false

  • skipPrereqs: true|false. Default value is false

  • WorkingDirectory: <Name of temp directory>

  • newOracleHomeLoc: <Location where Oracle Home will be created

A sample of the response received is shown below:

Update Oracle home software operation for RAC Database t05nwe can be monitored using the following EMCLI command:

emcli get_instance_status -exec=4943D8E3626E420EE0530854F10A18A9 -details –xml

Browser: https://blr123.example.com:11111/em/faces/core-jobs-procedureExecutionTracking?executionGUID=4943D8E3626E420EE0530854F10A18A9

Update / Rollback

Feature Description

Request Method

POST

URI for Update

em/websvcs/restful/emws/db/fleetmaintenance/performOperation/update

URI for Rollback

em/websvcs/restful/emws/db/fleetmaintenance/performOperation/rollback

Request Headers

Authorization: basic <generated credential value>

Content-Type: application/json

Body

 
{
"name": "<Operation name>",
"targetName": "<name of the target>",
"targetType": "<target type>",
"normalCredString": "<credential name>",
"privCredString": "<privileged credential name>"
"nodeList": “<list of nodes>”"dgRole":”primary|standby”"startupAfterSwitch":“true|false”"startupDBAfterSwitch": “true|false”
"skipSwitchDatabase":“true|false”"ignoreStandbyPrereq":“true|false”
}

Description of the Input Variables

  • name: Name of the operation

  • targetName: Name of the target

  • targetType: Refer to CLI Command Inputs Based on Entity Type table.

  • normalCredString: This must be entered in the format <Named Credential: Credential Owner> where:

    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.

    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.

  • privCredString: This must be entered in the format <Named Credential: Credential Owner> where:

    • <Named Credential>: Named credential for the host where new Oracle home will be deployed.

    • <Credential Owner>: The Enterprise Manager user who owns this Named Credential.

    These credentials are used to run scripts as root.

  • nodeList: comma separated list of nodes

  • dgRole: primary|standby

  • startupDBAfterSwitch: The default value is true. It is used for node-wise patching. To leave a database instance down after a cluster instance is patched

  • skipSwitchDatabase: It should be set to ‘true’. It skips the switching of database to patched home since it is already performed in earlier steps.

  • ignoreStandbyPrereq: The default value is false. This disables verification check if the Standby is on the same image version where the Primary is being moved to

  • startupAfterSwitch: For non-rolling patches, it is necessary to bring up the Primary database first from the patched home. It will ensure that Standby is left in shutdown state during the Update operation. Standby will be started in a separate step after Primary is patched and started.

A sample of the response received is shown below:

Update Oracle home software operation for RAC Database t05nwe can be monitored using the following EMCLI command:

emcli get_instance_status -exec=4943D8E3626E420EE0530854F10A18A9 -details –xml

Browser: https://blr123.example.com:11111/em/faces/core-jobs-procedureExecutionTracking?executionGUID=4943D8E3626E420EE0530854F10A18A9