18 Managing Plug-Ins

This chapter provides an overview of Plug-In Manager, and describes how you can use it to view, deploy, administer, and undeploy plug-ins.

In particular, this chapter covers the following:

• Introduction to Plug-ins

• Workflow of Plug-In Deployment

• Introduction to Plug-In Manager

• Knowing Your Plug-Ins

• Downloading, Deploying, and Upgrading Plug-Ins

• Undeploying Plug-Ins

• Advanced Operations with Plug-Ins

• Troubleshooting

18.1 Getting Started

Table 18-1 provides a quick view of the sections within this chapter that might be of interest to you.

Table 18-1 Getting Started

User	Sections of Interest
Beginner	Introduction to Plug-ins Workflow of Plug-In Deployment Introduction to Plug-In Manager
Basic	Workflow of Plug-In Deployment Customizing Your View Checking the Availability of Plug-Ins Viewing Information about Plug-Ins
Intermediate	Customizing Your View Checking the Availability of Plug-Ins Viewing Information about Plug-Ins Downloading Plug-Ins Deploying Plug-Ins to Oracle Management Service (Reduce OMS Restart time and Downtime) Upgrading Plug-Ins Deployed to Oracle Management Service Deploying Plug-Ins on Oracle Management Agent Upgrading Plug-Ins Deployed to Oracle Management Agent Undeploying Plug-Ins from Oracle Management Service Undeploying Plug-Ins from Oracle Management Agent Troubleshooting
Advanced	Re-deploying Plug-Ins on Oracle Management Agent Deploying Plug-In Patches While Deploying or Upgrading Management Agent (Create Custom Plug-In Update) Troubleshooting

18.2 Introduction to Plug-ins

This section covers the following:

• Enterprise Manager 12c Extensibility Paradigm

• Plug-Ins

• Plug-Ins Deployed by Default

• Plug-In Releases

• Roles Required to Manage Plug-Ins

18.2.1 Enterprise Manager 12c Extensibility Paradigm

Enterprise Manager is system management software that delivers centralized monitoring, administration, and life cycle management functionality for the complete IT infrastructure, including systems running Oracle and non-Oracle technologies.

Enterprise Manager has grown in size and magnitude over the years to offer a spectrum of powerful IT management and monitoring solutions. This growth has lead to changes in managing support for new features, enhancements, and bug fixes.

Considering these developments, Oracle has carefully redesigned the architecture of Enterprise Manager in such a way that the framework or the core base on which the product runs is clearly separated from the layer that offers IT solutions by means of features. This new architecture implemented in Enterprise Manager 12c enables Oracle to provide a much stronger framework with capabilities to extend itself seamlessly from time to time for supporting new features and enhancements.

You no longer have to wait for the next release of Enterprise Manager to access the latest monitoring features for released products. The pluggable framework in Enterprise Manager 12c allows target support to be included soon after new versions of targets ship. You can install a new Enterprise Manager system or upgrade an existing one, as soon as the Enterprise Manager release is made available by Oracle.

Based on the new design, the Enterprise Manager 12c architecture constitutes the following logical parts:

• EM Platform: Consists of a set of closely integrated UI and backend services that most monitoring and management functionality in Enterprise Manager depends on. Examples of platform subsystems include the Enterprise Manager target and metric model, the job, event, and provisioning framework. The platform also includes Oracle Management Agent (Management Agent) as well as the core background services such as the data loader, job dispatcher, and notification manager. The platform is delivered as part of an Enterprise Manager release, and can only be upgraded by upgrading to a new version of Enterprise Manager.

• EM Plug-ins: Modules that can be plugged to an existing Enterprise Manager Platform to provide target management or other vertical functionality in Enterprise Manager. Plug-ins offer special solutions or new features, for example, connectivity to My Oracle Support, and extend monitoring and management capability to Enterprise Manager, which enable you to monitor a particular target on a host. Plug-ins work in conjunction with OMS and Management Agent to offer monitoring services, and therefore they are deployed to the OMS as well as the Management Agent.

The plug-in releases happen more often than Enterprise Manager Core Platform releases. The plug-ins enable Enterprise Manager 12c to be updated with new features and management support for the latest Oracle product releases, without having to wait for the next platform release to provide such functionality.

18.2.2 Plug-Ins

Plug-ins are modules that can be plugged into an existing Enterprise Manager Cloud Control deployment to extend target management or other vertical functionality in Enterprise Manager.

At a high level, plug-ins contain archives for monitoring and discovering OMS instances and Management Agents. The archives contain Java and SQL codes, and metadata.

18.2.3 Plug-Ins Deployed by Default

As a part of Enterprise Manager Cloud Control installation, a set of basic plug-ins is deployed by default. You can deploy other plug-ins to extend the basic functionality of Enterprise Manager Cloud Control.

The plug-ins that are deployed by default, or are shipped out of box are as follows.

• Oracle Database: oracle.sysman.db

• Oracle Fusion Middleware: oracle.sysman.emas

• Oracle MOS (My Oracle Support): oracle.sysman.mos

• Oracle Exadata: oracle.sysman.xa

• Oracle Cloud Framework: oracle.sysman.cfw

Note:

For a brief description about these plug-ins, see Oracle Enterprise Manager Basic Installation Guide.

18.2.4 Plug-In Releases

Plug-in releases happen more often than Enterprise Manager Core platform releases. This new pluggable framework enables Enterprise Manager Cloud Control to be updated with management support for the latest Oracle product releases, without having to wait for the next platform release to provide such functionality.

For example, when a new version of Oracle Database is released, you can simply download and deploy the latest Oracle Database plug-in, which will include management support for the latest Oracle Database release. You can also work with plug-ins in Offline Mode.

18.2.5 Roles Required to Manage Plug-Ins

You need one or more of the following out-of-the-box roles to download, manage, and deploy plug-ins:

• EM_PLUGIN_OMS_ADMIN: Enables you to manage the lifecycle of plug-ins on Management Server instances.

• EM_PLUGIN_AGENT_ADMIN: Enables you to manage the lifecycle of plug-ins on Management Agents.

• EM_PLUGIN_USER: Enables you to view the plug-in lifecycle console.

18.3 Workflow of Plug-In Deployment

