Versions Type Operating system Requirements Dependencies Configuration Local log file Licenses Usage See also Changelog

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:

2.0.x
1.1.x
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:

2.0.x

Minimum of 4 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 3 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.
GNU C Library (glibc) version 2.35 or 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.
The following runtime libraries installed on the Greengrass core device:
- libstdc++ version 3.4.29 or greater
- libgcc_s version 3.0 or greater
- OpenSSL version 3.0.0 or greater
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.

1.0.x - 1.1.x

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.

2.0.0

Version 2.0.0 of this component supports both Greengrass nucleus and Greengrass nucleus lite. The following table lists the dependencies for version 2.0.0 of this component.

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

1.0.19 – 1.1.3

The following table lists the dependencies for versions 1.0.19 through 1.1.3 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.

2.0.x

maxConcurrentTunnels

(Optional) Maximum number of concurrent tunnels allowed.

Note

The value cannot be more than 20.

Default: 20

tunnelTimeoutSeconds

(Optional) Tunnel timeout duration in seconds.

Default: 43200 (12 hours)

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.greengrass.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 the maximum concurrent tunnels and timeout settings.


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

1.0.x - 1.1.x

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


{
  "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

Licenses

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

Usage

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

Deploy the secure tunneling component to your device.
Open the AWS IoT console. From the left menu, choose Remote actions, and then choose Secure tunnels.
Create a tunnel to your Greengrass device.
Download the source access token.
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.

Changelog

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

Version	Changes
2.0.0	New features Replaces the Java wrapper with a C wrapper. Replaces AWS IoT Device Client with AWS IoT Securetunneling Localproxy. Reduces the binary size from approximately 36 MB to approximately 4 MB. Reduces the memory footprint from approximately 100 MB to approximately 2 MB.
1.1.3	Bug fixes and improvements Upgrades the underlying AWS IoT Device Client invoked by the component from version 1.10.0 to version 1.10.1. Fixes the GNU C Library (glibc) compatibility issues in secure tunneling component version 1.1.2.
1.1.2	Warning This version is no longer available. The improvements in this version are available in later versions of this component. Bug fixes and improvements Upgrades the underlying AWS IoT Device Client invoked by the component from version 1.9.0 to version 1.10.0. Fixes the payload transfer issue which prevents users from forwarding large files from Greengrass V2 core devices to the source device through the secure tunnel.
1.1.1	Bug fixes and improvements Adds a configuration to support Greengrass nucleus lite.
1.1.0	New features Adds recipe supports for Greengrass nucleus lite.
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.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Secret manager

Shadow manager

Secure tunneling

Topics

Versions

Type

Operating system

Requirements

Endpoints and ports

Dependencies

Configuration

Note

Note

Example: Configuration merge update

Note

Example: Configuration merge update

Local log file

To view this component's logs

Licenses

Usage

See also

Changelog

Warning

Warning