Skip to content

Latest commit

 

History

History
222 lines (193 loc) · 9.94 KB

upgrading-to-tcat-server-6-r2-p1.adoc

File metadata and controls

222 lines (193 loc) · 9.94 KB

Upgrading to Tcat Server 6 R2 P1

This page provides important information for users who are upgrading from Tcat Server 6 R2 to the R2 P1 release. Throughout this page, the directory of your Tomcat installation is referred to as CATALINA_HOME. For information on what has changed in this release, see the Release Notes Tcat 6 R2.

Upgrading via the Installer

The R2 P1 installer upgrades your Tcat installation automatically. It installs a new console and a new agent WAR inside the installation directory. It backs up the previous console and agent into the CATALINA_HOME/tcat-backup-DATE in case you need to roll back to your previous installation.

First, stop your Tomcat or Tcat Server instance.

Before you run the installer, back up your configuration files, like this:

# cp $CATALINA_HOME/conf/server.xml ~/
# cp $CATALINA_HOME/conf/tomcat-users.xml ~/
# cp $CATALINA_HOME/conf/catalina.policy ~/
# cp $CATALINA_HOME/conf/catalina.properties ~/
# cp $CATALINA_HOME/conf/context.xml ~/
# cp $CATALINA_HOME/conf/logging.properties ~/
# cp $CATALINA_HOME/conf/web.xml ~/

Then, you may run the installer, and install the new Tcat Server release over your existing Tcat Server installation.

After the installer finishes installing Tcat Server, you may want to use your previous configuration settings from the configuration files that you backed up earlier.

If you have not modified the configuration files in the conf/ directory, start over with the stock configuration files from this new version of Tcat Server, and in that case you do not need to perform the configuration file copying that is shown below.

In general, if you have hand-modified any of the configuration files, you should use a diff and merge tool to inspect the differences between your backed up configuration file and the stock Tcat Server 6 R2 P1 copy, and carefully merge your changes into the new copy.

Here is a procedure you can follow:

  1. Restore your previous configuration from the backed up files:

    # cp ~/tomcat-users.xml $CATALINA_HOME/conf/tomcat-users.xml
# cp ~/context.xml $CATALINA_HOME/conf/context.xml
# cp ~/catalina.properties $CATALINA_HOME/conf/catalina.properties
# cp ~/logging.properties $CATALINA_HOME/conf/logging.properties

  2. Make sure your conf/catalina.properties has a common.loader definition that looks like this:

    common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.h

  3. Copy your backed up server.xml into place:

    # cp ~/server.xml $CATALINA_HOME/conf/server.xml

  4. Edit your server.xml to include this <Listener> among the listener elements near the top of server.xml (the order in which the listener elements are listed in the file does not matter):

    <!-- Prevent memory leaks due to use of particular java/javax APIs-->
  <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />

  5. Use a diff tool to merge in any changes from your backed up catalina.policy and web.xml files.

  6. Modify / edit your agent.properties file in all of your agent web applications so that it reports that its version number is "6.2.1". On non-Windows operating systems, you can use the following sed command to do that:

    # sed -i.bak -e 's/6\.2\.0/6.2.1/g' $CATALINA_HOME/webapps/agent/WEB-INF/agent.properties

  7. Start your Tomcat or Tcat Server instance.

  8. Clear your web browser cache, and log into the Tcat Server console. Once you are logged in, look for "Copyright 2015 MuleSoft, Inc." in the footer. If you’re still seeing an earlier year, it is likely that your web browser’s cache is still showing you an older copy of the console web application.

If you are using LDAP or the EC2 plugin, you must perform the manual steps as described at the end of this page.

Manually Upgrading

To manually upgrade using the R2 P1 installation ZIP file, you take the following steps.

  1. Stop your Tomcat or Tcat Server instance.

  2. Copy your existing Tomcat installation directory to a backup file. For example, on non-Windows operating systems, type:

    # cp -a $CATALINA_HOME $CATALINA_HOME.bak

  3. Remove the previous version of the Tcat Server console and agent webapps from your webapps/ directory:

    # cd $CATALINA_HOME/webapps
# rm -r console console.war agent agent.war

  4. Extract the R2 P1 installation ZIP file over your existing Tcat Server installation. For example, on non-Windows operating systems, type:

    # cd /opt
