Plugin Deployment and Management

Key Hyperic Plugin Management Features

Hyperic 4.6.5 product plugin management and deployment features ensure that all Hyperic 4.6.5 Agents reporting a Hyperic 4.6.5 Server run exactly the same product plugins as those deployed to the server. The key features are:

  • Plugin management interface — Plugin Manager is a user interface for deployment-wide management of product plugins. You use the Plugin Manager to deploy and manage plugins on the Hyperic Server and Hyperic Agents that report to the server. For more information, see About Plugin Manager below.

  • Server-Agent Plugin Synchronization (SAPS) — A Hyperic 4.6.5 Agent and the Hyperic 4.6.5 Server it reports to cooperate to ensure that the agent is running exactly the same set of plugins as the server. For more information, see About Plugin Sync at Startup below. SAPS is enabled by default, and can be disabled using the server.pluginsync.enabled property in the server's ServerHome\conf\server.conf file.

Version Requirements for Plugin Synchronization

In Hyperic 4.6.5, the SAPS process will not synchronize plugins on agents of an earlier version than the Hyperic Server. The Hyperic 4.6.5 Server can only synchronize plugins on agents running the same or later version. The Plugin Manager user interface indicates how many of the agents reporting to the server are in sync. If there are agents that are out-of-date, you can see which agents need upgrading. For more information, see ui-Administration.Plugin.Manager.

Plugin Administration Tasks

If you run Hyperic with SAPS enabled, you can use Plugin Manager to administer plugins on up-to-date agents throughout your Hyperic deployment. The primary tasks you perform are:

  • Deploy and update custom plugins — If you develop your own plugin, or customize a built-in plugin, use Plugin Manager to upload and deploy the new or modified plugin to the Hyperic Server and to all up-to-date agents in your deployment. Plugins you deploy with Plugin Manager are deployed to a directory external to the Hyperic Server's installation directory, so that they are not overwritten by a server upgrade. For more information, see Resource Plugin Deployment Directories below.

  • Remove plugins — For optimal Hyperic scalability, it is good practice reduce agent footprint by running only the plugins you use, and to remove a plugin if you have no resources of the types the plugin manages. You can remove one or more plugins from all up-to-date agents in your deployment with a single Plugin Manager command. (Prior to version 4.6, Hyperic releases did not provide a friendly mechanism for plugin removal; the suggested alternative was to configure each agent to include or exclude selected plugins, using the plugins.exclude or plugins.exclude agent properties. This method is still supported.)

Manual plugin deployment not supported

Prior to Hyperic 4.6, product plugins were manually deployed to agents and the Hyperic Server, separately, with no mechanism to determine or enforce consistency between the server and agents. In Hyperic 4.6 and later, manual plugin deployment is not supported — use Plugin Manager for all product plugin administration tasks.

Resource Plugin Deployment Directories

There are two product plugin deployment directories on the Hyperic Server:

  • ServerHome/hq-engine/hq-server/webapps/ROOT/WEB_INF/hq-plugins/ — This is the deployment directory for the standard plugins packaged with Hyperic Server.

  • user.dir/hq-plugins — When you deploy a custom plugin, or a customized version of a built-in plugin, Plugin Manager deploys it to the hq-plugins subdirectory of the current working directory of the Hyperic Server process. Custom plugins are deployed to a separate plugin directory, external to the server installation, so that they will not be overwritten when you upgrade the Hyperic Server. You can configure the server to store custom plugins in a different directory with the server.plugin.custom.dir property. For more information, see server.plugin.custom.dir.

On the Hyperic Agent all product plugins reside in the same directory — AgentHome/bundles/agent-x.y.z/pdk/plugins/ — which is where built-in plugins are installed, and where Plugin Manager deploys custom plugins, including customized versions of built-in plugins.

About Plugin Manager

Plugin Manager, available on the HQ Server Settings section of the Administration tab, is a user interface for deployment-wide management of product plugins. You can use the Plugin Manager to administer plugins on the Hyperic Server and on all up-to-date Hyperic Agents that report to the server.

Plugin Manager displays all plugins deployed to the Hyperic Server, and the status of each plugin on agents reporting to the server.

You can use Plugin Manager to upload new plugins, update existing plugins, and remove plugins. The changes you make are replicated on all up-to-date agents that report to the server. Note that plugins you upload must comply with plugin naming conventions, and may not be larger than 5 MB.

When you remove one or more plugins using Plugin Manager, all resources in inventory of types managed by the plugin are removed from inventory.

For information about using the Plugin Manager, see Manage Plugins with the Plugin Manager.

About Custom Plugin Deployment with Plugin Manager

When you upload a new or updated plugin with the Plugin Manager:

  1. The plugin is copied to the Hyperic Server's user.dir/hq-plugins directory.

  2. If a product plugin of the same name exists in the server's hq-plugins directory (likely to be the case if you are deploying a customized version of a built-in plugin), the version in user.dir/hq-plugins henceforth is loaded, rather than the version in the server's hq-plugins directory (ServerHome/hq-engine/hq-server/webapps/ROOT/WEB_INF/hq-plugins/).

  3. The Hyperic Server updates and restarts each up-to-date agent. Note that agent update and agent restart are asynchronous — the server processes two queues: one of agents that still need the update pushed, and one of those that have the update and need to be restarted.

    • The server pushes the new or changed plugins to all up-to-date agents, up to four at a time. A built-in throttle mechanism limits the number of agent update threads.

    • The server issues a restart command to each updated agent, up to 20 in parallel. A built-in throttle mechanism limits the number of agent restart threads.

About Plugin Removal with Plugin Manager

You can use the Plugin Manager to remove one or more plugins from the Hyperic Server and all up-to-date agents that report to the server.

When you remove a plugin:

  1. The plugin is removed from its deployment directory on the Hyperic Server.

  2. The plugin is removed from its deployment directory on each up-to-date Hyperic Agent reporting to the server, and each agent is restarted.

  3. All resources in inventory managed by the removed plugin are removed from Hyperic's resource inventory.

About Plugin Sync at Startup

Server-side and agent-side plugins can become out-of-sync if you manually add or remove plugins and do not apply updates consistently to the server and to every agent.

To detect plugin mismatches caused by inconsistent manual deployment, the Hyperic Server checks for out-of-sync plugins every time it starts up, and every time an agent connects to it upon agent start or restart. (The Hyperic Server does the post-startup checks five minutes after startup, so that any agents that were restarted while the server was down to sync their plugin inventory.) In the case of a mismatch between server-side and agent-side plugins, the Hyperic Server updates the agent.

The synchronization behavior described in the sections below apply only to up-to-date agents, as noted in Version Requirements for Plugin Synchronization.

About Plugin Sync at Server Startup

When the Hyperic Server starts up and loads the plugins in its deployment directories, it
compares the MD5 checksum of the plugins it loaded with the MD5 checksums in the plugin status report last received from each agent.

For a mismatch:

  • If an agent's last plugin status report included a plugin with the same name but different MD5 checksum than one that is currently deployed to the Hyperic Server, the server pushes its version to the agent.

  • If an agent's last plugin status report does not include a plugin that is currently deployed to the server (the agent did not load a plugin with the same name as one that the server loaded), the server pushes the plugin to the agent.

  • If an agent's last plugin status report included a plugin that is not deployed to the Hyperic Server (there is no plugin with the same name on the server), the server removes the plugin from the agent.

After updating the agent plugins appropriately, the server restarts the agent.

Disable Server-Agent Plugin Synchronization

SAPS is enabled by default. To disable SAPS, add the following line to ServerHome/conf/hq-server.conf:

server.pluginsync.enabled=false