Skip to end of metadata
Go to start of metadata

Upgrading the Server

This page is for upgrading or re-installing an existing RHQ Server. To install a new RHQ Server go to Installing the Server.

RHQ does not support mixed-versions among running components. When upgrading RHQ, all RHQ components upgraded with rhqctl must be brought down and upgraded before returning to service.

This does not include those RHQ Agents prepared for auto-update - those will not need to be shutdown. They will auto-update when they connect to the new servers.

Loss of Data
Loss of minimal monitoring data is inevitable given the down-time involved in shutting down instances of the RHQ Agents during the upgrade process. In addition, if you have a resource in inventory corresponding to the RHQ Server itself, upgrading RHQ will entail the loss of all data for that RHQ Server resource.

Before you Upgrade

Perform the following steps prior to your upgrade. The server should still be running until the step instructing to shut it down.

Please review all of the information at Windows Installation prior to upgrade on Windows.

Stop the RHQ Agents monitoring the RHQ Servers and RHQ Storage Nodes

RHQ Agents monitoring your RHQ Servers and RHQ Storage Nodes should be stopped prior to upgrade. Unlike remote agents, they are upgraded as part of the rhqctl --upgrade command itself.

Pre RHQ 4.8 upgrades
Versions prior to RHQ 4.8 did not have the rhqctl utility. If an RHQ Agent is running locally, monitoring the RHQ Server, it must be stopped prior to upgrade:
  • Stop a pre RHQ 4.8 Agent via the agent wrapper's stop command, the quit prompt command, or the RHQ Agent resource operation.
  • When upgrading, use the --from-agent-dir option.

Stop the RHQ Agents via the rhqctl --stop command.

Wait for the agents to fully stop before continuing. Note that remote agents will typically auto-update upon connection with an upgraded server, unless configured otherwise.

Remove unwanted platforms from inventory

It is most efficient to remove "out of service" platform resources prior to the upgrade. If you have machines you have stopped, decommissioned or will stop monitoring then stop any RHQ Agents that are still running on those machines. Then, via the RHQ GUI, uninventory the platforms that are no longer relevant.

Remove all RHQ Server resources from inventory (optional)

Because the upgrade will replace the RHQ Servers, any currently imported RHQ Server resources will no longer be available after the upgrade. New RHQ Server resources will be discovered and can be subsequently imported.

If, for some reason, you prefer to keep the old RHQ Server resources then ignore this step. They will have DOWN availability after the upgrade but can be uninventoried later, if so desired.

Stop All RHQ Servers and RHQ Storage Nodes

Note that all RHQ Agents monitoring RHQ Servers and RHQ Storage Nodes should already have been stopped.

  1. Stop the RHQ Servers.
    Pre RHQ 4.8 upgrades on Windows
    If you are running a pre RHQ 4.8 RHQ Server as a Windows service, uninstall the Windows service:
  2. Stop the RHQ Storage Nodes after the servers are down.
    This is only relevant to RHQ 4.8 and later. Note that rhqctl stop will stop all RHQ components previously installed with rhqctl which includes RHQ Server, RHQ Storage Node, and RHQ Agent installations.
  3. Do not stop the RHQ database - ensure it is still running.
  4. Do not delete the existing RHQ Server directory, it is used during the upgrade.
    • The rhqctl upgrade will merge the old into the new so you probably will not need to worry about merging them yourself. However, you will probably want to make sure most, if not all, values you had in the old properties file are the same in the new after the upgrade.
    • In the rare case that you customized the old bin/ (if on UNIX/Linux) or bin/wrapper/rhq-server-wrapper.conf (if on Windows) files, back them up because you will need to reapply those changes manually.

Backup your RHQ Database (recommended)

You should strongly consider backing up your database prior to proceeding. In case problems arise during the database upgrade, having a backup will allow you to restore to your previous state. Not doing so risks a potential loss of all prior data.

Prepare the New RHQ Server Distribution

Unzip the distribution to the directory within which it will be executed from, e.g.:

cd /opt/rhq
The new installation should not be copied on top of a previous installation. It is recommended to unzip to the same parent directory (e.g. /opt/rhq), making it a sibling root directory to the the existing install. All RHQ distribution zip files have a directory structure that ensure their content is extracted into a version-specified directory (e.g. "rhq-server-4.10.0") so this usually isn't a problem unless you are attempting to reinstall the same version as was previously installed. For example, the above commands will create a directory named /opt/rhq/rhq-server-4.10.0

Upgrade the RHQ Server

Because the upgrade will merge old settings into the new environment it should not be necessary to alter any properties in the newly unzipped server.

