Skip Headers
Oracle® Enterprise Manager Advanced Configuration
10g Release 3 (10.2.0.3.0)

Part Number B40002-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

10 Using Enterprise Manager For Grid Automation With Deployment Procedures

Deployment procedures are Oracle's latest contribution in automating operations around the grid. This chapter introduces the concept of deployment procedures to system administrators and integrators. The chapter spells out the advantages and features of deployment procedures and discusses a sampling of use cases that these deployment procedures are designed to solve.

Deployment procedures are out-of-box best practices that comprise enumeration of a set of steps that are orchestrated by Oracle Enterprise Manager. Oracle ships a set of Òbest practiceÓ deployment procedures to accomplish provisioning and patching related tasks. Deployment procedures can be extended and customized for customer needs. The deployment procedure to patch a single instance database differs from the one to patch a Data Guard or a RAC environment. Deployment procedures can vary from one customer to another, or from a test installation to a production installation.Deployment procedures take into account and resolve the reality that environments are often different, with each having complexities across different tiers with multiple dependencies. The situation is further compounded by existing operational practices. For example, in a typical data center, deployment procedures can involve a design time activity (typically performed by a lead administrator) and a runtime activity (typically performed by the operator).Deployment procedures have been introduced in Grid Control 10.2.0.3 and are licensed under the Oracle Enterprise Manager Provisioning Pack.

10.1 Key Advantages of Deployment Procedures

The main advantage of deployment procedures lies in the fact that they can provide an extremely flexible framework for data center automation. While a vendor like Oracle often has specific best practice recommendations for patching and provisioning, the reality is that each data center has unique ways of achieving them. Deployment procedures are nothing more than a framework to achieve synergy between Oracle's out of box best practices and customers' own methods. Custom scripts can easily be plugged into deployment procedures for handling special tasks. The following properties of deployment procedures increase their value:

  1. Extensible

    The objective of deployment procedures is to have as many best practice methods out of box as possible. In an ideal case the customer should be able to run the deployment procedures as-is against a set of targets. Oracle-shipped best practices deployment procedures cannot be modified. The customer can create a copy of the Oracle shipped deployment procedure and modify the same to insert or delete steps and error handling modes.

  2. Reusable

    Deployment procedures are reusable. The steps of the deployment procedure can be based against directives that are stored in the Software Library. The deployment procedures can also be exported and imported across environments. This implies that the deployment procedures once developed for a test environment need not be recreated for production environment.

  3. Hot-pluggable

    The out-of-box deployment procedures are metadata driven so new sets of procedures can be added to the Oracle Enterprise Manager environment without any additional outage.

  4. Automatable

    The runtime for all the deployment procedures can be automated using EMCLI and associated verbs, such as Oracle patching, OS patching and so forth. For more information on these verbs, see the Oracle® Enterprise Manager Command Line Interface 10g Release 3 (10.2.0.3) for Windows or UNIX.

10.1.1 Deployment Procedures Shipped In Oracle Enterprise Manager

In version 10.2.0.3 of Oracle Enterprise Manager, the out-of-box deployment procedures include the following:

  • Application Server Deployment

  • Oracle Clusterware/Oracle Real Applications Clusters (RAC) Provisioning

  • Delete/Scale Down Oracle Real Applications Clusters

  • One Click Extend Cluster Database

  • Patch Oracle RAC Database -- All Nodes

  • Patch Oracle RAC Database -- Rolling

  • Patch Oracle Clusterware (Rolling Upgrade)

  • Patch Oracle Database

  • Patch Application Server

  • Patch Solaris Hosts

  • Patch Linux Hosts

  • Patch Windows Hosts

  • Patch Standalone Oracle Automatic Storage Management

10.2 Deployment Procedure Requirements

Deployment procedures can be used for targets managed by agents with versions of 10.2.0.2.0 or higher. Certain features in the Deployment Procedures Manager will not work with a 10.2.0.1 (or lower version) agent, even if the agent is uploading to a 10.2.0.2.0 Management Server.

Deployment procedures can be found under the Deployment Procedure Manager on the Deployments page. Choose a deployment procedure and click Run to execute it.

