Updating ThingWorx Flow
Updating ThingWorx Flow manually is supported for the following versions:
• From an older version of 8.4.x to a later version of 8.4.x.
• From 8.4.x to 8.5.x.
• From an older version of 8.5.x to a later version of 8.5.x.
 |
Manual upgrade from a fresh installation of ThingWorx Flow 8.4.x to 9.x is not available. If you want to upgrade from a fresh installation of ThingWorx Flow 8.4.x to 9.x, you must migrate ThingWorx Flow.
|
|
|
If you wish to upgrade from a fresh installation of ThingWorx Flow 8.5.x and later to 9.x, you must use the ThingWorx Flow automated upgrade installer.
|
For this procedure, let us assume that you are currently on <older-8.x.x> and you want to update to <newer-8.x.x>.
Prerequisites
Before you update ThingWorx Flow, ensure that you have set the following prerequisites:
• You have the necessary privileges to modify all installed files for the services.
• You have downloaded the appropriate ThingWorx Flow patch update <newer-8.x.x> version for your operating system from the PTC Software Downloads website.
Here are the main steps of the process:
Step 1: Stop the ThingWorx Foundation and ThingWorx Flow services
Depending on your operating system, use the service control tools, sc or Services for Windows and sysctl for Linux to stop the following services:
• ThingWorxOrchestrationNginx or nginx
• ThingWorx-Foundation
• ThingWorx-Flow
• RabbitMQ / rabbitmq.service
Ensure that all respective processes are completely stopped. Any running process may cause issues in later stages while updating the folders.
Step 2: Back up your existing installation
Back up your existing installation that includes, but is not limited to the following:
• The ThingworxPlatform and ThingworxStorage folders in your ThingWorx Foundation installation folder
• The ThingworxOrchestration folder where ThingWorx Flow components were installed
• The ThingWorx Foundation and ThingWorx Flow databases
It is strongly recommended that you use the in built facilities to create backups with your database solution.
On PostgreSQL, use the pg_dump tool. On Microsoft SQL Server, use SQL Server Management Studio.
If you have installed ThingWorx Flow and/ or ThingWorx Foundation on virtual machines, use the native snapshot functionality to roll back an update. If you revert to the snapshot, you must restore your database backup if your database is hosted on a separate server or a virtual machine.
Step 3: Update ThingWorx Foundation to <newer–8.x.x>
If you are updating from 8.4.x to 8.5.x, refer to the section that is appropriate to your operating system and database type in the Upgrading to ThingWorx 8.5 guide.
If you are updating from an older version of 8.4.x to a newer version of 8.4.x, or an older version of 8.5.x to a newer version of 8.5.x, you might have to replace the Thingworx.war file only.
Step 4: Extract the ThingWorx Flow update TAR contents to a temporary folder
1. Create a new folder, modules-<newer-8.x.x> in the /ThingworxOrchestration folder.
This modules-<newer-8.x.x> folder must be parallel to the existing modules folder.
2. Extract the contents of the flow-upgrade-<newer-8.x.x>.tar.gz patch update to the modules-<newer-8.x.x> folder.
After you extract the contents of the TAR, the /ThingworxOrchestration/modules-<newer-8.x.x>/ folder must have the following folders:
◦ configs
◦ db_seed
◦ engine
◦ exchange
◦ lookup
◦ oauth
◦ 8.4.12 and later, 8.5.8 and later—ptc-flow-pm2 / pm2
◦ README.pdf
◦ static-ux
◦ symphony-cli
◦ symphony-connectors
◦ symphony-deploy
◦ symphony-sdk
◦ symphony-test-helper
◦ trigger
◦ tw-security-common-nodejs
◦ ux
◦ (Windows only) 8.4.12 and later, 8.5.8 and later—nginx-1.18.0.zip
◦ (Windows only) 8.4.12 and later, 8.5.8 and later—node-v12.16.3-win-x64.tar.gz
8.4.15 and later, 8.5.11 and later—node-v12.19.0-win-x64.tar.gz
Step 5: Replace the ThingWorx Flow services with their patched versions
1. To merge the existing ThingWorx Flow configuration setup with the patched software, copy the following specific files or folders from the existing ThingWorxOrchestration/modules/ folder to the /ThingWorxOrchestration/modules-<newer-8.x.x> folder:
|
Copy from
|
Copy to
|
|---|---|
|
/ThingworxOrchestration/modules/db_seed/config
|
/ThingworxOrchestration/modules-<newer-8.x.x>/db_seed/
|
|
/ThingworxOrchestration/modules/db_seed/migration_config.json
|
/ThingworxOrchestration/modules-<newer-8.x.x>/db_seed/
|
|
/ThingworxOrchestration/modules/db_seed/SHA1
Optional, only if it exists.
|
/ThingworxOrchestration/modules-<newer-8.x.x>/db_seed/
|
|
/ThingworxOrchestration/modules/engine/config
|
/ThingworxOrchestration/modules-<newer-8.x.x>/engine/
|
|
/ThingworxOrchestration/modules/engine/deploymentConfig.json
|
/ThingworxOrchestration/modules-<newer-8.x.x>/engine/
|
|
/ThingworxOrchestration/modules/engine/SHA1
Optional, only if it exists.
|
/ThingworxOrchestration/modules-<newer-8.x.x>/engine/
|
|
/ThingworxOrchestration/modules/exchange/config
|
/ThingworxOrchestration/modules-<newer-8.x.x>/exchange/
|
|
/ThingworxOrchestration/modules/exchange/deploymentConfig.json
|
/ThingworxOrchestration/modules-<newer-8.x.x>/exchange/
|
|
/ThingworxOrchestration/modules/exchange/SHA1
Optional, only if it exists.
|
/ThingworxOrchestration/modules-<newer-8.x.x>/exchange/
|
|
/ThingworxOrchestration/modules/lookup/config
|
/ThingworxOrchestration/modules-<newer-8.x.x>/lookup/
|
|
/ThingworxOrchestration/modules/lookup/deploymentConfig.json
|
/ThingworxOrchestration/modules-<newer-8.x.x>/lookup/
|
|
/ThingworxOrchestration/modules/lookup/SHA1
Optional, only if it exists.
|
/ThingworxOrchestration/modules-<newer-8.x.x>/lookup/
|
|
/ThingworxOrchestration/modules/oauth/config
|
/ThingworxOrchestration/modules-<newer-8.x.x>/oauth/
|
|
/ThingworxOrchestration/modules/oauth/deploymentConfig.json
|
/ThingworxOrchestration/modules-<newer-8.x.x>/oauth/
|
|
/ThingworxOrchestration/modules/oauth/SHA1
Optional, only if it exists.
|
/ThingworxOrchestration/modules-<newer-8.x.x>/oauth/
|
|
/ThingworxOrchestration/modules/static-ux/config
|
/ThingworxOrchestration/modules-<newer-8.x.x>/static-ux/
|
|
/ThingworxOrchestration/modules/static-ux/SHA1
Optional, only if it exists.
|
/ThingworxOrchestration/modules-<newer-8.x.x>/static-ux/
|
|
/ThingworxOrchestration/modules/trigger/config
|
/ThingworxOrchestration/modules-<newer-8.x.x>/trigger/
|
|
/ThingworxOrchestration/modules/trigger/deploymentConfig.json
|
/ThingworxOrchestration/modules-<newer-8.x.x>/trigger/
|
|
/ThingworxOrchestration/modules/trigger/SHA1
Optional, only if it exists.
|
/ThingworxOrchestration/modules-<newer-8.x.x>/trigger/
|
|
/ThingworxOrchestration/modules/ux/config
|
/ThingworxOrchestration/modules-<newer-8.x.x>/ux/
|
|
/ThingworxOrchestration/modules/ux/deploymentConfig.json
|
/ThingworxOrchestration/modules-<newer-8.x.x>/ux/
|
|
/ThingworxOrchestration/modules/ux/SHA1
Optional, only if it exists.
|
/ThingworxOrchestration/modules-<newer-8.x.x>/ux/
|
|
/ThingworxOrchestration/modules/orchestration.pm2.json
|
/ThingworxOrchestration/modules-<newer-8.x.x>/
|
|
/ThingworxOrchestration/modules/cache
|
/ThingworxOrchestration/modules-<newer-8.x.x>/
|
|
/ThingworxOrchestration/modules/node_modules/config
|
/ThingworxOrchestration/modules-<newer-8.x.x>/symphony-connectors/node_modules/
|
2. Move the following folders and files from /ThingworxOrchestration/modules-<newer-8.x.x>/symphony-connectors/ to /ThingworxOrchestration/modules-<newer-8.x.x>/:
◦ node_modules
◦ package.json
◦ package-lock.json
3. From /ThingworxOrchestration/modules-<newer-8.x.x>/, delete the empty symphony-connectors folder.
4. If you are upgrading from ThingWorx Flow 8.4.x to ThingWorx Flow 8.5.x, add the following lines to the deploymentConfig.json file under the /ThingworxOrchestration/modules-<newer-8.x.x>/engine/ folder:
"ENGINE_SIZE": "1802",
"KILL_WORKER_AFTER_RUN": "false",
"AVAILABLE_WORKER_CHECK_TRIES": "10",
"AVAILABLE_WORKER_CHECK_INTERVAL": "3000",
"WORKER_DISMISS_INTERVAL": "1800",
"KILL_WORKER_AFTER_RUN": "false",
"AVAILABLE_WORKER_CHECK_TRIES": "10",
"AVAILABLE_WORKER_CHECK_INTERVAL": "3000",
"WORKER_DISMISS_INTERVAL": "1800",
5. If you are upgrading from ThingWorx Flow 8.4.x to ThingWorx Flow 8.5.x, add the following lines to the deploymentConfig.json file under the /ThingworxOrchestration/modules-<newer-8.x.x>/ux/ folder:
"EXCHANGE": {
"HOST": "localhost",
"PORT": "7822"
},
"lookup": {
"host": "http://localhost:8077"
},
"HOST": "localhost",
"PORT": "7822"
},
"lookup": {
"host": "http://localhost:8077"
},
6. To update Flow Utilities, perform the following steps:
a. Delete the following folders from /ThingWorxOrchestration/packages:
▪ symphony-cli
▪ symphony-deploy
▪ symphony-sdk
▪ symphony-test-helper
b. Move the following folders from /ThingworxOrchestration/modules-<newer-8.x.x> to /ThingWorxOrchestration/packages:
▪ symphony-cli
▪ symphony-deploy
▪ symphony-sdk
▪ symphony-test-helper
c. Ensure that the user that installed ThingWorx Flow has complete ownership and permissions to all the Flow Utilities.
For example, navigate to the /ThingWorxOrchestration/packages folder and run the following command:
chown -R flowuser:flowuser symphony-cli
Replace flowuser with the user that ran the ThingWorx Flow installer.
7. (Linux only) Ensure that the user that installed ThingWorx Flow has complete ownership and permissions to the modules-<newer-8.x.x> folder.
Navigate to the ThingWorxOrchestration folder and run the following command:
chown -R flowuser:flowuser modules-<newer-8.x.x>
Replace flowuser with the user that ran the ThingWorx Flow installer.
8. (Windows only) Copy the RabbitMQ folder from the modules folder to the modules-<newer-8.x.x> folder.
9. After you have copied all the configuration settings, you must rename the following folders:
a. Rename the existing modules folder to modules-<older-8.x.x>.
b. Rename the modules-<newer-8.x.x> folder to modules.
|
|
On Windows, before you proceed with renaming the folders, you must stop the epmd.exe process.
|
For example, to rename the folders on Linux, run the following commands:
a. mv /ThingworxOrchestration/modules /ThingworxOrchestration/modules-<older-8.x.x>
b. mv /ThingworxOrchestration/modules-<newer-8.x.x> /ThingworxOrchestration/modules
10. (Linux only) Navigate to the ThingWorxOrchestration folder and run the following command to set full permissions to the modules folder:
chmod -R 777 modules
11. (Linux only) Navigate to the ThingWorxOrchestration/modules folder and run the following command to set the correct security context to the static-ux folder:
chcon -R -t httpd_sys_content_t static-ux
12. Rename and move the following folders:
a. Rename the existing tw-security-common-nodejs folder at /ThingWorxOrchestration/cryptography to tw-security-common-nodejs_<older-8.x.x>.
b. Move the tw-security-common-nodejs folder from /ThingworxOrchestration/modules/ to /ThingWorxOrchestration/cryptography.
c. Ensure that the user that installed ThingWorx Flow has complete ownership and permissions to the tw-security-common-nodejs folder.
For example, navigate to the /ThingWorxOrchestration/cryptography folder and run the following command:
chown -R flowuser:flowuser tw-security-common-nodejs
Replace flowuser with the user that ran the ThingWorx Flow installer.
d. If you are updating to 8.4.x, navigate to the /ThingWorxOrchestration/cryptography/tw-security-common-nodejs folder and run the following commands:
▪ On Windows, run npm install
On Linux, run sudo npm install.
▪ On Linux, run sudo chown -R flowuser:flowuser node_modules
Replace flowuser with the user that ran the ThingWorx Flow installer.
Step 6: Update Nginx, PM2, and NodeJS, if not already updated (8.4.12 and later, 8.5.8 and later)
Skip this step if you are already on the following versions:
• Nginx—1.18.0
• PM2—4.4.0
• NodeJS—12.19.x
|
|
If you skip this step, delete the following folders, from the modules folder:
• ptc-flow-pm2 / pm2
• nginx-1.18.0.zip
• node-v12.19.0-win-x64.tar.gz
|
Nginx
Windows
1. Rename C:\Program Files\nginx-1.13.12 to C:\Program Files\nginx-1.13.12_old.
2. From <Flow installation Directory>\modules, extract nginx-1.18.0.zip under C:\Program Files. Verify that you can see C:\Program Files\nginx-1.18.0\nginx.exe.
3. Rename C:\Program Files\nginx-1.18.0 to C:\Program Files\nginx-1.13.12.
4. Replace the C:\Program Files\nginx-1.13.12\conf\nginx.conf file by the C:\Program Files\nginx-1.13.12_old\conf\nginx.conf file.
5. Copy the C:\Program Files\nginx-1.13.12_old\conf\conf.d file to C:\Program Files\nginx-1.13.12\conf\.
6. From <Flow installation Directory>\modules, delete nginx-1.18.0.zip.
Linux
1. Create the /etc/yum.repos.d/nginx.repo file with the following content:
[nginx-stable]
name=nginx stable repo
baseurl=http://nginx.org/packages/centos/$releasever/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true
name=nginx stable repo
baseurl=http://nginx.org/packages/centos/$releasever/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true
2. Run the sudo yum upgrade nginx command.
PM2
Windows
1. Backup the <Flow installation Directory>\packages\ptc-flow-pm2\node_modules\pm2-windows-service-nosetup\src\daemon folder.
If you are on ThingWorx Flow 8.4.x, then the ptc-flow-pm2 folder is called pm2.
2. Rename <Flow installation Directory>\packages\ptc-flow-pm2 folder to ptc-flow-pm2_old.
If you are on ThingWorx Flow 8.4.x, then rename pm2 to pm2_old.
3. If you are updating from 8.4.x, do the following:
a. Move the pm2 folder from <Flow installation Directory>\modules to <Flow installation Directory>\packages and rename it to pm2.
b. Edit the <Flow installation Directory>\packages\pm2\node_modules\pm2-windows-service-nosetup\src\daemon\thingworxflow.xml file so that the following path is valid:
<argument>C:\ThingWorxOrchestration\packages\pm2\node_modules\node-windows\lib\wrapper.js</argument>
c. Add the following to the Path environment variable:
C:\ThingWorxOrchestration\packages\pm2\node_modules\.bin
d. Add the following environment variable:
PM2_SERVICE_PM2_DIR = C:\ThingWorxOrchestration\packages\pm2\node_modules\pm2
4. If you are updating from 8.5.x, replace <Flow installation Directory>\packages\ptc-flow-pm2 by the ptc-flow-pm2 folder from<Flow installation Directory>\modules.
5. Copy the backed-up daemon directory to <Flow installation Directory>\packages\ptc-flow-pm2\node_module\pm2-windows-service-nosetup\src.
If you are on ThingWorx Flow 8.4.x, then the ptc-flow-pm2 folder is called pm2.
Linux
1. Replace <Flow installation Directory>/packages/ptc-flow-pm2 by the ptc-flow-pm2 folder from <Flow installation Directory>\modules.
If you are on ThingWorx Flow 8.4.x, then under packages, the ptc-flow-pm2 folder is called pm2.
2. If you are updating from 8.4.x, do the following:
a. Rename the <Flow installation Directory>/packages/pm2 folder to pm2_old.
b. Move the ptc-flow-pm2 folder from <Flow installation Directory>/modules to <Flow installation Directory>/packages and rename it to pm2.
NodeJS
Windows
1. From <Flow installation Directory>\modules,
▪ For ThingWorx Flow 8.5.13 and older versions, extract node-v12.19.0-win-x64.tar.gz
▪ For ThingWorx Flow 8.5.14 and later versions, extract node-v14.16.0-win-x64.tar.gz
2. Replace the <Flow installation Directory>\node folder by the extracted folder.
3. From <Flow installation Directory>\modules,
▪ For ThingWorx Flow 8.5.13 and older versions, delete node-v12.19.0-win-x64.tar.gz
▪ For ThingWorx Flow 8.5.14 and later versions, delete node-v14.16.0-win-x64.tar.gz
Linux
Run the following commands:
1. sudo su
2. sudo curl -sL https://rpm.nodesource.com/setup_12.x | bash
For ThingWorx Flow 8.5.14 and later versions, run
sudo curl -sL https://rpm.nodesource.com/setup_14.x | bash
|
|
If you see the following error, run dnf module enable -y perl command.
Dependency problem: Problem: conflicting requests nothing provides module(perl:5.26) needed by module perl...
|
3. sudo yum install nodejs
4. sudo yum remove rh-nodejs8
|
|
This step is irrelevant if you are upgrading from NodeJS 12.x.
|
5. sudo rm -R /opt/rh
|
|
This step is irrelevant if you are upgrading from NodeJS 12.x.
|
Step 7: Limit the upload size in Nginx to 1 GB (Upgrading from 8.4.x to 8.5.x only)
1. In the <Nginx config directory>\conf.d\vhost-flow.conf file, find the following line:
client_max_body_size 18M;
2. Update the value from 18M to 1000M.
3. Verify that the result looks like this:
client_max_body_size 1000M;
Step 8: Encrypt the Nginx private key (8.4.14 and later, 8.5.10 and later)
The following section describes the steps that you need to perform to encrypt the out-of-the-box key file. If you are using a different .key file, then replace all orchestration.key references with your key file name.
1. Under the <Flow installation Directory>\SSL folder, create the nginx-keyfile file that contains the password for the encrypted private key.
2. Use the openssl utility to run the following command:
<openssl_cmd> rsa -aes256 -passout pass:<Same password as defined in the nginx-keyfile> -in "<Flow installation Directory>\SSL\orchestration.key" -out "<Flow installation Directory>\SSL\orchestration_enc.key"
Where:
◦ In Windows, <openssl_cmd>—Run cd C:/opscode/chef/embedded/bin, type openssl, and run the above command.
◦ In Linux, <openssl_cmd>—Type openssl and run the above command.
3. Delete orchestration.key and rename orchestration_enc.key to orchestration.key.
4. In the <Nginx config directory>\conf.d\vhost-flow.conf file, add the following line after the ssl_certificate_key parameter:
ssl_password_file "<Flow installation Directory>\SSL\nginx-keyfile";
Where:
◦ <Nginx config directory> is C:\Program Files\nginx-1.18.0\conf on Windows
◦ /etc/nginx on Linux.
5. (Linux only) Run the following commands:
a. sudo chown flowuser:flowuser <Flow installation Directory>\SSL\orchestration.key, where flowuser is the user that ran the ThingWorx Flow installer.
b. sudo chcon -t httpd_sys_content_t <Flow installation Directory>\SSL\orchestration.key
c. sudo chown flowuser:flowuser <Flow installation Directory>\SSL\nginx-keyfile, where flowuser is the user that ran the ThingWorx Flow installer.
d. sudo chcon -t httpd_sys_content_t <Flow installation Directory>\SSL\nginx-keyfile
Step 9: Make security changes in the Nginx configuration (8.4.14 and later, 8.5.10 and later)
1. Update the <Nginx config directory>\nginx.conf file to protect from a brute force attack and turn on the rate limit mechanism in Nginx. This limits the number of requests performed from a specific IP address.
a. Find the following lines:
# limit_req_zone $limit_key zone=by_ip:10m rate=100r/s;
# limit_req_zone $limit_method zone=post:10m rate=20r/s;
# limit_req_zone $request_uri zone=by_uri:10m rate=500r/m;
# # limit_req_zone "$binary_remote_addr$request_uri" zone=by_uri_ip:10m rate=2r/s;
# # limit_req_zone $http_authorization zone=by_oauth_token:100m rate=1r/m;
# limit_req_status 429;
# limit_req_zone $limit_method zone=post:10m rate=20r/s;
# limit_req_zone $request_uri zone=by_uri:10m rate=500r/m;
# # limit_req_zone "$binary_remote_addr$request_uri" zone=by_uri_ip:10m rate=2r/s;
# # limit_req_zone $http_authorization zone=by_oauth_token:100m rate=1r/m;
# limit_req_status 429;
b. Uncomment the first and last lines.
c. In the first line, modify the rate to 500r/s.
|
|
You can set the rate (requests per second) to a different number. However, 500r/s is a reasonable number of requests per second that illegitimate clients cannot reach.
|
d. Verify that the result looks like this:
limit_req_zone $limit_key zone=by_ip:10m rate=500r/s;
# limit_req_zone $limit_method zone=post:10m rate=20r/s;
# limit_req_zone $request_uri zone=by_uri:10m rate=500r/m;
# # limit_req_zone "$binary_remote_addr$request_uri" zone=by_uri_ip:10m rate=2r/s;
# # limit_req_zone $http_authorization zone=by_oauth_token:100m rate=1r/m;
limit_req_status 429;
# limit_req_zone $limit_method zone=post:10m rate=20r/s;
# limit_req_zone $request_uri zone=by_uri:10m rate=500r/m;
# # limit_req_zone "$binary_remote_addr$request_uri" zone=by_uri_ip:10m rate=2r/s;
# # limit_req_zone $http_authorization zone=by_oauth_token:100m rate=1r/m;
limit_req_status 429;
2. Update the <Nginx config directory>\nginx.conf file to set cache-control header to no-cache:
a. Find the following line:
map $sent_http_content_type $expires {
b. Change the value of text/html to -1.
c. Verify that the result looks like this:
map $sent_http_content_type $expires {
default off;
text/html -1;
text/css 30d;
application/javascript 7d;
~image/ 30d;
}
default off;
text/html -1;
text/css 30d;
application/javascript 7d;
~image/ 30d;
}
3. Update the <Nginx config directory>\conf.d\vhost-flow.conf file to block the HEAD HTTP method:
a. Find the following lines:
if ($scheme = "https") {
set $secure_var "secure";
}
set $secure_var "secure";
}
b. Add the following lines before the above lines:
# block 'head' http method for security reasons
if ($request_method = 'HEAD') {
return 405;
}
if ($request_method = 'HEAD') {
return 405;
}
c. Verify that the result looks like this:
set $proxy_scheme $scheme;
# block 'head' http method for security reasons
if ($request_method = 'HEAD') {
return 405;
}
if ($scheme = "https") {
set $secure_var "secure";
}
# block 'head' http method for security reasons
if ($request_method = 'HEAD') {
return 405;
}
if ($scheme = "https") {
set $secure_var "secure";
}
4. Update the <Nginx config directory>\conf.d\vhost-flow.conf file to avoid external redirects to location ~ ^(/config|/js|/locales|/resources):
a. Find the following lines:
location /Thingworx/Flow {
rewrite /Thingworx/Flow/(.*) /$1 break;
try_files $uri $uri/ @flow_api;
}
rewrite /Thingworx/Flow/(.*) /$1 break;
try_files $uri $uri/ @flow_api;
}
b. Change try_files $uri $uri/ @flow_api; to try_files $uri @flow_api;.
c. Add the following lines after the above lines:
# avoid external redirects for bellow locations
location ~ ^(/config|/js|/locales|/resources) {
internal;
}
location ~ ^(/config|/js|/locales|/resources) {
internal;
}
d. Verify that the result looks like this:
location /Thingworx/Flow {
rewrite /Thingworx/Flow/(.*) /$1 break;
try_files $uri @flow_api;
}
# avoid external redirects for bellow locations
location ~ ^(/config|/js|/locales|/resources) {
internal;
}
location @flow_api {
rewrite /Thingworx/Flow/(.*) /$1 break;
try_files $uri @flow_api;
}
# avoid external redirects for bellow locations
location ~ ^(/config|/js|/locales|/resources) {
internal;
}
location @flow_api {
5. Update the <Nginx config directory>\conf.d\vhost-flow.conf file to block options HTTP method, and add the rate limit for the brute force protection for the following locations:
|
Location
|
Step 1: Find location
|
Step 2: Add the specified content after the location
|
Step 3: Uncomment the specified line
|
Step 4: Add the specified content to the uncommented line
|
Step 5: Verify the result
|
|---|---|---|---|---|---|
|
location /Thingworx/Oauths
|
location /Thingworx/Oauths {
# limit_req zone=by_ip; # limit_conn addr 500; |
# block 'options' http method for security reasons
if ($request_method = 'OPTIONS') { return 405; } |
# limit_req zone=by_ip;
|
burst=10 nodelay
|
location /Thingworx/Oauths {
# block 'options' http method for security reasons if ($request_method = 'OPTIONS') { return 405; } limit_req zone=by_ip burst=10 nodelay; # limit_conn addr 500; |
|
location /Thingworx/Triggers
|
location /Thingworx/Triggers {
# limit_req zone=by_ip; # limit_conn addr 500; |
# block 'options' http method for security reasons
if ($request_method = 'OPTIONS') { return 405; } |
# limit_req zone=by_ip;
|
burst=10 nodelay
|
location /Thingworx/Triggers {
# block 'options' http method for security reasons if ($request_method = 'OPTIONS') { return 405; } limit_req zone=by_ip burst=10 nodelay; # limit_conn addr 500; |
|
location @flow_api
|
location @flow_api {
# limit_req zone=by_ip; # limit_conn addr 500; |
# block 'options' http method for security reasons
if ($request_method = 'OPTIONS') { return 405; } |
# limit_req zone=by_ip;
|
burst=10 nodelay
|
location @flow_api {
# block 'options' http method for security reasons if ($request_method = 'OPTIONS') { return 405; } limit_req zone=by_ip burst=10 nodelay; # limit_conn addr 500; |
6. Update the <Nginx config directory>\conf.d\vhost-flow.conf file to add the rate limit for the brute force protection for the following locations:
|
Location
|
Step 1: Find location
|
Step 2: Uncomment the specified line
|
Step 3: Add the specified content to the uncommented line
|
Step 4: Verify the result
|
|---|---|---|---|---|
|
location /Thingworx/Composer/apps/flow
|
location /Thingworx/Composer/apps/flow {
rewrite /Thingworx/Composer/apps/flow/(.*) /$1 break; # limit_req zone=by_ip; # limit_conn addr 500; |
# limit_req zone=by_ip;
|
burst=10 nodelay
|
location /Thingworx/Composer/apps/flow {
rewrite /Thingworx/Composer/apps/flow/(.*) /$1 break; limit_req zone=by_ip burst=10 nodelay; # limit_conn addr 500; |
|
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff2?)$
|
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff2?)$ {
rewrite /Thingworx/Composer/apps/flow/(.*) /$1 break; # limit_req zone=by_ip burst=10 nodelay; expires $expires; |
# limit_req zone=by_ip burst=10 nodelay;
|
—
|
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff2?)$ {
rewrite /Thingworx/Composer/apps/flow/(.*) /$1 break; limit_req zone=by_ip burst=10 nodelay; expires $expires; |
|
location /Thingworx/Lookups
|
location /Thingworx/Lookups {
|
# limit_req zone=by_ip;
|
burst=10 nodelay
|
location /Thingworx/Lookups {
add_header 'Access-Control-Allow-Credentials' 'true'; add_header 'Access-Control-Allow-Methods' 'GET,POST,PUT,DELETE,OPTIONS,HEAD'; add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Length, X-Requested-With, application_uid, application_id, application_api_key, authtoken, Content-Type'; add_header 'Access-Control-Max-Age' '1728000'; if ($request_method = 'OPTIONS') { return 200; } limit_req zone=by_ip burst=10 nodelay; # limit_conn addr 500; |
|
location /Thingworx/WS
|
location /Thingworx/WS {
|
# limit_req zone=by_ip;
|
burst=10 nodelay
|
location /Thingworx/WS {
limit_req zone=by_ip burst=10 nodelay; # limit_conn addr 500; |
|
location /Thingworx/RemoteTunnel
|
location /Thingworx/RemoteTunnel {
|
# limit_req zone=by_ip;
|
burst=10 nodelay
|
location /Thingworx/RemoteTunnel {
limit_req zone=by_ip burst=10 nodelay; # limit_conn addr 500; |
|
location /Thingworx/WSTunnelClient/
|
location /Thingworx/WSTunnelClient/ {
|
# limit_req zone=by_ip;
|
burst=10 nodelay
|
location /Thingworx/WSTunnelClient/ {
limit_req zone=by_ip burst=10 nodelay; # limit_conn addr 500; |
|
location /Thingworx/WSTunnelServer/
|
location /Thingworx/WSTunnelServer/ {
|
# limit_req zone=by_ip;
|
burst=10 nodelay
|
location /Thingworx/WSTunnelServer/ {
limit_req zone=by_ip burst=10 nodelay; # limit_conn addr 500; |
|
location /Thingworx
|
location /Thingworx {
|
# limit_req zone=by_ip;
|
burst=10 nodelay
|
location /Thingworx {
limit_req zone=by_ip burst=10 nodelay; # limit_conn addr 500; |
(Optional) Step 10: Make configuration changes to ThingWorx Foundation and ThingWorx Flow
If needed, proceed to make configuration changes to the ThingWorx Foundation and the ThingWorx Flow services.
This might be required if a patch introduces new configuration settings. Refer to the Release Notes for details on the new configuration settings and the files where they can be used.
Step 11: Reseed the database with the latest updates for ThingWorx Flow
Reseeding the ThingWorx Flow database does not affect any existing user-owned entities, such as workflows or triggers.
1. Launch Command Prompt and navigate to /ThingWorxOrchestration/modules/db_seed.
2. Execute the following command:
flow-deploy migrate -u <Flow DB username> -p <Flow DB password> -s <Flow installation Directory>
On Linux, run the flow-deploy command as a non-root user.
(Optional) Step 12: Deploy custom connectors
|
|
Complete the steps in this section only if you have developed custom connectors using the ThingWorx Flow SDK.
|
1. Ensure that the source code is available on the same system.
2. Navigate to the root directory of the connector and run the flow-deploy connector command.
For more information, see Deploying Connectors.
3. Run the following command to seed the custom connector in the database:
flow-deploy migrate -u <Flow DB username> -p <Flow DB password> -s <Flow installation Directory>
Step 13: Create extra.crt file (8.5.17 and later)
1. Navigate to <Flow installation Directory>\SSL.
Duplicate orchestration.crt file under the same SSL directory and rename it to extra.crt.
For Linux, run the following commands to setup ownership and permission for extra.crt:
a. chown <flow_user>:<flow_user> <Flow installation Directory>/SSL/extra.crt
b. chcon -t httpd_sys_content_t <Flow installation Directory>/SSL/extra.crt
2. Add the system environment variable NODE_EXTRA_CA_CERTS with value <Flow installation Directory>/SSL/extra.crt
3. Open cmd as Administrator on Windows or Terminal on Linux, and run the following commands:
a. pm2 restart all --update-env
b. pm2 save
Step 14: Make ThingWorx Flow work properly when self-signed certificate is used for connected applications (8.5.17 and later)
For any application, either third party applications or other PTC applications that are connected to ThingWorx Flow and configured with a self-signed certificate, the self-signed certificate must be appended to extra.crt file. Follow the steps below to append extra.crt file.
These connected application could be connected to ThingWorx Flow as: ThingWorx Flow connectors (that is Windchill, Integrity, SAP), or as CAS/IDP (that is PingFederate, ADFS, Azure AD) that is used for OAuth communication, or as Load Balancer that is used for HA architecture.
|
|
If the connected application is configured with a single CA-signed certificate, then skip the steps described below. Users will be able to use ThingWorx Flow properly.
However, if the CA-signed certificate has certificate chains and one of its intermediate certificates is a self-signed certificate, follow the steps below for the intermediate self-signed certificate.
|
|
|
For Linux, self-signed certificates must be 2048 bit length.
|
To append the certificate, follow these steps:
1. Navigate to <Flow Installation directory>\SSL and edit extra.crt file.
This file includes the content for all connected applications self-signed certificates.
2. Save the self-signed certificate content in PEM format.
|
|
You can use the Chrome browser to get the self-signed certificate in PEM format (Base 64 encoded), by exporting the self-signed certificate.
|
3. Copy the self-signed certificate content to extra.crt file.
4. Repeat steps 1 to 3 for every connected application’s self-signed certificate.
5. Append and save the content of the self-signed certificate to extra.crt file. Make sure to add a new line between each certificate.
Step 15: Edit ux configuration to have twx_endpoint configured with Nginx host and port (8.5.17 and later)
1. Navigate to <Flow installation Directory>\modules\ux and edit deploymentConfig.json.
2. Replace the value of twx_endpoint to have Nginx host and port instead of ThingWorx host and port
For example: Change "twx_endpoint": "http://localhost:8080/Thingworx" to "twx_endpoint": "https://twxqa.ptcnet.ptc.com:443/Thingworx"
Step 16: Start the services and verify their status
1. Start the services that were stopped in step 1 in the following order:
a. RabbitMQ / rabbitmq.service
|
|
Check the RabbitMQ logs to verify that the RabbitMQ service has completely started before you start the next service.
Windows: /ThingworxOrchestration/modules/RabbitMQ/log/rabbit@{hostname}.log
Linux: /var/log/rabbitmq/rabbit@{hostname}.log
|
b. ThingWorx-Foundation
c. ThingWorx-Flow
d. ThingWorxOrchestrationNginx or nginx
2. Review the ThingWorx Foundation logs and verify that no unexpected errors or warnings occurred during the startup.
3. To verify that ThingWorx Flow is updated correctly, launch Command Prompt as administrator and run the following command:
pm2 ls
The status of the following ThingWorx Flow components must be ‘online’:
◦ flow-api
◦ flow-engine
◦ flow-exchange
◦ flow-lookup
◦ flow-oauth-server
◦ flow-trigger
To view logs of an individual service, run the pm2 logs <service name> command.
(Optional) Step 17: Configure the Rotating Activity Logs
If you are using ThingWorx Flow 8.5.13 or later, you have the option to configure rotating logs.
Procedure to Configure Rotating Log Rules
1. Stop ThingWorxFlow service.
2. Disable the PM2 logging.
In the [installation_dir]\modules, open orchestration.pm2.json file, and edit all the modules to add:
"out_file": "/dev/null",
"error_file": "/dev/null"
"error_file": "/dev/null"
3. Open [Installation_dir]\.pm2\.dump.pm2, copy the value of CONFIG_IMAGE. Using command prompt, set environment variable with the value of CONFIG_IMAGE.
Example: set CONFIG_IMAGE=<CONFIG_IMAGE value>
|
|
For Linux, perform an additional step to reset PM2_HOME variable.
Example:
export CONFIG_IMAGE=<CONFIG_IMAGE value>
export PM2_HOME=/opt/ThingWorxOrchestration/.pm2
|
4. Create a new dump file to add .bak suffix for the original one by running the following commands:
a. pm2 start [installation_dir]\modules\orchestration.pm2.json
b. pm2 save
5. Verify that dump.pm2 file contains only NULL values for below parameters:
For Windows:
▪ "pm_out_log_path": "\\\\.\\NUL"
▪ "pm_err_log_path": "\\\\.\\NUL"
For Linux:
▪ "pm_out_log_path": "/dev/null"
▪ "pm_err_log_path": "/dev/null"
This confirms that the output of pm2 logs is disabled.
6. Run pm2 kill to stop the PM2.
7. Under Installation_dir]\.pm2\pm2.dump\Module_Name, in deploymentConfig.json file, under LOGGING edit the following values.
▪ Add the module name as sibling under the root of JSON.
Example: For engine add: "moduleName":"engine".
|
Parameter
|
Value
|
Description
|
|---|---|---|
|
MAX_LOG_SIZE
|
This must be number of bytes, kb, mb, or gb. When using the units, add 'K', 'M', or 'G' as a suffix, directly following the number. The default value is 10M.
There can be a deviation of about double MAX_LOG_SIZE.
|
This is to set log file size. This is the maximum size of the file after which the logs will rotate.
|
|
MAX_LOG_FILES
|
This value must be a number of days or number of files. The amount of the log files must be slight higher than what is configured. The default value is 10. Add suffix d if setting number of days.
There can be a deviation of about double MAX_LOG_FILES.
|
This is to set maximum number of logs to keep. If the value is not set, logs will not be deleted.
|
|
ROTATION_DATE_PATTERN
|
This must be a string representing the date format according to Moment.js Documentation to be used for rotating. The default value is set to YYYY-MM-DD which means that the log will rotate daily regardless of its size.
|
The meta-characters used in this string will dictate the frequency of the file rotation.
|
A sample code looks like this:
"LOGGING":
{ "ON_PREM": true,
"MAX_LOG_SIZE": "10M",
"MAX_LOG_FILES": "10",
"ROTATION_DATE_PATTERN": "YYYY-MM-DD",
},
{ "ON_PREM": true,
"MAX_LOG_SIZE": "10M",
"MAX_LOG_FILES": "10",
"ROTATION_DATE_PATTERN": "YYYY-MM-DD",
},
▪ Following are the configurable modules: Engine, Exchange, Lookup, Oauth,Trigger, Ux
▪ Separate all log variables using comma.
▪ Ensure that the logs are in correct format: <Log-Type/Name>-<Date in YYYY-MM-DD format>.log.<Log Number>.
8. Start ThingWorxFlow service.
Step 18: Restart the Workflow Subsystem
1. Log in to ThingWorx Foundation.
2. Navigate to > .
3. Click Restart.
Step 19: Verify that functionality is working as expected
Test functionality in ThingWorx Foundation and ThingWorx Flow to verify that they are working as expected. Verify that you can compose workflows in ThingWorx Composer and the Workflow Editor. For example, you can perform the following tasks:
• Log in to the ThingWorx Flow dashboard. To know how to access ThingWorx Flow and ThingWorx Composer, see Accessing ThingWorx Flow and ThingWorx Composer.
• Create and test a trigger in the workflow, if required.
Step 20: Delete the tw-security-common-nodejs_<older-8.x.x> folder
From the /ThingWorxOrchestration/cryptography folder, delete the tw-security-common-nodejs_<older-8.x.x> folder.
(Optional) Step 21: Delete the modules-<older-8.x.x> folder
Once you validate and verify that the update was successful, and flows are running successfully (and the previous release is no longer needed), delete the modules-<older-8.x.x> folder.
You have successfully updated ThingWorx Flow.
|
|
If flow execution in the engine stops abruptly, then follow the steps in Troubleshooting your ThingWorx Flow installation.
|