B Using emctl partool Utility

This appendix introduces you to the emctl partool utility and explains how you can use it to perform critical tasks such as exporting Deployment Procedures, importing PAR files, and so on. In particular, this appendix covers the following:

Overview of Provisioning Archive (PAR) Files
Overview of emctl partool Utility
Checking Oracle Software Library
Exporting Deployment Procedures
Importing PAR Files

Overview of Provisioning Archive (PAR) Files

Provisioning Archive (PAR) files are archive files that contain one of the following:

Deployment Procedures and the associated Oracle Software Library (Software Library) entities, such as components, directives, images, and so on.
Only the Software Library entities, such as components, directives, images, and so on.

When you install Enterprise Manager Grid Control, by default, all out-of-box Deployment Procedures are installed in the form of Provisioning Archive (PAR) files at the following location:

$ORACLE_HOME/sysman/prov/paf

For example, all application server-related Deployment Procedures are stored in asprov.par file.

Note:

The PAR file for Oracle VM Management-specific Deployment Procedures is available in the following location. Here, <ORACLE_HOME> is the Oracle home of the OMS:

$<ORACLE_HOME>/sysman/admin/deploymentprocedures

To use the Deployment Procedures in Enterprise Manager Grid Control, you need not import or export these PAR files. The only prerequisite is to set up Oracle Software Library (Software Library). Once you set up the Software Library, Enterprise Manager Grid Control will automatically extract the contents of these default PAR files and configure them so that you can start using the Deployment Procedures from the Grid Control console. When importing or exporting components and/or directives that contain properties with secret values, password will need to be provided to create Oracle Wallet to securely store/retrieve these properties.

Overview of emctl partool Utility

Over a period of time, you might have customized some Deployment Procedures, and you might want to reuse them in another instance of Enterprise Manager Grid Control. Under such circumstances, you might want to export the customized Deployment Procedures from one instance of Enterprise Manager Grid Control, and deploy them to another instance of Enterprise Manager Grid Control.

The emctl partool utility is a tool offered by Enterprise Manager Grid Control that helps you perform these functions using the command line interface. Essentially, the emctl partool utility helps you:

Export Deployment Procedures and its associated components and directives as PAR files
Import PAR files to the same instance or any other instance of Enterprise Manager Grid Control

The emctl partool utility is located in the $ORACLE_HOME/bin directory, and the out-of-box PAR files are located at $ORACLE_HOME/sysman/prov/paf.

Note:

The PAR file for Oracle VM Management-specific Deployment Procedures is available in the following location. Here, <ORACLE_HOME> is the Oracle home of the OMS:

$<ORACLE_HOME>/sysman/admin/deploymentprocedures

The following is the usage information displayed when you run $ORACLE_HOME/bin/emctl partool:

emctl partool <deploy|view> -parFile <file> -force(optional)
emctl partool <deploy|view> -parFile <file> -force(optional) -ssPasswd <password>
emctl partool <deploy|view> -parDir <dir> -force(optional)
emctl partool export -guid <procedure guid> -file <file>  -displayName <name> -description <desc> -metadataOnly(optional)
emctl partool -check
emctl partool -help

Note:

After you successfully deploy the PAR files, restart the OMS.

Table B-1 describes the additional options that can be used with the emctl partool utility.

Table B-1 emctl partool Options

Option	Description
-repPasswd <repPassword>	Indicates the repository password. User will be prompted for the repository password if -repPasswd is not specified on the command line. Note: Providing a password on the command line is insecure and should be avoided in a production environment.
-force	Forces the Software Library entities to be created or uploaded again. If already present, it creates a new revision.
-check	Checks whether the Software Library is configured.
-file <file>	Represents the PAR file.
-action <deploy\|view\|export>	Deploys, views, or exports PAR files.
-verbose	Indicates verbose mode.
-help	Displays Help information.
-displayName <displayName>	Indicates PAR file name.
-parDir <dir>	Directory where the PAR files are located.
-metadataOnly	Flag for metadata-only exports.
-guid <guid>	Procedure GUID to export. To export multiple procedures, provide the GUIDs separated by ","
-parFile <file>	Path to the 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.

Checking Oracle Software Library

Before running the emctl partool utility to export or import PAR files, ensure that the $ORACLE_HOME environment variable is set to the Oracle home directory of Oracle Management Service (OMS) and a Software Library path is configured.

To check the Software Library, run the following command:

$ORACLE_HOME/bin/emctl partool check

Exporting Deployment Procedures

To export Deployment Procedures, you must first obtain the GUID of those Deployment Procedures, and then run the emctl partool utility to create a PAR file. This section explains the following:

Obtaining Deployment Procedure's GUID
Creating PAR File

