Skip to content

MindSphere Remote Services - Appendix for Experts

This chapter targets experienced developers, who would like to setup and deploy MRS 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 delivered 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 3rd-party software is used, the user is responsible for obtaining the requested licenses and for adhering to them.

Copyright for all given examples and sample codes is with Siemens AG and MindSphere, (C) 2021 and 2022.


Configuration Guidelines for Firewalls

MRS establishes encrypted tunnels between Service Networks and MindSphere as well as Device Networks. MRS uses common WebSocket Secure (WSS) tunnels and optionally also IPsec tunnels for tunnels between MRS and Device Networks. This section provides detailed information on how to setup involved firewalls and optional proxys. Note: IPsec routers may demand additional settings depending on your company's policies and configurations, so they are not contained here. Indications could be derived from the router setup described in section Advanced connections.

Overview on MRS network and firewall setup

MRS network and firewall setup

Firewall settings

Outbound traffic - Destination CIDR range for MRS, typically * or 0.0.0.0 (but depends on security guidelines) - Destination server socket port 443 - Source CIDR range for set of MRS endpoints or IP of proxy server, e.g. 192.168.x.y/16 - Source MRS endpoint port range, typ. ≥ 49152 (assigned by Operating System) - Protocol WebSocket Secure (WSS)

Inbound traffic - Source CIDR range for MRS, typically * or 0.0.0.0 (but depends on security guidelines) - Source MRS connection socket port range, typ. ≥ 49152 (assigned by Operating system) - Destination CIDR range for set of MRS endpoints or IP of proxy server, e.g. 192.168.x.y/16 - Destination MRS endpoint port range, typ. ≥ 49152 (assigned by Operating System) - Protocol WebSocket Secure (WSS)

Proxy Server configuration (if used)

  1. Protocol WebSocketSecure (WSS) must be permitted
  2. Ensure that connection idle timeout is ≥ connection idle timeout in MRS
    • until 06/2022: WSS timeout not configurable in MRS yet
    • from 07/2022: WSS timeout configurable in MRS Protocol Application
  3. Whitelisting of URLs specific to MRS Endpoint ("client")
    • https://connectivity.eu1.vpnrts.mindsphere.io/uaa/oauth/token
    • https://s3restriction.eu1.vpnrts.mindsphere.io:443
    • https://wss.eu1.vpnrts.mindsphere.io:443/mts/
    • https://wss.eu1.vpnrts.mindsphere.io:443/ccf/
  4. Whitelisting of domain for overall MindSphere access (e.g. via browser)
    • *.eu1.mindsphere.io

Proxy Server settings for MRS Endpoint (if used)

  • Windows ® - Operating System proxy settings, or environment variables
  • Linux ® - environment variables only

Notes - Above setup outlines setup between MRS on MindSphere and a Device Network. It should be applied similarly for setup between MRS on MindSphere and a Service Network - As per Terms & Conditions for download, MRS Endpoints must reside in whitelisted countries as per European or German regulation - Information on Operating System ports can be obtained from Internet sources such as Internet-Assigned Numbers Authority (IANA)



Example: Linking MindSphere Assets and MRS Devices

Most MindSphere apps are data-centric and thus use MindSphere Asset Manager, which supports inheritance of data properties. However, MRS enables network-2-network access between 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 MRS Device, so that MRS functionality can be launched for a particular Asset. This section outlines, how such links can be created in MindSphere Asset Manager.

  1. Preparation of the app using the Asset Manager
  2. Make sure, that the Asset structure is loaded correctly into the Asset Manager app on the MindSphere launchpad so that Assets are separated in tenants and that these are associated with their respective customers.
  3. Use the MindSphere Settings app and grant all users access rights to the particular app and scope, that you want to link to MRS. For instance, use "Edit direct assignments", select a user of sample app "AHSH" and search for :
  4. For an AHSH Team Lead (TL) role, assign the user role ‘teamlead’.
  5. For an AHSH Team Member (TM) role, assign the user role ‘teammember’.
  6. for an AH&SH Site Owner (SO), assign the user role ‘siteowner’. 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 MRS Device is part of a global tenant, the SO needs to be a global user
    • If the Asset you want to link to a MRS 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 MRS-related functionality. Otherwise you might experience the AHSH TL/TM users trying to connect to MRS, but the AHSH role won't get notified accordingly.
  7. Note: please ensure, that user-specific information such as email-address is kept consistent across the MindSphere tenant, the to-be-linked app (e.g. AHSH) and MRS.

  8. Preparation of MRS

  9. Linking of Assets and MRS functionality typically requires the MRS 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.
  10. For instance, a particular MindSphere user must be granted access rights for the app, whose assets shall be linked, AND for the MRS app.
  11. 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 AH&SH), before MRS will establish a connection.
  12. Note: When you create a new MRS Device (via "System Management / Region" in MRS UI V.1) please fill-in the MindSphere Asset Id (taken from Asset Manager) of the Asset you want to link your Device to!

  13. Options for using Asset-2-Device links within a MindSphere app

  14. The app, that wants to link an Asset to MRS-provided functionality (such as a connection) must maintain a list of Asset-2-Device associations
  15. As an alternative, the app might have access to the MRS Device Manager API, so that it could access the ID of the associated MindSphere Asset from there.


