This chapter contains the following sections:
Introduction to Validating, Packaging, and Deploying the Plug-in
Importing and Deploying the Plug-in Archive into Enterprise Manager
Updating Deployed Metadata Files Using the Metadata Registration Service (MRS)
As a plug-in developer, you are responsible for the following steps within the validation, packaging, and deployment process:
Create the staging directory (plugin_stage):
The staging directory structure defines the location of files as they will be deployed to Oracle Management Service and Management Agents.
For more information, see Section 14.2, "Staging the Plug-in".
Validate the plug-in.
Use the empdk validate_plugin command to validate the content of the plug-in once you have designed and developed it. This command verifies that the XML metadata files are compliant.
For more information, see Section 14.3, "Validating the Plug-in".
Create the Oracle Plug-in Archive (OPAR) file.
The plug-in archive is the standard way of distributing the plug-in for importing and deploying the plug-in across different installations of the Enterprise Manager Cloud Control.
For more information, see Section 14.4, "Creating the Plug-in Archive".
Import the OPAR into Enterprise Manager.
Use the emcli import_update command to import the plug-in into Enterprise Manager.
For more information, see Section 14.5, "Importing and Deploying the Plug-in Archive into Enterprise Manager".
Deploy the plug-in.
You must deploy a plug-in on the Oracle Management Service before it is used for monitoring targets.
For more information, see Section 14.5.3, "Deploying the Plug-in on Oracle Management Service (OMS)".
Add target instances for the deployed plug-in to monitor.
For more information, see Section 14.6, "Adding a Target Instance".
Use the Metadata Registration Service (MRS) to deploy updated metadata files.
The MRS allows you to upload one or more updated metadata files to the Oracle Management Service and Management Agents where your plug-in is deployed. The MRS registers the updated metadata files with Enterprise Manager, and overwrites the existing metadata with your updates.
For more information, see Section 14.7, "Updating Deployed Metadata Files Using the Metadata Registration Service (MRS)".
After you have created the plug-in files, the next step is to stage the plug-in in preparation for validation and packaging. The staging directory structure defines the location of files as they will be deployed to Oracle Management Service and Management Agents.
The following example provides an example of the staging directory structure and Table 14-1 describes the archive directory structure. Files are placed in the archive based on whether they are deployed to Oracle Management Service, Management Agents, or both. When the plug-in is deployed to an OMS instance or a Management Agent, the requisite files are copied to their respective directory locations.
Example: Plug-in Directory Structure
plugin_stage/ | plugin.xml agent/ | plugin_registry.xml default_collection/ | target_type.xml metadata/ | target_type.xml scripts/ | scripts oms/ | metadata/ | default_collection/ | target_type.xml derivedAssoc/ | derivedAssoc_rule.xml discovery/ | discovery.xml gccompliance/ | ComplianceContent_name.xml jobTypes/ | job_type.xml mpcui/ | mpcui.xml reports/ | report.xml snapshotlive/ | target-type_ecmdef.xml targetType/ | target_type.xml discovery/ | discovery scripts
Note:
Use of the specified subdirectory names within the archive are not required, but are recommended by Oracle.Table 14-1 File Locations in Plug-in Archive Structure
| File | Directory | Notes |
|---|---|---|
|
|
|
Required. This file defines generic plug-in metadata that is deployed to Oracle Management Service. Place it at the root level within the archive structure.For more information, see Section 2.3.1, "Creating the plugin.xml File". |
|
|
Required. This file defines metadata describing the plug-in used by the Management Agent. It must be placed at the top level of the |
|
|
|
Required. This file defines metrics to be collected or computed for the target type. An identical copy of this file must be placed in both the |
|
|
|
Required. This file defines metric collection parameters such as metric data collection frequency and default metric alert thresholds. An identical copy of this file must be placed in both the Note: Oracle recommends that you name the default collections metadata file with the same file name as the target type metadata file. |
|
|
|
Optional. Defines configuration data collection. For more information, see Section 7.3.1, "Defining Configuration Collection Tables". |
|
|
|
Optional. Place all job type definition files in the |
|
|
|
Optional. Put report definition files in the |
|
|
|
Optional. Place the metadata file that defines the association derivation rules (or set of rules) in this directory. For more information, see Chapter 11, "Using Derived Associations". |
|
|
|
Optional. ComplianceContent_name.xml contains references to compliance standards, rules, and frameworks. This directory can contain compliance rule, compliance standard, and compliance framework XML files. For more information, see Section 13.8, "Packaging Compliance XML". |
|
|
|
Optional. Place all Data Loading Format (DLF) map entry (DLF) files associated with compliance rules or standards definitions in this directory. |
|
|
|
Optional. Place all management user interface metadata files in this directory. For more information, see Chapter 9, "Defining a Management User Interface". |
|
|
|
Optional. Place discovery metadata files in this location. For more information, see Section 12.4, "Packaging Discovery XML and Discovery Content". |
|
|
discovery script file(s) |
|
Optional. Place the Perl scripts and JAR files (if any) that are required to perform automatic discovery in this location. For more information, see Section 12.4, "Packaging Discovery XML and Discovery Content". |
|
script file(s) |
|
Optional. Put any scripts that will be deployed to Management Agents, such as metric collection scripts invoked by fetchlets, in this location. Use of the |
To specify customized file permissions for scripts packaged under the plug-in directory:
Create the following text file in the relevant directory (oms, agent, or discovery):
plugin_stage/oms/file_permissions.txt plugin_stage/agent/file_permissions.txt plugin_stage/discovery/file_permissions.txt
Specify the permissions for multiple files, each in one row. The format of the text file is similar to the following:
file_name:file_permission_number
or
file_pattern:file_permission_number
In these formats:
file_name represents the name of the file that will have permissions changed
file_pattern represents a pattern that the script will search for, such as a certain file type or all file names containing the pattern. Then all matched files will have permissions changed.
file_permission_number represents the UNIX permission description of the file. This is the new permissions value of the matched files.
For example, to change the permissions of all occurrences of example1.sh to 655 within the plugin_stage/oms directory, add the following entry to the plugin_stage/oms/file_permissions.txt file:
example1.sh:655
To change the permissions of all script files (of file type *.sh) to 655 within the plugin_stage/discovery directory, add the following entry to the plugin_stage/discovery/file_permissions.txt file:
*.sh:655
To change the permissions of all files beginning with abc to 655 within the plugin_stage/agent directory, add the following entry to the plugin_stage/agent/file_permissions.txt file:
abc*:655
Save and close the file_permissions.txt file. These permissions are read and retained during plug-in creation with the OPAR and later used during the plug-in software installation. For more information about plug-in creation, see Section 14.4, "Creating the Plug-in Archive".
Validate the plug-in throughout the development cycle, and before packaging the plug-in. Use the empdk validate_plugin command to validate the content of the plug-in after you have designed and developed it to verify that the XML metadata files are compliant. The tool is run against the specified plug-in staging directory and generates a report of any violations found. Specify the format of the generated report using the -format option.
The following example provides the command usage.
Example: empdk validate_plugin Command Usage
empdk validate_plugin -stage_dir staging directory [-tmp_dir temporary working location] [-out_dir output directory] [-format (html|text|xml)] [-conn_desc] - not used by external developers [-repos_user Enterprise Manager repository owner] [-debug [file to output debug information to]]
The following example validates the plug-in source files in the specified staging directory, and generates the validation report as a text file in the current working directory:
edk\bin>empdk validate_plugin -stage_dir C:\plugin_staging -format text
Table 14-2 provides the options that can be used to validate the plug-in.
Table 14-2 Options for Validating the Plug-in
| Option | Description |
|---|---|
|
|
Specify a temporary location to extract the plug-in files into. If not specified, it defaults to the current directory. |
|
|
The directory the validation report file will generated into. If not specified, the report file will be generated in the current working directory. |
|
|
Specify a file name where you want to store the debug information. If not specified, the default log file (validateplugin.logtime) will be created in the out directory and will store warning and error message only. If specified, then it will store all the debugging information to that log file |
|
|
The format the validation report will be generated in. If not specified, the report will be generated as a text file. |
After you have created the plug-in stage directory and validated the plug-in, the next step is to create an Oracle Plug-in Archive (OPAR) file. The OPAR file plays an important role at various stages of the plug-in lifecycle. It serves the following:
The plug-in archive is the standard way of distributing the plug-in for importing and deploying the plug-in across different installations of the Enterprise Manager Cloud Control.
You must test the plug-in being developed on an Enterprise Manager Cloud Control installation.
A plug-in is created by adding the files previously discussed to an OPAR using the Enterprise Manager Extensibility Development Kit (EDK). For more information about the EDK, see the Oracle Enterprise Manager Cloud Control Extensibility Programmer's Guide.
To create an OPAR, at the command prompt, enter the empdk create_plugin command. For more information about the create_plugin verb, see the command line help
The empdk create_plugin command syntax is as follows:
empdk create_plugin -stage_dir staging dir -conn_desc repository_connection_string -repos_user username [-repos_password repos_password] -out_dir output_directory [-debug] [-force]
For example:
edk\bin>empdk create_plugin -stage_dir C:\pluginstagdir -conn_desc myhost.us.example.com:25055:$ORACLE_SID -repos_user sysman -out_dir /tmp/plugins
Table 14-3 provides the options that can be used to create an OPAR:
Table 14-3 Options for Creating an OPAR
| Option | Description |
|---|---|
|
|
This option enables the command to create a temporary directory while executing. You can specify the path you want to use for this by providing a value following the option. Specify an existing directory or else you will receive an error. If not specified, then the out directory will be used for temporary location. If no out directory is specified, the current directory is the default. |
|
|
The directory in which the plug-in archive (*.opar) file will be created. If not specified, the plug-in archive will be created in the current directory. |
|
|
Specify a file name where you want to store the debug information.If not specified, the default log file (createplugin.logtime) will be created in the out directory and will store only warning and error messages. If specified, then it will store all the debugging information to that log file. This debugging information can be used to identify issues you may encounter while creating a plug-in. You can append the log created when you are filing a support request for a create plug-in related issue. |
|
|
If the out directory contains an OPAR with the same name, then you will be prompted to specify whether to overwrite the existing OPAR. If provided, it will automatically overwrite the existing OPAR. This is disabled by default. |
|
|
The connection descriptor that will connect to the Management Repository that the plug-in metadata will be written to when the plug-in is imported into Enterprise Manager. Specify the connection descriptor using the following syntax: For example: myhost.us.example.com:25055:$ORACLE_SID |
|
|
The user to connect to the Management Repository. |
If the command runs successfully, then a plugin_version.plugin_id.opar archive will be created in the directory where you ran this command.
If the command fails, an appropriate error message will be displayed. The parameters passed to the commands vary from user to user and across systems where the plug-in is being created.
Some common mistakes while trying to create the plug-in archive are:
If the path to the staging directory is entered incorrectly, then it raises a File not found or an Input not found exception.
The empdk command not found exception will be shown if you have not changed your current directory to the expanded EDK directory.
If the disk where you are trying to create the OPAR has inadequate memory, then an Input/Output-related exception might occur.
Once you have the plug-in archive ready with your *.opar file, you must import the plug-in into Enterprise Manager. Importing ensures that the content that you have created and packaged in the plug-in is available within Enterprise Manager.
Note:
You must first import the plug-in before it can be deployed onto Enterprise Manager.The following prerequisites are met before importing the plug-in.
Create a folder in the system where Enterprise Manger is installed. For example, /net/hostname/scratch/aime/swlib1.
From the console, select Enterprise, then Provisioning and Patching, and then Software Library.
Click Actions, then Administration.
Click Add.
In the pop up window, enter a name and location. For example, swlib1 and /net/hostname/scratch/aime/swlib1. This should be the folder that you created in step 1.
Wait for the processing to finish.
You will use the Enterprise Manager Command Line Utility, or EM CLI, to import the plug-in archive for deployment to Enterprise Manager.
A page is provided in the Cloud Control console with instructions on setting up EM CLI. Access the page at the following URL:
https://em_host:em_port/em/console/emcli/download
For example:
https://emserver.test.com:7799/em/console/emcli/download
After setting up EM CLI, synchronize the EM CLI client with an Oracle Management Service (OMS):
emcli sync
After synchronization, all verbs and associated command line help available to this OMS become available at the EM CLI client.
Once packaged, the plug-in must be imported into Enterprise Manager Cloud Control using the emcli import_update command. You have two options depending on where EM CLI is installed:
If EM CLI is on the same system as the system where you created the plug-in archive (*.opar file), then run the following command.
emcli import_update -file=”<path to *.opar file you created>” -omslocal
The -omslocal flag indicates that the plug-in archive is on the same system where you are running this command and the path exists on this system.
For example:
emcli import_update -file=/tmp/sample_plugin.opar -omslocal
If you are running EM CLI on a different system than the system where you created the plug-in archive (*.opar file), then run the following command:
emcli import_update
-file=”path to the .opar file”
-host="host name of plug-in host"
-credential_name="credential for plug-in host"
-credential_owner="credential owner on the plug-in host"
where:
-file: The absolute path to the *.opar file on the system where you created the archive.
-host: The host name for the host target where the file is available.
-credential_name: The name of the credentials on the remote system you are connecting to.
-credential_owner: The owner of the credentials on the host system you are connecting to.
For example:
emcli import_update -file=/tmp/sample_plugin.opar -host="host1.test.com" -credential_name="myOracleCred" -credential_owner="mypassword"
As an alternative to the previous step, you can also run the following command:
emcli import_update
-file=”path to *.opar file you created”
-host="hostname"
-credential_set_name="setname"
-credential_set_name: The set name of the preferred credential stored in the Management Repository for the host target. It can be one of the following:
HostCredsNormal: The default unprivileged credential set.
HostCredsPriv: The privileged credential set.
A plug-in must be deployed on Oracle Management Service (OMS) before it can be used to monitor targets. Follow the steps below to deploy the plug-in on Enterprise Manager Cloud Control.
Note:
Plug-ins must be deployed on Oracle Management Service before being deployed on Management Agents.Plug-ins for specific target types are deployed automatically on Management Agents that will monitor those target types. For more information, see Section 14.6, "Adding a Target Instance".
To deploy a plug-in on the Oracle Management Server:
From the Setup menu, select Extensibility, then Plug-ins.
Enterprise Manager displays the list of plug-ins that have been downloaded and can be deployed on the Plug-ins page.
On the Plug-ins page, select the specific plug-in you want to deploy.
Click Deploy On, then select Management Servers.
Ensure that dependent plug-ins are deployed and that all existing Management Agents are compatible with the version of the specified plug-in. Enterprise Manager prompts for credentials if the Management Agent is not available.
On the Deploy Plug-in window, enter the required details. Note that you will require the Management Repository SYS user password to complete the deployment process.
From the Version list, select the Plug-in version. The Target Type information is displayed in the table. Enter the Repository sys Password, then click Continue.
Proceed through the steps in the Deploy Plug-in windows.
Click Deploy to deploy the selected plug-in on all Enterprise Manager servers.
Enterprise Manager displays a page that allows you to monitor the deployment status. Enterprise Manager deploys the selected plug-in on all Enterprise Manager Servers.
You can also monitor the deployment status by going to the Enterprise Manager Cloud Control console, then going to the Plug-ins page as described in step 1, selecting the plug-in and select the Recent Deployment Activities tab at the bottom of the page for the selected plug-ins. This bottom section also lets you see details of your plug-in, which includes the plug-in ID, version, vendor, and so on.
If any of the steps during plug-in deployment fails, the log file is available in $ORACLE_HOME/cfgtoollogs/pluginca/*. Append these files when logging a support request for failure while deploying the plug-in. You can also use them to debug the problem.
You can import multiple versions of the same plug-in. The version to deploy can be selected from a list if you are using Cloud Control to deploy the plug-in, or can be specified on the command line if using EM CLI.
Only one version can be deployed on the Oracle Management Service (OMS) at any given time. If a later version has been deployed previously, it cannot be downgraded to an earlier version.
Updating a plug-in to a new version does not remove the content of the older plug-in(s) that were imported.
The Management Agent can have the same or earlier version of the plug-in that is deployed on the OMS. A version later than the version on the OMS is not allowed on the Management Agent.
The plug-in on OMS and the Management Agent can be updated independently of each other as long as the version on the OMS is the latest version.
Available updates are visible on the Plug-ins page. They can be downloaded from the Enterprise Manager store or imported using EM CLI as described in Section 14.5.2, "Importing the Plug-in Archive".
When the plug-in is deployed on OMS, it is ready to monitor target instances.
Note:
In the current Cloud Control release, deployment of a plug-in to a Management Agent that will monitor targets is no longer required. Instead, the plug-in for a specific target type is automatically deployed with the Management Agent that will monitor targets of that type.This is a significant change from previous releases, in which plug-ins had to be manually deployed to a Management Agent first. Then a target instance had to be added to the Management Agent manually.
You can add targets that the plug-in will monitor through Enterprise Manager Cloud Control by selecting Add Targets from the Setup menu. The process for adding targets - known in Cloud Control terminology as target promotion - varies depending on the option you choose.
You can also add a target instance using the EM CLI utility. Open a command prompt and run the following command:
emcli add_target -name="name" -type="type" -host="hostname" [-properties="pname1:pval1;pname2:pval2;..."]... [-separator=properties="sep_string"] [-subseparator=properties="subsep_string"] [-credentials="userpropname:username;pwdpropname:password;..."] [-input_file="parameter_tag:file_path"] [-display_name="display name"] [-groups="groupname1:grouptype1;groupname2:grouptype2;..."]... [-timezone_region="gmt offset"] [-monitor_mode="monitor mode"] [-instances="rac database instance target name1:target type1;..." ]
For example:
emcli add_target
-name="cluster_database"
-type="rac_database"
-host="myhost.us.example.com"
-monitor_mode="1"
-properties="ServiceName:service.us.example.com;ClusterName:newdb_cluster"
-instances="database_inst1:oracle_database;database_inst2:oracle_database"
Use the emcli help add_target help command to see more options when adding the target instance.
If targets have been added before, they will be promoted and monitored by the plug-in after it is deployed.
As part of the plug-in development process, you will package your plug-in as an archive and deploy it to an Enterprise Manager Cloud Control installation to test it. However, you will likely not want to re-deploy the plug-in each time you make changes to various metadata files.
Note:
You must update the metadata version each time you update a metadata file.The Metadata Registration Service (MRS) allows you to upload one or more updated metadata files to the Oracle Management Service and Management Agents your plug-in has been deployed to. The updated metadata files will be registered with Enterprise Manager, and will overwrite the existing metadata with your updates.
Note:
For target types and default collections, some additional steps are required for using MRS, see Section 14.7.1, "Target Types and Default Collections".This service is invoked through the emctl register oms metadata command. The syntax is as follows:
emctl register oms metadata -service Metadata Service Id (-file metadata file to register | -file_list file containing list of files to register) [-core | -pluginId Plugin Id] [-sysman_pwd "sysman password"]
For example, the following command registers changes to target type metadata file:
emctl register oms metadata -service targetType -file /staging/demo_hostsample.xml -pluginId test.demo.xyz -sysman_pwd myempassword
Table 14-4 describes the usage of the command.
Table 14-4 emctl Command Usage
| Option | Required Y/N | Description |
|---|---|---|
|
|
Y |
Specify the type of metadata to register. Values are:
|
|
|
N |
The path and file name for a single metadata file to upload and register. Either |
|
|
N |
The path and file name for a file containing a list of metadata file paths (one on each line). |
|
|
N |
Not valid for plug-in development. |
|
|
N |
The unique three-part identifier given to the deployed plug-in to update. See Section 2.2.1, "Defining the Plug-in ID" for details. |
|
|
Y |
The Enterprise Manager user password. |
For target types and default collections, some additional steps are required for using MRS if there are existing targets of this target type.
If you have an existing target and you want to update the metadata files during the plug-in development process, follow these steps:
Register the new metadata files using the emctl register oms metadata command.
emctl register oms metadata -service targetType -file full path/TargetTypeMetadata.xml -pluginId Plugin Id -sysman_pwd sysman emctl register oms metadata -service storeTargetType -file full path/TargetTypeMetadata.xml -pluginId Plugin Id -sysman_pwd sysman emctl register oms metadata-service default_collection -file full path/TargetTypeCollection.xml -pluginId Plugin Id -sysman_pwd sysman emctl register oms metadata-service systemStencil -file full path/TargetTypeStencil.xml -pluginId Plugin Id -sysman_pwd sysman
Place the metadata XML files in the correct directories of the plug-in home directory (PLUGIN_AGENT_HOME) in the Management Agent as shown. The PLUGIN_AGENT_HOME directory is created when the plug-in is deployed to the Management Agent. The default location is AGENT_BASE_DIR/plugins.
$PLUGIN_AGENT_HOME/metadata/ $PLUGIN_AGENT_HOME/default_collection
Restart the Management Agent.
AGENT_HOME/agent/bin/emctl stop agent AGENT_HOME/agent/bin/emctl start agent
In the preceding command, AGENT_HOME represents the Management Agent home directory.