Secure tunneling - AWS IoT Greengrass

Secure tunneling

With the aws.greengrass.SecureTunneling component, you can establish secure bidirectional communication with a Greengrass core device located behind restricted firewalls.

For example, imagine you have a Greengrass core device behind a firewall that prohibits all incoming connections. Secure tunneling uses MQTT to transfer an access token to the device and then uses WebSockets to make an SSH connection to the device through the firewall. With this AWS IoT managed tunnel, you can open the SSH connection needed for your device. For more information about using AWS IoT secure tunneling to connect to remote devices, see AWS IoT secure tunneling in the AWS IoT Developer Guide.

This component subscribes to the AWS IoT Core MQTT message broker on the $aws/things/greengrass-core-device/tunnels/notify topic to receive secure tunneling notifications.

Versions

This component has the following versions:

  • 1.0.x

Type

This component is a generic component (aws.greengrass.generic). The Greengrass nucleus runs the component's lifecycle scripts.

For more information, see Component types.

Operating system

This component can be installed on Linux core devices only.

Architectures:

  • Armv71

  • Armv8 (AArch64)

  • x86_64

Requirements

This component has the following requirements:

  • Minimum of 32 MB disk space available for the secure tunneling component. This requirement does not include the Greengrass core software or other components running on the same device.

  • Minimum of 16 MB RAM available for the secure tunneling component. This requirement does not include the Greengrass core software or other components running on the same device. For more information, see Control memory allocation with JVM options.

  • GNU C Library (glibc) version 2.25 or greater with a Linux kernel of 3.2 or greater are required for the secure tunneling component version 1.0.12 and greater. Versions of the operating system and libraries past their long-term support end of life date are not supported. You should use an operating system and libraries with long-term support.

  • Both the operating system and the Java runtime must be installed as 64 bit.

  • Python 3.5 or later installed on the Greengrass core device and added to the PATH environment variable.

  • libcrypto.so.1.1 installed on the Greengrass core device and added to the PATH environment variable.

  • Open outbound traffic on port 443 on the Greengrass core device.

  • Turn on support for the communication service that you want to use to communicate with the Greengrass core device. For example, to open an SSH connection to the device, you must turn on SSH on that device.

Endpoints and ports

This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see Allow device traffic through a proxy or firewall.

Endpoint Port Required Description

data.tunneling.iot.region.amazonaws.com

443 Yes

Establish secure tunnels.

Dependencies

When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the released versions of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.

1.0.19

The following table lists the dependencies for version 1.0.19 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <3.0.0 Soft
1.0.18

The following table lists the dependencies for version 1.0.18 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.13.0 Soft
1.0.16 – 1.0.17

The following table lists the dependencies for versions 1.0.16 to 1.0.17 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.12.0 Soft
1.0.14 – 1.0.15

The following table lists the dependencies for versions 1.0.14 to 1.0.15 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.11.0 Soft
1.0.11 – 1.0.13

The following table lists the dependencies for versions 1.0.11 – 1.0.13 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.10.0 Soft
1.0.10

The following table lists the dependencies for version 1.0.10 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.9.0 Soft
1.0.9

The following table lists the dependencies for version 1.0.9 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.8.0 Soft
1.0.8

The following table lists the dependencies for version 1.0.8 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.7.0 Soft
1.0.5 - 1.0.7

The following table lists the dependencies for versions 1.0.5 through 1.0.7 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.6.0 Soft
1.0.4

The following table lists the dependencies for version 1.0.4 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.5.0 Soft
1.0.3

The following table lists the dependencies for version 1.0.3 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.4.0 Soft
1.0.2

The following table lists the dependencies for version 1.0.2 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.3.0 Soft
1.0.1

The following table lists the dependencies for version 1.0.1 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.2.0 Soft
1.0.0

The following table lists the dependencies for version 1.0.0 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.3 <2.1.0 Soft

For more information about component dependencies, see the component recipe reference.

Configuration

This component provides the following configuration parameters that you can customize when you deploy the component.

OS_DIST_INFO

(Optional) The operating system of your core device. By default, the component attempts to identify automatically the operating system running on your core device. If the component fails to start with the default value, use this value to specify the operating system. For a list of supported operating systems for this component, see Device requirements.

This value can be one of the following: auto, ubuntu, amzn2, raspberrypi.

Default: auto

accessControl

(Optional) The object that contains the authorization policy that allows the component to subscribe to the secure tunneling notifications topic.

