Optional Configuration Properties Shown in the Minimal and HA Sample Configuration Files
The second sections of the minimal and HA configuration files for the Azure IoT Hub 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
Optional Properties Reference section, 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.
 |
Steps 1 through 3 in the following procedure apply to both single-server and HA clustering environments. Steps 4 through 6 apply to HA clustering only.
|
1. To receive notifications about file uploads from Azure IoT Edge devices by the FileTransfer event, add the lines file-upload-events group and its properties to the cx-server.protocol section of this file, as follows:
cx-server {
protocol {
file-upload-events {
# Set to "true" to receive file upload events. You must also set the
# repository-thing-name property.
enabled = false
# Specify the name of your AzureStorageContainerFileRepository Thing
# that is associated to the storage container linked with this IoT Hub
# in Azure. When a file is uploaded to an Azure storage container, the
# Connector will fire an event on the platform to the Thing with this
# name. This Thing does not need to exist prior to starting the
# Connector, but any file-upload events received before this Thing
# exists will fail and not be retried. For example:
# repository-thing-name = "IotHubStorageThing"
repository-thing-name = null
}
}
}
|
|
If you are upgrading to v.3.0.0 or later of the Connector, be aware that the blob storage section of the configuration file no longer applies for these later versions. Everything is configured on the AzureIotHub Thing.
|
2. For the Health Check Monitor, the Azure IoT Hub 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 a Azure IoT Hub Connector on startup, in the format, alwayson-cxserver-<uuid>, where <uuid> is a unique identification number. The name is used in the Monitoring mashup for Azure IoT Hub Connectors in ThingWorx Composer. To use a specific Thing name for the Azure IoT Hub Connector, uncomment the following line and change the value to the desired Thing name:
cx-server {
. . .
#thing.name = "azure-iot-hub-connector-1"
. . .
}
 |
If using a custom name for the Azure IoT Hub Connector, make sure that the name is unique. The ThingWorx Platform will not create a Thing for the Azure IoT Hub Connector or allow it to connect if the name is a duplicate.
|
4. 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:
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 Azure IoT Hub 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 Azure IoT Hub 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
}
5. Save and close the file.
Optional Properties Reference
For the Connector in a ThingWorx HA cluster, the default values shown below are 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 shown, uncomment the line (as needed) and change the value of the property. The table below explains their purpose and options.
|
Property
|
Default Value
|
Description
|
||
|---|---|---|---|---|
|
cx-server.protocol.port
|
8443
|
The port on which the Azure IoT Hub Connector 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 Azure IoT Hub 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
|
"alwayson-cxserver-1"
|
The Thing name with which the Azure IoT Hub Connector 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.transport.websockets.connections.verifyHostName
|
false
|
This property controls whether TLS host name validation is performed when making TLS connections to a ThingWorx Platform. TLS host name validation is enabled by default.
In the ThingWorx High Availability Clustering environment each ThingWorx Platform instance registers its IP address in ZooKeeper service discovery. The Azure IoT Hub Connector connects to a platform instance using the IP address registered in ZooKeeper. The TLS connection will fail host name validation unless the TLS certificate 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 this property. The default value will disable host name validation. Refer to the property, cx-server.transport.websockets.service-discovery.tls-enabled.
|
||
|
cx-server.transport.websockets.service-discovery.tls-enabled
|
true
|
SSL/TLS is enabled by default for the WebSocket connections between the Azure IoT Hub Connector 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 Azure IoT Hub 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.transport.websockets.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
At this point, you may want to configure metrics reporting. If so, leave your configuration file open and follow the steps in the topic,
Configuring Metrics Reporting.
When you have completed the configuration, save the configuration file and follow the remaining steps in this section to get the Connector up and running.
 |
If you are setting up an internal testing environment, it is strongly recommended but not required that you encrypt the configuration file. Make sure that you encrypt the Connector configuration file when setting up a production environment.
|