JBoss Community Archive (Read Only)

RHQ 4.9

Manually Upgrading the Agent

These instructions are for upgrading an RHQ agent on a managed machine. Do not use these instructions for upgrading agents that are on the same machine as RHQ Server or RHQ Storage Node installations. Use rhqctl to upgrade agents when co-locating agents with RHQ Servers and/or RHQ Storage Nodes.

Agent Auto-Updating

Since RHQ 2.2, agents have the ability to auto-update themselves. So, under most conditions, it isn't necessary to manually upgrade agents. However, if the auto-update fails for some reason or you disabled agent auto-update and you want to manually upgrade yourself, you need to follow the steps below.

If you need to manually upgrade a RHQ Agent (i.e. you do not want or cannot utilize the agent auto-upgrade capabilities), then follow these steps below. You will need to follow these steps if you are upgrading the RHQ Agent to version 2.2 or earlier.

All agents must be upgraded at the same time and they must be at the same version level as your RHQ Servers. Having agents of differing versions in your RHQ environment or of versions that don't match your RHQ Server is not supported.

  1. Shutdown your RHQ Agent.

  2. If you are running the agent on Windows and as a Windows service, uninstall the Windows service:

    cd <old-agent-install-dir>/bin
    rhq-agent-wrapper.bat remove
  3. Make sure you upgraded the RHQ Server.

  4. Restart your upgraded RHQ Servers if they are not yet started.

  5. If the current RHQ Agent that is to be upgraded is at version 2.2 or newer:

    • Download the agent update binary from the server

    • Copy the agent update binary .jar file into the parent directory where your agent is installed. For example, if your agent is installed in /opt/rhq-agent-parent/rhq-agent, copy the agent update binary .jar file to the /opt/rhq-agent-parent directory.

    • Extract the new RHQ Agent from the agent update binary by running the following command:

      java -jar <agent-update-binary.jar> --upgrade

      This will tell the agent update binary to extract the RHQ Agent distribution and update your currently existing agent that is found in "rhq-agent" subdirectory. At this point, you will have a fully upgraded RHQ Agent located in the original "rhq-agent" directory. The old agent has been backed up to the "rhq-agent-old" directory. If the upgrade encounters errors, you'll find log files that contain log messages that can help to diagnose the problem.

      For additional help on running the agent upgrade binary (such as to see a full list of all command line arguments/options), run the following:

      java -jar <agent-update-binary.jar> --help
  6. If the current RHQ Agent that is to be upgraded is older than version 2.2:

    • Follow the instructions to install a RHQ Agent here: RHQ Agent Installation

    • If you had your own keystore and truststore files, make sure you copy them over from the old agent installation to the new agent installation

    • If you had your own customizations to the agent script files, you will need to merge them into the new agent scripts. Note that you should no longer modify rhq-agent.bat,sh or rhq-agent-wrapper.bat,sh - instead, any environment modifications should be made to rhq-agent-env.bat,sh. This is discussed further here and here, but in short, any customizations you need to make to the agent launcher scripts should be done in rhq-agent-env.bat,sh.

  7. (optional) If you need to reconfigure the RHQ Agent before you restart it, read the documentation at RHQ Agent Installation that talks about configuring and reconfiguring the agent. Typically, you won't have to reconfigure the agent - the agent will pick up its previous configuration and update it as necessary.

  8. Finally, start the RHQ Agent.

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-13 08:48:03 UTC, last content change 2013-09-18 19:43:30 UTC.