Remote Services: Appendix for Experts¶

This chapter targets experienced developers, who would like to setup and deploy RS tunnel endpoints in specific ways.

DISCLAIMER: The provided guidelines or software are prototypes. There is NO WARRANTY, to the extent permitted by applicable law. The contained information is intended for testing and piloting purposes and demands adaption and quality validation in the user's respective system context. If Open-Source-Software (OSS) or third-party software is used, the user is responsible for obtaining the requested licenses and for adhering to them. Some of the described approaches might require software components only available to Siemens-internal developers.

Copyright for all given examples and sample codes is with Siemens AG, ©2021, ©2022 and ©2023.

Configuration Guidelines for Firewalls¶

RS establishes interconnected encrypted tunnels between Service Networks and Siemens cloud as well as Device Networks. RS uses common WebSocket Secure (WSS) tunnels and optionally also IPsec tunnels for tunnels between RS and Device Networks. This section provides detailed information on how to setup involved firewalls and optional proxys.

Network administrators use several configuration elements for protecting their networks from outside attacks and for regulating outbound traffic originating inside their networks. So you have to ensure, that firewalls, proxies and DNS are setup properly to allow RS to function under the forementioned protective constraints. The following figure outlines the purpose and impact of the respective components.

The next figure provides an overview of required configurations. Please note, that for sake of simplicity the figure only maps configurations onto an exemplary Device Network, but a Service Network connecting to the other side of RS must be configured similarly!

Capabilities of Remote Services Endpoints¶

RS on Siemens cloud as well as its Service Endpoints or Device Endpoints evolve over time. The table below outlines major enhancements or improvements for assessing required upgrades in a given customer configuration. For further information please refer to the RS-specific release notes. As a general recommendation, only most recent endpoints should be used.

Example: Containerized Device Endpoint¶

Remote Services provide Device Endpoints also as containers, which may be run on container platforms emulating physical devices.

Please download the containerized Device Endpoint and its configuration from RS UI V.2. Then follow below steps and adhere to the outlined and implied file and directory structure.

1. Extract the config.toml file from downloaded config.tar.gz and preserving its folder structure by placing the file into your local data/config/ directory.
2. Load the docker image into docker registry
3. Run the docker image providing it with the required configuration via a volume mount.

Necessary command-line operations for steps 2 and 3 are:

docker load -i "rs-device-endpoint-<device_urn>-<rs_client_version>-x64-docker-img.tar.gz"
docker run -v ./data:/opt/siemens/rsclient/data rs-endpoint-x64-docker-img:<rs_client_version>

Example: Device Endpoint as App for Industrial Edge Devices¶

RS provides a prototype of a Device Endpoint, which may be run on Industrial Edge Devices (IED), so that these may be used for remote access such as IT/OT integration.

For deploying a Device Endpoint as an Industrial Edge App (IEA) running on Industrial Edge Devices (IED) please follow the steps outlined below.

1. Download Industrial Edge Containerized x64 Client "Package" with "Config" from UI V2.
2. Extract .app file from the compressed rs-device-endpoint-<device_urn>-<rs_client_version>-x64-industrialedge-app.tar.gz file.
3. Extract config.toml from the compressed rs-device-config-<device_urn>-x64-industrialedge-app.tar.gz file.
4. In the Industrial Edge Management, perform the below steps:
   • Login to Industrial Edge Management.
   • Create Industrial Edge Device.
   • Download Industrial Edge Device Config File and Upload to IE Device.
5. In Industrial Edge Management, perform the below steps:
   • Navigate to the Catalog tab.
   • Import the downloaded Industrial Edge Containerized x64 Client App.
   • Load config.toml file and install Application to Industrial Edge Device.
   • Check the Job Status while Config File and Application is loading.
6. Check the Industrial Edge on Remote Services UIv2.

Example: Manual Update of Remote Device Endpoints on Linux®¶

In some cases you might want to update an existing Device Endpoint with a newer version and without traveling to the Site in which it resides. If this particular Device Endpoint can still be connected to via RS, the following process outlines how to update it from remote.
In stage 1 we install an auxiliary endpoint on a Device in parallel to the existing one. In stage 2 we connect to the Device via the auxiliary endpoint and remove the outdated tunnel and endpoint. We also install the new endpoint. Final stage 3 performs the switch-over to the new endpoint and removal of the auxiliary endpoint and its tunnel.

Example: Linking Data Assets and Remote Services Devices¶

Many Siemens cloud apps are data-centric and thus use an Asset Manager, which supports inheritance of data properties. However, RS enables network-2-network access between Apps or Data or Devices without any information on data structures and thus uses a Device Manager.

For integration purposes it might be necessary to link an apps' Assets to an RS Device, so that RS functionality can be launched for a particular Asset. This section outlines, how such links can be created in MindSphere Asset Manager.

Preparation of the App Using the Asset Manager

1. Make sure, that the Asset structure is loaded correctly into the Asset Manager app on your tenant's launchpad so that Assets are separated in tenants and that these are associated with their respective customers.
   
