Overview of the ThingWorx Connection Server
The ThingWorx Connection Server is a server application that allows remote ("Edge") devices that use the ThingWorx AlwaysOn™ protocol to connect to either a single-server ThingWorx Platform installation or to a ThingWorx High Availability Clustering environment. The Connection Server handles all message routing to and from Edge devices, providing scalable connectivity to ThingWorx Platform.
The following sections briefly describe the features of the ThingWorx Connection Server. Click the title of a section to display its content. Click the title again to hide the content.
Security
For secure communications, the ThingWorx Connection Server should be configured to use SSL/TLS for all communications. For communications with a ThingWorx Platform, the Connection Server must present an application key to authenticate with the platform. As a best practice it is strongly recommended that you encrypt this configuration file. The ThingWorx Platform uses the value of the application key and the user account under which the key was generated to determine if the requested action is permissible or not. For example, if the key provided with a request is a match, but the user account associated with the key does not have sufficient permissions to fulfill it, the request is denied.
SSL/TLS Support
The Connection Server supports SSL/TLS for communications with Edge devices and with ThingWorx Platform, whether in single-server mode or in a ThingWorx High Availability Clustering environment, By default, SSL/TLS is enabled. You need to configure a trust store file and password for communicating with ThingWorx Platform. You also need to configure a keystore file and password for communicating with Edge devices.
TLS Host Name Validation
The Connection Server supports TLS host name validation. This security feature compares the requested host name with subject identifiers in the server certificate, such as the subject common name (CN) and subject alternative names. TLS host-name validation occurs during the TLS Handshake. If the host name on the server certificate does not exactly match the host provided in the Connection Server configuration, the TLS handshake fails, and the connection to the ThingWorx Platform fails. This feature is enabled by default. Disabling it is strongly discouraged.
Health Check Service
The Connection Server provides a Health Check service that monitors the connection server and returns status information. To use the monitor, a port is configured. An administrator or another service can send an HTTP request to that port and get back status codes. For example, if deployed in AWS EC2 environment, an AWS ELB may send a request to determine if another instance should be created. Currently, there are two status codes: 200 (Connected - good health) and 504 - not connected (to the ThingWorx Platform). A timeout, connection refusal, or HTTP 500 also indicate issues.
Metrics and Logging
The Connection Server supports metrics and logging, which enable you to detect and troubleshoot problems. To monitor the metrics of a connection server, use the Monitoring mashup for ThingWorx. To troubleshoot using logging, set the log level to TRACE, re-run the scenario that resulted in a problem, and review the log files.
Tunneling and HTTP Pass-through Support
The Connection Server supports tunneling for users who want to establish remote sessions with their remote devices, using applications such as UltraVNC. It also supports HTTP pass-through connections for developers who want to use the ThingWorx Platform REST services. For these connection types, SSL/TLS is supported. In addition, SSL client certificates are supported. For details about configuring the Connection Server tunneling and HTTP pass-through support, refer to Configuring the HTTP Client for HTTP Pass-Through and Tunneling.
Remote Access Support through WebSocket Endpoint (TWS)
As of v.9.0.0, the Connection Server supports the WebSocket endpoint added to ThingWorx for remote access through the ThingWorx Remote Access Client (RAC). The endpoint is referred to as "TWS". It is dedicated to remote access for ThingWorx Remote Access Clients (RAC). Two RAC clients can each establish an AlwaysOn tunnel through the same Connection Server. For more information about the TWS endpoint, refer to WebSocket Endpoint for Remote Access in the ThingWorx Help Center.
 | No additional configuration for the Connection Server is required to support the TWS endpoint. This feature requires the Remote Access Extension, v.1.2.0. You can use the latest RAC, v.1.1.0. To learn the requirements for the versions of RAC, refer to Support Matrices for ThingWorx Remote Access Extension and Remote Access Client in the ThingWorx Help Center. |
WebSocket Idle Timeouts
To ensure that the Connection Server behaves correctly when dealing with idle WebSockets, the idle timeout for all WebSockets is configurable. The default value is 60 seconds. If a WebSocket is idle for longer than the default, the Connection Server closes the WebSocket. The property for this setting is cx-server.websockets.idle-timeout-ms. It is listed in the cxserver-long-sample.conf file in your Connection Server installation. To change the timeout, copy the property from the long sample to the cxserver.conf configuration file for your Connection Server and set it to the desired value. Refer to Adjusting the transport Settings.
Any time that a WebSocket is closed, the Connection Server sends an unbind message to ThingWorx Platform. The message contains all the Things that are bound to that WebSocket. The isConnected property of the bound Things is set to false on ThingWorx Platform.
WebSocket Authentication Request Timeouts
If an authentication request is not received before the authentication request timeout expires, the Connection Server will close the WebSocket. The default timeout is 5 seconds. The property for the timeout is cx-server.websockets.auth-request-timeout and is specified in seconds. Should you need to change this value, you can copy the property from the cxserver-long-sample.conf file to the cxserver.conf file for your Connection Server and set it to the desired value. Refer to Fine-Tuning a Connection Server.
Support for Multiplexed Client Connections
The Connection Server supports multiplexed client connections. Developers using the ThingWorx Edge C SDK or the ThingWorx Edge Java SDK can create device clients that multiplex the requests/responses over multiple physical connections to the Connection Server.
| | Multiplexed clients (Java SDK) must establish all WebSockets to the same Connection Server. If using a multiplexed client, you must ensure that the load balancer directs all traffic for a given client to the same Connection Server. If all WebSockets do not go to the same Connection Server, the client experiences issues with outgoing messages. In addition, if one of the Connection Servers to which the client is attached fails, all Things bound through that Connection Server show up as not connected in the ThingWorx Platform. However, the clients act as though they are still bound and do not try to re-bind. These Remote Things can neither receive outgoing messages from the platform nor send messages to the platform. Restarting the clients resolves the issue. |
Support for Compression
The Connection Server v8.2 and later supports compression for websocket connections using zlib 1.2.11. Note that WebSocket compression is completely mediated by the client side. That is, the client must specifically request compression. The ThingWorx Edge Java SDK and ThingWorx Edge C SDK have been updated to support requesting WebSocket compression.
Support for ThingWorx Clustering for High Availability
Starting with v.9.0.0, you can configure Connection Server instances to run in a high-availability environment, using ThingWorx High Availability Clustering. When operating in a high availability environment, each Connection Server authenticates using an application key as it does in a standalone environment.
For more information about using Connection Servers in a ThingWorx cluster, refer to Using the Connection Server in a ThingWorx High Availability
(HA) Clustering Environment.
Support for Remote Access in ThingWorx High Availability Clustering Environment
The Connection Server v.9.0.0 and later supports remote access sessions in a ThingWorx High Availability Clustering environment. The Connection Server must be configured to operate in this high-availability environment. Then, Remote Access Clients can establish AlwaysOn tunnels through the Connection Server. In this configuration, the Connection Server is used as a proxy for remote access sessions.
This feature supports the WebSocket endpoint, WS/TWS, AlwaysOn connections for Remote Access Clients (RAC). The RAC binds as a gateway Thing over a WS/TWS endpoint. Since the AlwaysOn protocol is bi-directional, egress to the RAC is supported. For information about this endpoint, refer to the section, WebSocket Endpoint for Remote Access in the topic, What's New in ThingWorx Remote Access Extension and ThingWorx Remote Access Client? in the ThingWorx Help Center.