AWS IoT Greengrass
Developer Guide

Configure the AWS IoT Greengrass Core

An AWS IoT Greengrass core is an AWS IoT thing (device). 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. 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 local execution 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 cloud using device authentication and authorization.

  • Local shadow synchronization of devices. Shadows can be configured to sync with the 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 /greengrass-root/config directory.

Note

greengrass-root represents the path where the AWS IoT Greengrass Core software is installed on your device. If you installed the software by following the steps in the Getting Started tutorial, then this is the /greengrass directory.

If you use the Easy 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.

GGC v1.10GGC v1.9GGC v1.8GGC v1.7Deprecated versions
GGC v1.10
{ "coreThing" : { "caPath" : "root.ca.pem", "certPath" : "hash.cert.pem", "keyPath" : "hash.private.key", "thingArn" : "arn:partition:iot:region:account-id:thing/core-thing-name", "iotHost" : "host-prefix-ats.iot.region.amazonaws.com", "ggHost" : "greengrass-ats.iot.region.amazonaws.com", "keepAlive" : 600 }, "runtime" : { "maxWorkItemCount" : 1024, "cgroup" : { "useSystemd" : "yes" } }, "managedRespawn" : false, "crypto" : { "principals" : { "SecretsManager" : { "privateKeyPath" : "file:///greengrass/certs/hash.private.key" }, "IoTCertificate" : { "privateKeyPath" : "file:///greengrass/certs/hash.private.key", "certificatePath" : "file:///greengrass/certs/hash.cert.pem" } }, "caPath" : "file:///greengrass/certs/root.ca.pem" } }

The config.json file supports the following properties:

coreThing

Field Description Notes
caPath

The path to the AWS IoT root CA relative to the /greengrass-root/certs directory.

For backward compatibility with versions earlier than 1.7.0. This property is ignored when the crypto object is present.

certPath

The path to the core device certificate relative to the /greengrass-root/certs directory.

For backward compatibility with versions earlier than 1.7.0. This property is ignored when the crypto object is present.
keyPath The path to the core private key relative to /greengrass-root/certs directory. For backward compatibility with versions earlier than 1.7.0. This property is ignored when the crypto object is present.
thingArn The Amazon Resource Name (ARN) of the AWS IoT thing that represents the AWS IoT Greengrass core device. Find this for your core in the AWS IoT Greengrass console under Cores, or by running the aws greengrass get-core-definition-version CLI command.
iotHost Your AWS IoT endpoint.

Find this in the AWS IoT console under Settings, or by running the aws iot describe-endpoint --endpoint-type iot:Data-ATS CLI command.

This command returns the Amazon Trust Services (ATS) endpoint. For more information, see the Server Authentication documentation.

ggHost Your AWS IoT Greengrass endpoint.

This is your iotHost endpoint with the host prefix replaced by greengrass (for example, greengrass-ats.iot.region.amazonaws.com). Use the same AWS Region as iotHost.

iotMqttPort Optional. The port number to use for MQTT communication with AWS IoT. Valid values are 8883 or 443. The default value is 8883. For more information, see Connect on Port 443 or Through a Network Proxy.
iotHttpPort Optional. The port number used to create HTTPS connections to AWS IoT. Valid values are 8443 or 443. The default value is 8443. For more information, see Connect on Port 443 or Through a Network Proxy.
ggMqttPort Optional. The port number to use for MQTT communication over the local network. Valid values are 1024 through 65535. The default value is 8883. For more information, see Configure the MQTT Port for Local Messaging.
ggHttpPort Optional. The port number used to create HTTPS connections to the AWS IoT Greengrass service. Valid values are 8443 or 443. The default value is 8443. For more information, see Connect on Port 443 or Through a Network Proxy.
keepAlive Optional. The MQTT KeepAlive period, in seconds. Valid range is between 30 and 1200 seconds. The default value is 600.
networkProxy Optional. An object that defines a proxy server to connect to. This can be an HTTP or HTTPS proxy. For more information, see Connect on Port 443 or Through a Network Proxy.

runtime

Field Description Notes
maxWorkItemCount

Optional. The maximum number of work items that the Greengrass daemon can process at a time. Work items that exceed this limit are ignored.

The work item queue is shared by system components, user-defined Lambda functions, and connectors.

The default value is 1024. The maximum value is limited by your device hardware.

Increasing this value increases the memory that AWS IoT Greengrass uses. You can increase this value if you expect your core to receive heavy MQTT message traffic.

postStartHealthCheckTimeout Optional. The time (in milliseconds) after starting that the Greengrass daemon waits for the health check to finish. The default timeout is 30 seconds (30000 ms).
cgroup
useSystemd Indicates whether your device uses systemd. Valid values are yes or no. Run the check_ggc_dependencies script in Module 1 to see if your device uses systemd.

crypto

The crypto contains properties that support private key storage on a hardware security module (HSM) through PKCS#11 and local secret storage. For more information, see AWS IoT Greengrass Core Security Principals, Hardware Security Integration, and Deploy Secrets to the AWS IoT Greengrass Core. Configurations for private key storage on HSMs or in the file system are supported.

Field Description Notes
caPath

The absolute path to the AWS IoT root CA.

Must be a file URI of the form: file:///absolute/path/to/file.

PKCS11
OpenSSLEngine

Optional. The absolute path to the OpenSSL engine .so file to enable PKCS#11 support on OpenSSL.

Must be a path to a file on the file system.

This property is required if you're using the Greengrass OTA update agent with hardware security. For more information, see Configure Support for Over-the-Air Updates.

P11Provider

The absolute path to the PKCS#11 implementation's libdl-loadable library.

Must be a path to a file on the file system.

slotLabel

The slot label that's used to identify the hardware module.

Must conform to PKCS#11 label specifications.

slotUserPin

The user pin that's used to authenticate the Greengrass core to the module.

Must have sufficient permissions to perform C_Sign with the configured private keys.

principals
IoTCertificate The certificate and private key that the core uses to make requests to AWS IoT.
IoTCertificate  .privateKeyPath

The path to the core private key.

For file system storage, must be a file URI of the form: file:///absolute/path/to/file.

For HSM storage, must be an RFC 7512 PKCS#11 path that specifies the object label.

IoTCertificate  .certificatePath

The absolute path to the core device certificate.

Must be a file URI of the form: file:///absolute/path/to/file.

MQTTServerCertificate

Optional. The private key that the core uses in combination with the certificate to act as an MQTT server or gateway.

MQTTServerCertificate  .privateKeyPath

The path to the local MQTT server private key.

Use this value to specify your own private key for the local MQTT server.

For file system storage, must be a file URI of the form: file:///absolute/path/to/file.

For HSM storage, must be an RFC 7512 PKCS#11 path that specifies the object label.

If this property is omitted, AWS IoT Greengrass rotates the key based your rotation settings. If specified, the customer is responsible for rotating the key.