2. Use the Siemens cloud Settings app and grant all users access rights to the particular app and scope, that you want to link to RS. For instance, use "Edit direct assignments", select a user of sample app "Asset Health & Service Hub" (AHSH) and search for "ahsh":
   • For an AHSH Team Lead (TL) role, assign the user role teamlead.
   • For an AHSH Team Member (TM) role, assign the user role teammember.
   • For an AHSH Site Owner (SO), assign the user role siteowner.
3. Then clear the search bar and look at the standard roles of this user at the top of the screen:
   • If the Asset you want to link to a RS Device is part of a global tenant, the SO needs to be a global user
   • If the Asset you want to link to a RS Device is part of a subtenant, you need to assign the SO to this subtenant
   • This is important as a SO can only use Assets that are in the SO’s tenant and the same applies for RS-related functionality. Otherwise you might experience the AHSH TL/TM users trying to connect to RS, but the AHSH role won't get notified accordingly.

Preparation of Remote Services

1. Linking of Assets and RS functionality typically requires the RS functionality to be pre-configured. Please use the mechanisms outlined in this user documentation for setting up device-specific connections and Protocol Applications plus required user access rights.
2. For instance, a particular Siemens cloud user must be granted access rights for the app, whose assets shall be linked, AND for the RS app.
3. For instance, you might also want to enable the option "AuthRequired" in the setup of the Protocol Application to request a handshake with another app (such as AHSH) or RS user, before RS will establish a connection. For details please see section RS Advanced Connections.

Example: Install Device Endpoint as a Daemon Process on Linux®¶

Installing a Device Endpoint as a daemon process can be used to make that endpoint subject to autostart - so it will be launched during a Device's boot process not requiring any user to be logged in.

Prerequisites:

• Script files (setup.sh and uninstall.sh) are needed for the daemon process installation
• OpenSSL 1.1.x must be installed on the target Device (OSS licensing and clearing applies)

1. Download a Device Endpoint from the RS UI and extract it to the directory that you want to install.
   
2. Copy the script files (setup.sh and uninstall.sh) to the same directory as shown above (make sure to copy them from the "Debian" or "RHEL" directories as accordingly to your OS)
   
3. RS-client file is the runner of the Device Endpoint, so it needs to be executable; after extracting the files enter the below command from the terminal: chmod +x RS-client
   
4. "License Agreement" needs to be accepted via running the Device Endpoint once before installing it as a daemon process. Enter "./rs-client" in the terminal, accept the license agreement via and press . Then the Device Endpoint will run.
   

   ./RS-client
   Use of RS Tunneling Service Client Requires Acceptance of the Following file: RS Connectivity Terms.pdf
   DO YOU ACCEPT THE TERMS OF THIS LICENSE AGREEMENT? (Y/N): 
   Y
   

5. Terminate the running Device Endpoint.
   
6. To install the Device Endpoint as a daemon process, related script files need to be set as executable; enter the following command from the terminal:
   

chmod +x setup.sh uninstall.sh

1. (Optional) If a proxy is needed; you may define this in an environment variable (replace {host} and {port} below with the actual values):
   

export https_proxy={host}:{port}

1. Enter "./setup.sh" as a super user to start the Device Endpoint and enable it as a daemon process on Linux:
   

./setup.sh

1. For quick verification of the initialization of the Device Endpoint as a daemon process, its log file might be helpful. New boot-up logs will be appended to this log file (log file will be created automatically if it didn't exist before).
   
2. To verify it from the OS, below command should displayed it as "active"
   

systemctl is-active RS-client

1. For de-installation run the provided uninstall script as a super user, which will stop the Device Endpoint and remove the related daemon entry on Linux
   

./uninstall.sh

Sample Script Files for Debian¶

setup.sh

wd=$(pwd)
sudo echo "

[Unit]
Description=rs-client

[Service]
WorkingDirectory=$wd
Environment="https_proxy=$https_proxy"
ExecStart=$wd/rs-client
Restart=always

[Install]
WantedBy=multi-user.target
" > rs-client.service

sudo cp RS-client.service /etc/systemd/system/RS-client.service
sudo systemctl daemon-reload
sudo systemctl enable rs-client
sudo systemctl restart rs-client
sudo systemctl status rs-client

uninstall.sh

sudo systemctl stop rs-client
sudo rm -f /etc/systemd/system/rs-client.service
sudo systemctl daemon-reload

Sample Script Files for RHEL¶

setup.sh

wd=$(pwd)
sudo echo "

[Unit]
Description=rs-client

[Service]
WorkingDirectory=$wd
Environment="https_proxy=$https_proxy"
ExecStart=$wd/rs-client
Restart=always

[Install]
WantedBy=multi-user.target
" > rs-client.service

sudo cp rsS-client.service /etc/systemd/system/rs-client.service
sudo systemctl daemon-reload
sudo service rs-client restart
sudo service rs-client status

uninstall.sh

sudo service rs-client stop
sudo rm -f /etc/systemd/system/rs-client.service
sudo systemctl daemon-reload