Configuring the eMessage Connector to Run in a ThingWorx High Availability Cluster
This topic assumes that you have set up your ThingWorx High Availability (HA) Clustering environment and want to configure the eMessage Connector to connect to the HA cluster of ThingWorx Platform instances..
Before You Begin
The configuration instructions for the eMessage Connector in an HA cluster assume the following tasks are complete:
• Your ThingWorx HA 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 Configuration.
• 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 eMessage Connector in your ThingWorx High Availability Clustering environment:
• Application key for this eMessage Connector.
• In the ThingWorx High Availability Clustering environment the ThingWorx Platform instances register their IP addresses in ZooKeeper service discovery. The eMessage Connector 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..
• 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 an eMessage Connector for HA Operations - Required Settings
To configure an eMessage Connector to operate in a ThingWorx HA Cluster, follow these steps:
1. Navigate to the conf subdirectory of the eMessage Connector installation, and make a copy of the emessage-ha-sample.conf file and rename it to emessage.conf .
2. Using a text editor, open your copy of the configuration file, emessage.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.ssl.key-store {
file = null
password = null
}
emessage.file-transfer {
download {
url = null
}
upload {
url = null
}
}
}
3. Using the information you collected, you must set these properties:
◦ transport.websockets.app-key — Replace null with the application key for the eMessage Connector 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"
4. By default SSL/TLS is enabled for incoming HTTPS connections from Edge devices. The Connector 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, as follows:
cx-server {
protocol.http-server.ssl.key-store {
file = null
password = null
}
}
 |
Pay particular attention to the exact spelling of the names of the keys in the configuration file. Making a simple mistake such as leaving the dash off of the key-store tag, for example, can result in obscure errors, depending on how the Connector handles HTTP/S calls from Axeda eMessage agents.
|
a. protocol.ssl.key-store.file — Replace null with the path to the keystore.pfx file for the eMessage Connector to use when connecting to a ThingWorx Platform instance in the cluster. For example:
key-store.file = "/opt/secure/keystore.pfx"
b. protocol.ssl.key-store.password — Replace null with the password for this keystore file.
key-store.password = "ieocir147f23np"
|
|
If you are currently using a JKS keystore, you will need to convert it to a PKCS #12 keystore. Refer to Converting JKS Keystores to PKCS Keystores for instructions. If you must use a Java keystore, refer to in the "Optional Configuration" section below.
|
5. The Connector also needs a trust store that contains the certificates necessary to validate the certificate presented by the ThingWorx Platform. By default, the Connector uses the default trust store provided by the JRE ("cacerts"). If you need to use a different trust store, refer to in the "Optional Configuration" section below.
For information on configuring SSL/TLS for the connection between an Axeda Global Access Server (GAS), v.6.9.2/v.6.9.3 and an eMessage Connector, refer to Configuring the Connector for Remote Access. For information on configuring the GAS itself to use SSL/TLS refer to the ThingWorx Global Access Server Reference, v.7.1.0, which is available on the Reference Documents page of the PTC Support site.
6. If you plan to transfer files between Axeda Agent devices and the ThingWorx Platform, you must configure the locations of the download and upload endpoints on the eMessage Connector where the transferred files can be accessed by the Axeda Agent devices and the ThingWorx Platform. The Agent will use these URLs when transferring files. The url properties are in the emessage.file-transfer.download and emessage.file-transfer.upload groups:
emessage {
file-transfer {
download {
url = "https://eMessageConnector:8443/download"
}
upload {
url = "https://eMessageConnector:8443/upload"
}
. . .
}
}
Additional properties are available to configure file downloads, including settings for retries and chunk size. They all have default values and are optional. For more information about them, refer to Configuring Additional Properties for File Transfers.
7. Leave the default settings for the following required properties. They must be set as is to enable successful connection to a ThingWorx HA Cluster:
cx-server {
. . .
platform.transport = "websockets_active_active"
transport.websockets.service-discovery.enabled = true
. . .
}
8. Save the file. At this point you have completed the minimum required configuration for the eMessage Connector 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. Follow the instructions in Setting Up an Encrypted Configuration File for an eMessage
Connector to encrypt the configuration file.
 |
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 and .
|
2. After encrypting the configuration file, follow the instructions in Setting Environment Variables for an eMessage Connector and Setting Environment Variables for an eMessage Connector.
3. After setting the environment variable, refer to Setting Up Permissions and Visibility for the eMessage Connector to set the required permissions and visibility before starting the Connector.
4. If you need to set options for the Token Authenticator used to authenticate Axeda Agents, refer to Configuring the TokenPropertyAuthenticator (eMessage Connector)
5. You are ready to start the Connector..
More Information About ThingWorx High Availability Clustering Configuration
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: