45 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:

45.1 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) and Patchset Updates (PSUs).

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 11.2.0.4 contains gold images (such as Ver. 1, Ver. 2, and so on) at different patch levels.

Database fleet maintenance can be used for:

  • Single Instance Oracle Homes and associated databases

  • 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)

Fleet maintenance involves the following steps:

  • Identifying configuration pollution using the Software Standardization Advisor.

  • Creating reference environments.

  • 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 switch 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:

From the 12.2 release, classic patching using Lifecycle Management Graphical User Interface is deprecated. You must use the Database Fleet Maintenance feature to patch 12.2 databases and GI environments.

45.2 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 45-1 Database Fleet Maintenance Steps


Database Fleet Maintenance

45.2.1 Meeting the Prerequisites

Before you start the fleet management operations, you must ensure that the following prerequisites are met:

  • The Enterprise Manager Software Library has been setup and configured.

  • The database and cluster targets to be patched have been discovered in Enterprise Manager.

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

  • Space is available on the hosts where the patching is to be carried out. More details are available in Staging and Deploying the Software.

The following shows table that 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 Purpose (for deploy operation) Purpose (for Update operation) Purpose (for Rollback operation) Purpose (for Cleanup software operation)

Single Instance database

oracle_database

DEPLOY_DB_SOFTWARE

UPDATE_DB

ROLLBACK_DB

CLEANUP_SOFTWARE

RAC database

rac_database

DEPLOY_RAC_SOFTWARE

UPDATE_RACDB

ROLLBACK_RACDB

CLEANUP_SOFTWARE

Oracle Restart

  

DEPLOY_SIHA_SOFTWARE

UPDATE_SIHA

ROLLBACK_SIHA

CLEANUP_SOFTWARE

Grid Infrastructure

cluster

DEPLOY_GI_SOFTWARE

UPDATE_GI

ROLLBACK_GI

CLEANUP_SOFTWARE

PDB

oracle_pdb

-NA-

UPDATE_PDB

ROLLBACK_PDB

-NA-

CDB

oracle_database/ rac_database

DEPLOY_CDB, ATTACH_CDB

-NA-

-NA-

-NA-

Note:

All values in the table above are case sensitive.

45.2.2 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, Databaseor Grid Infrastructureand click run/re-run to run the analysis.

  5. Click Generate Reportto 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]

45.2.3 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 45-2 Creating a Gold Image

Creating an Image

You can create an image for a database or grid infrastructure home using the emcli 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.

Verb

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

where the input_rac 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 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>

  • 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. For Grid Infrastructure or Oracle Restart Homes, this parameter should be listed as "REF_GI_CREDENTIALS". 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_SYSMAN_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'

45.2.4 Retrieving a List of Available Gold Images

Verb

Note:

To format the output of the emcli 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=<column name(s)>]
Example 
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

The input variables are:

  • 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

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

The input variables are:

  • 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 emcli command. It shows the current version of the given image by default unless a specific version_id is provided.

Verb

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)

45.2.5 Verifying if Image is Applicable

Verb

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.

Syntax: 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 “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= FE55AD7AB28974EFE04313B2F00AD4A0 -target_list=HAS1 -target_type=has

Grid Infrastructure

emcli db_software_maintenance -checkApplicability -image_id= FE55AD7AB28974EFE04313B2F00AD4A0 -target_list=CLUSTER1 -target_type=cluster

Oracle Restart

emcli db_software_maintenance –checkApplicability -image_id= FE55AD7AB28974EFE04313B2F00AD4A0 -target_list=HAS1 -target_type=has

Single Instance

emcli db_software_maintenance -checkApplicability -image_id= FE55AD7AB28974EFE04313B2F00AD4A0 -target_list=DB1 -target_type=oracle_database

Sample Output

Checking applicability for target [RACDB1]...
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.

45.2.6 Deleting an Image or Versions of an Image

Verb

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.

Verb

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.

45.2.7 Subscribing the Targets to the Selected Image

Verb

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.

Figure 45-3 Subscribing to an Image


Subscribing to an Image

Syntax: emcli db_software_maintenance -subscribeTarget -target_name="RACDB1" -target_type=rac_database -image_id=<image_id>

where:

  • target_name: The name of the target that needs to be patched.

  • target_type: Refer to the table “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, 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

Note:

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

45.2.8 Verifying the Subscription

Verb

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:

Figure 45-4 Verifying the Subscription


Verifying the Subscription

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 “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

45.2.9 Unsubscribing Targets from an Image

