Open a tunnel and start SSH session to remote device - AWS IoT Core
Prerequisites for the tutorialsTunnel setup methodsTunnel creation methods in AWS IoT console

Open a tunnel and start SSH session to remote device

In these tutorials, you'll learn how to remotely access a device that's behind a firewall. You can't start a direct SSH session into the device because the firewall blocks all inbound traffic. The tutorials show you how you can open a tunnel and then use that tunnel to start an SSH session to a remote device.

Prerequisites for the tutorials

The prerequisites for running the tutorial can vary depending on whether you use the manual or quick setup methods for opening a tunnel and accessing the remote device.

Note

For both setup methods, you must allow outbound traffic on port 443.

Tunnel setup methods

In these tutorials, you'll learn about the manual and quick setup methods for opening a tunnel and connecting to the remote device. The following table shows the difference between the setup methods. After you create the tunnel, you can use an in-browser command line interface to SSH into the remote device. If you misplace the tokens or the tunnel gets disconnected, you can send new access tokens to reconnect to the tunnel.

Quick and manual setup methods
Criteria Quick setup Manual setup
Tunnel creation Create a new tunnel with default, editable configurations. To access your remote device, you can only use SSH as the destination service. Create a tunnel by manually specifying the tunnel configurations. You can use this method to connect to the remote device using services other than SSH.
Access tokens The destination access token will be automatically delivered to your device on the reserved MQTT topic, if a thing name is specified when creating the tunnel. You don't have to download or manage the token on your source device. You'll have to manually download and manage the token on your source device. The destination access token is automatically delivered to the remote device on the reserved MQTT topic, if a thing name is specified when creating the tunnel.
Local proxy A web-based local proxy is automatically configured for you for interacting with the device. You don't have to manually configure the local proxy. You'll have to manually configure and launch the local proxy. To configure the local proxy, you can either use the AWS IoT Device Client or download the Local proxy reference implementation on GitHub.

Tunnel creation methods in AWS IoT console

The tutorials in this section show you how to create a tunnel using the AWS Management Console and the OpenTunnel API. If you configure the destination when creating a tunnel, AWS IoT secure tunneling delivers the destination client access token to the remote device over MQTT and the reserved MQTT topic, $aws/things/RemoteDeviceA/tunnels/notify). On receiving the MQTT message, the IoT agent on the remote device starts the local proxy in destination mode. For more information, see Reserved topics.

Note

You can omit the destination configuration if you want to deliver the destination client access token to the remote device through another method. For more information, see Configuring a remote device and using IoT agent.

In the AWS IoT console, you can create a tunnel using either of the following methods. For information about tutorials that will help you learn to create a tunnel using these methods, see Tutorials in this section.

  • Tunnels hub

    When you create the tunnel, you'll be able to specify whether to use the quick setup or the manual setup methods for creating the tunnel and provide the optional tunnel configuration details. The configuration details also include the name of the destination device and the service that you want to use for connecting to the device. After you create a tunnel, you can either SSH within the browser or open a terminal outside the AWS IoT console to access your remote device.

  • Thing details page

    When you create the tunnel, you'll also be able to specify whether to use the most recent, open tunnel or create a new tunnel for the device, in addition to choosing the setup methods and providing any optional tunnel configuration details. You can't edit the configuration details of an existing tunnel. You can use the quick setup method to rotate the access tokens and SSH into the remote device within the browser. To open a tunnel using this method, you must have created an IoT thing (for example, RemoteDeviceA) in the AWS IoT registry. For more information, see Register a device in the AWS IoT registry.

Tutorials in this section