Upgrade HQ Components

Topics marked with * relate to HQ Enterprise-only features.

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.

Feedback is welcome. Click Add Comment at the bottom of the page.

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.

Upgrading HQ Server External Database

When you perform a fresh installation and have an existing HQ database, the installation procedure will offer the option to upgrade the existing database, to overwrite the existing database, or to exit the installation. Note that if your database is quite large, overwriting may take a very long time. In large deployments, you can avoid the problem by dropping and recreating the HQ database schema before installing a new version of HQ Server. The commands to do so are: 
drop database hqdb;
create database hqdb;
grant all on hqdb.* to 'hqadmin'@'%' identified by 'hqadmin'
grant all on hqdb.* to 'hqadmin'@'localhost' identified by 'hqadmin'

Upgrade HQ Server on Unix-Based Platforms

1. Stop the current server instance. For example:

/opt/hyperic/server-4.1.1/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. You are prompted to acknowledge the SpringSource license agreement.

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

/opt/hyperic/server-4.1.1

6. 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.

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

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

8. Start the new server instance. For example:

/opt/hyperic/server-4.2.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. You are prompted to acknowledge the SpringSource license agreement.

5. 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-4.1.1

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.2.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.x 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.x 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.x properties file, in AgentHome/conf.

*Note: There are new properties as pf 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:

  • 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

Push Agent Bundle from the HQ Server

Available only in HQ Enterprise

Known upgrade issue in HQ 4.3 on HP-UX
A known problem in HQ 4.3 causes an agent upgrade performed from the HQ user interface to fail, because of incorrect permission settings for a shared library file, libsigar-pa-hpux-11.sl. The upgrade fails, and this error is written to agent.log:

{{2010-04-26 11:43:49,347 DEBUG [WrapperStartStopAppMain] [Sigar] /local0/hq/hyperic-hq-agent-4.3.0-EE/bundles/agent-4.3.0-EE-1411/pdk/lib/libsigar-pa-hpux-11.sl: Permission denied
org.hyperic.sigar.SigarException: /local0/hq/hyperic-hq-agent-4.3.0-EE/bundles/agent-4.3.0-EE-1411/pdk/lib/libsigar-pa-hpux-11.sl: Permission denied}}

To avoid this problem, set execute permissions on libsigar-pa-hpux-11.sl:

  1. On the HP-UX server where the agent was upgraded, go to the <hq-agent_install_path>/bundles/<hq-agent_upgraded_version>/pdk/lib directory.
  2. As the directory owner, run the chmod 755 command on the libsigar-pa-hpux-11.sl file.
  3. Go to the <hq-agent_install_path>/bin directory.
  4. Restart the HQ Agent.

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 bundle must reside in the /hq-agent-bundles directory of the HQ Server installation: 

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

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.

Property Description Example
HQ_AGENT_BUNDLE Name of directory with the new bundle, without full path specification. agent-4.1.0-EE-875
HQ_AGENT_ROLLBACK_BUNDLE Name of directory with the old bundle (the one you are upgrading from), without full path specification. agent-4.1.0-EE-874

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. Preserve the existing agent configuration.
    • Back up the agent.properties file from your previous installation. The default location for agent.properties in 4.x installations is the AgentHome/conf directory.
    • Note: In some HQ environments, agent.properties is stored in an alternative location that eases the process of automating the deployment of multiple agents. On Unix-based platforms, that location is the .hq subdirectory of the home directory of the user that runs the Agent. If your agent configuration is stored in that location, it will not be over-written by the new installation.

2. If the agent runs on Windows, uninstall the agent service from a command shell in AgentHome/bin: 

 
hq-agent.bat remove

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

4. On Windows, install the new agent service. In 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.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.