Figure 18-1 illustrates the workflow of plug-in deployment—how you typically set up the Enterprise Manager infrastructure, deploy plug-ins to OMS, and discovery and monitor targets using the deployed plug-ins.

Figure 18-1 Plug-In Deployment Workflow

Step 1: Setting up Self-Update Console

Self Update console is a common dashboard used for reviewing, downloading, and applying new updates available for Enterprise Manager. The console frees you from having to monitor multiple channels to get informed about new updates that are available from Oracle. The updates automatically downloaded by Self Update include plug-ins. For checking the availability of plug-ins and downloading them to Enterprise Manager, you must set up the Self Update Console. Set up the Self Update Console as described in Oracle Enterprise Manager Cloud Control Administrator's Guide.

Step 2: Checking Plug-In Availability

Checking the plug-in availability essentially refers to the act of verifying whether the plug-ins are available on My Oracle Support for download and deployment in Enterprise Manager. This is a prerequisite before downloading plug-ins. To check plug-in availability, follow the steps outlined in Section 18.5.2.

Step 3: Viewing Plug-In Information

Viewing plug-in information refers to the act of viewing basic information related to a particular plug-in, such as the plug-in ID, the plug-in release number, and other basic information. You must view plug-in information to understand what targets and operating systems are certified for plug-ins. You can also check whether or not a particular plug-in has already been deployed. To view plug-in information, follow the steps outlined in Section 18.5.3.

Step 4: Downloading Plug-Ins

Downloading plug-ins is the act of downloading plug-in archives or components, and its metadata, from My Oracle Support to Oracle Software Library (Software Library), so that they can be deployed suitably for discovering and monitoring certain targets. If you find that a particular target is not being monitored by plug-ins, you must download the required plug-ins. You can download both in online mode and offline mode. To download plug-ins, follow the steps outlined in Section 18.6.1.

Step 5: Deploying Plug-Ins to OMS

Deploying plug-ins to OMS is the next natural course of action once a plug-in is downloaded from My Oracle Support. This is to ensure the OMS capabilities are extended to either manage a new target or to add a new vertical capability. The installation and configuration of plug-ins on the OMS is essentially referred to as Deployment. Some plug-ins, when deployed, require the OMS to be re-started.

Figure 18-2 illustrates how plug-ins are deployed to the OMS.

Figure 18-2 Deploying Plug-Ins to OMS

When the plug-in archives are deployed from the Software Library to the OMS, the OMS receives three different components for each plug-in, namely the OMS plug-in components, the discovery plug-in components, and the monitoring plug-in components.

Discovery plug-in components are those components that help in the discovery of unmanaged targets. Monitoring plug-in components are those components that help in the adding of discovered targets to Enterprise Manager Cloud Control Console for monitoring purposes.

To deploy plug-ins on OMS, follow the steps outlined in Section 18.6.2.

Step 6: Discovering Targets

Discovering targets refers to the process of identifying unmanaged hosts and targets in your environment. During discovery of targets, the discovery components of plug-ins are deployed to the Management Agent home. Note that this enables Enterprise Manager Cloud Control to only identify a new target in your environment; it however does not monitor the target.

After converting unmanaged hosts to managed hosts in Enterprise Manager Cloud Control, you must configure automatic discovery of targets on those hosts so that the unmanaged targets running on those hosts can be identified.

For instructions to configure automatic discovery of targets on managed hosts, refer to the Discovering and Monitoring Targets section in the Oracle Enterprise Manager Cloud Control Administrator's Guide, using the following URL:

http://docs.oracle.com/cd/E24628_01/doc.121/e24473/discovery.htm#CBAGJFHC

Note:

When you configure automatic discovery of targets on managed hosts, discovery plug-in components are copied to Management Agent.

Once you have configured automatic discovery of targets on managed hosts, you must regularly check for discovered targets so that they can be promoted and monitored in Enterprise Manager Cloud Control.

For instructions to check for and promote discovered targets to managed status, refer to the Discovering and Monitoring Targets section in the Oracle Enterprise Manager Cloud Control Administrator's Guide, using the following URL:

http://docs.oracle.com/cd/E24628_01/doc.121/e24473/discovery.htm#CBAFHEHC

Note:

The plug-in for a specific target type is automatically deployed to the Management Agent that will monitor targets of that type. For example, if you discover a database target, the discovery plug-in component of the database plug-in is automatically deployed to the Management Agent installed on the database host.

However, this is true only for initial deployment. All subsequent updates to the Management Agent plug-in must be explicitly deployed. For example, if you want to deploy a new version of the database plug-in on the Management Agent, you must initiate the deployment using the instructions outlined in Oracle Enterprise Manager Cloud Control Basic Installation Guide.

Similarly, any patches to be applied on the Management Agent (framework or plug-in) must be explicitly applied using the instructions outlined in Oracle Enterprise Manager Cloud Control Administrator's Guide.

Figure 18-3 illustrates how the discovery plug-in components are deployed to the Management Agent while discovering new targets.

Figure 18-3 Discovering Targets

Step 7: Adding Targets for Monitoring

Once the targets are discovered, they are added to the infrastructure, so that they can be monitored in Enterprise Manager Cloud Control. While adding targets, the monitoring components of plug-ins are deployed to the Management Agent home.

Figure 18-4 illustrates how the monitoring plug-in components are deployed to the Management Agent while adding targets.

Figure 18-4 Adding Targets

18.4 Introduction to Plug-In Manager

Plug-In Manager is a feature of Enterprise Manager Cloud Control, that serves as a single window solution for performing all plug-in deployment-related activities, through GUI as well as CLI. Using Plug-In Manager, you can:

• View plug-ins available for download; plug-ins that have been downloaded; and plug-ins that have been deployed to Cloud Control.

• View certification and critical information about plug-ins such as the name of the plug-in, the vendor who supplied it, the plug-in ID and version, and a short description.

• Deploy plug-ins on OMS.

• Deploy and re-deploy plug-in on Management Agent.

• Create custom plug-in update.

• Undeploy plug-ins from OMS and Management Agent.

• View the status of a plug-in deployment operations.

18.4.1 Accessing Plug-In Manager

To access the Plug-In Manager console, from the Setup menu, select Extensibility, and then select Plug-ins.

Figure 18-5 illustrates how you can access Plug-in Manager.

Figure 18-5 Navigating to Plug-In Manager

18.4.2 Performing Operations Using Plug-In Manager

