How to get started with Cloud Remote Access for Cumulocity IoT
Tags: iot, cumulocity, deviceconnectivity, iotedge
Published: 2022-07-26 13:37:36

---
title: How to get started with Cloud Remote Access for Cumulocity IoT
published: true
date: 2022-07-04 09:30:25 UTC
tags: IoT, Cumulocity, DeviceConnectivity, IoTEdge
canonical_url: https://tech.forums.softwareag.com/t/how-to-get-started-with-cloud-remote-access-for-cumulocity-iot/258446
---
Author: Stefan Witschel
 
## Introduction

Last year I published an [article](https://tech.forums.softwareag.com/t/remote-connect-to-your-devices/239639) roughly describing the [Cloud Remote Access Feature](https://cumulocity.com/guides/10.13.0/cloud-remote-access/using-cloud-remote-access/) of Cumulocity IoT.

Since then I received a lot of requests 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:

1. What is the Cloud Remote Access Feature?
2. Which agents support it / How can an agent support cloud remote access?
3. How can I have a Web SSH / VNC Connection my Device?
4. How can I make use of the Passthrough configuration?
5. What are the benefits of using the Passthrough configuration instead of Web SSH / VNC?
6. 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](https://cumulocity.com/guides/10.13.0/cloud-remote-access/using-cloud-remote-access/) 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 that 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](https://xtermjs.org/)

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/0/3/0335e094fa8a70a6a2a963afb438c1c0569a583f_2_690x241.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/0/3/0335e094fa8a70a6a2a963afb438c1c0569a583f.png "image")

Here is an example how this looks like in the browser:

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/c/7/c7b2a76fcc6dc98e683a35e6fbcabaafe49e2079_2_690x258.jpeg)](https://aws1.discourse-cdn.com/techcommunity/original/3X/c/7/c7b2a76fcc6dc98e683a35e6fbcabaafe49e2079.jpeg "image")

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.

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/0/c/0cdaff7588644a368bdc2df40409a99eb6606961_2_690x236.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/0/c/0cdaff7588644a368bdc2df40409a99eb6606961.png "image")

