Upgrade and Migration Guide

NOTE: It is assumed in this topic that you have an existing tc Server installation, along with one or more tc Server instances, and you want to upgrade it to the latest version of tc Server. If you are installing tc Server for the first time, see Installing tc Server: Typical Steps for details.

This topic describes how to perform the following supported upgrade and migration use cases:

Upgrading a tc Server Installation to the Latest Version

The procedure in this section describes how to upgrade a tc Server installation to version 6.0.20.C from any of the following versions:

The tc Server upgrade procedure can be conceptually broken up into the following sub-tasks:

Depending on how you have configured your entire tc Server installation, you might perform different sub-tasks on different computers. For example, on the computer on which you have installed the AMS agent and application server component (called a managed node), you perform sub-tasks 2, 3, and 4. However, on the computer on which you installed the AMS server (and nothing else), you perform only task 1. However, for simplicity, the following procedure assumes that you have install all three components (AMS server, AMS agent, and application server) on the same computer and thus discusses all sub-tasks. Make the appropriate changes to the procedure to fit your particular environment.

The examples in this section use Unix sytax; 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.

To upgrade your tc Server installation to 6.0.20.C, follow these steps:

  1. Shut down all currently running tc Server components (AMS server, AMS agent, and all tc Server instances.)

    See Starting and Stopping tc Server Instances and Starting and Stopping the AMS Server and Agents for details.

  2. Read Overview of Installation for a discussion of the different tc Server distribution files and Important Note When Installing on Unix Platforms if you are upgrading on Unix.

  3. Download the appropriate tc Server distribution from the SpringSource Customer Account Portal.

  4. Unzip or untar the tc Server distribution file into a temporary directory. Be sure the owner of the temporary directory is the same as the user that unzips/untars the distribution file, or you will get an error when you run the installer program.

    On Windows, the distribution is a self-extracting JAR file that you can expand using Windows Explorer by double-clicking on it; the file unzips in the same directory in which it is located. NOTE: Internet Explorer recognizes that the downloaded distribution file is actually formatted as a ZIP file, and by default might change its file extension from .jar to .zip. This means that if you used IE to download the distribution file and its file extension changed, you might not be able to simply double-click on it to extract its contents. If this is the case, you can either use a zip extractor program, such as 7-Zip, to extract the files, or rename the file to have a .jar extension.

    On Unix, use the tar command to extract the files. For example, to untar the file in the current directory and assign the extracted files to the same group as the user executing the command:

    prompt$ tar --no-same-owner -xvfz /home/tarfiles/tcserver-6.0.20.C-GA-linux32.tgz
  5. Start a command prompt (Windows) or a terminal (Unix.)

  6. 64-bit Unix platforms only. If you are upgrading tc Server on a 64-bit computer, you must explicity set the JAVA_HOME environment variable to point to a 64-bit JVM or JRE. You must also ensure that your PATH environment variable includes this 64-bit JAVA_HOME/bin directory, and that it appears before any other non-64-bit JVM/JRE. This step ensures that you are able to upgrade/install all available components of tc Server (application server and AMS server/agent.)

    Use the which java Unix command to ensure your PATH variable points to the 64-bit JVM/JRE:

    prompt$ which java
    /usr/java64/jdk1.6.0_11/bin/java
  7. Change to the directory in which you unzipped the tc Server distribution file and execute the install.sh (Unix) or install.bat (Windows) script. For example, on Unix:

    prompt$ cd /home/springsource/tcServertmp
    prompt$ ./install.sh

    The installer program performs some checks of your system then displays a menu of options. Depending on the components that are available in the distribution, as well as the components you want to upgrade or install on your computer, pick one, two, or all of the following procedures marked in bold:

    Note that you must run the install.sh script from the directory in which it lives, and not from any other directory, or you will get an error.

  8. To upgrade the AMS server, follow these steps:

    1. Enter the number for the Upgrade tc Server AMS (Server) option at the Enter number: prompt.

    2. Enter the full pathname of the directory that contains the previous version of the AMS server. This is the directory that contains the AMS server sub-directories such as bin, data, hq-engine, and so on. An example of an AMS server pathname is /home/tcserver/server-2.0.0.SR02.

    3. Enter the full pathname of the directory in which you want to install the new version of the AMS server. If, for example, you want to install the new AMS server alongside the one mentioned in the preceding step, enter /home/tcserver.

      Important: The specified directory must already exist; the install program does not create it for you.

      The install program creates a directory under this main AMS server directory for the new server, such as /home/tcserver/server-2.0.0.SR04. The install program then migrates all the data in the old version of the AMS server to the new version.

    4. When the upgrade of the AMS server is complete, you will see the message Deleting temporary JRE ...hit return.... Hit return to get back to the main tc Server installer program. (On Windows you might have to press Enter twice.)

  9. To install the new version of the AMS agent, follow these steps:

    1. Enter the number for the Install tc Server AMS (Server/Agent) - Quick Setup option at the Enter number: prompt.

      The install program performs some checks of your system and then prints the AMS installation menu.

    2. Enter option #2 to install SpringSource AMS Agent.

    3. Enter the full pathname of the directory in which you want to install the new version of the AMS agent.

      Important: The specified directory must already exist; the install program does not create it for you.

      You can specify the same directory in which you installed the previous version of the AMS agent, such as /home/tcserver. The install program creates a directory under this main AMS installation directory for the AMS agent, such as /home/tcserver/agent-2.0.0.SR04.

    4. When the installation of the AMS components is complete, you will see the message Deleting temporary JRE ...hit return.... Hit return to get back to the main tc Server installer program. (On Windows you might have to press Enter twice.)

  10. To install the new version of the tc Server application server, follow these steps:

    1. Enter the number for the Install tc Server Application Server option at the Enter number: prompt.

    2. Enter the full pathname of the directory into which you want to install the new version of the tc Server application server component.

      Important: The specified directory must already exist; the install program does not create it for you.

      SpringSource recommends that you enter the same directory in which you installed the previous version of the application server component.

      For example, if you originally installed version 6.0.20.A of tc Server in the /home/tcserver directory, the installer program created a directory called /home/tcserver/tcServer-6.0/tomcat-6.0.20.A that contains the Tomcat binaries, etc. When you install version 6.0.20.C, you should also specify that the tc Server application server component be installed in /home/tcserver so that the installer program creates a directory called /home/tcserver/tcServer-6.0/tomcat-6.0.20.C.

      Installing 6.0.20.C in this way overwrites the following tc Server command scripts from the previous version in the top-level directory: tcserver-instance.sh and tcserver-ctl.sh, along with their supporting JAR files in the tijars directory. This is by design. The installation does not overwrite any other files or directories. If, however, you want to backup these command scripts in case you need to revert to the previous release, be sure to do that before installing the latest release.

  11. Enter the indicated number to exit when you have finished upgrading and installing all the required components for this computer.

  12. The remainder of this procedure describes how to upgrade the version of tc Server instances to 6.0.20.C.

    Open a terminal (Unix) or command window (Windows) and change to the INSTALL_DIR/tcServer6.0 directory, where INSTALL_DIR is the main installation directory such as /home/tcserver:

    prompt$ cd /home/tcserver/tcServer6.0

    By default, all tc Server instances are located in this directory in their own directory, such as myserver.

  13. For each previous-version tc Server instance you want to upgrade, run the following command:

    prompt$ ./tcserver-instance.sh -s instance -m -v 6.0.20.C

    where instance refers to the name of the sub-directory that contains the tc Server instance you want to upgrade. For example, if you want to upgrade the tc Server instance myserver, run the following command:

    prompt$ ./tcserver-instance.sh -s myserver -m -v 6.0.20.C
  14. Start the instance as described in Starting and Stopping tc Server Instances. The startup messages should indicate that the instance is now using version 6.0.20.C of tc Server. The messages should look similar to the following:

    prompt$ ./tcserver-ctl.sh start
    INFO Instance name:      myserver
    INFO Script directory:   /home/tcserver/tcServer-6.0
    INFO Instance base:      /home/tcserver/tcServer-6.0
    INFO Binary dir:         /home/tcserver/tcServer-6.0/tomcat-6.0.20.C
    INFO Tomcat Version:     6.0.20.C
    INFO tcServer Version:   6.0.20.C-GA
    Using CATALINA_BASE:   /home/tcserver/tcServer-6.0/myserver
    Using CATALINA_HOME:   /home/tcserver/tcServer-6.0/tomcat-6.0.20.C
    Using CATALINA_TMPDIR: /home/tcserver/tcServer-6.0/myserver/temp
    Using JRE_HOME:       /home/java/jdk1.6.0_11