Using Plug-in Manager, you can deploy, upgrade, redeploy, and undeploy plug-ins.

Figure 18-6 shows the operations you can perform using the Plug-In Manager.

Figure 18-6 Plug-In Manager Operations

18.5 Knowing Your Plug-Ins

This section explains the following:

• Customizing Your View

• Checking the Availability of Plug-Ins

• Viewing Information about Plug-Ins

18.5.1 Customizing Your View

This section tells you how to customize your view, and organize the plug-ins and columns displayed.

18.5.1.1 Customizing Displayed Plug-Ins

Over a period of time, as you download and deploy plug-ins, the number of plug-ins on your list increases. You can sort these plug-ins to view only the ones you require, for example, only the plug-ins available, or only the plug-ins deployed.

In order to customize your view, follow these steps.

1. From the View menu, select Plug-Ins.

2. From the Plug-Ins menu, select one of the following filters.

   • All, using this filter, you can view all plug-ins, including available, downloaded, and deployed plug-ins.

   • Only Available, using this filter, you can view the plug-ins that are available for download.

   • Only Downloaded, using this filter, you can view the plug-ins that are downloaded.

   • Only Deployed, using this filter, you can view the plug-ins that are deployed.

18.5.1.2 Customizing Displayed Columns

By default, only a few columns of information are displayed. Optionally, you can either enable other columns of your interest, or disable ones that are already displayed.

In order to customize the displayed columns, follow these steps.

1. From the View menu, select Columns.

2. From the Columns menu, select one of the following filters for columns.

   • Show All, using this filter, you can view all columns.

   • Vendor, using this filter, you can view information about the vendor.

   • Plug-In Id, using this filter, you can view the plug-in id.

   • Version, this filter has three options you can choose from. They are as follows.

     • Latest Available, using this filter, you can view the newest plug-ins that are available.

     • Latest Downloaded, using this filter, you can view the plug-ins that have been downloaded recently.

     • On Management Server, using this filter, you can view the plug-ins that are deployed to the OMS.

   • Management Agent with Discovery Plug-Ins Only, this filter displays the Management Agent which has only Discovery Plug-Ins deployed.

   • Management Agent with Plug-In, this filter displays the Management Agent which has any plug-in deployed on it.

   • Description, this filter displays the description of the plug-ins.

18.5.2 Checking the Availability of Plug-Ins

To check the availability of plug-ins, follow these steps:

1. Set up the Self Update Console as described in Oracle Enterprise Manager Cloud Control Administrator's Guide.

2. From the Setup menu, select Extensibility, then select Plug-ins.

3. On the Plug-ins page, in the Latest Available column of the table, check whether the plug-ins are available.

   To refresh the list of available plug-ins, click Check Updates. Note that clicking Check Updates will take you to the Self Update page.

18.5.3 Viewing Information about Plug-Ins

This section gives you more information on plug-ins, and functions related to plug-ins. This section covers the following sections:

• Differentiating Plug-In Releases from Enterprise Manager Platform Releases

• Identifying Plug-In ID

• Viewing Targets and Operating Systems Certified for Deployed Plug-Ins

• Viewing Plug-In Dependencies

• Verifying Deployed Plug-Ins

18.5.3.1 Differentiating Plug-In Releases from Enterprise Manager Platform Releases

Plug-ins have independent release cycles and release numbers, which may or may not be tied to Enterprise Manager Cloud Control product releases and release numbers.

Plug-in releases typically happen more often than Enterprise Manager platform releases.

Figure 18-7 describes how plug-in releases are numbered.

Figure 18-7 Plug-In Release Number Format

Figure 18-8 describes how Enterprise Manager platform releases are numbered.

Figure 18-8 Enterprise Manager Core Platform Release Number Format

18.5.3.2 Identifying Plug-In ID

To identify the ID of a plug-in, follow these steps:

1. From the Setup menu, select Extensibility, then select Plug-ins.

2. On the Plug-ins page, in the Plug-in ID column of the table, note the plug-in ID of the plug-in of your interest.

   If you do not see this column, from the View menu, select Columns, then select Plug-in ID.

Figure 18-9 illustrates how you can identify the plug-in ID of the Oracle Database plug-in.

Figure 18-9 Identifying Plug-In ID

18.5.3.3 Viewing Targets and Operating Systems Certified for Deployed Plug-Ins

To view a list of targets and operating systems certified for a deployed plug-in, follow these steps:

1. From the Setup menu, select Extensibility, then select Plug-ins.

2. On the Plug-ins page, select the plug-in of your interest, and from the Actions menu, select Information.

3. On the Plug-in Information page, in the General tab, review the information provided in the Certified Targets and Certified Operating Systems tables.

18.5.3.4 Viewing Plug-In Dependencies

To view the dependencies of the preferred plug-in, follow these steps:

1. From the Setup menu, select Extensibility, then select Plug-ins.

2. On the Plug-ins page, select the plug-in of your interest, and from the Actions menu, select Information.

3. On the Plug-in Information page, in the Dependencies tab, review the information provided in the tables.

18.5.3.5 Verifying Deployed Plug-Ins

To view and administer the deployed plug-ins, from the Setup menu, select Extensibility, then select Plug-ins. Enterprise Manager Cloud Control displays the Plug-ins page, which is essentially the Plug-In Manager console.

To identify the OMS instances on which the plug-in of your interest is deployed, follow these steps using Enterprise Manager Cloud Control Console:

1. From the Setup menu, select Extensibility, then select Plug-ins.

2. On the Plug-ins page, select the plug-in of your interest, and from the Actions menu, select Information.

3. On the Plug-in Information page, in the Management Servers tab, review the Oracle Management Services on which the plug-in is deployed.

To identify the Management Agents on which the plug-in of your interest is deployed, follow these steps using Enterprise Manager Cloud Control Console:

1. From the Setup menu, select Extensibility, then select Plug-ins.

2. On the Plug-ins page, select the plug-in of your interest, and from the Actions menu, select Information.

3. On the Plug-in Information page, in the Management Agent tab, review the Management Agents on which the plug-in is deployed.

To identify the Plug-ins deployed on OMS, on EM CLI, log in to EMCLI, and enter the following command. The command displays a list of all the plug-ins deployed on the OMS.

$emcli login

-username=<EM Console Username>

