Configuring the Connector for Remote Access
When an Axeda Global Access Server, v.6.9.2/v.6.9.3, registers with the eMessage Connector for the first time, the Connector performs validation checks and creates a GAS Thing, based on the GASModel Thing Template, on the ThingWorx Platform. It sets Thing properties from values of attributes sent in the GAS registration message. If it is not already set, the firstRegistrationDate property is set to the current date. Then the latestRegistrationDate property is set on the Thing.
If a Thing already exists for the GAS, the latestRegistrationDate is updated to the current date.
 |
As of v.2.0.0 of the eMessage Connector, support for ThingWorx High Availability (HA) Clustering is provided for remote sessions. As of v.3.0.0 of the Remote Access Extension, support is provided for ThingWorx GAS, v.7.x in an HA environment. Depending on the synchronization of models across the ThingWorx Platform instances in a cluster, the call to register a GAS could fail. The Connector uses the Retry Service to keep trying to register the GAS. For more information about the service, refer to the section, Retry Service for GAS Registration below.
|
Remote Access Configuration for the eMessage Connector
You can edit the Remote Access properties in the emessage.conf file, in the cx-server.remote-access group. Most of the properties define the HTTP Client connection between the Connector and the GAS. One property sets a timeout for a session to start.
 |
It is strongly recommended that you configure SSL/TLS for communication between the eMessage Connector and the GAS. The options to set for SSL/TLS are described in the following table.
|
|
Property
|
Default Value
|
Description
|
|---|---|---|
|
session-startup-timeout
|
120 seconds (2 minutes)
|
Defines the timeout for the start of a remote session, in seconds. This timeout is the number of seconds before a session that has not started is closed. The timeout must be greater than the asset Ping rate.
|
|
gas.http-client.connect-timeout
|
600000
|
The number of milliseconds before the connection to the GAS times out. The Connector drops the connection.
|
|
gas.http-client.request-timeout
|
100000
|
The number of milliseconds before a request to the GAS times out.
|
|
gas.http-client.ssl.enabled
|
false
|
Whether SSL/TLS is enabled for the connection between the Connector and the GAS.
|
|
gas.http-client.ssl.verify-host
|
false
|
Whether to verify the hostname used to connect to the GAS against the hostname presented in the server certificate.
|
|
gas.http-client.ssl.trust-all-certificates
|
false
|
Whether all server certificates should be trusted.
|
|
gas.http-client.ssl.trust-store.file
|
The name of the trust store file, in .jks format. If trust-all-certificates is false, then a client trust store must be configured and should contain the certificates of the server that the cliewnt trusts.
|
|
|
gas.http-client.trust-store.password
|
The password for the trust store.
|
|
|
gas.http-client.ssl.key-store.file
|
The name of the key-store file (.jks format). If GAS requires client authentication, the client must present its own certificate to the server when connecting.
|
|
|
gas.http-client.key-store.password
|
The password for the key-store file.
|
|
|
gas.http-client.ssl.additional-cipher-suites
|
By default the TLS configuration will use the cipher suites of the JVM.
|
The list of additional cipher suites to enable for the TLS configuration. For example:
additional-cipher-suites = [ "ECDHE-RSA-AES128-GCM-SHA256", "ECDHE-ECDSA-AES128-GCM-SHA256" ] |
|
gas.http-client.ssl.certificate-revocation-list-files
|
The list of files that specify the X.509 certificate revocation list. Trust can be configured to use a certificate revocation list (CRL) for revoked certificates that should no longer be trusted. For example:
certificate-revocation-list-files = [ "/some/path/to/crl.pem" ] |
Retry Service for GAS Registration
For v.2.0.0 of the eMessage Connector, support for the ThingWorx High Availability (HA) Clustering has been added. Depending on the synchronization of models across the ThingWorx Platforms in a cluster, the call to register a GAS Thing could fail. To keep trying to register a GAS Thing, the Connector uses the Retry Service. If any service call fails, the service continues retrying GAS Thing registration for a configured number of times, waiting a configured number of milliseconds between retries. The following table describes the properties to set:
|
Parameter
|
Description
|
Default Value
|
|---|---|---|
|
thread-pool-size
|
The number of threads in the thread pool to use for executing retries.
|
10 times
|
|
backoff-delay
|
The number of milliseconds specified that the service should wait after the first retry If a third retry is needed, the service waits for 2 times the backoff-delay. With each subsequent pause before retry lasts 2 times the previous delay. See the example below.
|
100 milliseconds
|
|
backoff-max-delay
|
The maximum number of milliseconds that the service waits between retries.
|
2000 milliseconds
|
|
max-retries
|
The maximum number of retries to execute before failing the service call
|
6 retries
|
For example, suppose you specify 200 milliseconds for the backoff-delay, 2000 milliseconds for backoff-max-delay, and 6 as the value for max-retries. The successive retries follow:
1. The service waits for 200 milliseconds between the first retry and the second.
2. If a third retry is necessary, it waits for 2 times the backoff-delay, or 400 milliseconds.
3. Before a fourth retry, it waits 2 times 400, or 800 milliseconds.
4. Before a fifth retry, it waits 2 x 800, or 1600 milliseconds.
5. Before the sixth and final retry, the service waits only 2000 milliseconds because that is the value of the backoff-max-delay property.
6. If the last retry fails, the service call fails and GAS registration will fail.
Example 1. Sample Configuration of RetryService and Remote Access in emessage.conf
Here is an example of the emessage.conf configuration:
cx-server {
remote-access {
session-startup-timeout = 120
gas {
http-client {
connect-timeout = 60000
request-timeout = 10000
ssl {
enabled = true
verify-host = true
trust-all-certificates = false
trust-store {
file = "<path_to_truststore>"
password = "<truststore_password>"
}
key-store {
file = "<path_to_keystore>"
password = "<keystore_password>"
type = pkcx12"
}
additional-cipher-suites = [
]
certificate-revocation-list-files = [
]
}
}
}
// The retry-service is used to retry failed service calls during the Global Access Server Thing
// registration workflow.The service calls that could be retried include token authentication,
// bind/unbind, and writing of properties.
retry-service {
// thread pool size used for executing retries
thread-pool-size = 10
// exponential backoff delay in milliseconds
backoff-delay = 100
// exponential backoff max delay in milliseconds
backoff-max-delay = 2000
// max number of retries to execute before failing
max-retries = 6
}
}