Note

Do not modify this configuration parameter if your deployment targets a thing group. If your deployment targets an individual core device, and you want to restrict its subscription to the device's topic, specify the core device's thing name. In the resources value in the device's authorization policy, replace the MQTT topic wildcard with the device's thing name.

{ "aws.greengrass.ipc.mqttproxy": { "aws.iot.SecureTunneling:mqttproxy:1": { "policyDescription": "Access to tunnel notification pubsub topic", "operations": [ "aws.greengrass#SubscribeToIoTCore" ], "resources": [ "$aws/things/+/tunnels/notify" ] } } }
Example: Configuration merge update

The following example configuration specifies to allow this component to open secure tunnels on a core device named MyGreengrassCore that runs Ubuntu.

{ "OS_DIST_INFO": "ubuntu", "accessControl": { "aws.greengrass.ipc.mqttproxy": { "aws.iot.SecureTunneling:mqttproxy:1": { "policyDescription": "Access to tunnel notification pubsub topic", "operations": [ "aws.greengrass#SubscribeToIoTCore" ], "resources": [ "$aws/things/MyGreengrassCore/tunnels/notify" ] } } } }

Local log file

This component uses the following log file.

/greengrass/v2/logs/aws.greengrass.SecureTunneling.log
To view this component's logs
  • Run the following command on the core device to view this component's log file in real time. Replace /greengrass/v2 with the path to the AWS IoT Greengrass root folder.

    sudo tail -f /greengrass/v2/logs/aws.greengrass.SecureTunneling.log

Licenses

This component includes the following third-party software/licensing:

Usage

To use the secure tunneling component on your device, do the following:

  1. Deploy the secure tunneling component to your device.

  2. Open the AWS IoT console. From the left menu, choose Remote actions, and then choose Secure tunnels.

  3. Create a tunnel to your Greengrass device.

  4. Download the source access token.

  5. Use the local proxy with the source access token to connect to your destination. For more information, see How to use the local proxy in the AWS IoT Developer Guide.

See also

Changelog

The following table describes the changes in each version of the component.

Version

Changes

1.0.19

Bug fixes and improvements
  • Upgrades the underlying AWS IoT Device Client invoked by the component from version 1.8.0 to version 1.9.0.

  • Increases the concurrent tunnel limit to 20 tunnels on a component level.

  • Increases the default AWS IoT Greengrass Core IPC timeout from 3 seconds to 10 seconds.

Warning

If you are using the secure tunneling local proxy as the tunnel source client, do not update your component to this version until you have also upgraded the local proxy to version 3.1.1 or later.

1.0.18

Version updated for Greengrass nucleus version 2.12.0 release.

1.0.17

Bug fixes and improvements
  • Fixes the thread cleanup issue which was blocking users from creating tunnels. This component will now cleanup a thread either once it receives the CloseTunnel signal or if the tunnel is expired after 12 hours.

1.0.16

Version updated for Greengrass nucleus version 2.11.0 release.

1.0.15

Bug fixes and improvements
  • Fixes a startup issue for users that do not have a home directory on the device. The secure tunneling component now starts without creating a directory for shadow documents.

1.0.14

Version updated for Greengrass nucleus version 2.10.0 release.

1.0.13

Bug fixes and improvements
  • Fixes an issue where an orphan client process prevents more than one tunnel from targeting the device.

1.0.12

Bug fixes and improvements
  • Adds support for x86_64 (AMD64) and ARMv8 (Aarch64) when running on Raspberry Pi OS.

1.0.11

Version updated for Greengrass nucleus version 2.9.0 release.

1.0.10

Version updated for Greengrass nucleus version 2.8.0 release.

1.0.9

Version updated for Greengrass nucleus version 2.7.0 release.

1.0.8

Version updated for Greengrass nucleus version 2.6.0 release.

1.0.7

Bug fixes and improvements
  • Fixes an issue where the component disconnects when you transfer large files over SCP.

1.0.6

This version contains bug fixes.

1.0.5

Version updated for Greengrass nucleus version 2.5.0 release.

1.0.4

Version updated for Greengrass nucleus version 2.4.0 release.

1.0.3

Version updated for Greengrass nucleus version 2.3.0 release.

1.0.2

Version updated for Greengrass nucleus version 2.2.0 release.

1.0.1

Version updated for Greengrass nucleus version 2.1.0 release.

1.0.0

Initial version.