[-password=<EM Console Password>]

[-force]

$emcli list_plugins_on_server

Example 18-1 Sample List of Plug-Ins Deployed on OMS

example.com:7654_Management_Service

Plug-in Name	Plug-in ID	Version (Revision)
Oracle Database	oracle.sysman.db	12.1.0.4.0
Oracle Fusion Middleware	oracle.sysman.emas	12.1.0.4.0
Oracle MOS (My Oracle Support)	oracle.sysman.mos	12.1.0.5.0
Oracle Exadata	oracle.sysman.xa	12.1.0.4.0

To identify and view all the Plug-ins deployed on Management Agent, on EM CLI, enter the following command:

$emcli list_plugins_on_agent

[agent_names="agent1,agent2,agent3..."

[-all] [-include_discovery]

Example 18-2 Sample List of Plug-ins Deployed on Management Agent

emcli list_plugins_on_agent -agent_names=agent1.example.com:3872
Lists plug-ins on the agent agent1.example.com

emcli list_plugins_on_agent -agent_names=agent1.example.com:3872,agent2.example.com:3872 -include_discovery
Lists plug-ins on both the agents provided along with their discovery components

emcli list_plugins_on_agent -agent_names='agent*,st*93'
Lists plug-ins on all agents with name matching one of the regular expressions agent* or st*93

emcli list_plugins_on_agent -all
Lists plug-ins on all the management agents.

18.6 Downloading, Deploying, and Upgrading Plug-Ins

This section explains the following:

• Downloading Plug-Ins

• Deploying Plug-Ins to Oracle Management Service (Reduce OMS Restart time and Downtime)

• Upgrading Plug-Ins Deployed to Oracle Management Service

• Deploying Plug-Ins on Oracle Management Agent

• Upgrading Plug-Ins Deployed to Oracle Management Agent

18.6.1 Downloading Plug-Ins

You can download the plug-ins in online or offline mode. Online refers to an environment where you have Internet connectivity to the Enterprise Manager Store. Offline refers to an environment where you do not have Internet connectivity. This section contains the following sections:

• Downloading Plug-Ins in Online Mode

• Downloading Plug-Ins in Offline Mode

• Importing Catalog Archives

• Importing Plug-In Archives

18.6.1.1 Downloading Plug-Ins in Online Mode

To download the plug-ins in online mode, follow these steps:

1. From the Setup menu, select Extensibility, then select Self Update.

2. On the Self Update page, in the table, click on Plug-in.

3. On the Plug-in Updates page, select the plug-in available for download, and click Download.

   Multiple selection of plug-ins is not supported.

4. In the Schedule Download dialog, select an appropriate option to schedule the download. You can also select Immediately which schedules the job for immediate action. Select Notify Once downloaded if you want to be informed once the download is complete.

5. Click Select.

   Enterprise Manager Cloud Control submits a job to download the selected plug-in from the Enterprise Manager Store to the Software Library.

   A confirmation dialog appears to confirm that the job has been submitted successfully. In this confirmation dialog, you can click Job Details to track the status of the job.

18.6.1.2 Downloading Plug-Ins in Offline Mode

To download the plug-ins in offline mode, follow these steps:

1. Set Enterprise Manager Cloud Control to Offline Mode. To do so, follow these steps.

   1. From the Setup menu, select Provisioning and Patching, then select Offline Patching.

   2. In the Online and Offline Settings tab, select Offline.

2. From the Setup menu, select Extensibility, then select Self Update.

3. On the Self Update page, click Check for Updates.

   A message appears with the following URL to an Oracle site from where the updates catalog file can be downloaded.

   https://updates.oracle.com/Orion/Download/download_patch/p9348486_112000_Generic.zip

4. From an Internet-enabled computer, download the catalog file using the aforementioned URL.

5. Copy the downloaded catalog file to the OMS host or the Management Agent host where you plan to deploy the plug-ins.

6. Import the catalog file to Enterprise Manager. For instructions, refer to Importing Catalog Archives.

7. On the Self Update page, in the table, click Plug-in.

8. On the Plug-in Updates page, select the imported update that is available for download. Click Download.

   A message appears with a URL to an Oracle site from where the update can be downloaded.

9. From a computer that is connected to the internet, download the update using the aforementioned URL.

10. Copy the downloaded file to the OMS host or the Management Agent host where you plan to deploy the plug-ins.

11. Import the downloaded plug-in archive to Enterprise Manager. For instructions, refer to Importing Plug-In Archives.

18.6.1.3 Importing Catalog Archives

To import a catalog archive, follow these steps:

1. Download the catalog archive as described in Section 18.6.1.2.

2. Execute the following emcli command to import the downloaded catalog archive.

$emcli import_update_catalog

-file="file"

-omslocal

emcli import_update_catalog

-file="file"

-host="hostname"

[-credential_set_name="setname"] | -credential_name="name" -credential_owner="owner"

Example 18-3 Sample for Importing Catalog Archive

$emcli import_update_catalog
        -file="/u01/common/p9984818_121000_Generic.zip"
        -omslocal
Imports the master catalog file p9984818_121000_Generic.zip. The file must exist on the OMS host. In a multiple OMS setup, the request can be processed by any OMS, so the file should be accessible from the OMS processing the request. This means that the file must be kept on a shared location that is accessible from all the OMS instances.
$emcli import_update_catalog
        -file="/u01/common/p9984818_121000_Generic.zip"
        -host="host1.example.com"
        -credential_set_name="HostCredsNormal"
 
Imports the master catalog file p9984818_121000_Generic.zip that is present on the host host1.example.com. The host must be a managed host target in Enterprise Manager, and the Management Agent on this host must be up and running. The preferred unprivileged credentials for host host1.example.com are used to retrieve the remote file.

18.6.1.4 Importing Plug-In Archives

Import plug-in archives to Oracle Software Library in the following cases:

• When you want to deploy any non-Oracle plug-ins, that is, plug-ins that have been created by a company other than Oracle, and are not available for download on the Self Update console.

• When you want to import other types of entity archives when Self Update is used in offline mode.

To import a plug-in archive, follow these steps:

1. Download the external archive as described in the previous section.

2. Set up the Enterprise Manager Command Line (EM CLI) utility. To do so, from the Setup menu, click Command Line Interface. Follow the instructions outlined on the Enterprise Manager Command Line Interface Download page.

3. Import the external archive in one of the following ways, depending on where EMCLI is installed.

   • If Enterprise Manager server is on the system on which you downloaded the plug-in archive (*.opar file), run the following command:

     $emcli import_update

     -file=”<path to *.opar file>”

     -omslocal

     The -omslocal flag indicates that the plug-in archive path mentioned in the -file option is directly accessible to the EM server.

   • If Enterprise Manager server is on a different system than the plug-in archive, run the following command:

     $emcli import_update

     -file=”<path to *.opar file you created>”

     -host="host1.example.com"

     -credential_name="host1_creds"

     -credential_owner="admin1"

     The command syntax is as follows:

     -file: The absolute path to the *.opar file on the system where you created the archive.

     -host: The target name for a 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.

   Note:

   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.

18.6.2 Deploying Plug-Ins to Oracle Management Service (Reduce OMS Restart time and Downtime)

You can deploy multiple plug-ins to an OMS instance in graphical interface or command line interface.

Note:

• To view a visual demonstration on how you can deploy a plug-in to the OMS and discover targets, access the following URL and click Begin Video.

  https://apex.oracle.com/pls/apex/f?p=44785:24:942581250672901::NO::P24_CONTENT_ID,P24_PREV_PAGE:6000,1">>https://apex.oracle.com/pls/apex/f?p=44785:24:942581250672901::NO::P24_CONTENT_ID,P24_PREV_PAGE:6000,1

• Plug-ins must be deployed on the OMS prior to being deployed on Management Agents.

• In a multi OMS environment, Plug-in Manager automates plug-in deployment on all the management servers.

• A plug-in upgrade failure could put the Management Repository in an inconsistent state. Oracle recommends that your repository database should be running in archive log mode, and that your backup policies are in place.

• The deployment time varies from one plug-in to another, depending on the volume of data populated in the Management Repository. A page is displayed that allows you to monitor the deployment status, as described in Section 18.6.2.1.

• The deployment of some plug-ins requires the OMS to be stopped, and then restarted. This process occurs automatically as part of the plug-in deployment process.

• While deploying plug-ins to the OMS, OMS plug-in components, discovery plug-in components, and monitoring plug-in components are deployed to the OMS.

To deploy plug-ins to the OMS in graphical mode, follow these steps:

1. From the Setup menu, select Extensibility, then select Plug-ins.

2. On the Plug-ins page, select the plug-in you want to deploy.

   Note:

   Alternately, you can move to the next step and select the plug-ins after the next step.

3. From the Deploy On menu, select Management Servers.

4. In the Deploy Plug-ins on Management Servers: Plug-ins page, verify that the plug-in details on the lower portion of the screen are correct. Additionally, you can add more plug-ins by clicking Add.

5. Select the Use Last Successful Prerequisite check box to skip the prerequisite checks.

   The check box is enabled only if the plug-in had successfully cleared the prerequisites checks within the last 24 hours and was not deployed.

6. Click Next.

7. In the Deploy Plug-ins on Management Servers: Prerequisite Checks page, wait for the prerequisite checks to complete (if not cleared already) and click Next.

8. In the Deploy Plug-ins on Management Servers: Repository page, specify the Management Repository SYS credentials. Click Named option to select the saved credentials or click New option to enter new credentials.

   The newly entered credentials will be automatically saved for future deployments, after the deployment is successful.

9. Click Next.

10. The Deploy Plug-ins on Management Servers: Review page displays the OMSs and the statuses of the OMSs where the plug-ins will be deployed, and the plug-ins. Verify that all the details are correct and click Deploy.

To deploy plug-ins to the OMS in silent mode, follow these steps:

1. Log in to EMCLI as follows:

   $ORACLE_HOME/bin/emcli login -username=sysman

2. Run the following command if the emcli client is an old version, and does not have all required verbs:

   $ORACLE_HOME/bin/emcli sync

3. To deploy the plug-ins on the OMS, run the following command:

   $emcli deploy_plugin_on_server

   -plugin="plug-in_id[:version]

   [-sys_password=sys_password]

   [-prereq_check]"

   Note:

   For information on plug-in id, refer to Section 18.5.3.2.

   For example,

   $emcli deploy_plugin_on_server -plugin="oracle.sysman.db:12.1.0.2.0;oracle.sysman.emas:12.1.0.2.0"

Note:

The procedure for plug-in deployment remains the same even in a multi-OMS environment. Enterprise Manager automatically detects whether it is a single-OMS or a multi-OMS environment and in case of a multi-OMS environment, Enterprise Manager automatically deploys the selected plug-in on all OMS instances.

If the plug-in deployment fails on a primary OMS, where the Administration Server is running, then you must first address the issue, and then resume the deployment or restore the system from backup. If however, the plug-in deployment fails on a non-primary OMS, identify the cause for the failure. If there is a fix or a workaround, fix the problem, and perform the same steps again. The system automatically detects which OMS instances do not have the plug-ins deployed, and deploys them on those servers.

If the problem persists, contact Oracle Support.

18.6.2.1 Tracking the Deployment Status of Plug-Ins on Oracle Management Service

This section describes the procedure of monitoring the deployment status of plug-ins that do not require down time as well as those that do require down time.

To monitor the status of deployment and undeployment operations of plug-ins that require down time, execute the following command:

emctl status oms -details

To monitor the status of deployment and undeployment operations for plug-ins that do not require down time, follow these steps:

1. From the Setup menu, select Extensibility, then select Plug-ins.

2. On the Plug-ins page, do one of the following:

   • From the Actions menu, select Deployment Activities.

   • Select a plug-in, and click the Recent Deployment Activities tab at the bottom of the page. Alternatively, you can also run the following command using EMCLI.

     $emcli get_plugin_deployment_status -plugin_id=<plugin_id>

18.6.3 Upgrading Plug-Ins Deployed to Oracle Management Service

This section contains the following sections:

• Upgrading Across Plug-In Versions Deployed to Oracle Management Service

• Upgrading Across Plug-In Revisions Within a Plug-In Version Deployed to Oracle Management Service

18.6.3.1 Upgrading Across Plug-In Versions Deployed to Oracle Management Service

You can upgrade across plug-in versions, that is, from one plug-in version to another higher plug-in version or a revision of another higher plug-in version. For example, from Oracle Database plug-in version 12.1.0.1.0 to version 12.1.0.2.0, or from Oracle Database plug-in version 12.1.0.1.0 to version 12.1.0.2.0 [u120427].

To upgrade across plug-in versions deployed to the OMS, follow these steps:

1. Check for the latest available versions and revisions in the Enterprise Manager Store as described in Section 18.5.2.

2. Download them as described in Section 18.6.1.

3. Deploy them to the OMS as described in Section 18.6.2.

18.6.3.2 Upgrading Across Plug-In Revisions Within a Plug-In Version Deployed to Oracle Management Service

This section describes how you can upgrade across plug-in revisions within a plug-in version, that is, from one revision of a plug-in version to another revision of the same plug-in version. For example, from Oracle Database plug-in version 12.1.0.2.0 [u120427] to version 12.1.0.2.0 [u120502].

To upgrade the plug-in revisions deployed to the OMS, follow these steps:

1. Check for the latest available revisions in the Enterprise Manager Store as described in Section 18.5.2.

2. Download them as described in Section 18.6.1.

3. Apply the patches required for the plug-in revision.

   1. From the Setup menu, select Extensibility, then select Plug-ins.

   2. On the Plug-ins page, select the plug-in revision you downloaded, and from the Actions menu, select Information.

   3. On the Plug-in Information page, in the General tab, in the Dependencies section, in the Bug Fixes Required table, click View Bug Fixes.

   4. In the Required Bug Fixes dialog, note the bug numbers listed in the Bug Number column of the Management Server Fixes table.

   5. Download the patches that contain the fixes for the bugs you noted in the previous step.

   6. Apply the downloaded patches on the OMS.

4. Deploy the latest available revisions to the OMS as described in Section 18.6.4.

18.6.4 Deploying Plug-Ins on Oracle Management Agent

While installing a Management Agent using the Add Host Targets Wizard, all the core discovery plug-ins available on the OMS are automatically deployed to the Management Agent.

For information about discovery plug-ins, refer to Section 18.5.3.

If you want to deploy any additional plug-ins after installing the Management Agent, then follow these steps:

1. Set up the Self Update console.

2. Check whether the plug-ins are available on Enterprise Manager store. For instructions refer to Section 18.5.2.

3. Download the available plug-ins. For instructions, refer to Section 18.6.1.

4. Deploy the downloaded plug-ins to the Management Agent.

   1. From the Setup menu, select Extensibility, then select Plug-ins.

   2. On the Plug-ins page, select the plug-in you want to deploy.

   3. From the Deploy On menu, select Management Agent.

   4. Follow the steps mentioned in the Deploy Plug-ins on Management Agent dialogue box.

   5. Click Deploy.

To deploy plug-ins in EM CLI, use the following command:

$emcli deploy_plugin_on_agent

-agent_names="agent1[;agent2...]"

-plugin="plug-in_id[:version"]

