How to get started with Cloud Remote Access for Cumulocity IoT
Introduction
Last year, I published an article roughly describing the Cloud Remote Access Feature of Cumulocity IoT.
Since then I received a lot of requests on how to use it in detail and decided to write another knowledge base article going into detail and covering all of the requests I received. So the following questions should be addressed in this article:
- What is the Cloud Remote Access Feature?
- Which agents support it / How can an agent support cloud remote access?
- How can I have a Web SSH / VNC Connection my Device?
- How can I make use of the Passthrough configuration?
- What are the benefits of using the Passthrough configuration instead of Web SSH / VNC?
- How can I connect to a device using Passthrough configuration and the local proxy?
Let’s get started with an overview about the Cloud Remote Access Feature!
Cloud Remote Access
The Cloud Remote Access Feature of Cumulocity IoT allows you to simply connect to your devices using SSH, Telnet, VNC or any other TCP-based protocol. The good thing about that is you don’t need any VPN tunnel by getting the same grade of security a VPN tunnel would provide. This is achieved by having a microservice running in Cumulocity IoT tunneling all protocols through a web socket connection and taking care of the authentication.
When using the SSH, Telnet or VNC configuration of the Cloud Remote Access, the tunneled connection is terminated within the Cloud Remote Access Microservice, and the output is visualized in a web terminal in a browser using xTerm.js
Here is an example how this looks like in the browser:
Sometimes it is not sufficient that we are limited to a web terminal and that the Cloud Remote Access Microservice terminates the connection. Therefore we have introduced the “Passthrough” Configuration.
As you can see from the sketch above in Passthrough configurations, no clients of the microservice are used. Instead it forwards the packets to another web socket channel where a local proxy is running. The local proxy connects to the web socket provided by the microservice, provides TCP sockets where native clients can be connected and of course tunnels the packets receiving from the clients through the web socket and vice versa.
The logic on the device side is always the same.
So let’s sum this up:
- If you want to have a web terminal using SSH, telnet or VNC, you can achieve that with the according provided configuration within the Cumulocity IoT platform
- If this is not sufficient and you want to use native clients, you can make use of the Passthrough configuration in combination of a local proxy.
- In both scenarios, you just need an agent implementing the Cloud Remote Access feature
Cloud Remote Access enabled agents
There are some agents available which are already implementing the Cloud Remote Access feature on device side.
Cloud Remote Access Agent
If you want to try out the Cloud Remote Access Feature and nothing else, the Cloud Remote Access Agent is the one you should go for. The good thing is it also contains a python module, which can by easily integrated into your python agent, enabling the cloud remote access feature only in a few steps. Have a look here for more details! The python package is also available at pypi
Also the thin-edge.io provides an example to add the cloud remote access to the thin-edge. It is actually using the module of the Cloud Remote Access Agent.
Contribute to thin-edge/thin-edge.io_examples development by creating an account on GitHub.
Device Management Reference Agent
The device management reference agent has been explained in detail in one of my last articles: https://tech.forums.softwareag.com/t/getting-started-with-cumulocity-iot-device-management
The cloud remote access module from the agent is part of this agent as it leverages docker containers to quickly create new devices and it comes with a preconfigured SSH & VNC Server. It is one of the fastest options to try out Cloud Remote Access as it provides a docker image on docker hub and a package on pypi.
Cumulocity Linux Agent
The Linux Agent is a lightweight agent implemented in C for linux operated devices. It also has implemented the Cloud Remote Access Feature.
c8yMQTT Raspberry Pi Sense Hat Agent
This agent is very similar to the Device Management Reference Agent. It is implemented in Python and supports the Cloud Remote Access Feature. It is mainly developed for the raspberry pi in combination with a sense hat.
Step-by-step to establish a Web SSH/VNC connection
As the Device Management Reference Agent has everything built in, in this guide I will use this one. Using the other agent requires additional steps like setting up a SSH and VNC Server on the Device.
NOTE: This is only used for demonstration purposes. Of course you can use any agent of the list above or custom agent to follow the steps below but need to set up additional components manually.
Prerequisites
- Docker must be installed
- Git or any other git client of your choice
- A Cumulocity (Trial) tenant with Cloud Remote Access Feature enabled.
NOTE: The Cloud Remote Access Feature is an additional feature and must be assigned to your Tenant. Please ask your contact or administrator to add it to your tenant
1. Start the DM-Agent
This is only needed if you don’t have any agent running already. Please go on with step 2 if you already have an agent running supporting Cloud Remote Access.
To see the following steps, please visit the Software AG Tech Community Knowledge Base article:
Originally published at https://tech.forums.softwareag.com on July 28, 2022.