Example: Containerization of Device Endpoint

This section outlines how to transform a MindSphere Remote Services (MRS) Endpoint's (formerly known as MRS Client) download tar.gz file into a Docker container.

Prerequisite file and directory structure

It is recommended to create the following directory structure and place the sample files as outlined below in it:

* <base_dir> // base directory
  * docker-compose.yaml // docker-compose file providing container image name, build location etc.
  * mrs-client // folder with all information to build the MRS Endpoint container
    * cfg-data // folder to place the MRS Endpoint's tar.gz file in 
    * lib // OpenSSL libs and dependencies
      * libssl1.1_1.1.0l-1_deb9u1_amd64.deb
      * openssl_1.1.0l-1_deb9u1_amd64.deb
    * Dockerfile // build file for the container image

Note: The <...> notation is used for metadata level here - please replace by appropriate concrete names. Indentation reflects the nested directory and file structure. '//' is used for comments. Please leave other names as given, in order for the examples to work.

Overview

This example requires an initial download of an MRS Endpoint tar.gz file from the MindSphere Remote Services (MRS) backend system. It contains both the MRS Endpoint code, as well as its required configuration. During the build process of the container image, the provided tar.gz file will be copied into the container image. Please make sure, that there is only one tar.gz file in the <base_dir>/cfg-data folder at any point in time.

Preparation of the configuration (customization of the Docker container image)

  • Onboard the Device as MindSpere Remote Services (MRS) device in MindSphere Remote Services backend
  • Download the MindSphere Remote Services (MRS) Endpoint's tar.gz package
  • Copy the tar.gz file to the <base_dir>/mrs-client/cfg-data folder, according to the directory structure above.

It ensures, that the provided MRS Device Endpoint download .tar.gz package containing MRS Endpoint code and configuration will be copied to the container image.

The tar.gz file contains everything what is needed for customization of the container, i.e. MRS Endpoint code plus MRS Endpoint configuration.

Building the container image

In this project, the Docker Compose framework is used to build the container image (as Docker development environment). In the Docker development environment, execute:

  • docker-compose build --no-cache

This command will build the container image. The --no-cache option ensures a fresh build, without using any cached Docker images along the container build history, but will take more time for the build process.

  • docker-compose up

This command will start up the container image in the Docker development environment.

Using the container image outside the Docker development environment

For use of the built container image without the Docker Compose framework (i.e., starting the container image without the Docker Compose framework used here as Docker development environment), start the container with the following command:

docker run -itd <container_image_ID> /bin/sh -c "cd /opt/siemens/mrs-client; ./mrs-client --approve-connectivity-terms"

By this command, when the container is started, the MRS Client in the container is also launched. Please note, that the MRS Endpoint in both variants will be invoked with implict approval of Terms & Conditions to use it.

Sample docker-compose.yml file

version: "2.4"

services:
  mrsclient:
    container_name: <container_image_name>
    build: ./mrs-client
    image: <container_image_name>:<container_image_version>
    restart: "no"
    command: /bin/sh -c "cd /opt/siemens/mrs-client; ./mrs-client --approve-connectivity-terms"
    platform: linux

Sample Dockerfile

