Optional Configuration Properties Shown in the Minimal and HA Sample Configuration Files
The second sections of the minimal and HA configuration files for the Connection Server provide properties whose default values suffice in most environment. The environment for each customer or business application is different, so to meet the needs of a wide variety of applications, these optional configuration properties provide the flexibility needed to meet those needs. This topic provides a procedure for setting optional properties that applies to both ThingWorx single-server and ThingWorx High Availability Clustering environments. If you just need a reference about the property settings, refer to the Optional Properties
Reference, which follows the procedure.
Procedure for Setting Optional Properties
The remaining properties in the configuration file are optional. They allow you to customize some of the more common configuration settings.
1. The Connection Server accepts WebSocket connections on port 8443 by default. To use a different port, set the cx-server.protocol.port property to the desired port. Here is the default setting:
cx-server {
protocol.port = 8443
. . .
}
2. For the Health Check Monitor, the Connection Server listens on port 9009 by default. To use a different port, uncomment the following line and change the port number. Here is the default:
cx-server{
. . .
#health-check.port = 9009
. . .
}
3. A Thing name is automatically assigned to a Connection Server on startup, in the format, alwayson-cxserver-<uuid>, where <uuid> is a unique identification number. The name is used in the Monitoring mashup for Connection Servers in ThingWorx Composer. To use a specific Thing name for the Connection Server, uncomment the following line and change the value to the desired Thing name:
cx-server {
. . .
#thing.name = "alwayson-cxserver-1"
. . .
}
 |
If using a custom name for the Connection Server, make sure that the name is unique. The ThingWorx Platform will not create a Thing for the Connection Server or allow it to connect if the name is a duplicate.
|
4. If you set up SSL/TLS using a PKCS #12 keystore when setting required properties, skip this step. Otherwise, if you must disable SSL/TLS for the port on which the Connection Server listens for incoming WebSocket connections, change the value of the protocol.http-server.ssl.enabled property to false.
5. The Connection Server needs a trust store containing the set of trusted certificates used for establishing the SSL/TLS connections with the ThingWorx Platform. The trust store must be in a Java Keystore (JKS) format and should be created with a password. By default the Connection Server will use the {jre}/lib/security/cacerts trust store bundled with the JRE.
If you are using certificates that are not trusted by the default "cacerts" trust store, you can configure the Connection Server to use a different trust store. The path to the trust store and the trust store's password must be specified in the configuration file and also must be set in the environment variable, CONNECTION_SERVER_OPTS, as follows:
a. Uncomment the file and password properties in the cx-server.protocol.http-client.ssl group, and specify path and password:
cx-server {
. . .
protocol.http-client.ssl {
trust-store {
#file = "/opt/truststore.jks"
#password = "changeit"
}
}
. . .
}
b. From a shell or Command Prompt, you need to point the CONNECTION_SERVER_OPTS environment variable to the trust store. As shown in the example below, set the path in javax.net.ssl.trustStore and the password in javax.net.ssl.trustStorePassword:
CONNECTION_SERVER_OPTS="-Djavax.net.ssl.trustStore=/opt/truststore.jks
-Djavax.net.ssl.trustStorePassword=changeit"
|
|
The environment variable, CONNECTION_SERVER_OPTS, must also be set to point to the configuration files for the Connection Server and for logging (logback.xml). Refer to Setting the Environment Variables for the Connection Server for details.
|
6. If you are using a PKCS #12 keystore, skip this step.
 |
The Java keystore (JKS) format is considered insecure compared to a PKCS #12 keystore. It is strongly recommended that you convert the JKS keystore into a PKCS #12 keystore.
|
If you must use a JKS keystore, follow these steps:
a. Set the key-store.file property shown in the REQUIRED section of the configuration file to the path of the JKS keystore (.jks).
b. Uncomment the following line to enable the JKS keystore format support:
#protocol.http-server.ssl.key-store.type = "jks"
7. By default, the Connection Server waits for 5 seconds for an authentication request. If the request is not received before the timeout period expires, the Connection Server closes the websocket connection. If you want to change the default balue, copy the auth-request-timeout property from thecxserver-long-sample.conf file to the the cx-server.protocol.websockets group in the configuration file for your Connection Server. Set the desired number of seconds to wait for an authentication request from an edge device. Here is an example:
cx-server
protocol
websockets
auth-request-timeout = 10s
8. If you do not require HTTP Pass-Through and tunneling, skip to the next step. Otherwise, configure options for HTTP Pass-Through and Tunneling in the cxserver.protocol.http-client group of properties in the configuration file. To do so, refer to Configuring the HTTP Client for HTTP Pass-Through and Tunneling. Be sure to set up the trust store for the http-client, as explained in the required properties topics, Minimal Configuration for Connecting to a Single-Server ThingWorx
Platform Installation Using SSL/TLS and High Availability Configuration.
9. The following steps are for ThingWorx HA Cluster use of the Connection Server.
a. Two properties control the use of TLS host name verification when making connections in a ThingWorx High Availability (HA) Cluster. By default, host name verification is enabled for HA WebSocket connections..
In a ThingWorx HA Cluster, the ThingWorx Platform instances register their IP address in Zookeeper service discovery. The Connection Server will connect to a ThingWorx Platform instance in a cluster using its IP address registered in ZooKeeper service discovery. The TLS connection will fail host name verification unless the ThingWorx Platform instance's TLS certificate contains an IPAddress entry in the Subject Alternative Name extension matching its IP address. In this scenario, you can disable host name verification by setting the host name verification properties to false, as shown here:
protocol.http-client.ssl.verify-host = false
transport.websockets.connections.verifyHostName = false
b. TLS is enabled by default for the WebSocket connections between the Connection Server and ThingWorx Platform instances in a cluster. Although not recommended, you can disable TLS for service discovery by uncommenting the transport.websockets.service-discovery.tls-enabled property and setting it to false:
 |
