Setting up Cloud Remote Access

Prerequisites

Set up your device

To configure your device for compatibility with the Cloud Remote Access functionality, you must install thin-edge.io. Thin-edge.io is fully integrated with Cloud Remote Access and can be easily deployed on any Linux-based device, eliminating the need for any custom integration.

Furthermore, devices can report their supported protocols using SmartREST template 150 which offers two significant advantages:

1. It prevents the display of unsupported protocols in the selection modal, streamlining the user experience and reducing potential confusion.
2. It enables administrators to restrict the use of potentially vulnerable protocols, such as Telnet, thereby enhancing the overall security of your deployment.

User Authorization

The Cloud Remote Access feature is a powerful tool that requires careful management. Due to its potential for significant system impact, access should be restricted to experienced administrators who fully understand its capabilities and risks.

To grant access to qualified users:

1. Navigate to Accounts > Roles in the Administration application.
2. Click Add global role at the top right.
3. Create a new role with the following details:
   • Name: “Cloud Remote Access Role”
   • Permissions: Enable “Admin” permission for “Remote Access”

Accessing Cloud Remote Access

In the Device Management application in the Cumulocity 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 add a remote access endpoint via Passthrough

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

Visit the Cumulocity CLI documentation to learn more about how to set up the passthrough connection from the device to your local machine using the local proxy that is embedded in the CLI.

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