Note:

If you want to export custom Deployment Procedures (PAR files) from Enterprise Manager 10g Grid Control Release 5 (10.2.0.5) and import them to Enterprise Manager 11g Grid Control Release 1 (11.1.0.0), then refer to the My Oracle Support note 1110052.1.

Obtaining Deployment Procedure's GUID

To obtain the GUID of a Deployment Procedure using Enterprise Manager Grid Control, follow these steps:

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 obtain the GUID of a Deployment Procedure using Enterprise Manager Command Line Interface (EM CLI), run the get_procedures verb. This command displays information such as GUID, Procedure Type, Name, Version, and Created By.

emcli get_procedures [-type={procedure type}]

[ ] denotes that the parameter is optional. If you do not provide this paramaeter, then the verb displays information about all the Deployment Procedures. If you provide this parameter, then the verb displays information only about the procedure type you have specified.

Creating PAR File

To create a PAR file that contains one or more Deployment Procedures, run the emctl partool utility with the export option as the action, and quote the GUIDs of the Deployment Procedures you want to export. Ensure that you separate the GUIDs by a comma.

$ORACLE_HOME/bin/emctl partool 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/emctl partool 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 the same instance of Enterprise Manager Grid Control or another instance, multiple times.

To export multiple deployment procedures, separate the GUIDs with commas as follows:

$ORACLE_HOME/bin/emctl partool export -guid "06B62B6ED5DA20BCE040578C850862A7,0C96E96D9818BC5FE040578C8508620F,09AEFF331025AAD0EE40578C85FB5772" -file $ENV{T_WORK}/tvmgf_partool_multi_dp.par -displayName "partool multi dp test" -description "partool multi dp test description" -repPasswd sysman

Note:

When a procedure is exported using emctl partool, 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 emctl partool.

Note:

Importing PAR Files

You can import PAR files using the command line interface or the graphical user interface offered by Enterprise Manager Grid Control, that is, the console. This section explains the following:

Importing Using Command Line Interface
Importing Using Grid Control Console

Note:

If you want to export custom Deployment Procedures (PAR files) from Enterprise Manager 10g Grid Control Release 5 (10.2.0.5) and import them to Enterprise Manager 11g Grid Control Release 1 (11.1.0.0), then refer to the My Oracle Support note 1110052.1.
After you successfully import the PAR files, restart the OMS.

Importing Using Command Line Interface

This section covers the following:

Importing Specific PAR File
Importing All PAR Files

Note:

If you want to export custom Deployment Procedures (PAR files) from Enterprise Manager 10g Grid Control Release 5 (10.2.0.5) and import them to Enterprise Manager 11g Grid Control Release 1 (11.1.0.0), then refer to the My Oracle Support note 1110052.1.
After you successfully import the PAR files, restart the OMS.

Importing Specific PAR File

To import or deploy a specific PAR file, run the following command:

$ORACLE_HOME/bin/emctl partool deploy -parFile $ORACLE_HOME/sysman/prov/paf/<par_file_name> -force

For example:

$ORACLE_HOME/bin/emctl partool deploy -parFile $ORACLE_HOME/sysman/prov/paf/asprov.par -force

Note:

If you have multiple OMSes in your environment, then you need run the emctl partool utility only once to deploy any PAR files or to perform other related operations.

Importing All PAR Files

To import or deploy all the PAR files in a directory, run the following command:

$ORACLE_HOME/bin/emctl partool deploy -parDir $ORACLE_HOME/sysman/prov/paf/ -force

Importing Using Grid Control Console

To import PAR files or deploy them to an OMS, you can use the emctl partool utility. Alternatively, you can also log in to Enterprise Manager Grid Control, navigate to the Deployment Procedure Manager page, and click Upload to upload a PAR file.

If a PAR file is being deployed using Grid Control, the SQL files in the PAR file will not be executed.

Note:

When importing or exporting components and/or directives that contain properties with secret values, you must use the -ssPasswd command and provide the secret store password to create Oracle Wallet. This ensures that the properties with secret values are securely stored using an Oracle Wallet, and can be accessed while importing with only the Oracle Wallet password.

For more information about the -ssPasswd command, see Table B-1, "emctl partool Options". For more information about importing and exporting Software Library entities, see Exporting and Importing Entities Across Oracle Enterprise Manager Deployments.

Note:

If you want to export custom Deployment Procedures (PAR files) from Enterprise Manager 10g Grid Control Release 5 (10.2.0.5) and import them to Enterprise Manager 11g Grid Control Release 1 (11.1.0.0), then refer to the My Oracle Support note 1110052.1.
After you successfully import the PAR files, restart the OMS.