# Step 3: Install the AWS IoT Greengrass Core software **Tip** We recommend you try out [AWS IoT Greengrass AI Agents Context Pack](https://github.com/aws-greengrass/greengrass-agent-context-pack) to quickly set up and experiment with AWS IoT Greengrass. The agent context pack will enable AI agents to set up Greengrass Nucleus and Nucleus Lite, deploy components, and troubleshoot common issues. Follow the steps in this section to set up your Raspberry Pi as a AWS IoT Greengrass core device that you can use for local development. In this section, you download and run an installer that does the following to configure the AWS IoT Greengrass Core software for your device: + Installs the Greengrass nucleus component. The nucleus is a mandatory component and is the minimum requirement to run the AWS IoT Greengrass Core software on a device. For more information, see [Greengrass nucleus component](greengrass-nucleus-component.md). + Registers your device as an AWS IoT thing and downloads a digital certificate that allows your device to connect to AWS. For more information, see [Device authentication and authorization for AWS IoT Greengrass](device-auth.md). + Adds the device's AWS IoT thing to a thing group, which is a group or fleet of AWS IoT things. Thing groups enable you to manage fleets of Greengrass core devices. When you deploy software components to your devices, you can choose to deploy to individual devices or to groups of devices. For more information, see [Managing devices with AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-thing-management.html) in the *AWS IoT Core Developer Guide*. + Creates the IAM role that allows your Greengrass core device to interact with AWS services. By default, this role allows your device to interact with AWS IoT and send logs to Amazon CloudWatch Logs. For more information, see [Authorize core devices to interact with AWS services](device-service-role.md). + Installs the AWS IoT Greengrass command line interface (`greengrass-cli`), which you can use to test custom components that you develop on the core device. For more information, see [Greengrass Command Line Interface](gg-cli.md). # Install the AWS IoT Greengrass Core software (console) 1. Sign in to the [AWS IoT Greengrass console](https://console.aws.amazon.com/greengrass). 1. Under **Get started with Greengrass**, choose **Set up core device**. 1. Under **Step 1: Register a Greengrass core device**, for **Core device name**, enter the name of the AWS IoT thing for your Greengrass core device. If the thing doesn't exist, the installer creates it. 1. Under **Step 2: Add to a thing group to apply a continuous deployment**, for **Thing group**, choose the AWS IoT thing group to which you want to add your core device. + If you select **Enter a new group name**, then in **Thing group name**, enter the name of the new group to create. The installer creates the new group for you. + If you select **Select an existing group**, then in **Thing group name**, choose the existing group that you want to use. + If you select **No group**, then the installer doesn't add the core device to a thing group. 1. Under **Step 3: Install the Greengrass Core software**, complete the following steps. ------ #### [ Nucleus classic ] 1. Choose **Nucleus classic** as your core device's software runtime. 1. Choose your core device's operating system: **Linux** or **Windows**. 1. Provide your AWS credentials to the device so that the installer can provision the AWS IoT and IAM resources for your core device. To increase security, we recommend that you get temporary credentials for an IAM role that allows only the minimum permissions necessary to provision. For more information, see [Minimal IAM policy for installer to provision resources](provision-minimal-iam-policy.md). **Note** The installer doesn't save or store your credentials. On your device, do one of the following to retrieve credentials and make them available to the AWS IoT Greengrass Core software installer: + (Recommended) Use temporary credentials from AWS IAM Identity Center 1. Provide the access key ID, secret access key, and session token from the IAM Identity Center. For more information, see **Manual credential refresh** in [ Getting and refreshing temporary credentials](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html#how-to-get-temp-credentials) in the *IAM Identity Center user guide*. 1. Run the following commands to provide the credentials to the AWS IoT Greengrass Core software. ------ #### [ Linux or Unix ] ``` export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY export AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE= ``` ------ #### [ Windows Command Prompt (CMD) ] ``` set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY set AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE= ``` ------ #### [ PowerShell ] ``` $env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE" $env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" $env:AWS_SESSION_TOKEN="AQoDYXdzEJr1K...o5OytwEXAMPLE=" ``` ------ + Use temporary security credentials from an IAM role: 1. Provide the access key ID, secret access key, and session token from an IAM role that you assume. For more information about how to retrieve these credentials, see [Requesting temporary security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html) in the *IAM User Guide*. 1. Run the following commands to provide the credentials to the AWS IoT Greengrass Core software. ------ #### [ Linux or Unix ] ``` export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY export AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE= ``` ------ #### [ Windows Command Prompt (CMD) ] ``` set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY set AWS_SESSION_TOKEN=AQoDYXdzEJr1K...o5OytwEXAMPLE= ``` ------ #### [ PowerShell ] ``` $env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE" $env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" $env:AWS_SESSION_TOKEN="AQoDYXdzEJr1K...o5OytwEXAMPLE=" ``` ------ + Use long-term credentials from an IAM user: 1. Provide the access key ID and secret access key for your IAM user. You can create an IAM user for provisioning that you later delete. For the IAM policy to give the user, see [Minimal IAM policy for installer to provision resources](provision-minimal-iam-policy.md). For more information about how to retrieve long-term credentials, see [Managing access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) in the *IAM User Guide*. 1. Run the following commands to provide the credentials to the AWS IoT Greengrass Core software. ------ #### [ Linux or Unix ] ``` export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ``` ------ #### [ Windows Command Prompt (CMD) ] ``` set AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE set AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ``` ------ #### [ PowerShell ] ``` $env:AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE" $env:AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" ``` ------ 1. (Optional) If you created an IAM user to provision your Greengrass device, delete the user. 1. (Optional) If you used the access key ID and secret access key from an existing IAM user, update the keys for the user so that they are no longer valid. For more information, see [ Updating access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_RotateAccessKey) in the *AWS Identity and Access Management user guide*. 1. Under **Run the installer**, complete the following steps. 1. Under **Download the installer**, choose **Copy** and run the copied command on your core device. This command downloads the latest version of the AWS IoT Greengrass Core software and unzips it on your device. 1. Under **Run the installer**, choose **Copy**, and run the copied command on your core device. This command uses the AWS IoT thing and thing group names that you specified earlier to run the AWS IoT Greengrass Core software installer and set up AWS resources for your core device. This command also does the following: + Set up the AWS IoT Greengrass Core software as a system service that runs at boot. On Linux devices, this requires the [Systemd](https://en.wikipedia.org/wiki/Systemd) init system. **Important** On Windows core devices, you must set up the AWS IoT Greengrass Core software as a system service. + Deploy the [AWS IoT Greengrass CLI component](gg-cli.md), which is a command-line tool that enables you to develop custom Greengrass components on the core device. + Specify to use the `ggc_user` system user to run software components on the core device. On Linux devices, this command also specifies to use the `ggc_group` system group, and the installer creates the system user and group for you. When you run this command, you should see the following messages to indicate that the installer succeeded. ``` Successfully configured Nucleus with provisioned resource details! Configured Nucleus to deploy aws.greengrass.Cli component Successfully set up Nucleus as a system service ``` **Note** If you have a Linux device and it doesn't have [systemd](https://en.wikipedia.org/wiki/Systemd), the installer won't set up the software as a system service, and you won't see the success message for setting up the nucleus as a system service. ------ #### [ Nucleus lite ] 1. Choose **Nucleus lite** as your core device's software runtime. 1. Select your device set up method to provision your device to a Greengrass core device. **Option 1: Set up a device with package download (approximately 1MB)** 1. Create an AWS IoT thing and the role for Greengrass. 1. Download the zip file that contains AWS IoT resources that your device needs to connect to AWS IoT: + A certificate and private key generated using AWS IoT's certificate authority. + A schema file to initiate Greengrass installation for your device. 1. Download the package that will install the latest Greengrass Nucleus lite runtime to your Raspberry Pi. 1. Provision your device to become an AWS IoT Greengrass Core device and connect it to AWS IoT: 1. a. Transfer the Greengrass package and connection kit to your device using a USB thumb drive, SCP/FTP, or SD cards. 1. b. Unzip the greengrass-package.zip file in the /GreengrassInstaller directory on the device. 1. c. Unzip the connection kit zip file in the /directory on the device. 1. d. Run the provided command on the device to install AWS IoT Greengrass 1. Then, choose **View core devices**. **Option 2: Set up a device with a pre-configured whole disk sample image download (approximately 100MB)** 1. Create an AWS IoT thing and the role for Greengrass. 1. Download the zip file that contains AWS IoT resources that your device needs to connect to AWS IoT: + A certificate and private key generated using AWS IoT's certificate authority. + A schema file to initiate Greengrass installation for your device. 1. Download the pre-configured whole disk sample image that contains Greengrass and the operating system. 1. To transfer the connection kit and flash the image onto your device, follow the readme file downloaded with the image. 1. To start Greengrass installation, turn on and boot the device from the flashed image 1. Then, choose **View core devices**. **Option 3: Set up a device with your own custom build** 1. Create an AWS IoT thing and the role for Greengrass. 1. Download the zip file that contains AWS IoT resources that your device needs to connect to AWS IoT: + A certificate and private key generated using AWS IoT's certificate authority. + A schema file to initiate Greengrass installation for your device. 1. To customize and build your own image using Yocto from source code, and then use the connection kit to install nucleus lite, follow the instructions on GitHub. 1. Then, choose **View core devices**. ------ # Install the AWS IoT Greengrass Core software (CLI) **Note** These steps do not apply to nucleus lite. **To install and configure the AWS IoT Greengrass Core software** 1. On your Greengrass core device, run the following command to switch to the home directory. ------ #### [ Linux or Unix ] ``` cd ~ ``` ------ #### [ Windows Command Prompt (CMD) ] ``` cd %USERPROFILE% ``` ------ #### [ PowerShell ] ``` cd ~ ``` ------ 1. On your core device, download the AWS IoT Greengrass Core software to a file named `greengrass-nucleus-latest.zip`. ------ #### [ Linux or Unix ] ``` curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip > greengrass-nucleus-latest.zip ``` ------ #### [ Windows Command Prompt (CMD) ] ``` curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip > greengrass-nucleus-latest.zip ``` ------ #### [ PowerShell ] ``` iwr -Uri https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip -OutFile greengrass-nucleus-latest.zip ``` ------ By downloading this software, you agree to the [Greengrass Core Software License Agreement](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf). 1. Unzip the AWS IoT Greengrass Core software to a folder on your device. Replace *GreengrassInstaller* with the folder that you want to use. ------ #### [ Linux or Unix ] ``` unzip greengrass-nucleus-latest.zip -d GreengrassInstaller && rm greengrass-nucleus-latest.zip ``` ------ #### [ Windows Command Prompt (CMD) ] ``` mkdir GreengrassInstaller && tar -xf greengrass-nucleus-latest.zip -C GreengrassInstaller && del greengrass-nucleus-latest.zip ``` ------ #### [ PowerShell ] ``` Expand-Archive -Path greengrass-nucleus-latest.zip -DestinationPath .\\GreengrassInstaller rm greengrass-nucleus-latest.zip ``` ------ 1. Run the following command to launch the AWS IoT Greengrass Core software installer. This command does the following: + Create the AWS resources that the core device requires to operate. + Set up the AWS IoT Greengrass Core software as a system service that runs at boot. On Linux devices, this requires the [Systemd](https://en.wikipedia.org/wiki/Systemd) init system. **Important** On Windows core devices, you must set up the AWS IoT Greengrass Core software as a system service. + Deploy the [AWS IoT Greengrass CLI component](gg-cli.md), which is a command-line tool that enables you to develop custom Greengrass components on the core device. + Specify to use the `ggc_user` system user to run software components on the core device. On Linux devices, this command also specifies to use the `ggc_group` system group, and the installer creates the system user and group for you. Replace argument values in your command as follows. 1. `/greengrass/v2` or *C:\$1greengrass\$1v2*: The path to the root folder to use to install the AWS IoT Greengrass Core software. 1. *GreengrassInstaller*. The path to the folder where you unpacked the AWS IoT Greengrass Core software installer. 1. *region*. The AWS Region in which to find or create resources. 1. *MyGreengrassCore*. The name of the AWS IoT thing for your Greengrass core device. If the thing doesn't exist, the installer creates it. The installer downloads the certificates to authenticate as the AWS IoT thing. For more information, see [Device authentication and authorization for AWS IoT Greengrass](device-auth.md). **Note** The thing name can't contain colon (`:`) characters. 1. *MyGreengrassCoreGroup*. The name of AWS IoT thing group for your Greengrass core device. If the thing group doesn't exist, the installer creates it and adds the thing to it. If the thing group exists and has an active deployment, the core device downloads and runs the software that the deployment specifies. **Note** The thing group name can't contain colon (`:`) characters. 1. *GreengrassV2IoTThingPolicy*. The name of the AWS IoT policy that allows the Greengrass core devices to communicate with AWS IoT and AWS IoT Greengrass. If the AWS IoT policy doesn't exist, the installer creates a permissive AWS IoT policy with this name. You can restrict this policy's permissions for you use case. For more information, see [Minimal AWS IoT policy for AWS IoT Greengrass V2 core devices](device-auth.md#greengrass-core-minimal-iot-policy). 1. *GreengrassV2TokenExchangeRole*. The name of the IAM role that allows the Greengrass core device to get temporary AWS credentials. If the role doesn't exist, the installer creates it and creates and attaches a policy named `GreengrassV2TokenExchangeRoleAccess`. For more information, see [Authorize core devices to interact with AWS services](device-service-role.md). 1. *GreengrassCoreTokenExchangeRoleAlias*. The alias to the IAM role that allows the Greengrass core device to get temporary credentials later. If the role alias doesn't exist, the installer creates it and points it to the IAM role that you specify. For more information, see [Authorize core devices to interact with AWS services](device-service-role.md). ------ #### [ Linux or Unix ] ``` sudo -E java -Droot="/greengrass/v2" -Dlog.store=FILE \ -jar ./GreengrassInstaller/lib/Greengrass.jar \ --aws-region region \ --thing-name MyGreengrassCore \ --thing-group-name MyGreengrassCoreGroup \ --thing-policy-name GreengrassV2IoTThingPolicy \ --tes-role-name GreengrassV2TokenExchangeRole \ --tes-role-alias-name GreengrassCoreTokenExchangeRoleAlias \ --component-default-user ggc_user:ggc_group \ --provision true \ --setup-system-service true \ --deploy-dev-tools true ``` ------ #### [ Windows Command Prompt (CMD) ] ``` java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" ^ -jar ./GreengrassInstaller/lib/Greengrass.jar ^ --aws-region region ^ --thing-name MyGreengrassCore ^ --thing-group-name MyGreengrassCoreGroup ^ --thing-policy-name GreengrassV2IoTThingPolicy ^ --tes-role-name GreengrassV2TokenExchangeRole ^ --tes-role-alias-name GreengrassCoreTokenExchangeRoleAlias ^ --component-default-user ggc_user ^ --provision true ^ --setup-system-service true ^ --deploy-dev-tools true ``` ------ #### [ PowerShell ] ``` java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" ` -jar ./GreengrassInstaller/lib/Greengrass.jar ` --aws-region region ` --thing-name MyGreengrassCore ` --thing-group-name MyGreengrassCoreGroup ` --thing-policy-name GreengrassV2IoTThingPolicy ` --tes-role-name GreengrassV2TokenExchangeRole ` --tes-role-alias-name GreengrassCoreTokenExchangeRoleAlias ` --component-default-user ggc_user ` --provision true ` --setup-system-service true ` --deploy-dev-tools true ``` ------ **Note** If you are running AWS IoT Greengrass on a device with limited memory, you can control the amount of memory that AWS IoT Greengrass Core software uses. To control memory allocation, you can set JVM heap size options in the `jvmOptions` configuration parameter in your nucleus component. For more information, see [Control memory allocation with JVM options](configure-greengrass-core-v2.md#jvm-tuning). When you run this command, you should see the following messages to indicate that the installer succeeded. ``` Successfully configured Nucleus with provisioned resource details! Configured Nucleus to deploy aws.greengrass.Cli component Successfully set up Nucleus as a system service ``` **Note** If you have a Linux device and it doesn't have [systemd](https://en.wikipedia.org/wiki/Systemd), the installer won't set up the software as a system service, and you won't see the success message for setting up the nucleus as a system service. # (Optional) Run the Greengrass software (Linux) **Note** These steps do not apply to nucleus lite. If you installed the software as a system service, the installer runs the software for you. Otherwise, you must run the software. To see if the installer set up the software as a system service, look for the following line in the installer output. ``` Successfully set up Nucleus as a system service ``` If you don't see this message, do the following to run the software: 1. Run the following command to run the software. ``` sudo /greengrass/v2/alts/current/distro/bin/loader ``` The software prints the following message if it launches successfully. ``` Launched Nucleus successfully. ``` 1. You must leave the current command shell open to keep the AWS IoT Greengrass Core software running. If you use SSH to connect to the core device, run the following command on your development computer to open a second SSH session that you can use to run additional commands on the core device. Replace *username* with the name of the user to sign in, and replace *pi-ip-address* with the IP address of the device. ``` ssh username@pi-ip-address ``` For more information about how to interact with the Greengrass system service, see [Configure the Greengrass nucleus as a system service](configure-greengrass-core-v2.md#configure-system-service). # Verify the Greengrass CLI installation on the device **Note** These steps do not apply to nucleus lite. The Greengrass CLI can take up to a minute to deploy. Run the following command to check the status of the deployment. Replace *MyGreengrassCore* with the name of your core device. ``` aws greengrassv2 list-effective-deployments --core-device-thing-name MyGreengrassCore ``` The `coreDeviceExecutionStatus` indicates the status of the deployment to the core device. When the status is `SUCCEEDED`, run the following command to verify that the Greengrass CLI is installed and runs. Replace `/greengrass/v2` with the path to the root folder. ------ #### [ Linux or Unix ] ``` /greengrass/v2/bin/greengrass-cli help ``` ------ #### [ Windows Command Prompt (CMD) ] ``` C:\greengrass\v2\bin\greengrass-cli help ``` ------ #### [ PowerShell ] ``` C:\greengrass\v2\bin\greengrass-cli help ``` ------ The command outputs help information for the Greengrass CLI. If the `greengrass-cli` isn't found, the deployment might have failed to install the Greengrass CLI. For more information, see [Troubleshooting AWS IoT Greengrass V2](troubleshooting.md). You can also run the following command to manually deploy the AWS IoT Greengrass CLI to your device. + Replace *region* with the AWS Region that you use. Make sure that you use the same AWS Region that you used to configure the AWS CLI on your device. + Replace *account-id* with your AWS account ID. + Replace *MyGreengrassCore* with the name of your core device. ------ #### [ Linux, macOS, or Unix ] ``` aws greengrassv2 create-deployment \ --target-arn "arn:aws:iot:region:account-id:thing/MyGreengrassCore" \ --components '{ "aws.greengrass.Cli": { "componentVersion": "2.17.0" } }' ``` ------ #### [ Windows Command Prompt (CMD) ] ``` aws greengrassv2 create-deployment ^ --target-arn "arn:aws:iot:region:account-id:thing/MyGreengrassCore" ^ --components "{\"aws.greengrass.Cli\":{\"componentVersion\":\"2.17.0\"}}" ``` ------ #### [ PowerShell ] ``` aws greengrassv2 create-deployment ` --target-arn "arn:aws:iot:region:account-id:thing/MyGreengrassCore" ` --components '{\"aws.greengrass.Cli\":{\"componentVersion\":\"2.17.0\"}}' ``` ------ **Tip** You can add `/greengrass/v2/bin` (Linux) or `C:\greengrass\v2\bin` (Windows) to your `PATH` environment variable to run `greengrass-cli` without its absolute path. The AWS IoT Greengrass Core software and local development tools run on your device. Next, you can develop a Hello World AWS IoT Greengrass component on your device.