[-discovery_only]

To deploy the latest revision of the plug-in, run the command above with an additional argument: allow_revision_update.

18.6.4.1 Tracking the Deployment Status of Plug-Ins on Oracle Management Agent

To track the deployment status of plug-ins on Management Agent, refer to Section 18.6.2.1.

18.6.5 Upgrading Plug-Ins Deployed to Oracle Management Agent

You can upgrade across plug-in versions, that is, from one plug-in version to another, higher plug-in version or a revision of another, higher plug-in version. For example, from Oracle Database plug-in version 12.1.0.1.0 to version 12.1.0.2.0, or from Oracle Database plug-in version 12.1.0.1.0 to version 12.1.0.2.0 [u120427].

Note:

You will upgrade the plug-in versions and revisions only on Management Agents that are already installed in your environment.

When a plug-in is deployed explicitly or a target is promoted on new Management Agents, then the latest plug-in version and revision automatically gets included from the OMS.

To upgrade across plug-in versions deployed to the Management Agent, follow these steps:

1. Check for the latest available versions and revisions in the Enterprise Manager Store as described in Section 18.5.2.

2. Download them as described in Section 18.6.1.

3. From the Setup menu, select Extensibility, then select Plug-ins.

4. On the Plug-ins page, select the plug-in you want to upgrade.

