3.8. 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 set up in the same setup wizard. The difference is that the server reuses its existing databases and data so that the configuration from the previous installation is preserved.
Upgrade to JBoss Operations Network 3.1.2 is only supported from JBoss ON 2.x versions and later.

NOTE

The JBoss ON servers must be upgraded before the JBoss ON agents can be upgraded.

WARNING

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.

3.8.1. Upgrading the JBoss ON Server

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.

WARNING

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.

TIP

See Chapter 7, Troubleshooting Installation and Upgrade if there are any problems during the upgrade process.
  1. First, do some prep work on 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. Remove any alert definitions which use conditions for obsolete metrics.
      For migrating to JBoss ON 3.1.2, there are four alert conditions — all for PostgreSQL databases — which should be removed:
      • User Time
      • Kernel Time
      • Physical Memory
      • Virtual Memory
  2. Prepare the JBoss ON agents for upgrade. Agents will auto-upgrade, meaning that when they detect that the server has a new version, the agent will request an update. Follow the instructions at Section 8.7, “About Agent Automatic Updates” to prepare the agent, and then just leave it running. The agent should be running in the background to upgrade properly, as in Section 8.4, “Running the JBoss ON Agent as a Service”.
    In some rare cases, the agent will be upgraded manually instead of upgrading itself. In that case, stop the agent before upgrading the server, and follow the instructions at Section 8.8, “Manually Upgrading the JBoss ON Agent”.
  3. Stop the JBoss ON server which is being upgraded as well as any currently running JBoss ON instances. For example:
    serverRoot/jon-server-3.1.2.0.GA1/bin/rhq-server.sh stop

    WARNING

    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.
  4. Open the server root directory. For example:
    cd /opt/jon
  5. Unzip the server packages.
    unzip jon-server-3.1.2.0.GA1.zip

    IMPORTANT

    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.1.2.0.GA1.
  6. Copy over any changes in your original rhq-server.properties file to the new file in serverRoot/jon-server-3.1.2.0.GA1/bin. Changes to this file include things like setting up SSL and enabling SMTP for email notifications.

    NOTE

    In JBoss ON 2.3.1 and older versions, the password to access the database is stored in plaintext. In JBoss ON 3.1.2, this password is hashed for security.

    TIP

    If you don't want to edit the rhq-server.properties file manually, you can change the server settings to the proper configuration in the Advanced Settings form during the server setup.
  7. 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:
    cd /opt/jon/jon-server-3.1.2.0.GA1
    
    unzip jon-plugin-pack-agent_plugin_name-3.1.2.0.GA1.zip

    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.
  8. Start the JBoss ON server. For example:
    serverRoot/jon-server-3.1.2.0.GA1/bin/rhq-server.sh start
  9. Back up your server database before going through the setup wizard. In case there is a problem with the upgrade process, the backup allows you to restore to its previous state.
  10. Open the web UI.
    http://hostname:7080
    As with a new installation, the installer opens after you log in.
  11. The setup process is the same as the initial setup procedure in Chapter 3, Installing and Upgrading the JBoss ON Server on Linux.

    WARNING

    Do not change any of the settings for the server, especially identifying information such as the Server Name field. This can cause errors during the upgrade process.
    When the database connection information is entered, the JBoss ON installer detects the existing JBoss ON database. This introduces a new field to the installer, prompting you for what to do with the existing database.
    Choose the default, Keep (maintain existing data). Do not choose Overwrite (lose existing data), or the installer will delete all of your JBoss ON data, including your inventory, monitoring history, alerts, and metrics.
  12. The Registered Servers lists every server in the server cloud. For upgrades and re-installs, this gives you the option to keep the existing server configuration (such as ports and notification settings) or to set new values. To preserve the settings, select the server from the registered servers list; otherwise, select New Server.
  13. Restart the browser after upgrade completes or force the browser to refresh, using Ctrl+F5.

    NOTE

    The browser caches an old session ID for the previous JBoss ON server installation. Attempting to open the GUI without refreshing the cache causes the login to fail and throws an error in the JBoss ON server logs:
    Exception:
    2012-05-23 16:37:08,046 ERROR [org.apache.catalina.connector.CoyoteAdapter] An exception or error occurred in the container during the request processing
    java.lang.NullPointerException
            at org.apache.catalina.connector.CoyoteAdapter.parseSessionCookiesId(CoyoteAdapter.java:507)
            at org.apache.catalina.connector.CoyoteAdapter.postParseRequest(CoyoteAdapter.java:449)
            at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:239)
    	... 8< ...
  14. Start any JBoss ON agents that were stopped for the upgrade process.
  15. 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.
  16. Optional. Add the new JBoss ON server as a resource in the inventory.

