Oracle® Enterprise Manager Administrator's Guide for Software and Server Provisioning and Patching 10g Release 5 (10.2.0.5.0) Part Number E14500-04 |
|
|
PDF · Mobi · ePub |
This chapter introduces the usage of EMCLI commands to run Deployment Procedures. In particular, this chapter covers the following:
To gain a better understanding for using EMCLI, you should familiarize yourself with the following EMCLI concepts:
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.
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.
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:
There are four required actions to run Deployment Procedures. Those steps are described below:
Step 1: Find the GUID of the procedure to be run using EMCLI. This is a one-time activity.
Step 2: Obtain the RuntimeData xml or RuntimeData template for the procedure that needs to be run. This is also a one-time activity.
Step 3: Create the properties file for the RuntimeData xml or RuntimeData template. This step is required for each execution of the procedure.
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.
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
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.
The following sections describe the properties files for out-of-box procedures, customized procedures, and extending procedure execution.
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.
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:
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
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 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.
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"/>
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.
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.
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 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 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 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 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.
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.
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.
You can set the credentials for targets through the Oracle Enterprise Manager user interface by following these steps:
Log in to Oracle Enterprise Manger.
Access the link "Preferences" on the top right corner of the page.
Click on "Preferred Credentials" link in the Options section of the page.
Setup 'Normal' or 'Preferred Credentials' from this page for the Target type. (Example: Database Instance, Cluster Database or Cluster).
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
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.
emcli clear_credential -target_type=oracle_database -target_name=myDB -credential_set=DBCredsNormal -user=admin1
emcli clear_credential -target_type=oracle_database -credential_set=DBCredsNormal -user=admin1
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
Following are the EMCLI verbs related to deployment procedures:
Display Procedure Instance status identified by the GUID on the command line.
emcli get_instance_status -guid={guid number} [-xml [-details] [-showJobOutput [-tailLength={Last N Characters}]]]
-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.
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 the list of all Deployment Procedure types.
emcli get_procedure_types
emcli delete_instance -instance=16B15CB29C3F9E6CE040578C96093F61
Procedure Type
Following are the emcli verbs for deployment instances.
Confirm manual step.
emcli confirm_instance -instance={instance_guid} -stateguid={state_guids}
-instance
The instance GUID.
-stateguid
The separated list of State GUIDs.
emcli confirm_instance -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid=51F762417C4943DEE040578C4E087168 emcli confirm_instance -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid='51F762417C4943DEE040578C4E087168,51F762417C4944DEE040578C4E087168'
Delete a stopped or completed Deployment Instance.
emcli confirm_instance -instance={instance_guid} -stateguid={state_guids}
-instance
The instance GUID.
emcli delete_instance -instance=16B15CB29C3F9E6CE040578C96093F61
Download Instance Data XML.
emcli get_instance_data_xml -instance={instance_guid}
-instance
The instance GUID.
emcli get_instance_data_xml -instance=16B15CB29C3F9E6CE040578C96093F61 > data.xml
The Instance Data XML.
Display list of Procedure Instances.
emcli get_instances -type={procedure type}
-type={procedure type}
display all the Procedure Instances of type {procedure type}.
emcli delete_instance -instance=16B15CB29C3F9E6CE040578C96093F61
GUID, Procedure Type, Instance Name, Status
Get arguments of failed steps which can be retried.
emcli get_retry_arguments -instance={instance_guid} [-stateguid={state_guid}]
-instance
The instance GUID.
-stateguid
The State GUID.
emcli get_retry_arguments -instance=16B15CB29C3F9E6CE040578C96093F61 emcli get_retry_arguments -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid=51F762417C4943DEE040578C4E087168
Ignore failed step.
emcli ignore_instance -instance={instance_guid} -stateguid={state_guid}
-instance
The instance GUID.
-stateguid
The State GUID.
emcli ignore_instance -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid=51F762417C4943DEE040578C4E087168 emcli ignore_instance -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid='51F762417C4943DEE040578C4E087168,51F762417C4944DEE040578C4E087168'
Reschedule a submitted Procedure Instance Note that only scheduled instances can be rescheduled
emcli reshedule_instance -instance={instance guid} -schedule= start_time:yyyy/MM/dd HH:mm; tz:{java timezone ID}; grace_period:xxx
-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 )
emcli reschedule_instance -instance=16B15CB29C3F9E6CE040578C96093F61 -schedule="start_time:2006/6/21 21:23;tz:America/New_York;grace_period:60
Resume a suspended Deployment Instance.
emcli resume_instance -instance={instance_guid}
-instance
The instance GUID
emcli resume_instance -instance=16B15CB29C3F9E6CE040578C96093F61
Retry failed instance or failed step.
emcli retry_instance -instance={instance_guid} [-stateguid={state_guid}]
-instance
The instance GUID
-stateguid
The State GUID.
emcli retry_instance -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid=51F762417C4943DEE040578C4E087168 emcli retry_instance -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid='51F762417C4943DEE040578C4E087168,51F762417C4944DEE040578C4E087168'
Set the user access privilege for jobs of the Deployment Instance.
emcli set_instance_jobgrants -instance_guid={instance guid} -grants={user:privilege}
-instance
The instance GUID
-grants
String of user:privilege pairs each separated by ; .
where user = em user name,
privilege = VIEW_JOB or FULL_JOB.
emcli set_instance_jobgrants -instance_guid=16B15CB29C3F9E6CE040578C96093F61 -grants="user1:VIEW_JOB;user2:FULL_JOB"
Start Deployment Procedure Manager Daemon.
emcli start_paf_daemon -interval={number in minutes}
-interval
Number in minutes that Deployment Procedure Manager Daemon should wait between each run.
Stop a scheduled, failed, or running Deployment Instance.
emcli stop_instance -instance={instance_guid}
-instance
The instance GUID
emcli stop_instance -instance=16B15CB29C3F9E6CE040578C96093F61
Submit a Deployment Procedure.
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]; ]
-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 )
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"
Instance GUID
Suspend a running Deployment Instance.
emcli suspend_instance -instance={instance_guid}
-instance
The instance GUID
emcli suspend_instance -instance=16B15CB29C3F9E6CE040578C96093F61
Update arguments of the failed step and retry it.
emcli update_and_retry_step -instance={instance_guid} -stateguid={state_guid} [-args="command1:value1;command2:value2;..."]
-instance
The instance GUID
-stateguid
The State GUID.
-args
Arguments, which will be updated.
emcli update_and_retry_step -instance=16B15CB29C3F9E6CE040578C96093F61 -stateguid=51F762417C4943DEE040578C4E087168 -args="command:ls"