5. From the Deploy On menu, select Management Agent.

6. In the Deploy Plug-in on Management Agent dialog, select the version or revision of the plug-in you want to upgrade to., and click Continue.

7. Select the preferred Management Agent to upgrade the plug-in on, and click Continue. Then click Next. And then click Deploy.

8. On the Confirmation dialog, click Close.

18.7 Undeploying Plug-Ins

This section explains the following:

• Undeploying Plug-Ins from Oracle Management Service

• Undeploying Plug-Ins from Oracle Management Agent

18.7.1 Undeploying Plug-Ins from Oracle Management Service

To undeploy plug-ins from the OMS, follow the steps:

1. First, undeploy all plug-ins from all Management Agents. To do so, follow the steps mentioned in Section 18.7.2.

2. From the Setup menu, select Extensibility, then select Plug-ins.

3. On the Plug-ins page, select the plug-in you want to undeploy, and from the Actions menu, select Undeploy From, then select Management Servers.

4. In the Undeploy Plug-in From Management Server dialog, enter the Management Repository SYS password, and click Continue. Then click Undeploy.

5. On the Confirmation dialog, click Close.

   To monitor the undeployment operation, click Show Status.

To undeploy a plug-in in EM CLI, use the following command:

$emcli undeploy_plugin_from_server

-plugin="plug-inId"

[-sys_password="sys_password"]

Note:

When a metadata plug-in is undeployed/redeployed, it is recomended that you run the following command. The command should be run in each OMS environment instance.

$emcli metric_control -command=flush_metadata_cache

If you want to undeploy only the plug-ins from the OMS, and not the entire Enterprise Manager system, then use the Plug-ins page within the Enterprise Manager Cloud Control Console. Do NOT use runInstaller to undeploy only the plug-ins.

18.7.2 Undeploying Plug-Ins from Oracle Management Agent

To undeploy plug-ins from the Management Agent, follow the steps:

1. From the Setup menu, select Extensibility, then select Plug-ins.

2. On the Plug-ins page, select the plug-in you want to undeploy, and from the Actions menu, select Undeploy From, then select Management Agent.

