Overview

Many legacy systems have an existing Web Server running on devices that is only available within the local network. To allow faster migration to the cloud (without waiting for all legacy features to be migrated to the cloud architecture) the "Device Tunneling" feature can be used to securely expose the local server to remove operators over the cloud.

Device Tunneling works by having the device create an outgoing tunnel to a special Xyte Proxy Server and the Xyte Cloud generating a secure URL that users with appropriate permissions can access and directly open in their web browsers.

Partner Side Setup

1. Open https://partners.xyte.io/
2. Navigate to Product → Models
3. Select and existing Model or create a new one
4. Navigate to “Supported Commands”
5. Click “Add Command”
6. Check “Open tunnel” in the options
   1. Select http or https based on how the local web-server is setup on the device. Regardless of the choice, all communication will be fully encrypted.

End Customer Experience

1. Navigate to https://app.xyte.io/

2. Find a device with the Model as defined above

3. Click on the command created above

4. The customer will be presented with the following notification:

   

5. Once the connection is ready, the dialog will change

   

6. Clicking on “Connect to device” will open a new tab that will be routed to the device’s internal web server.

Device Side Implementation

1. Once an open tunnel command is enqueued by an End Customer, it is treated as a regular Device side Command. The next call to Send Telemetry API will return command: true in the response (or if MQTT used, the command will be send to the channel).
2. The device must call Get Command API to get the tunneling details, which are encoded under the tunnelkey.
   Sample Get Command API Responce

   {
     "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "status": "pending",
     "name": "open_tunnel",
     "parameters": null,
     "tunnel": {
   		"id": unique-tunnel-id,
     	"ip": ip-for-ssh,
   		"port": port-for-ssh,
   		"username": username-for-ssh,
   		"password": password-for-ssh,
     }
   }
   

3. The device should open a tunnel from the local Web Server's port to the Proxy server's info, as provided in the Command's parameters.
4. Once the tunnel is open, the device must notify server that the command was successfully performed by calling Update Command API and setting "status": "done".

The tunnel will be automatically closed after 15 minutes of inactivity or if the Device terminates the tunnel

Demo Session

To test the tunneling feature on a Linux (or compatible platform) the above steps can be performed manually, via Postman like tools or the embedded Dev Center.

The Get Command API results should be mapped to the following parameters:

The following can be run in command line to simulate a tunnel

# As the fingerprint for the server may change,
# it's better to "clear" it our of the known hosts in advance
ssh-keygen -R {IP}

# Open the reverse tunnel with the parameters from the command
ssh -o ServerAliveInterval=5 -o StrictHostKeyChecking=no -p {PORT} -N -R 8080:{LOCAL-HOST}:{LOCAL-PORT} {USER}@{IP}

After running the command above, you will be asked for the {PASSWORD}