Verb

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 “CLI command inputs based on Entity type”

  • image_id is 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 specified in the <Retrieving a List of Available Gold Images> section.

45.2.10 Creating an Updated Version of the Image

Verb

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'

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

Verb:

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.

45.2.12 Staging and Deploying the Software

Verb

Fleet maintenance 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.

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=<credential name> —privilege_credential<privileged credential name> —inputfile="data:<location of input file>" [standbyAutoDeploy=true|false]

Description of the Input Variables

where:

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

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

  • target_type: The type of target on which this operation is being performed. Refer to the table 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: 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.

  • start_schedule: The date on which the stage and deploy is to be started if it is to be started in the future.

    Format: "start_time:yyyy/mm/dd HH:mm"

    Note: 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 emcli command.

  • input_file : This file will contain the following entries:

    • NEW_ORACLE_HOME_LIST=<path of 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 / 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”.

    Note: This verb submits a procedure which must be completed before you can proceed with the next steps.

Sample Output

Processing target "CLUSTER1"...

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

Check Passed.

Checking image subscription...

Check image subscription passed.

Operation 'Deploy 1120407 GI_Home' created successfully.

Space Requirements

  • The temporary space in the working directory (workingDir) must be approximately twice the size of the Reference Home. For example, a 11.2.0.4 image is about 6 GB – then temporary space of at least 12 GB is expected to complete the deploy step successfully

  • The dispatch location (dispatchLoc) requires the same amount of space as the workingDir plus an additional 500MB. If this parameter is not specified, the default working directory will be used.

  • For the Oracle Home, space required is the same as Reference Home. It is recommended to have additional storage available for the growth of log files and so on.

45.2.13 Migrating the Listeners

Verb

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. Grid Infrastructure homes are automatically migrated during the GI update process.

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
where:

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

  • purpose: There are standard tasks or purposes that can be performed by fleet operations which can be:

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

    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.

    Format: "start_time:yyyy/mm/dd HH:mm"

    Note: This is an optional parameter. If no date is provided, the fleet operation will start immediately.

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

45.2.14 Deploying Container Databases

Verb

In case of container databases, users have flexibility to update one or more PDBs 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 PDBs to the new container on demand. A new CDB is created using the structure-only template.

emcli db_software_maintenance -performOperation -purpose="DEPLOY_CDB" -target_name="<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 PDBs when they are updated.

emcli db_software_maintenance -performOperation -purpose="ATTACH_CDB" -target_name="<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>"

45.2.15 Updating the Database / Cluster

Verb

After the stage and deploy operations have been completed, the targets need to be migrated to the newly deployed Oracle homes.

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>

where:

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

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

  • target_type: Refer to the 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>.

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

45.2.15.1 Rolling Back Cluster / Database

Verb

This command is used to switch the database back to the previous Oracle home after the Update operation has been completed.

emcli db_software_maintenance -performOperation -name="Rollback RAC DB" -purpose=ROLLBACK_RACDB -target_type=rac_database -target_list= RACDB -normal_credential="NC_HOST_CREDS:SYSMAN" -privilege_credential="HOST_PRIV:SYSMAN" [-rolling=true/false] [-node_list="host1.us.oracle.com"]
where:

  • 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".

Sample Output

Processing target "RACDB"...

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

Check Passed.

Checking image subscription...

Check image subscription passed.

Operation Rollback RAC DB' created successfully.

45.2.15.2 Non-Rolling Applicable Patches

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

45.2.15.3 Updating and Rolling Back Standby Databases

This section is applicable for all primary and physical standby configurations (RAC - RAC, RAC - SI, SI - SI, RAC - RAC-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)

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> —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=<Name of temp 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

    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=<Name of temp directory>

      • enableDG=<true|false> The 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:

      • workingDir=<Name of temp 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 of temp 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=<Name of temp directory>

      • enableDG=<true|false> The default value is false. This should be set to ‘true’ if the standby is managed by Data Guard.

      • primary_dbhost_creds=<credential name of primary database host>. 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 CLI Command Inputs Based on Entity Type table for the correct value.

45.2.15.4 Node Wise RAC Database / Cluster Update

Verb

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. Hence a cluster update followed by a RAC database update results in an instance getting restarted twice.

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

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

  • Switch the cluster instance

  • Leave the RAC database instances shutdown

    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.

    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.us.oracle.com" –startupDatabase=false

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

