End of support notice: On October 7th, 2026, AWS will discontinue support for AWS IoT Greengrass Version 1. After October 7th, 2026, you will no longer be able to access the AWS IoT Greengrass V1 resources. For more information, please visit [Migrate from AWS IoT Greengrass Version 1](https://docs.aws.amazon.com/greengrass/v2/developerguide/migrate-from-v1.html). # Module 1: Environment setup for Greengrass This module shows you how to get an out-of-the-box Raspberry Pi, Amazon EC2 instance, or other device ready to be used by AWS IoT Greengrass as your AWS IoT Greengrass core device. **Tip** Or, to use a script that sets up your core device for you, see [Quick start: Greengrass device setup](quick-start.md). This module should take less than 30 minutes to complete. Before you begin, read the [requirements](gg-gs.md#gg-requirements) for this tutorial. Then, follow the setup instructions in one of the following topics. Choose only the topic that applies to your core device type. **Topics** + [Setting up a Raspberry Pi](setup-filter.rpi.md) + [Setting up an Amazon EC2 instance](setup-filter.ec2.md) + [Setting up other devices](setup-filter.other.md) **Note** To learn how to use AWS IoT Greengrass running in a prebuilt Docker container, see [Running AWS IoT Greengrass in a Docker container](run-gg-in-docker-container.md). # Setting up a Raspberry Pi Follow the steps in this topic to set up a Raspberry Pi to use as an AWS IoT Greengrass core. **Tip** AWS IoT Greengrass also provides other options for installing the AWS IoT Greengrass Core software. For example, you can use [Greengrass device setup](quick-start.md) to configure your environment and install the latest version of the AWS IoT Greengrass Core software. Or, on supported Debian platforms, you can use the [APT package manager](install-ggc.md#ggc-package-manager) to install or upgrade the AWS IoT Greengrass Core software. For more information, see [Install the AWS IoT Greengrass Core software](install-ggc.md). If you are setting up a Raspberry Pi for the first time, you must follow all of these steps. Otherwise, you can skip to [step 9](#add-ggc-user-ggc-group). However, we recommend that you re-image your Raspberry Pi with the operating system as recommended in step 2.   1. Download and install an SD card formatter such as [SD Memory Card Formatter](https://www.sdcard.org/downloads/formatter/). Insert the SD card into your computer. Start the program and choose the drive where you have inserted your SD card. You can perform a quick format of the SD card. 1. Download the [Raspbian Buster](https://downloads.raspberrypi.org/raspbian/images/raspbian-2020-02-14/) operating system as a `zip` file. 1. Using an SD card-writing tool (such as [Etcher](https://etcher.io/)), follow the tool's instructions to flash the downloaded `zip` file onto the SD card. Because the operating system image is large, this step might take some time. Eject your SD card from your computer, and insert the microSD card into your Raspberry Pi. 1. For the first boot, we recommend that you connect the Raspberry Pi to a monitor (through HDMI), a keyboard, and a mouse. Next, connect your Pi to a micro USB power source and the Raspbian operating system should start up. 1. You might want to configure the Pi's keyboard layout before you continue. To do so, choose the Raspberry icon in the upper-right, choose **Preferences** and then choose **Mouse and Keyboard Settings**. Next, on the **Keyboard** tab, choose **Keyboard Layout**, and then choose an appropriate keyboard variant. 1. Next, [connect your Raspberry Pi to the internet through a Wi-Fi network](https://www.raspberrypi.org/documentation/configuration/wireless/desktop.md) or an Ethernet cable. **Note** Connect your Raspberry Pi to the *same* network that your computer is connected to, and be sure that both your computer and Raspberry Pi have internet access before you continue. If you're in a work environment or behind a firewall, you might need to connect your Pi and your computer to the guest network to get both devices on the same network. However, this approach might disconnect your computer from local network resources, such as your intranet. One solution is to connect the Pi to the guest Wi-Fi network and to connect your computer to the guest Wi-Fi network *and* your local network through an Ethernet cable. In this configuration, your computer should be able to connect to the Raspberry Pi through the guest Wi-Fi network and your local network resources through the Ethernet cable. 1. You must set up [SSH](https://en.wikipedia.org/wiki/Secure_Shell) on your Pi to remotely connect to it. On your Raspberry Pi, open a [terminal window](https://www.raspberrypi.org/documentation/usage/terminal/) and run the following command: ``` sudo raspi-config ``` You should see the following: ![\[Raspberry Pi Software Configuration Tool (raspi-config) screenshot.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-001.png) Scroll down and choose **Interfacing Options** and then choose **P2 SSH**. When prompted, choose **Yes**. (Use the Tab key followed by Enter). SSH should now be enabled. Choose **OK**. Use the Tab key to choose **Finish** and then press Enter. If the Raspberry Pi doesn't reboot automatically, run the following command: ``` sudo reboot ``` 1. On your Raspberry Pi, run the following command in the terminal: ``` hostname -I ``` This returns the IP address of your Raspberry Pi. **Note** For the following, if you receive an ECDSA key fingerprint message (`Are you sure you want to continue connecting (yes/no)?`), enter `yes`. The default password for the Raspberry Pi is **raspberry**. If you are using macOS, open a terminal window and enter the following: ``` ssh pi@IP-address ``` *IP-address* is the IP address of your Raspberry Pi that you obtained by using the `hostname -I` command. If you are using Windows, you need to install and configure [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html). Expand **Connection**, choose **Data**, and make sure that **Prompt** is selected: ![\[PuTTY window with Prompt selected.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-001.4.png) Next, choose **Session**, enter the IP address of the Raspberry Pi, and then choose **Open** using default settings. ![\[PuTTY window with IP address in the "Host Name (or IP address)" field.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-001.5.png) If a PuTTY security alert is displayed, choose **Yes**. The default Raspberry Pi login and password are **pi** and **raspberry**, respectively. ![\[Initial PuTTY terminal window.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-001.6.png) **Note** If your computer is connected to a remote network using VPN, you might have difficulty connecting from the computer to the Raspberry Pi using SSH. 1. You are now ready to set up the Raspberry Pi for AWS IoT Greengrass. First, run the following commands from a local Raspberry Pi terminal window or an SSH terminal window: **Tip** AWS IoT Greengrass also provides other options for installing the AWS IoT Greengrass Core software. For example, you can use [Greengrass device setup](quick-start.md) to configure your environment and install the latest version of the AWS IoT Greengrass Core software. Or, on supported Debian platforms, you can use the [APT package manager](install-ggc.md#ggc-package-manager) to install or upgrade the AWS IoT Greengrass Core software. For more information, see [Install the AWS IoT Greengrass Core software](install-ggc.md). ``` sudo adduser --system ggc_user sudo addgroup --system ggc_group ``` 1. To improve security on the Pi device, enable hardlink and softlink (symlink) protection on the operating system at startup. 1. Navigate to the `98-rpi.conf` file. ``` cd /etc/sysctl.d ls ``` **Note** If you don't see the `98-rpi.conf` file, follow the instructions in the `README.sysctl` file. 1. Use a text editor (such as Leafpad, GNU nano, or vi) to add the following two lines to the end of the file. You might need to use the `sudo` command to edit as root (for example, `sudo nano 98-rpi.conf`). ``` fs.protected_hardlinks = 1 fs.protected_symlinks = 1 ``` 1. Reboot the Pi. ``` sudo reboot ``` After about a minute, connect to the Pi using SSH and then run the following command to confirm the change: ``` sudo sysctl -a 2> /dev/null | grep fs.protected ``` You should see `fs.protected_hardlinks = 1` and `fs.protected_symlinks = 1`. 1. Edit your command line boot file to enable and mount memory cgroups. This allows AWS IoT Greengrass to set the memory limit for Lambda functions. Cgroups are also required to run AWS IoT Greengrass in the default [containerization](lambda-group-config.md#lambda-containerization-considerations) mode. 1. Navigate to your `boot` directory. ``` cd /boot/ ``` 1. Use a text editor to open `cmdline.txt`. Append the following to the end of the existing line, not as a new line. You might need to use the `sudo` command to edit as root (for example, `sudo nano cmdline.txt`). ``` cgroup_enable=memory cgroup_memory=1 ``` 1. Now reboot the Pi. ``` sudo reboot ``` Your Raspberry Pi should now be ready for AWS IoT Greengrass. 1. Optional. Install the Java 8 runtime, which is required by [stream manager](stream-manager.md). This tutorial doesn't use stream manager, but it does use the **Default Group creation** workflow that enables stream manager by default. Use the following commands to install the Java 8 runtime on the core device, or disable stream manager before you deploy your group. Instructions for disabling stream manager are provided in Module 3. ``` sudo apt install openjdk-8-jdk ``` 1. To make sure that you have all required dependencies, download and run the Greengrass dependency checker from the [AWS IoT Greengrass Samples](https://github.com/aws-samples/aws-greengrass-samples) repository on GitHub. These commands unzip and run the dependency checker script in the `Downloads` directory. **Note** The dependency checker might fail if you are running version 5.4.51 of the Raspbian kernel. This version does not mount memory cgroups correctly. This might cause Lambda functions running in container mode to fail. For more information on updating your kernel, see the [ Cgroups not loaded after kernel upgrade](https://www.raspberrypi.org/forums/viewtopic.php?t=280656) in the Raspberry Pi forums. ``` cd /home/pi/Downloads mkdir greengrass-dependency-checker-GGCv1.11.x cd greengrass-dependency-checker-GGCv1.11.x wget https://github.com/aws-samples/aws-greengrass-samples/raw/master/greengrass-dependency-checker-GGCv1.11.x.zip unzip greengrass-dependency-checker-GGCv1.11.x.zip cd greengrass-dependency-checker-GGCv1.11.x sudo modprobe configs sudo ./check_ggc_dependencies | more ``` Where `more` appears, press the Spacebar key to display another screen of text. **Important** This tutorial requires the Python 3.7 runtime to run local Lambda functions. When stream manager is enabled, it also requires the Java 8 runtime. If the `check_ggc_dependencies` script produces warnings about these missing runtime prerequisites, make sure to install them before you continue. You can ignore warnings about other missing optional runtime prerequisites. For information about the **modprobe** command, run **man modprobe** in the terminal. Your Raspberry Pi configuration is complete. Continue to [Module 2: Installing the AWS IoT Greengrass Core software](module2.md). # Setting up an Amazon EC2 instance Follow the steps in this topic to set up an Amazon EC2 instance to use as your AWS IoT Greengrass core. **Tip** Or, to use a script that sets up your environment and installs the AWS IoT Greengrass Core software for you, see [Quick start: Greengrass device setup](quick-start.md). Although you can complete this tutorial using an Amazon EC2 instance, AWS IoT Greengrass should ideally be used with physical hardware. We recommend that you [set up a Raspberry Pi](setup-filter.rpi.md) instead of using an Amazon EC2 instance when possible. If you're using a Raspberry Pi, you do not need to follow the steps in this topic.   1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/) and launch an Amazon EC2 instance using an Amazon Linux AMI. For information about Amazon EC2 instances, see the [Amazon EC2 Getting Started Guide](https://docs.aws.amazon.com/AWSEC2/latest/GettingStartedGuide/). 1. After your Amazon EC2 instance is running, enable port 8883 to allow incoming MQTT communications so that other devices can connect with the AWS IoT Greengrass core. 1. In the navigation pane of the Amazon EC2 console, choose **Security Groups**. ![\[Navigation pane with Security Groups highlighted.\]](http://docs.aws.amazon.com/greengrass/v1/developerguide/images/gg-get-started-002.6.1.png) 1. Select the security group for the instance that you just launched, and then choose the **Inbound rules** tab. 1. Choose **Edit inbound rules**. To enable port 8883, you add a custom TCP rule to the security group. For more information, see [ Adding rules to a security group](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html#adding-security-group-rule) in the *Amazon EC2 User Guide*. 1. On the **Edit inbound rules** page, choose **Add rule**, enter the following settings, and then choose **Save**. + For **Type**, choose **Custom TCP Rule**. + For **Port range**, enter **8883**. + For **Source**, choose **Anywhere**. + For **Description**, enter **MQTT Communications**.   1. Connect to your Amazon EC2 instance. 1. In the navigation pane, choose **Instances**, choose your instance, and then choose **Connect**. 1. Follow the instructions on the **Connect To Your Instance** page to connect to your instance [ by using SSH](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstancesLinux.html) and your private key file. You can use [PuTTY](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/putty.html) for Windows or Terminal for macOS. For more information, see [ Connect to your Linux instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstances.html) in the *Amazon EC2 User Guide*. You are now ready to set up your Amazon EC2 instance for AWS IoT Greengrass. 1. After you are connected to your Amazon EC2 instance, create the `ggc_user` and `ggc_group` accounts: ``` sudo adduser --system ggc_user sudo groupadd --system ggc_group ``` **Note** If the `adduser` command isn't available on your system, use the following command. ``` sudo useradd --system ggc_user ``` 1. To improve security, make sure that hardlink and softlink (symlink) protections are enabled on the operating system of the Amazon EC2 instance at startup. **Note** The steps for enabling hardlink and softlink protection vary by operating system. Consult the documentation for your distribution. 1. Run the following command to check if hardlink and softlink protections are enabled: ``` sudo sysctl -a | grep fs.protected ``` If hardlinks and softlinks are set to `1`, your protections are enabled correctly. Proceed to step 6. **Note** Softlinks are represented by `fs.protected_symlinks`. 1. If hardlinks and softlinks are not set to `1`, enable these protections. Navigate to your system configuration file. ``` cd /etc/sysctl.d ls ``` 1. Using your favorite text editor (Leafpad, GNU nano, or vi), add the following two lines to the end of the system configuration file. On Amazon Linux 1, this is the `00-defaults.conf` file. On Amazon Linux 2, this is the `99-amazon.conf` file. You might need to change permissions (using the `chmod` command) to write to the file, or use the `sudo` command to edit as root (for example, `sudo nano 00-defaults.conf`). ``` fs.protected_hardlinks = 1 fs.protected_symlinks = 1 ``` 1. Reboot the Amazon EC2 instance. ``` sudo reboot ``` After a few minutes, connect to your instance using SSH and then run the following command to confirm the change. ``` sudo sysctl -a | grep fs.protected ``` You should see that hardlinks and softlinks are set to 1. 1. Extract and run the following script to mount [Linux control groups](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/resource_management_guide/ch01) (cgroups). This allows AWS IoT Greengrass to set the memory limit for Lambda functions. Cgroups are also required to run AWS IoT Greengrass in the default [containerization](lambda-group-config.md#lambda-containerization-considerations) mode. ``` curl https://raw.githubusercontent.com/tianon/cgroupfs-mount/951c38ee8d802330454bdede20d85ec1c0f8d312/cgroupfs-mount > cgroupfs-mount.sh chmod +x cgroupfs-mount.sh sudo bash ./cgroupfs-mount.sh ``` Your Amazon EC2 instance should now be ready for AWS IoT Greengrass. 1. Optional. Install the Java 8 runtime, which is required by [stream manager](stream-manager.md). This tutorial doesn't use stream manager, but it does use the **Default Group creation** workflow that enables stream manager by default. Use the following commands to install the Java 8 runtime on the core device, or disable stream manager before you deploy your group. Instructions for disabling stream manager are provided in Module 3. + For Debian-based distributions: ``` sudo apt install openjdk-8-jdk ``` + For Red Hat-based distributions: ``` sudo yum install java-1.8.0-openjdk ``` 1. To make sure that you have all required dependencies, download and run the Greengrass dependency checker from the [AWS IoT Greengrass Samples](https://github.com/aws-samples/aws-greengrass-samples) repository on GitHub. These commands download, unzip, and run the dependency checker script in your Amazon EC2 instance. ``` mkdir greengrass-dependency-checker-GGCv1.11.x cd greengrass-dependency-checker-GGCv1.11.x wget https://github.com/aws-samples/aws-greengrass-samples/raw/master/greengrass-dependency-checker-GGCv1.11.x.zip unzip greengrass-dependency-checker-GGCv1.11.x.zip cd greengrass-dependency-checker-GGCv1.11.x sudo ./check_ggc_dependencies | more ``` **Important** This tutorial requires the Python 3.7 runtime to run local Lambda functions. When stream manager is enabled, it also requires the Java 8 runtime. If the `check_ggc_dependencies` script produces warnings about these missing runtime prerequisites, make sure to install them before you continue. You can ignore warnings about other missing optional runtime prerequisites. Your Amazon EC2 instance configuration is complete. Continue to [Module 2: Installing the AWS IoT Greengrass Core software](module2.md). # Setting up other devices Follow the steps in this topic to set up a device (other than a Raspberry Pi) to use as your AWS IoT Greengrass core. **Tip** Or, to use a script that sets up your environment and installs the AWS IoT Greengrass Core software for you, see [Quick start: Greengrass device setup](quick-start.md). If you're new to AWS IoT Greengrass, we recommend that you use a Raspberry Pi or an Amazon EC2 instance as your core device, and follow the [setup steps](module1.md) appropriate for your device. If you plan to build a custom Linux-based system using the Yocto Project, you can use the AWS IoT Greengrass Bitbake Recipe from the `meta-aws` project. This recipe also helps you develop a software platform that supports AWS edge software for embedded applications. The Bitbake build installs, configures, and automatically runs the AWS IoT Greengrass Core software on your device. Yocto Project An open source collaboration project that helps you build custom Linux-based systems for embedded applications regardless hardware architecture. For more information, see the [Yocto Project](https://www.yoctoproject.org/). `meta-aws` An AWS managed project that provides Yocto recipes. You can use the recipes to develop AWS edge sofware in Linux-based systems built with [OpenEmbedded](https://www.openembedded.org/wiki/Main_Page) and Yocto Project. For more information about this community supported capability, see the [https://github.com/aws/meta-aws](https://github.com/aws/meta-aws)project on GitHub. `meta-aws-demos` An AWS managed project that contains demonstrations for the `meta-aws` project. For more examples about the integration process, see the [https://github.com/aws-samples/meta-aws-demos](https://github.com/aws-samples/meta-aws-demos) project on GitHub. To use a different device or [supported platform](what-is-gg.md#gg-platforms), follow the steps in this topic. 1. If your core device is an NVIDIA Jetson device, you must first flash the firmware with the JetPack 4.3 installer. If you're configuring a different device, skip to step 2. **Note** The JetPack installer version that you use is based on your target CUDA Toolkit version. The following instructions use JetPack 4.3 and CUDA Toolkit 10.0. For information about using the versions appropriate for your device, see [How to Install Jetpack](https://docs.nvidia.com/jetson/jetpack/install-jetpack/index.html) in the NVIDIA documentation. 1. On a physical desktop that is running Ubuntu 16.04 or later, flash the firmware with the JetPack 4.3 installer, as described in [Download and Install JetPack](https://docs.nvidia.com/jetson/archives/jetpack-archived/jetpack-33/index.html#jetpack/3.3/install.htm%3FTocPath%3D_____3) (4.3) in the NVIDIA documentation. Follow the instructions in the installer to install all the packages and dependencies on the Jetson board, which must be connected to the desktop with a Micro-B cable. 1. Reboot your board in normal mode, and connect a display to the board. **Note** When you use SSH to connect to the Jetson board, use the default user name (**nvidia**) and the default password (**nvidia**). 1. Run the following commands to create user `ggc_user` and group `ggc_group`. The commands you run differ, depending on the distribution installed on your core device. + If your core device is running OpenWrt, run the following commands: ``` opkg install shadow-useradd opkg install shadow-groupadd useradd --system ggc_user groupadd --system ggc_group ``` + Otherwise, run the following commands: ``` sudo adduser --system ggc_user sudo addgroup --system ggc_group ``` **Note** If the `addgroup` command isn't available on your system, use the following command. ``` sudo groupadd --system ggc_group ``` 1. Optional. Install the Java 8 runtime, which is required by [stream manager](stream-manager.md). This tutorial doesn't use stream manager, but it does use the **Default Group creation** workflow that enables stream manager by default. Use the following commands to install the Java 8 runtime on the core device, or disable stream manager before you deploy your group. Instructions for disabling stream manager are provided in Module 3. + For Debian-based or Ubuntu-based distributions: ``` sudo apt install openjdk-8-jdk ``` + For Red Hat-based distributions: ``` sudo yum install java-1.8.0-openjdk ``` 1. To make sure that you have all required dependencies, download and run the Greengrass dependency checker from the [AWS IoT Greengrass Samples](https://github.com/aws-samples/aws-greengrass-samples) repository on GitHub. These commands unzip and run the dependency checker script. ``` mkdir greengrass-dependency-checker-GGCv1.11.x cd greengrass-dependency-checker-GGCv1.11.x wget https://github.com/aws-samples/aws-greengrass-samples/raw/master/greengrass-dependency-checker-GGCv1.11.x.zip unzip greengrass-dependency-checker-GGCv1.11.x.zip cd greengrass-dependency-checker-GGCv1.11.x sudo ./check_ggc_dependencies | more ``` **Note** The `check_ggc_dependencies` script runs on AWS IoT Greengrass supported platforms and requires specific Linux system commands. For more information, see the dependency checker's [Readme](https://github.com/aws-samples/aws-greengrass-samples/blob/master/greengrass-dependency-checker-GGCv1.11.x/README.md). 1. Install all required dependencies on your device, as indicated by the dependency checker output. For missing kernel-level dependencies, you might have to recompile your kernel. For mounting Linux control groups (`cgroups`), you can run the [cgroupfs-mount](https://raw.githubusercontent.com/tianon/cgroupfs-mount/master/cgroupfs-mount) script. This allows AWS IoT Greengrass to set the memory limit for Lambda functions. Cgroups are also required to run AWS IoT Greengrass in the default [containerization](lambda-group-config.md#lambda-containerization-considerations) mode. If no errors appear in the output, AWS IoT Greengrass should be able to run successfully on your device. **Important** This tutorial requires the Python 3.7 runtime to run local Lambda functions. When stream manager is enabled, it also requires the Java 8 runtime. If the `check_ggc_dependencies` script produces warnings about these missing runtime prerequisites, make sure to install them before you continue. You can ignore warnings about other missing optional runtime prerequisites. For the list of AWS IoT Greengrass requirements and dependencies, see [Supported platforms and requirements](what-is-gg.md#gg-platforms).