SecretsManager The private key that secures the data key used for encryption. For more information, see Deploy Secrets to the AWS IoT Greengrass Core.
SecretsManager  .privateKeyPath

The path to the local secrets manager private key.

Only an RSA key is supported.

For file system storage, must be a file URI of the form: file:///absolute/path/to/file.

For HSM storage, must be an RFC 7512 PKCS#11 path that specifies the object label. The private key must be generated using the PKCS#1 v1.5 padding mechanism.

The following configuration properties are also supported:

Field Description Notes

mqttMaxConnectionRetryInterval

Optional. The maximum interval (in seconds) between MQTT connection retries if the connection is dropped.

Specify this value as an unsigned integer. The default is 60.

managedRespawn

Optional. Indicates that the OTA agent needs to run custom code before an update.

Valid values are true or false. For more information, see OTA Updates of AWS IoT Greengrass Core Software.

writeDirectory

Optional. The write directory where AWS IoT Greengrass creates all read-write resources.

For more information, see Configure a Write Directory for AWS IoT Greengrass.

GGC v1.9
{ "coreThing" : { "caPath" : "root.ca.pem", "certPath" : "hash.cert.pem", "keyPath" : "hash.private.key", "thingArn" : "arn:partition:iot:region:account-id:thing/core-thing-name", "iotHost" : "host-prefix-ats.iot.region.amazonaws.com", "ggHost" : "greengrass-ats.iot.region.amazonaws.com", "keepAlive" : 600 }, "runtime" : { "cgroup" : { "useSystemd" : "yes" } }, "managedRespawn" : false, "crypto" : { "principals" : { "SecretsManager" : { "privateKeyPath" : "file:///greengrass/certs/hash.private.key" }, "IoTCertificate" : { "privateKeyPath" : "file:///greengrass/certs/hash.private.key", "certificatePath" : "file:///greengrass/certs/hash.cert.pem" } }, "caPath" : "file:///greengrass/certs/root.ca.pem" } }

The config.json file supports the following properties:

coreThing

Field Description Notes
caPath

The path to the AWS IoT root CA relative to the /greengrass-root/certs directory.

For backward compatibility with versions earlier than 1.7.0. This property is ignored when the crypto object is present.

certPath

The path to the core device certificate relative to the /greengrass-root/certs directory.

For backward compatibility with versions earlier than 1.7.0. This property is ignored when the crypto object is present.
keyPath The path to the core private key relative to /greengrass-root/certs directory. For backward compatibility with versions earlier than 1.7.0. This property is ignored when the crypto object is present.
thingArn The Amazon Resource Name (ARN) of the AWS IoT thing that represents the AWS IoT Greengrass core device. Find this for your core in the AWS IoT Greengrass console under Cores, or by running the aws greengrass get-core-definition-version CLI command.
iotHost Your AWS IoT endpoint.

Find this in the AWS IoT console under Settings, or by running the aws iot describe-endpoint --endpoint-type iot:Data-ATS CLI command.

This command returns the Amazon Trust Services (ATS) endpoint. For more information, see the Server Authentication documentation.

ggHost Your AWS IoT Greengrass endpoint.

This is your iotHost endpoint with the host prefix replaced by greengrass (for example, greengrass-ats.iot.region.amazonaws.com). Use the same AWS Region as iotHost.

iotMqttPort Optional. The port number to use for MQTT communication with AWS IoT. Valid values are 8883 or 443. The default value is 8883. For more information, see Connect on Port 443 or Through a Network Proxy.
iotHttpPort Optional. The port number used to create HTTPS connections to AWS IoT. Valid values are 8443 or 443. The default value is 8443. For more information, see Connect on Port 443 or Through a Network Proxy.
ggHttpPort Optional. The port number used to create HTTPS connections to the AWS IoT Greengrass service. Valid values are 8443 or 443. The default value is 8443. For more information, see Connect on Port 443 or Through a Network Proxy.
keepAlive Optional. The MQTT KeepAlive period, in seconds. Valid range is between 30 and 1200 seconds. The default value is 600.
networkProxy Optional. An object that defines a proxy server to connect to. This can be an HTTP or HTTPS proxy. For more information, see Connect on Port 443 or Through a Network Proxy.

runtime

Field Description Notes
postStartHealthCheckTimeout Optional. The time (in milliseconds) after starting that the Greengrass daemon waits for the health check to finish. The default timeout is 30 seconds (30000 ms).
cgroup
useSystemd Indicates whether your device uses systemd. Valid values are yes or no. Run the check_ggc_dependencies script in Module 1 to see if your device uses systemd.

crypto

The crypto object is added in v1.7.0. It introduces properties that support private key storage on a hardware security module (HSM) through PKCS#11 and local secret storage. For more information, see AWS IoT Greengrass Core Security Principals, Hardware Security Integration, and Deploy Secrets to the AWS IoT Greengrass Core. Configurations for private key storage on HSMs or in the file system are supported.

Field Description Notes
caPath

The absolute path to the AWS IoT root CA.

Must be a file URI of the form: file:///absolute/path/to/file.

PKCS11
OpenSSLEngine

Optional. The absolute path to the OpenSSL engine .so file to enable PKCS#11 support on OpenSSL.

Must be a path to a file on the file system.

This property is required if you're using the Greengrass OTA update agent with hardware security. For more information, see Configure Support for Over-the-Air Updates.

P11Provider

The absolute path to the PKCS#11 implementation's libdl-loadable library.

Must be a path to a file on the file system.

slotLabel

The slot label that's used to identify the hardware module.

Must conform to PKCS#11 label specifications.

slotUserPin

The user pin that's used to authenticate the Greengrass core to the module.

Must have sufficient permissions to perform C_Sign with the configured private keys.

principals
IoTCertificate The certificate and private key that the core uses to make requests to AWS IoT.
IoTCertificate  .privateKeyPath

The path to the core private key.

For file system storage, must be a file URI of the form: file:///absolute/path/to/file.

For HSM storage, must be an RFC 7512 PKCS#11 path that specifies the object label.

IoTCertificate  .certificatePath

The absolute path to the core device certificate.

Must be a file URI of the form: file:///absolute/path/to/file.

MQTTServerCertificate

Optional. The private key that the core uses in combination with the certificate to act as an MQTT server or gateway.

MQTTServerCertificate  .privateKeyPath

The path to the local MQTT server private key.

Use this value to specify your own private key for the local MQTT server.

For file system storage, must be a file URI of the form: file:///absolute/path/to/file.

For HSM storage, must be an RFC 7512 PKCS#11 path that specifies the object label.

If this property is omitted, AWS IoT Greengrass rotates the key based your rotation settings. If specified, the customer is responsible for rotating the key.

SecretsManager The private key that secures the data key used for encryption. For more information, see Deploy Secrets to the AWS IoT Greengrass Core.
SecretsManager  .privateKeyPath

The path to the local secrets manager private key.

Only an RSA key is supported.

For file system storage, must be a file URI of the form: file:///absolute/path/to/file.

