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.

  • Secure, encrypted storage of local secrets and controlled access by connectors and Lambda functions.

  • 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 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 automatically restarted.

  • Secure, over-the-air software updates of user-defined Lambda functions.

AWS IoT Greengrass Core Configuration File

The configuration file for the AWS IoT Greengrass core software is the config.json file, which 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 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.

GGC v1.7.0GGC v1.6.0GGC v1.5.0GGC v1.3.0GGC v1.1.0GGC v1.0.0
GGC v1.7.0

This is the config.json file that's generated when the Greengrass group and core are created with the Easy group creation option in the AWS IoT Greengrass console.

{ "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 prior to 1.7.0. This property is ignored when the crypto is present.

certPath

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

For backward compatibility with versions prior to 1.7.0. This property is ignored when the crypto is present.
keyPath The path to the core private key relative to /greengrass-root/certs directory. For backward compatibility with versions prior to 1.7.0. This property is ignored when the crypto 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 list-core-definitions 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 assumes that you're using an Amazon Trust Services (ATS) endpoint. For more information, see the Server Authentication in AWS IoT Core 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 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, Connect on Port 443 or through a Network Proxy.
keepAlive Optional. The MQTT KeepAlive period, in 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, 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 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. This is used by the Greengrass OTA update agent.

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

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.

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.6.0
{ "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. You can find this for your core in the AWS IoT Greengrass console under Cores, or by running the aws greengrass list-core-definitions 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.0
{ "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. Find this for your core in the AWS IoT Greengrass console under Cores, or by running the aws greengrass list-core-definitions 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. 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.3.0
{ "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.0
{ "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.0

In AWS IoT Greengrass Core v1.0.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 with the certificate type of your root CA. For example, if you're using an Amazon Trust Services (ATS) certificate (preferred), the coreThing.iotHost and coreThing.ggHost properties must include the ats segment (for example, abcde1234uwxyz-ats.iot.us-west-2.amazonaws.com).

If you're using a legacy endpoint, either create an ATS endpoint and download an appropriate certificate (preferred) or make sure that your endpoints correspond with your certificate. For more information, see the Server Authentication in AWS IoT Core documentation.

You can find your AWS IoT endpoint in the AWS IoT console under Settings, or by running the aws iot describe-endpoint CLI command with the appropriate --endpoint-type parameter. For example:

  • To return an ATS signed data endpoint, run aws iot describe-endpoint --endpoint-type iot:Data-ATS

  • To return a VeriSign signed data endpoint (legacy), run aws iot describe-endpoint --endpoint-type iot:Data

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

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

Connect on Port 443 or through a Network Proxy

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

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

  • 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. If a function specifies these variables, AWS IoT Greengrass doesn't override them.

To Configure MQTT on Port 443

This procedure allows the core to use port 443 for MQTT messaging. When using this configuration, AWS IoT Greengrass specifies the x-amzn-mqtt-ca header in the TLS handshake, which is expected by AWS IoT. For more information, see Protocols in the AWS IoT Developer Guide.

  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. 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 a Network Proxy

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

Use the networkProxy object to specify information about the network proxy. This object has the following properties.

networkProxy object

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.

Configure a Write Directory for AWS IoT Greengrass

This feature is available for AWS IoT Greengrass Core v1.6.0 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/ | |-- nodejs6.10/ | |-- python2.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

  1. Grant required access to the AWS IoT Greengrass:

    Note

    This step is required only if you want to make the Greengrass root directory read-only. The write directory must be configured before you begin this procedure.

    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.7.0/lambda/
  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 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 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, then the daemon won't start.

MQTT Message Queue

MQTT messages that are destined for 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 the cloud, the message is removed from the queue. AWS IoT Greengrass manages the queue by using a system-defined GGCloudSpooler Lambda function.

Configure the MQTT Message Queue

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

You can configure AWS IoT Greengrass to store unprocessed messages in memory or in a local storage cache. 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.

Note

Versions 1.5.0 and earlier use in-memory storage with a queue size of 2.5 MB. You cannot configure storage settings for earlier versions.

The following environment variables for the GGCloudSpooler Lambda function are used to define 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. 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.

To Cache Messages in Local Storage

To configure AWS IoT Greengrass to cache messages to the file system so they persist across core restarts, you create a function definition version where the GGCloudSpooler function specifies the FileSystem storage type. 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.

Note

This procedure assumes 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.

    aws greengrass list-groups
  2. Copy the Id and LatestVersion properties of your target group from 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 ComponentDefinitionVersionArn for each group component 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.

    Note

    You can optionally 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"}]'
  7. Copy the Arn of the function definition version from the output.

  8. Create a group version that contains the system-defined 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 by using the ComponentDefinitionVersionArn values 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.

    • 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 create a function definition version that doesn't include the GGCloudSpooler function.

This system-defined 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).

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.

See Also