High Availability Configuration
This topic assumes that you have set up your ThingWorx High Availability Clustering environment and want to configure the Connection Server to connect to the HA cluster of ThingWorx Platform instances. Refer to the following sections:
3. Next Steps
Before You Begin
 |
The application key that this Connection Server will use to authenticate with the ThingWorx Platform. PTC recommends using an Application Key with minimal permissions for security reasons. Additionally, for the purposes of this Application Key, no visibility or permissions are required.
|
The configuration instructions for the Connection Server in an HA cluster assume the following tasks are complete:
• Your ThingWorx High Availability Cluster is installed, configured, and running. For links to ThingWorx HA help topics, refer to the section below, More Information about ThingWorx
High Availability Clustering.
• For security best practices, you want to enable Simple Authentication Security Layer (SASL) for communications with the service discovery provider, ZooKeeper.
Before you begin, collect the following information for configuring the Connection Server in your ThingWorx High Availability Clustering environment:
• Application key for this Connection Server.
• In the ThingWorx High Availability Clustering environment the ThingWorx Platform instances register their IP addresses in ZooKeeper service discovery. The AlwaysOn Connection Server uses the IP address registered in ZooKeeper to connect to a ThingWorx Platform instance. Since host name validation is enabled by default, make sure that the TLS certificate of each ThingWorx Platform instance contains an IPAddress entry in the Subject Alternative Name extension that matches its IP address. Otherwise, the TLS connection will fail host name validation. Although not recommended, you can disable host name validation. Refer to Optional Configuration Properties Shown in the Minimal and
HA Sample Configuration Files.
• To set the connectionString for service discovery, a list of the host:port pairs for the ZooKeeper instances in the cluster. You need to enter these pairs as a comma-separated list while configuring service discovery for the Connection Server.
• Whether to use SASL for communications with the ZooKeeper instances, and if so, the paths to the configuration files for KRB5 (Kerberos) and JAAS (Java Authentication and Authorization Service) in the cluster.
 |
For information about configuring KRB5 and JAAS for SASL communications with ZooKeeper instances, refer to the topic, Installing and Configuring ZooKeeper for ThingWorx HA, in the ThingWorx Help Center. For specific information about ZooKeeper and SASL, refer to the page, ZooKeeper and SASL. It provides links to information about configuring client-server mutual authentication and server-server mutual authentication with SASL and ZooKeeper. It also has an appendix that defines Kerberos, SASL, and JAAS, with links to download required software.
|
Configuring a Connection Server for HA Operations - Required Settings
To configure a Connection Server to operate in a ThingWorx High Availability Clustering environment, follow these steps:
1. Navigate to the conf subdirectory of the Connection Server installation, and make a copy of the cxserver-ha-sample.conf file and rename it to cxserver.conf.
2. Using a text editor, open your copy of the HA sample configuration file, cxserver.conf. The file contains the required and optional settings, all with comments to explain them. The following lines show the required settings that you need to change, without the comments:
cx-server {
transport.websockets {
app-key = null
}
discovery {
connectionString = null
}
protocol.http-server.ssl.key-store {
file = null
password = null
}
}
3. Using the information you collected, you must set the following properties:
◦ transport.websockets.app-key — Replace null with the application key for the Connection Server to use to authenticate with a ThingWorx Platform instance in the cluster. For example:
app-key = "77777777-2222-2222-aaaa-cccccccccccc"
◦ discovery.connectionString — Replace null with the comma-separated list of host:port pairs for the ZooKeeper instances in the cluster. For example:
connectionString = "zookeeper-1:2181,zookeeper-2:2181,zookeeper-3:2181"
◦ By default SSL/TLS is enabled for incoming WebSocket connections from edge devices. The Connection Server needs a keystore containing the certificate chain and private key used for establishing the SSL/TLS connections with edge devices.
The keystore must be in a PKCS#12 format and should be created with a password. Specify the file and password properties in the cx-server.protocol.http-server.ssl.key-store group, with the PKCS #12 keystore's path and password:
▪ protocol.http-server.ssl.key-store.file — Replace null with the path to the key-store file. For example: /opt/secure/key-store.pfx.
▪ protocol.http-server.ssl.key-store.password — Replace null with the password for the keystore . You can set this property to null if there is no password. However, it is highly recommended to use a password. For example: s82@fl9#trr2.
cx-server {
protocol.http-server.ssl.key-store {
file = "/opt/secure/keystore.pfx"
password = "ai23#!f0j29QW"
}
}
4. Leave the default settings for the following required properties. They must be set as is to enable successful connection to a ThingWorx High Availability Clustering environment:
cx-server {
. . .
platform.transport = "websockets_active_active"
transport.websockets.service-discovery.enabled = true
. . .
}
|
|
In a ThingWorx HA Cluster, the ThingWorx Platform instances register their IP addreses 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. If this scenario describes your use case, disable host name verification by changing the value of the transport.websockets.service-discovery.enabled property to false:
|
5. The Connection Server also needs a trust store that contains the certificates necessary to validate the certificate presented by the ThingWorx Platform. By default, the Connection Server uses the default trust store provided by the JRE ("cacerts"). If the ThingWorx Platform is using a self-signed certificate (not recommended) or a certificate signed by an untrusted third party, refer to the table entry for the property cx-server.protocol.http.client.ssl.trust-store.file, in Optional Configuration Properties Shown in the Minimal and
HA Sample Configuration Files to configure a different trust store.
6. Save the file. At this point you have completed the minimum required configuration for the Connection Server to run in a ThingWorx HA Cluster.
Next Steps
At this point, you may want to configure optional properties and/or metrics reporting. If so, leave your configuration file open and follow the steps in the appropriate topic:
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.
More Information about ThingWorx High Availability Clustering
For general information on ThingWorx High Availability Clustering installations, refer to the Overview of ThingWorx High Availability.
For specifics on setting up the HA cluster, refer to the following topics: