Upgrade Hyperic Agent

About this page...

This page has instructions for upgrading the Hyperic Agent to 4.6. Before performing the steps on this page, see Hyperic Upgrade Processes for information about upgrade options and other steps in the upgrade process.

If you want to configure your 4.6 agents for a user-managed keystore, see the information in the Upgrade Server and Agent with User-Managed Keystores section of Hyperic Upgrade Processes.

Agent Upgrade Methods

To upgrade a Hyperic 4.x Agent to 4.6 you can either:

Push Agent Bundle from the vFabric Hyperic Server

Available only in vFabric Hyperic

You can update one or more Hyperic Agents by pushing the new bundle to it from the Hyperic Server, using the Hyperic user interface. The bundle must reside in the ServerHome/hq-engine/hq-server/webapps/ROOT/WEB-INF/hq-agent-bundles directory.

The agent upgrade command is available on the Views tab for an Hyperic Agent (or a group of agents). For more information see Start, Stop, and Other Agent Operations in vFabric Hyperic Configuration.

Note: When you update an agent bundle, the configuration settings in the agent's AgentHome/conf/agent.properties file are not changed. However, the first time you start an agent that you have updated to 4.6.6 or later, passwords specified in the file will be encrypted.

Agent Name Unchanged by Bundle Upgrade Process

Note that if you upgrade a 4.x agent by pushing a new bundle from the Hyperic Server, the name of the agent is not changed. So, an agent name that contains the Hyperic version number — as is the default naming convention — reflects the originally installed version, rather than the version to which it has been upgraded. For example, if you push a 4.6 bundle to an agent whose name is "HQ Agent 4.5", the agent name will remain "HQ Agent 4.5".

Upgrade Agent Bundle Manually

Follow these steps if you wish to manually upgrade the agent bundle in your agent installation, instead of pushing the bundle from the Hyperic Server.

Note: When you update an agent bundle, your previous agent configuration is preserved — the AgentHome/conf/agent.properties file is not overwritten.

  1. Copy the agent bundle (agent-4.x.y-nnn.tgz or agent-4.x.y-nnn.zip) from



  2. Unpack the agent bundle.

  3. Edit the rollback.properties file in AgentHome/conf to specify the location of the new agent bundle and the bundle it will supersede.





    Name of directory with the new bundle, without full path specification.



    Name of directory with the old bundle (the one you are upgrading from), without full path specification.


  4. Restart the agent. For instructions, see Start, Stop, and Other Agent Operations in vFabric Hyperic Configuration.

If the upgrade to the new agent bundle fails, an attempt will be made to start the agent using the old agent bundle.

You can determine whether the upgrade was successful and what version you are running by looking at the log files in AgentHome/logs.

Create a Custom Agent Upgrade Bundle

This section describes how to create a custom agent bundle. Pre-configuring the agent eases the process of upgrading multiple agents. For additional information, see Install Hyperic Agents in Volume.

  1. Back up an existing agent located in:

    • For example:

      cp ServerHome/hq-engine/hq-server/webapps/ROOT/WEB-INF/hq-agent-bundles/agent-4.5.0-EE-nnn.tgz
  2. Extract the bundle. For example:

    tar xzf ServerHome/hq-engine/hq-server/webapps/ROOT/WEB-INF/hq-agent-bundles/agent-4.5.0-EE-nnn.tgz
    • This results in a new directory corresponding to the agent bundle, like this:

  3. Update the contents of expanded directory. For instance, you could add custom plugins to the plugins directory:

  4. Rename expanded directory to the name of custom agent bundle. For example:

    mv ServerHome/hq-engine/hq-server/webapps/ROOT/WEB-INF/hq-agent-bundles/agent-4.5.0-EE-nnn
  5. Pack up agent bundle, using the directory name from from the previous step as the tarball file name. For example:

    tar cvf ServerHome/hq-engine/hq-server/webapps/ROOT/WEB-INF/hq-agent-bundles/my-bundle.tar
    gzip ServerHome/hq-engine/hq-server/webapps/ROOT/WEB-INF/hq-agent-bundles/my-bundle

Upgrade Agent Using a Full Agent Package

These instructions apply to both Hyperic HQ and vFabric Hyperic.

To upgrade an Hyperic 4.x Agent using full the agent package:

  1. Stop the 4.x agent.

  2. Preserve the existing agent configuration.

    • Back up the agent.properties file from your previous installation. The default location for agent.properties in 4.x installations is the AgentHome/conf directory.

    • Note: In some Hyperic environments, agent.properties is stored in an alternative location that eases the process of automating the deployment of multiple agents. On Unix-based platforms, that location is the .hq subdirectory of the home directory of the user that runs the Agent. If your agent configuration is stored in that location, it will not be over-written by the new installation.

  3. If the agent runs on Windows, uninstall the agent service from a command shell in AgentHome/bin:

    hq-agent.bat remove
  4. Unpack the 4.y agent into the agent installation directory.

  5. Restore the backed up agent.properties file to AgentHome/conf (unless you keep the properties file in the .hq subdirectory of the home directory of the user that runs the agent.)

  6. Start the Hyperic Agent

    • On Unix-like platforms, enter this command in a shell:

      sh hq-agent.sh start
    • On Windows, install the new agent service and start the agent. In a command shell in AgentHome/bin enter:

      hq-agent.bat install
      hq-agent.bat start