AWS IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the AWS IoT Greengrass V1 maintenance policy. After this date, AWS IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on AWS IoT Greengrass V1 won't be disrupted and will continue to operate and to connect to the cloud. We strongly recommend that you migrate to AWS IoT Greengrass Version 2, which adds significant new features and support for additional platforms.
Configure the AWS IoT Greengrass core
An AWS IoT Greengrass core is an AWS IoT thing (device) that acts as a hub or gateway in edge environments. Like other AWS IoT devices, a core exists in the registry, has a device shadow, and uses a device certificate to authenticate with AWS IoT Core and AWS IoT Greengrass. The core device runs the AWS IoT Greengrass Core software, which enables it to manage local processes for Greengrass groups, such as communication, shadow sync, and token exchange.
The AWS IoT Greengrass Core software provides the following functionality:
-
Deployment and the local running of connectors and Lambda functions.
-
Process data streams locally with automatic exports to the AWS Cloud.
-
MQTT messaging over the local network between devices, connectors, and Lambda functions using managed subscriptions.
-
MQTT messaging between AWS IoT and devices, connectors, and Lambda functions using managed subscriptions.
-
Secure connections between devices and the AWS Cloud using device authentication and authorization.
-
Local shadow synchronization of devices. Shadows can be configured to sync with the AWS Cloud.
-
Controlled access to local device and volume resources.
-
Deployment of cloud-trained machine learning models for running local inference.
-
Automatic IP address detection that enables devices to discover the Greengrass core device.
-
Central deployment of new or updated group configuration. After the configuration data is downloaded, the core device is restarted automatically.
-
Secure, over-the-air (OTA) software updates of user-defined Lambda functions.
-
Secure, encrypted storage of local secrets and controlled access by connectors and Lambda functions.
AWS IoT Greengrass core configuration file
The configuration file for the AWS IoT Greengrass Core software is config.json
. It
is located in the /
directory.greengrass-root
/config
Note
greengrass-root
represents the path where the AWS IoT Greengrass Core
software is installed on your device. Typically, this is the /greengrass
directory.
If you use the Default Group creation option from the AWS IoT Greengrass console,
then the config.json
file is deployed to the core device in a
working state.
You can review the contents of this file by running the following command:
cat /
greengrass-root
/config/config.json
The following is an example config.json
file. This is the version
that's generated when you create the core from the AWS IoT Greengrass console.
Service endpoints must match the root CA certificate type
Your AWS IoT Core and AWS IoT Greengrass endpoints must correspond to the certificate type of the root CA certificate on your device. If the endpoints and certificate type do not match, authentication attempts fail between the device and AWS IoT Core or AWS IoT Greengrass. For more information, see Server authentication in the AWS IoT Developer Guide.
If your device uses an Amazon Trust Services (ATS) root CA certificate, which is the
preferred method, it must also use ATS endpoints for device management and discovery
data plane operations. ATS endpoints include the ats
segment, as shown in
the following syntax for the AWS IoT Core endpoint.
prefix
-ats.iot.region
.amazonaws.com
Note
For backward compatibility, AWS IoT Greengrass currently supports legacy VeriSign root CA certificates and endpoints in some AWS Regions. If you're using a legacy VeriSign root CA certificate, we recommend that you create an ATS endpoint and use an ATS root CA certificate instead. Otherwise, make sure to use the corresponding legacy endpoints. For more information, see Supported legacy endpoints in the Amazon Web Services General Reference.
Endpoints in config.json
On a Greengrass core device, endpoints are specified in the coreThing
object in the config.json
file. The iotHost
property represents the AWS IoT Core endpoint. The
ggHost
property represents the AWS IoT Greengrass endpoint. In the following
example snippet, these properties specify ATS endpoints.
{ "coreThing" : { ... "iotHost" : "abcde1234uwxyz-ats.iot.us-west-2.amazonaws.com", "ggHost" : "greengrass-ats.iot.us-west-2.amazonaws.com", ... },
- AWS IoT Core endpoint
-
You can get your AWS IoT Core endpoint by running the aws iot describe-endpoint CLI command with the appropriate
--endpoint-type
parameter.-
To return an ATS signed endpoint, run:
aws iot describe-endpoint --endpoint-type iot:Data-ATS
-
To return a legacy VeriSign signed endpoint, run:
aws iot describe-endpoint --endpoint-type iot:Data
-
- AWS IoT Greengrass endpoint
-
Your AWS IoT Greengrass endpoint is your
iotHost
endpoint with the host prefix replaced by greengrass. For example, the ATS signed endpoint isgreengrass-ats.iot.
. This uses the same Region as your AWS IoT Core endpoint.region
.amazonaws.com
Connect on port 443 or through a network proxy
This feature is available for AWS IoT Greengrass Core v1.7 and later.
Greengrass cores communicate with AWS IoT Core using the MQTT messaging protocol with TLS client authentication. By convention, MQTT over TLS uses port 8883. However, as a security measure, restrictive environments might limit inbound and outbound traffic to a small range of TCP ports. For example, a corporate firewall might open port 443 for HTTPS traffic, but close other ports that are used for less common protocols, such as port 8883 for MQTT traffic. Other restrictive environments might require all traffic to go through an HTTP proxy before connecting to the internet.
To enable communication in these scenarios, AWS IoT Greengrass allows the following configurations:
-
MQTT with TLS client authentication over port 443. If your network allows connections to port 443, you can configure the core to use port 443 for MQTT traffic instead of the default port 8883. This can be a direct connection to port 443 or a connection through a network proxy server.
AWS IoT Greengrass uses the Application Layer Protocol Network
(ALPN) TLS extension to enable this connection. As with the default configuration, MQTT over TLS on port 443 uses certificate-based client authentication. When configured to use a direct connection to port 443, the core supports over-the-air (OTA) updates for AWS IoT Greengrass software. This support requires AWS IoT Greengrass Core v1.9.3 or later.
-
HTTPS communication over port 443. AWS IoT Greengrass sends HTTPS traffic over port 8443 by default, but you can configure it to use port 443.
-
Connection through a network proxy. You can configure a network proxy server to act as an intermediary for connecting to the Greengrass core. Only basic authentication and HTTP and HTTPS proxies are supported.
The proxy configuration is passed to user-defined Lambda functions through the
http_proxy
,https_proxy
, andno_proxy
environment variables. User-defined Lambda functions must use these passed-in settings to connect through the proxy. Common libraries used by Lambda functions to make connections (such as boto3 or cURL and pythonrequests
packages) typically use these environment variables by default. If a Lambda function also specifies these same environment variables, AWS IoT Greengrass doesn't override them.Important
Greengrass cores that are configured to use a network proxy don't support OTA updates.
To configure MQTT over port 443
This feature requires AWS IoT Greengrass Core v1.7 or later.
This procedure allows the Greengrass core to use port 443 for MQTT messaging with AWS IoT Core.
-
Run the following command to stop the Greengrass daemon:
cd /
greengrass-root
/ggc/core/ sudo ./greengrassd stop -
Open
for editing as the su user.greengrass-root
/config/config.json -
In the
coreThing
object, add theiotMqttPort
property and set the value to443
, as shown in the following example.{ "coreThing" : { "caPath" : "root.ca.pem", "certPath" : "12345abcde.cert.pem", "keyPath" : "12345abcde.private.key", "thingArn" : "arn:aws:iot:us-west-2:123456789012:thing/core-thing-name", "iotHost" : "abcd123456wxyz-ats.iot.us-west-2.amazonaws.com",
"iotMqttPort" : 443,
"ggHost" : "greengrass-ats.iot.us-west-2.amazonaws.com", "keepAlive" : 600 }, ... } -
Start the daemon.
cd /
greengrass-root
/ggc/core/ sudo ./greengrassd start
To configure HTTPS over port 443
This feature requires AWS IoT Greengrass Core v1.8 or later.
This procedure configures the core to use port 443 for HTTPS communication.
-
Run the following command to stop the Greengrass daemon:
cd /
greengrass-root
/ggc/core/ sudo ./greengrassd stop -
Open
for editing as the su user.greengrass-root
/config/config.json -
In the
coreThing
object, add theiotHttpPort
andggHttpPort
properties, as shown in the following example.{ "coreThing" : { "caPath" : "root.ca.pem", "certPath" : "12345abcde.cert.pem", "keyPath" : "12345abcde.private.key", "thingArn" : "arn:aws:iot:us-west-2:123456789012:thing/core-thing-name", "iotHost" : "abcd123456wxyz-ats.iot.us-west-2.amazonaws.com",
"iotHttpPort" : 443,
"ggHost" : "greengrass-ats.iot.us-west-2.amazonaws.com","ggHttpPort" : 443,
"keepAlive" : 600 }, ... } -
Start the daemon.
cd /
greengrass-root
/ggc/core/ sudo ./greengrassd start
To configure a network proxy
This feature requires AWS IoT Greengrass Core v1.7 or later.
This procedure allows AWS IoT Greengrass to connect to the internet through an HTTP or HTTPS network proxy.
-
Run the following command to stop the Greengrass daemon:
cd /
greengrass-root
/ggc/core/ sudo ./greengrassd stop -
Open
for editing as the su user.greengrass-root
/config/config.json -
In the
coreThing
object, add the networkProxy object, as shown in the following example.{ "coreThing" : { "caPath" : "root.ca.pem", "certPath" : "12345abcde.cert.pem", "keyPath" : "12345abcde.private.key", "thingArn" : "arn:aws:iot:us-west-2:123456789012:thing/core-thing-name", "iotHost" : "abcd123456wxyz-ats.iot.us-west-2.amazonaws.com", "ggHost" : "greengrass-ats.iot.us-west-2.amazonaws.com", "keepAlive" : 600,
"networkProxy": { "noProxyAddresses" : "http://128.12.34.56,www.mywebsite.com", "proxy" : { "url" : "https://my-proxy-server:1100", "username" : "Mary_Major", "password" : "pass@word1357" } }
}, ... } -
Start the daemon.
cd /
greengrass-root
/ggc/core/ sudo ./greengrassd start
networkProxy object
Use the networkProxy
object to specify information about the network
proxy. This object has the following properties.
Field | Description |
---|---|
noProxyAddresses |
Optional. A comma-separated list of IP addresses or host names that are exempt from the proxy. |
proxy |
The proxy to connect to. A proxy has the following properties.
|
Allowing endpoints
Communication between Greengrass devices and AWS IoT Core or AWS IoT Greengrass must be authenticated. This authentication is based on registered X.509 device certificates and cryptographic keys. To allow authenticated requests to pass through proxies without additional encryption, allow the following endpoints.
Endpoint | Port | Description |
---|---|---|
greengrass. |
443 |
Used for control plane operations for group management. |
or
|
MQTT: 8883 or 443 HTTPS: 8443 or 443 |
Used for data plane operations for device management, such as shadow sync. Allow the use of one or both endpoints, depending on whether your core and client devices use Amazon Trust Services (preferred) root CA certificates, legacy root CA certificates, or both. For more information, see Service endpoints must match the root CA certificate type. |
or
|
8443 or 443 |
Used for device discovery operations. Allow the use of one or both endpoints, depending on whether your core and client devices use Amazon Trust Services (preferred) root CA certificates, legacy root CA certificates, or both. For more information, see Service endpoints must match the root CA certificate type. NoteClients that connect on port 443 must implement the
Application Layer Protocol Negotiation (ALPN) |
*.s3.amazonaws.com |
443 |
Used for deployment operations and over-the-air updates. This
format includes the |
logs. |
443 |
Required if the Greengrass group is configured to write logs to CloudWatch. |
Configure a write directory for AWS IoT Greengrass
This feature is available for AWS IoT Greengrass Core v1.6 and later.
By default, the AWS IoT Greengrass Core software is deployed under a single root directory where AWS IoT Greengrass performs all read and write operations. However, you can configure AWS IoT Greengrass to use a separate directory for all write operations, including creating directories and files. In this case, AWS IoT Greengrass uses two top-level directories:
-
The
greengrass-root
directory, which you can leave as read-write or optionally make read-only. This contains the AWS IoT Greengrass Core software and other critical components that should remain immutable during runtime, such as certificates andconfig.json
. -
The specified write directory. This contains writable content, such as logs, state information, and deployed user-defined Lambda functions.
This configuration results in the following directory structure.
- Greengrass root directory
-
greengrass-root
/ |-- certs/ | |-- root.ca.pem | |--hash
.cert.pem | |--hash
.private.key | |--hash
.public.key |-- config/ | |-- config.json |-- ggc/ | |-- packages/ | |--package-version
/ | |-- bin/ | |-- daemon | |-- greengrassd | |-- lambda/ | |-- LICENSE/ | |-- release_notes_package-version
.html | |-- runtime/ | |-- java8
/ | |-- nodejs8.10
/ | |-- python3.8
/ | |-- core/ - Write Directory
-
write-directory
/ |-- packages/ | |--package-version
/ | |-- ggc_root/ | |-- rootfs_nosys/ | |-- rootfs_sys/ | |-- var/ |-- deployment/ | |-- group/ | |-- group.json | |-- lambda/ | |-- mlmodel/ |-- var/ | |-- log/ | |-- state/
To configure a write directory
-
Run the following command to stop the AWS IoT Greengrass daemon:
cd /
greengrass-root
/ggc/core/ sudo ./greengrassd stop -
Open
for editing as the su user.greengrass-root
/config/config.json -
Add
writeDirectory
as a parameter and specify the path to the target directory, as shown in the following example.{ "coreThing": { "caPath": "root-CA.pem", "certPath": "hash.pem.crt", ... }, ... "writeDirectory" : "/
write-directory
" }Note
You can update the
writeDirectory
setting as often as you want. After the setting is updated, AWS IoT Greengrass uses the newly specified write directory at the next start, but doesn't migrate content from the previous write directory. -
Now that your write directory is configured, you can optionally make the
greengrass-root
directory read-only. For instructions, see To Make the Greengrass Root Directory Read-Only.Otherwise, start the AWS IoT Greengrass daemon:
cd /
greengrass-root
/ggc/core/ sudo ./greengrassd start
To make the Greengrass root directory read-only
Follow these steps only if you want to make the Greengrass root directory read-only. The write directory must be configured before you begin.
-
Grant access permissions to required directories:
-
Give read and write permissions to the
config.json
owner.sudo chmod 0600 /
greengrass-root
/config/config.json -
Make ggc_user the owner of the certs and system Lambda directories.
sudo chown -R ggc_user:ggc_group /
greengrass-root
/certs/ sudo chown -R ggc_user:ggc_group /greengrass-root
/ggc/packages/1.11.6/lambda/Note
The ggc_user and ggc_group accounts are used by default to run system Lambda functions. If you configured the group-level default access identity to use different accounts, you should give permissions to that user (UID) and group (GID) instead.
-
-
Make the
greengrass-root
directory read-only by using your preferred mechanism.Note
One way to make the
greengrass-root
directory read-only is to mount the directory as read-only. However, to apply over-the-air (OTA) updates to the AWS IoT Greengrass Core software in a mounted directory, the directory must first be unmounted, and then remounted after the update. You can add theseumount
andmount
operations to theota_pre_update
andota_post_update
scripts. For more information about OTA updates, see Greengrass OTA update agent and Managed respawn with OTA updates. -
Start the daemon.
cd /
greengrass-root
/ggc/core/ sudo ./greengrassd startIf the permissions from step 1 aren't set correctly, tthe daemon won't start.
Configure MQTT settings
In the AWS IoT Greengrass environment, local client devices, Lambda functions, connectors, and system components can communicate with each other and with AWS IoT Core. All communication goes through the core, which manages the subscriptions that authorize MQTT communication between entities.
For information about MQTT settings you can configure for AWS IoT Greengrass, see the following sections:
Note
OPC-UA is an information exchange standard for industrial communication. To implement support for OPC-UA on the Greengrass core, you can use the IoT SiteWise connector. The connector sends industrial device data from OPC-UA servers to asset properties in AWS IoT SiteWise.
Message quality of service
AWS IoT Greengrass supports quality of service (QoS) levels 0 or 1, depending on your configuration and the target and direction of the communication. The Greengrass core acts as a client for communication with AWS IoT Core and a message broker for communication on the local network.
For more information about MQTT and QoS, see Getting Started
- Communication with the AWS Cloud
-
-
Outbound messages use QoS 1
The core sends messages destined for AWS Cloud targets using QoS 1. AWS IoT Greengrass uses an MQTT message queue to process these messages. If message delivery isn't confirmed by AWS IoT, the message is spooled to be retried later. The message cannot be retried if the queue is full. The message delivery confirmation can help minimize data loss from intermittent connectivity.
Because outbound messages to AWS IoT use QoS 1, the maximum rate at which the Greengrass core can send messages depends on the latency between the core and AWS IoT. Each time the core sends a message, it waits until AWS IoT acknowledges the message before it sends the next message. For example, if the round-trip time between the core and its AWS Region is 50 milliseconds, the core can send up to 20 messages per second. Consider this behavior when you choose the AWS Region where your core connects. To ingest high-volume IoT data to the AWS Cloud, you can use stream manager.
For more information about the MQTT message queue, including how to configure a local storage cache that can persist messages destined for AWS Cloud targets, see MQTT message queue for cloud targets.
-
Inbound messages use QoS 0 (default) or QoS 1
By default, the core subscribes with QoS 0 to messages from AWS Cloud sources. If you enable persistent sessions, the core subscribes with QoS 1. This can help minimize data loss from intermittent connectivity. To manage the QoS for these subscriptions, you configure persistence settings on the local spooler system component.
For more information, including how to enable the core to establish a persistent session with AWS Cloud targets, see MQTT persistent sessions with AWS IoT Core.
-
- Communication with local targets
-
All local communication uses QoS 0. The core makes one attempt to send a message to a local target, which can be a Greengrass Lambda function, connector, or client device. The core doesn't store messages or confirm delivery. Messages can be dropped anywhere between components.
Note
Although direct communication between Lambda functions doesn't use MQTT messaging, the behavior is the same.
MQTT message queue for cloud targets
MQTT messages that are destined for AWS Cloud targets are queued to await processing. Queued messages are processed in first in, first out (FIFO) order. After a message is processed and published to AWS IoT Core, the message is removed from the queue.
By default, the Greengrass core stores in memory unprocessed messages destined for AWS Cloud targets. You can configure the core to store unprocessed messages in a local storage cache instead. Unlike in-memory storage, the local storage cache has the ability to persist across core restarts (for example, after a group deployment or a device reboot), so AWS IoT Greengrass can continue to process the messages. You can also configure the storage size.
Warning
The Greengrass core might queue duplicate MQTT messages when it loses connection,
because it retries a publish operation before the MQTT client detects that it's
offline. To avoid duplicate MQTT messages for cloud targets, configure the
core's keepAlive
value to less than half of its
mqttOperationTimeout
value. For more information, see AWS IoT Greengrass core configuration file.
AWS IoT Greengrass uses the spooler system component (the GGCloudSpooler
Lambda
function) to manage the message queue. You can use the following
GGCloudSpooler
environment variables to configure storage
settings.
-
GG_CONFIG_STORAGE_TYPE. The location of the message queue. The following are valid values:
-
FileSystem
. Store unprocessed messages in the local storage cache on the disk of the physical core device. When the core restarts, queued messages are retained for processing. Messages are removed after they are processed. -
Memory
(default). Store unprocessed messages in memory. When the core restarts, queued messages are lost.This option is optimized for devices with restricted hardware capabilities. When using this configuration, we recommend that you deploy groups or restart the device when the service disruption is the lowest.
-
-
GG_CONFIG_MAX_SIZE_BYTES. The storage size, in bytes. This value can be any non-negative integer greater than or equal to 262144 (256 KB); a smaller size prevents the AWS IoT Greengrass Core software from starting. The default size is 2.5 MB. When the size limit is reached, the oldest queued messages are replaced by new messages.
Note
This feature is available for AWS IoT Greengrass Core v1.6 and later. Earlier versions use in-memory storage with a queue size of 2.5 MB. You cannot configure storage settings for earlier versions.
To cache messages in local storage
You can configure AWS IoT Greengrass to cache messages to the file system so they persist
across core restarts. To do this, you deploy a function definition version where
the GGCloudSpooler
function sets the storage type to
FileSystem
. You must use the AWS IoT Greengrass API to configure the local
storage cache. You can't do this in the console.
The following procedure uses the create-function-definition-version
CLI command to
configure the spooler to save queued messages to the file system. It also
configures a 2.6 MB queue size.
-
Get the IDs of the target Greengrass group and group version. This procedure assumes that this is the latest group and group version. The following query returns the most recently created group.
aws greengrass list-groups --query "reverse(sort_by(Groups, &CreationTimestamp))[0]"
Or, you can query by name. Group names are not required to be unique, so multiple groups might be returned.
aws greengrass list-groups --query "Groups[?Name=='
MyGroup
']"Note
You can also find these values in the AWS IoT console. The group ID is displayed on the group's Settings page. Group version IDs are displayed on the group's Deployments tab.
-
Copy the
Id
andLatestVersion
values from the target group in the output. -
Get the latest group version.
-
Replace
group-id
with theId
that you copied. -
Replace
latest-group-version-id
with theLatestVersion
that you copied.
aws greengrass get-group-version \ --group-id
group-id
\ --group-version-idlatest-group-version-id
-
-
From the
Definition
object in the output, copy theCoreDefinitionVersionArn
and the ARNs of all other group components exceptFunctionDefinitionVersionArn
. You use these values when you create a new group version. -
From the
FunctionDefinitionVersionArn
in the output, copy the ID of the function definition. The ID is the GUID that follows thefunctions
segment in the ARN, as shown in the following example.arn:aws:greengrass:us-west-2:123456789012:/greengrass/definition/functions/bcfc6b49-beb0-4396-b703-6dEXAMPLEcu5/versions/0f7337b4-922b-45c5-856f-1aEXAMPLEsf6
Note
Or, you can create a function definition by running the
create-function-definition
command, and then copying the ID from the output. -
Add a function definition version to the function definition.
-
Replace
function-definition-id
with theId
that you copied for the function definition. -
Replace
arbitrary-function-id
with a name for the function, such asspooler-function
. -
Add any Lambda functions that you want to include in this version to the
functions
array. You can use theget-function-definition-version
command to get the Greengrass Lambda functions from an existing function definition version.
Warning
Make sure that you specify a value for
GG_CONFIG_MAX_SIZE_BYTES
that's greater than or equal to 262144. A smaller size prevents the AWS IoT Greengrass Core software from starting.aws greengrass create-function-definition-version \ --function-definition-id
function-definition-id
\ --functions '[{"FunctionArn": "arn:aws:lambda:::function:GGCloudSpooler:1","FunctionConfiguration": {"Environment": {"Variables":{"GG_CONFIG_MAX_SIZE_BYTES":"2621440","GG_CONFIG_STORAGE_TYPE":"FileSystem"}},"Executable": "spooler","MemorySize": 32768,"Pinned": true,"Timeout": 3},"Id": "arbitrary-function-id
"}]'Note
If you previously set the
GG_CONFIG_SUBSCRIPTION_QUALITY
environment variable to support persistent sessions with AWS IoT Core, include it in this function instance. -
-
Copy the
Arn
of the function definition version from the output. -
Create a group version that contains the system Lambda function.
-
Replace
group-id
with theId
for the group. -
Replace
core-definition-version-arn
with theCoreDefinitionVersionArn
that you copied from the latest group version. -
Replace
function-definition-version-arn
with theArn
that you copied for the new function definition version. -
Replace the ARNs for other group components (for example,
SubscriptionDefinitionVersionArn
orDeviceDefinitionVersionArn
) that you copied from the latest group version. -
Remove any unused parameters. For example, remove the
--resource-definition-version-arn
if your group version doesn't contain any resources.
aws greengrass create-group-version \ --group-id
group-id
\ --core-definition-version-arncore-definition-version-arn
\ --function-definition-version-arnfunction-definition-version-arn
\ --device-definition-version-arndevice-definition-version-arn
\ --logger-definition-version-arnlogger-definition-version-arn
\ --resource-definition-version-arnresource-definition-version-arn
\ --subscription-definition-version-arnsubscription-definition-version-arn
-
-
Copy the
Version
from the output. This is the ID of the new group version. -
Deploy the group with the new group version.
-
Replace
group-id
with theId
that you copied for the group. -
Replace
group-version-id
with theVersion
that you copied for the new group version.
aws greengrass create-deployment \ --group-id
group-id
\ --group-version-idgroup-version-id
\ --deployment-type NewDeployment -
To update the storage settings, you use the AWS IoT Greengrass API to create a new function
definition version that contains the GGCloudSpooler
function with
the updated configuration. Then add the function definition version to a new
group version (along with your other group components) and deploy the group
version. If you want to restore the default configuration, you can deploy a
function definition version that doesn't include the GGCloudSpooler
function.
This system Lambda function isn't visible in the console. However, after the function is added to the latest group version, it's included in deployments that you make from the console, unless you use the API to replace or remove it.
MQTT persistent sessions with AWS IoT Core
This feature is available for AWS IoT Greengrass Core v1.10 and later.
A Greengrass core can establish a persistent session with the AWS IoT message broker. A persistent session is an ongoing connection that allows the core to receive messages sent while the core is offline. The core is the client in the connection.
In a persistent session, the AWS IoT message broker saves all subscriptions the core makes during the connection. If the core disconnects, the AWS IoT message broker stores unacknowledged and new messages published as QoS 1 and destined for local targets, such as Lambda functions and client devices. When the core reconnects, the persistent session is resumed and the AWS IoT message broker sends stored messages to the core at a maximum rate of 10 messages per second. Persistent sessions have a default expiry period of 1 hour, which begins when the message broker detects that the core disconnects. For more information, see MQTT persistent sessions in the AWS IoT Developer Guide.
AWS IoT Greengrass uses the spooler system component (the GGCloudSpooler
Lambda
function) to create subscriptions that have AWS IoT as the source. You can use the
following GGCloudSpooler
environment variable to configure persistent
sessions.
-
GG_CONFIG_SUBSCRIPTION_QUALITY. The quality of subscriptions that have AWS IoT as the source. The following are valid values:
-
AtMostOnce
(default). Disables persistent sessions. Subscriptions use QoS 0. -
AtLeastOncePersistent
. Enables persistent sessions. Sets thecleanSession
flag to0
inCONNECT
messages and subscribes with QoS 1.Messages published with QoS 1 that the core receives are guaranteed to reach the Greengrass daemon's in-memory work queue. The core acknowledges the message after it's added to the queue. Subsequent communication from the queue to the local target (for example, Greengrass Lambda function, connector, or device) is sent as QoS 0. AWS IoT Greengrass doesn't guarantee delivery to local targets.
Note
You can use the maxWorkItemCount configuration property to control the size of the work item queue. For example, you can increase the queue size if your workload requires heavy MQTT traffic.
When persistent sessions are enabled, the core opens at least one additional connection for MQTT message exchange with AWS IoT. For more information, see Client IDs for MQTT connections with AWS IoT.
-
To configure MQTT persistent sessions
You can configure AWS IoT Greengrass to use persistent sessions with AWS IoT Core. To do this,
you deploy a function definition version where the GGCloudSpooler
function sets the subscription quality to AtLeastOncePersistent
.
This setting applies to all your subscriptions that have AWS IoT Core
(cloud
) as the source. You must use the AWS IoT Greengrass API to configure
persistent sessions. You can't do this in the console.
The following procedure uses the create-function-definition-version
CLI command to
configure the spooler to use persistent sessions. In this procedure, we assume
that you're updating the configuration of the latest group version of an
existing group.
-
Get the IDs of the target Greengrass group and group version. This procedure assumes that this is the latest group and group version. The following query returns the most recently created group.
aws greengrass list-groups --query "reverse(sort_by(Groups, &CreationTimestamp))[0]"
Or, you can query by name. Group names are not required to be unique, so multiple groups might be returned.
aws greengrass list-groups --query "Groups[?Name=='
MyGroup
']"Note
You can also find these values in the AWS IoT console. The group ID is displayed on the group's Settings page. Group version IDs are displayed on the group's Deployments tab.
-
Copy the
Id
andLatestVersion
values from the target group in the output. -
Get the latest group version.
-
Replace
group-id
with theId
that you copied. -
Replace
latest-group-version-id
with theLatestVersion
that you copied.
aws greengrass get-group-version \ --group-id
group-id
\ --group-version-idlatest-group-version-id
-
-
From the
Definition
object in the output, copy theCoreDefinitionVersionArn
and the ARNs of all other group components exceptFunctionDefinitionVersionArn
. You use these values when you create a new group version. -
From the
FunctionDefinitionVersionArn
in the output, copy the ID of the function definition. The ID is the GUID that follows thefunctions
segment in the ARN, as shown in the following example.arn:aws:greengrass:us-west-2:123456789012:/greengrass/definition/functions/bcfc6b49-beb0-4396-b703-6dEXAMPLEcu5/versions/0f7337b4-922b-45c5-856f-1aEXAMPLEsf6
Note
Or, you can create a function definition by running the
create-function-definition
command, and then copying the ID from the output. -
Add a function definition version to the function definition.
-
Replace
function-definition-id
with theId
that you copied for the function definition. -
Replace
arbitrary-function-id
with a name for the function, such asspooler-function
. -
Add any Lambda functions that you want to include in this version to the
functions
array. You can use theget-function-definition-version
command to get the Greengrass Lambda functions from an existing function definition version.
aws greengrass create-function-definition-version \ --function-definition-id
function-definition-id
\ --functions '[{"FunctionArn": "arn:aws:lambda:::function:GGCloudSpooler:1","FunctionConfiguration": {"Environment": {"Variables":{"GG_CONFIG_SUBSCRIPTION_QUALITY":"AtLeastOncePersistent"}},"Executable": "spooler","MemorySize": 32768,"Pinned": true,"Timeout": 3},"Id": "arbitrary-function-id
"}]'Note
If you previously set the
GG_CONFIG_STORAGE_TYPE
orGG_CONFIG_MAX_SIZE_BYTES
environment variables to define storage settings, include them in this function instance. -
-
Copy the
Arn
of the function definition version from the output. -
Create a group version that contains the system Lambda function.
-
Replace
group-id
with theId
for the group. -
Replace
core-definition-version-arn
with theCoreDefinitionVersionArn
that you copied from the latest group version. -
Replace
function-definition-version-arn
with theArn
that you copied for the new function definition version. -
Replace the ARNs for other group components (for example,
SubscriptionDefinitionVersionArn
orDeviceDefinitionVersionArn
) that you copied from the latest group version. -
Remove any unused parameters. For example, remove the
--resource-definition-version-arn
if your group version doesn't contain any resources.
aws greengrass create-group-version \ --group-id
group-id
\ --core-definition-version-arncore-definition-version-arn
\ --function-definition-version-arnfunction-definition-version-arn
\ --device-definition-version-arndevice-definition-version-arn
\ --logger-definition-version-arnlogger-definition-version-arn
\ --resource-definition-version-arnresource-definition-version-arn
\ --subscription-definition-version-arnsubscription-definition-version-arn
-
-
Copy the
Version
from the output. This is the ID of the new group version. -
Deploy the group with the new group version.
-
Replace
group-id
with theId
that you copied for the group. -
Replace
group-version-id
with theVersion
that you copied for the new group version.
aws greengrass create-deployment \ --group-id
group-id
\ --group-version-idgroup-version-id
\ --deployment-type NewDeployment -
-
(Optional) Increase the maxWorkItemCount property in the core configuration file. This can help the core handle increased MQTT traffic and communication with local targets.
To update the core with these configuration changes, you use the AWS IoT Greengrass API to
create a new function definition version that contains the
GGCloudSpooler
function with the updated configuration. Then
add the function definition version to a new group version (along with your
other group components) and deploy the group version. If you want to restore the
default configuration, you can create a function definition version that doesn't
include the GGCloudSpooler
function.
This system Lambda function isn't visible in the console. However, after the function is added to the latest group version, it's included in deployments that you make from the console, unless you use the API to replace or remove it.
Client IDs for MQTT connections with AWS IoT
This feature is available for AWS IoT Greengrass Core v1.8 and later.
The Greengrass core opens MQTT connections with AWS IoT Core for operations such as shadow sync and certificate management. For these connections, the core generates predictable client IDs based on the core thing name. Predictable client IDs can be used with monitoring, auditing, and pricing features, including AWS IoT Device Defender and AWS IoT lifecycle events. You can also create logic around predictable client IDs (for example, subscribe policy templates based on certificate attributes).
Note
Duplicate client IDs used in simultaneous connections can cause an infinite connect-disconnect loop. This can happen if another device is hardcoded to use the core device name as the client ID in connections. For more information, see this troubleshooting step.
Greengrass devices are also fully integrated with the Fleet Indexing service of AWS IoT Device Management. This allows you to index and search for devices based on device attributes, shadow state, and connection state in the cloud. For example, Greengrass devices establish at least one connection that uses the thing name as the client ID, so you can use device connectivity indexing to discover which Greengrass devices are currently connected or disconnected to AWS IoT Core. For more information, see Fleet indexing service in the AWS IoT Developer Guide.
Configure the MQTT port for local messaging
This feature requires AWS IoT Greengrass Core v1.10 or later.
The Greengrass core acts as the local message broker for MQTT messaging between local Lambda functions, connectors, and client devices. By default, the core uses port 8883 for MQTT traffic on the local network. You might want to change the port to avoid a conflict with other software that runs on port 8883.
To configure the port number that the core uses for local MQTT traffic
-
Run the following command to stop the Greengrass daemon:
cd /
greengrass-root
/ggc/core/ sudo ./greengrassd stop -
Open
for editing as the su user.greengrass-root
/config/config.json -
In the
coreThing
object, add theggMqttPort
property and set the value to the port number you want to use. Valid values are 1024 to 65535. The following example sets the port number to9000
.{ "coreThing" : { "caPath" : "root.ca.pem", "certPath" : "12345abcde.cert.pem", "keyPath" : "12345abcde.private.key", "thingArn" : "arn:aws:iot:us-west-2:123456789012:thing/core-thing-name", "iotHost" : "abcd123456wxyz-ats.iot.us-west-2.amazonaws.com", "ggHost" : "greengrass-ats.iot.us-west-2.amazonaws.com",
"ggMqttPort" : 9000,
"keepAlive" : 600 }, ... } -
Start the daemon.
cd /
greengrass-root
/ggc/core/ sudo ./greengrassd start -
If automatic IP detection is enabled for the core, the configuration is complete.
If automatic IP detection is not enabled, you must update the connectivity information for the core. This allows client devices to receive the correct port number during discovery operations to acquire core connectivity information. You can use the AWS IoT console or AWS IoT Greengrass API to update the core connectivity information. For this procedure, you update the port number only. The local IP address for the core remains the same.
- To update the connectivity information for the core (console)
-
-
On the group configuration page, choose the Greengrass core.
-
On the core details page, choose the MQTT broker endpoints tab.
-
Choose Manage endpoints and then choose Add endpoint
-
Enter your current local IP address and the new port number. The following example sets the port number
9000
for the IP address192.168.1.8
. -
Remove the obsolete endpoint, and then choose Update
-
- To update the connectivity information for the core (API)
-
-
Use the UpdateConnectivityInfo action. The following example uses
update-connectivity-info
in the AWS CLI to set the port number9000
for the IP address192.168.1.8
.aws greengrass update-connectivity-info \ --thing-name "MyGroup_Core" \ --connectivity-info "[{\"Metadata\":\"\",\"PortNumber\":9000,\"HostAddress\":\"192.168.1.8\",\"Id\":\"localIP_192.168.1.8\"},{\"Metadata\":\"\",\"PortNumber\":8883,\"HostAddress\":\"127.0.0.1\",\"Id\":\"localhost_127.0.0.1_0\"}]"
-
Note
You can also configure the port that the core uses for MQTT messaging with AWS IoT Core. For more information, see Connect on port 443 or through a network proxy.
Timeout for publish, subscribe, unsubscribe operations in MQTT connections with the AWS Cloud
This feature is available in AWS IoT Greengrass v1.10.2 or later.
You can configure the amount of time (in seconds) to allow the Greengrass core to
complete a publish, subscribe, or unsubscribe operation in MQTT connections to
AWS IoT Core. You might want to adjust this setting if the operations time out because
of bandwidth constraints or high latency. To configure this setting in the config.json file, add or change the
mqttOperationTimeout
property in the coreThing
object.
For example:
{ "coreThing": { "mqttOperationTimeout": 10, "caPath": "root-ca.pem", "certPath": "
hash
.cert.pem", "keyPath": "hash
.private.key", ... }, ... }
The default timeout is 5 seconds. The minimum timeout is 5 seconds.
Activate automatic IP detection
You can configure AWS IoT Greengrass to enable client devices in a Greengrass group to automatically discover the Greengrass core. When enabled, the core watches for changes to its IP addresses. If an address changes, the core publishes an updated list of addresses. These addresses are made available to client devices that are in the same Greengrass group as the core.
Note
The AWS IoT policy for client devices must grant the
greengrass:Discover
permission to allow devices to retrieve
connectivity information for the core. For more information about the policy
statement, see Discovery authorization.
To enable this feature from the AWS IoT Greengrass console, choose Automatic detection when you deploy your Greengrass group for the first time. You can also enable or disable this feature on the group configuration page by choosing the Lambda functions tab and selecting the IP detector. Automatic IP detection is enabled if Automatically detect and override MQTT broker endpoints is selected.
To manage automatic discovery with the AWS IoT Greengrass API, you must configure the
IPDetector
system Lambda function. The following procedure shows how to
use the create-function-definition-version CLI command to configure automatic
discovery of the Greengrass core.
-
Get the IDs of the target Greengrass group and group version. This procedure assumes that this is the latest group and group version. The following query returns the most recently created group.
aws greengrass list-groups --query "reverse(sort_by(Groups, &CreationTimestamp))[0]"
Or, you can query by name. Group names are not required to be unique, so multiple groups might be returned.
aws greengrass list-groups --query "Groups[?Name=='
MyGroup
']"Note
You can also find these values in the AWS IoT console. The group ID is displayed on the group's Settings page. Group version IDs are displayed on the group's Deployments tab.
-
Copy the
Id
andLatestVersion
values from the target group in the output. -
Get the latest group version.
-
Replace
group-id
with theId
that you copied. -
Replace
latest-group-version-id
with theLatestVersion
that you copied.
aws greengrass get-group-version \ --group-id
group-id
\ --group-version-idlatest-group-version-id
-
-
From the
Definition
object in the output, copy theCoreDefinitionVersionArn
and the ARNs of all other group components exceptFunctionDefinitionVersionArn
. You use these values when you create a new group version. -
From the
FunctionDefinitionVersionArn
in the output, copy the ID of the function definition and the function definition version:arn:aws:greengrass:
region
:account-id
:/greengrass/groups/function-definition-id
/versions/function-definition-version-id
Note
You can optionally create a function definition by running the
create-function-definition
command, and then copy the ID from the output. -
Use the
get-function-definition-version
command to get the current definition state. Use thefunction-definition-id
you copied for the function definiton. For example,4d941bc7-92a1-4f45-8d64-EXAMPLEf76c3
.aws greengrass get-function-definition-version --function-definition-id
function-definition-id
--function-definition-version-idfunction-definition-version-id
Make a note of the listed function configurations. You will need to include these when creating a new function definition version in order to prevent loss of your current definition settings.
-
Add a function definition version to the function definition.
-
Replace
function-definition-id
with theId
that you copied for the function definition. For example,4d941bc7-92a1-4f45-8d64-EXAMPLEf76c3
. -
Replace
arbitrary-function-id
with a name for the function, such asauto-detection-function
. -
Add all Lambda functions that you want to include in this version to the
functions
array, such as any listed in the previous step.
aws greengrass create-function-definition-version \ --function-definition-id
function-definition-id
\ --functions '[{"FunctionArn":"arn:aws:lambda:::function:GGIPDetector:1","Id":"arbitrary-function-id
","FunctionConfiguration":{"Pinned":true,"MemorySize":32768,"Timeout":3}}]'\ --region us-west-2 -
-
Copy the
Arn
of the function definition version from the output. -
Create a group version that contains the system Lambda function.
-
Replace
group-id
with theId
for the group. -
Replace
core-definition-version-arn
with theCoreDefinitionVersionArn
that you copied from the latest group version. -
Replace
function-definition-version-arn
with theArn
that you copied for the new function definition version. -
Replace the ARNs for other group components (for example,
SubscriptionDefinitionVersionArn
orDeviceDefinitionVersionArn
) that you copied from the latest group version. -
Remove any unused parameters. For example, remove the
--resource-definition-version-arn
if your group version doesn't contain any resources.
aws greengrass create-group-version \ --group-id
group-id
\ --core-definition-version-arncore-definition-version-arn
\ --function-definition-version-arnfunction-definition-version-arn
\ --device-definition-version-arndevice-definition-version-arn
\ --logger-definition-version-arnlogger-definition-version-arn
\ --resource-definition-version-arnresource-definition-version-arn
\ --subscription-definition-version-arnsubscription-definition-version-arn
-
-
Copy the
Version
from the output. This is the ID of the new group version. -
Deploy the group with the new group version.
-
Replace
group-id
with theId
that you copied for the group. -
Replace
group-version-id
with theVersion
that you copied for the new group version.
aws greengrass create-deployment \ --group-id
group-id
\ --group-version-idgroup-version-id
\ --deployment-type NewDeployment -
If you want to manually input the IP address of your Greengrass core, you can
complete this tutorial with a different function definition that does not include the
IPDetector
function. This will prevent the detection function from
locating and automatically inputting your Greengrass core IP address.
This system Lambda function isn't visible in the Lambda console. After the function is added to the latest group version, it's included in deployments that you make from the console, unless you use the API to replace or remove it.
Configure the init system to start the Greengrass daemon
It's a good practice to set up your init system to start the Greengrass daemon during boot, especially when managing large fleets of devices.
Note
If you used apt
to install the AWS IoT Greengrass Core software, you can use the
systemd scripts to enable start on boot. For more information, see Use systemd scripts to manage the
Greengrass daemon lifecycle.
There are different types of init system, such as initd, systemd, and SystemV, and
they use similar configuration parameters. The following example is a service file for
systemd. The Type
parameter is set to forking
because
greengrassd (which is used to start Greengrass) forks the Greengrass daemon process, and
the Restart
parameter is set to on-failure
to direct systemd
to restart Greengrass if Greengrass enters a failed state.
Note
To see if your device uses systemd, run the check_ggc_dependencies
script as described in Module 1. Then to use systemd,
make sure that the useSystemd
parameter in config.json is set to yes
.
[Unit] Description=Greengrass Daemon [Service] Type=forking PIDFile=/var/run/greengrassd.pid Restart=on-failure ExecStart=/greengrass/ggc/core/greengrassd start ExecReload=/greengrass/ggc/core/greengrassd restart ExecStop=/greengrass/ggc/core/greengrassd stop [Install] WantedBy=multi-user.target