Chapter 3. Upgrading and Removing Servers and Agents
3.1. Upgrading JBoss ON
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_ASparameter without setting a password. In JBoss ON 3.2, the
RHQ_SERVER_PASSWORDparameter is required with the
3.1.2. About the Upgrade Script
rhqctlscript 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
--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
|--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 |
|--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
- 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
exitcommand at the agent command prompt.
[root@server ~]# agentRoot/rhq-agent/bin/rhq-agent.sh > exit
- Windows only. If the
RHQ_AGENT_RUN_AS_MEparameter was set in the agent's
rhq-agent-env.batfile, then there must be a password and the password prompt must be disabled.
NoteIf 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.
- 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.
- 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/rhq-server.sh stop
ImportantIf 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.
- 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.
- Unzip the server packages.
[root@server ~]# unzip jon-server-3.2.0.GA.zip -d serverRoot/jon-server-3.2.0.GA
ImportantDo 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
- Optional. Copy over any changes in the original
rhq-server.propertiesfile 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.
- Run the
rhqctlscript with the
upgradesubcommand. 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-itThe
upgradecommand installs and configures a storage database automatically as part of upgrade; the
--run-data-migrator do-itoption migrates the existing monitoring data into the new database. Otherwise, all the historical monitoring data would be lost.
NoteFor 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 estimateoption to get a time estimate.
ImportantIt is possible to migrate the historical monitoring data by running the
--run-data-migratorlater. However, any new monitoring data collected between the server upgrade and the data migration will be lost.
- 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 jon-plugin-pack-agent_plugin_name-3.2.0.GA.zip -d /opt/jon/jon-server-3.2.0.GA
NoteIf 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.
- Start the JBoss ON server and agent.
[root@server ~]# serverRoot/jon-server-3.2.0.GA/bin/rhqctl.sh start
- Optional. Add the new JBoss ON server as a resource in the inventory.