Upgrading a ThingWorx Connection Server to Version 9.0.x
This topic explains how to upgrade a ThingWorx Connection Server from version 8.5.x to 9.0.x when using the Connection Server in a ThingWorx Single-Server Environment and when using it in a ThingWorx High Availability (HA) Clustering environment.
Downloading the Distribution 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.0 node.
3. Expand the node, ThingWorx Connection Services, 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 v.8.5.x to 9.0.x in a ThingWorx Single-Server Environment
These are the instructions for upgrading the ThingWorx Connection Server from version 8.5.x to version 9.0.x when the Connection Server connects to a ThingWorx single-server environment.
1. Navigate to the conf subdirectory of the new Connection Server installation, and make a copy of the cx-server-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 in a text editor.
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 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. Save the configuration file.
6. To encrypt the configuration file again, follow the instructions in Encrypting the Configuration File.
7. 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.
8. Shut down the v.8.5.x Connection Server.
9. Start the v.9.0.x Connection Server.
10. Verify that the Connection Server successfully connected to ThingWorx by confirming it appears in the ThingWorx Composer list of Connection Servers. In ThingWorx Composer, click the 
icon (Monitoring menu) and then select Connection Servers to display the page.
icon (Monitoring menu) and then select Connection Servers to display the page.Upgrading from 8.5.x to 9.0.x in a ThingWorx High Availability Clustering Environment
These instructions explain how to upgrade the Connection Server from version 8.5.x in a ThingWorx single-server environment to version 9.0.x in a ThingWorx High Availability Clustering environment.
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.
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 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. The Connection Server will look up ThingWorx Platform instances in the High Availability (HA) Clustering environment from ZooKeeper. To avoid confusion later, set the following property to null
cx-server.transport.websockets.platforms = null
6. Add the following lines to the configuration file to enable service discovery:
cx-server {
. . .
platform.transport = "websockets_active_active"
transport.websockets.service-discovery.enabled = true
. . .
}
7. 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"
}
}
8. 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.
9. 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 {
. . .
# transport.websockets.service-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.
10. 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, add the following to the configuration file:
cx-server {
transport.websockets.service-discovery.service-name = "thingworx-https"
transport.websockets.service-discovery.tls-enabled = true
}
◦ To connect without SSL/TLS to the ThingWorx Platform instances, add the following to the configuration file:
cx-server {
transport.websockets.service-discovery.service-name = "thingworx-http"
transport.websockets.service-discovery.tls-enabled = false
}
| | 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. |
11. 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 to 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. |
12. To encrypt the configuration file again, follow the instructions in Encrypting the Configuration File.
13. 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.
14. Shut down the v.8.5.x Connection Server.
15. Start the v.9.0.x Connection Server.
16. Verify that the Connection Server successfully connected to ThingWorx by confirming it appears in the ThingWorx Composer list of Connection Servers. In ThingWorx Composer, click the 
icon (Monitoring menu) and then select Connection Servers to display the page.
icon (Monitoring menu) and then select Connection Servers to display the page.