How to upgrade Java for Spotfire® Server 7.5 -10.9

Upgrade Java for Spotfire® Server 7.5-10.9

Disclaimer

This article was originally written for Spotfire Server 7.5. In Spotfire Server 10.3, the hotfix tool was removed but the instructions could still be useful. The article is not valid for Spotfire Server 10.10 or later.

Introduction

Spotfire Server includes an Oracle Java Development Kit (JDK). This JDK is usually the most recent and secure version at the time of the Spotfire Server release (note: it is also regularly updated in Service Pack releases for Spotfire Server LTS versions). If you always want to use the most recent Java version though, you must upgrade to the newer Java version manually, whenever it is released by Oracle. To make a full switch, you must do changes for both the server and the node manager.

This page describes how to upgrade Java for Spotfire Server version 7.5-10.9 specifically. For other versions, please refer to the following:

• For Spotfire Server 10.10-11.2, refer to the community article "How to upgrade Java for Spotfire® Server 10.10-11.2" (https://community.spotfire.com/articles/spotfire/upgrade-java-spotfire-server-1010-112/)
• For Spotfire® Server 11.3 and higher, refer to the page "Switching the Java Development Kit" in the Spotfire Server Installation and Administration Manual:  https://docs.tibco.com/pub/spotfire_server/12.0.0/doc/html/TIB_sfire_server_tsas_admin_help/server/topics/switching_the_java_development_kit.html (refer to the manual for your specific version).

Upgrade process

It is possible to perform this upgrade with minimal impact on the Spotfire system. It is however necessary to restart each Spotfire Server at least once. Except for the downloading of the new Java runtime environment in step 1, the process outlined below must be followed for each Spotfire Server in your environment. 

1. Download the new Java Runtime Environment.
2. Back up the Spotfire Server.
3. Apply  Spotfire Server hotfixes.
4. Prepare the new Java Runtime Environment.
5. Switch to the new Java Runtime Environment.
6. Optional: Remove the old Java Runtime Environment.

1.    Download the new Java Runtime Environment

Download the new Java runtime environment that you want to use. The Spotfire Server expects to be running an Oracle Server Java SE Runtime Environment (?Oracle Server JRE?), but a full Oracle Java SE Development Kit will also work. The Oracle Java SE Runtime Environment does not contain all tools necessary to run the Spotfire Server and is therefore not supported. Using Java runtime environments from other vendors than Oracle is not supported either. These instructions will describe how to upgrade to a newer Oracle Server JRE version.

It is only supported to upgrade to a newer Java runtime environment of the same major version as the one bundled with the product. It is also not supported to downgrade to an older Java version (major or minor) than the one bundled with the Spotfire Server, unless you are cleared to do so by Spotfire Support.

Make sure to download the correct Oracle Server JRE version for your operating system.

• If you are running the  Spotfire Server on Windows, select the Windows x64 version. 
• If you are running the Spotfire Server on Linux, select the Linux x64 version.

For security reasons, do not forget to check the integrity of the downloaded file by verifying the file?s checksum.

2.    Back up the Spotfire Server

Before upgrading the Java runtime environment, make sure to perform a full backup of the Spotfire Server. See the ?Backup of Spotfire Server? section in the ?Backup and restore? chapter in the Spotfire Server manual for more information.

3.    Apply Spotfire Server hotfixes

Before you start the upgrade of the Java runtime environment, make sure that you have applied the latest hotfix for your version of the Spotfire Server. 

4.    Prepare the new Java Runtime Environment

The following section describes how to copy configuration information from the old Java runtime environment to the new Java runtime environment. Some of the copied information is machine specific, so it is not possible to prepare a single new Java runtime environment to be deployed on multiple Spotfire Servers. These steps must be followed once for each Spotfire Server in your environment. Also, make sure to copy ? not move ? the specified files from the old Java runtime environment to the new Java runtime environment.

a.    Install the new Oracle Server JRE

The Oracle Server JRE is shipped as a compressed archive. Extract the archive in a temporary directory. Move the extracted Java directory, which is named jdk1.X.Y_Z, where X.Y_Z denotes the version, into the <TSS installation directory>/ directory. Make sure not to extract it to the old, already existing <TSS installation directory>/jdk directory.

You will now have the following two Java directories:

• <TSS installation directory>/jdk/
• <TSS installation directory>/jdk1.X.Y_Z/

b.    Reinstall the JCE Unlimited Strength Jurisdiction Policy files

If the JCE Unlimited Strength Jurisdiction Policy files have been installed in the old Java runtime environment, they must be installed in the new Java runtime environment as well.

Note: It is your responsibility to verify that these policy files are allowed under local regulations.

c.    If the  Spotfire Server 7.5 is using the legacy Windows NT authentication

If the Spotfire Server 7.5 is configured to use the legacy Windows NT authentication method, you need to copy the files listed below from the old Java runtime environment to the new Java runtime environment. It is also recommended that you copy these files if you do not know what authentication method is being used.

• <TSS installation directory>/jdk/jre/lib/ext/server-native.jar
• <TSS installation directory>/jdk/jre/lib/ext/SfWinCon.dll

For Spotfire Server version 7.6 and higher, there is no need to copy any of those files.

d.    If the Spotfire Server is using Kerberos authentication

If the Spotfire Server is configured to use Kerberos authentication, you need to copy the files listed below from the old Java runtime environment to the new Java runtime environment. It is recommended that you copy these files if you do not know what authentication method is being used, but if the spotfire.keytab file does not exist, you are probably not using Kerberos authentication anyway.

• <TSS installation directory>/jdk/jre/lib/security/krb5.conf
• <TSS installation directory>/jdk/jre/lib/security/spotfire.keytab

e.    If the Spotfire Server is authenticating to the Spotfire database using Kerberos

If the Spotfire Server is configured to authenticate to the Spotfire database using Kerberos authentication, you also need to copy the files listed below from the old Java runtime environment to the new Java runtime environment. It is recommended that you copy these files if you do not know how the Spotfire Server authenticates to the Spotfire database, but if the files do not exist, the server is probably not authenticating using Kerberos.

• <TSS installation directory>/jdk/jre/lib/security/krb5.conf
• <TSS installation directory>/jdk/jre/lib/security/spotfire-database.login
• <TSS installation directory>/jdk/jre/lib/security/spotfire-database.keytab (if the file exists)

Note: Since the spotfire-database.keytab file contains sensitive information it must be handled with care. Make sure that unauthorized users cannot read or modify the new copy.

You must also register the spotfire-database.login file again. Open the file <TSS installation directory>/jdk1.X.Y_Z/jre/lib/security/java.security in a text editor. Locate the section which configures the ?Default login configuration file?:

#
# Default login configuration file
#
#login.config.url.1=file:${user.home}/.java.login.config

Update the last line so that it refers to the spotfire-database.login file:

#
# Default login configuration file
#
login.config.url.1=file:${user.home}/.java.login.config

Note: Make sure to remove the leading number sign (#) from the edited line.

Note: Make sure to use forward slashes in the path above, even if you are running the  Spotfire Server on a Windows operating system. 

f.    If the TICO Spotfire Server is connecting to an LDAP server using TLS (LDAPS)

If the Spotfire Server is configured to access an LDAP server using TLS (LDAPS), you may need to add the LDAP server?s certificate, or the certificate for the Certificate Authority (CA) that issued the LDAP server?s certificate, to the new Java runtime environment?s CA certificate truststore. See the section ?Configuring LDAPS? in the Spotfire Server manual for more information. However, it is important to make sure to run the keytool command in the directory <TSS installation directory>/jdk1.X.Y_Z/jre/lib/security/ and not in the old Java runtime environment, which you would do if you followed the manual?s instructions verbatim.

Note: It is very important not to just copy the file <TSS installation directory>/jdk/jre/lib/security/cacerts from the old Java runtime environment to the new Java runtime environment instead of adding the LDAP server?s certificate, or the CA certificate, to the new Java runtime environment?s CA certificate truststore. If you do that, you will be using an outdated truststore which poses a security risk.

g.    If the Spotfire Server is connecting to a database server server using TLS

If the  Spotfire Server is configured to connect to a database server using TLS, you may need to add the database server?s certificate, or the certificate for the Certificate Authority (CA) that issued the database server?s certificate, to the new Java runtime environment?s CA certificate truststore. See the section ?Configuring LDAPS? in the Spotfire Server manual for more information. These instructions apply to database servers as well. However, make sure to run the keytool command in the directory <TSS installation directory>/jdk1.X.Y_Z/jre/lib/security/ and not in the old Java runtime environment, which you would do if you followed the manual?s instructions verbatim.

Note: It is very important not to just copy the file <TSS installation directory>/jdk/jre/lib/security/cacerts from the old Java runtime environment to the new Java runtime environment instead of adding the database server?s certificate, or the CA certificate, to the new Java runtime environment?s CA certificate truststore. If you do that, you will be using an outdated truststore which poses a security risk.

h.    If the Spotfire Server is authenticating to an LDAP server using GSSAPI

If the Spotfire Server is configured to authenticate to an LDAP server using GSSAPI, you need to copy the following file from the old Java runtime environment to the new Java runtime environment:

• <TSS installation directory>/jdk/jre/lib/security/krb5.conf

i.    If using Spotfire Server 7.8 or lower, update the launch scripts for the Configuration Tool on Windows

In the Java SE 8u121 release, Oracle removed the jdk1.X.Y_Z\bin\javaw.exe file. In Spotfire Server 7.5 to 7.8, this file is explicitly referenced by the launch script for the Configuration Tool on Windows. This means that if you upgrade any of those versions to Java SE 8u121 or later, you need to update the launch script with the correct path to the javaw binary.

Open the file <TSS installation directory>/tomcat/bin/uiconfig.bat in a text editor . Change %JAVA_HOME%\bin\javaw to %JAVA_HOME%\jre\bin\javaw and save the file.

The modified launch script will work with both the old and new Java runtime environments.

Note: For Spotfire Server version 7.9 and higher, there is no need to edit this file.

5.    Switch to the new Java Runtime Environment

When the preparation of the new Java runtime environment is done, it is time to switch from the old to the new Java runtime environment.

1. Shut down the Spotfire Server.
2. Rename the directory <TSS installation directory>/jdk to <TSS installation directory>/jdk.original.
3. Rename the directory <TSS installation directory>/jdk1.X.Y_Z to <TSS installation directory>/jdk.
4. Start the Spotfire Server.

The Java runtime environment has now been upgraded.

6.    Optional: Remove the old Java Runtime Environment

Once you decide that the old Java runtime environment is not needed anymore, it can easily be removed by deleting the directory <TSS installation directory>/jdk.original. However, it will not cause any problems keeping it. If you remove the old Java runtime environment, you cannot revert the Java changes without restoring from a backup. Thus, it is suggested that you perform an extra backup of the Spotfire Server as described in step 2 above before deleting the <TSS installation directory>/jdk.original directory.

How to revert to the old Java Runtime Environment

If you for some reason need to switch back to the old Java runtime environment it is easy to do so, assuming the old Java runtime environment has not already been removed.

1. Shut down the Spotfire Server.
2. Rename the directory <TSS installation directory>/jdk to <TSS installation directory>/jdk.reverted.
3. Rename the directory <TSS installation directory>/jdk.original to <TSS installation directory>/jdk.
4. Start the Spotfire Server.

The Spotfire Server will now use the original Java runtime environment version again.

Upgrade Java for Spotfire Node Manager

Introduction

The Spotfire node manager (?TSNM?) bundles a Java runtime environment. This Java runtime environment is usually the most recent and most secure version at the time of the Spotfire Server release. If you always want to use the most recent Java version, you need to manually upgrade to the newer Java version whenever it is released by Oracle.

Upgrade process

It is possible to perform this upgrade with minimal impact on the Spotfire system. It is however necessary to restart each Spotfire node manager at least once. The process outlined below must be followed for each Spotfire node manager in your environment.

1. Install the new Java Runtime Environment.
2. Switch to the new Java Runtime Environment.
3. Optional: Remove the old Java Runtime Environment.

It is assumed that a new Java runtime environment has already been downloaded for the Spotfire Server. The same Java runtime environment can be used for the Spotfire Node Manager.

1.    Prepare the new Java Runtime Environment

The Oracle Server JRE is shipped as a compressed archive. Extract the archive to the Spotfire node manager installation directory so that it can be found on the path <TSNM installation directory>/jdk1.X.Y_Z, where X, Y and Z correspond to the Java version. Make sure not to extract it to the old, already existing <TSNM installation directory>/jdk directory.

2.    Switch to the new Java Runtime Environment

When the preparation of the new Java runtime environment is done, it is time to switch from the old to the new Java runtime environment.

1. Shut down the Spotfire node manager.
2. Rename the directory <TSNM installation directory>/jdk to <TSNM installation directory>/jdk.original.
3. Rename the directory <TSNM installation directory>/jdk1.X.Y_Z to <TSNM installation directory>/jdk.
4. Start the Spotfire Node Manager.

The Java runtime environment has now been upgraded.

3.    Optional: Remove the old Java Runtime Environment

Once you decide that the old Java runtime environment is not needed anymore, it can be removed by deleting the directory <TSNM installation directory>/jdk.original. However, it will not cause any problems keeping it. If you remove the old Java runtime environment, you cannot revert the Java changes without reinstalling or restoring from a backup. Thus, it is suggested that you perform an extra backup of the Spotfire Server as described in step 2 above before deleting the <TSNM installation directory>/jdk.original directory.

How to revert to the old Java Runtime Environment

If you for some reason need to switch back to the old Java runtime environment it is easy to do so, assuming the old Java runtime environment has not already been removed.

1. Shut down the Spotfire node manager.
2. Rename the directory <TSNM installation directory>/jdk to <TSNM installation directory>/jdk.reverted.
3. Rename the directory <TSNM installation directory>/jdk.original to <TSNM installation directory>/jdk.
4. Start the Spotfire node manager.

The Spotfire node manager will now use the original version again.