Upgrade and Migration Guide

Several upgrade procedures are supported for this release of Pivotal tc Server.

Upgrade an Instance to a Newer tc Runtime Binary

This section has instructions for upgrading tc Server instances to a new version of the tc Runtime.

Note: If you want to upgrade to the latest tc Server package, see one of these two sections:

For example, suppose that your tc Server release came bundled with tomcat-8.0.14.A.RELEASE. Later, you could decide to upgrade to the tomcat-8.0.15.A.RELEASE (or another version) when it is released. The instructions in this section enable you to stay current with new tc Runtime releases without fully installing the full tc Server installation. This lets you take advantage of getting the latest features, security vulnerability fixes, and bug fixes.

Before You Start

Be sure to stop a tc Server instance before you upgrade the tc runtime version. For instructions, see Starting and Stopping tc Runtime Instances.


  1. Change directory to the tc Server installation directory. For example:

    prompt$ cd /opt/pivotal/pivotal-tc-server-standard-3.0.2.RELEASE 
  2. Use the --list option to view a list of available runtimes to install. The command generally requires a few seconds to return the list. For example:

    prompt$ ./tcruntime-admin.sh get-runtime --list
    Retrieving Available Runtimes (this may take a moment)

Available Runtimes for tc Server 3.1.x:

7.0.70.A.RELEASE - installed 
8.0.36.A.RELEASE - installed 

Runtimes are specified by version, such as 8.0.15.A.RELEASE. If ‘installed’ trails the version number, that indicates the runtime version is currently installed.

  1. Use the --version option to download and install a specific runtime version. For example:

    prompt$ ./tcruntime-admin.sh get-runtime --version 8.0.33.A.RELEASE
    Downloading 8.0.33.A.RELEASE
    Expanded 8.0.33.A.RELEASE

    If the specified version is already installed, then the command returns a message similar to the following:

    prompt$ ./tcruntime-admin.sh get-runtime --version 8.0.36.A.RELEASE
    Runtime version 8.0.36.A.RELEASE has been detected as already being installed.

Upgrade an Instance in a New tc Server Directory

This section has instructions for upgrading tc Server instances to a new version of tc Server.

Run the tcruntime-instance.sh upgrade or (tcruntime-instance.bat upgrade) command to upgrade an existing tc Server instance to a new version of tc Server. The upgrade command migrates configuration information and applications from an existing instance to the new one. The command takes this form:

 tcruntime-instance.sh upgrade -v
        <tcRuntimeVersion> -i PathToNewInstanceDirectory PathToOldInstance       


tcRuntimeVersion is the Tomcat binary that you want the new instance to use, for example, 7.0.37.B.RELEASE.


  • The tc Runtime version must exist in the new tc Server installation directory. If you want to use a tc Runtime that exists in your previous tc Server installation, but not the new one, you must copy it into the new tc Server installation directory.
  • If you do not use the -v option to specify a binary version, the upgrade assumes you do not want to upgrade the binary and tries to create the new instance with the same binary. If the older instance uses a version of Tomcat that does not exist in the new version of tc Server, you must copy it from the older tc Server installation to the new one, or the upgrade will fail.

PathToNewInstanceDirectory specifies the directory in which you want the upgraded instance to be created.


  • If you do not use the -i option to specify a directory, the instance will be created in the current working directory.
  • If you specify the directory where the old instance exists, that instance will be upgraded in place.

PathToOldInstance points to the instance that you wish to upgrade.

Before You Start


