8. Upgrade and Migration Guide

This chapter describes how to perform the following supported upgrade procedures:

8.1 Upgrading a 2.0.X tc Server Installation to 2.1.X

This chapter describes how to upgrade an existing 2.0.X tc Server installation to 2.1.X.

Understanding the 2.0.X to 2.1.X tc Server Upgrade Process

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.

tc Server 2.0.X Upgrade Procedure

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:

  • You installed the 4.2 HQ server in /home/tcserver/server-4.2.0.8-EE and that you are using an external database, such as Oracle, rather that the bundled database.
  • You installed 2.0.4 tc Server Standard Edition (managed node package) in /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:

  1. Unix only: Read Important Note When Installing on Unix Platforms.

  2. On the computer on which you are going to upgrade the existing HQ Server:

    1. Back up your existing HQ Server installation, including any external database that you are using.

    2. Start a terminal (Unix) or command prompt (Windows).

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

      See Starting and Stopping the HQ Server and Agents.

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

    5. Download the 4.5 HQ EE server distribution. You can download an evaluation copy from the Hyperic Download Center.

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

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

    8. 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
    9. 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.

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

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

  3. 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:

    1. Start a terminal (Unix) or command prompt (Windows.)

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

      See Starting and Stopping the HQ Server and Agents.

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

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

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

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

      2. 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 
      3. 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.

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

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

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

      See Starting and Stopping tc Runtime Instances.

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

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

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

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

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

Post-Upgrade Requirements and Notes

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.