Amazon IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. After this date, Amazon IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on Amazon IoT Greengrass V1 won't be disrupted and will continue to operate and to connect to the cloud. We strongly recommend that you migrate to Amazon IoT Greengrass Version 2, which adds significant new features and support for additional platforms.
Quick start: Greengrass device setup
Greengrass device setup is a script that sets up your core device in minutes, so that you can start using Amazon IoT Greengrass. Use this script to:
Configure your device and installs the Amazon IoT Greengrass Core software.
Configure your cloud-based resources.
Optionally deploy a Greengrass group with a Hello World Lambda function that sends MQTT messages to Amazon IoT from the Amazon IoT Greengrass core. This sets up the Greengrass environment shown in the following diagram.
Requirements
Greengrass device setup has the following requirements:
-
Your core device must use a supported platform. The device must have an appropriate package manager installed:
apt
,yum
, oropkg
. -
The Linux user who runs the script must have permissions to run as
sudo
. -
You must provide your Amazon Web Services account credentials. For more information, see Provide Amazon Web Services account credentials.
Note
Greengrass device setup installs the latest version of the Amazon IoT Greengrass Core software on the device. By installing the Amazon IoT Greengrass Core software, you agree to the Greengrass Core Software License Agreement
.
Run Greengrass device setup
You can run Greengrass device setup in just a few steps. After you provide your Amazon Web Services account credentials, the script provisions your Greengrass core device and deploys a Greengrass group in minutes. Run the following commands in a terminal window on the target device.
Note
These steps show you how to run the script in interactive mode, which prompts you to enter or accept each input value. For information about how to run the script silently, see Run Greengrass device setup in silent mode.
-
Provide your credentials. In this procedure, we assume you provide temporary security credentials as environment variables.
export AWS_ACCESS_KEY_ID=
AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE=
Note
If you're running Greengrass device setup on a Raspbian or OpenWrt platform, make a copy of these commands. You must provide them again after you reboot the device.
-
Download and start the script. You can use
wget
orcurl
to download the script.-
wget
:wget -q -O ./gg-device-setup-latest.sh https://d1onfpft10uf5o.cloudfront.net/greengrass-device-setup/downloads/gg-device-setup-latest.sh && chmod +x ./gg-device-setup-latest.sh && sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass-interactive
-
curl
:curl https://d1onfpft10uf5o.cloudfront.net/greengrass-device-setup/downloads/gg-device-setup-latest.sh > gg-device-setup-latest.sh && chmod +x ./gg-device-setup-latest.sh && sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass-interactive
-
Proceed through the command prompts for input values. You can press the Enter key to use the default value or type a custom value and then press Enter.
The script writes status messages to the terminal that are similar to the following.
-
If your core device is running Raspbian or OpenWrt, reboot the device when prompted, provide your credentials, and then restart the script.
-
When prompted to reboot the device, run one of the following commands.
-
For Raspbian platforms:
sudo reboot
-
For OpenWrt platforms:
reboot
-
After the device reboots, open the terminal and provide your credentials as environment variables.
export AWS_ACCESS_KEY_ID=
AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE=
-
Restart the script.
sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass-interactive
-
When prompted whether to use your input values from the previous session or start a new installation, enter
yes
to reuse your input values.Note
On platforms that require a reboot, your input values from the previous session, excluding credentials, are temporarily stored in the
GreengrassDeviceSetup.config.info
file.
When the setup is complete, the terminal displays a success status message that's similar to the following.
-
-
Review the new Greengrass group that the script configures using the input values you provide.
-
Sign in to the Amazon Web Services Management Console
on your computer and open the Amazon IoT console. Note
Make sure that the Amazon Web Services Region selected in the console is the same one that you used to configure your Greengrass environment. By default, the Region is US West (Oregon).
-
In the navigation pane, expand Greengrass devices, then choose Groups (V1) to locate the newly created group.
-
-
If you included the Hello World Lambda function, Greengrass device setup deploys the Greengrass group to your core device. To test the Lambda function, or for information about how to remove the Lambda function from the group, continue to Verify the Lambda function is running on the core device in Module 3-1 of the Getting Started tutorial.
Note
Make sure that the Amazon Web Services Region selected in the console is the same one that you used to configure your Greengrass environment. By default, the Region is US West (Oregon).
If you didn't include the Hello World Lambda function, you can create your own Lambda function or try other Greengrass features. For example, you can add the Docker application deployment connector to your group and use it to deploy Docker containers to your core device.
Troubleshooting issues
You can use the following information to troubleshoot issues with the Amazon IoT Greengrass device setup.
Error: Python (python3.7) not found. Attempting to install it...
Solution: You might see this error when working with an Amazon EC2 instance.
This error occurs when Python is not installed in the /usr/bin/python3.7
folder. To
resolve this error, move Python in the correct directory after installing it:
sudo ln -s /usr/local/bin/python3.7 /usr/bin/python3.7
Additional troubleshooting
To troubleshoot additional issues with the Amazon IoT Greengrass device setup, you can look for debug information in the log files:
For issues with the Greengrass device setup configuration, check the
/tmp/greengrass-device-setup-bootstrap-
file.epoch-timestamp
.logFor issues with the Greengrass group or core environment setup, check the
GreengrassDeviceSetup-
file in the same directory asdate
-time
.loggg-device-setup-latest.sh
or in the location you specified.
For more troubleshooting help, see Troubleshooting Amazon IoT Greengrass or check
the Amazon IoT Greengrass tag on Amazon re:Post
Greengrass device setup configuration options
You configure Greengrass device setup to access your Amazon resources and set up your Greengrass environment.
Provide Amazon Web Services account credentials
Greengrass device setup uses your Amazon Web Services account credentials to access your Amazon resources. It supports long-term credentials for an IAM user or temporary security credentials from an IAM role.
First, get your credentials.
To use long-term credentials, provide the access key ID and secret access key for your IAM user. For information about creating access keys for long-term credentials, see Managing access keys for IAM users in the IAM User Guide.
To use temporary security credentials (recommended), provide the access key ID, secret access key, and session token from an assumed IAM role. For information about extracting temporary security credentials from the Amazon STS
assume-role
command, see Using temporary security credentials with the Amazon CLI in the IAM User Guide.
Note
For the purposes of this tutorial, we assume that the IAM user or IAM role has administrator access permissions.
Then, provide your credentials to Greengrass device setup in one of two ways:
As environment variables. Set the
AWS_ACCESS_KEY_ID
,AWS_SECRET_ACCESS_KEY
, andAWS_SESSION_TOKEN
(if required) environment variables before you start the script, as shown in step 1 of Run Greengrass device setup.As input values. Enter your access key ID, secret access key, and session token (if required) values directly in the terminal after you start the script.
Greengrass device setup doesn't save or store your credentials.
Provide input values
In interactive mode, Greengrass device setup prompts you for input values. You can press the Enter key to use the default value or type a custom value and then press Enter. In silent mode, you provide input values after you start the script.
- Amazon access key ID
-
The access key ID from the long-term or temporary security credentials. Specify this option as an input value only if you don't provide your credentials as environment variables. For more information, see Provide Amazon Web Services account credentials.
Option name for silent mode:
--aws-access-key-id
- Amazon secret access key
-
The secret access key from the long-term or temporary security credentials. Specify this option as an input value only if you don't provide your credentials as environment variables. For more information, see Provide Amazon Web Services account credentials.
Option name for silent mode:
--aws-secret-access-key
- Amazon session token
-
The session token from the temporary security credentials. Specify this option as an input value only if you don't provide your credentials as environment variables. For more information, see Provide Amazon Web Services account credentials.
Option name for silent mode:
--aws-session-token
- Amazon Web Services Region
-
The Amazon Web Services Region where you want to create the Greengrass group. For the list of supported Amazon Web Services Regions, see Amazon IoT Greengrass in the Amazon Web Services General Reference.
Default value:
us-west-2
Option name for silent mode:
--region
- Group name
-
The name for the Greengrass group.
Default value:
GreengrassDeviceSetup_Group_
guid
Option name for silent mode:
--group-name
- Core name
-
The name for the Greengrass core. The core is an Amazon IoT device (thing) that runs the Amazon IoT Greengrass Core software. The core is added to the Amazon IoT registry and the Greengrass group. If you provide a name, it must be unique in the Amazon Web Services account and Amazon Web Services Region.
Default value:
GreengrassDeviceSetup_Core_
guid
Option name for silent mode:
--core-name
- Amazon IoT Greengrass Core software installation path
-
The location in the device file system where you want to install the Amazon IoT Greengrass Core software.
Default value:
/
Option name for silent mode:
--ggc-root-path
- Hello World Lambda function
-
Indicates whether to include a Hello World Lambda function in the Greengrass group. The function publishes an MQTT message to the
hello/world
topic every five seconds.The script creates and publishes this user-defined Lambda function in Amazon Lambda and adds it to your Greengrass group. The script also creates a subscription in the group that allows the function to send MQTT messages to Amazon IoT.
Note
This is a Python 3.7 Lambda function. If Python 3.7 isn't installed on the device and the script is unable to install it, the script prints an error message in the terminal. To include the Lambda function in the group, you must install Python 3.7 manually and restart the script. To create the Greengrass group without the Lambda function, restart the script and enter
no
when prompted to include the function.Default value:
no
Option name for silent mode:
--hello-world-lambda
- This option doesn't take a value. Include it in your command if you want to create the function. - Deployment timeout
-
The number of seconds before Greengrass device setup stops checking the status of the Greengrass group deployment. This is used only when the group includes the Hello World Lambda function. Otherwise, the group is not deployed.
The deployment time depends on your network speed. For slow network speeds, you can increase this value.
Default value:
180
Option name for silent mode:
--deployment-timeout
- Log path
-
The location of the log file that contains information about Greengrass group and core setup operations. Use this log to troubleshoot deployment and other issues with the Greengrass group and core setup.
Default value:
./
Option name for silent mode:
--log-path
- Verbosity
-
Indicates whether to print detailed log information in the terminal while the script runs. You can use this information to troubleshoot device setup.
Default value:
no
Option name for silent mode:
--verbose
- This option doesn't take a value. Include it in your command if you want to print detailed log information.
Run Greengrass device setup in silent mode
You can run Greengrass device setup in silent mode so that the script doesn't prompt you for any values. To run in silent mode, specify bootstrap-greengrass
mode and your input values after you start the script. You can omit input values if you want to use their defaults.
The procedure depends on whether you provide your Amazon Web Services account credentials as environment variables before you start the script, or as input values after you start the script.
-
Provide your credentials as environment variables. The following example exports temporary credentials, which include the session token.
export AWS_ACCESS_KEY_ID=
AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE=
Note
If you're running Greengrass device setup on a Raspbian or OpenWrt platform, make a copy of these commands. You must provide them again after you reboot the device.
-
Download and start the script. Provide input values as needed. For example:
-
To use all default values:
wget -q -O ./gg-device-setup-latest.sh https://d1onfpft10uf5o.cloudfront.net/greengrass-device-setup/downloads/gg-device-setup-latest.sh && chmod +x ./gg-device-setup-latest.sh && sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass
-
To specify custom values:
wget -q -O ./gg-device-setup-latest.sh https://d1onfpft10uf5o.cloudfront.net/greengrass-device-setup/downloads/gg-device-setup-latest.sh && chmod +x ./gg-device-setup-latest.sh && sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass --region us-east-1 --group-name Custom_Group_Name --core-name Custom_Core_Name --ggc-root-path /custom/ggc/root/path --deployment-timeout 300 --log-path /customized/log/path --hello-world-lambda --verbose
Note
To use
curl
to download the script, replacewget -q -O
withcurl
in the command. -
-
If your core device is running Raspbian or OpenWrt, reboot the device when prompted, provide your credentials, and then restart the script.
-
When prompted to reboot the device, run one of the following commands.
-
For Raspbian platforms:
sudo reboot
-
For OpenWrt platforms:
reboot
-
After the device reboots, open the terminal and provide your credentials as environment variables.
export AWS_ACCESS_KEY_ID=
AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE=
-
Restart the script.
sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass
-
When prompted whether to use your input values from the previous session or start a new installation, enter
yes
to reuse your input values.Note
On platforms that require a reboot, your input values from the previous session, excluding credentials, are temporarily stored in the
GreengrassDeviceSetup.config.info
file.
When the setup is complete, the terminal displays a success status message that's similar to the following.
-
-
If you included the Hello World Lambda function, Greengrass device setup deploys the Greengrass group to your core device. To test the Lambda function, or for information about how to remove the Lambda function from the group, continue to Verify the Lambda function is running on the core device in Module 3-1 of the Getting Started tutorial.
Note
Make sure that the Amazon Web Services Region selected in the console is the same one that you used to configure your Greengrass environment. By default, the Region is US West (Oregon).
If you didn't include the Hello World Lambda function, you can create your own Lambda function or try other Greengrass features. For example, you can add the Docker application deployment connector to your group and use it to deploy Docker containers to your core device.
-
Download and start the script. Provide your credentials and any other input values that you want to specify. The following examples show how to provide temporary credentials, which include the session token.
-
To use all default values:
wget -q -O ./gg-device-setup-latest.sh https://d1onfpft10uf5o.cloudfront.net/greengrass-device-setup/downloads/gg-device-setup-latest.sh && chmod +x ./gg-device-setup-latest.sh && sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass --aws-access-key-id AKIAIOSFODNN7EXAMPLE --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY --aws-session-token AQoDYXdzEJr1K...o5OytwEXAMPLE=
-
To specify custom values:
wget -q -O ./gg-device-setup-latest.sh https://d1onfpft10uf5o.cloudfront.net/greengrass-device-setup/downloads/gg-device-setup-latest.sh && chmod +x ./gg-device-setup-latest.sh && sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass --aws-access-key-id AKIAIOSFODNN7EXAMPLE --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY --aws-session-token AQoDYXdzEJr1K...o5OytwEXAMPLE= --region us-east-1 --group-name Custom_Group_Name --core-name Custom_Core_Name --ggc-root-path /custom/ggc/root/path --deployment-timeout 300 --log-path /customized/log/path --hello-world-lambda --verbose
Note
If you're running Greengrass device setup on a Raspbian or OpenWrt platform, make a copy of your credentials. You must provide them again after you reboot the device.
To use
curl
to download the script, replacewget -q -O
withcurl
in the command. -
-
If your core device is running Raspbian or OpenWrt, reboot the device when prompted, provide your credentials, and then restart the script.
-
When prompted to reboot the device, run one of the following commands.
-
For Raspbian platforms:
sudo reboot
-
For OpenWrt platforms:
reboot
-
Restart the script. You must include your credentials in the command, but not the other input values. For example:
sudo -E ./gg-device-setup-latest.sh bootstrap-greengrass --aws-access-key-id AKIAIOSFODNN7EXAMPLE --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY --aws-session-token AQoDYXdzEJr1K...o5OytwEXAMPLE=
-
When prompted whether to use your input values from the previous session or start a new installation, enter
yes
to reuse your input values.Note
On platforms that require a reboot, your input values from the previous session, excluding credentials, are temporarily stored in the
GreengrassDeviceSetup.config.info
file.
When the setup is complete, the terminal displays a success status message that's similar to the following.
-
-
If you included the Hello World Lambda function, Greengrass device setup deploys the Greengrass group to your core device. To test the Lambda function, or for information about how to remove the Lambda function from the group, continue to Verify the Lambda function is running on the core device in Module 3-1 of the Getting Started tutorial.
Note
Make sure that the Amazon Web Services Region selected in the console is the same one that you used to configure your Greengrass environment. By default, the Region is US West (Oregon).
If you didn't include the Hello World Lambda function, you can create your own Lambda function or try other Greengrass features. For example, you can add the Docker application deployment connector to your group and use it to deploy Docker containers to your core device.