3.8.2. Migrating SNMP Settings

The SNMP settings are not migrated with the other server settings. These settings have to be restored manually after migration, and there are two ways to do this:
  • Run a SQL command to copy the settings from the database table for the old server instance into the table for the new instance.
  • Set the SNMP settings in the JBoss ON GUI.

3.8.2.1. Running SQL Commands to Migrate the SNMP Settings

  1. Open the administrative page, with the location admin/test/sql.jsp. For example:
    http://server.example.com:7080/admin/test/sql.jsp
  2. Run the command to migrate the SNMP settings:
    select property_key,property_value from RHQ_SYSTEM_CONFIG where property_key like 'SNMP%';
  3. Click the Execute SQL button.
  4. Reconfigure all of the SNMP alert notification senders.

3.8.2.2. Configuring SNMP Settings in the GUI

TIP

Take a screenshot of the SNMP settings before beginning the upgrade procedure, so that the image is available as a reference to re-do the SNMP settings.
  1. In the top menu, click the Administration tab.
  2. In the Configuration box on the left navigation bar, click the Plugins link.
  3. Click the Server Plugins tab.
  4. Click the name of the SNMP plug-in in the list.
  5. In the plug-in details page, click the Configure 'Alert:SNMP' link to open the configuration page for the plug-in.
  6. Click the EDIT button at the bottom of the configuration screen to make the fields active.
  7. All SNMP versions require the JBoss ON MIB OID (1.3.6.1.4.1.18016.2.1) and selected version, plus optional information to access the trap. Expand the version-specific configuration section and fill in the information about the SNMP agent.
  8. Once SNMP is set up for the server, reconfigure all of the SNMP alert notification senders.

3.8.3. Resetting Passwords for Configured Content Repositories

Password obfuscation was introduced in JBoss Operations Network 3.1 for stored content providers credentials, including the credentials used to access the JBoss Customer Portal (a default repository in JBoss ON). The methods used to obfuscate, store, and retrieve the content repository credentials in the database are updated in JBoss ON 3.1.1.
When upgrading from JBoss ON 3.1 to JBoss ON 3.1.2, any stored credentials for an existing content repository must be updated in order to apply the new obfuscation method.
Passwords must be changed both for the user account on the repository itself and for the repository configuration in JBoss ON.

NOTE

The password change is only necessary when upgrading from JBoss ON 3.1 It is not required when upgrading from an earlier version of JBoss ON to JBoss ON 3.1.2.

3.8.4. Upgrading the JBoss EAP 6 Resource Plug-in

JBoss Operations Network 3.0 and 3.0.1 had a tech preview version of the JBoss Enterprise Application Platform (EAP) 6 agent plug-in. With normal upgrade processes, agent plug-ins are updated when the JBoss ON server is updated. However, tech preview plug-ins are not upgraded. The tech preview version of the plug-in must be deleted, and then the new plug-in installed.
The EAP 6 tech preview plug-in and the EAP 6 GA plug-in are treated as two separate plug-ins by JBoss ON. If the tech preview version is not deleted, then any EAP 6 resource will be discovered and listed twice in the inventory, once discovered by the tech preview plug-in and discovered again by the GA plug-in.

NOTE

Any configuration, monitoring data and baselines, and resource histories will be lost after upgrading to the new EAP 6 plug-in.
To load the new EAP 6 plug-in:
  1. Delete the original tech preview plug-in and purge it from the JBoss ON database. Purging the plug-in allows the server to deploy the new plug-in in its place.
    1. In the top menu, click the Administration tab.
    2. In the Configuration box on the left navigation bar, click the Agent Plugins link.
    3. Select the EAP 6 tech preview plug-in.
    4. Click the Delete button.
    5. Click the SHOW DELETED button at the bottom of the plug-ins list.
    6. Select the EAP 6 plug-in, and then click the PURGE button. This removes the entry in the JBoss ON database that tells the servers to ignore that original tech preview plug-in and any updates to it.

      IMPORTANT

      Wait for the purge operation to complete before continuing with the upgrade process.
  2. If the server has not already been upgraded, upgrade the JBoss ON server, as described in Section 3.8.1, “Upgrading the JBoss ON Server”.
  3. Install the EAP 6 plug-in pack, as described in Chapter 5, Installing JBoss Agent Plug-in Packs.
  4. Import the EAP 6 server and its children.
    Configuring and managing resources for EAP 6 domains and standalone servers is described in How to Manage JBoss Servers.