This section has instruction for upgrading your HQ deployment to a new version. You should upgrade both the HQ Server and the HQ Agent to the same version.

Upgrade HQ Server

You upgrade the HQ Server using the full installer, using the upgrade option. (The installer does not upgrade the HQ Agent.)

What Happens During Server Upgrade 

The installer installs a new version of HQ Server; it obtains the configuration information from your previous server installation and configures the new server instance accordingly.

If you use HQ's internal database, the installer creates a new database instance that contains the data from the existing instance. The new instance has an updated schema, but the  PostgreSQL server itself in not upgraded to a new version.

If you use an external database, the installer updates the existing instance. 

Upgrade HQ Server on Unix-Based Platforms

1.  Stop the current server instance. For example:

/opt/hyperic/server-3.2.5/bin/hq-server.sh stop

2. If you use an external HQ database, back it up before proceeding. 

3. Run the HQ installer in upgrade mode. For example:

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

4. The installer prompts for the path to the previous HQ Server instance. Enter the path, for example:

/opt/hyperic/server-3.2.5

5.  The installer prompts for the path to the new server instance.  Enter the path to the directory under which the new server instance will be installed.  For example, to install the new instance under your existing HQ home directory:

/opt/hyperic

The installer will finish the upgrade.

6.  Archive your old HQ Server directory, so that if you want, you can revert to the previous version. For example:

tar -zcvf hq-server-3.2.5-archive.tgz hq-server-3.2.5-EE

7.  Start the new server instance. For example:

/opt/hyperic/server-4.0.0/bin/hq-server.sh start

Upgrade HQ Server on Windows Platforms

1.  Stop the existing server instance using the Windows Services Control Panel.

2.  Follow the instructions that apply, depending on whether you use the HQ built-in database or an external database:

• If you use the built-in HQ database, stop the HQ database using the Windows Services Control Panel. The upgrade process will migrate your database schema to the latest edition. Note that PostgreSQL itself is not upgraded to the latest version that ships with the HQ. The database server remains the one installed when you first installed HQ Server.

• If using an external database, back it up.

3.  Run the HQ installer in upgrade mode:

c:\hyperic\hyperic-hq-installer\setup.bat -upgrade

4. The installer prompts for the path to the previous HQ Server instance. 

Enter the full path to your existing server installation, for instance:

c:\hyperic\server-3.2.5

5. The installer prompts for the path where the upgrade version should be installed. 

Enter the path to the directory that will contain the new server installation. For instance, to install the new instance under your existing HQ home directory:

c:\hyperic\

The installer will finish the upgrade.

6.  Archive your previous HQ Server directory so that if you wish you can revert to the previous version.

7. Update the Windows Service with the new version information:

c:\hyperic\server-4.0.0\bin\hq-server.exe \-i

8.  Start the upgraded HQ Server using the Windows Services Control Panel.

Solving Problems with Upgraded Servers with an Oracle Database

If you are upgrading an HQ installation with an Oracle backend and you experience any of the following errors during upgrade, follow the steps below to resolve the problem.

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.

2. Execute this SQL:

DELETE FROM EAM_SERVICE WHERE SERVICE_TYPE_ID IS NULL;

3. Re-run the upgrade.

Clear Browser Cache Before Using the Portal

If you are upgrading to 4.0 from a 3.2.x or 3.1.x version, before using the HQ user interface, users must clear the browser cache, or reload the Dashboard using the Shift Refresh key sequence.

If you do not clear the browser cache, portions of the HQ user interface may display improperly.

Upgrade HQ 3.1.x and 3.2.x Agents

These instructions apply to both the open source and enterprise editions of HQ.

You must use an agent-only package to upgrade 3.1.x and 3.2.x agents to 4.x.

1. Stop the 3.1.x or 3.2.x agent.

2. Unpack the 4.0 agent into the agent installation directory.

3. To preserve your previous configuration settings, copy property settings that you have customized from the 3.2.x or 3.1.x agent.properties file into the 4.0 properties file, in AgentHome/conf.

Note:  There are new properties in HQ 4.0, so you cannot use a 3.x properties file.

4.  Install the HQ Agent service (Windows only):  

AgentHome\bin\hq-agent.bat install

5. Start the agent. For instructions, see Start the HQ Agent.

Notes:

• The first time you start the agent, it will prompt for startup settings. If you prefer, you can supply the settings in the agent properties file before starting the agent the first time.   For instructions, see Configuring Agent Startup Settings in its Properties File.

• When you first upgrade a HQ Enterprise 3.1.x or 3.2.x agent to 4.0 or later, you cannot configure unidirectional communications at first startup. You must configure bidirectional communications at first startup of an agent upgraded from 3.x to 4.x, and then, follow the instructions in Changing Between Unidirectional and Bidirectional Agent Communications.

Upgrade HQ 4.x Agents

To  upgrade a HQ 4.x agent to a newer version, you can:

