10 Using Enterprise Manager For Grid Automation With Deployment Procedures

10.4.1.1 Insert Custom Step to Backup the Database Before Patching

A data center is notified by Grid Control that its Oracle Database installations are affected by Oracle's latest Critical Patch Update (CPU). The Security administrator studies the impact and hands it over to the lead DBA who first applies it to his test systems. In the process he wants to backup the database before applying the patch. He uses the Create Like feature of the out-of-box Oracle Database Patching Deployment procedure and inserts a custom step before the Apply Patch step, associating his script to take a backup, which he has uploaded to the Software Library. As a result, on the execution of the Deployment Procedure the backup of the database is performed each time before applying the patch.

10.4.1.2 Manual Step

XYZ Corporation has a process of ensuring that users are logged off from their application before the database is shutdown. The DBA checks with key users that they have indeed logged off before proceeding with the database shutdown. This can be achieved by introducing a manual step before the ÒStop DatabaseÓ step. The procedure would pause on the completion of the manual step. Only when the DBA chooses to continue would the procedure advance.

10.4.1.3 Application Service Shutdown and Startup Handling

Deployment procedures can be used to perform operations that are outside the scope of out-of-box procedures. Examples include stopping and starting an ERP application or registering a newly provisioned service with the load balancer. Each of these steps can run in the context of any valid operating system user and can make use of a Pluggable Authentication Module like ÒpbrunÓ (Powerbroker). They can also run in superuser mode using ÒsudoÓ.

10.4.1.4 Set Notification for the Deployment Procedure Run

Oracle Enterprise Manager version 10.2.0.3 has capabilities that allow it to send notifications for the deployment procedure run status.

To receive notifications from deployment procedures, follow the steps below during design time:

1. Do a 'Create Like' of the out-of-box procedures

2. Select the check box 'Enable Notification', and optionally provide the 'Notification Tag Name'.

3. Select the statuses for which you would want the notifications to be sent from the list. For example : Success, Failure, or Action Required.

4. Save the procedure.

5. Enable the Send Email option for the standard PAF Status Notification rule from the Notification Rules page under Preferences.

Upon running the procedure based on the status selected for notification, the users for whom the email address is setup would receive notifications.

The above case assumes that the Mail Server is configured and the email address is preset in the Oralce Enterprise Manager Grid Control. For instructions on how to configure notifications, see Section 13.1, "Setting Up Notifications".

Advanced users can customize the standard PAF Status Notification rule to receive notifications in required ways for specific deployment procedures. For example, you might want to be notified by email for a test system procedure, but for a production run you might want to be informed of the status through SMS Alerts. To incorporate specific requirements and enable different methods of notification, you would need to use the 'Create Like' function to modify the standard out-of-box notification rule and edit the job with the specific notification tag name used in the deployment procedure and associating specific Method of notification from the pre-defined notification methods.

10.8.3.1 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 Appendix B 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.

10.8.3.2 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"/>...

The portions in bold face are actually the configuration property values that were used during the last execution of the patching procedure.

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.

10.8.3.3 Properties File For Extending Procedure Execution

Properties file also 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 at Appendix B, "Sample Property Files for the Out-of-Box RuntimeData Templates" for the various procedures). For example:

node1 = node2,node 3

Wherein node1 is the Target for which you had executed 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 Section 10.8.8, "Queries to Acquire Data for Patching Runtime" for the list of queries which can be used to acquire data for creating properties file.

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

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

perl executeDP.pl patch_standalone_DB.xml Properties.txt 1FC6362A6A0615A6E040578C5E54218B

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.

1FC6362A6A0615A6E040578C5E54218B 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 executed script. Also, the deployment procedure is scheduled to run immediately in the time zone of the OMS.

10.8.5.1 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 the EMCLI 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 as described in section.

• 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 atleast 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 the 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 atleast 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 Gold Image, 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.

10.8.5.2 Use Cases for Extend Cluster Procedure

Use Case 1: User wants to use the EMCLI to extend a 2-node 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 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.

10.8.5.3 Use Cases For RAC Delete/Descale Procedure

Use Case 1: User wants to use the 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.

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

10.8.5.5 Limitations

There are two limitiations to consider when using patching deployment procedures through EMCLI.

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

2. EMCLI based patching currently does not support adding more than one patch using the properties file to the standard template. The standard out-of-box properties file supports the ability to specify only a single patch number as a value to the property "PA_VAR_patchID_1". For the EMCLI execution using the exported runtime data xml for the run, you can only utilize it for the patch numbers with which it was created. You cannot add patches in an adhoc fashion during the run time through properties file.

   To patch the targets with more than one patch, run the deployment procedure from the user interface selecting the new patches and then submit the procedure. Stop the execution immediately after the initialization step. This will generate the run time data xml with the new patch numbers. Export the run time data xml and use it to for the EMCLI based execution.

10.8.6.1 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).

10.8.6.2 Setting Credentials Through EMCLI

You can set the credentials for targets through the 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 3 (10.2.0.3.0). This document is available at:

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