Introduction

The Remote Device Access solution provides a generic way to access a server on a remote device via the Cloud.

The user can access the server of the device using a standard web browser. All traffic is routed on a secure connection through the Cloud to the device.

To connect the device to the Cloud an edge device running the device local proxy application is needed. This device can be either the target device itself or an edge device that is located in the network of the target device.

Download Source Code of Open Source Components

The source code and the corresponding licenses of the used open source components can be downloaded.

Generation of Connection String

To associate a device with the Cloud you need a connection string. The following section describes the generation of the string.

Provision a device

To use the device local proxy on your local device you first need to provision a device for it.

1. Open the Cloud Remote Access web page.

2. On the configuration page in the devices section click the "Add" button.

RDA Quickstart - Web UI Add

 

3. Type a name and a location for the device and click "ADD".

RDA Quickstart - Web UI Add 2

 

4. Copy the now shown connection string and store it in a temporary location (clipboard). You can copy the string by clicking the red marked copy button.

RDA Quickstart - Web UI Connection String

Installation

This guide describes two different ways to install the device local proxy on your device. Either via the Portainer web interface or via the command line.

Prerequisites

The following requirements must be fulfilled in order to install the client on your device:

  • Docker engine installed on edge-device
  • Internet access on edge-device
  • Device provisioned via web page

Login Data for Container Registry

The login data for the container registry is managed by your admin.

Please contact them to get the correct server url (referred as <Registry Login Server>), username (referred as <Registry Username>) and password (referred as <Registry Password>).

Installation using command line

1. Connect to the device using ssh.

$ ssh <user>@<ip-of-device>

2. Login with docker to your container registry. Use the copied <Registry Username> and <Registry Password>.

$ docker login <Registry Login Server>

3. Pull the container image from the public container registry.<br>

$ docker pull <Registry Login Server>/modules/devicelocalproxy

4. Run the newly pulled image. To associate the device with Cloud Remote Access you need to provide the previously copied connection string as an environment variable.

  1. To run the container a single time without a restart use the following command.
    $ docker run -e IOTHUB_DEVICE_CONN_STRING='<Copied Connection String>' <Registry Login Server>/modules/devicelocalproxy
  2. To automatically restart the client after a reboot of the system add the "--restart always" parameter.
    $ docker run -e IOTHUB_DEVICE_CONN_STRING='<Copied Connection String>' --restart always <Registry Login Server>/modules/devicelocalproxy

 

Installation using Portainer

1. Open the Portainer web page and login.

2. Go to the correct endpoint (in this example "local").

RDA Quickstart - Portainer Endpoint Selection

 

3. Navigate to the Registries page on the left-handed navigation bar.

RDA Quickstart - Portainer Registries Selection

 

4. Click "Add registry".

5. Select "Custom registry" and fill out name (M&M-CloudRemoteShell), registry url (<Registry Login Server>), user (<Registry Username>) and password (<Registry Password>).

RDA Quickstart - Portainer Registry

 

6. Click "Add registry".

7. Navigate to containers on the left-handed navigation bar.

RDA Quickstart - Portainer Container Selection

 

8. Click "Add container".

9. Fill out name (DeviceLocalProxy), select the newly added registry and fill out image (modules/devicelocalproxy).

RDA Quickstart - Portainer Add Container

 

10. In the advanced container settings open the "Env" tab and add the previously copied Connection string as an environment variable (name: IOTHUB_DEVICE_CONN_STRING, value: <Copied Connection string>).

RDA Quickstart - Portainer Environment Variable

 

11. Click "Deploy the container".

12. Start the container by selecting it and clicking "Start".