To use deployment procedures, you should first set up the Software Library before applying the 10.2.0.3 patchset. This ensures that the deployment procedures are installed out of the box. If you fail to set up the Software Library beforehand, you will have to set it up later and then manually deploy the files after the installation. For more information see Section 10.8.1, "Known Issues". For instructions on how to set up a software library, see Section 18.7, "Setting Up and Configuring a Software Library With Oracle Enterprise Manager".

10.3 Use-Cases for Deployment Procedures

The following sections provide examples of some use cases for deployment procedures.

10.3.1 Using Deployment Procedures to Apply Security-Related Critical Patch Updates to Oracle Databases

The out-of-box deployment procedure Patch Oracle Database can be used to apply critical patch updates (CPU) to several single instance databases simultaneously. In the following example, patch 5049080, a critical patch, is applied to 10.2.0.1 databases.

This involves the following steps:

  1. Patch Download and Upload step (optional)

    Upload to Patch Cache is required only if there is no connection between the Management Server and Oracle Metalink. In 10.2.0.3 the Software Library is integrated with the Patch Cache. While uploading a patch to the Patch cache, you can choose the ÒCreate Oracle Software Update ComponentÓoption. This will ensure that the patch is visible in the Software Library.

  2. Runtime (Deployment time) steps:

    There are 3 inputs that must be provided at runtime - the patch number(s), the targets and the credentials. Finally the procedure must be scheduled for immediate or deferred execution.

    1. Select the procedure ÒXYZ Corp's CPU patching procedureÓ and run it.

      You can choose to select the patch from Metalink or from the Software Library.

    2. Deployment Procedure by default will run the default SQL (catcpu.sql for CPUs) if present or you can provide custom SQL script to run.

    3. The targets are then chosen from a list of targets that are automatically populated on the screen based on the version of the product the patch applies to.

    4. Credentials follow. You can choose to use the ORACLE_HOME credentials from the repository.

    5. Finally the procedure is scheduled and submitted. The procedure can then be monitored by using ÒProcedure Completion StatusÓ link. It can be retried from a failed step, if required.

10.3.2 Using Deployment Procedures for Single-Click Extend of Real Application Clusters

The out-of-box "Extend Real Application Clusters" deployment procedure can be used for extending an existing Real Application Cluster to one or many nodes. In the following example, an existing cluster is extended to one additional node.

Use the following steps:

  1. Runtime (Deployment time) steps:

    1. Run the out-of-box Extend Real Application Clusters procedure.

    2. Choose the existing cluster to be extended and mention the details of the new node where the cluster will be extended.

    3. Mention the credential information for the new nodes and a schedule for extension operation. After you finish, click the Submit button to execute the deployment procedure.

    Once you submit the procedure, you can monitor it using the Procedure Completion Status link.

10.3.3 Using Deployment Procedures for Delete/Scale Down of Real Application Clusters

You can use the out-of-box Delete/Scale Down Real Application Clusters deployment procedure to delete or scale down an existing Real Application Cluster.

Use the following steps:

  1. Runtime (Deployment) steps:

    1. Run the out-of-box Delete/Scale Down Real Application Clusters procedure.

    2. From the list of available nodes, select one, multiple, or all nodes for deletion from the cluster.

    3. Mention the credential information for the new nodes and a schedule for extension operation. When you finish, click Submit to execute the deployment procedure.

Once you submit the procedure, you can monitor it using the Procedure Completion Status feature.

10.4 Customizable Deployment Procedures

The out-of-box deployment procedures can be used as starting templates to create similar procedures (using the ÒCreate LikeÓ functionality), which can then be customized. You can edit the deployment procedure to insert or delete a step or a phase, or to enable or disable a step or a phase. Deployment procedures also allow different error handling methods depending upon the case. For example, in a patching operation where hosts are patched in parallel, it may be wise to simply skip the host on which a failure occurs. However, failure on a device creation could render the remaining provisioning operation ineffective. Therefore it may be necessary to abort the entire procedure for failure of such a step.

10.4.1 Customization Examples

The following sections describe three examples that illustrate how deployment procedures can be customized.

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

