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 2: Installing the AWS IoT Greengrass Core software This module shows you how to install the AWS IoT Greengrass Core software on your chosen device. In this module, you first create a Greengrass group and core. Then, you download, configure, and start the software on your core device. For more information about AWS IoT Greengrass Core software functionality, see [Configure the AWS IoT Greengrass core](gg-core.md). Before you begin, make sure that you have completed the setup steps in [Module 1](module1.md) for your chosen device. **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). This module should take less than 30 minutes to complete. **Topics** + [Provision an AWS IoT thing to use as a Greengrass core](provision-core.md) + [Create an AWS IoT Greengrass group for the core](create-group.md) + [Install and run AWS IoT Greengrass on the core device](start-greengrass.md) # Provision an AWS IoT thing to use as a Greengrass core Greengrass *cores* are devices that run the AWS IoT Greengrass Core software to manage local IoT processes. To set up a Greengrass core, you create an AWS IoT *thing*, which represents a device or logical entity that connects to AWS IoT. When you register a device as an AWS IoT thing, that device can use a digital certificate and keys that allow it to access AWS IoT. You use an [AWS IoT policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) to allow the device to communicate with the AWS IoT and AWS IoT Greengrass services. In this section, you register your device as an AWS IoT thing to use it as a Greengrass core. **To create an AWS IoT thing** 1. Navigate to the [AWS IoT console](https://console.aws.amazon.com/iot). 1. Under **Manage**, expand **All devices**, and then choose **Things**. 1. On the **Things** page, choose **Create things**. 1. On the **Create things** page, choose **Create single thing**, and then choose **Next**. 1. On the **Specify thing properties** page, do the following: 1. For **Thing name**, enter a name that represents your device, such as **MyGreengrassV1Core**. 1. Choose **Next**. 1. On the **Configure device certificate** page, choose **Next**. 1. On the **Attach policies to certificate** page, do one of the following: + Select an existing policy that grants permissions that cores require, and then choose **Create thing**. A modal opens where you can download the certificates and keys that the device uses to connect to the AWS Cloud. + Create an attach a new policy that grants core device permissions. Do the following: 1. Choose **Create policy**. The **Create policy** page opens in a new tab. 1. On the **Create policy** page, do the following: 1. For **Policy name**, enter a name that describes the policy, such as **GreengrassV1CorePolicy**. 1. On the **Policy statements** tab, under **Policy document**, choose **JSON**. 1. Enter the following policy document. This policy allows the core to communicate with the AWS IoT Core service, interact with device shadows, and communicate with the AWS IoT Greengrass service. For information about how to restrict this policy's access based on your use case, see [Minimal AWS IoT policy for the AWS IoT Greengrass core device](device-auth.md#gg-config-sec-min-iot-policy). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish", "iot:Subscribe", "iot:Connect", "iot:Receive" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": [ "iot:GetThingShadow", "iot:UpdateThingShadow", "iot:DeleteThingShadow" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": [ "greengrass:*" ], "Resource": [ "*" ] } ] } ``` ------ 1. Choose **Create** to create the policy. 1. Return to the browser tab with the **Attach policies to certificate** page open. Do the following: 1. In the **Policies** list, select the policy that you created, such as **GreengrassV1CorePolicy**. If you don't see the policy, choose the refresh button. 1. Choose **Create thing**. A modal opens where you can download the certificates and keys that the core uses to connect to AWS IoT. 1. Return to the browser tab with the **Attach policies to certificate** page open. Do the following: 1. In the **Policies** list, select the policy that you created, such as **GreengrassV1CorePolicy**. If you don't see the policy, choose the refresh button. 1. Choose **Create thing**. A modal opens where you can download the certificates and keys that the core uses to connect to AWS IoT. 1. In the **Download certificates and keys** modal, download the device's certificates. **Important** Before you choose **Done**, download the security resources. Do the following: 1. For **Device certificate**, choose **Download** to download the device certificate. 1. For **Public key file**, choose **Download** to download the public key for the certificate. 1. For **Private key file**, choose **Download** to download the private key file for the certificate. 1. Review [Server Authentication](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html) in the *AWS IoT Developer Guide* and choose the appropriate root CA certificate. We recommend that you use Amazon Trust Services (ATS) endpoints and ATS root CA certificates. Under **Root CA certificates**, choose **Download** for a root CA certificate. 1. Choose **Done**. Make a note of the certificate ID that's common in the file names for the device certificate and keys. You need it later. # Create an AWS IoT Greengrass group for the core AWS IoT Greengrass *groups* contain settings and other information about its components, such as client devices, Lambda functions, and connectors. A group defines the configuration for a core, including how its components can interact with each other. In this section, you create a group for your core. **Tip** For an example that uses the AWS IoT Greengrass API to create and deploy a group, see the [gg\$1group\$1setup](https://github.com/awslabs/aws-greengrass-group-setup) repository on GitHub. **To create a group for the core** 1. Navigate to the [AWS IoT console](https://console.aws.amazon.com/iot). 1. Under **Manage**, expand **Greengrass devices**, and choose **Groups (V1)**. **Note** If you don't see the **Greengrass devices** menu, change to an AWS Region that supports AWS IoT Greengrass V1. For the list of supported Regions, see [AWS IoT Greengrass V1 endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/greengrass.html) in the *AWS General Reference*. You must [create the AWS IoT thing for your core](provision-core.md) in a Region where AWS IoT Greengrass V1 is available. 1. On the **Greengrass groups** page, choose **Create group**. 1. On the **Create Greengrass group** page, do the following: 1. For **Greengrass group name**, enter a name that describes the group, such as **MyGreengrassGroup**. 1. For **Greengrass core**, choose the AWS IoT thing that you created earlier, such as **MyGreengrassV1Core**. The console automatically selects the thing's device certificate for you. 1. Choose **Create group**. # Install and run AWS IoT Greengrass on the core device **Note** This tutorial provides instructions for you to run the AWS IoT Greengrass Core software on a Raspberry Pi, but you can use any supported device. In this section, you configure, install, and run the AWS IoT Greengrass Core software on your core device. **To install and run AWS IoT Greengrass** 1. From the [AWS IoT Greengrass Core software](what-is-gg.md#gg-core-download-tab) section in this guide, download the AWS IoT Greengrass Core software installation package. Choose the package that best fits the CPU architecture, distribution, and OS of your core device. + For Raspberry Pi, download the package for the Armv7l architecture and Linux operating system. + For an Amazon EC2 instance, download the package for the x86\$164 architecture and Linux operating system. + For NVIDIA Jetson TX2, download the package for the Armv8 (AArch64) architecture and Linux operating system. + For Intel Atom, download the package for the x86\$164 architecture and Linux operating system. 1. In previous steps, you downloaded five files to your computer: + `greengrass-OS-architecture-1.11.6.tar.gz` – This compressed file contains the AWS IoT Greengrass Core software that runs on the core device. + `certificateId-certificate.pem.crt` – The device certificate file. + `certificateId-public.pem.key` – The device certificate's public key file. + `certificateId-private.pem.key` – The device certificate's private key file. + `AmazonRootCA1.pem` – The Amazon root certificate authority (CA) file. In this step, you transfer these files from your computer to your core device. Do the following: 1. If you don't know the IP address of your Greengrass core device, open a terminal on the core device and run the following command. **Note** This command might not return the correct IP address for some devices. Consult the documentation for your device to retrieve your device IP address. ``` hostname -I ``` 1. Transfer these files from your computer to your core device. The file transfer steps vary depending on the operating system of your computer. Choose your operating system for steps that show how to transfer files to your Raspberry Pi device. **Note** For a Raspberry Pi, the default user name is **pi** and the default password is **raspberry**. For an NVIDIA Jetson TX2, the default user name is **nvidia** and the default password is **nvidia**. ------ #### [ Windows ] To transfer the compressed files from your computer to a Raspberry Pi core device, use a tool such as [WinSCP](https://winscp.net/eng/download.php) or the [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) **pscp** command. To use the **pscp** command, open a Command Prompt window on your computer and run the following: ``` cd path-to-downloaded-files pscp -pw Pi-password greengrass-OS-architecture-1.11.6.tar.gz pi@IP-address:/home/pi pscp -pw Pi-password certificateId-certificate.pem.crt pi@IP-address:/home/pi pscp -pw Pi-password certificateId-public.pem.key pi@IP-address:/home/pi pscp -pw Pi-password certificateId-private.pem.key pi@IP-address:/home/pi pscp -pw Pi-password AmazonRootCA1.pem pi@IP-address:/home/pi ``` **Note** The version number in this command must match the version of your AWS IoT Greengrass Core software package. ------ #### [ macOS ] To transfer the compressed files from your Mac to a Raspberry Pi core device, open a Terminal window on your computer and run the following commands. The *path-to-downloaded-files* is typically `~/Downloads`. **Note** You might be prompted for two passwords. If so, the first password is for the Mac's `sudo` command and the second is the password for the Raspberry Pi. ``` cd path-to-downloaded-files scp greengrass-OS-architecture-1.11.6.tar.gz pi@IP-address:/home/pi scp certificateId-certificate.pem.crt pi@IP-address:/home/pi scp certificateId-public.pem.key pi@IP-address:/home/pi scp certificateId-private.pem.key pi@IP-address:/home/pi scp AmazonRootCA1.pem pi@IP-address:/home/pi ``` **Note** The version number in this command must match the version of your AWS IoT Greengrass Core software package. ------ #### [ UNIX-like system ] To transfer the compressed files from your computer to a Raspberry Pi core device, open a terminal window on your computer and run the following commands: ``` cd path-to-downloaded-files scp greengrass-OS-architecture-1.11.6.tar.gz pi@IP-address:/home/pi scp certificateId-certificate.pem.crt pi@IP-address:/home/pi scp certificateId-public.pem.key pi@IP-address:/home/pi scp certificateId-private.pem.key pi@IP-address:/home/pi scp AmazonRootCA1.pem pi@IP-address:/home/pi ``` **Note** The version number in this command must match the version of your AWS IoT Greengrass Core software package. ------ #### [ Raspberry Pi web browser ] If you used the Raspberry Pi's web browser to download the compressed files, the files should be in the Pi's `~/Downloads` folder, such as `/home/pi/Downloads`. Otherwise, the compressed files should be in the Pi's `~` folder, such as `/home/pi`. ------ 1. On the Greengrass core device, open a terminal, and navigate to the folder that contains the AWS IoT Greengrass Core software and certificates. Replace *path-to-transferred-files* with the path where you transferred the files on the core device. For example, on a Raspberry Pi, run `cd /home/pi`. ``` cd path-to-transferred-files ``` 1. Unpack the AWS IoT Greengrass Core software on the core device. Run the following command to unpack the software archive that you transferred to the core device. This command uses the `-C /` argument to create the `/greengrass` folder in the root folder of the core device. ``` sudo tar -xzvf greengrass-OS-architecture-1.11.6.tar.gz -C / ``` **Note** The version number in this command must match the version of your AWS IoT Greengrass Core software package. 1. Move the certificates and keys to the AWS IoT Greengrass Core software folder. Run the following commands to create a folder for certificates and move the certificates and keys to it. Replace *path-to-transferred-files* with the path where you transferred the files on the core device, and replace *certificateId* with the certificate ID in the file names. For example, on a Raspberry Pi, replace *path-to-transferred-files* with **/home/pi** ``` sudo mv path-to-transferred-files/certificateId-certificate.pem.crt /greengrass/certs sudo mv path-to-transferred-files/certificateId-public.pem.key /greengrass/certs sudo mv path-to-transferred-files/certificateId-private.pem.key /greengrass/certs sudo mv path-to-transferred-files/AmazonRootCA1.pem /greengrass/certs ``` 1. The AWS IoT Greengrass Core software uses a configuration file that specifies parameters for the software. This configuration file specifies the file paths for certificate files and the AWS Cloud endpoints to use. In this step, you create the AWS IoT Greengrass Core software configuration file for your core. Do the following: 1. Get the Amazon Resource Name (ARN) for your core's AWS IoT thing. Do the following: 1. In the [AWS IoT console](https://console.aws.amazon.com/iot), under **Manage**, under **Greengrass devices**, choose **Groups (V1)**. 1. On the **Greengrass groups** page, choose the group that you created earlier. 1. Under **Overview**, choose **Greengrass core**. 1. On the core details page, copy the **AWS IoT thing ARN**, and save it to use in the AWS IoT Greengrass Core configuration file. 1. Get the AWS IoT device data endpoint for your AWS account in the current Region. Devices use this endpoint to connect to AWS as AWS IoT things. Do the following: 1. In the [AWS IoT console](https://console.aws.amazon.com/iot), choose **Settings**. 1. Under **Device data endpoint**, copy the **Endpoint**, and save it to use in the AWS IoT Greengrass Core configuration file. 1. Create the AWS IoT Greengrass Core software configuration file. For example, you can run the following command to use GNU nano to create the file. ``` sudo nano /greengrass/config/config.json ``` Replace the contents of the file with the following JSON document. ``` { "coreThing" : { "caPath": "AmazonRootCA1.pem", "certPath": "certificateId-certificate.pem.crt", "keyPath": "certificateId-private.pem.key", "thingArn": "arn:aws:iot:region:account-id:thing/MyGreengrassV1Core", "iotHost": "device-data-prefix-ats.iot.region.amazonaws.com", "ggHost": "greengrass-ats.iot.region.amazonaws.com", "keepAlive": 600 }, "runtime": { "cgroup": { "useSystemd": "yes" } }, "managedRespawn": false, "crypto": { "caPath": "file:///greengrass/certs/AmazonRootCA1.pem", "principals": { "SecretsManager": { "privateKeyPath": "file:///greengrass/certs/certificateId-private.pem.key" }, "IoTCertificate": { "privateKeyPath": "file:///greengrass/certs/certificateId-private.pem.key", "certificatePath": "file:///greengrass/certs/certificateId-certificate.pem.crt" } } } } ``` Then, do the following: + If you downloaded a different Amazon root CA certificate than Amazon Root CA 1, replace each instance of *AmazonRootCA1.pem* with the name of the Amazon root CA file. + Replace each instance of *certificateId* with the certificate ID in the name of the certificate and key files. + Replace *arn:aws:iot:*region*:*account-id*:thing/MyGreengrassV1Core* with the ARN of your core's thing that you saved earlier. + Replace *MyGreengrassV1core* with the name of your core's thing. + Replace *device-data-prefix-ats.iot.region.amazonaws.com* with the AWS IoT device data endpoint that you saved earlier. + Replace *region* with your AWS Region. For more information about the configuration options that you can specify in this configuration file, see [AWS IoT Greengrass core configuration file](gg-core.md#config-json). 1. Make sure that your core device is connected to the internet. Then, start AWS IoT Greengrass on your core device. ``` cd /greengrass/ggc/core/ sudo ./greengrassd start ``` You should see a `Greengrass successfully started` message. Make a note of the PID. **Note** To set up your core device to start AWS IoT Greengrass on system boot, see [Configure the init system to start the Greengrass daemon](gg-core.md#start-on-boot). You can run the following command to confirm that the AWS IoT Greengrass Core software (Greengrass daemon) is functioning. Replace *PID-number* with your PID: ``` ps aux | grep PID-number ``` You should see an entry for the PID with a path to the running Greengrass daemon (for example, `/greengrass/ggc/packages/1.11.6/bin/daemon`). If you run into issues starting AWS IoT Greengrass, see [Troubleshooting AWS IoT Greengrass](gg-troubleshooting.md).