When you complete this procedure for all components on all computers, you will have successfully upgraded your full tc Server installation.

You should now start the new versions of the AMS server and agent rather than the old versions; for details see Starting and Stopping the AMS Server and Agents. The new version of the AMS server will contain all data from the old version, such as discovered resources and alert information. Note that when you start the new version of the AMS agent, the script requests information about the AMS server to which it will communicate. Be sure to enter the information for the upgraded AMS server. This is a one-time event and subsequent starts of the agent do not require this input.

Upgrading Only the Tomcat Version in a tc Server Installation

This section is for users who want to upgrade only the installed Tomcat binaries of tc Server, rather than upgrade all its components, such as the AMS server and agent. The procedure first describes how to install a new version of the tomcat-XXX directory in the main tc Server directory (such as /home/tcserver/tcServer-6.0/tomcat-6.0.20.D) and then how to upgrade each of your tc Server instances so they use the new version of the Tomcat binaries.

  1. Shut down all currently running tc Server instances. For example:

    prompt$ cd /home/tcserver/tcServer-6.0
    prompt$ ./tcserver-ctl.sh myserver stop

    See Starting and Stopping tc Server Instances.

  2. Download the tcServer-6.0.X.X-GA-tomcat.tar.gz (Unix) or tcServer-6.0.X.X-GA-tomcat.zip (Windows) file from the Customer Support Portal. After logging in using your customer login, navigate to the tc Server 6.0 section of the Software Updates page.

    For example, if you want to upgrade to version 6.0.20.D of the Tomcat binaries, download the tcServer-6.0.20.D-GA-tomcat.tar.gz (or ZIP file).

  3. Unix Only: Read Important Note When Installing on Unix Platforms.

  4. Untar (Unix) or unzip (Windows) the file you just downloaded into the parent directory of the main tc Server tcServer-6.0 installation directory. For example, on Unix, if you installed tc Server in /home/tcserver/tcServer-6.0 and downloaded the TAR file into the /home/downloads directory:

    prompt$ cd /home/tcserver
    prompt$ tar --no-same-owner -xvf /home/downloads/tcServer-6.0.20.D-GA-tomcat.tar.gz

    This creates a new Tomcat binary directory (such as /home/tcserver/tcServer-6.0/tomcat-6.0.20.D) and overwrites the existing tcserver-XXX.sh|bat files. This is by design.

  5. Unix Only. Ensure that all tcserver-XXX.sh files are executable using the chmod command as shown:

    prompt$ cd /home/tcserver/tcServer-6.0
    prompt$ chmod +x *.sh
  6. For each tc Server instance you want to upgrade, run the following command:

    prompt$ ./tcserver-instance.sh -s instance-name -m -v 6.0.X.X

    where instance-name refers to the name of the sub-directory that contains the tc Server instance you want to upgrade and 6.0.X.X refers to the version to which you want to upgrade, such as 6.0.20.D. If you do not specify the -v option, then the script upgrades the instance to the latest version.

    For example, if you want to upgrade the tc Server instance myserver to 6.0.20.D, run the following command:

    prompt$ ./tcserver-instance.sh -s myserver -m -v 6.0.20.D

    You should see the following message:

    Modifying existing instance "myserver" to tomcat-6.0.20.D ...
    Done.
  7. Start the instance as described in Starting and Stopping tc Server Instances. The startup messages should indicate that the instance is now using the new version of tc Server. The messages should look similar to the following:

    prompt$ ./tcserver-ctl.sh myserver start
    INFO Instance name:      myserver
    INFO Script directory:   /home/tcserver/tcServer-6.0
    INFO Instance base:      /home/tcserver/tcServer-6.0
    INFO Binary dir:         /home/tcserver/tcServer-6.0/tomcat-6.0.20.D
    INFO Tomcat Version:     6.0.20.D
    INFO tcServer Version:   6.0.20.C-GA
    Using CATALINA_BASE:   /home/tcserver/tcServer-6.0/myserver
    Using CATALINA_HOME:   /home/tcserver/tcServer-6.0/tomcat-6.0.20.D
    Using CATALINA_TMPDIR: /home/tcserver/tcServer-6.0/myserver/temp
    Using JRE_HOME:       /home/java/jdk1.6.0_18

