4.4. Upgrading a 3.2 Server, Storage Nodes, and Server Plug-ins

Procedure 4.1. Prepare the Current Installation For Upgrade

1. Stop the JBoss ON agent running on the server machine.

   [jsmith@server ~]# serverRoot/jon-server-3.2.0.GA/bin/rhqctl stop --agent

   Agents installed with the server must be updated with the JBoss ON server. All other agents will update themselves automatically when the server is upgraded.
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.

   RHQ_AGENT_PASSWORD=secret
   RHQ_AGENT_PASSWORD_PROMPT=false

   Important
   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 inventory. It is easier to clean up the configuration before migration than it is after.
   • Remove any unused or out-of-service platforms from the inventory.
   • 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 all servers and storage nodes.
   Stop the JBoss ON server which is being upgraded as well as any currently running JBoss ON instances in the cloud.
   Important
   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.

   [jsmith@server ~]# serverRoot/jon-server-3.2.0.GA/bin/rhqctl stop

5. Back up the server database and its associated rhq-data directory before running the upgrade script.
   If a problem with the upgrade process occurs, these backups allows you to restore JBoss ON to its previous state.
   Warning
   It is not possible to revert your JBoss ON server to the previous version after it is upgraded.

   • Back up the database.
   • Back up the rhq-data directory on each rhq-storage node.

   Backing up these parts of your JBoss ON installation will allow you to restore back to the previous environment.

Procedure 4.2. Upgrade Each Standalone Storage Node

1. Stop all 3.2 processes for the storage node and agent.

   [jsmith@server ~]# serverRoot/jon-server-3.2.0.GA/bin/rhqctl stop

2. Unzip the server packages.

   [jsmith@server ~]# unzip jon-server-3.3.2.GA.zip -d serverRoot/jon-server-3.3.2.GA

   Important
   Do not copy the new server installation on top of a previous server installation.

   Do not delete the existing JBoss ON installation directory, since it is used during the upgrade. rhqctl upgrade merges the old rhq-server.properties file into the new rhq-server.properties file.
   The directory structure within the server package gives the new server installation directory a version-specific name, such as /opt/jon/jon-server-3.3.2.GA.
3. Verify all Database properties are correctly set in serverRoot/jon-server-3.2.0.GA/bin/rhq-server.properties. See Section 3.6.2, “Attributes in the Properties File” for the database properties required.
4. Run the upgrade script.

   [jsmith@server ~]# serverRoot/jon-server-3.3.2.GA/bin/rhqctl upgrade --from-server-dir serverRoot/jon-server-3.2.0.GA

   Note
   If a storage node is on the same system, those storage nodes will be upgraded with the upgrade is issued to the JBoss ON server. Standalone (storage nodes not co-located with a JBoss ON server) still require individual upgrades.

Procedure 4.3. Upgrade Each Server

1. If the rhq-server.sh or rhq-server-wrapper.conf files have been customized, back up those files. Changes made to these files must be reapplied manually after the upgrade script is run.
2. Run the rhqctl script with the upgrade subcommand. For example:

   [jsmith@server ~]# ./serverRoot/jon-server-3.3.2.GA/bin/rhqctl upgrade --from-server-dir /opt/rhq/rhq-server-old --from-agent-dir /home/rhq/rhq-agent-old

   The --from-server-dir option is required to identify the server being migrated.
3. Check the upgraded rhq-server.properties file against the pre-upgrade server's copy to make sure any edits were properly merged in. It is good practice to verify that the old properties file has been properly copied into the new properties file at this step of the upgrade process.
4. If the rhq-server.sh or rhq-server-wrapper.conf files were customized, reapply any changes.
5. Download and expand Plug-in packs separately before proceeding.
   Plug-in packs for specific needs (such as supporting management tasks for other layered Red Hat JBoss Middleware products) are available for installation separate from the core JBoss ON packages.
   See Section 3.7, “Basic Setup: Installing the Server on Linux” or Section 3.8, “Basic Setup: Installing the Server on Microsoft Windows” for instructions to download Agent Plug-in packs.
   Each plug-in pack has 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.
   Note
   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.
   The plug-in files can be unzipped anywhere. For example:

   [jsmith@server ~]# unzip jon-plugin-pack-agent_plugin_name-3.3.2.GA.zip -d /opt/jon/jon-server-3.3.2.GA

Procedure 4.4. Update the Storage Cluster Schema

1. Start all storage nodes. Do not start any servers or agents.

   [jsmith@server ~]# serverRoot/jon-server-3.3.2.GA/bin/rhqctl start --storage

2. On a JBoss ON server system, re-run the upgrade command with the --storage-schema option. The command only has to be run once for the storage schema changes to be propagated to the storage cluster.

   [jsmith@server ~]# serverRoot/jon-server-3.3.2.GA/bin/rhqctl upgrade --storage-schema

Procedure 4.5. Upgrade Each Agent Not Configured for Auto-Update

1. Click Section 6.7, “Manually Upgrading the JBoss ON Agent” and follow the direction to upgrade each Agent.
2. Return to this procedure once you have completed the Agent Upgrade steps.

Procedure 4.6. Start the Upgraded Installation

1. Start the server, agent, and storage node.

   [jsmith@server ~]# serverRoot/jon-server-3.3.2.GA/bin/rhqctl start

2. Optional. Add the new JBoss ON server as a resource in the inventory.