• Push Agent Bundle from the HQ Server - Only supported in HQ Enterprise.
• Upgrade a 4.x Agent Bundle Manually - Only supported in HQ Enterprise.
• Upgrade a 4.x Agent Using a Full Agent Package - Use this method if you use the open source edition of HQ; also supported in HQ Enterprise.

The first two options - updating the agent bundle only - do not overwrite the previous configuration, so you don't have to back up and restoring the agent.properties file.  Note that if you wish, you can create and distribute a custom agent bundle, following the directions provided later in this section.

Push Agent Bundle from the HQ Server

Available only in HQ Enterprise

You can update one or more HQ Agents by pushing the new bundle to it from the HQ Server, using the HQ user interface.

The agent upgrade command is available on the Views tab for an HQ Agent (or a group of HQ Agents).  For more information, see Agent Control Commands.

Note:  When you update an agent bundle, its previous agent configuration is preserved.

Upgrade a 4.x Agent Bundle Manually

Available only in HQ Enterprise

Follow these steps if you wish to manually upgrade the agent bundle in your agent installation, instead of pushing the bundle from the HQ Server.  

Note:  When you update an agent bundle, your previous agent configuration is preserved.

1. Copy the agent bundle (agent-4.x.y-nnn.tgz or agent-4.x.y-nnn.zip) from

ServerHome/hq-engine/server-4.x.y-EE/default/deploy/hq.ear/hq-agent-bundles

to

AgentHome/bundles

2.  Unpack the agent bundle.

3.  Edit the rollback.properties file in AgentHome/conf to specify the location of the new agent bundle and the bundle it will supersede.

4.  Restart the agent. For instructions, see Restart the HQ Agent.

Note: The first time you start the agent, it will prompt for start settings. If you prefer, you can supply the settings in the agent properties file before starting the agent the first time.   For instructions, see Configuring Agent Startup Settings in its Properties File.

If the upgrade to the new agent bundle fails, an attempt will be made to start the agent using the old agent bundle.

You can determine whether the upgrade was successful and what version you are running by looking at the log files in AgentHome/logs.

Create a Custom 4.x Agent Upgrade Bundle*

Available only in HQ Enterprise

This section describes how to create a custom agent bundle.  Pre-configuring the agent eases the process of upgrading multiple agents.  For additional information, see Deploying Multiple HQ Agents.

1.  Back up an existing agent located in:

ServerHome/hq-engine/server-4.x.y-EE/default/deploy/hq.ear/hq-agent-bundles

For example:

cp ServerHome/hq-engine/server-4.z.y-EE/default/deploy/hq.ear/hq-agent-bundles/agent-4.0.0-EE-802.tgz ServerHome/hq-engine/server-4.x.y-EE/default/deploy/hq.ear/hq-agent-bundles/agent-4.0.0-EE-802.tgz.bak

2.  Extract the bundle. For example:

tar xzf ServerHome/hq-engine/server-4.x.y-EE/default/deploy/hq.ear/hq-agent-bundles/agent-4.0.0-EE-802.tgz

This results in a new directory corresponding to the agent bundle, like this:

ServerHome/hq-engine/server-4.x.y-EE/default/deploy/hq.ear/hq-agent-bundles/agent-4.0.0-EE-802

3. Update the contents of expanded directory. For instance, you could add  custom plugins to the plugins directory:

ServerHome/hq-engine/server-4.x.y-EE/default/deploy/hq.ear/hq-agent-bundles/agent-4.0.0-EE-802/pdk/plugins

4.  Rename expanded directory to the name of custom agent bundle. For example:

mv ServerHome/hq-engine/server-4.x.y-EE/default/deploy/hq.ear/hq-agent/bundles/agent-4.0.0-EE-802 ServerHome/hq-engine/server-4.x.y-EE/default/deploy/hq.ear/hq-agent-bundles/my-bundle

5.  Pack up agent bundle, using the directory name from from the previous step as the tarball file name. For example: 

tar cvf ServerHome/hq-engine/server-4.x.y-EE/default/deploy/hq.ear/hq-agent-bundles/my-bundle.tar
ServerHome/hq-engine/server-4.x.y-EE/default/deploy/hq.ear/hq-agent-bundles/my-bundle;
gzip ServerHome/hq-engine/server-4.x.y-EE/default/deploy/hq.ear/hq-agent-bundles/my-bundle

Upgrade a 4.x Agent Using a Full Agent Package

These instructions apply to both the open source and enterprise editions of HQ. 

To upgrade an HQ 4.x Agent using full the agent package:

1.  Stop the 4.x agent.

2.  Unpack the 4.y agent into the agent installation directory.

3.  Install the agent service (Windows only):

From a command shell in AgentHome/bin enter:

hq-agent.bat install

5.  Start the agent. For instructions, see Start the HQ Agent.

Note: The first time you start the agent, it will prompt for start settings. If you prefer, you can supply the settings in the agent properties file before starting the agent the first time.   For instructions, see Configuring Agent Startup Settings in its Properties File.