Upgrading a ThingWorx Connection Server from 9.2.0 to 9.2.1
This topic explains how to upgrade a ThingWorx Connection Server from version 9.1.1 to 9.2.0 when using the Connection Server in a ThingWorx Single-Server Environment and when using it in a ThingWorx High Availability (HA) Clustering environment. Start with the first section listed, "Best Practices for Upgrading".
Click a section title to display its content. Click the title again to hide the content.
Best Practices for Upgrading
 | Starting with v.9.2.0, the Connection Server no longer supports Java 8. If you have not already, you must upgrade to Oracle JDK 11 or Amazon Corretto Java 11 (Open JDK) on the machine that will run the Connection Server. The Oracle Java SE Development Kit 11 is available for download at Java Downloads | Oracle. The Amazon Corretto 11 (OpenJDK 11) is available for download at Downloads for Amazon Corretto 11 - Amazon Corretto. |
Before you begin the upgrade, here are some best practices to follow:
• Upgrade your ThingWorx Platform computer to Java 11 and then upgrade your ThingWorx Platform to v.9.2.0 before you begin the upgrade for the Connection Server.
• Similarly, upgrade the computer that will run the Connection Server v.9.2.0 to use Java 11.
• After upgrading to Java 11, make sure that you set the JAVA_HOME environment variable to point to the Java 11 JDK.
• Copy any site-specific configuration values from the existing installation configuration file to the new installation configuration file. Do not just copy the existing configuration file to the new installation.
Downloading the Distributon Bundle
To download the distribution bundle for your operating system, go to the PTC Support site, Software Download page and then
1. Select the Product Family, THINGWORX CONNECTION SERVICES.
2. On the download page for the ThingWorx Connection Services Product Family, the releases are numbered by the related release of ThingWorx Platform. To upgrade, expand the Release 9.3 node.
3. Expand the node, ThingWorx Connection Server, and then the node, Most Recent Datecode.
4. Click HTTPS to download the distribution bundle.
5. Extract the downloaded zip file to an appropriate location.
Upgrading from 9.2.0 to 9.2.1 in a ThingWorx Single-Server Environment
These are the instructions for upgrading the ThingWorx Connection Server from version 9.1.1 to version 9.2.0 when the Connection Server connects to a ThingWorx single-server environment. It is expected that you have already downloaded and extracted the distribution bundle.
1. If you have not yet upgraded to Java 11, you must do so before attempting to install the 9.2.0 version of the Connection Server. Java 8 is no longer supported in this release. It is recommended that you perform a fresh installation of Java 11 and then a fresh installation of the Connection Server. The Oracle Java SE Development Kit 11 is available for download at https://www.oracle.com/java/technologies/javase-jdk11-downloads.html. The Amazon Corretto 11 (OpenJDK 11) is available for download at https://docs.aws.amazon.com/corretto/latest/corretto-11-ug/downloads-list.html.
| | Make sure you set the JAVA_HOME environment variable to point to the new JDK installation. |
2. If the currently installed Connection Server is using an encrypted configuration file and you still have the configuration file for the encryption library, decrypt it following the decrypting instruction in Step 5 of the section, Encrypting the Configuration File.
3. It is recommended to make a copy of the new sample configuration file, cxserver-sample.conf, in the conf directory of the extracted distribution. Open the file in a text editor and save it as cx-server.conf.
4. Open the decrypted configuration file and re-apply the custom settings from that file to the new cx-server.conf..
5. If TLS is used for WebSocket connections between the AlwaysOn Edge devices and the Connection Server, convert the JKS keystore to a PKCS#12 keystore. If you have already done this, skip to Step 6.
 | If you must continue using a JKS keystore, set the cx-server.protocol.http-server.ssl.key-store.type property to jks in the configuration file and skip the rest of this step. Using a JKS keystore is discouraged because it is less secure format than PKCS#12. |
