32 Using EMCLI to Run Deployment Procedures

This chapter introduces the usage of EMCLI commands to run Deployment Procedures. In particular, this chapter covers the following:

• Before You Begin

• Prerequisites for Using EMCLI to Run Deployment Procedures

• Using EMCLI to Run Deployment Procedures

• Use Cases for EMCLI-based Provisioning and Patching

• Setting Up Preferred Credentials for Targets

• Queries to Acquire Data for Patching Runtime

• EMCLI Verbs for Deployment Procedures

• EMCLI Verbs for Deployment Instances

Before You Begin

Before you begin, familiarize yourself with the following:

• RuntimeData xml

  Runtime data response file (known as RuntimeData xml) is required to run any out-of-the-box or customized procedures. This file provides input for the configuration parameters consumed by a given procedure during execution.

  Each time you use the Enterprise Manager Console to run an out-of-box or customized Deployment Procedure, a RuntimeData xml file is automatically created based on the user input for the various parameters required by the procedure.

• RuntimeData Template

  Oracle provides out of the box templates for creating runtime data response files for the Deployment Procedures used in the most common use cases. These are known as "RuntimeData templates". These templates are available under the emcli/samples directory in OMS oracle home. The user needs to modify the configuration properties in these templates in order to generate RuntimeData xml file for a executing a procedure.

  For example, in order to provision RAC/AS you need to provide inputs such as install base location, shared device paths for the OCR, Voting disk and data files (in case of RAC). Similarly, for patching procedures inputs such as targets to be patched and patch number would be needed.

• Procedure GUID

  Both out-of-box and customized procedures are associated with a global unique identifier (GUID). This GUID is required while executing the procedures using EMCLI.

• Procedure Instance GUID

  Each execution of a given out-of-box or customized procedures is associated with an instance global unique identifier (GUID). This instance GUID is generated at runtime and can be used to monitor the execution of the procedure.

• Properties File

  For every execution of Deployment Procedure you must modify the values of the required configuration parameters for a RuntimeData xml or RuntimeData template. Instead of manually editing the xml files, you can populate a simple properties with name-value pairs for listing values of configuration parameters such as hosts, platform for deployment, and so on.

• Procedure Execution Scripts

  Oracle provides out of box scripts for the execution of procedures for Provisioning and Patching. These Perl scripts are available under the emcli/scripts directory in the OMS Oracle home. The user needs to copy the scripts to the working directory location where the EMCLI client is setup for execution.

  The properties file, the associated RuntimeData xml or RuntimeData template, and GUID of the relevant procedure are then submitted as input to an out-of-box script which creates a new runtime data response file and runs the procedure.

Note:

For more information on EMCLI, see Oracle Enterprise Manager Command Line Interface Guide available at:

http://www.oracle.com/technology/documentation/oem.html

Prerequisites for Using EMCLI to Run Deployment Procedures

You must ensure that the following requirements are met prior to using EMCLI to run Deployment Procedures:

• EMCLI client must be set up. Refer to the Installation and Configuration section of the Oracle Enterprise Manager Command Line Interface 10g Release 5 (10.2.0.5.0) for configuring the EMCLI client. The document is available in the following location:

  http://download.oracle.com/docs/cd/B16240_01/doc/nav/portal_booklist.htm

• Targets that will be supplied to the Deployment Procedures are managed by Management Agents of version 10.2.0.2 or higher.

• Download the procedure execution scripts, out-of-box templates and properties files on the machine where the EMCLI client is setup. The out-of-box templates and properties files for patching and provisioning are available in the respective directories under OMS HOME/emcli/samples/.

• EMCLI-based patching and provisioning uses the Oracle Home credentials set in Oracle Enterprise Manager. The preferred credentials can be set for the targets during the execution of the Deployment Procedures in Oracle Enterprise Manager. It can also be set explicitly from the Oracle Enterprise Manager user interface or by using EMCLI. Refer to Setting Up Preferred Credentials for Targets to set credentials for the Oracle Homes.

Using EMCLI to Run Deployment Procedures

Oracle provides out-of-the-box templates for creating run time data for Deployment Procedures used in the most common use cases. These are known as runtimedata templates. You can access them under the emcli/samples directory in the OMS Oracle home and you can then modify the configuration properties in these templates.

The following depicts the process to use EMCLI to run Deployment Procedures:

Figure 32-1 EMCLI Process to Run Deployment Procedures

There are four required actions to run Deployment Procedures. Those steps are described below:

1. Step 1: Find the GUID of the procedure to be run using EMCLI. This is a one-time activity.

2. Step 2: Obtain the RuntimeData xml or RuntimeData template for the procedure that needs to be run. This is also a one-time activity.

3. Step 3: Create the properties file for the RuntimeData xml or RuntimeData template. This step is required for each execution of the procedure.

4. Step 4: Submit the RuntimeData template or RuntimeData, properties file for the given execution and procedure GUID as input to an out-of-box script that will generate a new runtime data response file and then use this response file to run the procedure using EMCLI.

Each of these steps is discussed in detail in the subsequent sections.

Step 1: Finding Procedure GUID

EMCLI is case-sensitive so be sure to use the correct EMCLI verb and pass correct input. GUID out-of-box and customized procedures can be found using the following EMCLI verbs:

get_procedures

Usage: emcli get_procedures -type="procedure type"

Description: Get a list of Deployment Procedures.