3. In the Undeploy Plug-in From Management Agent dialog, click Add and add the Management Agents from which you want to undeploy the plug-in. Click Continue. Then click Undeploy.

4. On the Confirmation dialog, click Close.

   To monitor the undeployment operation, click Show Status.

Note:

Undeploying a plug-in from Management Agent removes all the targets that were monitored by the plug-in.

Undeployment of a plug-in from the Management Agent restarts the Management Agent. The Management Agent does not monitor any target during downtime.

To undeploy a plug-in using EM CLI, use the following command:

$emcli undeploy_plugin_from_agent

-plugin="pluginId"

{-agent_names="agent1[;agent2...]" | -all_discovery_only_agents}

To undeploy all versions of oracle.sysman.db2 plug-ins from all Management Agents where only Discovery Plug-ins are deployed, use the following command:

$emcli undeploy_plugin_from_agent -plugin=oracle.sysman.db2 -all_discovery_only_agents

18.8 Advanced Operations with Plug-Ins

This section explains the following:

• Re-deploying Plug-Ins on Oracle Management Agent

• Deploying Plug-In Patches While Deploying or Upgrading Management Agent (Create Custom Plug-In Update)

18.8.1 Re-deploying Plug-Ins on Oracle Management Agent

Using re-deploy option, you can re-deploy plug-ins on Oracle Management Agent. The re-deploy plug-in option reconfigures the same plug-in on the Management Agent, and does not change the configuration details.

$emcli redeploy_plugin_on_agent

{-agent_names="agent1[;agent2...]" | -group_name="group1"}

-plugin="plug-in_id:version"

[-redeploy_noprompt]

Note:

While using this option, note that the existing plug-in home will be overwritten, and all applied patches will be lost.

The re-deploy wizard displays the following warning message:

Re-deployment of a plug-in overwrites the existing OracleHome of a plug-in and you will lose any patch(es) that has been applied on plug-in OracleHome.

However, if you have enabled -redeploy_nopromt option, then the warning message will not be displayed.

To continue, click Yes.

The redeploy command cannot be used on multiple Management Agents without having Custom Plug-in Update for a plug-in.

Note:

After a metadata plug-in is redeployed, it is recomended that you run the following command.

$emcli metric_control -command=flush_metadata_cache

The command should be run on all OMS instances.

18.8.2 Deploying Plug-In Patches While Deploying or Upgrading Management Agent (Create Custom Plug-In Update)

When a new plug-in is released, it can be downloaded using Self-update. If there are defects with the Management Agent plug-ins, Oracle then releases O-patch style patches. While plug-ins get deployed automatically during target discovery on Management Agents, patches for the plug-ins have to be applied on each plug-in manually.

Custom plug-in update is the user copy of the plug-in, along with patches applied to it. Using the Create Custom Plug-In Update command allows you to create a custom copy of plug-in along with the patches applied in self update. Once the patches are applied, you can create a custom plug-in update of the plug-ins on that Management Agent. The custom plug-in update then becomes a gold image for that plug-in with all the patches applied on that Oracle Home, along with the base plug-in binaries.

After the Custom Plug-in Update is created, any plug-in deployment operation for the plug-in on any Management Agent, using either UI or EMCLI, the new custom copy will be deployed instead of the Oracle supplied version. In this way you don't have to reapply the plug-in patches manually on each plugin home of agent. This custome plug-in image is also used by Agent deployment ot upgrade activity so that the plug-ins getting deployed on these agents are with the patch included.

There are two methods of creating Custom Plug-in Update. The following sections describe the two methods.

• Creating Custom Plug-In Update Using EMCLI(recommended)

• Creating Custom Plug-In Update Using EDK

18.8.2.1 Creating Custom Plug-In Update Using EMCLI

To create a custom plug-in update, follow these steps:

1. Select a test Management Agent which is up and running on which the preferred plug-in is already deployed. Apply any patches that you want to apply on this plug-in.

2. Perform the required testing.

3. Create a custom plug-in update using the following command:

   $emcli create_custom_plugin_update

   -agent_name="agent_name"

   -plugin_id="plugin_id"

Note:

To overwrite and update your current custom plug-in update that is stored in a repository, use the overwrite option.

$emcli create_custom_plugin_update

-agent_name="agent_name"

-plugin_id="plugin_id"

[-overwrite]

This command creates and imports a custom plug-in update from an existing Management Agent where the selected plug-in is deployed. The custom plug-in update will be used for all subsequent plug-in deployments on any Management Agent, in place of Oracle supplied versions.

Custom plug-in update is created as per plug-in type. If a custom plug-in update is created, and after three days, a patch is applied, in order to include the patch, the custom plug-in update will have to be created again.

To view a list of all Custom Plug-in Updates created, run the following command.

$emcli list_custom_plugin_updates

To view a a list of patches included in a particular Custom Plug-in Update, run the following command.

$emcli list_patches_in_custom_plugin_update -plugin=<plugin_id>:<version> [-discovery]

On the Plug-in Manager console, when you select a plug-in, if a Custom Plug-in Update exists, an icon is displayed beside the version identifier, indicating that that particular plug-in version is customized in the environment, with a list of patches. displays the Custom Plug-in Update icon. Once the custom plug-in update exists, it will be used by the Management Agent for deployment and upgrade automatically.

Figure 18-10 Custom Plug-in Update Icon

When you click the Custom Plug-in Update icon, the page that displays the information on Custom Plug-in Update is displayed. displays the Custom Plug-in Update information page.

Figure 18-11 Custom Plug-in Update Information Page

18.8.2.2 Creating Custom Plug-In Update Using EDK

To create custom plug-in update using EDK, follow these steps.

1. Download EDK, using the UI or EMCLI, on the Management Agent Host.

   To download EDK using UI, from the Setup menu, select Extensibility, and then select Development Kit.

   To download EDK using EMCLI, run the following command.

   $emcli get_ext_dev_kit

2. Run the following command.

   $empdk create_custom_plugin_update -out_dir <output dir>

   -agent_state_dir <agent_state_dir>

   -agent_oracle_home <agent_oracle_home>

   -plug_id <plugin_id>

   For help with empdk commands, run the following command.

   $/empdk -help

The plug-in update is saved to on a local directory as a .zip file. The .zip file has to be copied to an OMS instance. Once the .zip file is created, from the OMS Home, run the following command to import the custom plug-in update.