Upgrading Only the tc Server AMS Plugin

The AMS Server component of tc Server is pre-configured with a plugin that encapsulates the tc Server functionality in AMS. This tc Server AMS plugin is usually invisible to you because it is automatically configured when you install the AMS Server component of tc Server, and then automatically upgraded when you upgrade the AMS server component as part of a full tc Server upgrade.

However, sometimes you might need to upgrade only the tc Server AMS plugin (rather than the entire AMS server) to, for example, fix a security vulnerability that affects only the plugin and not the rest of the AMS server. This section describes how you perform an upgrade of only the tc Server AMS plugin.

  1. Open a terminal (Unix) or command window (Windows).

  2. Stop the AMS server, if it is currently running. For example, if you installed the AMS server component in /home/tcserver/server-2.0.0.SR04 on Unix:

    prompt$ cd /home/tcserver/server-2.0.0.SR04/bin
    prompt$ ./ams-server.sh stop
  3. Delete the following three directories and one file that apply to the old version of the tc Server AMS plugin:

    • AMS-SERVER-INSTALL-DIR/hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tcserverclient
    • AMS-SERVER-INSTALL-DIR/hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tomcatappmgmt
    • AMS-SERVER-INSTALL-DIR/hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tomcatserverconfig
    • AMS-SERVER-INSTALL-DIR/hq-engine/server/default/deploy/tomcatserverconfig.war

    where AMS-SERVER-INSTALL-DIR refers to the main AMS server installation directory, such as /home/tcserver/server-2.0.0.SR04. For example:

    prompt$ cd /home/tcserver/server-2.0.0.SR04
    prompt$ rm -r hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tcserverclient
    prompt$ rm -r hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tomcatappmgmt
    prompt$ rm -r hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tomcatserverconfig
    prompt$ rm -r hq-engine/server/default/deploy/tomcatserverconfig.war 
  4. Download the tc Server AMS plugin ZIP file from the Customer Support Portal. The file is called:

    springsource-tc-server-hq-plugin-server-1.X.X.XX.zip

  5. Unzip the contents of the ZIP file into the AMS-SERVER-INSTALL-DIR/hq-engine/server/default/deploy directory. For example, if you downloaded the ZIP file into the /home/Downloads directory:

    prompt$ cd /home/tcserver/server-2.0.0-SR04/hq-engine/server/default/deploy
    prompt$ unzip /home/Downloads/springsource-tc-server-hq-plugin-server-1.1.0.SR01.zip
  6. Start the AMS Server. For example, on Unix:

    prompt$ cd /home/tcserver/server-2.0.0.SR04/bin
    prompt$ ./ams-server.sh start