For HSM storage, must be an RFC 7512 PKCS#11 path that specifies the object label. The private key must be generated using the PKCS#1 v1.5 padding mechanism.

The following configuration properties are also supported:

Field Description Notes

mqttMaxConnectionRetryInterval

Optional. The maximum interval (in seconds) between MQTT connection retries if the connection is dropped.

Specify this value as an unsigned integer. The default is 60.

managedRespawn

Optional. Indicates that the OTA agent needs to run custom code before an update.

Valid values are true or false. For more information, see OTA Updates of AWS IoT Greengrass Core Software.

writeDirectory

Optional. The write directory where AWS IoT Greengrass creates all read-write resources.

For more information, see Configure a Write Directory for AWS IoT Greengrass.

GGC v1.8
{ "coreThing" : { "caPath" : "root.ca.pem", "certPath" : "hash.cert.pem", "keyPath" : "hash.private.key", "thingArn" : "arn:aws:iot:region:account-id:thing/core-thing-name", "iotHost" : "host-prefix-ats.iot.region.amazonaws.com", "ggHost" : "greengrass-ats.iot.region.amazonaws.com", "keepAlive" : 600 }, "runtime" : { "cgroup" : { "useSystemd" : "yes" } }, "managedRespawn" : false, "crypto" : { "principals" : { "SecretsManager" : { "privateKeyPath" : "file:///greengrass/certs/hash.private.key" }, "IoTCertificate" : { "privateKeyPath" : "file:///greengrass/certs/hash.private.key", "certificatePath" : "file:///greengrass/certs/hash.cert.pem" } }, "caPath" : "file:///greengrass/certs/root.ca.pem" } }

The config.json file supports the following properties:

coreThing

Field Description Notes
caPath

The path to the AWS IoT root CA relative to the /greengrass-root/certs directory.

For backward compatibility with versions earlier than 1.7.0. This property is ignored when the crypto object is present.

certPath

The path to the core device certificate relative to the /greengrass-root/certs directory.

For backward compatibility with versions earlier than 1.7.0. This property is ignored when the crypto object is present.
keyPath The path to the core private key relative to /greengrass-root/certs directory. For backward compatibility with versions earlier than 1.7.0. This property is ignored when the crypto object is present.
thingArn The Amazon Resource Name (ARN) of the AWS IoT thing that represents the AWS IoT Greengrass core device. Find this for your core in the AWS IoT Greengrass console under Cores, or by running the aws greengrass get-core-definition-version CLI command.
iotHost Your AWS IoT endpoint.

Find this in the AWS IoT console under Settings, or by running the aws iot describe-endpoint --endpoint-type iot:Data-ATS CLI command.

This command returns the Amazon Trust Services (ATS) endpoint. For more information, see the Server Authentication documentation.

ggHost Your AWS IoT Greengrass endpoint.

This is your iotHost endpoint with the host prefix replaced by greengrass (for example, greengrass-ats.iot.region.amazonaws.com). Use the same AWS Region as iotHost.

iotMqttPort Optional. The port number to use for MQTT communication with AWS IoT. Valid values are 8883 or 443. The default value is 8883. For more information, see Connect on Port 443 or Through a Network Proxy.
iotHttpPort Optional. The port number used to create HTTPS connections to AWS IoT. Valid values are 8443 or 443. The default value is 8443. For more information, see Connect on Port 443 or Through a Network Proxy.
ggHttpPort Optional. The port number used to create HTTPS connections to the AWS IoT Greengrass service. Valid values are 8443 or 443. The default value is 8443. For more information, see Connect on Port 443 or Through a Network Proxy.
keepAlive Optional. The MQTT KeepAlive period, in seconds. Valid range is between 30 and 1200 seconds. The default value is 600.
networkProxy Optional. An object that defines a proxy server to connect to. This can be an HTTP or HTTPS proxy. For more information, see Connect on Port 443 or Through a Network Proxy.

runtime

Field Description Notes
cgroup
useSystemd Indicates whether your device uses systemd. Valid values are yes or no. Run the check_ggc_dependencies script in Module 1 to see if your device uses systemd.

crypto

The crypto object is added in v1.7.0. It introduces properties that support private key storage on a hardware security module (HSM) through PKCS#11 and local secret storage. For more information, see AWS IoT Greengrass Core Security Principals, Hardware Security Integration, and Deploy Secrets to the AWS IoT Greengrass Core. Configurations for private key storage on HSMs or in the file system are supported.

Field Description Notes
caPath

The absolute path to the AWS IoT root CA.

Must be a file URI of the form: file:///absolute/path/to/file.

PKCS11
OpenSSLEngine

Optional. The absolute path to the OpenSSL engine .so file to enable PKCS#11 support on OpenSSL.

Must be a path to a file on the file system.

This property is required if you're using the Greengrass OTA update agent with hardware security. For more information, see Configure Support for Over-the-Air Updates.

P11Provider

The absolute path to the PKCS#11 implementation's libdl-loadable library.

Must be a path to a file on the file system.

slotLabel

The slot label that's used to identify the hardware module.

Must conform to PKCS#11 label specifications.

slotUserPin

The user pin that's used to authenticate the Greengrass core to the module.

Must have sufficient permissions to perform C_Sign with the configured private keys.

principals
IoTCertificate The certificate and private key that the core uses to make requests to AWS IoT.
IoTCertificate  .privateKeyPath

The path to the core private key.

For file system storage, must be a file URI of the form: file:///absolute/path/to/file.

For HSM storage, must be an RFC 7512 PKCS#11 path that specifies the object label.

IoTCertificate  .certificatePath

The absolute path to the core device certificate.

Must be a file URI of the form: file:///absolute/path/to/file.

MQTTServerCertificate

Optional. The private key that the core uses in combination with the certificate to act as an MQTT server or gateway.

MQTTServerCertificate  .privateKeyPath

The path to the local MQTT server private key.

Use this value to specify your own private key for the local MQTT server.

For file system storage, must be a file URI of the form: file:///absolute/path/to/file.

For HSM storage, must be an RFC 7512 PKCS#11 path that specifies the object label.

If this property is omitted, AWS IoT Greengrass rotates the key based your rotation settings. If specified, the customer is responsible for rotating the key.

SecretsManager The private key that secures the data key used for encryption. For more information, see Deploy Secrets to the AWS IoT Greengrass Core.
SecretsManager  .privateKeyPath

The path to the local secrets manager private key.

Only an RSA key is supported.

For file system storage, must be a file URI of the form: file:///absolute/path/to/file.

For HSM storage, must be an RFC 7512 PKCS#11 path that specifies the object label. The private key must be generated using the PKCS#1 v1.5 padding mechanism.

The following configuration properties are also supported:

Field Description Notes

mqttMaxConnectionRetryInterval

Optional. The maximum interval (in seconds) between MQTT connection retries if the connection is dropped.

Specify this value as an unsigned integer. The default is 60.

managedRespawn