$emcli import_plugin_update -archive=<archive path>

On the Plug-in Manager console, when you select a plug-in, if a Custom Plug-in Update exists, an icon is displayed beside the version identifier, indicating that that particular plug-in version is customized in the environment, with a list of patches. Figure 1-1 displays the Custom Plug-in Update icon.

18.9 Troubleshooting

This section contains information on troubleshooting plug-in related issues. The following sections are covered in this section:

• Understanding Plug-In Homes

• Troubleshooting OMS Plug-In Deployment and Upgrade Issues

  • Troubleshooting OMS Plug-In Deployment Issues

  • Rollback and Resume OMS Plug-In Upgrade

• Troubleshooting Management Agent Plug-In Deployment and Upgrade Issues

  • Troubleshooting Management Agent Plug-In Deployment Issues

  • Troubleshooting Management Agent Plug-In Upgrade Issues

18.9.1 Understanding Plug-In Homes

Plug-in homes are essentially Oracle homes that are dedicated for plug-ins. The plug-in home for plug-ins deployed to the OMS is different from the plug-in home for plug-ins deployed to the Management Agent. Each plug-in home will be its own ORACLE_HOME with a dependency on the OMS. Since plug-in homes are registered in the oraInventory, they should not be manually deleted or manipulated.

Figure 18-12 shows the plug-in homes for plug-ins deployed to Enterprise Manager Cloud Control 12c Release 1 (12.1.0.1) (for OMS as well as for central agent).

Figure 18-12 Plug-In Homes for Enterprise Manager Cloud Control 12c Release 1 (12.1.0.1) (for OMS as well as for Central Agent)

Figure 18-13 indicates the plug-in home for plug-ins deployed to a standalone Management Agent of 12c Release 1 (12.1.0.1).

Figure 18-13 Plug-In Home for Standalone Oracle Management Agent 12c Release 4 (12.1.0.4)

Figure 18-14 indicates the plug-in home for plug-ins deployed to Enterprise Manager Cloud Control 12c Release 2 (12.1.0.2) or later (only for OMS).

Figure 18-14 Plug-In Homes for Enterprise Manager Cloud Control 12c Release 2 (12.1.0.2) (Only for OMS)

Figure 18-15 indicates the plug-in home for plug-ins deployed to a central agent and a standalone Management Agent of 12c Release 2 (12.1.0.2) or later.

Figure 18-15 Plug-In Home for Central Agent and Standalone Oracle Management Agent 12c Release 2 (12.1.0.2)

18.9.2 Troubleshooting OMS Plug-In Deployment and Upgrade Issues

If the deployment of a new plug-in fails, the system automatically recovers. When the automatic recovery is complete, all OMS instances are started. If the upgrade of an existing plug-in fails, manual system recovery is required.

This section provides troubleshooting tips related to the following topics:

• Troubleshooting OMS Plug-In Deployment Issues

• Rollback and Resume OMS Plug-In Upgrade

18.9.2.1 Troubleshooting OMS Plug-In Deployment Issues

If plug-in deployment to the OMS fails, first check the details of the deployment, using the following commands.

• If the OMS is down, use the following command.

  $emctl status oms -details

• If the OMS is running, use the following command.

  $emcli get_plugin_deployment_status

Note:

When the status of the OMS is displayed, review the log files that are displayed in the output.

It is recommended that you take a backup of the Repository in case of a failure in the Recovery.

Review the pluginca log file available in the following location. Use them to debug the issue, and if you raise a service request to Oracle Support, then make sure you append these to the service request.

$<OMS_HOME>/cfgtoollogs/pluginca/*

Note:

When you install an additional OMS by cloning an existing, running OMS instance, the plug-in deployed to the source OMS are automatically carried over to the cloned OMS as well. Therefore, you do not have to redeploy the plug-ins on the cloned OMS.

In case of multi OMS environment, the OMS_HOME in the log file path indicates the root folder of the OMS where the failure occurs.

For information about installing an additional OMS, refer to the Oracle Enterprise Manager Cloud Control Basic Installation Guide.

18.9.2.2 Rollback and Resume OMS Plug-In Upgrade

If plug-in upgrade fails, then do one of the following:

• Raise a Service Request to find out if there is a possibility of recovering from the current Management Repository.

• Rollback to the latest backup of the Management Repository.

• If you have not taken a backup of the Management Repository, diagnose and resolve the issue that is causing the plug-in upgrade to fail.

  Then, run the following command to resume the plug-in upgrade:

  $<OMS_HOME>/bin/emctl resume_plugin_upgrade

  This command automatically detects and resumes the last failed upgrade session. Once the plug-in upgrade succeeds, the OMS restarts automatically. The same deployment ID is updated with the current status of the operation. In case of a multi-OMS environment, the plug-in upgrade happens on the first OMS, and then on all other additional OMS instances.

• If flashback is enabled, the section number will be printed.

18.9.3 Troubleshooting Management Agent Plug-In Deployment and Upgrade Issues

This section provides troubleshooting tips related to the following topics:

• Troubleshooting Management Agent Plug-In Deployment Issues

• Troubleshooting Management Agent Plug-In Upgrade Issues

18.9.3.1 Troubleshooting Management Agent Plug-In Deployment Issues

If plug-in deployment to the Management Agent fails, then review the log file available in the following locations.

agent_inst/sysman/log/*

agent_inst/sysman/registry.xml

agent_inst/install/logs/*

18.9.3.2 Troubleshooting Management Agent Plug-In Upgrade Issues

If plug-in upgrade fails, then review the log file available in the following locations.

• To review the log files using the UI, follow these steps.

  1. From the Setup menu, select Extensibility, and then select Plug-ins.

  2. Select the preferred plug-in, and review the information displayed in the Recent Deployment Activities tab.

  3. Click the link in the Action column for the preferred Management Agent. From the Deployment Steps tab, select the job name. Selecting the job name opens the job details wizard.

• The detailed logs for Management Agent upgrade and deployment are available at the following location.

  agent_inst/install/logs/agentplugindeploy_N.log

  In the aforementioned location, N refers to the internal ID. Check the latest log files in the location.

• While filing an SR, upload the following log files.

  agent_inst/install/logs/*

  agent_inst/sysman/log/*

  agent_inst/sysman/registry.xml