Using Cloud Remote Access

Prerequisites

To use Cloud Remote Access, you need

• a Cloud Remote Access compatible gateway connected to your Cumulocity IoT account.
• a remote device with a VNC, SSH or Telnet server that is connected to the gateway and reachable from the gateway.
• “Remote access” permission granted to the tenant user.
• the Cloud Remote Access microservice included into your subscription plan.

Accessing Cloud Remote Access

In the Device management application in the Cumulocity IoT platform, click All devices in the Devices menu and select the desired gateway from the device list.

When you open the gateway you will find the Remote access tab in its tab list.

In the Remote Access tab, you can configure devices for remote control, so-called “endpoints”, and connect to remote devices.

Connections can be established to the gateway itself (localhost) or to any device in the local area network reachable by the device.

Managing endpoints

The “endpoint” is the IP address and port of the VNC, SSH or Telnet server running on the remote device. The IP address and port must be reachable from the gateway.

To configure a new remote device

1. Click Add endpoint at the right of the top menu bar.
2. Enter a name for the new endpoint and select the protocol to be used.
3. Follow the descriptions below for the protocol-specific settings.

To add a remote access endpoint via VNC

1. Enter the host (IP address or hostname) and the port of the server.
2. Select a sign-in method. If you select “Password only”, provide the password for the VNC server.
3. Click Save to add the endpoint.

Once the connection is established, a new browser tab will open displaying the front screen or operating panel of the remote device you are connected to. The top bar of the screen will show “starting VNC handshake” when the process is starting.

To add a remote access endpoint via SSH

1. Enter the host (IP address or hostname) and the port of the server.

2. Select a sign-in method.
   

   Username and password: If this method is selected, it is mandatory to enter a username and password.

   

   Public/private keys: Automatically generate public and private keys or simply paste pre-generated keys. The keys can also be uploaded from a file.

   

   Info

   The public key must be installed on the remote device as authorized key.

   Optionally, you can also add a host key to ensure connection to the correct device. This key can also be uploaded from a file.

3. Click Save to add the endpoint.

The following formats are supported when adding new keys:

• OpenSSHv1
• OpenSSHv2
• PEM
• SSH2

The following algorithms are supported when adding new keys:

• RSA
• DSA
• ECDSA
• ED25519

To add a remote access endpoint via Telnet

1. Enter the host (IP address or hostname) and the port of the server.
2. Click Save to add the endpoint.

To edit an endpoint

To edit an endpoint, click the menu icon at the right of the respective entry and select Edit from the context menu.

To delete an endpoint

To delete an endpoint, click the menu icon at the right of the respective entry and select Remove from the context menu.

To connect to an endpoint

To connect to configured endpoints, select an endpoint in the Remote access tab and click Connect. The connection to the configured remote device is established and the VNC, SSH or Telnet screen is shared in the client area.

To terminate the connection, click Disconnect.

Auto-saving host key functionality

A host key is a public key of the server which is generated when an SSH server is installed. It is used to verify the identity of the server.

By enabling the auto-saving host key functionality you will no longer need to enter the host key after each connection. Instead, the host key can be automatically saved after the first successfully established connection to a remote access endpoint.

In order to enable the auto-save host key functionality, navigate to the Remote access page under the Settings menu in the Administration application. Activate the checkbox and then click Save.

Audit logs

For each gateway device, audit logs are available.

The audit logs can be found in the Control tab of the gateway device.

For each connection, the Cloud Remote Access microservice creates an operation in scope of the current user. Then the operation will be updated by the device to reflect the current status. Finally, the operation will have a status of SUCCESSFUL or FAILED.

Troubleshooting

Endpoints cannot be set up

If you cannot set up new endpoints, check if you have sufficient permissions.

To set up new endpoints, you need ADMIN permission for “Device control” to be able to register a device and ADMIN permission for “Remote access” to be able to add an endpoint.

For more information on permissions, refer to Managing permissions.

Connection fails

The connection via a gateway to a remote VNC, SSH or Telnet server can fail because of network problems. In this case you must contact your network administrator.

Unsupported protocol version

In case of Real VNC, if you get an error message stating that you are using an unsupported protocol version (for example 005.00x), try the following workaround:

1. Open VNC.
2. Navigate to Options.
3. Select the Export tab.
4. Search for Protocol version.
5. Enter “3.8” as protocol version.