Option:

-type="procedure type"Display all the Deployment Procedure of type {procedure type}.

Output Columns: GUID, Procedure Type, Name, Version, Created By

RAC procedures are of type: RACPROVAS procedures are of type: AS ProvisioningThe Standalone Database, RAC rolling, and CRS patching procedures are of type: PatchOracleSoftware

Alternatively the type associated with procedures can be found using the get_procedure_type EMCLI command.

get_procedure_types

Usage: emcli get_procedure_types

Description: Get the list of all Deployment Procedure types

Output Columns: Procedure Type

Step 2: Obtaining RuntimeData Template And RuntimeData XML

For out-of-box procedures, RuntimeData Templates are located in the emcli/samples directory in the Oracle Management Service (OMS) Oracle home.

For customized procedures you has to download the RuntimeData xml generated from an earlier execution of this procedure. To obtain the RuntimeData xml you first need to find the Instance GUID associated with the earlier execution of the procedure and then use it to download the RuntimeData xml generated for it. The following EMCLI verbs can be used to download a RuntimeData xml:

emcli get_instances -type="procedure type"

Usage: emcli get_instances -type="procedure type"

Description: Display list of procedure instances. EMCLI verb to obtain Instance GUID associated with an earlier execution of the customized procedure.

Option: -type="procedure type"Display all the Procedure Instances of a given type.

Output Columns: Instance GUID, Procedure Type, Instance Name, Status

To find the type associated with procedures, use the get_procedures_type verb.

emcli get_instance_data_xml -instance="instance_guid"

Usage: emcli get_instance_data_xml -instance="instance_guid"

Description: Download Instance Data XML. EMCLI verb to download a RuntimeData xml using Instance GUID.

Option: -instance is used to specify the instance GUID.

Example: emcli get_instance_data_xml -instance="16B15CB29C3F9E6CE040578C96093F61"

Output: The Instance Data XML.

Step 3: Creating Properties File

The following sections describe the properties files for out-of-box procedures, customized procedures, and extending procedure execution.

Properties File for Out-Of-Box Procedures

If you are using an out-of-box RuntimeData template, a user identifies the variables in the RuntimeData template file that need to be replaced with values for the configuration properties for a given execution of the procedure. Of all the variables present in the Runtime Data templates, only some might be mandatory for running a given procedure. Once this is done you can create the properties file, which would contain name value pairs mentioning the variables and the values with which they would be replaced for generating the RuntimeData xml file.

For out-of-box procedures, a sample properties file can be found in Appendix B, "Sample Property Files for the Out-of-Box RuntimeData Templates". The corresponding RuntimeData Templates can be obtained from the zip file where this document is present.

Note that each sample properties files in the appendix mentioned above contains a section for mandatory variables which should be present in the properties file with relevant values to be substituted at run time. You can optionally provide values for other variables present in the templates.

Properties File for Customized Procedures

In case of customized procedures, the RuntimeData xml actually have values instead of placeholder variables for the configuration properties. You need to replace the old runtime values in the RuntimeData xml of the previous run with the new runtime values, which are relevant to the new run.

For this, you can have a properties file of the form:

<old_value>=<new_value>

For example, consider this snippet from the RuntimeData xml used to patch an Oracle Database:

…

<scalar value="dbtarget1" classname="java.lang.String" name="targetsToPatch"/><scalar value=" HostPrefNormal" classname="java.lang.String" name="hostCredentialSet"/>   <list classname="java.util.Vector" name="patchIDs">   <scalar value="=%oracle_home%/EMStagedPatches " classname="java.lang.String" name="stageDir"/><scalar value="false" classname="java.lang.String"     name="isPatchset"/><scalar value="true" classname="java.lang.String"     name="isNotPatchset"/><scalar value="defaultSqlScript" classname="java.lang.String" name="sqlScript"/>...

To patch another database you need to create a properties file with oldvalue=newvalue type of entries for at least the mandatory parameters (in case of patching on the mandatory property is targetsToPatch). Hence the new properties file would look something as below:

dbtarget1=dbtarget2

Since this approach would simply replace an old-string with a new-string, you might run into issues if the old-string is substring in multiple strings in the DP runtime xml. In that case the resulting runtime xml might be erroneous. To circumvent this issue, it is strongly advised to format the properties file a proper fashion. The thumb-rule here is: put the specifics before the generics. A fragment of a properties file in the form of old-value=new-value pairs shown below, illustrates this point.

node1.test.com=node2example.com

node1=node2

node1,node2=node3,node4

Also, for specifying the passwords in the properties file please make sure you include the following line in the properties file before mentioning any passwords.

oracle.sysman.pp.paf.impl.EncryptedString =oracle.sysman.pp.paf.impl.UnencryptedString

After this you can mention the password as shown in the examples below:

1. For a password value to replace the placeholder variable in the template file

   oracle.sysman.pp.paf.impl.EncryptedString=oracle.sysman.pp.paf.impl. UnencryptedStringcrsasmrac_provisioning_USER_PASSWORD=mypassword
   

2. For a new password value to replace an older one in a RuntimeData xml

   oracle.sysman.pp.paf.impl.EncryptedString=oracle.sysman.pp.paf.impl. UnencryptedStringmyOLDpass=myNEWpassword
   

Note that mypassword and myNewpassword used in the above examples are clear text passwords.

Note:

The elements var_runOpatchUpgrade and var_isUpgradeStepEnabled have been added to support Opatch upgrade. The first element should be set to "true" to run the opatch upgrade step. var_isUpgradeStepEnabled should be set to "true" if opatch is to be upgraded, otherwise, it should be "false".

Properties File For Extending Procedure Execution

Properties file allows you to use the same RuntimeData xml for extending the use case. For example, you might have performed a successful procedure execution (partial cluster scale- up or scale down or patching) for a target and you want to extend it to a set of new targets.

You can do this by using a Properties file and replacing the parameter values in it (Refer to the Mandatory parameter section in Appendix B, "Sample Property Files for the Out-of-Box RuntimeData Templates". For example:

node1 = node2,node 3

Wherein node1 is the target for which you had run the procedure previously and node2 and node3 are the targets to which you want to extend the procedure execution.

An exception to this rule is extending the patching procedures to a different set of targets, which would require you to have a properties file with the following mandatory parameter (Instead of the approach of <old-value>=<new-value>):

PA_VAR_targetsToPatch=Tgt2, Tgt3, Tgt4

Wherein Tgt2, Tgt3 and Tgt4 are the new targets to which you want to extend the procedure execution.

Refer to Queries to Acquire Data for Patching Runtime for the list of queries which can be used to acquire data for creating properties file.

Properties File For Applying Multiple Patches At Once

The new elements added in RuntimeData xml to support multiple patches are:

• patchesToBeApplied - Enter comma-separated list of patch IDs for this element.

  Example: <scalar value="patchesToBeApplied" classname="java.lang.String" name="patchListToApply"/>

• patchSourceForPatches - Enter patch source, which is either SWLIB or METALINK. Default source is SWLIB

  Example: <scalar value="patchSourceForPatches" classname="java.lang.String" name="patchListSource"/>

• patchPlatformForPatches - This is optional. Enter supported platforms for patchOptional. You must provide a valid platform ID. To get platform IDs, run the displayPlatformInfo.pl script in <EMCLI working directory>/scripts.

  Example: <scalar value="patchPlatformForPatches" classname="java.lang.String" name="patchPlatform"/>

• patchReleaseForPatches - Enter the release of the patchset. This is optional, but required for patchsets.

  Example: <scalar value="patchReleaseForPatches" classname="java.lang.String" name="patchRelease"/>

Step 4: Procedure Execution

First download and apply the Metalink patch - 5890474 on OMS 10.2.0.3 which will update the EMCLI procedure execution scripts, out-of-box templates, and properties files. This updates the emcli/samples and emcli/scripts directory in OMS Oracle home. After applying the patch on the OMS, download the procedure execution scripts, out-of-box templates, and properties files on the machine where the EMCLI client is set up. The out-of-box templates and properties files for patching and provisioning are available in the respective directories under OMSHOME/emcli/samples/.

Once the RuntimeData template or RuntimeData xml and properties file are ready, then the procedure can be run using the following script.

Usage:

perl executeDP.pl -t <template> -p <properties file name> -g <DP GUID> [-s <schedule> in the format yyyy/MM/dd HH:mm] [-z <time zone ID>] [-d <emcli directory path>, mandatory if emcli executable is not in the current directory]

Template -- The name of the RuntimeData template for out-of-box procedures or location of the RuntimeData xml file downloaded after the execution of a customized procedure.

Properties file name -- The location of the properties file created for executing the procedure.

DP GUID -- The GUID of the procedure that needs to be run.

emcli Directory -- The directory which contains the EMCLI executable. If the current working directory contains the EMCLI executable, this parameter is optional.

Schedule -- The time when the Deployment Procedure would be scheduled to run. If not specified it defaults to running the Deployment Procedure immediately. The HH:MM is based on 24 hrs clock, for example, 22:30.

Time Zone ID -- The time zone to which the Deployment Procedure run is scheduled. If not specified it defaults to the time zone of the OMS.

Below is a sample code string executing RAC provisioning procedure for UNIX using out-of-box procedure:

perl executeDP.pl -t crsasmrac_gold_prov_template.xml -p Properties.txt -g 31ABCFF2199BB77990B057AC4A442DAC -t 2007/02/03 10:00 -z Americas/New_York -d /oracle/prod/orahome/

The following parameter descriptions apply to the script:

crsasmrac_gold_prov_template.xml is the name of the out-of-box template.

Properties.txt is the properties file

31ABCFF2199BB77990B057AC4A442DAC is the GUID for the RAC provisioning procedure for UNIX

2007/02/03 10:00 is the date and time during which the Deployment Procedure is scheduled to run.

Americas/New_York is the Time Zone ID for which the time schedule is set.

/oracle/prod/orahome/ is the directory location for the EMCLI executables.

The properties file and the out-of-box template are located in the same directory as the script that was run.

Executing SIDB Patching for UNIX Using An Out-of-Box Procedure

Below is a sample code string executing single instance database patching for UNIX using an out-of-box procedure:

perl executeDP.pl patch_standalone_DB.xml Properties.txt 2EECED3592A0175FE040578CE808291F

The following parameter descriptions apply to the script:

patch_standalone_DB.xml is the name of the out-of-box template.

Properties.txt is the properties file.

2EECED3592A0175FE040578CE808291F is the GUID for the Single Instance Database patching procedure for UNIX.

The templates, properties file, and the EMCLI executables are located in the same directory as the script. Also, the Deployment Procedure is scheduled to run immediately in the time zone of the OMS.

Use Cases for EMCLI-based Provisioning and Patching

The following sections describe various use cases for EMCLI-based provisioning and patching procedures. You must first download and apply the Metalink patch - 5890474 on OMS 10.2.0.3 which will update the EMCLI procedure execution scripts, out-of-box templates, and properties files. This updates the emcli/samples and emcli/scripts directory in OMS oracle home. After applying the patch on OMS, download the procedure execution scripts, out-of-box templates, and properties files on the machine where the EMCLI client is setup. The out-of-box templates and properties files for patching and provisioning are available in the respective directories under OMS HOME/emcli/samples/.Before using any Real Application Cluster (RAC) related procedure, ensure that the Management Agents on the nodes are cluster Management Agents.

Use Cases for CRS/ASM/RAC Provisioning Procedure

Use Case 1: User wants to use the EMCLI to provision a 2-node RAC using a Gold Image from the software library. He uses the out-of-box templates and properties file to perform this operation.

• User creates a Properties file with the mandatory configuration parameters required for RAC provisioning procedure and assigns appropriate values for the variables. Refer Sample Properties file with Mandatory parameters for out-of-box RAC provisioning procedure using Gold Image

• User finds the appropriate GUID for the RAC provisioning procedure. Refer to section "Out-of-box RuntimeData Templates For RAC Procedures" of Appendix A, "Out-Of-Box RuntimeData Templates" for GUID, procedure type, and template name information for the out-of-box RAC provisioning procedure using Gold Image from Software Library.

• User submits the procedure for execution by invoking the executeDP.pl script and providing the location details of the properties file, location of the out-of-box template and procedure GUID.

Use Case 2: User wants to use EMCLI to provision another 4 node RAC using the same out-of-box templates and properties file as used in Use case 1 to perform this operation.

• User takes the properties file from the previous use case and makes the necessary changes for the mandatory parameters to provision a 4-node RAC.

• User submits the procedure for execution by invoking the executeDP.pl script and providing the location details of the properties file, location of the out-of-box template and procedure GUID. Sample usage of the script is shown below.

Use Case 3: User wants to use the EMCLI to provision a 2-node RAC using a Reference Installation. He uses the out-of-box templates and properties file to perform this operation.

• User creates a Properties file with the mandatory configuration parameters required for RAC provisioning procedure and assigns appropriate values for the variables. Refer Sample Properties file with Mandatory parameters for out-of-box RAC provisioning procedure using Reference Installation.

• User finds the appropriate GUID for the RAC provisioning procedure. Refer to section "Out-of-box RuntimeData Templates For RAC Procedures" of Appendix A, "Out-Of-Box RuntimeData Templates" for GUID, procedure type, and template name information for the out-of-box RAC provisioning procedure using Reference Installation.

• User submits the procedure for execution by invoking the executeDP.pl script and providing the location details of the properties file, location of the out-of-box template and procedure GUID.

Use Case 4: User customizes and tests the out-of-box RAC provisioning procedure using reference host. He wants to use the EMCLI to provision a 2-node RAC. He uses the runtime data xml of the trial runs of his customized procedure and properties file to perform this operation on a similar 2-node RAC.

• Locates the instance GUID of the previous trial run.

• User downloads the Runtime data xml for the previous execution of the procedure.

• User identifies the parameters in the Runtime data xml that need to be substituted with new values. He then creates a properties file with name-value pairs like <old-value>=<new-value> for carrying out the necessary runtime substitutions. This properties file should at least contain the substitution rule for the values corresponding to the mandatory parameters mentioned in Sample Properties file with Mandatory parameters for out-of-box RAC provisioning procedure using Reference Installation in addition to the other values that he might want to substitute.

• User finds the GUID for the customized RAC provisioning procedure. Refer to section Finding Procedure GUID.

• User submits the procedure for execution by invoking the executeDP.pl script and providing the location details of the properties file, location of the downloaded Runtime data xml, and procedure GUID.

Use Case 5: User customizes and tests the out-of-box RAC provisioning procedure. He wants to use EMCLI to provision a N-node RAC. He uses the runtime data xml of a trial run of his customized procedure and properties file to perform this operation on a M-node cluster (where M>N).

• Locates the instance GUID of the previous trial run of the customized procedure.

• User downloads the Runtime data xml for the previous execution of the procedure.

• User identifies the parameters in the Runtime data xml that need to be substituted with new values. He then creates a properties file with name-value pairs like <old-value>=<new-value> for carrying out the necessary runtime substitutions. This properties file should at least contain the substitution rule for the values corresponding to the mandatory parameters mentioned in Sample Properties file with Mandatory parameters for out-of-box Oracle RAC provisioning procedure using Gold Image, in addition to the other values that he might want to substitute.

• User finds the GUID for the customized Oracle RAC provisioning procedure. Refer to section Finding Procedure GUID.

• User submits the procedure for execution by invoking the executeDP.pl script and providing the location details of the properties file, location of the downloaded Runtime data xml and procedure GUID.

Use Cases for Extend Cluster Procedure

Use Case 1: User wants to use the EMCLI to extend a 2-node Oracle RAC to 4-node cluster. He uses the out-of-box templates and properties file to perform this operation.

• User creates a Properties file with at least the mandatory parameters required for cluster Extension procedure and assigns appropriate values for the variables. Refer to Sample Properties file with Mandatory parameters for out-of-box Cluster Extend procedure.

• User finds the appropriate GUID for the RAC provisioning procedure. Refer to section "Out-of-box RuntimeData Templates For RAC Procedures" of Appendix A, "Out-Of-Box RuntimeData Templates" for GUID, procedure type, and template name information for the out-of-box Cluster Extend procedure.

• User submits the procedure for execution by invoking the executeDP.pl script and providing the location details of the properties file, name of the out-of-box template and procedure GUID.

Use Cases For RAC Delete/Descale Procedure

Use Case 1: User wants to use EMCLI to delete the 2-node RAC cluster. He uses the out-of-box templates and properties file to perform this operation.

• User creates a Properties file with at least the mandatory parameters required for RAC Delete procedure and assigns appropriate values for the variables. Refer Sample Properties file with Mandatory parameters for out-of-box Cluster Delete procedure.

• User finds the appropriate GUID for the RAC Delete procedure. Refer to section "Out-of-box RuntimeData Templates For RAC Procedures" of Appendix A, "Out-Of-Box RuntimeData Templates" for GUID, procedure type, and template name information for the out-of-box Scale Down/Delete RAC procedure. Note that template used for Cluster Scale down and Cluster Delete use cases differ.

• User submits the procedure for execution by invoking the executeDP.pl script and providing the location details of the properties file, name of the out-of-box template and procedure GUID.

Use Case 2: User wants to use the EMCLI to descale a 2-node RAC cluster. He uses the out-of-box templates and properties file to perform this operation.

• User creates a Properties file with at least the mandatory parameters required for RAC Scale Down procedure and assigns appropriate values for the variables. Refer Sample Properties file with Mandatory parameters for out-of-box Cluster Descale procedure.

• User finds the appropriate GUID for the RAC Descale procedure. Refer to section "Out-of-box RuntimeData Templates For RAC Procedures" of Appendix A, "Out-Of-Box RuntimeData Templates" for GUID, procedure type, and template name information for the out-of-box Scale Down/Delete RAC procedure. Note that template used for Cluster Scale down and Cluster Delete use cases are different.

• User submits the procedure for execution by invoking the executeDP.pl script and providing the location details of the properties file, name of the out-of-box template and procedure GUID.

Use Cases for Patching

Use Case 1: User wants to use the out-of-box Database Patching procedure to apply a one-off patch to a database. He uses the out-of-box templates and properties file to perform this operation.

• User creates a Properties file with the mandatory configuration parameters required for patching the database with a particular one-off and assigns appropriate values for these variables. List of the mandatory values can be found from the Sample Properties file with Mandatory parameters for all the patching procedures.

• User finds the appropriate GUID for the Patch provisioning procedure. Refer to section "Out-of-box RuntimeData Templates For Patching Procedures" of Appendix A, "Out-Of-Box RuntimeData Templates" for GUID, procedure type, and template name information for the out-of-box Patch Oracle Database procedure.

• User submits the procedure for execution by invoking the executeDP.pl script and providing the location details of the properties file, location of the out-of-box template and procedure GUID.

Use Case 2: User wants to use the Database Patching procedure to apply multiple one-off patches to multiple databases. He uses the out-of-box templates and properties file created in use User Case 1 above to perform this operation.

• User creates a Properties file with the mandatory configuration parameters required for patching the database with a particular one-off and assigns appropriate values for these variables. List of the mandatory values can be found from the Sample Properties file with Mandatory parameters for all the patching procedures.

• User submits the procedure for execution by invoking the executeDP.pl script and providing the location details of the properties file, location of the out-of-box template and procedure GUID.

Use Case 3: User wants to use the Database Patching procedure to apply a patchset to a set of databases. He uses the out-of-box templates and properties file created in use Use Case 1 above to perform this operation.

• User creates a Properties file with the mandatory configuration parameters required for patching the database with a particular one-off and assigns appropriate values for these variables. List of the mandatory values can be found from the Sample Properties file with Mandatory parameters for all the patching procedures.

• User find the appropriate GUID for the Patch provisioning procedure.

• User submits the procedure for execution by invoking the executeDP.pl script and providing the location details of the properties file, location of the out-of-box template and procedure GUID.

Use Case 4: User customizes and tests the out-of-box Oracle Clusterware Patching procedure. He wants to use the EMCLI to patch a 2-node cluster. He uses the runtime data xml of the trial runs of his customized procedure and properties file to perform this operation on a similar 2-node cluster.

• User creates a Properties file with the mandatory configuration parameters required for patching the database with a particular one-off and assigns appropriate values for these variables. List of the mandatory values can be found from the Sample Properties file with Mandatory parameters for all the patching procedures.

• User finds the GUID for the customized patching procedure.

• User submits the procedure for execution by invoking the executeDP.pl script and providing the location details of the properties file, location of the run time data xml and procedure GUID.

Use Case 5: User customizes and tests the out-of-box Oracle Clusterware Patching procedure. He wants to use the EMCLI to patch a 2-node cluster. He uses the runtime data xml of the trial runs of his customized procedure and properties file to perform this operation on a similar N-node cluster.

• User creates a Properties file with the mandatory configuration parameters required for patching the database with a particular one-off and assigns appropriate values for these variables. List of the mandatory values can be found from the Sample Properties file with Mandatory parameters for all the patching procedures.

  For example, use the mandatory variable of the Properties file for scaling up to multiple Targets as seen here:

  PA_VAR_targetsToPatch=NewTarget1, NewTarget2, NewTarget3…

• User finds the GUID for the customized patching procedure.

• User submits the procedure for execution by invoking the executeDP.pl script and providing the location details of the properties file, location of the runtime data xml and procedure GUID.

Limitations

There is a limitation to consider when using patching Deployment Procedures through EMCLI.

Out-of -box templates are not available for patching Deployment Procedures like Application Server patching, Real Application Cluster -All nodes and pre-requisite checkers for Database, Real Application Cluster (RAC), Automatic Storage Management (ASM) and Clusterware. To use EMCLI for these procedures:

• Run the procedure once through the UI.

• Export the run time data xml

  emcli get_instance_data_xml -instance="instance_guid"

  Where, instance_guid is of the Deployment Procedure. (Refer to step 2-Obtaining Runtime Data Template and Data xml.)

• Create a properties file with the mandatory configuration parameter required for patching or running pre-requisite checker and assign appropriate values for the other changes. List of the mandatory values can be found from the Sample Properties file with Mandatory parameters for all the patching procedures.

  For example, use the mandatory variable of the Properties file for scaling up to multiple Targets

  PA_VAR_targetsT=NewTarget1, NewTarget2, NewTarget3…

• Submit the procedure for execution by invoking the executeDP.pl script and providing the location details of the properties file, location of the runtime data xml and procedure GUID.

Setting Up Preferred Credentials for Targets

The EMCLI execution looks for the credentials for the Targets under the Enterprise Manager with the OMS user executing the procedures. The preset credentials is looked up for the Targets under patching or for the ones used as a reference during provisioning procedures.

The credentials can be stored while doing any patching or provisioning operations through the Enterprise Manager user interface in the 'Credentials' section of the procedure run. If not, you can set up the credentials either through the Enterprise Manager OMS explicitly or through the use of EMCLI commands.

Setting Credentials from the Oracle Enterprise Manager User Interface

You can set the credentials for targets through the Oracle Enterprise Manager user interface by following these steps:

1. Log in to Oracle Enterprise Manger.

2. Access the link "Preferences" on the top right corner of the page.

3. Click on "Preferred Credentials" link in the Options section of the page.

4. Setup 'Normal' or 'Preferred Credentials' from this page for the Target type. (Example: Database Instance, Cluster Database or Cluster).

Setting Credentials through EMCLI

You can set the credentials for targets through EMCLI command line interface using the following code sequence:

set_credential              -target_type="ttype"             [-target_name="tname"]              -credential_set="cred_set"             [-user="user"]              -columns="col1:newval1;col2:newval2;..."             [-input_file="tag1:file_path1;tag2:file_path2;..."]             [-oracle_homes="home1;home2"]

The following list describes the options used in the EMCLI code:

• target_type - Type of target. Must be "host" in case "-oracle_homes" parameter is specified.

• target_name - Name of target. Omit this argument to set enterprise preferred credentials. Must be hostname in case "-oracle_homes" parameter is specified.

• user - Enterprise Manager user whose credentials are affected. If omitted, the current user's credentials are affected.

• columns - The name and new value of the column(s) to set. Every column of the credential set must be specified. Alternatively, a tag from the -input_file argument may be used so that the credential values are not seen on the command line. This argument may be specified more than once.

• input_file - Path of file that has -columns argument(s). This option is used to hide passwords. Each path must be accompanied by a tag, which is referenced in the -columns argument. This argument may be specified more than once.

• oracle_homes - Name of oracle homes on the target host. Credentials will be added/updated for all specified homes.

The list of columns and the credential sets they belong to is included in the metadata file for each target type. This and other credential information is in the <CredentialInfo> section of the metadata.

The following is an example of the sequence:

emcli set_credential -target_type=host -target_name=host.us.oracle.com -credential_set=OHCreds -user=admin1 -column="OHUsername:joe;OHPassword:newPass" -oracle_homes="database1;mydb"

For more details on EMCLI, refer to the verb reference section of Oracle® Enterprise Manager Command Line Interface 10g Release 5 (10.2.0.5.0). This document is available at:

http://download.oracle.com/docs/cd/B16240_01/doc/nav/portal_booklist.htm

Clearing Credentials through EMCLI

You can clear preferred or monitoring credentials for given users through the EMCLI command line interface using the following code sequence:

emcli clear_credential
       -target_type="ttype"
       [-target_name="tname"]
       -credential_set="cred_set"
       [-user="user"]
       [-oracle_homes="home1;home2"] 

The following list describes the options used in the EMCLI code:

• target_type - Type of target. Must be "host" in case "-oracle_homes" parameter is specified.

• target_name - Name of target. Omit this argument to set enterprise preferred credentials. Must be hostname in case "-oracle_homes" parameter is specified.

• credential_set - Credential set affected. This value is ignored for monitoring credentials.

• user - Enterprise Manager user whose credentials are affected. If omitted, the current user's credentials are affected.

• oracle_homes - Name of oracle homes on the target host. Credentials will be cleared for all specified homes.

Example 1:

 emcli clear_credential
         -target_type=oracle_database
         -target_name=myDB
         -credential_set=DBCredsNormal
         -user=admin1

Example 2:

emcli clear_credential
         -target_type=oracle_database
         -credential_set=DBCredsNormal
         -user=admin1

Queries to Acquire Data for Patching Runtime

Use the following queries to acquire data for patching runtime:

• Use the following query to acquire an Instance name from a host:

  select target_name, target_type, oracle_home from em$ECM_TARGETS_VIEW where host = '<host name>';

• Get the instance name for a given host:

  select target_name, target_type, oracle_home from em$ECM_TARGETS_VIEW where host = '<host name>';

• Get the instances of a CRS given the name of the CRS:

  select assoc_target_name, crs_instance from sysman.mgmt$target_associations where assoc_def_name='contains' and source_target_name='<crs_name>' and source_target_type='cluster'

• Get all CRS and its instances:

  select source_target_name crs_name, assoc_target_name, crs_instance from sysman.mgmt$target_associations where assoc_def_name='contains' and source_target_type='cluster' order by source_target_name

• Get instances of a RAC cluster given the name of the RAC cluster:

  select assoc_target_name rac_instance from sysman.mgmt$target_associations where assoc_def_name='contains' and source_target_name='<rac_name>' and source_target_type='rac_database'

• Get all RAC clusters and their instances:

  select source_target_name rac_name, assoc_target_name rac_instance from sysman.mgmt$target_associations where assoc_def_name='contains' and source_target_type='rac_database' order by source_target_name

EMCLI Verbs for Deployment Procedures

Following are the EMCLI verbs related to deployment procedures:

get_instance_status

Description

Display Procedure Instance status identified by the GUID on the command line.

Usage

emcli get_instance_status  -guid={guid number} [-xml [-details] [-showJobOutput [-tailLength={Last N Characters}]]]

Option

-guid={guid number}

Mandotory option to display the details of a Procedure Instance identified by the guid number.

{guid number} can be found using the emcli get_instances.

-xml

Show the complete status of each of the steps in XML format

-details

Optional option to display more details to the output of the command. Can only be used in conjunction with the -xml option.

-showJobOutput

Show output or error of the Job Execution steps.

-tailLength={Last N Characters}

Optional argument to limit the number of characters in the job step output or error. Can only be used with the -showJobOutput option.

{Last N Characters} is a positive non-zero number till which the characters would be picked from the end of the job step output

Max permissible characters to dump as part of the above is set by system.

If this option is not provided, then max permissible characters would be dumped.

Example

emcli get_instance_status -guid=16B15CB29C3F9E6CE040578C96093F61 -xml -showJobOutput -tailLength=1024
    emcli get_instance_status -guid=16B15CB29C3F9E6CE040578C96093F61 -xml -details -showJobOutput
    emcli get_instance_status -guid=16B15CB29C3F9E6CE040578C96093F61 -xml -details
    emcli get_instance_status -guid=16B15CB29C3F9E6CE040578C96093F61 

get_procedure_types

Description

Get the list of all Deployment Procedure types.

Usage

emcli get_procedure_types

Example

emcli delete_instance -instance=16B15CB29C3F9E6CE040578C96093F61

Output Column

Procedure Type

get_procedure_xml

Description

Get the Deployment Procedure XML file. XML will be printed on standard output.

Usage

emcli get_procedure_xml -procedure={procedure guid}

Option

-procedure

The procedure GUID.

Example

emcli get_procedure_xml -procedure=16B15CB29C3F9E6CE040578C96093F61 > proc.xml

Output

The Deployment Procedure XML

get_procedures

Description

Get a list of Deployment Procedures.

Usage

emcli get_procedures [-type={procedure type}]

Option

-type={procedure type}

display all the Deployment Procedure of type {procedure type}.

Output Columns

GUID, Procedure Type, Name, Version, Created By.

EMCLI Verbs for Deployment Instances

Following are the emcli verbs for deployment instances.

confirm_instance

Description

Confirm manual step.

Usage

emcli confirm_instance -instance={instance_guid} -stateguid={state_guids}

Option

-instance

The instance GUID.

-stateguid

The separated list of State GUIDs.

Example

emcli confirm_instance -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid=51F762417C4943DEE040578C4E087168
    emcli confirm_instance -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid='51F762417C4943DEE040578C4E087168,51F762417C4944DEE040578C4E087168'

delete_instance

Description

Delete a stopped or completed Deployment Instance.

Usage

emcli confirm_instance -instance={instance_guid} -stateguid={state_guids}

Option

-instance

The instance GUID.

Example

emcli delete_instance -instance=16B15CB29C3F9E6CE040578C96093F61

get_instance_data_xml

Description

Download Instance Data XML.

Usage

emcli get_instance_data_xml -instance={instance_guid}

Option

-instance

The instance GUID.

Example

emcli get_instance_data_xml -instance=16B15CB29C3F9E6CE040578C96093F61 > data.xml

Output

The Instance Data XML.

get_instances

Description

Display list of Procedure Instances.

Usage

emcli get_instances -type={procedure type}

Option

-type={procedure type}

display all the Procedure Instances of type {procedure type}.

Example

emcli delete_instance -instance=16B15CB29C3F9E6CE040578C96093F61

Output Columns

GUID, Procedure Type, Instance Name, Status

get_retry_arguments

Description

Get arguments of failed steps which can be retried.

Usage

emcli get_retry_arguments -instance={instance_guid} [-stateguid={state_guid}]

Option

-instance

The instance GUID.

-stateguid

The State GUID.

Example

emcli get_retry_arguments -instance=16B15CB29C3F9E6CE040578C96093F61
    emcli get_retry_arguments -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid=51F762417C4943DEE040578C4E087168

ignore_instance

Description

Ignore failed step.

Usage

emcli ignore_instance -instance={instance_guid} -stateguid={state_guid}

Option

-instance

The instance GUID.

-stateguid

The State GUID.

Example

emcli ignore_instance -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid=51F762417C4943DEE040578C4E087168
    emcli ignore_instance -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid='51F762417C4943DEE040578C4E087168,51F762417C4944DEE040578C4E087168'

reschedule_instance

Description

Reschedule a submitted Procedure Instance Note that only scheduled instances can be rescheduled

Usage

emcli reshedule_instance        -instance={instance guid}        -schedule=            start_time:yyyy/MM/dd HH:mm;            tz:{java timezone ID};            grace_period:xxx

Option

-instance

The GUID of the instance to execute.

-schedule

The schedule for the Procedure Instance. start_time - when the procedure should start tz - the timezone ID ( optional ) grace_period - grace period in minutes( optional )

Example

emcli reschedule_instance -instance=16B15CB29C3F9E6CE040578C96093F61 -schedule="start_time:2006/6/21 21:23;tz:America/New_York;grace_period:60

resume_instance

Description

Resume a suspended Deployment Instance.

Usage

emcli resume_instance -instance={instance_guid}

Option

-instance

The instance GUID

Example

emcli resume_instance -instance=16B15CB29C3F9E6CE040578C96093F61

retry_instance

Description

Retry failed instance or failed step.

Usage

emcli retry_instance -instance={instance_guid} [-stateguid={state_guid}]

Option

-instance

The instance GUID

-stateguid

The State GUID.

Example

emcli retry_instance -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid=51F762417C4943DEE040578C4E087168
    emcli retry_instance -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid='51F762417C4943DEE040578C4E087168,51F762417C4944DEE040578C4E087168'

set_instance_jobgrants

Description

Set the user access privilege for jobs of the Deployment Instance.

Usage

emcli set_instance_jobgrants -instance_guid={instance guid} -grants={user:privilege}

Option

-instance

The instance GUID

-grants

String of user:privilege pairs each separated by ; .

where user = em user name,

privilege = VIEW_JOB or FULL_JOB.

Example

emcli set_instance_jobgrants -instance_guid=16B15CB29C3F9E6CE040578C96093F61 -grants="user1:VIEW_JOB;user2:FULL_JOB"

start_paf_daemon

Description

Start Deployment Procedure Manager Daemon.

Usage

emcli start_paf_daemon -interval={number in minutes}

Option

-interval

Number in minutes that Deployment Procedure Manager Daemon should wait between each run.

status_paf_daemon

Description

Get Deployment Procedure Manager Daemon status.

Usage

emcli status_paf_daemon

stop_instance

Description

Stop a scheduled, failed, or running Deployment Instance.

Usage

emcli stop_instance -instance={instance_guid}

Option

-instance

The instance GUID

Example

emcli stop_instance -instance=16B15CB29C3F9E6CE040578C96093F61

stop_paf_daemon

Description

Stop Deployment Procedure Manager Daemon.

Usage

emcli stop_paf_daemon

submit_procedure

Description

Submit a Deployment Procedure.

Usage

emcli submit_procedure
        -procedure="guid of the procedure"
        -input_file="data:{file_path}"
        [-instance_name="name for the procedure instance"]
        [-grants="users and their correspoding access levels"]
        [-schedule=
            start_time:yyyy/MM/dd HH:mm;
            tz:{java timezone ID};
            grace_period:xxx];
        ]