a. To convert the existing Connection Server keystore from a JKS keystore to a PKCS#12 keystore, follow the instructions in the topic, Converting JKS Keystores to PKCS Keystores.
b. In the configuration file, update the cx-server.protocol.http-server.ssl.key-store.file property in the configuration file to point to the PKCS#12 keystore.
c. If the password has changed, update the cx-server.protocol.http-server.ssl.key-store.password property in the configuration file.
6. Save the configuration file.
7. To encrypt the configuration file again, follow the instructions in Encrypting the Configuration File.
8. If a new configuration file was created, be sure to update the environment variables to point to the new configuration file location. For assistance with this step, refer to Setting the Environment Variables for the Connection Server.
9. Shut down the v.9.1.1 Connection Server.
10. Start the v.9.2.0 Connection Server.
11. Verify that the Connection Server successfully connected to ThingWorx by confirming it appears in the ThingWorx Composer list of Connection Servers and shows "Running" at the top. To access this page follow these steps:
a. In the left navigation panel of ThingWorx Composer, click the 
icon (Monitoring menu).
icon (Monitoring menu).b. Select Connection Servers to display the page.
Upgrading from 9.2.0 to 9.2.1 in a ThingWorx High Availability Clustering Environment
These instructions explain how to upgrade the Connection Server from version 9.1.1 in a ThingWorx Single-Server environment to version 9.2.0 in a ThingWorx High Availability (HA) Clustering environment.
IMPORTANT! The 9.1.x and 9.2.0 versions of the Connection Server support Oracle JDK 11 and Amazon Corretto 11 (OpenJDK 11). However, although the 9.1.x versions continue to support Java 8, the 9.2.0 and later versions no longer support Java 8. With v.9.2.0 and later, you must upgrade to Java 11. It has important security enhancements and fixes.
To install the Connection Server version 9.2.0 in a ThingWorx High Availability (HA) Clustering environment, follow these steps:
1. Navigate to the conf subdirectory of the new Connection Server installation, and make a copy of the cx-server-ha-sample.conf file and rename it to cx-server.conf. Then open it in a text editor.
2. If the currently installed Connection Server is using an encrypted configuration file and you still have the configuration file for the encryption library, decrypt it following the decrypting instruction in Step 5 of the section, Encrypting the Configuration File.
3. Open the decrypted configuration file and re-apply the custom settings to the new cs-server.conf file.
4. If TLS is used for WebSocket connections between the AlwaysOn Edge devices and the Connection Server, convert the JKS keystore to a PKCS#12 keystore. If you are already using PKCS#12, skip to Step 5.
| | If you must continue using a JKS keystore, set the cx-server.protocol.http-server.ssl.key-store.type property to jks in the configuration file and skip the rest of this step. Using a JKS keystore is discouraged because it is less secure format than PKCS#12. |
a. To convert the existing Connection Server keystore from a JKS keystore to a PKCS#12 keystore, follow the instructions in the topic, Converting JKS Keystores to PKCS Keystores.
b. In the configuration file, update the cx-server.protocol.http-server.ssl.key-store.file property in the configuration file to point to the PKCS#12 keystore.
c. If the password has changed, update the cx-server.protocol.http-server.ssl.key-store.password property in the configuration file.
5. You must set the following properties to enable service discovery:
cx-server {
. . .
platform.transport = "websockets_active_active"
transport.websockets.service-discovery.enabled = true
. . .
}
6. You must add the hosts and ports of the ZooKeeper instances to which the Connection Server should connect as a comma-separated list of {host}:{port}, as shown in the following example:
cx-server {
discovery {
connectionString = "zookeeper-1:2181,zookeeper-2:2181,zookeeper-3:2181"
}
}
7. If ZooKeeper is configured to use SSL/TLS, enable the Connection Server to connect to ZooKeeper securely by following the instructions in the section, "Configuring the Connection Server," in the topic, Configuring SSL/TLS for ZooKeeper in the ThingWorx Platform 9 Help Center.
8. If Zookeeper is configured to use Simple Authentication and Security Layer (SASL), enable the SASL support in the Connection Server by uncommenting and setting the following properties:
cx-server {
. . .
#discovery {
# sasl-enabled = true
# sasl-krb5-conf-file = /path/to/kerberos-conf
# sasl-jaas-file = /path/to/jaas-conf
#}
}
For information on configuring SASL for ZooKeeper, refer to ZooKeeper Client-Server mutual authentication.
9. The Connection Server needs to be configured with the service name used to lookup the ThingWorx Platform instances in ZooKeeper and determine whether to connect securely to the registered ThingWorx Platform instances.
◦ To connect securely with SSL/TLS to the ThingWorx Platform instances, uncomment and set the following properties:
cx-server {
# transport.websockets.service-discovery.tls-enabled = true
# transport.websockets.service-discovery.service-name = "thingworx-https"
}
◦ To connect without SSL/TLS to the ThingWorx Platform instances, uncomment and set the following properties:
cx-server {
# transport.websockets.service-discovery.tls-enabled = false
# transport.websockets.service-discovery.service-name = "thingworx-http"
}
| | By default the ThingWorx Platform uses the thingworx-http service name when registering its HTTP endpoint information in ZooKeeper and the thingworx-https service name when registering its HTTPS endpoint information. If the ThingWorx Platform is configured to use different service names, be sure to use the correct service name in the preceding Connection Server configuration. |
10. If SSL/TLS is used to connect securely to the ThingWorx Platform instances and the SSL/TLS certificates presented by the ThingWorx Platform instances do not contain the instance’s IP address that is registered in ZooKeeper, you must disable host name verification by uncommenting and setting the following properties in the configuration file:
cx-server {
# protocol.http-client.ssl.verify-host = false
# transport.websockets.connections.verifyHostName = false
}
| | The IP address of a ThingWorx Platform instance can be set in the instance’s SSL/TLS certificate either in Subject Common Name (CN) field or in the Subject Alternative Name field. The IP address that the ThingWorx Platform registers in ZooKeeper is either the first site-local IP address, if found, or the first non-loopback IP address found on the available network interfaces. |
11. To encrypt the configuration file again, follow the instructions in Encrypting the Configuration File.
12. If a new configuration file was created, be sure to update the environment variables to point to the new configuration file location. For assistance with this step, refer to Setting the Environment Variables for the Connection Server.
13. Shut down the v.9.1.x Connection Server.
14. Start the v.9.2.0 Connection Server.
15. Verify that the Connection Server successfully connected to ThingWorx by confirming it appears in the ThingWorx Composer list of Connection Servers and shows "Running" at the top. To access this page follow these steps:
a. In the left navigation panel of ThingWorx Composer, click the 
icon (Monitoring menu).
icon (Monitoring menu).b. Select Connection Servers to display the page.