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.
-
For information about prerequisites for the quick setup method tutorial, see Prerequisites for quick setup method.
-
For information about prerequisites for the manual setup method tutorial, see Prerequisites for manual setup method. If you use this setup method, you must configure the local proxy on your source device. To download the local proxy source code, see Local proxy reference implementation on GitHub
.
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.
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 Amazon IoT Device Client or
download the Local proxy reference implementation on GitHub |
Tunnel creation methods in Amazon IoT console
The tutorials in this section show you how to create a tunnel using the Amazon Web Services Management Console
and the OpenTunnel API. If you configure the
destination when creating a tunnel, Amazon 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 Amazon 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 Amazon 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 Amazon IoT registry. For more information, see Register a device in the Amazon IoT registry.