Option

-procedure

The GUID of the procedure to execute.

-input_file=data:file_path

The input data for the Deployment Procedure.

The file_path should point to a file containing the data XML file.

-instance_name

The name of the procedure instance ( optional )

-grants

Users and their corresponding access levels ( optional )

String of user:privilege pairs each separated by ; .

where user = em user name,

privilege = VIEW_JOB or FULL_JOB.

-schedule

The schedule for the Deployment Procedure ( optional ).

If not specified, the procedure will be executed immediately.

start_time - when the procedure should start

tz - the timezone ID ( optional )

grace_period - grace period in minutes( optional )

Example

emcli submit_procedure -input_file=data:data.xml -procedure=16B15CB29C3F9E6CE040578C96093F61 -grants="user1:VIEW_JOB;user2:FULL_JOB" -schedule="start_time:2006/6/21 21:23;tz:America/New_York;grace_period:60" -instance_name="MyProcedureInstance_0001"

Output

Instance GUID

suspend_instance

Description

Suspend a running Deployment Instance.

Usage

emcli suspend_instance -instance={instance_guid}

Option

-instance

The instance GUID

Example

emcli suspend_instance -instance=16B15CB29C3F9E6CE040578C96093F61

update_and_retry_step

Description

Update arguments of the failed step and retry it.

Usage

emcli update_and_retry_step -instance={instance_guid} -stateguid={state_guid} [-args="command1:value1;command2:value2;..."]

Option

-instance

The instance GUID

-stateguid

The State GUID.

-args

Arguments, which will be updated.

Example

emcli update_and_retry_step -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid=51F762417C4943DEE040578C4E087168 -args="command:ls"