Step 8. Set the Environment Variables for the Azure IoT Hub Connector
Sample Environment Settings
Here are sample environment settings for running the Azure IoT Hub Connector, shown with Linux paths.
IOTHUB_HOME=/appl/twxAzureIoTHubConnector
JAVA_HOME=/usr/java/latest
JAVA_JRE=/usr/java/latest/jre
JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom
AZURE_IOT_OPTS=-Dconfig.file=/appl/twxAzureIoTHubConnector/connector/conf/azure-iot.conf
-Dlogback.configurationFile=/appl/twxAzureIoTHubConnector/connector/conf/logback.xml
-Dsecret.management.config.file=/appl/iothub/security-common/security-common-cli-1.0.2.40/bin/platform.conf
-Dconfig.plaintext=true
If you want to run the Connector as a service on Linux, store these variables in a file, EnvironmentFile. For more information on running as a service on Linux, refer to
Running
the Connector as a Service on Linux.
For detailed instructions on setting the AZURE_IOT_OPTS environment variable, refer to
the section below.
Setting the AZURE_IOT_OPTS Environment Variable
Before starting the Azure IoT Hub Connector, you must set the AZURE_IOT_OPTS environment variable. The Connector checks the environment variable to locate the configuration files for the Connector and to check for SSL/TLS on startup. The configuration files include the encryption.conf file that the Connector will use to decrypt the credentials for the Azure IoT Hub it connects to and the azure-iot.conf (unencrypted) or azure-iot.conf.encrypted file that the Connector reads on startup. Depending on whether you
encrypted the configuration file, start with either of the following sections:
If you are using SSL/TLS for communications between the Connector and the ThingWorx Platform, you also need to complete that configuration by setting the environment variable as explained in
Setting an Environment
Variable When Using SSL/TLS.
 |
When you set the environment variable using the configuration files options and then set it again using the SSL/TLS options, the values set for the configuration files are retained. You are just adding the SSL/TLS options. If desired, you could combine the configuration file options with the SSL/TLS options in one long command.
|
Setting an Environment Variable When Using an Encrypted Configuration File
 |
This section assumes that you have followed the steps in
Step 7. Encrypt the Configuration File for creating the configuration file for the encryption library and then encrypting the Connector's configuration file.
|
To set up the Azure IoT Hub Connector so that it will decrypt the encrypted configuration file, you need to know the paths to and names of the following files created when setting up an encrypted configuration file:
• The encrypted configuration file for the Connector. For example, azure-iot.conf.encrypted.
• The encryption.conf configuration file that is used to encrypt/decrypt the Azure IoT Hub credentials as well as to encrypt the Connector's configuration file.
To set up the Azure IoT Hub Connector so that it will decrypt the encrypted configuration file, add a secret.management.config.file property to the AZURE_IOT_OPTS environment variable, as follows:
1. Set the environment variable for the configuration file:
On Linux:
export AZURE_IOT_OPTS="-Dsecret.management.config.file=
<your-encryption.conf-path>/encryption.conf
-Dconfig.file=<your-connector-config-path>/azure-iot.conf.encrypted
-Dlogback.configurationFile=<your-connector-config-path>/logback.xml"
On Windows:
set AZURE_IOT_OPTS=-Dsecret.management.config.file=
<your-encryption.conf-path>\encryption.conf
-Dconfig.file=<your-connector-config-path>\azure-iot.conf.encrypted
-Dlogback.configurationFile=<your-connector-config-path>\logback.xml
|
|
In the command-line examples above, line feeds have been added for publishing purposes. If you want to copy/paste the commands, first paste them into a text editor and remove the line feeds. Then copy into your shell or Command Prompt window. There should be a space between the end of a -D entry and the beginning of the next one.
|
 |