To receive notifications on the deployment procedure status during the design phase on a Create Like or the out-of-the-box deployment procedure, check the Enable Notifications check box and provide details for the Notification Tag Name, which you can use to associate to other Enterprise Manager Notification methods, and the status for which you would require notifications such as Success, Failure, or Action Required. The administrator is notified when the procedure based on the status selected for notification is run.

The above use case would require Configuration of Mail Server for Notification methods from Enterprise Manager to be working. For instructions about how to configure Notifications, see Section 13.1, "Setting Up Notifications".

To leverage the Enterprise Manager Notification methods, create a notification rule similar to "PAF Status Notification", which you can get to by navigating to the Preferences page and selecting Notification rule, and configure it such that the job name is prepended with the notification job tag that you specified for your procedures. Repeat the process to create notification rules to activate notification for other procedures associated with their notification tag name.

10.4.2 Importing or Exporting Deployment Procedures

In version 10.2.0.3 there is an out-of-box PARDeploy utility to export deployment procedures created by a user and distribute them across various Oracle Enterprise Manager deployments.

Provisioning Archive files can contain deployment procedures and/or components and directives from Software Library. Oracle provides PAR files that contain Oracle best-practices deployment procedures and the directives required to run them.PARDeploy tool is located at $ORACLE_HOME/bin directory. Please be sure the $ORACLE_HOME environment variable is set to the oracle home of the OMS and the Software Library path is configured before you run PARDeploy. When you run $ORACLE_HOME/bin/PARDeploy, it will print out the following usage information.

Usage:

parFile <file> -force(optional)

PARDeploy -action <deploy|view> -parDir <dir> -force(optional)

PARDeploy -action export -guid <procedure guid> -file

<file> -displayName <name> -description <desc> -metadataOnly(optional) PARDeploy -check

  • -force <force> -- Force the Software Library entities to be created

  • -check <check> -- Check to determine whether Software Library is configured

  • -file <file> -- PAR file

  • -action <deploy|view|export> -- Deploy, view, or export par file

  • displayName <displayName> -- PAR file name

  • parDir <dir> -- Directory where par files are located

  • metadataOnly <metadataOnly> -- Flag for metadata-only exports

  • guid <guid> -- Procedure GUID to export

  • parFile <file> -- Path of PAR file

  • description <description> -- PAR file description

PAR files provided by Oracle are located at $ORACLE_HOME/sysman/prov/paf. To deploy asprov.par in that directory, you can run the following command.

$ORACLE_HOME/bin/PARDeploy -action deploy -parFile $ORACLE_HOME/sysman/prov/paf/asprov.par -force

You can also deploy all of the PAR files in that directory by running the following command:

$ORACLE_HOME/bin/PARDeploy -action deploy -parDir $ORACLE_HOME/sysman/prov/paf/ -force

To create a PAR file that contains a specific procedure, use the export action. You must have the GUID of the deployment procedure, which you can acquire by logging into Enterprise Manager and moving to the Deployments tab. Then you can click on the Deployments procedure link in the Deployment Procedure Manager section. In the table, find the deployment procedure that you want to export and click on the name. In the procedure view page, note the URL address on the Navigation toolbar. The format should be similar to this:

http://<OMS host>:<port>/em/console/paf/procedureView?guid=<value of GUID>

You will then need to use the GUID value to run PARDeploy tool. For example, if the GUID of the deployment procedure that you want to export is FAC05DD31E3791C3E030579D23106C67, then run the following command:

$ORACLE_HOME/bin/PARDeploy -action export -guid FAC05DD31E3791C3E030579D23106C67 -file exportedDP.par -displayName "User exported DP" -description "Deployment Procedure to be copied to other OMS"

After you run this command, a new PAR file named exportedDP.par will be created in the directory where you run the command. Then you can import this PAR file to another OMS. You can use this PARDeploy tool to import or deploy it to an OMS, or you can also log in to the second Enterprise Manager, go to the Deployment Procedures main page and click on the Upload button to upload the PAR file.

Please note that when a procedure is exported using PARDeploy, any directives or components referred by the procedure will also be exported. However, only the latest revision of these directives or components will be exported. If you do not want to export components or directives, you can specify the metadataOnly flag when running PARDeploy.

10.5 Executing Deployment Procedures Using Pluggable Authentication Modules (PAM) and SUDO