Optional. Indicates that the OTA agent needs to run custom code before an update.

Valid values are true or false. For more information, see OTA Updates of AWS IoT Greengrass Core Software.

writeDirectory

Optional. The write directory where AWS IoT Greengrass creates all read-write resources.

For more information, see Configure a Write Directory for AWS IoT Greengrass.

GGC v1.7
{ "coreThing" : { "caPath" : "root.ca.pem", "certPath" : "hash.cert.pem", "keyPath" : "hash.private.key", "thingArn" : "arn:aws:iot:region:account-id:thing/core-thing-name", "iotHost" : "host-prefix-ats.iot.region.amazonaws.com", "ggHost" : "greengrass-ats.iot.region.amazonaws.com", "keepAlive" : 600 }, "runtime" : { "cgroup" : { "useSystemd" : "yes" } }, "managedRespawn" : false, "crypto" : { "principals" : { "SecretsManager" : { "privateKeyPath" : "file:///greengrass/certs/hash.private.key" }, "IoTCertificate" : { "privateKeyPath" : "file:///greengrass/certs/hash.private.key", "certificatePath" : "file:///greengrass/certs/hash.cert.pem" } }, "caPath" : "file:///greengrass/certs/root.ca.pem" } }

The config.json file supports the following properties:

coreThing

Field Description Notes
caPath

The path to the AWS IoT root CA relative to the /greengrass-root/certs directory.

For backward compatibility with versions earlier than 1.7.0. This property is ignored when the crypto object is present.

certPath

The path to the core device certificate relative to the /greengrass-root/certs directory.

For backward compatibility with versions earlier than 1.7.0. This property is ignored when the crypto object is present.
keyPath The path to the core private key relative to /greengrass-root/certs directory. For backward compatibility with versions earlier than 1.7.0. This property is ignored when the crypto object is present.
thingArn The Amazon Resource Name (ARN) of the AWS IoT thing that represents the AWS IoT Greengrass core device. Find this for your core in the AWS IoT Greengrass console under Cores, or by running the aws greengrass get-core-definition-version CLI command.
iotHost Your AWS IoT endpoint.

Find this in the AWS IoT console under Settings, or by running the aws iot describe-endpoint --endpoint-type iot:Data-ATS CLI command.

This command returns the Amazon Trust Services (ATS) endpoint. For more information, see the Server Authentication documentation.

ggHost Your AWS IoT Greengrass endpoint.

This is your iotHost endpoint with the host prefix replaced by greengrass (for example, greengrass-ats.iot.region.amazonaws.com). Use the same AWS Region as iotHost.

iotMqttPort Optional. The port number to use for MQTT communication with AWS IoT. Valid values are 8883 or 443. The default value is 8883. For more information, see Connect on Port 443 or Through a Network Proxy.
keepAlive Optional. The MQTT KeepAlive period, in seconds. Valid range is between 30 and 1200 seconds. The default value is 600.
networkProxy Optional. An object that defines a proxy server to connect to. This can be an HTTP or HTTPS proxy. For more information, see Connect on Port 443 or Through a Network Proxy.

runtime

Field Description Notes
cgroup
useSystemd Indicates whether your device uses systemd. Valid values are yes or no. Run the check_ggc_dependencies script in Module 1 to see if your device uses systemd.

crypto

The crypto object, added in v1.7.0, introduces properties that support private key storage on a hardware security module (HSM) through PKCS#11 and local secret storage. For more information, see Hardware Security Integration and Deploy Secrets to the AWS IoT Greengrass Core. Configurations for private key storage on HSMs or in the file system are supported.

Field Description Notes
caPath

The absolute path to the AWS IoT root CA.

Must be a file URI of the form: file:///absolute/path/to/file.

PKCS11
OpenSSLEngine

Optional. The absolute path to the OpenSSL engine .so file to enable PKCS#11 support on OpenSSL.

Must be a path to a file on the file system.

This property is required if you're using the Greengrass OTA update agent with hardware security. For more information, see Configure Support for Over-the-Air Updates.

P11Provider

The absolute path to the PKCS#11 implementation's libdl-loadable library.

Must be a path to a file on the file system.

slotLabel

The slot label that's used to identify the hardware module.

Must conform to PKCS#11 label specifications.

slotUserPin

The user pin that's used to authenticate the Greengrass core to the module.

Must have sufficient permissions to perform C_Sign with the configured private keys.

principals
IoTCertificate The certificate and private key that the core uses to make requests to AWS IoT.
IoTCertificate  .privateKeyPath

The path to the core private key.

For file system storage, must be a file URI of the form: file:///absolute/path/to/file.

For HSM storage, must be an RFC 7512 PKCS#11 path that specifies the object label.

IoTCertificate  .certificatePath

The absolute path to the core device certificate.

Must be a file URI of the form: file:///absolute/path/to/file.

MQTTServerCertificate

Optional. The private key that the core uses in combination with the certificate to act as an MQTT server or gateway.

MQTTServerCertificate  .privateKeyPath

The path to the local MQTT server private key.

Use this value to specify your own private key for the local MQTT server.

For file system storage, must be a file URI of the form: file:///absolute/path/to/file.

For HSM storage, must be an RFC 7512 PKCS#11 path that specifies the object label.

If this property is omitted, AWS IoT Greengrass rotates the key based your rotation settings. If specified, the customer is responsible for rotating the key.

SecretsManager The private key that secures the data key used for encryption. For more information, see Deploy Secrets to the AWS IoT Greengrass Core.
SecretsManager  .privateKeyPath

The path to the local secrets manager private key.

Only an RSA key is supported.

For file system storage, must be a file URI of the form: file:///absolute/path/to/file.

For HSM storage, must be an RFC 7512 PKCS#11 path that specifies the object label. The private key must be generated using the PKCS#1 v1.5 padding mechanism.

The following configuration properties are also supported:

Field Description Notes

mqttMaxConnectionRetryInterval

Optional. The maximum interval (in seconds) between MQTT connection retries if the connection is dropped.

Specify this value as an unsigned integer. The default is 60.

managedRespawn

Optional. Indicates that the OTA agent needs to run custom code before an update.

Valid values are true or false. For more information, see OTA Updates of AWS IoT Greengrass Core Software.

writeDirectory

Optional. The write directory where AWS IoT Greengrass creates all read-write resources.

For more information, see Configure a Write Directory for AWS IoT Greengrass.

Deprecated versions

The following versions of the AWS IoT Greengrass Core software are not supported. This information is included for reference purposes only.

GGC v1.6GGC v1.5GGC v1.3GGC v1.1GGC v1.0
GGC v1.6
{ "coreThing": { "caPath": "root-ca-pem", "certPath": "cloud-pem-crt", "keyPath": "cloud-pem-key", "thingArn": "arn:aws:iot:region:account-id:thing/core-thing-name", "iotHost": "host-prefix.iot.region.amazonaws.com", "ggHost": "greengrass.iot.region.amazonaws.com", "keepAlive": 600, "mqttMaxConnectionRetryInterval": 60 }, "runtime": { "cgroup": { "useSystemd": "yes|no" } }, "managedRespawn": true, "writeDirectory": "/write-directory" }