The provided software uses OSS components demanding OSS clearing: - libssl1.1_1.1.0l-1_deb9u1_amd64.deb, download source: http://ftp.debian.org/debian/pool/main/o/openssl/ - openssl_1.1.0l-1_deb9u1_amd64.deb, download source: http://ftp.debian.org/debian/pool/main/o/openssl/ These used OSS components are an extension of the Debian 9 (buster:slim) Docker container baseline image, and are needed on Operating System level to execute the software, but are not inherent part of the software itself. Please download newer versions, if available.

# Use lightweight Debian 9 container image
FROM debian:stretch-slim

# Add libssl 1.1 support to container image
RUN mkdir -p /opt/siemens/lib
COPY ./lib/libssl1.1_1.1.0l-1_deb9u1_amd64.deb /opt/siemens/lib
COPY ./lib/openssl_1.1.0l-1_deb9u1_amd64.deb /opt/siemens/lib
RUN dpkg -i /opt/siemens/lib/libssl1.1_1.1.0l-1_deb9u1_amd64.deb
RUN dpkg -i /opt/siemens/lib/openssl_1.1.0l-1_deb9u1_amd64.deb

# Create folder structure in container for client code and configuration
RUN mkdir -p /opt/siemens/mrs-client
RUN mkdir -p /opt/siemens/cfg-data

# Installation of MRS Client and configuration
COPY ./cfg-data /opt/siemens/cfg-data
RUN tar xvzf /opt/siemens/cfg-data/*.tar.gz -C /opt/siemens/mrs-client
RUN chmod +x /opt/siemens/mrs-client/mrs-client


Example: Deploying containerized Device Endpoint on (Industrial) Edge Devices

This section outlines, how to create a containerized MRS Device Endpoint, that can be deployed on Edge Devices. The steps for containerizing a Device Endpoint and for deploying it as an Industrial Edge App are outlined in the sketch below.

This prototype documentation needs an "Alpine Linux-based MRS Device Endpoint" project as a prerequisite, in order to build the actual Industrial Edge application providing the MRS Endpoint. It first builds a MindSphere MRS Device Endpoint installed in a very lightweight Linux production container image.

The MRS Device Endpoint container image built by the referenced "Alpine Linux-based MRS Device Endpoint" MindSphere-internal project contains both the Endpoint plus its associated specific configuration. For building the container image, there are two options to build it: either including an Endpoint configuration or excluding it. In the first case, the MRS Endpoint configuration has to provided statically in the container image during its build process. In the latter case, the MRS Endpoint configuration has to provided dynamically with container installation (deployment). The latter approach has the advantage of needing to build an Endpoint container image only once and individually configure it for each specific target Edge Device.

Note: for further information please reach out to your MindSphere contact person.

Steps for deploying MRS Device Endpoint as Industrial Edge App

The following OSS components are currently being used and should be subject to OSS and license clearing: - Alpine Linux 3.15.0 as operating system of the Endpoint container. It allows for a small memory footprint, suggested download: https://hub.docker.com/_/alpine/?tab=tags - OpenSSL as a static link library linked to the Endpoint, suggested download site: https://www.openssl.org/source/, source code tar ball: https://www.openssl.org/source/openssl-1.1.1m.tar.gz - Docker environment including Docker Compose, which is leveraged for orchestration of Industrial Edge applications constituted by multiple Docker containers each having individual application-specific purposes. In this prototype project, the Industrial Edge application is made up of one container only, nevertheless Docker Compose is required.

Building an Industrial Edge application demands the 3rd-party Industrial Edge framework by Siemens Digital Industries (DI). We assume readers to be familiar with its key workflows and components shown above.

The central element to build an application for the Siemens Industrial Edge framework is an initial docker-compose.yaml file. This file is a descriptor file for managing the container by the Docker Compose framework. It specifies e.g. the container's build-, network-, and volume configuration, its restart behavior and start-up configuration. The build configuration in the docker-compose.yaml file refers to a Dockerfile.

In order to build and properly set up this Industrial Edge framework application container image, there is the need for a volume for provisioning of configuration data to the Industrial Edge application. The volume is part of the Industrial Edge application project. It hands over the configuration to the Industrial Edge application when the container image will be instantiated at runtime.

Configuration of remote access API of the Docker engine

In order for the tools of the Industrial Edge framework to remotely control the Docker engine, an API for remote access to the Docker engine (i.e. Docker daemon) has to be configured on its hosting machine. Note: As the Docker API is not protected and execution of remote commands is on root level, it is strongly recommended to host the Docker environment in a network that is exposed locally only. Example: host the Docker environment on a VM in a private network (local host network), which is only reachable from the VM environment host.

For activation of the remote access API of the Docker engine, please do the following: add the following line to the Docker engine configuration file /etc/docker/daemon.json:

{
  <...>,
  "hosts": ["tcp://0.0.0.0:2375", "unix:///var/run/docker.sock"]
}

After editing, restart the Docker service, or simply reboot the Docker host. Don't forget to add a comma in the previous line and/ or after the inserted line, depending on the position it is added. For sanity checks, execute the following on the client side (e.g. environment hosting IEAP):

docker -H tcp://<IP_address_of_the_Docker_host>:2375 info

Alternatively, for permanent use, set the remote Docker host in an environment variable:

docker -H tcp://<IP_address_of_the_Docker_host>:2375 info
export DOCKER_HOST=tcp://<IP_address_of_the_Docker_host>:2375
echo $DOCKER_HOST
docker info

In both alternatives, the referenced Docker engine should be displayed as being on the remote host.

As an additional sanity check execute the following command on the Docker host itself,: sudo netstat -lntp. The result should look similar to this:

Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name
tcp        0      0 :::2375                 :::*                    LISTEN      2821/dockerd

This configuration should work on Alpine Linux.

Building the Alpine Linux-based container image hosting the Device Endpoint

The referenced "Alpine Linux-based MRS Device Endpoint" project has to be executed, and it is a prerequisite to build the Industrial Edge application providing the MRS Endpoint. It builds a MindSphere MRS Device Endpoint installed in a very lightweight Linux production container image. This allows for fast downloading, fast container startup, as well as provides a very resource-saving deployment in any container hosting framework. It is hence very well-suited as baseline container image for an Industrial Edge application and its deployment on resource-constrained edge devices.

The MRS Device Endpoint container image built by the referenced "Alpine Linux-based MRS Device Endpoint" project contains both the Endpoint plus its associated specific configuration. For building the container image, there are two options to build it: either including an Endpoint configuration or excluding it. Including the Endpoint configuration means static integration of the endpoint configuration into the container image. Excluding the Endpoint configuration means, that is has to be provided dynamically when starting the Industrial Edge application.

After completion of the build process of the Device Endpoint container image, it should be available in the in the container registry of the Docker environment, which is made available to the Industrial Edge framework.

Onboarding of the IED device to IEM

Use the Industrial Edge Manager (IEM) for the following steps: 1. create new edge device 2. set edge device information 3. set edge device network information 4. set edge device proxy settings

Building the Industrial Edge framework application for MRS Device Endpoint

The overall process to build an Industrial Edge (IE) framework application is as follows: 1. Register the Docker engine in IEAP, if not done yet - click on + Docker Engine - Select HTTP as protocol, and specify the IP address of the Docker engine and its port (2375). Don't tick TLS. A successful registration of the Docker engine is reflected on the left side of the command band, showing its IP address. 2. Create a standalone application in IEAP - Click on the + Create button in the Standalone Applications panel, in order to create a new Standalone Application as basis for the Industrial Edge application being to built. - Most important is the field Repository Name, which specifies the name of the Industrial Edge application container image (i.e., its repository name), and which will be provided by the container registry of the connected Docker engine. Please note, that the referenced container image name needs to be unique across the Industrial Edge framework (!), even if the same container image shall be used for another instantiation of the same Industrial Edge framework application. - also select an appropriate tile icon to represent the Standalone Application 3. Assign a version to the standalone application using IEAP - click on the tile for the new Standalone Application, which you created in the previous step. Next, click the + Add New Version actions button - in the next dialog, specify the version of the Docker Compose .yaml file, that is required to describe the orchestrated Industrial Edge application (which might consist of several individual Docker container images, each representing a service to be orchestrated as part of the Industrial Edge application). Take the version from the docker-compose.yaml file, that is to be imported in the subsequent step, e.g. 2.4
- next, click on the Import YAML button in the panel of the selected standalone application - Note: A docker-compose.yaml file specifies the various services it will orchestrate by means of several services sections. For each service, it specifies a container image. For the MRS Device Endpoint as an Industrial Edge application, there is only one service to orchestrate, namely the containerized MRS Client. Thus, the docker-compose.yaml file needs to specify only one services section, the one for the MRS Endpoint. Please ensure, that the referenced container image in the MRS Endpoint service section in the docker-compose.yaml file specifies a valid container image (i.e. repository name and tag), that the container registry of the Docker engine does provide. - edit the docker-compose.yaml file and optionally remove the /publish and /cfg-data folders - set the memory limit of the Industrial Edge application, e.g. 128MB, which is suitable for the MRS Endpoint - save your changes 4. Create an IEM project for the IE application - don't proceed with "Next" button, since you want to import the application of this project from a standalone application in IEAP in a subsequent step - you will have to provide a specific application and a specific version in the next step - Note: Importing the standalone application to the project does NOT import a version as well. This has to happen separately in the step after the import of the standalone application. 5. Import the standalone application from IEAP to the IEM project (upload) - connect the IEAP to the IEM by clicking on the Go online button in the command ribbon of IEAP - navigate to the Standalone Applications pane in IEAP and select the Standalone Application (tile) and check the Versions pane - Use the small icon with a sloping arrow under Actions to import the selected Version (Version is selected by the respective row) of the application to the IEM. In the event that the sloping arrow is not displayed, check whether IEAP is connected to the IEM . - If successful, there will be a new tile representing the application. 6. Import the version of the standalone application to the IEM project - To provide a Version for the imported Application in the IEM project, go to IEAP and check the My Projects pane. The Application newly imported to the IEM project should be displayed there. If it is not displayed, select the respective project from the drop down selector in the command band of the My Projects pane. - Click on the project tile in the My Projects pane. The Application's Versions pane shows up, and in the Status column, there is a Start Upload button. Click this button to complete the Version import of the Application to IEM. 7. Deploy the container plus its configuration to an IED - Click on the Install button in the Actions column of the reviewed Version of the Application. - In the upcoming dialog please ignore the provisioning of a Configuration for this Industrial Edge application, if the MRS Endpoint configuration was statically built-in to the MRS Endpoint container image. It is not needed in this case, because the MRS Device Endpoint Alpine Linux container image already does contain its configuration. So, simply click the Next button, to select the IED this Industrial Edge application is to be deployed upon. - Otherwise, if the MRS Endpoint container image does not contain a Configuration, it has to be dynamically provided now, when the MRS Endpoint Industrial Edge application will be installed. Provide a configuration .tar.gz file downloaded from the MRS backend for the respective Device Endpoint in the aforementioned upcoming dialog, and click the Next button, to select the IED this Industrial Edge application is to be deployed upon.
- Select the device to install the Industrial Edge application upon. Click the Install Now button. Allow the installation, although the installation goes along with some warnings (signature check not successful, host network check not successful). The Industrial Edge application is installed on the selected IED. 8. Application lifecycle control for installed IE applications - navigate to My Installed Apps in the left-side navigation pane of the IEM - It gives a tile overview of installed Industrial Edge applications on every registered IED. Clicking on an application tile shows displays further details and a command ribbon for lifecycle control (e.g. start, stop, uninstall) of the respective IE application.



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)

Prequisites for Device Endpoint as a Linux daemon

  1. Download a Device Endpoint from the MRS 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. mrs-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 mrs-client
  4. "License Agreement" needs to be accepted via running the Device Endpoint once before installing it as a daemon process. Enter "./mrs-client" in the terminal, accept the license agreement via and press . Then the Device Endpoint will run. ./mrs-client ```Use of MRS Tunneling Service Client Requires Acceptance of the Following file: MRS 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
    7. (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}
    8. Enter "./setup.sh" as a super user to start the Device Endpoint and enable it as a daemon process on Linux:
    
    ./setup.sh
    9. 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).
    10. To verify it from the OS, below command should displayed it as "active"
    
    systemctl is-active mrs-client
    11. 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=MRSclient

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

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

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

**uninstall.sh**
sudo systemctl stop mrs-client sudo rm -f /etc/systemd/system/mrs-client.service sudo systemctl daemon-reload
## Sample script files for RHEL

**setup.sh**
wd=$(pwd) sudo echo "

[Unit] Description=MRSclient

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

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

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

**uninstall.sh**
sudo service mrs-client stop sudo rm -f /etc/systemd/system/mrs-client.service sudo systemctl daemon-reload ```



Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.


Last update: July 29, 2022