| Oracle® Enterprise Manager Advanced Configuration 10g Release 5 (10.2.0.5) Part Number E10954-03 |
|
|
PDF · Mobi · ePub |
| Oracle® Enterprise Manager Advanced Configuration 10g Release 5 (10.2.0.5) Part Number E10954-03 |
|
|
PDF · Mobi · ePub |
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 are licensed under the Provisioning and Patch Automation Pack.
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:
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.
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.
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.
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 Enterprise Manager Command Line Interface Guide available at:
The following are the out-of-box deployment procedures:
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
Database Provisioning
Oracle Replay Client Provisioning
Linux RPM Repository Server Setup
Patch Oracle Clusterware - All Nodes
Note:
You can patch Oracle Management Agents from Enterprise Manager Grid Control by using the Agent Patch wizard. Enterprise Manager cannot be used to patch its own components such as Repository and Application Server.The following are the requirements for running deployment procedures.
The following are the different versions of products for which the deployment procedures can be run.
Table 11-1 Supported Versions of Products
| Deployment Procedure Name | Supported Versions of Products |
|---|---|
|
Oracle Database Provisioning - Single Instance |
Oracle Database 10.2, 11.1 |
|
Oracle Database Provisioning - RAC Instance |
|
|
Application Server Provisioning |
Oracle Application Server 10.1.3, 10.1.3.1 SOA, 10.1.2.0.2, 10.1.3, 10.1.2.0.2 |
The supported version of SUDO is 1.6.9.5 P5.
The supported version of PBRUN is 4.0.8.
You can use Oracle Management Agent 10g Release 2 (10.2.0.2.0) or higher. However, Oracle recommends you to use the latest Management Agent release available at:
http://www.oracle.com/technology/software/products/oem/htdocs/agentsoft.html
To use deployment procedures, you should first set up the Software Library. 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 instructions on how to set up a software library, see "General Troubleshooting Techniques for Creating the Management Repository" 0, "Setting Up and Configuring a Software Library With Oracle Enterprise Manager". For more information see Section 11.9.1, "Known Issues".
Before using the Deployment Procedures, apply the patches required for your release of Enterprise Manager Grid Control as described in My Oracle Support note 427577.1.
If you are using Enterprise Manager 10g Grid Control Release 5 (10.2.0.5) and if it is configured for offline mode of patching, then from My Oracle Support, manually download patch 6880880 for the required platform and version of the target you are patching, and upload it to the Software Library. This is a platform-specific patch, so you will have to carefully select the platform while downloading this patch.
For example, if you are patching Oracle Database 11g Release 1 (11.1) that is running on Linux x86, then download patch 6880880 for the Linux x86 platform and for the 11.1.0.0.0 release. To upload patches to the Software Library, in Grid Control, click the Deployments tab, and from the Patching section, click View/Upload Patch. Ensure that you upload it under the product family "System Management Products and Product - Universal Installer" with the appropriate release and platform details.
The following sections provide examples of some use cases for deployment procedures.
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.
Note:
Before running any patching-related deployment procedures, meet the prerequisites listed in Section 11.2.5, "Patch Requirements".This involves the following steps:
Patch Download and Upload step (optional)
You can choose to upload it to Oracle Software Library or Patch Cache.
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.
Select the out-of-box deployment procedure “Patch Oracle Database” and run it.
You can choose to select the patch from My Oracle Support or from the Software Library.
Deployment Procedure by default will run the default SQL (catcpu.sql for CPUs) if present or you can provide custom SQL script to run.
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.
Credentials follow. You can choose to use the ORACLE_HOME credentials from the repository.
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.
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:
Runtime (Deployment time) steps:
Run the out-of-box Extend Real Application Clusters procedure.
Choose the existing cluster to be extended and mention the details of the new node where the cluster will be extended.
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.
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:
Runtime (Deployment) steps:
Run the out-of-box Delete/Scale Down Real Application Clusters procedure.
From the list of available nodes, select one, multiple, or all nodes for deletion from the cluster.
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.
Enhanced Linux Patching feature of Enterprise Manager supports the Unbreakable Linux Network (ULN) subscribers through EM. ULN provides access to Linux software patches, updates and fixes for its customers. Oracle provides three levels of Unbreakable Linux support:
Network Support - access to patches and updates via ULN
Basic Support - access to patches and updates via ULN, 24x7 support, complete Linux server life cycle management
Premier Support - access to patches and updates via ULN, 24x7 support, Linux server life cycle management, backporting, lifetime support
The Linux Staging Server Setup page in EM allows you to set up a staging server for Linux patching. You can select the Host to setup the Staging server and register the host to the Unbreakable Linux Network (ULN).
Before using the Enhanced Linux patching feature, you must set up the Stating Server and this is a one-time task. The processes involved in setting up a Staging server are:
Manually registering the Staging server machine to ULN
Manually subscribing to additional ULN channels
Configuring the Staging Server in EM
These processes can be executed by using a deployment procedure that has four steps:
Installs the up2date tool in the Staging Server.
Register the Staging Server to ULN. This is a manual step.
Subscribes the Staging Server to additional ULN channels.
This is also a manual step and the deployment procedure will prompt you to perform these two steps manually and outside EM.
The deployment procedure downloads the latest packages from the subscribed channels into the Staging Server.
This is a recurring step, run once in 24 hours. It checks for any new packages that are available in the ULN channels and downloads it into the Staging Server. First three steps are run only once. The last step is performed only after the two manual steps are completed.
Staging server can be registered to ULN by using the up2date tool. Up2date is a program that allows a machine to be synchronized with the latest packages. To use ULN and up2date, you must register the Staging server with ULN and subscribe to a ULN channel (it is also possible to subscribe to multiple channels). There are several ULN channels available and one containing the latest version is automatically chosen upon registration depending on the architecture and OS version of the Staging server.
Follow these tasks as a root user to register Staging server to ULN:
Download the Enterprise Linux up2date RPM from http://linux.oracle.com. To install the up2date RPM, type the following command in the command line:
#rpm -Uvh up2date-4.4.6936.i386.rpm
up2date version and architecture varies according to Staging Server configuration. This command will be run as a root user.
Import GPG Key of Oracle by running the command:
#rpm --import /usr/share/rhn/RPM-GPG-KEY
Note:
The Software Library by default contains the latest version of up2date for Red Hat Enterprise Linux 4, i386 hardware platform. If the Staging Server is of a different release version or architecture (use uname -p on your system to identify the architecture), download the appropriate version of "up2date" and "up2date-gnome" packages from the link
http://linux.oracle.com/switch.html. Compress these two packages by using Zip utility into a file named "up2date_comp.zip" and replace it in the Software Library location, "Components > Oracle Components > Stage Server Up2date Component > 10.2.0.4.0 > Linux > UP2DATE_RPM".Run the following command to register the server:
#up2date --nox --register
Executing this command takes you through a series of interview screens and finally the ULN is registered to the default channel el4_<arch>_latest.
You can use the Web interface provided by ULN to subscribe to additional ULN channels. The web-interface is accessed through http://linux.oracle.com, and you can log on using the user name and password supplied at the time of registration. This process needs to be done whenever you want to subscribe the Staging Server to a new ULN channel. As of now, the ULN interface allows only to subscribe to channels that match the architecture of the machine.
To start the Stating server set up process in EM, perform these steps:
Click the Staging Server Setup link from the Patching Setup page.
Enterprise Manager displays the Linux Staging Server Setup page.
Select the Host where you want to setup the Staging server and needs to be registered to the Unbreakable Linux Network (ULN)
Specify the credentials for the staging server host to be used for patching
EM then schedules a recurring job that drives the download of latest packages from the subscribed ULN channels into the Staging Server. This job also extracts header information of the packages by running the "yum-arch" and "up2date" commands.
You can provision Oracle homes using the deployment procedures or the cloning wizard. Depending on the Oracle home type, one method might be more suitable than the other. To understand when to use which method, see My Oracle Support note 737939.1.
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.
There are various phases and steps in a deployment procedure. A phase contains steps or more phases and is associated with a target list. It defines the execution of the steps within. The types of phases are:
Rolling phase - in this type of phase, steps are executed serially across targets.
Parallel phase - in this type of phase, steps are executed in parallel across targets.
A step is an abstraction of a unit of work. For example, starting the database. It is part of a phase or is independent. The types of steps are:
Directive
Directive Step is a special type of Action Step to deploy a directive alone. This is useful when users want to store their custom scripts in the Software Library and reuse them in a Deployment Procedure.
Component (Generic or Registered)
A Generic Component Step is a special type of Action Step to deploy a Software Library Component and the associated Directive. Deployment Procedure Manager executes the directive with respect to the component. Components used for Generic Component Step generally has one directive associated with it. This association is done by selecting both the component and directive while creating the step. All directives that you associate with the component while uploading to the software library will be ignored while executing the step.
Job
Job Step is a special type of Action Step that executes a predefined job type on a target. This is used if you want to execute a job type as a part of a Deployment Procedure. You need to pass job parameters for a step.
Manual
Manual Step is that task that requires user interaction and cannot be automated. Typically, Deployment Manager would display the instructions that need to be performed by the user. After the operation is performed, the user proceeds to the next step.
Host Command
Host Command Step is a special type of Action Step that encapsulates simple host commands. This step allows the user to enter a command line or a script (multiple commands) to be executed on the target host.
You can provide values to various properties associated with a directive or component through Map Properties. You have three execution privileges: Normal, Sudo and PAM (Pluggable Authentication Modules) for Windows platform. You can choose the appropriate privilege you want by selecting the privilege from Execution privilege list box, under Execution Mode section.
The following sections describe three examples that illustrate how deployment procedures can be customized.
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.
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.
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”.
Enterprise Manager Grid Control 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:
Do a 'Create Like' of the out-of-box procedures
Select the check box 'Enable Notification', and optionally provide the 'Notification Tag Name'.
Select the statuses for which you would want the notifications to be sent from the list. For example: Success, Failure, or Action Required.
Save the procedure.
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 Oracle Enterprise Manager Grid Control. For instructions on how to configure notifications, see Section 14.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.
The deployment procedures and/or the components and directives from the Software Library are essentially stored in Procedure Archive (PAR) files. When you import or export deployment procedures, you technically import or export PAR files. These PAR files can be imported or exported using an out-of-box PARDeploy utility.
The PARDeploy utility is located at $ORACLE_HOME/bin directory, and the PAR files are located at $ORACLE_HOME/sysman/prov/paf.
The following is the usage information displayed when you run $ORACLE_HOME/bin/PARDeploy:
PARDeploy -action <deploy|view> -parFile <file> -force(optional) PARDeploy -action <deploy|view> -parFile <file> -force(optional) -ssPasswd <password> PARDeploy -action <deploy|view> -parDir <dir> -force(optional) PARDeploy -action export -guid <procedure guid> -file <file> -displayName <name> -description <desc> -metadataOnly(optional) PARDeploy -check PARDeploy -help
Additionally, the following options are provided:
| Option | Description |
|---|---|
|
-force |
Force the swlib entities to be created/reuploaded, if already present creates a new revision. |
|
-check |
Check if Software Library is configured. |
|
-file <file> |
PAR file. |
|
-action <deploy|view|export> |
Deploy, view or export par file. |
|
-verbose |
Verbose mode. |
|
-help |
Display this help message. |
|
-displayName <displayName> |
PAR file name. |
|
-parDir <dir> |
Directory where par files are located. |
|
-metadataOnly |
Flag for metadata-only exports. |
|
-guid <guid> |
Procedure GUID to export. To export mulitiple procedures provide the GUIDs separated by "," |
|
-parFile <file> |
Path of par file. |
|
-description <description> |
PAR file description. |
|
-ssPasswd <secretStorePassword> |
This is optional. If used with -action export; if any of the exported Software Library entity contains a secret property, an Oracle Wallet is created to store the value of the secret property. Oracle Wallet is created using the specified password. You are prompted to enter a password if -ssPasswd switch is used and if password is not supplied as a command line argument. You must use the same password while importing the PAR file in a new repository. If used with -action <deploy|view>; if the PAR file contains any password protected Oracle Wallet (that stores an entity's secret property values), then this parameter is required to open the store. You are prompted to enter a password if -ssPasswd switch is used and password is not specified as a command line argument. |
Note:
In the case of multiple OMS environments, you need run the PARdeploy utility only once to deploy any PAR files or to perform other related operations.Before running the PARDeploy utility to import or export PAR files, ensure that the $ORACLE_HOME environment variable is set to the Oracle home directory of the OMS and the Software Library path is configured.
To check software library, run the following command:
$ORACLE_HOME/bin/PARDeploy -check
To deploy a specific PAR file, run the following command:
$ORACLE_HOME/bin/PARDeploy -action deploy -parFile $ORACLE_HOME/sysman/prov/paf/<par_file_name> -force
For example:
$ORACLE_HOME/bin/PARDeploy -action deploy -parFile $ORACLE_HOME/sysman/prov/paf/asprov.par -force
To deploy all of the PAR files in a directory:
$ORACLE_HOME/bin/PARDeploy -action deploy -parDir $ORACLE_HOME/sysman/prov/paf/ -force
To export a deployment procedure, you must first create a PAR file that contains that particular deployment procedure. Each deployment procedure has a unique GUID. Before running the PARDeploy tool to export it, obtain the GUID of the deployment procedure.
To obtain the GUID of the deployment procedure:
In Grid Control, click the Deployments tab.
On the Deployments page, from the Deployment Procedure Manager section, click Deployment Procedures.
Deployment Procedure Manager page, in the Procedures table, click the deployment procedure you want to export.
On the View Procedure page, note the URL of the page from the address bar of the browser.
The format of the URL should be similar to this:
http://<OMS host>:<port>/em/console/paf/procedureView?guid=<value of GUID>
To create a PAR file that contains this deployment procedure, run the PARDeploy utility with the export option as the action, and quote the GUID of the deployment procedure you want to export.
$ORACLE_HOME/bin/PARDeploy -action export -guid <GUID> -file exportedDP.par -displayName "User exported DP" -description "<description>"
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 is created in the directory where you ran the command. You can then import this PAR file to another OMS.
To export multiple deployment procedures or PAR files, specify the GUIDs separated by a comma.
Note:
When a procedure is exported using PARDeploy, any directives or components referred by the procedure are also 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.To import PAR files or deploy them to an OMS, you can use the PARDeploy utility. Alternatively, you can also log in to the second Enterprise Manager Grid Control, navigate to the Deployment Procedure Manager page, and click Upload to upload the PAR file.
When importing or exporting components and/or directives that contain properties with secret values, you must use the -ssPasswd command and provide the secrete store password to create Oracle Wallet. This helps in securely storing and retrieving these properties. For more informationabout the -ssPasswd command, see Table 11-2, "PARDeploy Options".
Enterprise Manager Grid Control allows you to run deployment procedures using authentication utilities such as SUDO, PowerBroker, and Privilege Delegation.
While SUDO and PowerBroker are third-party utilities supported in Enterprise Manager Grid Control, Privilege Delegation is proprietary to Oracle. Privilege Delegation is a framework that allows you to use either SUDO or PowerBroker to perform an activity with the privileges of another user. Privilege Delegation can use either SUDO or PowerBroker, but not both, and the settings are only for a single host. Therefore, if a host is set up with pbrun, then it will use only pbrun.
The support for SUDO and PowerBroker is offered in Enterprise Manager 10g Grid Control Release 4 (10.2.0.4) or lower, but the support for Privilege Delegation is offered only in Enterprise Manager 10g Grid Control Release 5 (10.2.0.5) or higher.
For more information about Privilege Delegation, see the section on Configuring Privilege Delegation Providers in the chapter Additional Configuration Tasks. You can also find information about Privilege Delegation in the online help system provided in Enterprise Manager Grid Control.
You can use any of these utilities to run deployment procedures in Enterprise Manager Grid Control. However, some limitations involved in using SUDO and PowerBroker are:
While SUDO is supported in a password-protected mode, PowerBroker is not. Therefore, every time you use PowerBroker, you will have to run them without a password.
You have to configure SUDO and PowerBroker settings every time you edit a deployment procedure. You cannot create a standard template with these settings that can be reused wherever required.
You can use SUDO and PowerBroker settings only for deployment procedures, and not for jobs that can be run for performing critical tasks on hosts.
Privilege Delegation, a framework that combines SUDO and PowerBroker, offers the same functionality with the following advantages:
You have the flexibility to use either SUDO or PowerBroker within the same framework.
Using the framework, you can now run PowerBroker in a password-protected mode. This offers more security.
You can create a template with these Privilege Delegation settings and reuse it for multiple hosts. This not only allows you to standardize Privilege Delegation setting across your enterprise, but also facilitates the process of configuring Privilege Delegation Settings. It simplifies the Privilege Delegation setting management as well.
You can use the Privilege Delegation settings not only for deployment procedures, but also for jobs in Enterprise Manager Grid Control.
While SUDO and PowerBroker do not require any prerequisite templates to be created, Privilege Delegation does. Therefore, before editing a deployment procedure, create a Privilege Delegation template with the required settings for a host. To do so, follow these steps:
In Grid Control, click Setup from the top-right corner.
On the Overview of Setup page, from the vertical menu, click Manage Privilege Delegation Settings.
On the Manage Privilege Delegation Settings page, from the Related Links section, click Manage Privilege Delegation Settings Template.
On the Manage Privilege Delegation Settings Templates page, from the Create list, select a privilege delgation type, either Sudo or PowerBroker, and click Go.
On the Create '<delegation type>' Setting Template page, provide the template name and the command to run (for PowerBroker, you can optionally provide the password prompt), and click Save.
On the Manage Privilege Delegation Setting Templates page, select the template you created and click Apply.
On the Apply '<delegation type>' Setting: New page, click Add Targets to apply the privilege delegation template settings to selected hosts, and click Apply.
Note:
If you do not apply the privilege delegation template to a target, and if you configure a step in the deployment procedure to run in Privilege Delegation mode, then the deployment procedure for that target runs the step in normal mode instead.While editing a deployment procedure, you can choose to run any step using SUDO, PowerBroker, or Privilege Delegation.
For SUDO and PowerBroker, you can specify the SUDO and PowerBroker commands to run, and also set environment variables and the preferred command interpreter for them (Figure 11-1).
For Privilege Delegation, you can specify the user and the profile that the step must run as (Figure 11-2).
For each step, from the Run Privilege column, you can select either SUDO, PAM, or Privilege Delegation (Figure 11-3).
If you select SUDO or PAM, then in the Run Privilege Command/Privilege Delegation column, specify the Run As command. If you select Privilege Delegation, then specify the Run As value in the first text box and the Profile value in the second text box.
Note:
If you select SUDO or PAM, and leave the Run Privilege Command column blank, then the commands as set in the SUDO Command and PAM Command fields (Figure 11-1) are used. However, if you want some steps to override these globally declared commands, then in the Run Privilege Command column for that step, specify the commands that need to be used instead. If these settings are not made, then the Run As and Profile values specified along with preferred credential are used.See Also:
You can access My Oracle Support note 603108.1 to view use cases that describe how SUDO and PAM settings can be applied.For file transfer-based job steps, you can apply the Privilege Delegation settings while editing that step. For example, one of the steps in the One Click Extend Cluster Database deployment procedure is Copy Archives. This is a file transfer-based job step for which you can apply the Privilege Delegation settings. To do so, you can click the step name and on the Map Parameters page, in the Run Mode section, from the Run Privilege for Source Target list and Run Privilege for Destination Target list, select Privilege Delegation. Then provide the Run As value and profile that must be used.
Note:
For configuration collection-based job step, you can NOT apply any Privilege Delegation settings. For example, one of the steps in the One Click Extend Cluster Database deployment procedure is Refresh Host Configuration. This is a configuration collection-based step for which Privilege Delegation settings cannot be applied.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.
Database Specific:
oraHome - Directory of the ORACLE_HOME
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
runRootScript - Yes/no indicating whether root script needs to be run
Automated Storage Management Specific:
asmTargetHome - Selected ASM target ORACLE_HOME
asmIntanceName - ASM instance running from the ORACLE_HOME
asminstances - ASM instances running from the ORACLE_HOME
Real Application Cluster Specific:
racLocalInstanceNames - All local RAC Database instances running out of the ORACLE_HOME
racLocalInstanceTgtNames - All local RAC Database target names running out of the ORACLE_HOME
racLocalInstanceHomes - All ORACLE_HOMEs running the RAC database instances locally
racLocalInstanceSids - sids of the local RAC instances running in the ORACLE_HOME
Clusterware Specific:
nodeName - Name of CRS node on which the RAC instance being patched is running
crsName - Cluster name
Application Server Specific:
oracleSid - Value of SID that may be present in an AS ORACLE_HOME
Global:
isPatchset - Yes/No specifying whether patchset is being applied to the ORACLE_HOME
stageDir - The staging directory to use provided like %oracle_home%....
replacedStageDir - The absolute staging location of patches
patchIDs - List of patch ids selected
patchSrcs - Indicating whether the patches came from My Oracle Support or software library
patchData – Uniform resource Names (URNs) of the patches
patchReleases - Corresponding release of the patches
targetVersion - Version of the target being patched
The following section describes basic EMCLI concepts and requirements for using EMCLI to run deployment procedures.
Before using EMCLI to run deployment procedures, familiarize yourself with the following EMCLI concepts:
RuntimeData xml
Runtime data response file (known as RuntimeData xml) is required to execute 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 User Interface to execute 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. Refer to Appendix A, "Out-Of-Box Runtime Data Templates" for GUID of out-of-box procedures.
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 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 executes the procedure.
You must ensure that the following requirements are met prior to using EMCLI to execute deployment procedures:
EMCLI client must be set up. Please refer to the Installation and Configuration section of the Enterprise Manager Command Line Interface Guide for configuring the EMCLI client. The document is available at:
Targets that will be supplied to the deployment procedures are managed by Management Agents of version 10.2.0.2 or higher.
If you are using Enterprise Manager 10g Grid Control Release 3 (10.2.0.3), then download and apply the My Oracle Support patch - 5890474 on 10.2.0.3 OMS, 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.
If you are using Enterprise Manager 10g Grid Control Release 3 (10.2.0.3), then 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, please be sure that the management agents on the nodes are cluster agents. Refer to Section 11.8.7, "Converting Standalone Agents to Cluster Agents" for information about converting standalone agents to cluster agents.
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. Please refer to Section 11.8.6, "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 process to use EMCLI to execute deployment procedures is depicted in Figure 11-5.
Figure 11-5 EMCLI Process to Execute Deployment Procedures
There are four required actions to execute deployment procedures. Those steps are described below:
Step 1: Find the GUID of the procedure to be executed using EMCLI. This is a one-time activity.
Step 2: Obtain the RuntimeData xml or RuntimeData template for the procedure that needs to be executed. 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 execute 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
Note:
GUIDs and procedure types for the out-of-box procedures can be found in Appendix A, "Out-Of-Box Runtime Data Templates".For out-of-box procedures, RuntimeData Templates are located in the emcli/samples directory in the Oracle Management Service (OMS) oracle home. Information about out-of-box procedures and their associated out-of-box templates can be found in Appendix A, "Out-Of-Box Runtime Data Templates".
For customized procedures you have 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 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.
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 double quotes 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:
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 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 11.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.
In 10.2.0.4, new elements have been added in RuntimeData xml to support multiple patches. The new elements are:
patchesToBeApplied - Enter a 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"/>
Note:
If you are using Enterprise Manager 10g Grid Control Release 3 (10.2.0.3), first download and apply the My Oracle Support 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 executed 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 executed.
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 executed script.
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 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 executed script. Also, the deployment procedure is scheduled to run immediately in the time zone of the OMS.
Note:
The following sections describe various use cases for EMCLI-based provisioning and patching procedures. You must first download and apply the My Oracle Support patch - 5890474 on 10.2.0.3 OMS, 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 please be sure that the management agents on the nodes are cluster agents. Please refer to Section 11.8.7, "Converting Standalone Agents to Cluster Agents" to converting standalone agents to cluster 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 Runtime Data 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 Runtime Data 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 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 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 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 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.
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 Runtime Data 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 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 Runtime Data 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 Runtime Data 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 Runtime Data 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 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 Enterprise Manager Command Line Interface Guide available at:
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
For using the RAC-related procedures, you must have cluster agents on the cluster nodes. The standalone agents on a cluster can be converted to cluster agents in the following ways:
Before following these steps, meet the prerequisites for Agent Installation as described in the Enterprise Manager Grid Control Installation and Basic Configuration Guide available at:
http://www.oracle.com/technology/documentation/oem.html
Converting standalone agents to cluster agents using Oracle Enterprise Manager:
Log in to Oracle Enterprise Manager
Navigate to the Deployments tab, click on Install Agent, and then click Fresh Install
On the Agent Deploy application page that appears:
Choose the default selection for "Source Shiphome Directory"
Select the appropriate version for the already installed standalone agents. Please note that in order to use deployment procedures these agents should be at least of version 10.2.0.2.
Choose the required platform.
Provide the list of hosts that form a part of the cluster.
Check the "Cluster Install" check box.
Use the "Populate Defaults" button to fill values for "Cluster Node List" parameter.
Provide the cluster name of the existing cluster.
Provide the host credentials and the agent installation base directory for the nodes that form the cluster.
Supply any other optional parameters and click on the continue button.
Converting the standalone agents using the agentca utility:
Invoke the agentca using the -f and -c option from the <Agent Oracle home>/bin directory of the standalone agent on each cluster node. Also use the -n option to specify the name of the cluster. For example:
<Agent Oracle Home>/bin/agentca -f -n <cluster name> -c "{<comma separated cluster node list like node1, node 2…>}"
In case ssh connection is setup between the cluster nodes, then run the following command from <Agent Oracle Home>/oui/bin directory on one of the nodes:
./runInstaller -updateNodelist ORACLE_HOME=<Agent Oracle Home> "CLUSTER_NODES={<comma separated list of nodes in the cluster>}"
In case ssh connection is not setup between the nodes then run the following command from <Agent Oracle Home>/oui/bin directory on each node:
./runInstaller -updateNodelist ORACLE_HOME=< Agent Oracle Home > "CLUSTER_NODES={< comma separated list of nodes in the cluster >}" -local
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
The following section discusses known issues surrounding deployment procedures and describes how to troubleshoot problems that may arise when using deployment procedures.
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.
The following are some troubleshooting scenarious related to deployment procedures.
If any deployment procedure 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. For faster resolution of any deployment procedure-related issues, plan to provide these files to support when you create a support request.
OMS Log Files:
Generic EM trace file - $OMS ORACLE_HOME /sysman/log/emoms.trc
PAF logs - $OMS ORACLE_HOME/ sysman/log/pafLogs/
For specific deployment procedure instance - $OMS_ORACLE_HOME/sysman/log/pafLogs/<name>_<instance_guid>.log
Agent Log Files
$Agent_ORACLE_HOME/sysma/logs/emagent.nohup
$Agent_ORACLE_HOME/sysma/logs/emagent.trc
Optionally, to capture more details you can make the logging finer. Follow the steps below to re-set the log level and capture the logs mentioned above. (Note: Its advised to archive the old logs and have a fresh run after resetting the log level to capture the fresh logs.)
For OMS:
“$ORACLE_HOME/sysman/config/emomslogging.properties”file@ log4j.rootCategory=....
Replace the value of the above parameter to 'DEBUG'. Restart the OMS for the changes to take effect:
OMS Home/bin/emctl stop oms
OMS Home/bin/emctl start oms
For Agent:
AGENT_HOME/sysman/config/emd.properties
tracelevel.Dispatcherr=DEBUG (Writes to emagent.nohup)
tracelevel.command=DEBUG (Writes to emagent.trc)
Re-load the agent: $Agent_ORACLE_HOME/bin/emctl reload agent
The settings above are to be set only when you want additional details and when the logs do not have sufficient information to debug the issue. Make sure to set the debug level back to the original levels after reproducing the issue. While reporting issues with deployment procedures, associate the tar/zip of the logs from both the above locations with the SR.
|
 Copyright © 2003, 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|