emcli db_software_maintenance -performOperation -name="Update RAC DB" -purpose=UPDATE_RACDB -target_type=rac_database -target_list= RACDB -normal_credential="NC_HOST_CREDS:SYSMAN" -privilege_credential="HOST_PRIV:SYSMAN" -rolling=true -node_list="host1.us.oracle.com"

where:

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

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

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

  • 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 launched 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.

  • 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: This is an optional parameter. If no date is provided, the fleet operation will start immediately.

Sample Output

Processing target "RACDB"...

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

Check Passed.

Checking image subscription...

Check image subscription passed.

PDB Update

Update PDB moves a PDB from its predecessor container to the newly available successor container. This can be executed only if there is the Attach CDB / Deploy CDB operation has already been performed.

emcli db_software_maintenance -performOperation -purpose=”UPDATE_PDB” —target_name=”<PDB_TARGET_Name>” —target_type=”oracle_pdb” —name=”Operation Name” –description=”Operation description” normal_credential=”<credential name> -privilege_credential=”<privilege credential name>” —database_credential=”<credential name>”

45.3 Update De-mystified

The following section highlights how Oracle Homes can be switched to the parallel 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 parallel Home.

  • 'oratab' file entries are updated

  • Instance is brought down and brought up with the parallel home as the new Oracle Home.

  • Target is brought of Blackout mode.

  • For pre-12c databases, SQLs are run using SQL*Plus and for 12c database, 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 ($SRC_HOME/crs/utl/crsconfig_dirs).

  • Configuration files like spfile, password, listener.ora, sqlnet.ora, tnsnames.ora are copied over to the parallel 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 Parallel Home as new Oracle Homes.

  • Configuration scripts are run.

  • All targets are brought out of Blackout mode.

  • If the management database is used, for pre-12c database, SQLs are run using SQL*Plus and for 12c database, 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 parallel Home.

  • 'oratab' file entries are updated

  • Instance is brought down and brought up with Parallel Home as new Oracle Home.

  • Target is brought out of Blackout mode.

  • For pre-12c databases, SQLs are run using SQL*Plus and for 12c database, 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 parallel Home.

  • 'oratab' file entries are updated

  • Instance is brought down and brought up with Parallel Home as new Oracle Home concurrently.

  • For pre-12c databases, SQLs are run using SQL*Plus and for 12c database, the datapatch utility is called to make data changes.

45.4 Upgrading Oracle Homes

There are two types of Upgrades supported – namely minor and major. A minor upgrade is moving a Oracle Home from one patchset to another (Ex: 11.2.0.3 to 11.2.0.4) whereas a major upgrade is moving a database from one major release to another (ex: 11.x to 12.x). All the steps such as Gold Image creation, image subscription and deploy image remain the same. Please note that 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.

The typical CLI command format is given below:

emcli db_software_maintenance -performOperation -name="Update RAC DB" -purpose=UPDATE_RACDB -target_type=rac_database -target_list= RACDB -normal_credential="NC_HOST_CREDS:SYSMAN" -privilege_credential="HOST_PRIV:SYSMAN" -database_credential=<SYSDBA credentials of the database>

In case of the primary and standby databases, upgrade needs to be done through the rolling upgrade user interface in Enterprise Manager. The wizard can be launched from the target database home page of the primary or standby database. On the Database home page, select Oracle Database, Provisioning, then select Upgrade Database. Refer to <Data Guard Rolling Upgrade> section for more details.

45.5 Cleaning Up Oracle Homes

Since Oracle homes consume storage, they can be cleaned up to release space when they are no longer in use. To achieve this, set the following emctl property and run the emcli command, also shown below to delete unused homes of a given target. Oracle homes will be deleted only if there are no targets running from them.

emctl set property -name oracle.sysman.emInternalSDK.db.gis.lineageLength -sysman_pwd $em_sysman_pwd –value

where value is the number of Oracle Homes that must be retained. The default value 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.

emcli db_software_maintenance -performOperation -name=" User specified Operation name " -purpose=<Operation Type> —target_list=<List of targets> —target_type=<target type> —normal_credential=<credential_name> —privilege_credential=<privilege credential_name> —workDir=/tmp [-reportOnly=true|false>

Description of Input Variables

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

  • purpose: CLEANUP_SOFTWARE

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

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

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

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

45.6 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.us.oracle.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.idc.oracle.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.us.oracle.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.us.oracle.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.us.oracle.com:11111/em/faces/core-jobs-procedureExecutionTracking?executionGUID=4943D8E3626E420EE0530854F10A18A9