This chapter describes how to perform the following supported upgrade procedures:
This chapter describes how to upgrade an existing 2.0.X tc Server installation to 2.1.X.
Upgrading a 2.0.X tc Server installation to 2.1.X consists of the following subtasks, which are explained in more detail in the next section:
Upgrade your existing 4.2 HQ Server to version 4.5. You no longer have to use a tc Server-specific version of HQ; rather, the standard 4.5 Enterprise Edition (EE) distribution now includes the tc Server HQ plugin.
To perform this subtask, you download the 4.5 HQ EE
distribution and use its setup.sh -upgrade (Unix)
or setup.bat -upgrade (Windows) command script to
perform the upgrade.
The procedure below shows basic steps to perform this task, but for additional details, see Upgrade Hyperic Components.
Install the 4.5 HQ Agent on every computer on which you have installed tc Runtime. As with the 4.5 HQ Server, the standard 4.5 HQ Agent now includes the tc Server HQ plugin. You do not actually upgrade your existing HQ Agent; rather, you simply install the new HQ Agent in a separate directory and immediately start using it. Note that if you previously used the HQ Agent that was included in the Managed Node package of 2.0.X tc Server Standard Edition, you can simply remove that old directory once the upgrade is complete.
To perform this subtask, you install the HQ Agent from the
standard 4.5 HQ EE distribution using the
setup.sh (Unix) or setup.bat
(Windows) script. You can also simply push the 4.5 Agent to the tc
Server computers using the upgraded 4.5 HQ Server. This
documentation shows how to perform the former.
The procedure below shows basic steps to perform this task, but for additional details, see Upgrade Hyperic Components.
You can continue to monitor and manage your existing 2.0.x tc Runtime instances using 4.5 HQ without any extra step.
You can, however, optionally install the 2.1.X tc Runtime if you want to start using the new runtime features, such as improved templating, the released version of Spring Insight, or later release of the Tomcat binaries. In this case, you install the 2.1.X runtime separately from the 2.0.X installation rather than on top of the 2.0.X installation. You then create new 2.1.X tc Runtime instances and, if desired, manually migrate the configuration and applications from existing 2.0.X instances to the new 2.1 instances.
If you upgrade your existing tc Runtime instances to version 2.1, you will also need to upgrade your HQ Server and Agent(s) to version 4.5. The 4.2.x versions of the HQ Server and Agent will not monitor a tc Runtime instance that has been upgraded to 2.1.
Depending on how you have configured your tc Server installation, you might perform different subtasks on different computers. For example, on the computer on which you have installed the HQ Agent and runtime component (called a managed node), you perform the second and third subtasks. On the computer on which you installed the HQ Server (and nothing else), you perform only the first subtask. The procedure below breaks the steps into those you do on the managed node computer(s) and those you do on the HQ Server computer. If you have previously installed all components on the same computer, then simply execute all steps on the same computer.
Most of the examples in this section use Unix syntax; if you are
upgrading on Windows, change the forward slashes to back-slashes and
replace the *.sh suffix with *.bat
when running a command script. Other changes between the two platforms
are called out.
For simplicity, it is assumed in this procedure that your 2.0.X environment results from you following the 2.0 Quick Start instructions, except that the HQ Server is on a computer different from the tc Runtime instances. In particular, this means that:
/home/tcserver/server-4.2.0.8-EE
and that you are using an external database, such as Oracle, rather that the bundled database.
/home/tcserver/springsource-tc-server-node
. This means that your 4.2 HQ Agent is installed in a sub-directory, such as
/home/tcserver/springsource-tc-server-node/hyperic-hq-agent-4.2.0.8-EE
.
If your setup is different, such as the various components are installed in different directories, adjust the procedure accordingly.
To upgrade your 2.0.X tc Server installation to 2.1.X, follow these steps:
Unix only: Read Important Note When Installing on Unix Platforms.
On the computer on which you are going to upgrade the existing HQ Server:
Back up your existing HQ Server installation, including any external database that you are using.
Start a terminal (Unix) or command prompt (Windows).
If the HQ server is running, shut it down. For example, on
Unix, if you installed the HQ server in
/home/tcserver:
prompt$ cd /home/tcserver/server-4.2.0.8-EE prompt$ bin/hq-server.sh stop
On Windows, if you installed the HQ server as a Windows service, you use the Windows Services Console to stop the server.
Windows only. If you installed the HQ Server as a Windows service, uninstall it. For example:
prompt> cd c:\home\tcserver\server-4.2.0.8-EE prompt> bin\hq-server.exe -u
See Windows: Installing the HQ Server and Agents as Windows Services
Download the 4.5 HQ EE server distribution. You can download an evaluation copy from the Hyperic Download Center.
Unzip 4.5 HQ Server distribution into a temporary directory.
For example, if you downloaded the distribution to the
/home/Downloads directory on Unix:
prompt$ cd /home/Downloads prompt$ tar xvzf hyperic-hq-installer-4.5.0-EE-noJRE.tar.gz
The unzip or tar command creates a directory called
hyperic-hq-installer-4.5.0 that contains the
setup.sh|bat script and all the product
files.
If you are using an external database to store HQ data, start the database server if it is not already running. Consult your database server documentation for details.
From your terminal window or command prompt, change to
this directory and execute the setup.sh
-upgrade (Unix) or setup.bat
-upgrade (Windows) script. The
-upgrade flag specifies that the script
should migrate information in your existing HQ inventory to the
new HQ Server. For example, on Unix:
prompt$ cd /home/Downloads/hyperic-hq-installer-4.5.0 prompt$ ./setup.sh -upgrade
After accepting the terms of the agreement, enter the full
pathname of the directory that contains the
previous version of the HQ Server that you
want to upgrade, for example
/home/tcserver/server-4.2.0.8-EE.
At the prompt, enter the full pathname of the directory in
which you want to install the new HQ Server. If, for example,
you want to install the new HQ server alongside the existing HQ
server mentioned in the previous step , enter
/home/tcserver.
Note:The specified directory must already exist; the setup program does not create it for you.
The setup script creates a new subdirectory under your
inputted directory for the new HQ Server, such as
/home/tcserver/server-4.5.0-EE. The setup
script then migrates a subset of information about the existing
tc Runtime instances from the old version of the HQ server to
the new HQ Server.
If the upgrade of the HQ Server completes successfully, you should see the following message:
Setup completed. A copy of the output shown above has been saved to: /home/Downloads/hyperic-hq-installer-4.5.0/installer/logs/hq-install.log
Important: From now on, use this new HQ Server; it should have basic information about the existing tc Runtime instances from your old HQ Server.
Start the upgraded server using the
bin/hq-server.sh start command. For
example:
prompt$ cd /home/tcserver/server-4.5.0-EE prompt$ bin/hq-server.sh start
See Starting and Stopping the HQ Server and Agents for details and Windows instructions for installing the server as a service.
On the computer on which you are going to install the new HQ Agent and (optionally) migrate the existing 2.0.X tc Runtimes to 2.1.X:
Start a terminal (Unix) or command prompt (Windows.)
If it is running, shut down the existing HQ Agent. For
example, if you installed the HQ agent as part of a 2.0.x
managed node in
/home/tcserver/springsource-tc-server-node:
prompt$ cd /home/tcserver/springsource-tc-server-node/hyperic-hq-agent-4.2.0.8-EE prompt$ bin/hq-agent.sh stop
Windows only. If you installed the HQ Agent as a Windows service, you use the Windows Services Console to stop it.
Windows only. If you
installed the HQ Agent as a Windows service, uninstall it. For
example, if you installed the 2.0.X managed node in
c:\home\tcserver\springsource-tc-server-node:
prompt> cd c:\home\tcserver\springsource-tc-server-node\hyperic-hq-agent-4.2.0.8-EE prompt> bin\hq-agent.bat remove
See Windows: Installing the HQ Server and Agents as Windows Services.
Download the 4.5 HQ Agent-only distribution. You can download an evaluation copy from the Hyperic Download Center.
Alternatively, you can also use the full 4.5 HQ EE Server distribution you used to install the HQ Server because it also includes the 4.5 HQ Agent, although this distribution is much larger than the Agent-only distribution.
If you are installing the 4.5 HQ Agent from the Agent-only distribution, simply unzip or untar it into the directory in which you want the Agent to live.
For example, if you want to install the 4.5 HQ Agent in
the /home/tcserver directory and you
downloaded it to the /home/Downloads
directory:
prompt$ cd /home/tcserver prompt tar xvzf /home/Downloads/hyperic-hq-agent-4.5.0-EE-xx-x86-linux.tar.gz
This creates the
/home/tcserver/hyperic-hq-agent-4.5.0-EE
directory which contains all the HQ Agent files.
If you are installing the 4.5 HQ Agent from the full 4.5 HQ EE Server distribution, follow these steps:
Unzip the 4.5 HQ EE Server distribution into a temporary directory.
For example, if you downloaded the HQ Server
distribution to the /home/Downloads
directory on Unix:
prompt$ cd /home/Downloads prompt$ tar xvzf hyperic-hq-installer-4.5.0-EE-noJRE.tar.gz
The unzip or tar command creates a directory called
hyperic-hq-installer-4.5.0.
From your terminal window or command prompt, change to
this directory and execute the setup.sh
(Unix) or setup.bat (Windows)
script.
prompt$ cd /home/Downloads/hyperic-hq-installer-4.5.0 prompt$ ./setup.sh
After accepting the terms of the agreement, enter
2 to install only the HQ Agent. Then
enter the full pathname of the directory in which you want
the Agent to live, such as
/home/tcserver.
This creates the
/home/tcserver/agent-4.5.0-EE directory
which contains all the HQ Agent files.
Start the new 4.5 HQ Agent using the
bin/hq-agent.sh start command. Following our
example on Unix (assuming you installed from the Agent-only
package):
prompt$ cd /home/tcserver/hyperic-hq-agent-4.5.0-EE prompt$ bin/hq-agent.sh start
The first time you start the new 4.5 HQ Agent, the script requests information about the HQ Server to which it will communicate; specify the upgraded HQ Server (version 4.5.0 in our example.) This is a one-time event and subsequent starts of the agent do not require this input. See the table in the Configure Agent -Server Communication Interactively section of the Hyperic documentation for information about these prompts.
Important: From now on, use this new 4.5 HQ Agent and not the old HQ Agent.
See Starting and Stopping the HQ Server and Agents for details and Windows instructions for installing the agent as a service.
If you want to migrate your existing 2.0.X tc Runtime instance to 2.1.X, follow the rest of this procedure. Note that you are not required to migrate the 2.0.X instances; you can continue to monitor and manage them using the new 4.5 HQ UI without any further steps.
If they are running, shut down your 2.0.X tc Runtime
instances. For example, if you installed the 2.0.x managed node
in /home/tcserver/springsource-tc-server-node
and have a tc Runtime instance called
myserver:
prompt$ cd /home/tcserver/springsource-tc-server-node prompt$ ./tcruntime-ctl.sh myserver stop
If your tc Runtime instance is located in a directory
other than the main tc Server installation directory, use the
INSTANCE-DIR/bin/tcruntime-ctl.sh script to
stop the instance; in this case, you do not specify the name of
the instance as a parameter to the script. For example:
prompt$ cd /home/tcserver/instances/myserver prompt$ bin/tcruntime-ctl.sh stop
Windows only. If you installed the tc Runtime instances as Windows services, you use the Windows Services Console to stop them.
Windows only. If you
installed your tc Runtime instances as Windows services,
uninstall them. For example, if you installed tc Server managed
node in
c:\home\tcserver\springsource-tc-server-node
and you created a tc Runtime instance called
myserver:
prompt> cd c:\home\tcserver\springsource-tc-server-node prompt> tcruntime-ctl.bat myserver uninstall
If your tc Runtime instance is located in a directory
other than the main tc Server installation directory, use the
INSTANCE-DIR\bin\tcruntime-ctl.bat script to
uninstall the instance; in this case, you do not specify the
name of the instance as a parameter to the script. For
example:
prompt> cd c:\home\tcserver\instances\myserver prompt> bin\tcruntime-ctl.bat uninstall
See Windows: Starting and Stopping tc Runtime Instances as Windows Services.
Install the Standard Edition of tc Runtime using the
general installation procedure described in Installing Standard
Edition (tc Runtime Only). Be sure to install the 2.1
runtime in a different directory from the
2.0.X runtime, such as
/home/tcserver-2.1.
This creates, for example, the directory
/home/tcserver-2.1/springsource-tc-server-standard.
Create a new 2.1 instance to which you will migrate the
configuration and applications of your existing 2.0.X instance.
To avoid confusion, consider calling the instance something
different, such as myserver-2.1, although
this is not necessary. For example, on Unix:
prompt$ cd /home/tcserver-2.1/springsource-tc-server-standard prompt$ ./tcruntime-instance.sh create myserver-2.1
Note that the syntax of the
tcruntime-instance script has changed in 2.1.
See Creating tc
Runtime Instances: Typical Steps.
Manually migrate the configuration, applications, and
anything else you added to the 2.0.x instance to the new 2.1
instance. The exact steps differ for each instance, depending on
how you have configured the 2.0.x instance and the applications
you have deployed. For example, you can copy over
*.war files from the old
webapps directory to the new one. If you
changed the old conf/server.xml or
conf/context.xml files, make the equivalent
changes to the new files. If you prefer, you can make these
changes using the HQ UI once you add this new tc Runtime
instance to the HQ Inventory.
Start the new myserver-2.1 instance as
described in Starting
and Stopping tc Runtime Instances. The startup messages
should indicate that you are using the new 2.1 runtime:
prompt$ cd /home/tcserver-2.1/springsource-tc-server-standard prompt$ ./tcruntime-ctl.sh myserver-2.1 start INFO Instance name: myserver-2.1 INFO Script directory: /home/tcserver-2.1/springsource-tc-server-standard INFO tc Runtime location:/home/tcserver-2.1/springsource-tc-server-standard INFO Instance base: /home/tcserver-2.1/springsource-tc-server-standard INFO Binary dir: /home/tcserver-2.1/springsource-tc-server-standard/tomcat-6.0.29.B.RELEASE INFO Runtime version: 6.0.29.B.RELEASE INFO Script version: 2.5.0.RELEASE Using CATALINA_BASE: /home/tcserver-2.1/springsource-tc-server-standard/myserver-2.1 Using CATALINA_HOME: /home/tcserver-2.1/springsource-tc-server-standard/tomcat-6.0.29.B.RELEASE Using CATALINA_TMPDIR: /home/tcserver-2.1/springsource-tc-server-standard/myserver-2.1/temp Using JRE_HOME: /home/java/jdk1.6.0_21 Using CLASSPATH: /home/tcserver-2.1/springsource-tc-server-standard/myserver-2.1/bin/tomcat-juli.jar:/home/tcserver-2.1/springsource-tc-server-standard/tomcat-6.0.29.B.RELEASE/bin/bootstrap.jar
When you complete this procedure for all components on all computers, you will have successfully upgraded your 2.0.X tc Server installation to 2.1.X.
After you complete HQ upgrade, you must always use the new versions of HQ Server and Agents rather than the old ones. For details about starting and stopping them, see Starting and Stopping the HQ Server and Agents.
When you first connect to the HQ user interface that is using the
upgraded HQ Server, the new 4.5 HQ Agent(s) and other resources show up
in the Auto-Discovery portlet. You must add them to the Inventory before
you can proceed. The 4.5 HQ Server itself now uses a tc Runtime instance
internally (called tc Runtime hq-server, which you
add to the Inventory along with eveyrthing other new resource. You
should, however, not use this tc Runtime instance for your own
purposes.
Your existing 2.0.x tc Runtime instances should already be in the HQ Inventory, and you should be able to manage and control them as before. Any previous custom configuration of the isntances should show up intact, as well as all deployed applications. Additionally, all history and management information about the instance, such as control history, historical metric data, and alert settings, will still be available.
If you created a new 2.1 instance, it will show up in the Auto-Discover panel; as soon as you add it to the HQ inventory, you can start monitoring and managing it as usual. Because you migrated the old 2.0.x instance to this new 2.1 instance, you can delete the old 2.0.X tc Runtime instance from the HQ Inventory.