Deployment procedures allow execution in sudo and other pluggable authentication modules (PAM) contexts. The sudo and the PAM command to be used throughout the procedure can be specified while editing the procedure. The individual directive steps can be chosen to run in normal mode, privileged mode (which requires sudo setup at the target for superuser execution for the command) or as a different user than the preferred credentials.

The use case is described below. The operating system users on the target box are shown below. User names in actual environments may vary.

Requirements for the users are:

The goal in these examples is to patch the DATABASE HOME using foo's credentials.

10.5.1 Design Time Experience Example (One Time)

This process must be completed only once to customize the deployment procedure.

  1. User selects the Oracle shipped Patch Oracle Database Deployment Procedure and does a Create Like for that deployment procedure and provides it a name.

  2. User selects run-as sudo for all steps in the edited deployment procedure

  3. User selects the sudo command to be run. In this example it may be Òsudo –u oracleÓ

  4. User gives the staging location for the directives in ÒStaging Area PathÓ. The default is %oracle_spool%/EMStagedPatches/Others. Example: It could be %emd_root%/EMStagedPatches/Others This directory needs to have 770 permissions. This could also be any other directory which can be written onto by user ÒoracleÓ.

  5. User saves the modified deployment procedure (Patch Oracle Database with sudo).

10.5.2 Run Time Experience (Every Time)

This process must be completed for every run of the deployment procedure. User selects the modified patching deployment procedure (Patch Oracle Database with sudo) and runs it.

  1. User selects the Database Updates to be patched.

  2. User provides the location for staging the patch. The default for this is: User gives the PA Staged location as: %oracle_spool%/EMStagedPatches/Others Example: It could be %emd_root%/EMStagedPatches/Others This directory needs to have 770 permissions and it should exist before the DP is run. This could also be any other directory which can be written onto by user ÒoracleÓ.

  3. Now user gives foo's credentials (Patching User credentials).

  4. Schedule and submit the job.

10.6 Deployment Procedure Variables

Oracle Enterprise Manager exposes several variables that can be used with deployment procedures. These variables can be used by Oracle customers to customize their specific tasks like startup and shutdown using their own directives.

Per ORACLE_HOME:

oraHome - Directory of the ORACLE_HOME

replacedStageDir - The absolute staging location of patches

instances - Selected database targets from the ORACLE_HOME

all_instances_home - All database targets running from the ORACLE_HOME

dbSIDs - All sids from the ORACLE_HOME

dbListeners - All listeners from the ORACLE_HOME

isPatchset - Yes/no of if patchset is being applied to the ORACLE_HOME

runRootScript - Yes/no indicating if rootscript needs to be run

Global:

stageDir - the staging directory to use provided like %oracle_home%....

patchIDs - list of patch ids selected

patchSrcs - indicating whether the patches came from Metalink or software lib

patchData – Uniform resource Names (URNs) of the patches

patchReleases - corresponding release of the patches

10.7 Using EMCLI to Execute 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 process to use EMCLI to execute deployment procedures is depicted in Figure 10-1.

Figure 10-1 EMCLI Process to Execute Deployment Procedures

Surrounding text describes Figure 10-1 .

For each run, you can populate a simple properties file with specific information such as hosts, platform for deployment, and other required information.

The provided sample scripts use these two files as inputs and generate an instantiated runtime data response file containing all properties required for provisioning the system. This approach allows you to maintain one template and generate a small properties file for custom changes, thus ensuring that you do not have to be concerned about XML format changes or changes to variables due to customizations created by the system administrator for that data center.

Set up EMCLI on your system and submit the procedure with this instantiated runtime data as the input, along with the procedure to be executed. EMCLI provides an instanceGUID for the procedure being executed. You can monitor the status of this instance using its instanceGUI from CLI or from the Oracle Enterprise Manager user interface.

10.7.1 Creating the RuntimeData Templates

If you have tested and are satisfied with the provisioning procedures provided by Oracle, you can skip this section. If you have customized the procedures to your environment, you can use these steps to create templates for your system.

10.7.1.1 Step 1: Locate the Successful Test Run of Your Customized Procedure

