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

Open https://partners.xyte.io/
Navigate to Product → Models
Select and existing Model or create a new one
Navigate to “Supported Commands”
Click “Add Command”
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

Navigate to https://app.xyte.io/
Find a device with the Model as defined above
Click on the command created above
The customer will be presented with the following notification:
Once the connection is ready, the dialog will change
Clicking on “Connect to device” will open a new tab that will be routed to the device’s internal web server.

Device Side Implementation

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

The device must call Get Command API to get the tunneling details, which are encoded under the tunnelkey.

{
  "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",
    "server_public_key_fingerprint": "SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Field	Description
`tunnel.id`	Unique identifier for this tunnel session
`tunnel.ip`	IP address of the Xyte Proxy Server
`tunnel.port`	SSH port on the Xyte Proxy Server
`tunnel.username`	SSH username for authenticating to the proxy
`tunnel.password`	SSH password for authenticating to the proxy
`tunnel.server_public_key_fingerprint`	SHA-256 fingerprint of the proxy server's SSH host public key. Use this to verify the server identity before establishing the tunnel and prevent man-in-the-middle attacks. May be `null` if not available.

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

Parameters Name	Value
{IP}	Command Response - tunnel.ip
{PORT}	Command Response - tunnel.port
{USER}	Command Response - tunnel.username
{PASSWORD}	Command Response - tunnel.password
{FINGERPRINT}	Command Response - tunnel.server_public_key_fingerprint
{LOCAL-PORT}	Port of the local web server on the device
{LOCAL-HOST}	Host of the local web server on the device (usually `localhost`)

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

# Fetch the proxy server's host key and verify its fingerprint
# against server_public_key_fingerprint from the command response.
# This confirms you are connecting to the legitimate Xyte Proxy Server.
SERVER_KEY=$(ssh-keyscan -p {PORT} {IP} 2>/dev/null)
ACTUAL_FINGERPRINT=$(echo "$SERVER_KEY" | ssh-keygen -l -f - | awk '{print $2}')

if [ "$ACTUAL_FINGERPRINT" != "{FINGERPRINT}" ]; then
  echo "Host key fingerprint mismatch — aborting."
  exit 1
fi

# Add the verified host key and open the reverse tunnel
echo "$SERVER_KEY" >> ~/.ssh/known_hosts
ssh -o ServerAliveInterval=5 -o StrictHostKeyChecking=yes \
    -p {PORT} -N -R 8080:{LOCAL-HOST}:{LOCAL-PORT} {USER}@{IP}

# You will be prompted for {PASSWORD}

If server_public_key_fingerprint is null, skip the verification step and use -o StrictHostKeyChecking=no instead. Fingerprint verification is strongly recommended in production firmware.