In this post we'll take a look at how to migrate the RSSO application to a new version of tomcat web server. There are many reasons why you might want to migrate to a new tomcat version, some of which can include:
- Keeping up with the latest supported version of Tomcat
- A newer version has the features you require
- New Tomcat support for the latest version of java
- The need for better web server performance
In this blog we'll use the example of migrating the RSSO application from tomcat 7.0.62 to apache-tomcat8.5.23. We will be installing the new version of Tomcat and Java on the same machine as the 7.0.62 Tomcat install to minimise downtime.
File System locations used in this example:
Tomcat 7 : C:\Program Files\Apache Software Foundation RSSO\apache-tomcat-7.0.62
Tomcat 8 : C:\Program Files\Apache Software Foundation RSSO\apache-tomcat8.5.23 (will be installed in this path)
Java 7 : C:\Program Files\Java\jre7
Java 8 : C:\Program Files\Java\jre1.8.0_151 (will be installed in this path)
This procedure will be done on Windows but the process will still be valid on Linux, unless stated for Windows only.
Installing The New Version of Tomcat(for this post apache-tomcat8.5.23 & Java jre1.8.0_151)
2. Install java. NOTE: If installing Java on the same server as a previous install of Tomcat, Java installer will asks to uninstall previous versions of java select "No". This is until we confirm that the new version of Tomcat is working as expected.
3. Extract the downloaded Tomcat files to the Apache Software directory i.e. "C:\Program files\ApacheSoftware" or "\opt\ApacheSoftware" or where ever you have a previous version of TC
4. Open a command prompt and set environment variable JAVA_HOME to the new version of tomcat. We will set the Java environment variable permanently at a later point once we have confirmed everything is working. Keep this command prompt open.
5. From command prompt run the following command and confirm the correct version of java is running "Java -version"
6. On windows we need to create the service for Tomcat. Open command prompt "cd" in to the the Apache/tomcat/bin directory and run "service.bat install" command. Once the service has been created successfully (fig1) check in windows services manger for the service.
If you have a previous version of Tomcat running on the server leave it running for the time being and do no start the new Tomcat service just yet.
Moving the RSSO Installation Files
We now have to move the RSSO application files from the previous install of Tomcat to the new one.
1. Copy the "/Tomcat/webapps/rsso" directory from the previous Tomcat install to the same location on the new Tomcat install. In the example we are using from
"C:\Program Files\Apache Software Foundation RSSO\apache-tomcat-7.0.62\webapps" to "C:\Program Files\Apache Software Foundation RSSO\apache-tomcat8.5.23\webapps"
2. Copy the following files from the old version of Tomcat from tomcat/lib to the same location on the new version. Note if you have installed a future version of RSSO relative to this blog date the versions numbers may have changed.
3. If you have a trust store location used by RSSO SAML Authentiction, login to the RSSO Admin console --->Advanced and check where the trust/keystore store path is. You will then need to copy this file from the the old version of Tomact to the same location on the new install (fig2)
fig2 Shows the location of the store usually used for SAML authentication (field names may have changed from one version of RSSO to another) just copy the file to the new Tomcat location if its not a common path as show below
Moving Tomcat files & Edit Configuration File
Our next steps is to move any tomcat configuration files from the previous version to the next version & also make some changes to the server.xml file if using HTTPS
1. If the previous Tomcat version was running on HTTPS we need to move over, the keystore file and trustore files files (If being used) RSSO
Open the Tomcat\conf\server.xml file, search for " keystoreFile" This will give you the location of the keystore and truststore (if being used)
copy the keystore file from the previous version of tomcat to the same location on the new Tomacat server. If the path is common to both versions of tomacat it does not need to be copied for example if the keystore path is "C:\mykeystores\keystore.p12" then there is no need to move it.
2. If you have made any customisation to the /tomcat/conf/context.xml file then copy this file to the new Tomcat Install in the same location
3. If using HTTPS our next step is to copy the entries from the server.xml file from the old version of Tomcat to the new version. Open the tomcat/conf/server.xml file search for " keystoreFile" copy the whole segment from this connector port element and place it in the same location in the new Tomcat server.xml file and save the file. The segment will look like the example below
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true"
keystoreFile="C:/Program Files/Apache Software Foundation RSSO/apache-tomcat-7.0.62/conf/keystore.p12"
NOTE: Remember if the keystore location is in the old Tomcat version path (highlighted in green) you will need to change it to point to the new version path as per example below
FROM: keystoreFile="C:/Program Files/Apache Software Foundation RSSO/apache-tomcat-7.0.62/conf/keystore.p12"
TO: keystoreFile="C:/Program Files/Apache Software Foundation RSSO/apache-tomcat-8.5.23/conf/keystore.p12"
At this point we have configured everything we need to start the new Tomcat service.
1. Stop the old tomcat service
2. Start the new tomcat service
3. Login to the RSSO admin console with the same URL as before
You should now be able to continue testing. Test for a few days to make sure everything is OK before moving on to finalising the install. If you are not able to login to the RSSOadmin console
stop the new tomcat service, restart the old one then check the troubleshooting section below
If you have been testing for a few days and have not come across any issues with the new version of Tomcat you can proceed to finalise the install. To do this
Windows: Set System Variable JAVA_HOME and or JRE_HOME to the new version of Java (just be aware of any other applications using the old java version) there is no harm in not doing this as the Tomcat service will always use the new one if you ran the service.bat correctly above.
You can remove the Tomcat Service from windows by opening a command prompt "cd" in to the old version of Tomcat directory/bin and run "service.bat remove" (fig3)
You can then proceed to delete the old tomcat install files.
Linux: Set JAVA_HOME and OR JRE_HOME to the version of Java in the user profile. If you are not sure if other applications are using the old version of Java don't change it, just remember you might need to EXPORT JAVA_HOME=NewJavaPath when starting the the tomcat process. If you don't need the files from the old Tomcat version they can be deleted.
If after starting up the new Tomcat service and you are not able to log in yo the RSSO admin console, the first place to look is in the Tomcat/Logs/catalina.<date>.log file
check for any error messages. A common one from the procedure above would be
java.lang.IllegalArgumentException: Illegal character in path at index 12: C:/ProgramFiles/Apache Software Foundation RSSO/apache-tomcat-8.5.23/conf/keystore.p12
at java.net.URI.create(Unknown Source)
at java.net.URI.resolve(Unknown Source)
This message indicates that the path to the keystore file is not found. Confirm the path is correct
If there are not any errors in the catalina.log file, then the webserver itself has come up correctly. The next step is to look in the Tomcat/logs/rsso.log file for any errors, a common one
from the procedure above is
Details: Unable to load class: com.microsoft.sqlserver.jdbc.SQLServerDriver from ClassLoader:java.net.URLClassLoader@19469ea2;ClassLoader:ParallelWebappClassLoader
----------> Parent Classloader:
This usually indicate some of the RSSO library files are missing from the Tomcat/lib directory, confirm you have copied the files from the previous version of Tomcat correctly, the files are
Note if you have installed a future version of RSSO relative to this blog date the versions numbers may have changed.
If all these files are in the lib directory, look at the error message in the RSSO.log file, that will usually give you a hint about which lib file is missing, then check the previous version of Tomcat/lib directory for the file name and copy it over.