Note

If you use the Easy group creation option from the AWS IoT Greengrass console, then the config.json file is deployed to the core device in a working state that specifies the default configuration.

The config.json file supports the following properties:

Field Description Notes
caPath

The path to the AWS IoT root CA relative to the /greengrass-root/certs directory.

Save the file under /greengrass-root/certs.

certPath

The path to the AWS IoT Greengrass core certificate relative to the /greengrass-root/certs directory.

Save the file under /greengrass-root/certs.
keyPath The path to the AWS IoT Greengrass core private key relative to /greengrass-root/certs directory. Save the file under /greengrass-root/certs.
thingArn The Amazon Resource Name (ARN) of the AWS IoT thing that represents the AWS IoT Greengrass core device. Find this for your core in the AWS IoT Greengrass console under Cores, or by running the aws greengrass get-core-definition-version CLI command.
iotHost Your AWS IoT endpoint. Find this in the AWS IoT console under Settings, or by running the aws iot describe-endpoint CLI command.
ggHost Your AWS IoT Greengrass endpoint. This value uses the format greengrass.iot.region.amazonaws.com. Use the same region as iotHost.
keepAlive The MQTT KeepAlive period, in seconds. This is an optional value. The default is 600.

mqttMaxConnectionRetryInterval

The maximum interval (in seconds) between MQTT connection retries if the connection is dropped.

Specify this value as an unsigned integer. This is an optional value. The default is 60.

useSystemd Indicates whether your device uses systemd. Valid values are yes or no. Run the check_ggc_dependencies script in Module 1 to see if your device uses systemd.

managedRespawn

An optional over-the-air (OTA) updates feature, this indicates that the OTA agent needs to run custom code before an update.

Valid values are true or false. For more information, see OTA Updates of AWS IoT Greengrass Core Software.

writeDirectory

The write directory where AWS IoT Greengrass creates all read-write resources.

This is an optional value. For more information, see Configure a Write Directory for AWS IoT Greengrass.

GGC v1.5
{ "coreThing": { "caPath": "root-ca-pem", "certPath": "cloud-pem-crt", "keyPath": "cloud-pem-key", "thingArn": "arn:aws:iot:region:account-id:thing/core-thing-name", "iotHost": "host-prefix.iot.region.amazonaws.com", "ggHost": "greengrass.iot.region.amazonaws.com", "keepAlive": 600 }, "runtime": { "cgroup": { "useSystemd": "yes|no" } }, "managedRespawn": true }

The config.json file exists in /greengrass-root/config and contains the following parameters:

Field Description Notes
caPath

The path to the AWS IoT root CA relative to the /greengrass-root/certs folder.

Save the file under the /greengrass-root/certs folder.

certPath

The path to the AWS IoT Greengrass core certificate relative to the /greengrass-root/certs folder.

Save the file under the /greengrass-root/certs folder.
keyPath The path to the AWS IoT Greengrass core private key relative to /greengrass-root/certs folder. Save the file under the /greengrass-root/certs folder.
thingArn The Amazon Resource Name (ARN) of the AWS IoT thing that represents the AWS IoT Greengrass core device. Find this for your core in the AWS IoT Greengrass console under Cores, or by running the aws greengrass get-core-definition-version CLI command.
iotHost Your AWS IoT endpoint. Find this in the AWS IoT console under Settings, or by running the aws iot describe-endpoint command.
ggHost Your AWS IoT Greengrass endpoint. This value uses the format greengrass.iot.region.amazonaws.com. Use the same region as iotHost.
keepAlive The MQTT KeepAlive period, in seconds. This is an optional value. The default value is 600 seconds.
useSystemd Indicates whether your device uses systemd. Valid values are yes or no. Run the check_ggc_dependencies script in Module 1 to see if your device uses systemd.

managedRespawn

An optional over-the-air (OTA) updates feature, this indicates that the OTA agent needs to run custom code before an update.

For more information, see OTA Updates of AWS IoT Greengrass Core Software.

GGC v1.3
{ "coreThing": { "caPath": "root-ca-pem", "certPath": "cloud-pem-crt", "keyPath": "cloud-pem-key", "thingArn": "arn:aws:iot:region:account-id:thing/core-thing-name", "iotHost": "host-prefix.iot.region.amazonaws.com", "ggHost": "greengrass.iot.region.amazonaws.com", "keepAlive": 600 }, "runtime": { "cgroup": { "useSystemd": "yes|no" } }, "managedRespawn": true }

The config.json file exists in /greengrass-root/config and contains the following parameters:

Field Description Notes
caPath

The path to the AWS IoT root CA relative to the /greengrass-root/certs folder.

Save the file under the /greengrass-root/certs folder.

certPath

The path to the AWS IoT Greengrass core certificate relative to the /greengrass-root/certs folder.

Save the file under the /greengrass-root/certs folder.
keyPath The path to the AWS IoT Greengrass core private key relative to /greengrass-root/certs folder. Save the file under the /greengrass-root/certs folder.
thingArn The Amazon Resource Name (ARN) of the AWS IoT thing that represents the AWS IoT Greengrass core. You can find this value in the AWS IoT Greengrass console under the definition for your AWS IoT thing.
iotHost Your AWS IoT endpoint. You can find this value in the AWS IoT console under Settings.
ggHost Your AWS IoT Greengrass endpoint. You can find this value in the AWS IoT console under Settings with greengrass. prepended.
keepAlive The MQTT KeepAlive period, in seconds. This is an optional value. The default value is 600 seconds.
useSystemd A binary flag, if your device uses systemd. Values are yes or no. Use the dependency script in Module 1 to see if your device uses systemd.

managedRespawn

An optional over-the-air (OTA) updates feature, this indicates that the OTA agent needs to run custom code before an update.

For more information, see OTA Updates of AWS IoT Greengrass Core Software.

GGC v1.1
{ "coreThing": { "caPath": "root-ca-pem", "certPath": "cloud-pem-crt", "keyPath": "cloud-pem-key", "thingArn": "arn:aws:iot:region:account-id:thing/core-thing-name", "iotHost": "host-prefix.iot.region.amazonaws.com", "ggHost": "greengrass.iot.region.amazonaws.com", "keepAlive": 600 }, "runtime": { "cgroup": { "useSystemd": "yes|no" } } }

The config.json file exists in /greengrass-root/config and contains the following parameters:

Field Description Notes
caPath

The path to the AWS IoT root CA relative to the /greengrass-root/certs folder.

Save the file under the /greengrass-root/certs folder.

certPath

The path to the AWS IoT Greengrass core certificate relative to the /greengrass-root/certs folder.