Each procedure execution is associated with a unique instanceGUID.

  1. Log in to Enterprise Manager.

  2. Go to the Deployments tab and choose Procedure Completion Status.

    You can access the RAC procedure completion status by clicking on the RAC Provisioning Procedures and then clicking on Procedure Completion Status tab.

    You can access the AS procedure completion status by clicking on the Application Server Provisioning Procedures and then clicking on Procedure Completion Status.

    You can access the Patching procedure completion status by clicking on the Patch procedure and then clicking on the Procedure Completion Status tab.

  3. Retrieve the instanceGUID for the execution.

    The link takes you to the procedure steps. The URL includes the instanceGUID. You can acquire the same information from the following EMCLI command:

    emcli get_intances -type={procedure type}

    Usage: ./emcli get_instances -type={procedure type}Description: Displays a list of procedure instances Option: -type={procedure type}Output Columns: GUID, Procedure Type, Instance Name, Status See Also: emcli help get_procedure_types

10.7.1.2 Step 2: Download the Runtime Data For This Run

Use EMCLI to download the runtime data associated with this instance. Use the following command:

emcli get_instance_data_xml -instance={instance_guid}

Usage: ./emcli get_instance_data_xml -instance={instance_guid}Description: Download Instance Data XML Option: -instance Option Description: The instance of the GUID. Example: emcli get_instance_data_xml -instance=16B15Cb29C3F9E6CE040578C Output: The Instance Data XML

10.7.1.3 Step 3: Locate and Create Instantiation Variables

For various use cases, you must have the XML file for the RuntimeData containing the parameter values for the specific deployment procedure run. This must be in a format where the parameter values, which are passed at runtime, are distinctly identified by appropriate placeholders.

Below is an example of a RuntimeData template fie and an explanation of its syntax.

<?xml version = '1.0' encoding = 'UTF-8'?><runtimeData xmlns="http://www.oracle.com/paf/runtimeDataXML"> <elements> <scalar value="^rac_partial_delete_node_PUB_NODELIST_ALL_NODES^" classname="java.lang.String" name="PUB_NODELIST_ALL_NODES"/> <scalar value="^rac_partial_delete_node_NODE_LIST_FOR_DELETION^" classname="java.lang.String" name="NODE_LIST_FOR_DELETION"/> <scalar value="^rac_partial_delete_node_HOST_LIST_FOR_DELETION^" classname="java.lang.String" name="HOST_LIST_FOR_DELETION"/> <scalar value="^rac_partial_delete_node_REMAINING_NODE_LIST^" classname="java.lang.String" name="REMAINING_NODE_LIST"/> ....... ....... ....... </elements></runtimeData>

In the example above, the actual values have been replaced with special placeholder variables that will be substituted by the script with values from the properties file. The syntax of the placeholder variable is seen here:

^<Usecase_name>_<Procedure_variable_name>^

You are can choose any variable name, however, you should refer to this best practice naming convention to capture the use case name adn the variable name. Since the variable is contained in the properties file for runtime deployment, it serves as a self-explanatory indicator of what should be filled in.

In the example above, the use case name is rac_partial_delete_node for scaling down RAC clusters. The surrounding carets (^) are a requirement of parsing logic which is used to substitute values at runtime.

The template should now be ready for use at runtime.

10.7.2 Using the RuntimeData XML Instead Of RuntimeData Templates

Although the previous discussion describes a very generic approach for submitting any deployment procedure using EMCLI where the inputs are a Properties file and Runtime Data template file, there is an alternative approach that uses the same generic script to submit deployment procedures for different use cases using a property file as the only input parameter. No Runtime Data template file is required. Instead, the Runtime data XML file of a previous deployment procedure run is used after downloading it using EMCLI (see Step 1: Locate the Successful Test Run of Your Customized Procedure).

In this approach you can replace the old runtime values in the runtime XML of the previous run with the new runtime values, which are relevant to the new run for the different use case. For example, if you have performed a successful partial cluster scale-down, suppose your deployment runtime XMLfor the run contains the following syntax:

<scalar value="node1" classname="java.lang.String" name="NODE_LIST_FOR_DELETION"/>

On a different occasion, for performing a complete cluster deletion, you might need to have the variable value as:

<scalar value="node1,node2" classname="java.lang.String" name="NODE_LIST_FOR_DELETION"/>

For this you can use a properties file of the form:

<old_value>=<new_value>

In this specific example, the properties file will have:

node1=node1,node2

The script will use the old runtime data XML from the pervious run along with the properties file and it will generate the new runtime data XML file (name will be passed as a parameter) and this can then be used to submit the deployment procedure using EMCLI for the new usecase.

While this second approach would considerably expedite the process, a word of caution is worth mentioning. Since this approach would simply replace an old string with a new string, you might run into issues if the old string is a substring in multiple strings in the deployment procedure runtime XML. In that case the resulting runtime XML might be erroneous. To circumvent this issue, you should format the properties file properly. The rule-of-thumb is to put the specifics before the generics. In particular, while specifying node names you should put the FQDNs before the simple node names. A fragment of a properties file in the form of old-value=new-value pairs is shown below and illustrates this point.

node2.test.com=node3.example.com node1.test.com=node4.example.com node2,node1=node3,node4 node2=node3 node1=node4 ...

10.7.3 Creating a Properties File for Provisioning Procedures

The properties file contains values for the placeholder variables and are essentially in the form of a group of name-value pairs. In the RAC scale-down procedure, the properties file would appear as shown below:

rac_partial_delete_node _PUB_NODELIST_ALL_NODES=node2,node1 rac_partial_delete_node _NODE_LIST_FOR_DELETION=node2 rac_partial_delete_node _HOST_LIST_FOR_DELETION=node2.example.com rac_partial_delete_node _REMAINING_NODE_LIST=node1

The following command may be used to create the properties file. Run this with the runtime data template XML containing the placeholder variables, and the property name as parameters. It will create the property file name in the current working directory:

grep -e "\^.*\^" <runtimedata template xml file> | awk -F"^"'{print $2"="}' | sort | uniq > <prop file>

For example, the command could look like this:

grep -e "\^.*\^" runtimedata_sh.xml | awk -F"^"'{print $2"="}' | sort | uniq > runtime.properties

You can then populate the properties file with appropriate inputs. An alternative approach using the runtime data XML instead of creating templates as described earlier, you could have a set of old-value=new-value pairs in the properties file as seen below:

OraCrs10g_home=OraCrs10g OraASM10g_home1=OraASM10g OraRAC10g_home1=OraRAC10g node2.test.com=stamy02.example.com node1.test.com=stamy01.example.com node2,node1=stamy02,stamy01 node2=stamy02 node1=stamy01

10.7.3.1 Properties File Variables for Provisioning Procedures

The following table shows a list of properties file variables used for Extend Cluster with CRS, RAC, and Agent Push.

Table 10-1 Properties File Variables for Provisioning Procedures

Variable Name Description Example

PUB_NODELIST_ALL_NODES

List of nodes

Node1, Node2

CLUSTERWARE_ORACLE_HOME_LOC

Clusterware Home location

/u01/app/oracle/crs

CLUSTER_ORACLE_HOME_NAME

Clusterware Home name

OraCrs10g_home

ORADATA_LOC

Shared Oradata Location

/oradbshare/oradata/linorcl/temp01.dbf

OCR_PARTITION_VALUE

OCR File Location

/oradbshare/crs/ocr/oradbshare/crs/ocr

VDSK_PARTITION_VALUE

Vdisk File Location

/oradbshare/crs/vdsk

PRIV_NODELIST_VALUE

Private Node Names

node1-priv, node2-priv

PRIV_IP_LIST_VALUE

Private IPs

10.35.69.70,10.2.0.2

VIRTUAL_NODELIST_VALUE

Virtual Node Names

node1-vip, node2-vip

VIRTUAL_IP_LIST_VALUE

Virtual IPs

130.35.69.135,136.34.56.176

DB_SID

Global Database Name

.LINORCL

DB_ORACLE_HOME_LOC

RAC Database Home Location

/u01/app/oracle/product/10.2.0/rac

DB_ORACLE_HOME_NAME

RAC Database Home Name

OraDb10g_home1

DEVICES

List of shared disks

/dev/sda/1%120%ocfs%/oradbshare%ocfs

NICS

Network Interface

