Upgrading Tomcat
This page is for system administrators who are upgrading Tomcat.
Overview
The instructions on this page provide guidance on how to upgrade:
- a standard Tomcat setup
- a Tomcat setup with some configuration changes to
server.xml
andweb.xml
.
Most PhixFlow installations use a standard Tomcat setup. Some common variations are:
SSL termination is handled in Tomcat to provide a secure connection. This means you have installed a certificate.
Tomcat uses a non-standard port number.
PhixFlow can export large files because the limit set by
maxPostSize
has been increased or disabled.
To upgrade, we recommend you install the target version of Tomcat as a new installation, then move resources and configuration changes from the previous install. This means the common variations listed above will be moved into the new installation.
Tomcat provides a tool for comparing configuration files between patch versions; for example, for version 9 see https://tomcat.apache.org/migration-9.html#Upgrading_9.0.x. However, at PhixFlow, we have found it easier and more reliable to treat even minor upgrades as new installations.
On Linux
The following instructions assume that Tomcat is installed in /opt/tomcat
, as recommended in PhixFlow’s installation instructions. If you have installed Tomcat somewhere else, remember to replace /opt/tomcat
in commands with your installation directory.
Step 1 Identify your current version of Tomcat
At the command line, enter:
/opt/tomcat/bin/version.sh
Step 2 Check your configuration (if necessary)
You can skip this step if you have notes or a checklist of your configuration.
If you cannot remember what configuration changes you have made to Tomcat, you can find out by comparing your current configuration files to those in a standard installation.
- Find your current version of Tomcat on the Tomcat download page:
- for version 8: http://tomcat.apache.org/download-80.cgi
- for version 9: https://tomcat.apache.org/download-90.cgi
- for older versions of Tomcat look for your version under
Archives
→ <your version> →bin
. Download the link with the formatapache-tomcat-VERSION.
tar.gz
Download your current version to a temporary location, for example
/tmp/tmpTomcat
, and unpack it:cd /tmp mkdir tmpTomcat cd tmpTomcat curl -O https://archive.apache.org/dist/tomcat/tomcat-8/v8.0.45/bin/apache-tomcat-8.0.45.tar.gz tar xvf apache-tomcat-8*tar.gz --strip-components=1
Use the
diff
command to compare theconf
directory with your current installation'sconf
directory, for example:diff /opt/tomcat/conf /tmp/tmpTomcat/conf
- Make a note of any differences between the two configurations.
You will need to reproduce these changes in the new installation in Step 5, below.
In particular, check for changes in:- server.xml
- context.xml
- web.xml
- tomcat-users.xml.
PhixFlow does not recommend updates to this file but you may have enabled internal Tomcat users.
Make a note of any extra files in your current installation's
tomcat/bin
directory. For example, you may have files to integrate with a monitoring agent. Use thediff
command to compare thetomcat/bin
directory with your current installation's tomcat/bin directory, for example:diff /opt/tomcat/bin /tmp/tmpTomcat/bin
You will copy these files into the new
bin
directory in step 5.Make a note of any extra files in your current installation's
tomcat/lib
directory. For example, you may have files to support connections to additional databases. Usediff
to compare these directories, for example:diff /opt/tomcat/lib /tmp/tmpTomcat/lib
You will copy these files into the new
tomcat/lib
directory in step 5For connections to databases in addition to Oracle, MySQL and MySQL, use Database Driver to configure the additional library files required.
Remove your temporary download. For example:
cd /tmp rm -r tmpTomcat
Step 3 Back-up the current Tomcat installation
Stop Tomcat.
If you have installed Tomcat to run undersystemd
, enter:sudo systemctl stop tomcat
Move the current
/opt/tomcat
directory into a backup.If you have a
tomcat-back
directory from a previous upgrade, delete it:sudo rm -r /opt/tomcat-back
Create the backup:
sudo mv /opt/tomcat/ /opt/tomcat-back
Step 4 Install the new version of Tomcat
To install the required new version of Tomcat:
Download
- To find the latest version, go to the Tomcat downloads page: https://tomcat.apache.org/download-90.cgi
- Find the latest Binary Distributions section, then the Core sub-heading, and copy the tar.gz link.
To download Tomcat, on the Linux server, go to the
tmp
directory. Use thecurl
command to download from the the tar.gz link.cd /tmp curl -O http://mirror.ox.ac.uk/sites/rsync.apache.org/tomcat/tomcat-9/v9.0.38/bin/apache-tomcat-9.0.38.tar.gz
- Install
Unpack the Tomcat
tar.gz
file into/opt/tomcat
.This creates the tomcat folders (conf, logs, webapps etc.) directly undersudo mkdir /opt/tomcat cd /opt/tomcat sudo tar xvf /tmp/apache-tomcat-9*tar.gz --strip-components=1
/opt/tomcat
.Set the file ownership and permissions.
cd /opt/tomcat sudo chown -R tomcat webapps/ work/ temp/ logs/ sudo chgrp -R tomcat . sudo chmod -R g+r conf sudo chmod g+x conf
Step 5 Configure the new version of Tomcat
Move the PhixFlow webapp from the backup into the new Tomcat
webapps
directory.sudo mv /opt/tomcat-back/webapps/phixflow /opt/tomcat/webapps/
If you have custom folders, move them back into the new Tomcat installation, for example
tomcat/secure
andtomcat/metadata
.- If there were any additional files in
tomcat/bin
, copy these back into the new installation. - If there were any additional files in
tomcat/lib
, copy these back into the new installation. Apply the standard configuration settings and hardening steps; see Install Tomcat.
Copy your specific configurations from the backup files into the Tomcat configuration files, for example: SSL termination, non-standard ports, etc.
Copy only the sections that are specific to your installation.You do not need to re-create the service configuration for Tomcat. For example, if you previously installed Tomcat to run under
systemd
, the service script will continue to work after the upgrade.You may need to revise your service configuration if you have:
also updated Java
not installed Tomcat in the same location as previously.
Step 6 Restart and Test
Restart Tomcat
sudo systemctl start tomcat
Test that Tomcat is running and the PhixFlow webapp can run:
sudo systemctl status tomcat curl http://localhost:8080/phixflow/start.html
Check that you are now running the required version of Tomcat:
/opt/tomcat/bin/version.sh
On Windows
The following instructions assume that you already have Tomcat 9 installed in c:\app\tomcat9
, as recommended in PhixFlow’s installation instructions. If Tomcat is at a different version, and/or you have chosen to install it in a different location, remember to replace
in the following commands with your installation directory.c:\app\tomcat9
Step 1 Identify your current version of Tomcat
To run the following process you must have the following environment variables set:
- CATALINA_HOME
- JAVA_HOME
If you have not set these variables, you can set them in your current session. For example, in Powershell, enter:
$env:JAVA_HOME="C:\Program Files\Java\jre1.8.0_282" $env:CATALINA_HOME="C:\app\tomcat9"
To check the version, in PowerShell enter:
& "C:\app\tomcat9\bin\version.bat"
Step 2 Check your configuration
You can skip this step if you have notes or a checklist of your configuration.
If you cannot remember what configuration changes you have made to Tomcat, you can compare your configuration files to those in a standard installation.
Download a new copy of your current version of Tomcat.
- Find your current version of tomcat on the Tomcat download page:
- for version 8: http://tomcat.apache.org/download-80.cgi
- for version 9: https://tomcat.apache.org/download-90.cgi
- for older versions of Tomcat look for your version under
Archives
→ <your version> →bin
. Download the link with the formatapache-tomcat-VERSION-windows-x64.zip
- Download your current version and unpack it to a temporary directory, for example
TempCurrent
. Do not install it. Use the
compare
command to find the differences between theTempCurrent\conf
files and those in your current installation'sconf
directory. For example, in PowerShell, enter:compare-object (get-content c:\app\tomcat9\conf\file.xml) (get-content TempCurrent\conf\file.xml)
In particular, you are looking for differences in the following files:
- server.xml
- context.xml
- web.xml
- tomcat-users.xml.
PhixFlow does not recommend updates to this file but you may have enabled internal Tomcat users.
- Make a note of any differences between your current installation and the test installation.
You will need to reproduce these changes in the new installation in Step 7 below. There may be additional files in your current installation's
tomcat\bin
directory, for example to integrate with a monitoring agent. Use the compare command to compare thebin
directory with your current installation's tomcat\bin directory, for example:compare-object (get-childitem c:\app\tomcat9\bin) (get-childitem TempCurrent\bin)
- Make a note of any extra files in current installation's
bin
directory - these will need copying back in step 7 There may be additional files in your current installation's
lib
directory - usually these will be for supporting to connections to databases outside of the standard set. Use the compare command to compare these directories, for example:compare-object (get-childitem c:\app\tomcat9\lib) (get-childitem TempCurrent\lib)
To support connections to databases outside of the standard set, there is now a better way of setting up the additional library files: Database Driver
- Make a note of any extra files in your current installation's
lib
directory - these will need copying back in step 7 - Remove your temporary download.
Step 3 Back up the current Tomcat installation
Copy the entire
tomcat9
folder to a backup location.If your log files are large and you do not want to retain them, as a minimum, you must back up the following
tomcat9\
sub-folders:webapps
conf
lib
bin
- and if they exist:
metadata
andsecure.
Step 4 Note your Java setup
- Open Tomcat Properties. If you need further details on how to do this, see: Tomcat start/ stop, open properties
- Go to the Java tab.
- Check and make a note of your changes to the Java setup, including those required by PhixFlow.
In particular, note:- the path of the Java Virtual Machine
Java options. Make a note of any options you have added in addition to the PhixFlow recommendations. PhixFlow recommends:
-Djava.awt.headless=true -XX:+PrintGCDetails -XX:+PrintGCDateStamps -Xloggc:C:\tomcat\logs\gc-%t.log
- Memory allocation
- On the server, open Services → Apache Tomcat service properties:
If Tomcat is running under a service account, make a note of the service account name. Ensure you have the service account password.
Step 5 Uninstall the current version of Tomcat
We do not recommend using Uninstall.exe in the tomcat9
base directory as we found it did not work. The following method above has proved more reliable.
- Open Add or remove programs.
- Locate Tomcat and click Uninstall.
- Windows asks if you want to remove all files:
- Recommended - Click Yes if you have taken a backup of the necessary folders in Step 3.
- Alternatively - Click No if you want Windows to keep the
conf
,logs
,null
andwebapps
directories, as well as any other directories you have added.
Step 6 Install the new version of Tomcat
To install the required new version of Tomcat, follow the instructions on Install Tomcat on Windows. Remember to reapply the settings:
recommended for PhixFlow; see Configure the service wrapper
you noted in Step 4, such as:
JVM path
memory settings
service account; see Run under service account.
Step 7 Configure the new version of Tomcat
Copy the PhixFlow webapp from the backup into the new Tomcat
webapps
directory, for example frombackup\webapps\phixflow
totomcat9\webapps\phixflow
.
This step means PhixFlow configuration files, such asphixflow-datasource.xml
are updated with your configuration.- If the webapp has a datalink, this will need recreating
If you have custom folders, copy them back into the new Tomcat installation, for example
tomcat9\secure
andtomcat9\metadata
.- If there were any additional files in
tomcat9\bin
, copy these back into the new installation - If there were any additional files in
tomcat9\lib
, copy these back into the new installation Apply the standard configuration settings and hardening steps; see Install Tomcat.
Copy your specific configurations (as identified in Step 2) from the backup files into the Tomcat configuration files, for example: SSL termination, non-standard ports, etc.
Copy only the sections that are specific to your installation.If you are using MS SQL Server integrated authentication, remember to replace the Java option to set the classpath for
sqljdbc_auth.dll
. This should be included in the Java options you noted in Step 4, above. To be certain, you can check instructions for Tomcat configuration on MS SQL Server Integrated Authentication.
Step 8 Restart and Test
Restart the Tomcat service and check that it is running.
Start the PhixFlow webapp and check that it is running.
Check that you are now running the required version of Tomcat.
Assuming you have set the JAVA_HOME environment variable, in PowerShell, enter:& "C:\app\tomcat9\bin\version.bat"