Save the file under the /greengrass-root/certs folder.
keyPath The path to the AWS IoT Greengrass core private key relative to the /greengrass-root/certs folder. Save the file under the /greengrass-root/certs folder.
thingArn The Amazon Resource Name (ARN) of the AWS IoT thing that represents the AWS IoT Greengrass core. You can find this value in the AWS IoT Greengrass console under the definition for your AWS IoT thing.
iotHost Your AWS IoT endpoint. You can find this value in the AWS IoT console under Settings.
ggHost Your AWS IoT Greengrass endpoint. You can find this value in the AWS IoT console under Settings with greengrass. prepended.
keepAlive The MQTT KeepAlive period, in seconds. This is an optional value. The default value is 600 seconds.
useSystemd A binary flag, if your device uses systemd. Values are yes or no. Use the dependency script in Module 1 to see if your device uses systemd.
GGC v1.0

In AWS IoT Greengrass Core v1.0, config.json is deployed to greengrass-root/configuration.

{ "coreThing": { "caPath": "root-ca-pem", "certPath": "cloud-pem-crt", "keyPath": "cloud-pem-key", "thingArn": "arn:aws:iot:region:account-id:thing/core-thing-name", "iotHost": "host-prefix.iot.region.amazonaws.com", "ggHost": "greengrass.iot.region.amazonaws.com", "keepAlive": 600 }, "runtime": { "cgroup": { "useSystemd": "yes|no" } } }

The config.json file exists in /greengrass-root/configuration and contains the following parameters:

Field Description Notes
caPath

The path to the AWS IoT root CA relative to the /greengrass-root/configuration/certs folder.

Save the file under the /greengrass-root/configuration/certs folder.

certPath

The path to the AWS IoT Greengrass core certificate relative to the /greengrass-root/configuration/certs folder.

Save the file under the /greengrass-root/configuration/certs folder.
keyPath The path to the AWS IoT Greengrass core private key relative to the /greengrass-root/configuration/certs folder. Save the file under the /greengrass-root/configuration/certs folder.
thingArn The Amazon Resource Name (ARN) of the AWS IoT thing that represents the AWS IoT Greengrass core. You can find this value in the AWS IoT Greengrass console under the definition for your AWS IoT hing.
iotHost Your AWS IoT endpoint. You can find this value in the AWS IoT console under Settings.
ggHost Your AWS IoT Greengrass endpoint.

You can find this value in the AWS IoT console under Settings with greengrass. prepended.

keepAlive The MQTT KeepAlive period, in seconds. This is an optional value. The default value is 600 seconds.
useSystemd A binary flag if your device uses systemd. Values are yes or no. Use the dependency script in Module 1 to see if your device uses systemd.

Endpoints Must Match the Certificate Type

Your AWS IoT and AWS IoT Greengrass endpoints must correspond to the certificate type of the root CA certificate on your device.

If you're using an Amazon Trust Services (ATS) root CA certificate (preferred), you must use ATS endpoints. ATS endpoints include the ats segment, as shown in the following syntax for the AWS IoT endpoint.

prefix-ats.iot.region.amazonaws.com

In some AWS Regions, AWS IoT Greengrass also currently supports legacy Verisign endpoints and root CA certificates for backward compatibilty. For more information, see AWS IoT Greengrass in the Amazon Web Services General Reference.

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. For more information, see Server Authentication in the AWS IoT Developer Guide. Otherwise, make sure to use the corresponding legacy endpoints. For example, the following syntax is used for legacy AWS IoT endpoints:

prefix.iot.region.amazonaws.com

If your endpoints and certificate type do not match, authentication attempts between AWS IoT and AWS IoT Greengrass fail.

Endpoints in config.json

On an AWS IoT Greengrass core device, in the config.json file, the AWS IoT and AWS IoT Greengrass endpoints are specified in the coreThing object. The iotHost property represents the AWS IoT 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 endpoint

You can get your AWS IoT 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 is greengrass-ats.iot.region.amazonaws.com. This uses the same region as your AWS IoT endpoint.

Connect on Port 443 or Through a Network Proxy

This feature is available for AWS IoT Greengrass Core v1.7 and later.

AWS IoT Greengrass communicates with AWS IoT 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 AWS IoT 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, and no_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 python requests 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.

  1. Run the following command to stop the Greengrass daemon:

    cd /greengrass-root/ggc/core/ sudo ./greengrassd stop
  2. Open greengrass-root/config/config.json for editing as the su user.

  3. In the coreThing object, add the iotMqttPort property and set the value to 443, 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 }, ... }
  4. 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.

  1. Run the following command to stop the Greengrass daemon:

    cd /greengrass-root/ggc/core/ sudo ./greengrassd stop
  2. Open greengrass-root/config/config.json for editing as the su user.

  3. In the coreThing object, add the iotHttpPort and ggHttpPort 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 }, ... }
  4. 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.

  1. Run the following command to stop the Greengrass daemon:

    cd /greengrass-root/ggc/core/ sudo ./greengrassd stop
  2. Open greengrass-root/config/config.json for editing as the su user.

  3. 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" } } }, ... }
  4. 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.

  • url. The URL of the proxy server, in the format scheme://userinfo@host:port.

    • scheme. The scheme. Must be http or https.

    • userinfo. Optional. The user name and password information. If specified, the username and password fields are ignored.

    • host. The host name or IP address of the proxy server.

    • port. Optional. The port number. If not specified, the following default values are used:

      • http: 80

      • https: 443

  • username. Optional. The user name to use to authenticate to the proxy server.

  • password. Optional. The password to use to authenticate to the proxy server.

Whitelisting Endpoints

Communication between Greengrass devices and AWS IoT 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, whitelist the following endpoints.

Endpoint Port Description
greengrass.region.amazonaws.com 443

Used for control plane operations for group management.

prefix-ats.iot.region.amazonaws.com

or

prefix.iot.region.amazonaws.com

MQTT: 8883 or 443

HTTPS: 8443 or 443

Used for data plane operations for device management, such as shadow sync.

Whitelist one or both endpoints, depending on whether your core and connected devices use Amazon Trust Services (preferred) root CA certificates, legacy root CA certificates, or both. For more information, see Endpoints Must Match the Certificate Type.

greengrass-ats.iot.region.amazonaws.com

or

greengrass.iot.region.amazonaws.com

8443 or 443

Used for device discovery operations.

Whitelist one or both endpoints, depending on whether your core and connected devices use Amazon Trust Services (preferred) root CA certificates, legacy root CA certificates, or both. For more information, see Endpoints Must Match the Certificate Type.

Note

Clients that connect on port 443 must implement the Application Layer Protocol Negotiation (ALPN) TLS extension and pass x-amzn-http-ca as the ProtocolName in the ProtocolNameList. For more information, see Protocols in the AWS IoT Developer Guide.

*.s3.amazonaws.com 443

Used for deployment operations and over-the-air updates. This format includes the * character because endpoint prefixes are controlled internally and might change at any time.