eth0:130.35.68.0:PUBLIC,eth1:10.35.68.0:PRIVATE

CLUSTER_NAME

Clusterware Name

CRS

WORK_DIR_LOC

Temporary Work Directory

/temp

REF_NODENAME

Reference Node on Cluster From Where important actions will be triggered

node1.example.com

LISTENER_ORACLE_HOME

Home location of RAC DB Listener

/u01/app/oracle/product/10.2.0/rac

DB_TARGET

Database target

LINORCL

PUB_NODELIST_ADD_INSTANCE_NODES

Node to be added to the existing cluster

node2

EM_REP_USER_NAME

Database user with SYS credentials

SYSMAN

EXT_NODENAME

Host name for the node to be added to the existing cluster

node2.example.com

CRS_NODE_NIC_LIST

Node name, private name, and virtual name for the node being added to the cluster

node2:node2-priv:node2-vip

REF_USERNAME

Reference Host Credentials

oracle

REF_PASSWORD

Reference Host Credentials

oracle

EXT_NODENAME_username

Host credentials of target being included in the cluster

oracle

EXT_NODENAME_password

Host credentials of target being included in the cluster

oracle

CLUSTER_NODE_VIP_NAME

Virtual Name

node2-vip

CLUSTER_NODE_PRIVATE_NAME

Private Name

node2-priv

PRIV_NODELIST_PREREQS

NodeLists

node1-priv,node2-priv,node1-vip

VIRTUAL_IP_LIST_PREREQS

Virtual IPs

136.34.56.176

PRIV_IP_LIST_PREREQS

Private IPs

10.35.69.70,10.2.0.2,130.35.69.135


10.7.3.2 Properties File Variables for Patching Procedures

The following table lists the variables that are present in the runtime template XMLs that are populated with a matching variable from the properties file. A '?' is used to represent the number of occurrences of the variable in the template.

Table 10-2 Properties File Variables for Patching Procedures

Variable Name Description Example

PA_VAR_targetName_?

Host name of the oracle homes where the DB instance resides. This variable must be repeated for each unique host. Please note the targetName under 'homeBeingPatched' is same as the name of the containing host.

Host1.us.oracle.com

PA_VAR_oraHome_?

Oracle Home location to be patched. For each home in the host this variable is repeated. Value of 'credContainerLoc' should have same value as oraHome.

/scratch/OracleHomes/h1

PA_VAR_instance_?_?

Selected list of instances (for example, targets) to be patched in the home.

Target1

PA_VAR_patchID_?

Patch ID of the patch to be installed.

123456

PA_VAR_patchData_?

URN of the patch if it is in the software library. Else it is of the form pPatchID_release_platform_productid.

p4926771_9.2.0.6_46_9480 represents patch 49226771 of release 9.2.0.6 on LINUX for Oracle Database.

PA_VAR_patchSrcs_?

Either specified as SWLIB if patch is in software library, or as METALINK.

METALINK

PA_VAR_patchTypes_?

Type of patch. Ex: Patch, PatchSet.

Patch

PA_VAR_patchReleases_?

Version of the patch

10.2.0.3

PA_VAR_patchPlatforms_?

Platform of the patch

LINUX

PA_VAR_stageDir

Location where the patches are staged.

%oracle_home%EMStagedPatches

PA_VAR_isPatchset

True if Patch is a Patchset, False otherwise.

false

PA_VAR_isNotPatchset

True if the patch is a Patch, False otherwise.

true

PA_VAR_sqlScript

Location of the SQL script to be run. Set to "defaultSqlScript", if the SQL script inside the patch must be run and there is not custom SQL script.

defaultSqlScript

PA_VAR_isUpgradeStepEnabled

True of OPatch in the Oracle Home must be upgraded.

true


The elements 'hostsBeingPatched' and 'homesBeingPatched' do not have to be populated from the properties files. However, variables inside those elements are being populated. The element 'hostsBeingPatched' is the target list declaration that contains the hosts where patching will be done while 'homesBeingPatched' is the inner target list declaration that represents the list of homes within the host.

10.7.3.3 Updating the Runtime Data Template to Fit Various Patching Use Cases

