Chapter 3. Upgrading and Removing Servers and Agents

3.1. Upgrading JBoss ON

An upgrade procedure for JBoss Operations Network essentially overlays the new JBoss ON packages and libraries over the existing configuration and databases. The upgrade procedure, then, is very similar to the installation process. The new packages need to be installed, and then the server is configured through the same setup script. The difference is that the server reuses its existing databases and data so that the configuration from the previous installation is preserved.

3.1.1. Upgrade Notes

  • It is not possible to revert your JBoss ON server to the previous version after it is upgraded. Back up all data before upgrading.
  • There will be a minimal loss monitoring data because of the downtime required when the server and agents are being upgraded. Additionally, any monitoring data for the JBoss ON server will be lost, if the server is included in the inventory.
  • The JBoss ON servers must be upgraded before the JBoss ON agents can be upgraded.
  • Upgrading the JBoss ON server essentially creates a new server instance that replaces the old instance. If the JBoss ON server was added to the inventory, then the old JBoss ON server resource must be deleted from the inventory because it will not be a usable resource after upgrade. Once the upgrade process is complete, then the JBoss ON server must be added to the inventory again and all of the previous configuration for that resource (like alerts, scheduled operations, and group membership) must be redone.
  • All JBoss ON servers in the high availablity cloud must be stopped when one is upgraded. Otherwise, the installer will hang when it tries to contact the database and the database is unavailable because it is in use by another JBoss ON server.
  • Do not copy the new server installation on top of a previous server installation.
  • On Windows. When configuring JBoss ON servers as services on Windows, it was possible to set the RHQ_SERVER_RUN_AS parameter without setting a password. In JBoss ON 3.2, the RHQ_SERVER_PASSWORD parameter is required with the RHQ_SERVER_RUN_AS parameter.

3.1.2. About the Upgrade Script

As with installation (Section 2.6, “About the rhqctl Script”), the rhqctl script is used to manage server migrations. The upgrade command, much like the install command, handles all three management components on the server system:
  • Upgrades the JBoss ON server
  • Upgrades the JBoss ON agent
  • Installs and configures a new storage database node for monitoring data
The upgrade script requires the original location of the server and agent directories.
Probably the most critical option is the ability to migrate monitoring data to the new monitoring database (--run-data-migrator). If this is not done, then none of the previous monitoring information is visible or accessible through JBoss ON.

Table 3.1. Options for Upgrading JBoss ON

Option Description
--start Starts all services as soon as the upgrade process is complete.
--server | --storage | --agent Upgrades the specified component only, rather than all management components.
--from-server-dir directory Gives the directory path to the server to be upgraded.
--from-agent-dir directory Gives the directory path to the agent to be upgraded. The upgrade script assumes that the agent is installed in the same directory as the server, in a subdirectory named rhq-agent/. If the agent is in a different location, then this option is required.
--run-data-migrator none | estimate | print-command | do-it Migrates the data from an existing JBoss ON SQL database into a new monitoring storage database. The upgrade command creates the monitoring database. If this option is not used, than any previous monitoring data are lost.
The options allow anestimate to be made of the run time (which can be hours for large databases), to print the manual commands to migrate the data, or to run the migration.

3.1.3. Upgrading the JBoss ON Server and Components

Not every step in this upgrade procedure applies to every JBoss Operations Network installation. Just run through the steps in order, and perform the ones necessary for your deployment.


To make the migration process go faster, deploy multiple storage nodes before upgrading the server. This is covered in Section 2.10, “Installing Storage Nodes Before Installing the Server”.


It is not possible to revert your JBoss ON server to the previous version after it is upgraded. Back up all data before upgrading.
  1. Stop the JBoss ON agent running on the server machine. Agents installed with the server are not autoupdated and must be updated with the JBoss ON server. All other agents will update themselves automatically when the server is upgraded.
    This is done by stopping the agent service or by using the exit command at the agent command prompt.
    [root@server ~]# agentRoot/rhq-agent/bin/ 
    > exit
  2. Windows only. If the RHQ_AGENT_RUN_AS or RHQ_AGENT_RUN_AS_ME parameter was set in the agent's rhq-agent-env.bat file, then there must be a password and the password prompt must be disabled.


    If one of the RHQ_AGENT_RUN_AS* parameters is set without a password, then the agent upgrade process hangs.
    Alternatively, the RHQ_AGENT_RUN_AS* parameter can be removed prior to upgrading.
  3. Clean up the JBoss ON configuration. It is easier to clean up the configuration before migration than it is after.
    1. Remove any unused or out of service platforms from the inventory.
    2. If the older JBoss ON server was added to the JBoss ON inventory, then remove it. The old JBoss ON server must be removed from the inventory because it is no longer a usable resource.
  4. Stop the JBoss ON server which is being upgraded as well as any currently running JBoss ON instances in the cloud. For example:
    [root@server ~]# serverRoot/jon-server-3.1.0.GA/ stop


    If the upgraded JBoss ON server will use a database that existing JBoss ON instances are also using, then all of the existing JBoss ON instances have to be stopped. Otherwise, the installer will hang when it tries to contact the database and the database is unavailable because it is in use by another JBoss ON server.
  5. Back up the server database before going through the upgrade script. In case there is a problem with the upgrade process, the backup allows you to restore to its previous state.
  6. Unzip the server packages.
    [root@server ~]# unzip -d serverRoot/jon-server-3.2.0.GA


    Do not copy the new server installation on top of a previous server installation.
    The directory structure within the server package gives the new server installation directory a version-specific name, such as /opt/jon/jon-server-3.2.0.GA.
  7. Optional. Copy over any changes in the original file to the new file. Changes to this file include things like setting up SSL and enabling SMTP for email notifications.
    Copy over the changes to the properties file only — do not copy over the entire file. The new properties file contains new configuration parameters; overwriting those new parameters could cause the server not to start.
  8. Run the rhqctl script with the upgrade subcommand. The required attributes are listed in Table 3.1, “Options for Upgrading JBoss ON”. For example:
    [root@server ~]# ./serverRoot/jon-server-3.2.0.GA/bin/rhqctl upgrade --from-server-dir /opt/rhq/rhq-server-old --from-agent-dir /home/rhq/rhq-agent-old --run-data-migrator do-it
    The upgrade command installs and configures a storage database automatically as part of upgrade; the --run-data-migrator do-it option migrates the existing monitoring data into the new database. Otherwise, all the historical monitoring data would be lost.


    For large databases, it can take hours to migrate monitoring data. Consider performing a migration during an extended period of low use.
    To see roughly how long the migration will take, as part of planning, run the upgrade command with the --run-data-migrator estimate option to get a time estimate.


    It is possible to migrate the historical monitoring data by running the upgrade with the --run-data-migrator later. However, any new monitoring data collected between the server upgrade and the data migration will be lost.
  9. Additional plug-in packs for specific needs (such as supporting management tasks for EWS, EAP, and SOA-P) are available to be installed separate from the core JBoss ON agent packages. Each plug-in pack as at least one (and sometimes more than one) agent plug-in. Each zip file for the plug-ins has a README.txt file with specific setup instructions.
    The plug-in files can be unzipped anywhere. For example:
    [root@server ~]# unzip -d /opt/jon/jon-server-3.2.0.GA


    If there are multiple JBoss ON servers in a high availability setup, the agent plug-in pack only has to be installed once. The other servers will pick up the plug-ins as part of the high availability polls.
  10. Start the JBoss ON server and agent.
    [root@server ~]# serverRoot/jon-server-3.2.0.GA/bin/ start
  11. Optional. Add the new JBoss ON server as a resource in the inventory.