The value of the tls-enabled property needs to align with the service-name used to look up ThingWorx Platform endpoints. If you enable TLS here, the service-name property must match the configured HTTPS service name of the ThingWorx Platform.
|
c. The ThingWorx Platform instances in an HA cluster register with Zookeeper service discovery depending on the configuration. If the platform instance is configured with an HTTPS endpoint, it registers with its configured HTTPS service, thingworx-https, by default. If TLS is enabled for service discovery, the platform instance must be configured with an HTTPS endpoint and the service name set in the Connector's configuration file must be thingworx-https. If TLS is disabled for service discovery and the platform instance is configured with an HTTP endpoint, it registers with its configured HTTP service name, thingworx-http, by default. Here are the properties with their default settings:
transport.websockets.service-discovery {
tls-enabled = true
service-name = "thingworx-https"
}
d. In a ThingWorx HA cluster, the Connector supports connecting to ZooKeeper using the Simple Authentication and Security Layer (SASL) mechanism. To use the SASL mechanism, uncomment the following lines and specify the paths to the required configuration files:
discovery {
# sasl-enabled = true
# sasl-krb5-conf-file = /path/to/kerberos-conf
# sasl-jaas-file = /path/to/jaas-conf
}
10. Save and close the file. Then continue to Next Steps
Optional Properties Reference
The default values shown below will be used if you do not explicitly change them. These properties allow you to customize some of the more advanced configuration settings. To set a property to a different value than the default value, uncomment the line and change the value of the property. The table below explains their purpose and options.
|
|
If you require HTTP Pass-Through and tunneling, configure options for HTTP Pass-Through and Tunneling in the cxserver.protocol.http-client group of properties in the configuration file. To do so, refer to . Then, return here to set up the trust store for the http-client, as shown for the cx-server.protocol.http-client.ssl.trust-store.file and cx-server.protocol.http-client.ssl.trust-store.password properties in the following table.
|
|
Property
|
Default Value
|
Description
|
||
|---|---|---|---|---|
|
cx-server.protocol.port
|
8443
|
The port on which the Connection Server listens for incoming WebSocket connections. The default value is the common secure port, 8443. If no port is specified at all, port 8080 is used.
|
||
|
cx-server.health-check.port
|
9009
|
The port on which the Connection Server's Health Check service listens for HTTP(S) connections. To use a different port, uncomment the line and enter a different port number.
|
||
|
cx-server.thing.name
|
"alwayson-cxserver-1"
|
The Thing name with which the Connection Server binds after connecting to the ThingWorx Platform. If no name is specified (the value is null), the Thing name will be alwayson-cxserver-<uuid>, where <uuid> is a randomly generated, unique identifier. To use a different Thing name, uncomment the line and enter the Thing name.
|
||
|
cx-server.protocol.http-client.ssl.verify-host
cx-server.transport.websockets.connections.verifyHostName
|
false
|
These two properties control whether TLS host name validation is performed when making TLS connections to a ThingWorx Platform. TLS host name validation is enabled by default. Disabling host-name verification could open up potential man-in-the-middle attacks and is strongly discouraged.
In the ThingWorx High Availability Clustering environment each ThingWorx Platform instance registers its IP address in ZooKeeper service discovery. The Connection Server connects to a platform instance using the IP address registered in ZooKeeper. The TLS connection will fail host name validation unless the TLS cerfiticate of the platform instance contains an IP Address entry in the Subject Alternative Name extension that matches its IP address.
In this scenario, you can disable host name validation by uncommenting these two properties. The default values will disable host name validation.
|
||
|
false
|
||||
|
cx-server.protocol.http-server.ssl.enabled
|
true
|
SSL/TLS is enabled by default for the port on which the Connection Server listens for incoming WebSocket connections. PTC strongly recommends always leaving SSL/TLS enabled.
|
||
|
cx-server.protocol.http-server.ssl.key-store.type
|
"pkcs12"
|
Java Key Store: The Java Key Store format is considered insecure compared to a PKCS #12 key store. It is recommended that you convert the JKS key store into a PKCS #12 key store, following this instructions in Converting JKS Keystores to PKCS Keystores. If you must use a JKS key store:
1. Set the key-store.file property above in the REQUIRED section to the path of the JKS key store (.jks).
2. Uncomment this property line to enable the JKS key store format support.
|
||
|
cx-server.protocol.http-client.ssl.enabled
|
true
|
Enables or disables SSL/TLS configuration for the HTTP pass-through and remote access/tunneling WebSocket connections to the ThingWorx Platform. By default it is enabled.
|
||
|
cx-server.protocol.http-client.ssl.trust-store.file
|
"/path/to/trust-store.jks"
|
Path to the trust store containing the certificates trusted by the Connection Server. The trust store must be in the Java key Store format (.jks). The trust store provided by Java ({jre}/lib/security/cacerts) is used by default.
To use a different trust store:
1. Uncomment the #file = … line and specify the path to the trust store.
2. Add the -Djavax.net.ssl.trustStore=/path/to/trust-store system property, using the actual path to the trust store, to the CONNECTION_SERVER_OPTS environment variable when launching the Connection Server.
|
||
|
cx-server.protocol.http-client.ssl.trust-store.password
|
"changeit"
|
The password for the trust store. If there is no password, you can set this property to null. The default trust store password is the password for the trust store provided Java. To use a different trust store password:
1. Uncomment the #password = … line, and specify the trust store password.
2. Add the -Djavax.net.ssl.trustStorePassword=changeit system property , with the actual password for the trust store, to the CONNECTION_SERVER_OPTS environment variable when launching the Connection Server.
|
||
|
cx-server.transport.websockets.service-discovery.tls-enabled
|
true
|
SSL/TLS is enabled by default for the WebSocket connections between the Connection Server and a ThingWorx Platform in a ThingWorx High Availability Cluster. The value of this property must align with the service-name used to look up ThingWorx Platform endpoints. If SSL/TLS is enabled here, the service-name property value must match the HTTPS service name configured for the ThingWorx Platform. If SSL/TLS is disabled here, the service-name property value must match the HTTP service name configured for the ThingWorx Platform.
|
||
|
cx-server.transport.websockets.service-discovery.service-name
|
"thingworx-https"
|
The service name with which the Connection Server should look up the ThingWorx Platform instances from service discovery. The platform instances will register with service discovery depending on its configuration. If it is configured with an HTTPS endpoint, the platform will register with its configured HTTPS service name, thingworx-https by default. If it is configured with an HTTP endpoint, the platform will register with its configured HTTP service name, thingworx-http by default.
|
||
|
cx-server.transport.websockets.service-discovery.sasl-enabled
|
true
|
Whether to use SASL for communications with the ZooKeeper instances,
|
||
|
cx-server.transport.websockets.service-discovery.sasl-krb5-conf-file
|
/path/to/kerberos-conf
|
If SASL is enabled, specify the path to the configuration file for KRB5 (Kerberos) in the cluster.
|
||
|
cx-server.transport.websockets.service-discovery.sasl-jaas-file
|
/path/to/jaas-conf
|
If SASL is enabled, specify the path to the configuration file for JAAS (Java Authentication and Authorization Service) in the cluster.
|
||
|
cx-server.websockets.max-msg-size-bytes
|
1048576
|
The maximum size for a message (in bytes). The default value is 1 MB.
|
||
|
cx-server.websockets.client-binding-limit
|
c1000
|
The maximum number of Things that can be bound within a single WebSocket connection.
|
||
|
cx-server-connected-client-limit
|
1000000
|
The maximum number of simultaneous WebSocket connections.
|
||
|
cx-server.websockets.idle-timeout-ms
|
60000
|
The number of milliseconds that a WaybSocket can be idle before it is closed. When the WebSocket has no activity for longer than the specified value, the Connection Server closes it.
|
||
|
cx-server.websockets.max-frame-size-bytes
|
Next Steps
When you have completed the configuration, follow these steps:
1. As a best practice, encrypt the configuration for optimal security. Do this before setting the environment variable. For instructions, refer to Setting Up an Encrypted Configuration File.
2. After encrypting the configuration file, follow the instructions in Setting
the Environment Variable When Using an Encrypted Configuration. To complete the SSL/TLS configuration, make sure you also follow the steps for setting the environment variable Setting
an Environment Variable When Using SSL/TLS.
|
|
If you are setting up an internal testing environment, this step is strongly recommended but not required. Do not skip this step when setting up a production environment. If you choose not to encrypt the configuration file, set the environment variable to point to your configuration files and to the SSL/TLS settings, as explained in Setting the Environment Variable When Using an Unencrypted Configuration
File and Setting
an Environment Variable When Using SSL/TLS
|
3. After setting the environment variable, you are ready to start the Connection Server.