Optional Configuration Properties
The second sections of the minimal and HA configuration files for the eMessage Connector 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 table, Table 11, 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 eMessage Connector 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 Connector 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 an eMessage Connector on startup, in the format, emessage-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 eMessage Connector, uncomment the following line and change the value to the desired Thing name:
cx-server {
. . .
#thing.name = "my-emessage-connector"
. . .
}
 |
If using a custom name for the eMessage Connector, make sure that the name is unique. The ThingWorx Platform will not create a Thing for the eMessage Connector or allow it to connect if the name is a duplicate.
|
4. If you set up SSL/TLS properties in the "Required Configuration", skip this step. Otherwise, if you must disable SSL/TLS for the port on which the eMessage Connector listens for incoming HTTP connections from the Agents, change the value of the protocol.ssl.enabled property to false.
5. The Java keystore format (JKS) 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). Make sure that you also set the key-store.password property for the JKS keystore.
 |
Setting these properties is shown in Step 5 of the "Required Configuration" section in the topic,Minimal Configuration.
|
b. Uncomment the following line to enable the JKS keystore format support:
#protocol.ssl.key-store.type = "jks"
6. The eMessage Connector also 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 Connector will use the "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 Connector to use a different trust store. The path to the trust store and the trust store's password must be set with Java system properties (environment variables), as follows:
a. Open a shell or Command Prompt.
b. Set the EMESSAGE_OPTS system property, using the path and password of the trust store, as shown here:
EMESSAGE_OPTS="-Djavax.net.ssl.trustStore=/opt/truststore.jks
-Djavax.net.ssl.trustStorePassword=changeit"
|
|
The environment variable, EMESSAGE_OPTS, must be set to point to the configuration files for the Connector and for logging (logback.xml). In addition, when using SSL/TLS, you must set the trust store path and password as shown above. For procedures, refer to Setting Environment Variables for an eMessage Connector.
|
7. Users can change the ping rate of an agent from ThingWorx by invoking the SetPingRate service. The default minimum, acceptable rate is 5000 ms (5 seconds). If you want to change this minimum, set the minimum-ping-rate property in the emessage group. The following example sets the minimum ping rate to 60 seconds (60000 ms):
emessage {
. . .
minimum-ping-rate = 60000
}
8. The properties of the platform-binding group control the maximum number of egress messages that the Connector can accept per Thing and the number of seconds that the Connector waits for them.
◦ max-messages-per-thing — This property controls the maximum number of egress messages per request to obtain for a Thing.
◦ message-fulfillment-timeout — This property controls the number of seconds that the Connector must wait for any expected messages from theThingWorx Platform to arrive upon receiving a poll from an agent.
The default values of platform-binding are:
platform-binding {
max-messages-per-thing = 10
message-fulfillment-timeout = 10000
}
9. This step is for use of the Connector in a ThingWorx HA Cluster:
a. 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 property to false, as shown here:
cx-server {
. . .
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.
|
b. The eMessage Connector needs to be configured with the service name used to look up the ThingWorx Platform instances in ZooKeeper and to determine whether to connect securely to the registered ThingWorx Platform instances. By default, the Connector is configured to connect securely to the platform instances.
▪ To connect securely with SSL/TLS to the ThingWorx Platform instances, leave the default values for the following properties as shown here:
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, set the properties as shown here:
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 for the eMessage Connector service-discovery.service-name value.
|
c. 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.
|
|
The eMessage Connector does not comply with FIPS standards on its own. However, it automatically activates FIPS 140-3 compliant algorithms to support communication with a FIPS compliant Axeda Agent. The users should note that no configuration is required for eMessage to utilize FIPS 140-3 compliant algorithms.
|
Optional Configuration Properties for the eMessage Connector
The remaining properties are optional. 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. Again, the properties are presented without the detailed comments. To set a property to a different value than the default value shown, uncomment the line and change the value of the property. The following table explains their purpose and options.
|
Property
|
Default Value
|
Description
|
||
|---|---|---|---|---|
|
cx-server.protocol.port
|
8443
|
The port on which the eMessage Connector listens for incoming HTTP 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 eMessage Connector'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
|
"emessage-cxserver-<uuid>"
|
The Thing name with which the eMessage Connector binds after connecting to the ThingWorx Platform. If no name is specified (the value is null), the Thing name will be emessage-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.ssl.enabled
|
true
|
SSL/TLS is enabled by default for the port on which the eMessage Connector listens for incoming HTTP connections. PTC strongly recommends always leaving SSL/TLS enabled.
|
||
|
cx-server.protocol.ssl.key-store.type
|
"jks"
|
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.transport.websockets.service-discovery.tls-enabled
|
true
|
SSL/TLS is enabled by default for the WebSocket connections between the eMessage Connector and a ThingWorx Platform in a ThingWorx HA 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.discovery.service-name
|
"thingworx-https"
|
The service name with which the eMessage Connector 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.discovery.sasl-enabled
|
true
|
Whether to use SASL for communications with the ZooKeeper instances,
|
||
|
cx-server.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.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.
|
Next Steps
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 Minimal Configuration and Setting the Environment Variable.
|
2. After encrypting the configuration file, follow the instructions in 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..