As you can see from the sketch above in Passthrough configurations no clients of the microservice are use. 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 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 but nothing else the [Cloud Remote Access Agent](https://github.com/SoftwareAG/cumulocity-remote-access-agent) is the one you should go for. The good thing about it is that it also contains a python module which can by easily integrated into you python agent enabling the cloud remote access feature only in a few steps. Have a look [here](https://github.com/SoftwareAG/cumulocity-remote-access-agent#embed-device-proxy-module) for more details! The python package is also available at [pypi](https://pypi.org/project/c8y-device-proxy/)

[Cumulocity Remote Access Agent](https://github.com/SoftwareAG/cumulocity-remote-access-agent)

### [thin-edge.io](http://thin-edge.io)

Also the [thin-edge.io](http://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.

[thin-edge.io remote access](https://github.com/thin-edge/thin-edge.io_examples/tree/main/remote-access)


### 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](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](https://hub.docker.com/r/switschel/c8ydm) and [a package on pypi](https://pypi.org/project/c8ydm/).

### 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.

[Cumulocity Linux Agent](https://github.com/SoftwareAG/cumulocity-agents-linux)

### 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.

[Cumulocity IoT Python3 Agent](https://github.com/SoftwareAG/c8yMQTT)

## 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 other agent requires additional steps like setting up a SSH and VNC Server on the Device.

> **NOTE:** This is only used for demonstration purpose. 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](https://www.docker.com/) must be installed
- [Git](https://git-scm.com/) or any other git client of your choice
- A Cumulocity [(Trial)](https://signup.softwareag.cloud/#/basic?product=cumulocity&utm_referrer=TechCommunity)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.

First of all we have to have the agent started. Normally this is done by just running ./start.sh or start.bat once you’ve cloned the repo and registering the device using the container id in your tenant. For more details check this guide. [Getting Started with Cumulocity IoT Device Management](https://tech.forums.softwareag.com/t/getting-started-with-cumulocity-iot-device-management/256401#steps-to-follow-6)

### 2. Assign Cloud Remote Access roles to users

To use the Cloud Remote Access functionality we have to add the existing roles to the users who should be allowed to use this feature. As this feature is pretty powerful (and sometimes destructive) it should be only assigned to experts who exactly know what they are doing.

Go to **Administration** → **Roles** → **Add global role** (on top right).  
Give it the name “Cloud Remote Access Role” and make sure to check the “Admin” permission for “Remote Access”.

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/6/6/66cc5f5bd6b3cfa71eb553a0d38ae66ff59c52a5_2_690x390.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/6/6/66cc5f5bd6b3cfa71eb553a0d38ae66ff59c52a5.png "image")

Next go to **Users** → select your user and assign the just created role to it. Don’t forget to save your user.

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/5/7/57ad306cfea3abd79af7134f60bf1934756c04ad_2_690x180.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/5/7/57ad306cfea3abd79af7134f60bf1934756c04ad.png "image")

> **NOTE:** If you don’t see the “Remote Access” Tab in Device Management most probably it is because you haven’t assigned the role to your user

### 3. Configure Web SSH Remote Connection

Now that we have the required permission to use the Cloud Remote Access we can switch to **Device Management** Application. Go to your device. You should see now the “Remote Access” Tab. Click on **Add Endpoint**.

The following details must be provided:

- **Name of endpoint:** Local SSH Server _(in my case)_
- **Protocol:** SSH
- **Sign-in method:** Username and password
- **Host:** 127.0.0.1 _(the SSH Server is running in the same host where the device agent is running)_
- **Port:** 22
- **Username:** root _(preconfigured in dm-agent docker file, must be changed of course in different environments)_
- **Password:** test123# _(preconfigured in dm-agent docker file, must be changed of course in different environments)_

The host key is optional and will be accepted & stored on first connect.

In the end please click on **Save** to store the configuration.

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/7/c/7c2132532bbf19b0890cf5bf347e72bdb847080b_2_491x500.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/7/c/7c2132532bbf19b0890cf5bf347e72bdb847080b.png "image")

### 4. Start Web SSH Remote Connection

As we have configured our first SSH connection we can now test it by clicking on “Connect”

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/8/d/8d94ef5ad41f75c18c13ab5f09df8c526db7f287_2_690x393.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/8/d/8d94ef5ad41f75c18c13ab5f09df8c526db7f287.png "image")

A pop up will be opened with the web ssh client session. After some seconds you should see the terminal of your device

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/9/c/9c3975b321927f667e53d95df355259a782b5996_2_680x499.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/9/c/9c3975b321927f667e53d95df355259a782b5996.png "image")

Now you can enter any command of you choice e.g. “df -h” to check available disk space.

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/a/2/a2e131a35fead45a003541a0f2cdcfd20cd9ff3b_2_683x500.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/a/2/a2e131a35fead45a003541a0f2cdcfd20cd9ff3b.png "image")

> **NOTE:** If you don’t see the terminal but getting a time out or other error message please check if the device online and available. Also check the provided credentials and connection details you’ve provided in step 3.

### 5. Configure & Start the VNC remote connection

Let’s repeat the steps of step 3 and 4 for a VNC remote connection.  
Click an “Add Endpoint”.

The following details must be provided:

- **Name:** Local VNC
- **Protocol:** VNC
- **Sign-in method:** Password only
- **Host:** 127.0.0.1
- **Port** : 5901 _(notice the change to 5901 here)_
- **Password:** test456# _(preconfigured in dm-agent docker file, must be changed of course in different environments)_

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/5/7/57fc17e7d780ffa209261a0db46be21f40b1cac2_2_580x500.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/5/7/57fc17e7d780ffa209261a0db46be21f40b1cac2.png "image")

Click on “Save”.  
Finally click on “Connect” to start the VNC Remote connection. You should see the desktop screen now in a browser windows

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/d/8/d87a340d45095cbe26f64b381ccb46f9af8d6a7e_2_690x481.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/d/8/d87a340d45095cbe26f64b381ccb46f9af8d6a7e.png "image")

> **NOTE:** If you don’t see the desktop and getting an error try different ports e.g. 5902. Sometimes the vncserver increases the port automatically especially when the agent is multiple times restarted.

## Step-By-Step Guide to setup a Passthrough connection

As described above the Passthrough is the most advanced way to use cloud remote access. You might wonder why there is no “Passthrough” option in the drop-down box when creating a new Remote Access Endpoint. This is a systemwide option that is disabled by default on all our public instances ([cumulocity.com](http://cumulocity.com) / [eu-latest.cumulocity.com](http://eu-latest.cumulocity.com) and so on). On dedicated instances this option can be set to enabled and you will see an option in the drop-down box when creating a new endpoint. Still you can try it the Passthrough option on public instances. Follow the steps below to do so.

> **NOTE:** This guide only helps to demo & demonstrate the passthrough capabilities. If you want to use this in production and on a mass scale please get in contact with your responsible Software AG contact or Software AG support to make sure not running to any issues.

### 1. Create Passthrough Endpoint

First of all we need to create a Passthrough endpoint. The easiest way would be using the UI. So if you can see the Passthrough option in the UI use that to create an endpoint. You just need to provide a name, a url and a port. No credentials are needed as they are provided by the client.  
If you don’t see the Passthrough option in the selection box you can create an endpoint using the REST API.  
Use Postman or a similar REST Client to execute the following call:

```
POST <host>/service/remoteaccess/devices/<InternalDeviceID>/configurations

Headers: 
Basic Auth: <base64 encoded (yourC8YUser : yourPassword)>
Content-Type: application/json
Accept: application/json

Payload:
{
    "name": "Passthrough",
    "hostname": "<hostname of local server>",
    "port": <port of local server>,
    "protocol": "PASSTHROUGH",
    "credentialsType": "NONE"
}

```

Example to connect to the local SSH Server:

```
POST https://switschel.eu-latest.cumulocity.com/service/remoteaccess/devices/97282922/configurations

Headers:
<see above>

Payload:
{
    "name": "Passthrough",
    "hostname": "127.0.0.1",
    "port": 22,
    "protocol": "PASSTHROUGH",
    "credentialsType": "NONE"
}

```

As reponse we get back:

```
{
    "attrs": {},
    "id": "2",
    "name": "Passthrough",
    "hostname": "127.0.0.1",
    "port": 22,
    "protocol": "PASSTHROUGH",
    "credentials": {
        "type": "NONE"
    }
}

```

Also in the UI when we refresh the Cloud Remote Access view on our Device we should see the endpoint now:

[![image](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/a/f/af8e6c8251f9c38df479c5449d2cd39f0b215e1a_2_690x185.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/a/f/af8e6c8251f9c38df479c5449d2cd39f0b215e1a.png "image")

### 2. Install local proxy

As we’ve seen in the introduction section for passthrough we need an agent supporting remote access and a local proxy running on the client side or on a server we can connect to with our local clients. A local proxy is provided as an open-source project:
[Local Proxy for Cumulocity Cloud Remote Access](https://github.com/SoftwareAG/cumulocity-remote-access-local-proxy)

So if needed you can clone / fork it and adapt it to your needs. For now we focus on get it running so on our local computer / computer where we want to run the local proxy we make sure that python3 is installed e.g. python --version or python3 --version. Also make sure that pip is installed. If not install it to your computer.

As a next step we install the local proxy via:

```
pip install c8ylp

```

### 3. Connecting to device

Afterwards we can run the local proxy. The local proxy supports multiple [modes](https://github.com/SoftwareAG/cumulocity-remote-access-local-proxy#common-usages). For us two modes are of interest:

- Server Mode - which opens a local server listening on a port a a local client can connect
- connect ssh Mode - directly use local installed ssh client to establish a ssh session

First of all we need to login to our tenant:

```
swit@SAG-34TVR73:~$ c8ylp login --env-file mytenant.env
Loading env-file: mytenant.env
Host: switschel.eu-latest.cumulocity.com
Enter your Cumulocity Username: stefan.witschel@softwareag.com
Enter your Cumulocity Password [input hidden]:
Env file was updated: mytenant.env

```

The c8ylp login command will create a env file which stores the required information so we don’t have to enter them on any other request again.

#### 3.1 Using connect ssh mode

Next we can already establish a ssh connection. Make sure that you’ve open ssh locall installed on your computer by entering “ssh” in your terminal.

Now we can run the connect mode of the local proxy:

```
c8ylp connect <ssh external ID of device> --ssh-user root --env-file mytenant.env

```

Example:

```
c8ylp connect ssh cc47511bb809 --ssh-user root --env-file mytenant.env

```

It will prompt you for the password for the user root and directly connects you to the device.

[![image](https://aws1.discourse-cdn.com/techcommunity/original/3X/e/9/e903dc637ba54d6f75cc13a75da2fdebb90fe4c2.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/e/9/e903dc637ba54d6f75cc13a75da2fdebb90fe4c2.png "image")

#### 3.2 Using server mode

As an alternative we can use the server mode so we don’t have the requirement to have ssh installed but can use any other client like putty to connect to our local proxy instance.

```
c8ylp server cc47511bb809 --env-file mytenant.env

```

As result we can an random port back we can use to connect with a client of our choice:

[![image](https://aws1.discourse-cdn.com/techcommunity/original/3X/4/2/42a66acdefcf5f859ea7cfc9ebcb21bc01151b0f.png)](https://aws1.discourse-cdn.com/techcommunity/original/3X/4/2/42a66acdefcf5f859ea7cfc9ebcb21bc01151b0f.png "image")

In my example I use putty:  
 ![image](https://aws1.discourse-cdn.com/techcommunity/original/3X/8/8/887957921b4c2d13ef61b4fbba2a989724413422.png)

Connection is established successfully:  
 ![image](https://aws1.discourse-cdn.com/techcommunity/original/3X/0/4/048d927a4fa69c1eb827e549b8e56de8412d4143.png)

### 4. Further Use Cases for using Passthrough

There are much more use cases for using the Passthrough endpoint but not only SSH.

For example you can bridge a local accessible Web UI using the Passthrough configuration. To do so you just need to configure the internal URL and port in the Passthrough config. If you now connect the local proxy in server mode you can enter localhost and the generated port in your browser to access the local User Interface.

Basically any TCP-Port can be bridged that way not only SSH, VNC or HTTP.

## Summary

In this guide I demonstrated almost all possibilities you have when using the Cloud Remote Access Feature including SSH, VNC and Passthrough endpoints on a step-by-step approach and using the DM reference agent. It should help to understand the basic concepts and demonstrates on an example how to perform the steps using Cumulocity IoT.

If you have any questions or feedback feel free to approach me! In case of issues with used components like dm-agent or local proxy feel free to open an issue directly in the github projects.


[Visit the original post](https://tech.forums.softwareag.com/t/how-to-get-started-with-cloud-remote-access-for-cumulocity-iot/258446)