The example commands in the instructions below assume you are upgrading a tc Server 2.9.5 instance to 3.0.2.

  1. Install the new version of tc Server in a new installation directory, as described in Installing Pivotal tc Server. For example, install tc Server 3.0.2 in /opt/pivotal/pivotal-tc-server-standard-3.0.2.RELEASE.
  2. If the directory where you want the upgraded server instance to be installed does not exist, create it.
  3. Change directory to new TCS installation directory. For example:

    prompt$ cd /opt/pivotal/pivotal-tc-server-standard-3.0.2.RELEASE 
  4. Run the upgrade command. For example:

    prompt$ tcruntime-instance.sh upgrade -i ../tcs-3.0.2-instances -v 7.0.57.A.RELEASE  ../tcs-2.9.5-instances/myserver1 

    The command above creates an upgraded version of the “myserver1” instance in the /tcs-3.0.2-instances directory.

Upgrade an Instance in the Existing tc Server Directory

RHEL - Upgrade Using the Pivotal RPM Repository

Pivotal tc Server provides RPMs in Pivotal repositories from which you can install on an RHEL computer or virtual machine. If you originally installed tc Server on the RHEL computer using yum install, then you use yum upgrade to upgrade the installation to the latest version.

The yum upgrade process:

  • Installs the latest tc Runtime versions in the /opt/pivotal/pivotal-tc-server-standard directory. The old tc Runtime versions associated with the previous version of tc Server are preserved.
  • Copies the new versions of the tc Server commands and templates to the /opt/pivotal/pivotal-tc-server-standard directory.



  1. From the RHEL computer on which you will upgrade Pivotal tc Server, log in as the root user.
  2. Execute the following yum command:

    prompt# yum upgrade pivotal-tc-server-standard 

    The yum command begins the upgrade process, resolves dependencies, and displays the packages it plans to upgrade.

  3. Enter y at the prompt to begin the actual upgrade.

    When the upgrade process finishes, you will see a Complete! message at the end. Check the output of the command to ensure that the upgrade was successful.

  4. For each tc Runtime instance that you created in the previous tc Server installation that you want to upgrade, follow these steps:

    1. If necessary, become the user that created the instances you want to upgrade, such as tcserver:

      prompt# su - tcserver 
    2. Change to the directory in which the instance is located. For example:

      prompt$ cd /var/opt/pivotal/pivotal-tc-server-standard 
    3. Execute the tcruntime-instance upgrade command. Specify the name of the tc Runtime instance you are upgrading and use the -v option to specify the new tc Runtime version that the upgraded instance will start to use. For example, if your tc Runtime instance is called myserver:

      prompt$ /opt/pivotal/pivotal-tc-server-standard/tcruntime-instance.sh upgrade -v 7.0.57.A.RELEASE myserver 

    When you start the upgraded tc Runtime instance, it will use the 7.0.57.A.RELEASE tc Runtime.

Upgrading Java Version

It is recommended to create a duplicate instance prior to upgrading Java. The duplicate instance can be used for testing purposes.

To upgrade the java version, the JAVA_HOME variable in bin/setenv.sh (Unix) and the set.JAVA_HOME property in conf/wrapper.conf (Windows) needs to be updated to point to the new Java Home.

When upgrade from a Java version prior to 8 any PermGen settings should be removed. These are usually found in the JAVA_OPT variable in bin/setenv.sh

An example of a Java 6 setenv.sh

  # Edit this file to set custom options
  # Tomcat accepts two parameters JAVA_OPTS and CATALINA_OPTS
  # JAVA_OPTS are used during START/STOP/RUN
  # CATALINA_OPTS are used during START/RUN

  JVM_OPTS="-Xmx512M -Xss256K -XX:MaxPermSize-512M"

An example of a Java 8 setenv.sh

  # Edit this file to set custom options
  # Tomcat accepts two parameters JAVA_OPTS and CATALINA_OPTS
  # JAVA_OPTS are used during START/STOP/RUN
  # CATALINA_OPTS are used during START/RUN

  JVM_OPTS="-Xmx512M -Xss256K"

It may be necessary to set the -XX:MaxMetaspaceSize which by default is only limited by the amount of memory available to the java process. Not setting this value could result in a server crash. Do not set Metaspace to be the same as a previous PermGem size as they have different meanings and purposes.