Initial Setup of Integration Runtime Service for Integration Connectors
After installing ThingWorx, follow the steps below to download and configure the ThingWorx Runtime Service. If you are in a Docker environment, you can use an installer to set up a basic configuration for the Integration Connectors. The installer includes a logging file where you can modify some configuration as described below.
Downloading Integration Runtime
The Integration Runtime service is available at support.ptc.com under Download Software > Order or Download Software Updates > ThingWorx Foundation > Release <version> > ThingWorx Integration Runtime > Most Recent Version > ThingWorx-Integration-Runtime-<version>.
Configuring Integration Runtime
 |
Do not create a Thing from the IntegrationRuntime Thing Template.
|
1. Create an application key in ThingWorx for the Integration Runtime to use for communication to the ThingWorx Platform.
2. Launch Integration Services as a Java process using one of the following options:
|
|
Do not enable -Dorg.apache.camel.jmx.createRmiConnector settings.
|
◦ external configuration file specifying connection parameters.
java -DconfigFile=<path to IntegrationRuntime settings>-jar <path to IntegrationRuntime-x.x.x>.jar, where x.x.x is replaced with the version you are using.
3. (Optionally) Create custom logback settings file, and specify the path to it on the command line using the following: -Dlogs.includedLogback=<path to logback include>
4. If you are encrypting entries in the integrationRuntime-settings.json configuration file or encrypting the entire configuration file, you must specify the path to the security-common encryption configuration on the command line using the following:
|
|
-Dencrypted.config.file=true is required in the examples below if you are encrypting the entire configuration file, and it must point to the encrypted Integration Runtime configuration file. If you are only encrypting entries in the file, omit the setting or set it to false.
|
java -Dsecret.management.config.file=<Path to encryption.conf> -Dencrypted.config.file=true -DconfigFile=<path to encrypted integrationRuntime-settings.json.encrypted>
An example command is provided below:
java -Dsecret.management.config.file=C:\Integ_runtime\encryption.conf -Dencrypted.config.file=true -DconfigFile=integrationRuntime-settings.json.encrypted -jar C:\Integ_runtime\integration-runtime-x.x.x-bXXX.jar
5. If you are running ThingWorx High Availability (HA) clustering, all WebSocket connectionsmustbe routed through a ThingWorx Connection Server.
The Integration Connector uses WebSockets to communicate with ThingWorx. A typical HA landscape uses multiple Connection Servers with a load balancer in front of the Connection Servers. In an HA landscape, the Integration Runtime must route through the configured load balancer and to a Connection Server.
Sample Configuration File (integrationRuntime-settings.json)
{
"traceRoutes": "false",
"OutboundTimeout": "1",
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"basePath": "/Thingworx",
"sslEnable": "true",
"ignoreSSLErrors": "false"
},
"Performance": {
"minPoolSize":"4",
"maxPoolSize":"10",
"maxThreadLife":"10000",
"maxQueueSize":"1000"
},
"Proxy": {
"host":"localhost",
"port":"8888",
"user":"<proxy username>",
"pass":"<proxy password>"
},
"SSL": {
"verbose": "true",
"Keystore": {
"path": "/usr/security/keystore.jks",
"password": "encrypt.keystore.password"
},
"Truststore": {
"path": "/usr/security/truststore",
"password": "encrypt.truststore.password"
}
},
"RetryPolicy": {
"MaximumRetries": 2,
"RetryDelay": 2000,
"BackoffMultiplier": 1
},
"RedirectPolicy": {
"MaximumRedirects": 3,
"EnableRedirect": true
}
}
"traceRoutes": "false",
"OutboundTimeout": "1",
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"basePath": "/Thingworx",
"sslEnable": "true",
"ignoreSSLErrors": "false"
},
"Performance": {
"minPoolSize":"4",
"maxPoolSize":"10",
"maxThreadLife":"10000",
"maxQueueSize":"1000"
},
"Proxy": {
"host":"localhost",
"port":"8888",
"user":"<proxy username>",
"pass":"<proxy password>"
},
"SSL": {
"verbose": "true",
"Keystore": {
"path": "/usr/security/keystore.jks",
"password": "encrypt.keystore.password"
},
"Truststore": {
"path": "/usr/security/truststore",
"password": "encrypt.truststore.password"
}
},
"RetryPolicy": {
"MaximumRetries": 2,
"RetryDelay": 2000,
"BackoffMultiplier": 1
},
"RedirectPolicy": {
"MaximumRedirects": 3,
"EnableRedirect": true
}
}
Configuration File Settings
As explained in the descriptions, some configuration settings can be specified or can override configuration file settings using Java system properties (for example, -D<name>=<value>).
|
Setting
|
Default
|
Description
|
|---|---|---|
|
traceRoutes
|
false
|
Specifies whether the route execution should log messages as each processor in the route is invoked.
|
|
Thingworx
|
Specifies the settings needed to connect to the ThingWorx Platform (single-server mode) or Connection Server load balancer (cluster mode), formatted as JSON.
|
|
|
SSL
|
Specifies the Secure Sockets Layer (SSL) settings in JSON format.
|
|
Setting
|
Default
|
Description
|
||
|---|---|---|---|---|
|
appKey
|
Specifies the application key from the ThingWorx Platform that has been configured for use by this Integration Runtime. This setting can be overridden with a Java system property.
|
|||
|
basePath
|
/Thingworx
|
Specifies the base path in the URI to the ThingWorx Platform (single-server mode) or Connection Server load balancer (cluster mode). This setting can be overridden with a Java system property.
|
||
|
OutboundTimeout
|
WSCommnucationSubsystem’s Idle Connection Timeout
|
Specifies the Integration Runtime timeout for any third party request in waiting state. If no value is specified, Integration Runtime will take value from WSCommunicationSubsytem’s Idle connection timeout.
When Integration Runtime gets started, it will compare the value specified in integrationRuntime-settings.json file and WSCommunictaionSubsystem’s Idle Connection timeout. The lower of these two values will be passed to Integration Runtime.
The default value is 30 and can be set as required.
|
||
|
host
|
localhost
|
Specifies the host in the URI to the ThingWorx Platform (single-server mode) or Connection Server load balancer (cluster mode). This setting can be overridden with a Java system property.
|
||
|
port
|
443
|
Specifies the port in the URI to the ThingWorx Platform (single-server mode) or Connection Server load balancer (cluster mode). This setting can be overridden with a Java system property.
|
||
|
sslEnable
|
true
|
Specifies whether SSL should be used to connect to the ThingWorx Platform via WebSocket. If true, then "wss" protocol is used for the URI. Otherwise, "ws" protocol is used.
|
||
|
ignoreSSLErrors
|
false
|
Specifies whether SSL errors should be ignored. This value should not be set to true in a production environment.
|
|
Setting
|
Default
|
Description
|
|---|---|---|
|
minPoolSize
|
4
|
Minimum number of threads allocated to an event processing pool.
|
|
maxPoolSize
|
10
|
Maximum number of threads allocated to an event processing pool.
|
|
maxThreadLife
|
10000
|
Maximum response wait time for a thread.
|
|
maxQueueSize
|
1000
|
Maximum queue entries before adding a new working thread.
|
|
Setting
|
Default
|
Description
|
|---|---|---|
|
host
|
N/A
|
The name of the proxy host.
|
|
port
|
N/A
|
The port number of the proxy host.
|
|
User
|
N/A
|
The user name of the proxy host.
|
|
Pass
|
N/A
|
The password of the proxy host.
|
|
Setting
|
Default
|
Description
|
|---|---|---|
|
verbose
|
false
|
Specifies whether Java handshake protocol will output verbose messages. If true, then Java system property javax.net.debug is set to ssl:handshake:verbose.
|
|
Keystore
|
Specifies the SSL keystore settings in JSON format.
|
|
|
Truststore
|
Specifies the SSL truststore settings in JSON format.
|
|
Setting
|
Description
|
|---|---|
|
path
|
Specifies the path to the SSL keystore file. Using this setting is equivalent to setting the Java system property javax.net.ssl.keyStore.
|
|
password
|
Specifies the password for to the SSL keystore file. Using this setting is equivalent to setting the Java system property javax.net.ssl.keyStorePassword. To avoid storing the password as plain text, use the value encrypt.keystore.password. See the Encrypting Password Settings section below.
|
|
Setting
|
Description
|
|---|---|
|
path
|
Specifies the path to the SSL truststore file. Using this setting is equivalent to setting the Java system property javax.net.ssl.trustStore.
|
|
password
|
Specifies the password for to the SSL truststore file. Using this setting is equivalent to setting the Java system property javax.net.ssl.trustStorePassword. To avoid storing the password as plain text, use the value encrypt.truststore.password. See the Encrypting Password Settings section below.
|
|
Setting
|
Default
|
Description
|
|---|---|---|
|
MaximumRetries
|
2
|
Specifies the number of times to retry a request after it has failed due to system availability.
In the case of HTTP requests, retries occur with a 503 response from the server.
|
|
RetryDelay
|
1000
|
When a request fails but can be retried, RetryDelay represents how long (in milliseconds) to wait before attempting to retry. RetryDelay will be used in conjunction with BackoffMultiplier when determining subsequent retries.
|
|
BackoffMultiplier
|
1
|
Specifies for how long to multiply the RetryDelay on subsequent retries. For example, if the BackoffMultiplier was set to2 and MaximumRetries was set to 3, the first retry would occur at 1 second; the second retry would occur 2 seconds after the first; the third would occur 4 seconds after and so on.
|
|
UnauthorizedRetries
|
2
|
Specifies the number of times to retry a request that failed due to an unauthorized request. This setting applies to an HTTP request with a 401 response from the server.
|
|
Setting
|
Default
|
Description
|
|---|---|---|
|
MaximumRedirects
|
3
|
Specifies the number of times to retry a redirect.
|
|
EnableRedirect
|
true
|
Specifies if redirect is enabled for requests resulting in a redirect status code 3xx.
|
Encrypting the Configuration File
To provide greater security, you can encrypt the entire configuration file and, optionally, individual values within the file. This feature is provided in version 8.0.4+ of Integration Runtime. The installation of the Integration Runtime includes the security-common library. The JAR for this library is included in the Integration Runtime installation. It provides the back-end tool that does the encrypting and decrypting of the configuration file.
A Command Line Interface (CLI) is available to interact with the security library, which includes encrypting the configuration file. For complete information about this CLI, reference Security Management Tool. This topic explains where to obtain the tool and how to use it. For your convenience, steps specific to Integration Runtime are provided in the sections below. You can download the CLI from the PTC Support Site.
1. The security-common library requires its own configuration file. Using a text editor, create the following file and save it as encryption.conf:
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128
keystore {
password-file-path = "/ThingworxPlatform"
password-file-name = "keystore-password"
path = "/ThingworxStorage"
name = "keystore"
}
}
}
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128
keystore {
password-file-path = "/ThingworxPlatform"
password-file-name = "keystore-password"
path = "/ThingworxStorage"
name = "keystore"
}
}
}
2. Create the password-file-path and path directories specified in the encryption.conf file. In the example above, the password-file-path directory is /ThingworxPlatform (Linux). On a Windows computer, it would be C:\\ThingworxPlatform.
|
|
You can store the encrypted configuration file anywhere. Just make sure that the encryption configuration file and the environment variables point to the correct path.
|
3. Assuming that you have downloaded and extracted the CLI distribution, you can encrypt the configuration file. Open a command prompt or shell, and navigate to the securitycommon-cli-x.x.x.xx/bin directory, where x.x.x.xx represents the version of the tool.
4. Run the CLI, as appropriate to your operating system:
◦ Linux — security-common-cli
◦ Windows — security-common-cli.bat
5. When prompted, enter the name of the security configuration file to initialize. The following is a Linux example of the sequence:
../security-common-cli-1.x.x.xx/bin$ ./security-common-cli
Not initialized, use 'init <config-file>' to initialize
> init [pathTo]encryption.conf
Loading config from file encryption.conf
Secret Provider: com.thingworx.security.provider.keystore.KeyStoreProvider
KeyStore
Path: /ThingworxPlatform/keystore
Password File: /ThingworxStorage/keystore-password
Keystore Password: 336974503775017XXXX
>
Not initialized, use 'init <config-file>' to initialize
> init [pathTo]encryption.conf
Loading config from file encryption.conf
Secret Provider: com.thingworx.security.provider.keystore.KeyStoreProvider
KeyStore
Path: /ThingworxPlatform/keystore
Password File: /ThingworxStorage/keystore-password
Keystore Password: 336974503775017XXXX
>
6. While still in the security CLI, encrypt the configuration file of the Integration Runtime. In this example, it is integrationRuntime-settings.json using the encryptFile command, as shown below:
encryptFile C:\Integ_runtime\integrationRuntime-settings.json C:\Integ_runtime\integrationRuntime-settings.json.encrypted
integrationRuntime-settings.json.encrypted is your encrypted configuration file.
7. Verify that the encryption was successful by using the decryptFile command:decryptFile C:\Integ_runtime\integrationRuntime-settings.json.encrypted C:\Integ_runtime\integrationRuntime-settings.json.decrypted
|
|
The content of the integrationRuntime-settings.json.decrypted should match the content of the original integrationRuntime-settings.json file.
|
|
|
Remove the unencrypted versions of the file.
|
8. To close the CLI, type exit at the prompt.
Encrypting Entries in the Configuration File
Passwords or other entries in the configuration file can be encrypted in Integration Runtime 8.0.4+. Use the same encryption mechanism for the ThingWorx Platform that is used for encrypting the PostgreSQL database password.
Follow the instructions in Encrypting Passwords, but use the values encrypt.app.key instead of encrypt.db.password or encrypt.licensing.password, and using the integrationRuntime-settings.json instead of platform-settings.json. If your ThingWorx system is already using encryption for the PostgreSQL database password, then these new passwords are added to the same keystore file; otherwise, a new keystore file is created.
Migrating the Keystore and Keystore Password
If you used a keystore for encrypting values and are now performing a migration, complete the following steps on the keystore and password files:
1. If the Integration Runtime is still using twx/config and /ThingworxStorage/keyStore as your keystore files, then do the following:
◦ Copy /twx/config to /ThingworxPlatform/keystore-password
◦ Copy /ThingworxStorage/keyStore to /ThingworxStorage/keystore.jks
2. Starting with ThingWorx 8.5, the keystore format changed from .jks to .pfx. You need to migrate the keystore. See "Changes in ThingWorx 8.5" in the Security Management Tool topic for more info.
3. This step varies, depending on whether your Integration Runtime shares keystore files with the 8.5+ ThingWorx server's Keystore:
◦ If it does share keystore files with the 8.5+ ThingWorx Platform's keystore, follow the Upgrading ThingWorx guide to have the ThingWorx server automatically migrate the keystore file from the old ".jks" to the new ".pfx" format.
◦ If it does not share keystore files with the platform, follow these steps:
a. Download the latest version of the security-common-cli. For assistance, see the "Usage" section of the topic, Security Management Tool.
b. Start the CLI and the keystore will automatically be migrated. For example:
./security-common-cli encryption.conf
c. In your encryption.conf file, change all references to keystore.jks to keystore. Do not include the .pfx file extension.
d. Backup the old keystore.jks to a secure location and remove it from the ThingworxStorage directory.
Configuring for SSL
By default, the Integration Runtime connects to ThingWorx using SSL. The following table describes the ThingWorx Platform configurations and the associated Integration Runtime configuration settings that are needed to connect successfully. The keystore settings are not necessary for connecting to the ThingWorx Platform; they provide a client certificate from the Integration Runtime in a two-way SSL negotiation.
|
ThingWorx Configuration
|
Integration Runtime Settings
|
|---|---|
|
ThingWorx is not configured for SSL
|
Specify thingworxUri using a Java system property and use ws protocol or specify sslEnable=false in SSL settings.
|
|
ThingWorx is configured for SSL using self-signed certificate
|
Specify sslEnable=true and ignoreSSLErrors=true in SSL settings.
|
|
ThingWorx is configured for SSL with a self-signed certificate and the certificate is trusted.
ThingWorx is configured for SSL with a certificate signed by a Certificate Authority (CA), and it was not configured to provide the entire CA Certificate Chain.
|
Export the certificate from the keystore file and import it to a truststore file.
Specify enable=true and Trustore in SSL settings.
Truststore password may be encrypted.
Alternatively, add the certificate to the Integration Runtime JVM default truststore (usually located here:$JAVA_HOME/lib/security/cacerts). In this case, it is not necessary to explicitly specify Truststore in SSL settings.
|
|
ThingWorx is configured for SSL with a certificate signed by a Certificate Authority (CA), and it was configured to provide the entire CA Certificate Chain.
|
Specify enable=true in SSL settings. This is the default setting.
|
SSL Configuration Example: Non-Productions Configuration
If ThingWorx is configured for SSL using a self-signed certificate, use the following integrationRuntime-settings.json:
{
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"sslEnable": "true",
"ignoreSSLErrors": "true"
}
}
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"sslEnable": "true",
"ignoreSSLErrors": "true"
}
}
SSL Configuration Example: Production Configuration
If ThingWorx is configured for SSL using a self-signed certificate, use the following steps to create a truststore:
1. Fetch the server's self-signed certificate. It is used in the next step to force the Integration Runtime to trust it.
If you don’t have the certificate stored locally, this is one way to acquire ThingWorx Platform's self-signed certificate.
openssl s_client -connect your-ThingWorx-platform:8443< /dev/null| sed -ne'/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'twx-platform-public.crt
2. Create local copy of truststore that the Integration Runtime will use to trust the server's self-signed certificate.
Rather than add the missing certificate directly to the JVM's stock truststore, first save a copy of it, and then add the missing certificate to the copy.
cp $JAVA_HOME/jre/lib/security/cacerts /etc/opt/java/security/cacerts-customized
$JAVA_HOME/bin/keytool -importcert -alias somealias -keystore /etc/opt/java/security/cacerts-customized -file twx-platform-public.crt
$JAVA_HOME/bin/keytool -importcert -alias somealias -keystore /etc/opt/java/security/cacerts-customized -file twx-platform-public.crt
3. Change the password the truststore.
The default password for the JVM cacerts file is changeit. Similar to changing the password of any other keystore, we could change the password of cacerts-customized by issuing the following:
keytool storepasswd keystore /etc/opt/java/security/cacerts-customized
Enter keystore password: changeit
New keystore password: new-password
Re-enter new keystore password: new-password
Enter keystore password: changeit
New keystore password: new-password
Re-enter new keystore password: new-password
4. Use the following integrationRuntime-settings.json.
{
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"sslEnable": "true",
"ignoreSSLErrors": "false"
}
"SSL": {
"Truststore": {
"path": "/etc/opt/java/security/cacerts-customized",
"password": "new-password"
}
}
}
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"sslEnable": "true",
"ignoreSSLErrors": "false"
}
"SSL": {
"Truststore": {
"path": "/etc/opt/java/security/cacerts-customized",
"password": "new-password"
}
}
}
Sample Log Configuration File (integrationRuntime-logback.xml)
<?xml version="1.0"?>
<included>
<property name="logs.dir" value="/ThingworxStorage/IRlogs" />
<property name="logs.uniqueId" value="${processId}" />
<property name="logs.maxFileSize" value="1MB" />
<property name="logs.maxIndex" value="5" />
<logger name="com.twx.integration" level="DEBUG" />
<logger name="org.apache.camel" level="DEBUG" />
</included>
<included>
<property name="logs.dir" value="/ThingworxStorage/IRlogs" />
<property name="logs.uniqueId" value="${processId}" />
<property name="logs.maxFileSize" value="1MB" />
<property name="logs.maxIndex" value="5" />
<logger name="com.twx.integration" level="DEBUG" />
<logger name="org.apache.camel" level="DEBUG" />
</included>
Log Configuration File Settings
A standard logback.xml configuration file is included in the IntegrationRuntime.jar. For more information on logback configuration, see Logback Project. This file sets up the root logger with logging to the console and a rolling log file. You can specify an optional include file using this Java system property: logs.includedLogback. Use the include file to enable other loggers and specify properties. The rolling log file is configured with a fixed window and size-based triggering policies, and it can be customized by setting the properties below:
|
Setting
|
Default
|
Description
|
|---|---|---|
|
logs.dir
|
Specifies the location where log files will be generated. The default is the current working directory.
|
|
|
logs.maxFileSize
|
5MB
|
Specifies the maximum log file size that triggers a rollover to a new log file.
|
|
logs.maxIndex
|
9
|
Specifies the maximum index of the fixed size rollover window. The initial index starts at 1.
|
|
logs.timestampPattern
|
yyyy-dd-MM HH:mm:ss.SSS
|
Specifies the timestamp pattern to use for each log event.
|
|
logs.uniqueId
|
<processId>
|
Specifies a value that is appended to the log file name. This is used to generate unique file names. The default value is obtained via a Java callback to return the JVM's process ID.
|