Based on your requirements of patching in multiple hosts and homes, the number of child elements under 'hostsBeingPatched' and 'homesBeingPatched' must be modified in the runtime template data. The same is true of other variables such as PA_VAR_patchId and PA_VAR_patchSrcs.

Using the new runtime data template, the properties file can be generated using the steps described in Section 10.7.4, "Creating the Properties File for Patching Procedures".

10.7.3.4 Getting the Host and Homes From the Instances For Patching Runtime Data

Use the following query to acquire the host name to which the instances belong:

Select host_name from mgmt_targets where target_name = '<instance_name>'

Use the following query to acquire the home location out of which the instance is running:

Select p.property_value from mgmt_target_properties p, mgmt_targets t where p.target_guid = t.target_guid and p.property_name = 'OracleHome' and t.target_name = '<instance_name>'

In the above syntax, a RAC instance represents the RAC instance target, a Standalone instance represents a database target, and a CRS (Clusterware) instance represents the target corresponding to the CRS node, which in most cases is the same as the host name.

10.7.4 Creating the Properties File for Patching Procedures

The method for creating properties files for patching procedures is identical to the method used for provisioning procedures. The same grep command can be used to generate the properties file by using the template runtime XML for standalone database patching. For the alternative approach using the runtime data XML instead of creating templates, the properties file sample is shown below:

PA_VAR_targetName_1=host1.us.oracle.com PA_VAR_oraHome_1=/scratch/home1 PA_VAR_instances_1_1=target11 PA_VAR_instances_1_2=target12 PA_VAR_targetName_2=host2.us.oracle.com PA_VAR_oraHome_2=/scratch/home2 PA_VAR_instances_2_1=target21

10.7.5 Submitting the Deployment Procedure

After the EMCLI has been set up, follow these steps to submit the deployment procedure:

  1. Instantiate the Runtime data

    perl instantiate_runtimedata.pl <source RuntimeData template file name> <destination RuntimeData file name> <Properties file name>

    The destination RuntimeData file name is the file that is generated and contains the substituted property values and is used for the deployment procedure execution. You can pass any desired file name for this parameter. The perl script can be used to generate the runtime data for both provisioning and patching procedures.

  2. Retrieve the appropriate procedure GUID

    The GUID associated with a specific procedure can be retrieved using EMCLI or the Enterprise Manager User Interface. To obtain the GUID of a deployment procedure, click on its link. The View Procedure page displays showing the GUID as the last portion of the URL. Alternatively, you use the following EMCLI commands to retrieve the procedure types and the procedure GUID.

    ./emcli get_procedure_types ./emcli get_procedures -type=(procedure type)

  3. Submit the deployment procedure for execution.

    To submit the deployment procedure for execution, run the following command:

    emcli submit_procedure -procedure=<DP GUID> -input_file=data:<destination RuntimeData file name> [-schedule="<time>"]

    Usage:

    emcli submit_procedure -procedure="GUID of the procedure" -input_file="data:{file_path}" -instance_name="name of the procedure instance" -schedule= start_time:yyyy/MM/dd HH:mm; tz:{java timezone ID}];

    Description: Submit a deployment procedure

    Example:

    emcli submit_procedure -input_file=data:data.xml - procedure=16B15Cb29C3F9E6CE040578C - -schedule="start_time:2007/6/21 21:23;tz:America/New_York"

10.8 Known Issues and Troubleshooting

The following section discusses known issues surrounding deployment procedures and describes how to troubleshoot problems that may arise when using deployment procedures.

10.8.1 Known Issues

If you upgrade an existing 10.2.0.1 or 10.2.0.2 version of Enterprise Manager to version 10.2.0.3, then you must manually re-upload any existing shiphomes for RAC or Application Server procedures.

10.8.2 Troubleshooting

If a specific run of deployment procedures fails, then the following log files can provide insight into the reason of the failure. Correct the reason for failure and rerun the deployment procedure:

  • <OMS_ORACLE_HOME>sysman/log/pafLogs/<log file for this session>

  • <OMS_ORACLE_HOME>sysman/log/emoms.trc

  • <OMS_ORACLE_HOME>sysman/log/emoms.log

For faster resolution of any deployment procedure-related issues, plan to provide these files to support when you create a support request.