Red Hat Training

A Red Hat training course is available for Red Hat JBoss Operations Network

4.3. Upgrading a 3.1.x Server and Server Plug-ins

JBoss ON 3.1.2 and later can be upgraded to JBoss ON 3.3. Earlier JBoss ON 3.1 servers must first be upgraded to 3.1.2, and they then can be upgraded to JBoss ON 3.3.
Not every step in this upgrade procedure applies to every Red Hat JBoss Operations Network installation. Run through the steps in order, and perform the ones necessary for your deployment.
Warning
It is not possible to revert your JBoss ON server to the previous version after it is upgraded. Back up all data before upgrading.
Note
To make the migration process go faster, deploy multiple storage nodes before upgrading the server. This is covered in Section 3.11, “Installing Storage Nodes Before Installing the Server”.
  1. For older 3.1 versions, upgrade to JBoss ON 3.1.2 or the latest release.
  2. Stop the JBoss ON agent running on the server machine. If the agent is running as a service, then stop the system service. It is also possible to stop it at the command prompt: 
    [jsmith@server ~]$ agentRoot/rhq-agent/bin/rhq-agent.sh
> exit
  3. 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
    Note
    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.
  4. Clean up the JBoss ON configuration. 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.
  5. Stop all servers. For example: 
    [jsmith@server ~]$ serverRoot/jon-server-3.1.2.GA/rhq-server.sh stop
    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.
  6. Windows only. If the server is running as a service, uninstall that service. 
    C:> cd C:\jon\jon-server-3.1.2\bin
C:\jon\jon-server-3.1.2\bin> ./rhq-server.bat remove
  7. 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.
  8. 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.
  9. 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.
  10. Run the upgrade command.
    There are three critical options that can be used with the upgrade command:
    • One option is always required: --from-server-dir, which identifies the original server's installation directory.
    • If there is a local agent, then the --from-agent-dir is also required. If there is no agent, one will be installed when installing the storage node. By default in 3.3, this is installed within the same parent directory as the server's installation directory (such as /opt/jon).
    • Decide where to host the new storage node. The upgrade command will create a new local storage node by default. Alternatively, a storage node can be created first; the storage node configuration is then added to the properties file and signaled with the --use-remote-storage-node option.
    For example, this runs the upgrade for a local server and agent and creates a new local storage node: 
    [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
    To use a remote storage node:
    1. On a different system, create the new storage node, as in Section 3.11, “Installing Storage Nodes Before Installing the Server”.
    2. Edit the new rhq-server.properties file to point to the new storage node. 
      rhq.storage.cql-port=9142
rhq.storage.gossip-port=7100
rhq.storage.seeds=192.168.0.1, 192.168.0.2, 192.168.0.3
start=false
    3. Run the upgrade script with the --use-remote-storage-node option. 
      [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 --use-remote-storage-node
  11. After upgrading to JBoss ON 3.3, to alter any defaults for the storage node, create a serverRoot/jon-server-3.3.2.GA/bin/rhq-storage.properties. This file can be used to set any --storage-config options. These include the directories for data storage, host and port information, and several other options.
  12. Upgrade 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
  13. Important. Migrate the historical monitoring data.
    There is a command-line script available to migrate all existing monitoring data. In most cases, this should be run at the same time the server is migrated.
    Note
    For large databases, it can take hours to migrate monitoring data, and the process must not be interrupted. Consider performing a migration during an extended period of low use.
    The data migrator tool can provide an estimate of how long the migration will take, to assist with planning.
    If the data migrator tool is not run, all of the measurement data from the old server is no longer available. Also, if there is a large gap between when the server is upgraded and the data migration is run, any new monitoring data collected between the server upgrade and the data migration will be lost. 
    [jsmith@server ~]$ ./rhq-data-migration.sh
  14. Check the rhq-server.properties file to make sure any edits were properly merged in. While this merge process should migrate all the values properly, it is still good practice to verify that the old properties file have been properly copied into the new properties file after the upgrade has completed.
  15. If the rhq-server.sh or rhq-server-wrapper.conf files were customized, reapply any changes.
  16. Optional. Additional 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.
    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
  17. Start the server, agent, and storage node. 
    [jsmith@server ~]$ serverRoot/jon-server-3.3.2.GA/bin/rhqctl start
  18. Optional. Add the new JBoss ON server as a resource in the inventory.
Report a bug