If for some reason you do need to edit prior to the upgrade:

  • Do not set rhq.autoinstall.database to the value of "overwrite" since this will purge all the RHQ data in the database and effectively make this a new, clean install and not a true upgrade. Note that the rhqctl control script will attempt to set this value to "auto" so an overwrite is not mistakenly performed.
  • Do make sure you set to the original server's name - that is, this should be the same server name of the server you are upgrading. If the previous installed server left this blank, you can leave this blank as well, but you must ensure that the hostname/domain of the machine has not changed. If that did change, you must explicitly put the old name of the server as the value of this property. If this name does not match the previous server's name, you will effectively be adding another server to the RHQ HA Cloud, which is not what you want to do when simply upgrading an already existing server. Again, rhqctl will attempt to merge the old value in the old file to the new file, so you really should not have to do anything.
    • If you aren't sure what the name was, you can ask the server installer to give you a list of all existing servers currently registered in the RHQ system. You do this via the --listservers (aka -l) command line option to the rhq-installer script:

rhqctl upgrade

The RHQ Server upgrade is performed via the <rhq-install-dir>/bin/rhqctl upgrade command. Please review the command options before continuing.

In particular the --from-server-dir option is required. It specifies the install directory of the RHQ Server you are upgrading from and it is there that settings will be merged. For example, if your old server was installed at /opt/rhq/rhq-server-4.9, you will want to use the option "--from-server-dir /opt/rhq/rhq-server-4.9"

RHQ 4.8 Upgrades (only)

The storage node in 4.8 included native libraries for different things like data compression. If your platform has support for those native libraries, then compression was used by default on the data files. In 4.9, the native libraries have been removed in an effort to provide better cross-platform support. Compression has to be turned off in 4.8 before upgrading; otherwise, the storage node will not run in 4.9. Download the patch zip file here. Unzip the file and follow the instructions in the .sh/.bat file.

The patch script runs the CQL Shell for Apache Cassandra cqlsh which requires python 2.5, 2.6 or 2.7 to run. The script also runs nodetool which requires JRE 1.7 set as the JAVA_HOME.

Pre RHQ 4.8 Upgrades (only)

There are some important things to note when upgrading pre RHQ 4.8 servers. In particular, the upgrade will involve the initial installation of an RHQ Storage Node (unless --use-remote-storage-node is specified). And every RHQ Storage Node requires an RHQ Agent to manage it. In addition, if you wish to retain your old measurement data, you will need to run the data migrator tool to transfer the old measurement data from your RDBMS database to the new storage backend.


Starting in RHQ 4.8 the RHQ Agent will be installed for all servers co-located with an RHQ Storage Node, which is the default. The Agent will be installed to a fixed directory, which is the parent directory of the new server installation (making it a sibling directory).

For Pre RHQ 4.8 upgrades use the --from-agent-dir option to specify the old agent location, if it exists. For example, if you are upgrading an older agent located at /home/rhqproject/rhq-agent, you would need to specify the option "--from-agent-dir /home/rhqproject/rhq-agent" in order to upgrade that agent. The new agent will remain in that location.

Use the --from-agent-dir option even if the agent exists in what will become the default, fixed location.

Configuring the RHQ Storage Node

  1. To alter any defaults for the RHQ Storage Node create a <rhq-install-dir>/bin/ file. In this file you can specify any of the RHQ Storage Node --storage-config options. These include the directories for data storage, host and port information, and several other options.

Data Migrator

While optional, if you do not run the data migrator tool, all of your old measurement data from the old install will no longer be available. If you wish to retain your historical measurement data, you need to run the data migrator tool. The rhqctl upgrade command provides an option --run-data-migrator. That option gives you things such as: the ability to run the data migration tool as part of the upgrade, or an estimate of how long data migration would take, or the full command you need to use to run the data migration manually, or the ability to skip the data migration all together.

See the RHQ Control Script page for more on this option.

Windows Service Account

On Windows the RHQ Server, RHQ Storage Node, and RHQ Agent will be installed as Windows Services. See more here before installing.

Because the upgrade may result in new Windows services, it is important to ensure the services will be run as the desired user. Set the required environment variables as needed.

Executing the rhqctl upgrade command

When all of the above steps have been completed the upgrade command can be executed:

cd <new-install-dir>/bin
./rhqctl upgrade --from-server-dir <old-install-dir> [--from-agent-dir <old-agent-dir>] [options]

This will:

  • Merge the old RHQ Storage Node settings into the RHQ Storage Node, or install a new RHQ Storage Node, and start the RHQ Storage Node.
  • Merge the old RHQ Server settings into the new RHQ Server and start the RHQ Server.
  • Update the old RHQ Agent or install a new RHQ Agent if necessary, and start the RHQ Agent.
During the upgrade you may see error messages similar to the following in the console. These error messages are harmless.

Repeat for Each HA Server

Upgrade each RHQ Server in your HA installation. If you run only a single RHQ Server you can skip this step.

Install the new version of the RHQ Agent to each Agent machine.

Follow the Manually Upgrading the Agent instructions if you need to manually upgrade your agents. If your agents will auto-update themselves, you don't have to do anything for this step.

Start up the new Server and Agents.

rhqctl upgrade will not, by default, leave the upgraded services running. Specifying the --start option will ensure the upgraded services are started after upgrade but otherwise the services must be started via the following command. See Running the RHQ Server for more details:

cd <new-install-dir>/bin
rhqctl start
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.