Upgrade Guide

Added by John Sachs, last edited by Chip Witt on May 25, 2007  (view change)


Upgrading Hyperic HQ sounds harder than it actually is. The upgrade process involves two relatively easy steps:

  1. Upgrade HQ Server
    1. Detailed Windows Instructions
    2. Detailed Non-Windows Instructions
    3. Important Server Upgrade Notes
  2. Upgrade HQ Agents

Upgrading HQ Server

Backup the database!

If your HQ database is not the built-in database, be sure to back it up before upgrading. This is very important. If you are using the built-in database, the upgrade process creates a copy of your database, so you essentially get a free backup without having to worry about it.

Overview

To upgrade the HQ Server, first download the full installation package of HQ (filename like hyperic-hq-installer-*.tgz) and unpack it. Next, stop the currently installed HQ Server if it is still running and make a backup of your database, if necessary (see note below, if you are unsure). Then start the installer in upgrade mode like this:

$ ./hyperic-hq-installer/setup.sh -upgrade

The installer will start up and ask the location of the HQ Server to be upgraded. Enter the full path to the current HQ Server. Then enter the location where the new HQ Server will be installed.

Detailed Windows Instructions

  1. Stop the running instance of HQ Server through the Windows Services Control Panel
  2. Manage database considerations
    • If using the built-in database: Stop the HQ Database through the Windows Services Control Panel
    • If using a standalone database: Backup your database
  3. Run the setup.bat file using the "-upgrade" parameter
    c:\hyperic\hyperic-hq-installer\setup.bat -upgrade
  4. The installer will prompt you to enter the path to the previous HQ Server instance you have been running
    c:\hyperic\server-3.0.x
  5. The installer will prompt you to enter the path where the upgrade version should be installed
    c:\hyperic
  6. The installer will finish the upgrade. You should archive your old HQ Server directory in the case that you decide to revert to the earlier build.
  7. Update the Windows Service with the new version information
    c:\hyperic\server-3.0.x\bin\hq-server.exe -i
  8. Start the upgraded HQ Server using the Windows Services Control Panel

back to top

Detailed Non-Windows (Unix, Linux, OS X) Instructions

  1. Stop the running instance of HQ Server
    /opt/hyperic/server-3.0.x/bin/hq-server.sh stop
  2. Run the setup.sh file using the "-upgrade" parameter
    /opt/hyperic/hyperic-hq-installer/setup.sh -upgrade
  3. The installer will prompt you to enter the path to the previous HQ Server instance you have been running
    /opt/hyperic/server-3.0.x
  4. The installer will prompt you to enter the path where the upgrade version should be installed
    /opt/hyperic
  5. The installer will finish the upgrade. You should archive your old HQ Server directory in the case that you decide to revert to the earlier build.
  6. Start the upgraded HQ Server
    /opt/hyperic/server-3.0.y/bin/hq-server.sh start

back to top

Notes on Server Upgrades
  • The installer does not do "in place" upgrading of the files. It essentially looks at the configuration of the current server, then installs a new one in a new location with the same configuration.
  • If the server to be upgraded is using the HQ built-in database, that database is copied to the new location. So you get an automatic backup of your database and you can roll back to the previous version at any time by simply stopping the new server and starting up the old one.
  • If the HQ database is not the built-in database, that database will be upgraded "in place". This means that you almost certainly want to take a backup of your database before doing the upgrade.
Oracle Upgrades

If you are upgrading an HQ with an Oracle backend and you experience any of the following errors during upgrade, follow the specified steps to successfully upgrade your HQ.

Error updating EAM_SERVICE.SERVICE_TYPE_ID: java.sql.SQLException: ORA-02296: cannot enable (HQDBUSER.) - null values found 

Error executing statement desc=[null] SQL=[
ALTER TABLE eam_stat_errors DROP CONSTRAINT rt_errs_fk_rstat CASCADE
] java.sql.SQLException: ORA-02443: Cannot drop constraint - nonexistent constraint

Fix this with these steps:

  1. Restore your database from backup (you did take a backup, right?)
  2. Execute this SQL: 
    DELETE FROM EAM_SERVICE WHERE SERVICE_TYPE_ID IS NULL;
  3. Copy this db-upgrade.xml to hyperic-hq-installer/installer-3.0.x-EE/data/db-upgrade.xml replacing the one already there
  4. Re-run the upgrade

back to top

Upgrading HQ Agents

Upgrading HQ Agents is even easier than the server. Since the agent's configuration is stored almost entirely by the server (see note), all that needs to happen to 'upgrade' the agent, is to install a new one. Agent only packages are available for download to speed this process (filename like hyperic-hq-agent-*.tgz). Unpack that package, stop the current agent and start up the new one. Specify HQ Server connection information (see "Agent Upgrades" note) and the agent upgrade is complete.

Notes Specific to Windows

Since the HQ Agent is stopped and started by way of the Services Control Panel in Windows, one must follow a slightly different process to perform a successful upgrade.

  1. Stop the HQ Agent service through the Services Control Panel
  2. Start the new agent by launching hq-agent.exe from the command-line, and specifying the connection information (see "Agent Upgrades" note)
  3. Issue a Control-C to stop the hq-agent.exe process, and return to a command prompt
  4. Run hq-agent.exe -i from the command-line to update the HQ Agent service entry
  5. Start the HQ Agent service through the Services Control Panel
Notes on Agent Upgrades

There are some configuration parameters for the agent not stored in the database. These are things that are configured in the agent.properties file (example: listen port). Another thing to note is that if your HQ is using custom plugins, you may need to do some extra work to make sure those plugins get into the upgraded HQ Agent.

Fortunately, both of these things (agent.properties and custom plugins) can be easily set to be picked up automatically for upgrades. Any configuration property in agent.properties will be overridden by properties in ~/.hq/agent.properties (on Windows machines, the ~/.hq directory configuration does not work. You must modify the contents of the agent.properties file within the agent directory on Windows) for the user running the agent. Similarly, any plugin in the directory ../hq-plugins (one up from the agent installation directory) will get picked up by the agent. So essentially, you can set these things and forget them as long as you continue to run the agent as the same OS user and you continue to install upgraded agents to the same install path.

Automatic Connection

The connection information that must be configured when the agent is started for the first time can be entered into the agent.properties file. If that information exists in the configuration file, you will not need to interactively configure it. This helps tremendously when deploying agents on a large scale. If you couple this with the information in the note above, you can see that by adding the configuration properties to the ~/.hq/agent.properties file (on Windows machines, the ~/.hq directory configuration does not work. You must modify the contents of the agent.properties file within the agent directory on Windows), you get automatic connection configuration for new agents. The lines that configure the connection look like this:

agent.setup.camIP=localhost
agent.setup.camPort=7080
agent.setup.camSSLPort=7443
agent.setup.camSecure=no
agent.setup.camLogin=hqadmin
agent.setup.camPword=hqadmin
agent.setup.agentIP=*default*
agent.setup.agentPort=*default*

back to top

Labels

 
(None)
System Monitoring Software
SourceForge.net Logo