Migrating from SpringSource ERS

This section is for users who want to migrate an existing ERS 4.0 instance to tc Server 6.0.20.C. It is assumed that you have already installed version 6.0.20.C; if not, see Installing tc Server: Typical Steps.

For clarity, the migration procedure will use the following sample data; adjust the examples to fit your own environment accordingly. It is assumed that:

The examples use Unix sytax; if you are migrating on Windows, change the forward slashes to back-slashes and replace the *.sh suffix with *.bat when running a command script.

To migrate an existing ERS server instance, follow these steps:

  1. If the ERS instance you want to migrate is running, stop it. See the ERS documentation for details.

  2. Open a terminal (Unix) or command window (Windows).

  3. Copy the existing ERS 4.0 server instance directory to the tc Server application server installation directory. For example:

    prompt$ cp -r /opt/ers40/servers/ers-instance /home/tcserver/tcServer-6.0
  4. Edit the /home/tcserver/tcServer-6.0/ers-instance/bin/tomcat_startup.sh file (tomcat_startup.bat on Windows)) and update the following variables to point to the new tc Server directories:

    • root_dir: Points to the tc Server application server home directory. In our example, this would be /home/tcserver/tcServer-6.0.
    • tomcat_dir: Points to the directory that contains the Tomcat binaries. In our example, this would be $root_dir/tomcat-6.0.20.C.
    • server_dir: Points to the server instance directory. In our example, this would be $root_dir/$server_name; this variable value assumes that you are not changing the name of the migrated instance, which is pointed to by the server_name variable.
  5. Windows Only: Edit the /home/tcserver/tcServer-6.0/ers-instance/conf/wrapper.properties file and update the following variables to point to the new tc Server directories:

    • ers.home: Points to the tc Server application server home directory. In our example, this would be /home/tcserver/tcServer-6.0.
    • wrapper.tomcat_home: Points to the directory that contains the Tomcat binaries. In our example, this would be $(ers.home)\tomcat-6.0.20.C.
    • server.home: Points to the server instance directory. In our example, this would be $(ers.home)\$(server.name); this variable value assumes that you are not changing the name of the migrated instance, which is pointed to by the server.name variable.
  6. Start the instance using the same ERS start script you have always used (tomcat_startup.sh, located in the /home/tcserver/tcServer-6.0/ers-instance/bin directory.) This time, however, because you have changed the values of the variables that point to the server binaries, the instance will now be using tc Server 6.0.20.C binaries.