Make sure that you do NOT use double quotation marks when setting the environment variable on Windows. If you use them, the Connector will fail to start.
|
2. After setting the environment variables, leave the shell or Command Prompt window open so that you can set the environment variable for SSL/TLS, as explained in the section below,
Setting an Environment
Variable When Using SSL/TLS. If you have already set the variable for SSL/TLS, continue to
Step 9. Run the Service to Grant Permissions and Visibility
to the Connector.
Setting the Environment Variable When Using an Unencrypted Configuration File
You need to set the following parameters for the AZURE_IOT_OPTS environment variable when using an unencrypted configuration file:
|
Parameter
|
Description
|
|---|---|
|
-Dsecretmanagement.config.file
|
To tell the Azure IoT Hub Connector what configuration file to use when decrypting the Azure IoT Hub credentials sent by the ThingWorx Platform, set this parameter to <your-connector-config-path>/encryption.conf. This parameter specifies the full path to the configuration file for the encryption library.
|
|
-Dconfig.plaintext
|
Set this parameter to true to tell the Connector that its configuration file is not encrypted.
|
|
-Dconfig.file
|
Specify the location and name of the configuration file for the Connector: <your-connector-config-path/azure-iot.conf.
|
|
-Dlogback.configurationFile
|
Specify the full path to the configuration file for Logback. To customize the logback.xml file, refer to
Logging. For more information about configuring Logback, visit
http://logback.qos.ch/manual/index.html.
|
|
|
Make sure that you do NOT use double quotation marks when setting the environment variables on Windows. If you use them, the Connector will fail to start.
|
The following examples set the environment variable for an azure-iot.conf configuration file that is not encrypted and for the logback.xml logging configuration file.
On Linux, open a shell and enter the following to set the environment variable for a configuration file that is not encrypted:
export AZURE_IOT_OPTS="-Dsecret.management.config.file=
<your-connector-config-path>/encryption.conf
-Dconfig.plaintext=true
-Dconfig.file=<your-connector-config-path>/azure-iot.conf
-Dlogback.configurationFile=<your-connector-config-path>/logback.xml"
On Windows, run a Command Prompt as Administrator, and enter the following to set the environment variable for a configuration file that is not encrypted:
set AZURE_IOT_OPTS=-Dsecret.management.config.file=<your-connector-config-path\encryption.conf
-Dconfig.plaintext=true
-Dconfig.file=<your-connector-config-path>\azure-iot.conf
-Dlogback.configurationFile=<your-connector-config-path>\logback.xml
|
|
In the command-line examples above, line feeds have been added for publishing purposes. If you want to copy/paste the commands, first paste them into a text editor and remove the line feeds. Then copy into your shell or Command Prompt window. There should be a space between the end of a -D entry and the beginning of the next one.
|
After setting the AZURE_IOT_OPTSenvironment variable, leave the shell or Command Prompt window open so that you can set the environment variable for SSL/TLS or continue to
Step 9. Run the Service to Grant Permissions and Visibility
to the Connector.
Setting an Environment Variable When Using SSL/TLS
If you configured the Azure IoT Hub Connector to use SSL/TLS for communications with ThingWorx Platform, follow these steps to set the environment variable and complete the SSL/TLS configuration:
1. Set the environment variable from the command line. Choose the command for the operating system where your Connector is running. If you want to add the version of TLS to use between the Connector and the ThingWorx Platform, continue to the next step.
◦ On Linux:
export AZURE_IOT_OPTS="-Djavax.net.ssl.trustStore=/etc/opt/java/
security/cacerts-customized -Djavax.net.ssl.trustStorePassword=new-password"
◦ On Windows:
set AZURE_IOT_OPTS=-Djavax.net.ssl.trustStore=
<your-connector-path-to-certs>\cacerts-customized
-Djavax.net.ssl.trustStorePassword=new-password
|
|
In the command-line examples above, line feeds have been added for publishing purposes. If you want to copy/paste the commands, first paste them into a text editor and remove the line feeds. Then copy into your shell or Command Prompt window. There should be a space between the end of a -D entry and the beginning of the next one.
|
|
|
Make sure that you do NOT use double quotation marks when setting the environment variable on Windows. If you use them, the Connector will fail to start.
|
2. To limit the secure protocol version used between the Connector and ThingWorx Platform, add the desired version of the TLS protocol to the AZURE_IOT_OPTS environment variable before launching the Connector. From most secure to least, the versions you can choose are TLSv1.2, TLSv1.1, and TLSv1 protocols.
For example
-Djdk.tls.client.protocols=TLSv1.2
3. If you did not need to create a new Trust Store, you have completed the setup for using SSL/TLS between the Azure IoT Hub Connector and ThingWorx. Otherwise, to use the customized cacerts file that you created as the Trust Store, run the following command:
-Djavax.net.ssl.trustStore=/etc/opt/java/security/cacerts-customized
-Djavax.net.ssl.trustStorePassword=new-password