# unzip ~/TcatServer-6.2.1.zip

  5. If you have not modified the configuration files in the conf/ directory, you should instead start over with the stock configuration files from this new version of Tcat Server, and in that case you do not need to perform the configuration file copying that is shown below.

    In general, if you have hand-modified any of the configuration files, you should use a diff and merge tool to inspect the differences between your backed up configuration file and the stock Tcat Server 6 R2 P1 copy, and carefully merge your changes into the new copy you use.

    Here is a procedure you can follow: Restore your previous configuration from the backed up files:

    # cp ~/tomcat-users.xml $CATALINA_HOME/conf/tomcat-users.xml
# cp ~/context.xml $CATALINA_HOME/conf/context.xml
# cp ~/catalina.properties $CATALINA_HOME/conf/catalina.properties
# cp ~/logging.properties $CATALINA_HOME/conf/logging.properties

  6. Make sure your conf/catalina.properties has a common.loader definition that looks like this:

    common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar

  7. Copy your backed up server.xml into place:

    # cp ~/server.xml $CATALINA_HOME/conf/server.xml

  8. Edit your server.xml to include this <Listener> among the listener elements near the top of server.xml (the order in which the listener elements are listed in the file does not matter):

    <!-- Prevent memory leaks due to use of particular java/javax APIs-->
  <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />

  9. Use a diff tool to merge in any changes from your backed up catalina.policy and web.xml files.

  10. Modify / edit your agent.properties file in all of your agent web applications so that it reports that its version number is "6.2.1". On non-Windows operating systems, you can use the following sed command to do that:

    # sed -i.bak -e 's/6\.2\.0/6.2.1/g' $CATALINA_HOME/webapps/agent/WEB-INF/agent.properties

  11. Copy your agent’s truststore.jks file into the new installation:

    $ cp $CATALINA_HOME.bak/webapps/agent/WEB-INF/truststore.jks CATALINA_HOME/webapps/agent/WEB-INF/

  12. Modify / edit your agent.properties file in all of your agent web applications so that it reports that its version number is "6.2.1". On non-Windows operating systems, you can use the following sed command to do that:

    # sed -i.bak -e 's/6\.2\.0/6.2.1/g' $CATALINA_HOME/webapps/agent/WEB-INF/agent.properties

  13. If your original installation created a directory named galaxy-data anywhere other than in the root of your CATALINA_HOME directory, move it to the root of your CATALINA_HOME directory now. For example:

    $ mv $CATALINA_HOME/bin/galaxy-data $CATALINA_HOME/galaxy-data

  14. Clear out your work and temp directories. For example:

    $ rm -rf $CATALINA_HOME/temp/* $CATALINA_HOME/work/*

  15. Set the proper ownership and group for the runtime tree (you must have superuser privileges to perform this step). For example:

    # chown -R tomcat:tomcat $CATALINA_HOME

  16. Start your Tomcat or Tcat Server instance.

  17. Clear your web browser cache, and log into the Tcat Server console. Once you are logged in, look for "Copyright 2015 MuleSoft, Inc." in the footer. If you’re still seeing an earlier year, it is likely that your web browser’s cache is still showing you an older copy of the console web application.

If you are using LDAP or the Amazon EC2 plugin, see the directions below on how to complete the upgrade.

LDAP Upgrade

To migrate your previous LDAP configuration file from your backup to the new Tcat Server installation, you must copy the LDAP configuration file to the new installation and then copy the LDAP JAR to the Console webapp.

Copy the LDAP Configuration File

If you used the installer to upgrade, you restore your configuration by copying tcat-backup-DATE/console/WEB-INF/classes/ldap.xml to the CATALINA_HOME/webapps/console/WEB-INF/classes directory. For example, on UNIX, type:

$ cd $CATALINA_HOME
$ cp tcat-backup-DATE/console/WEB-INF/classes/ldap.xml webapps/console/WEB-INF/classes

If you upgraded manually, you restore your configuration by copying webapps/console/WEB-INF/classes/ldap.xml from your backup file to the CATALINA_HOME/webapps/console/WEB-INF/classes directory. For example, on UNIX, type:

$ cd $CATALINA_HOME
$ cp $CATALINA_HOME.bak/webapps/console/WEB-INF/classes/ldap.xml webapps/console/WEB-INF/classes

Copy the LDAP JAR into the Console Webapp

You must install the new LDAP JAR into the Console webapp as described in Enabling Authentication Through LDAP.

Amazon EC2 Plugin Upgrade

The Amazon EC2 plugin for Tcat R1 is not forward compatible with R2. You must download a new version of the plugin and install it by following the Amazon EC2 instructions.