logs.region.amazonaws.com 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 and config.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.7/ | |-- 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

  1. Run the following command to stop the AWS IoT Greengrass daemon:

    cd /greengrass-root/ggc/core/ sudo ./greengrassd stop
  2. Open greengrass-root/config/config.json for editing as the su user.

  3. 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.

  4. 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.

  1. Grant access permissions to required directories:

    1. Give read and write permissions to the config.json owner.

      sudo chmod 0600 /greengrass-root/config/config.json
    2. 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.10.0/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.

  2. 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 these umount and mount operations to the ota_pre_update and ota_post_update scripts. For more information about OTA updates, see Greengrass OTA Update Agent and AWS IoT Greengrass Core Update with Managed Respawn.

  3. Start the daemon.

    cd /greengrass-root/ggc/core/ sudo ./greengrassd start

    If the permissions from step 1 aren't set correctly, tthe daemon won't start.

Configure MQTT Settings

In the AWS IoT Greengrass environment, local devices, Lambda functions, connectors, and system components can communicate with each other and with AWS IoT. 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:

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 AWS IoT Greengrass core acts as both client (for communication with AWS IoT) and message broker (for communication on the local network).


                        The core as client and local message broker.

For more information about QoS, see Quality of Service Levels and Protocol Flows on the MQTT website.

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 (unless the queue is full). This can help minimize data loss from intermittent connectivity.

    For more information, 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.

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 connected 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, the message is removed from the queue.

By default, the AWS IoT Greengrass core stores unprocessed messages destined for AWS Cloud targets in memory. 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.

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.

  1. Get the IDs of the target Greengrass group and group version. In this procedure, we assume this is the latest group and group version. The following command 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 page.

  2. Copy the Id and LatestVersion values from the target group in the output.

  3. Get the latest group version.

    • Replace group-id with the Id that you copied.

    • Replace latest-group-version-id with the LatestVersion that you copied.

    aws greengrass get-group-version \ --group-id group-id \ --group-version-id latest-group-version-id
  4. From the Definition object in the output, copy the CoreDefinitionVersionArn and the ARNs of all other group components except FunctionDefinitionVersionArn. You use these values when you create a new group version.

  5. From the FunctionDefinitionVersionArn in the output, copy the ID of the function definition. The ID is the GUID that follows the functions 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 copy the ID from the output.

  6. Add a function definition version to the function definition.

    • Replace function-definition-id with the Id that you copied for the function definition.

    • Replace arbitrary-function-id with a name for the function, such as spooler-function.

    • Add any Lambda functions that you want to include in this version to the functions array. You can use the get-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, include it in this function instance.

  7. Copy the Arn of the function definition version from the output.

  8. Create a group version that contains the system Lambda function.

    • Replace group-id with the Id for the group.

    • Replace core-definition-version-arn with the CoreDefinitionVersionArn that you copied from the latest group version.

    • Replace function-definition-version-arn with the Arn that you copied for the new function definition version.

    • Replace the ARNs for other group components (for example, SubscriptionDefinitionVersionArn or DeviceDefinitionVersionArn) 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-arn core-definition-version-arn \ --function-definition-version-arn function-definition-version-arn \ --device-definition-version-arn device-definition-version-arn \ --logger-definition-version-arn logger-definition-version-arn \ --resource-definition-version-arn resource-definition-version-arn \ --subscription-definition-version-arn subscription-definition-version-arn
  9. Copy the Version from the output. This is the ID of the new group version.

  10. Deploy the group with the new group version.

    • Replace group-id with the Id that you copied for the group.

    • Replace group-version-id with the Version that you copied for the new group version.

    aws greengrass create-deployment \ --group-id group-id \ --group-version-id group-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

This feature is available for AWS IoT Greengrass Core v1.10 only.

An AWS IoT 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 connected devices. When the core reconnects, the persistent session is resumed and AWS IoT 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 the cleanSession flag to 0 in CONNECT 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. 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 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.

  1. Get the IDs of the target Greengrass group and group version. In this procedure, we assume this is the latest group and group version. The following command 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 page.

  2. Copy the Id and LatestVersion values from the target group in the output.

  3. Get the latest group version.

    • Replace group-id with the Id that you copied.

    • Replace latest-group-version-id with the LatestVersion that you copied.

    aws greengrass get-group-version \ --group-id group-id \ --group-version-id latest-group-version-id
  4. From the Definition object in the output, copy the CoreDefinitionVersionArn and the ARNs of all other group components except FunctionDefinitionVersionArn. You use these values when you create a new group version.

  5. From the FunctionDefinitionVersionArn in the output, copy the ID of the function definition. The ID is the GUID that follows the functions 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 copy the ID from the output.

  6. Add a function definition version to the function definition.

    • Replace function-definition-id with the Id that you copied for the function definition.

    • Replace arbitrary-function-id with a name for the function, such as spooler-function.

    • Add any Lambda functions that you want to include in this version to the functions array. You can use the get-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 or GG_CONFIG_MAX_SIZE_BYTES environment variables to define storage settings, include them in this function instance.

  7. Copy the Arn of the function definition version from the output.

  8. Create a group version that contains the system Lambda function.

    • Replace group-id with the Id for the group.

    • Replace core-definition-version-arn with the CoreDefinitionVersionArn that you copied from the latest group version.

    • Replace function-definition-version-arn with the Arn that you copied for the new function definition version.

    • Replace the ARNs for other group components (for example, SubscriptionDefinitionVersionArn or DeviceDefinitionVersionArn) 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-arn core-definition-version-arn \ --function-definition-version-arn function-definition-version-arn \ --device-definition-version-arn device-definition-version-arn \ --logger-definition-version-arn logger-definition-version-arn \ --resource-definition-version-arn resource-definition-version-arn \ --subscription-definition-version-arn subscription-definition-version-arn
  9. Copy the Version from the output. This is the ID of the new group version.

  10. Deploy the group with the new group version.

    • Replace group-id with the Id that you copied for the group.

    • Replace group-version-id with the Version that you copied for the new group version.

    aws greengrass create-deployment \ --group-id group-id \ --group-version-id group-version-id \ --deployment-type NewDeployment
  11. (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 AWS IoT Greengrass core opens MQTT connections with AWS IoT 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).

GGC v1.9 and laterGGC v1.8
GGC v1.9 and later

Two Greengrass system components open MQTT connections with AWS IoT. These components use the following patterns to generate the client IDs for the connections.

Operation Client ID pattern
Deployments

core-thing-name

Example: MyCoreThing

Use this client ID for connect, disconnect, subscribe, and unsubscribe lifecycle event notifications.

MQTT message exchange with AWS IoT

core-thing-name-cnn

Example: MyCoreThing-c01

nn is an integer that starts at 00 and increments with each new connection to a maximum of of 05. The number of connections is determined by the number of devices that sync their shadow state with AWS IoT (maximum 200 per group) and the number of subscriptions with cloud as their source in the group (maximum 50 per group).

