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/
topic to receive secure tunneling notifications.greengrass-core-device
/tunnels/notify
Topics
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 |
---|---|---|---|
|
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
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.
/logs/aws.greengrass.SecureTunneling.log
/greengrass/v2
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
with the path to the AWS IoT Greengrass root folder./greengrass/v2
sudo tail -f
/logs/aws.greengrass.SecureTunneling.log/greengrass/v2
Licenses
This component includes the following third-party software/licensing:
-
AWS IoT Device Client
/Apache License 2.0 -
AWS IoT Device SDK for Java
/Apache License 2.0 -
gson
/Apache License 2.0 -
log4j
/Apache License 2.0 -
slf4j
/Apache License 2.0
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.
See also
-
AWS IoT secure tunneling in the AWS IoT Developer Guide
-
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 |
---|---|
1.1.0 |
|
1.0.19 |
WarningIf 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 |
|
1.0.16 |
Version updated for Greengrass nucleus version 2.11.0 release. |
1.0.15 |
|
1.0.14 |
Version updated for Greengrass nucleus version 2.10.0 release. |
1.0.13 |
|
1.0.12 |
|
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 |
|
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. |