Step 6. Configure the Connector
 |
The Connector reads its configuration file with the expectation that the file uses the
Typesafe config format and the extension, .conf.
|
This topic provides instructions for creating a configuration file for the Azure IoT Hub Connector that has the minimum set of properties required to communicate securely with a ThingWorx Platform, an Azure IoT Hub, and your Azure IoT Edge devices.
1. Navigate to the <azure_connector_install>/conf directory
2. Copy the azure-iot-sample.conf configuration file, rename it to azure-iot.conf, and open the new file in a text editor.
The rest of this procedure takes you through the required properties, which are not in the order in which they appear in the configuration file. You must set these properties for the configuration file to be valid. An invalid configuration file will prevent the Connector from starting.
3. In the app-key property of the transport.websockets group, enter the application key that was created for this Azure IoT Hub Connector. The example below is intended only to show where the application key appears in the configuration file:
cx-server {
...
transport {
websockets {
app-key = "<some_application_key>"
4. For the platforms property, enter the URL for the ThingWorx Platform endpoint. Note that the default value assumes that you will use SSL/TLS for the connection between the Connector and the ThingWorx Platform instance (wss://<host>:<port>):.
cx-server {
...
transport {
websockets {
app-key = "<some_application_key>"
platforms = "<wss://<host>:<port>>"
}
In the example above, the connection between the Connector and the instance of the ThingWorx Platform is secured (wss instead of ws). For best security practices, always use TLS in production.
|
|
If you are running your ThingWorx Platform inside of Azure, the wss hostname should use the actual external hostname of your ThingWorx Platform, not its hostname in Azure. You cannot use the internal hostname because it will not match the HTTPS certificate. In the example above, the certificate has acme-twx-85-we.ptcmsdev.com as the hostname so acme-twx-85-we.ptcmsdev.com must be used here.
|
If, for non-production purposes, you want to use a non-secure connection between the Connector and your ThingWorx Platform instance (for example, both are running on your laptop for development purposes), you would use "ws://localhost:80".
 |
If SSL/TLS will be used between the Connector and the instance of ThingWorx Platform, the URL MUST usewss and the SSL/TLS port (e.g., 443). In addition, if your ThingWorx Platform requires SSL/TLS and is not using a certificate signed by a valid Certificate Authority, be sure to include the signer's certificate in the cacerts keystore that is used by your Java installation before starting up. Otherwise, the system will not start properly, failing with SSL/TLS error messages.
|
5. Make sure that the websockets and transport groups are closed.
6. Edit the following properties in the configuration file for your Azure IoT Connector, connector.conf:
a. hub-thing-name — Enter the thingName of the AzureIotHub Thing you created using ThingWorx Composer.
b. repository-thing-name — Enter the thingName of your AzureIotBlobStorageTemplate Thing.
7. By default SSL/TLS is enabled, and use of SSL/TLS is strongly recommended. If SSL/TLS is terminated at a load balancer, you need to disable SSL/TLS in the configuration file. If SSL/TLS is not terminated at a load balancer, you need to configure SSL/TLS for the Azure IoT Connector. Locate the group, cx-server.protocol.ssl. In the ssl group, modify the settings for SSL/TLS as required for your environment.
a. Leave the default value of the enabled property. The default value is true, as shown here:
cx-server {
protocol {
ssl {
enabled = true
If this property is set to false, all the other SSL/TLS properties are ignored.
b. By default, the protocol specified is TLS. To specify a particular version of the TLS protocol to use, add the protocol property and set it to the desired version: TLSv1, TLSv1.1, or TLSv1.2. For example:
cx-server {
protocol {
ssl {
enabled = true
protocol = "TLSv1.2"
When you specify a TLS version, the Connector uses the default trust store provided by the JVM.
c. The keystore file, which you specify next, is the key store for the shared encryption key between the Connector and the ThingWorx Platform. This is typically a separate key from the ThingWorx Platform default encryption key and is generated using the Security Tool. This shared encryption key is used for encrypting credentials and configuration information for the platform to send to the Connector in order to successfully connect to the Azure IoT Hub. Enter the full path to the key store file and the password for that key store.The example below shows the default values:
cx-server {
protocol {
ssl {
enabled = true
protocol = "TLSv1.2"
key-store {
file = "./keystore"
password = "changeit"
}
The keystore must be in the valid Java Key Store format. In addition, if no password is required, set the password property to null.
8. If you want to be notified of 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 {
//Should the receiver for file-upload notifications be started?
enabled = true
// Specify the name of your AzureStorageContainerFileRepository-Thing
// that is associated to the storage container linked with this IoT Hub
// in Azure Portal: Messaging > Storage Container > Hub > File upload.
// 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"
}
}
}
 |
If you are upgrading to v.3.0.0 of the Connector, be aware that the blob storage section of the configuration file no longer applies for version 3.0.0. Everything is configured on the AzureIotHub Thing.
|
9. Save the configuration file. The final file should look similar to this example. Your entries will differ:by the names you have used for the repository-thing-name, ssl settings, hub-thing-name, app-key, and platforms URL. For best security practices, encrypt your Connector's configuration file. Otherwise, your application key is vulnerable.
cx-server {
protocol {
file-upload-events {
// Should the receiver for file-upload notifications be started?
enabled = true
// Name of the Thing (using template AzureStorageContainerFileRepository) which is associated to the storage container
// linked with this IoT Hub (within Azure Portal: Hub > File upload (under Messaging) > Storage container).
//
// 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.
repository-thing-name = "IoTHubStorageThingMe3d01-xyzabcd"
}
health-check {
port = 9009
}
ssl {
enabled = true
protocol = "TLSv1.2"
key-store {
file = "/appl/thingworxData/keystore"
password = "<your-key-store-password>"
}
additional-cipher-suites = [
"ECDHE-RSA-AES128-GCM-SHA256",
"ECDHE-ECDSA=AES128-GCM-SHA256"
]
trust-store {
file = ${java.home}/lib/security/cacerts
// Change this default password!
password = "changeit"
}
}
// This is the name of the Thing that represents your Azure IoT Hub in Thingworx
hub-thing-name = "<the-thing-name-of-your-azure-iot-hub>"
}
transport.websockets {
// ThingWorx Platform application key
app-key = "<your-application-key>"
// One or more platforms can be specified here, comma separated
platforms = "wss://<your-thingworx-server>.<your-domain-name>.com:8443/Thingworx/WS"
}
}
10. At this point, you have the following choices:
◦ To configure metrics reporting now, refer to
Configuring Metrics Reporting.
◦ If configuration is complete, your next step is
Step 7. Set Up Encryption for Azure IoT Hub Credentials.
Optional Configuration
1. This step is OPTIONAL. A name is automatically assigned to the Azure IoT Hub Connector on startup, in the format, <protocol>-cxserver-<uuid>, where:
◦ <protocol> is generally the communications protocol that your devices use. For the Azure IoT Hub Connector, <protocol> represents the Azure IoT Device Cloud. For the Azure IoT Hub Connector, the automatically assigned name would be azure-iot-cxserver-<uuid>.
◦ <uuid> is a unique identification number for the Azure IoT Hub Connector.
The name is used in the monitoring mashup for connection servers in ThingWorx. If your environment requires that you devise a specific naming scheme, add the thing and name lines under the cx-server group, as shown below. Then, change the value of the name property from null to the desired name:
cx-server {
thing {
name = null
}
When choosing a naming scheme, keep in mind that the ThingWorx Platform will not create a Thing for the Azure IoT Hub Connector (allowing it to connect), if it detects that the name is a duplicate.
2. If port 9009 is free for the Health Check Monitor of the Connector to listen on, the default configuration will suffice, so continue to the next step. Otherwise, locate the following lines in your configuration file (in the cxserver section, at the same level as thing) and change the number of the port for the health check monitor to an available port.
cx-server {
health-check {
port = 9009
}
3. You can also configure SSL/TLS for this port
health-check {
port = 9009
}