The spooler system component makes connections with AWS IoT to exchange messages for subscriptions with a cloud source or target. The spooler also acts as proxy for message exchange between AWS IoT and the local shadow service and device certificate manager.

Note

If you enable persistent sessions for subscription with AWS IoT, the core opens at least one additional connection to use in a persistent session. The system components don't support persistent sessions, so they can't share that connection.

GGC v1.8

Several Greengrass system components open MQTT connections with AWS IoT. These components use the following patterns to generate the client IDs for the connections.

Operation Client ID pattern
Deployments

core-thing-name

Example: MyCoreThing

Use this client ID for connect, disconnect, subscribe, and unsubscribe lifecycle event notifications.

MQTT message exchange with AWS IoT

core-thing-name-spr

Example: MyCoreThing-spr

Shadow sync

core-thing-name-snn

Example: MyCoreThing-s01

nn is an integer that starts at 00 and increments with each new connection to a maximum of 03. The number of connections is determined by the number of devices (maximum 200 devices per group) that sync their shadow state with AWS IoT (maximum 50 subscriptions per connection).

Device certificate management

core-thing-name-dcm

Example: MyCoreThing-dcm

Note

Duplicate client IDs used in simultaneous connections can cause an infinite connect-disconnect loop. This can happen if another device is hard-coded 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. 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.

The AWS IoT Greengrass core acts as the local message broker for MQTT messaging between local Lambda functions, connectors, and Greengrass 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

  1. Run the following command to stop the Greengrass daemon:

    cd /greengrass-root/ggc/core/ sudo ./greengrassd stop
  2. Open greengrass-root/config/config.json for editing as the su user.

  3. In the coreThing object, add the ggMqttPort 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 to 9000.

    { "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 }, ... }
  4. Start the daemon.

    cd /greengrass-root/ggc/core/ sudo ./greengrassd start
  5. 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 Greengrass 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)
    1. On the group configuration page, choose Cores, and then choose the core.

    2. On the core details page, choose Connectivity, and then choose Edit.

    3. Choose Add another connection, enter your current local IP address and the new port number. The following example sets the port number 9000 for the IP address 192.168.1.8.

      
                                                The core as client and local message
                                                  broker.
    4. 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 number 9000 for the IP address 192.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. For more information, see Connect on Port 443 or Through a Network Proxy.

Activate Automatic IP Detection

You can configure AWS IoT Greengrass to enable automatic discovery of your AWS IoT Greengrass core using the IPDetector system Lambda function. This feature can also be enabled by choosing Automatic detection when you deploy your group from the console for the first time, or from the group's Settings page in the console at any time.

Note

You can check whether automatic IP detection is enabled in the AWS IoT console. On the group's Settings page, under Core connectivity information, check the Local connection detection setting. Automatic IP detection is enabled if Automatically detect and override connection information is selected.

The following procedure uses the create-function-definition-version CLI command to configure automatic discovery of the Greengrass core.

  1. Get the IDs of the target Greengrass group and group version. In this procedure, we assume this is the latest group and group version. The following command 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 page.

  2. Copy the Id and LatestVersion values from the target group in the output.

  3. Get the latest group version.

    • Replace group-id with the Id that you copied.

    • Replace latest-group-version-id with the LatestVersion that you copied.

    aws greengrass get-group-version \ --group-id group-id \ --group-version-id latest-group-version-id
  4. From the Definition object in the output, copy the CoreDefinitionVersionArn and the ARNs of all other group components except FunctionDefinitionVersionArn. You use these values when you create a new group version.

  5. 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.

  6. Use the get-function-definition-version command to get the current definition state. Use the function-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-id function-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.

  7. Add a function definition version to the function definition.

    • Replace function-definition-id with the Id 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 as auto-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
  8. Copy the Arn of the function definition version from the output.

  9. Create a group version that contains the system Lambda function.

    • Replace group-id with the Id for the group.

    • Replace core-definition-version-arn with the CoreDefinitionVersionArn that you copied from the latest group version.

    • Replace function-definition-version-arn with the Arn that you copied for the new function definition version.

    • Replace the ARNs for other group components (for example, SubscriptionDefinitionVersionArn or DeviceDefinitionVersionArn) 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-arn core-definition-version-arn \ --function-definition-version-arn function-definition-version-arn \ --device-definition-version-arn device-definition-version-arn \ --logger-definition-version-arn logger-definition-version-arn \ --resource-definition-version-arn resource-definition-version-arn \ --subscription-definition-version-arn subscription-definition-version-arn
  10. Copy the Version from the output. This is the ID of the new group version.

  11. Deploy the group with the new group version.

    • Replace group-id with the Id that you copied for the group.

    • Replace group-version-id with the Version that you copied for the new group version.

    aws greengrass create-deployment \ --group-id group-id \ --group-version-id group-version-id \ --deployment-type NewDeployment

If you want to manually input the IP address of your AWS IoT 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 AWS IoT 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.

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

For information about how to create and enable a service file for systemd on a Raspberry Pi, see SYSTEMD in the Raspberry Pi documentation.

Archive an AWS IoT Greengrass Core Software Installation

When you upgrade to a new version of the AWS IoT Greengrass Core software, you can archive the currently installed version. This preserves your current installation environment so you can test a new software version on the same hardware. This also makes it easy to roll back to your archived version for any reason.

To archive the current installation and install a new version

  1. Download the AWS IoT Greengrass Core Software installation package that you want to upgrade to.

  2. Copy the package to the destination core device. For instructions that show how to transfer files, see this step.

    Note

    You copy your current certificates, keys, and configuration file to the new installation later.

    Run the commands in the following steps in your core device terminal.

  3. Make sure that the Greengrass daemon is stopped on the core device.

    1. To check whether the daemon is running:

      ps aux | grep -E 'greengrass.*daemon'

      If the output contains a root entry for /greengrass/ggc/packages/ggc-version/bin/daemon, then the daemon is running.

      Note

      This procedure is written with the assumption that the AWS IoT Greengrass Core software is installed in the /greengrass directory.

    2. To stop the daemon:

      cd /greengrass/ggc/core/ sudo ./greengrassd stop
  4. Move the current Greengrass root directory to a different directory.

    sudo mv /greengrass /greengrass_backup
  5. Untar the new software on the core device. Replace the os-architecture and version placeholders in the command.

    sudo tar –zxvf greengrass-os-architecture-version.tar.gz –C /
  6. Copy the archived certificates, keys, and configuration file to the new installation.

    sudo cp /greengrass_backup/certs/* /greengrass/certs sudo cp /greengrass_backup/config/* /greengrass/config
  7. Start the daemon:

    cd /greengrass/ggc/core/ sudo ./greengrassd start

Now, you can make a group deployment to test the new installation. If something fails, you can restore the archived installation.

To restore the archived installation

  1. Stop the daemon.

  2. Delete the new /greengrass directory.

  3. Move the /greengrass_backup directory back to /greengrass.

  4. Start the daemon.

See Also