# Install the AWS IoT Greengrass Core software
AWS IoT Greengrass extends AWS to edge devices so that they can act on the data they generate, while they use the AWS Cloud for management, analytics, and durable storage. Install the AWS IoT Greengrass Core software on edge devices to integrate with AWS IoT Greengrass and the AWS Cloud.
**Important**
Before you download and install the AWS IoT Greengrass Core software, check that your core device meets the [requirements](greengrass-nucleus-component.md#greengrass-v2-requirements) to install and run the AWS IoT Greengrass Core software v2.0.
The AWS IoT Greengrass Core software includes an installer that sets up your device as a Greengrass core device. When you run the installer, you can configure options, such as the root folder and the AWS Region to use. You can choose to have the installer create required AWS IoT and IAM resources for you. You can also choose to deploy local development tools to configure a device that you use for custom component development.
The AWS IoT Greengrass Core software requires the following AWS IoT and IAM resources to connect to the AWS Cloud and operate:
+ An AWS IoT thing. When you register a device as an AWS IoT thing, that device can use a digital certificate to authenticate with AWS. This certificate allows the device to communicate with AWS IoT and AWS IoT Greengrass. For more information, see [Device authentication and authorization for AWS IoT Greengrass](device-auth.md).
+ (Optional) An AWS IoT thing group. You use thing groups 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. You can add a device to a thing group to deploy that thing group's software components to the device. For more information, see [Deploy AWS IoT Greengrass components to devices](manage-deployments.md).
+ An IAM role. Greengrass core devices use the AWS IoT Core credentials provider to authorize calls to AWS services with an IAM role. This role allows your device to interact with AWS IoT, send logs to Amazon CloudWatch Logs, and download custom component artifacts from Amazon Simple Storage Service (Amazon S3). For more information, see [Authorize core devices to interact with AWS services](device-service-role.md).
+ An AWS IoT role alias. Greengrass core devices use the role alias to identify the IAM role to use. The role alias enables you to change the IAM role but keep the device configuration the same. For more information, see [Authorizing direct calls to AWS services](https://docs.aws.amazon.com/iot/latest/developerguide/authorizing-direct-aws.html) in the *AWS IoT Core Developer Guide*.
Choose one of the following options to install the AWS IoT Greengrass Core software on your core device.
+ **Quick installation**
Choose this option to set up a Greengrass core device in as few steps as possible. The installer creates the required AWS IoT and IAM resources for you. This option requires you to provide AWS credentials to the installer to create resources in your AWS account.
You can't use this option to install behind a firewall or network proxy. If your devices are behind a firewall or network proxy, consider [manual installation](manual-installation.md).
For more information, see [Install AWS IoT Greengrass Core software with automatic resource provisioning](quick-installation.md).
+ **Manual installation**
Choose this option to create the required AWS resources manually or to install behind a firewall or network proxy. By using a manual installation, you don't need to give the installer permission to create resources in your AWS account, because you create the required AWS IoT and IAM resources. You can also configure your device to connect on port 443 or through a network proxy. You can also configure the AWS IoT Greengrass Core software to use a private key and certificate that you store in a hardware security module (HSM), Trusted Platform Module (TPM), or another cryptographic element.
For more information, see [Install AWS IoT Greengrass Core software with manual resource provisioning](manual-installation.md).
+ **Installation with AWS IoT fleet provisioning**
Choose this option to create the required AWS resources from an AWS IoT fleet provisioning template. You might choose this option to create similar devices in a fleet, or if you manufacture devices that your customers later activate, such as vehicles or smart home devices. Devices use claim certificates to authenticate and provision AWS resources, including an X.509 client certificate that the device uses to connect to the AWS Cloud for normal operation. You can embed or flash the claim certificates into the device's hardware during manufacturing, and you can use the same claim certificate and key to provision multiple devices. You can also configure devices to connect on port 443 or through a network proxy.
For more information, see [Install AWS IoT Greengrass Core software with AWS IoT fleet provisioning](fleet-provisioning.md).
+ **Installation with custom provisioning**
Choose this option to develop a custom Java application that provisions the required AWS resources. You might choose this option if you [create your own X.509 client certificates](https://docs.aws.amazon.com/iot/latest/developerguide/device-certs-your-own.html) or if you want more control over the provisioning process. AWS IoT Greengrass provides an interface that you can implement to exchange information between your custom provisioning application and the AWS IoT Greengrass Core software installer.
For more information, see [Install AWS IoT Greengrass Core software with custom resource provisioning](custom-provisioning.md).
AWS IoT Greengrass also provides containerized environments that run the AWS IoT Greengrass Core software. You can use a Dockerfile to [run AWS IoT Greengrass in a Docker container](run-greengrass-docker.md).
**Topics**
+ [Install with automatic provisioning](quick-installation.md)
+ [Install with manual provisioning](manual-installation.md)
+ [Install with fleet provisioning](fleet-provisioning.md)
+ [Install with custom provisioning](custom-provisioning.md)
+ [Installer arguments](configure-installer.md)
# Install AWS IoT Greengrass Core software with automatic resource provisioning
The AWS IoT Greengrass Core software includes an installer that sets up your device as a Greengrass core device. To set up a device quickly, the installer can provision the AWS IoT thing, AWS IoT thing group, IAM role, and AWS IoT role alias that the core device requires to operate. The installer can also deploy the local development tools to the core device, so you can use the device to develop and test custom software components. The installer requires AWS credentials to provision these resources and create the deployment.
If you can't provide AWS credentials to the device, you can provision the AWS resources that the core device requires to operate. You can also deploy the development tools to a core device to use as a development device. This enables you to provide fewer permissions to the device when you run the installer. For more information, see [Install AWS IoT Greengrass Core software with manual resource provisioning](manual-installation.md).
**Important**
Before you download the AWS IoT Greengrass Core software, check that your core device meets the [requirements](greengrass-nucleus-component.md#greengrass-v2-requirements) to install and run the AWS IoT Greengrass Core software v2.0.
**Note**
To install and run the AWS IoT Greengrass Core software as a non-root user, see [Set up AWS IoT Greengrass V2 core devices as non-root](setup-greengrass-non-root.md).
**Topics**
+ [Set up the device environment](#set-up-device-environment)
+ [Provide AWS credentials to the device](#provide-installer-aws-credentials)
+ [Download the AWS IoT Greengrass Core software](#download-greengrass-core-v2)
+ [Install the AWS IoT Greengrass Core software](#run-greengrass-core-v2-installer)
## Set up the device environment
Follow the steps in this section to set up a Linux or Windows device to use as your AWS IoT Greengrass core device.
### Set up a Linux device
**To set up a Linux device for AWS IoT Greengrass V2**
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend that you use [Amazon Corretto](https://aws.amazon.com/corretto/) or [OpenJDK](https://openjdk.java.net/) long-term support versions. Version 8 or higher is required. The following commands show you how to install OpenJDK on your device.
+ For Debian-based or Ubuntu-based distributions:
```
sudo apt install default-jdk
```
+ For Red Hat-based distributions:
```
sudo yum install java-11-openjdk-devel
```
+ For Amazon Linux 2:
```
sudo amazon-linux-extras install java-openjdk11
```
+ For Amazon Linux 2023:
```
sudo dnf install java-11-amazon-corretto -y
```
When the installation completes, run the following command to verify that Java runs on your Linux device.
```
java -version
```
The command prints the version of Java that runs on the device. For example, on a Debian-based distribution, the output might look similar to the following sample.
```
openjdk version "11.0.9.1" 2020-11-04
OpenJDK Runtime Environment (build 11.0.9.1+1-post-Debian-1deb10u2)
OpenJDK 64-Bit Server VM (build 11.0.9.1+1-post-Debian-1deb10u2, mixed mode)
```
1. (Optional) Create the default system user and group that runs components on the device. You can also choose to let the AWS IoT Greengrass Core software installer create this user and group during installation with the `--component-default-user` installer argument. For more information, see [Installer arguments](configure-installer.md).
```
sudo useradd --system --create-home ggc_user
sudo groupadd --system ggc_group
```
1. Verify that the user that runs the AWS IoT Greengrass Core software (typically `root`), has permission to run `sudo` with any user and any group.
1. Run the following command to open the `/etc/sudoers` file.
```
sudo visudo
```
1. Verify that the permission for the user looks like the following example.
```
root ALL=(ALL:ALL) ALL
```
1. (Optional) To [run containerized Lambda functions](run-lambda-functions.md), you must enable [cgroups](https://en.wikipedia.org/wiki/Cgroups) v1, and you must enable and mount the *memory* and *devices* cgroups. If you don't plan to run containerized Lambda functions, you can skip this step.
To enable these cgroups options, boot the device with the following Linux kernel parameters.
```
cgroup_enable=memory cgroup_memory=1 systemd.unified_cgroup_hierarchy=0
```
For information about viewing and setting kernel parameters for your device, see the documentation for your operating system and boot loader. Follow the instructions to permanently set the kernel parameters.
1. Install all other required dependencies on your device as indicated by the list of requirements in [Device requirements](greengrass-nucleus-component.md#greengrass-v2-requirements).
### Set up a Windows device
**Note**
This feature is available for v2.5.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md).
**To set up a Windows device for AWS IoT Greengrass V2**
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend that you use [Amazon Corretto](https://aws.amazon.com/corretto/) or [OpenJDK](https://openjdk.java.net/) long-term support versions. Version 8 or higher is required.
1. Check whether Java is available on the [PATH](https://en.wikipedia.org/wiki/PATH_(variable)) system variable, and add it if not. The LocalSystem account runs the AWS IoT Greengrass Core software, so you must add Java to the PATH system variable instead of the PATH user variable for your user. Do the following:
1. Press the Windows key to open the start menu.
1. Type **environment variables** to search for the system options from the start menu.
1. In the start menu search results, choose **Edit the system environment variables** to open the **System properties** window.
1. Choose **Environment variables...** to open the **Environment Variables** window.
1. Under **System variables**, select **Path**, and then choose **Edit**. In the **Edit environment variable** window, you can view each path on a separate line.
1. Check if the path to the Java installation's `bin` folder is present. The path might look similar to the following example.
```
C:\\Program Files\\Amazon Corretto\\jdk11.0.13_8\\bin
```
1. If the Java installation's `bin` folder is missing from **Path**, choose **New** to add it, and then choose **OK**.
1. Open the Windows Command Prompt (`cmd.exe`) as an administrator.
1. Create the default user in the LocalSystem account on the Windows device. Replace *password* with a secure password.
```
net user /add ggc_user password
```
**Tip**
Depending on your Windows configuration, the user's password might be set to expire at a date in the future. To ensure your Greengrass applications continue to operate, track when the password expires, and update it before it expires. You can also set the user's password to never expire.
To check when a user and its password expire, run the following command.
```
net user ggc_user | findstr /C:expires
```
To set a user's password to never expire, run the following command.
```
wmic UserAccount where "Name='ggc_user'" set PasswordExpires=False
```
If you’re using Windows 10 or later where the [`wmic` command is deprecated](https://learn.microsoft.com/en-us/windows/win32/wmisdk/wmic), run the following PowerShell command.
```
Get-CimInstance -Query "SELECT * from Win32_UserAccount WHERE name = 'ggc_user'" | Set-CimInstance -Property @{PasswordExpires="False"}
```
1. Download and install the [PsExec utility](https://docs.microsoft.com/en-us/sysinternals/downloads/psexec) from Microsoft on the device.
1. Use the PsExec utility to store the user name and password for the default user in the Credential Manager instance for the LocalSystem account. Replace *password* with the user's password that you set earlier.
```
psexec -s cmd /c cmdkey /generic:ggc_user /user:ggc_user /pass:password
```
If the **PsExec License Agreement** opens, choose **Accept** to agree to the license and run the command.
**Note**
On Windows devices, the LocalSystem account runs the Greengrass nucleus, and you must use the PsExec utility to store the default user information in the LocalSystem account. Using the Credential Manager application stores this information in the Windows account of the currently logged on user, instead of the LocalSystem account.
## Provide AWS credentials to the device
Provide your AWS credentials to your device so that the installer can provision the required AWS resources. For more information about the required permissions, see [Minimal IAM policy for installer to provision resources](provision-minimal-iam-policy.md).
**To provide AWS credentials to the device**
+ 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*.
## Download the AWS IoT Greengrass Core software
You can download the latest version of the AWS IoT Greengrass Core software from the following location:
+ [https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip](https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip)
**Note**
You can download a specific version of the AWS IoT Greengrass Core software from the following location. Replace *version* with the version to download.
```
https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-version.zip
```
**To download the AWS IoT Greengrass Core software**
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. (Optional) To verify the Greengrass nucleus software signature
**Note**
This feature is available with Greengrass nucleus version 2.9.5 and later.
1. Use the following command to verify your Greengrass nucleus artifact's signature:
------
#### [ Linux or Unix ]
```
jarsigner -verify -certs -verbose greengrass-nucleus-latest.zip
```
------
#### [ Windows Command Prompt (CMD) ]
The file name might look different depending on the JDK version you install. Replace *`jdk17.0.6_10`* with the JDK version you installed.
```
"C:\\Program Files\\Amazon Corretto\\jdk17.0.6_10\\bin\\jarsigner.exe" -verify -certs -verbose greengrass-nucleus-latest.zip
```
------
#### [ PowerShell ]
The file name might look different depending on the JDK version you install. Replace *`jdk17.0.6_10`* with the JDK version you installed.
```
'C:\\Program Files\\Amazon Corretto\\jdk17.0.6_10\\bin\\jarsigner.exe' -verify -certs -verbose greengrass-nucleus-latest.zip
```
------
1. The `jarsigner` invocation yields output that indicates the results of the verification.
1. If the Greengrass nucleus zip file is signed, the output contains the following statement:
```
jar verified.
```
1. If the Greengrass nucleus zip file isn't signed, the output contains the following statement:
```
jar is unsigned.
```
1. If you provided the Jarsigner `-certs` option along with `-verify` and `-verbose` options, the output also includes detailed signer certificate information.
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. (Optional) Run the following command to see the version of the AWS IoT Greengrass Core software.
```
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
```
**Important**
If you install a version of the Greengrass nucleus earlier than v2.4.0, don't remove this folder after you install the AWS IoT Greengrass Core software. The AWS IoT Greengrass Core software uses the files in this folder to run.
If you downloaded the latest version of the software, you install v2.4.0 or later, and you can remove this folder after you install the AWS IoT Greengrass Core software.
## Install the AWS IoT Greengrass Core software
Run the installer with arguments that specify to do the following:
+ Create the AWS resources that the core device requires to operate.
+ 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.
+ 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.
To set up a development device with local development tools, specify the `--deploy-dev-tools true` argument. The local development tools can take up to a minute to deploy after the installation completes.
For more information about the arguments that you can specify, see [Installer arguments](configure-installer.md).
**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).
**To install the AWS IoT Greengrass Core software**
1. Run the AWS IoT Greengrass Core installer. Replace argument values in your command as follows.
**Note**
Windows has a path length limitation of 260 characters. If you are using Windows, use a root folder like `C:\greengrass\v2` or `D:\greengrass\v2` to keep the Greengrass components paths under the 260 character limit.
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
```
------
#### [ 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
```
------
#### [ 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
```
------
**Important**
On Windows core devices, you must specify `--setup-system-service true` to set up the AWS IoT Greengrass Core software as a system service.
The installer prints the following messages if it succeeds:
+ If you specify `--provision`, the installer prints `Successfully configured Nucleus with provisioned resource details` if it configured the resources successfully.
+ If you specify `--deploy-dev-tools`, the installer prints `Configured Nucleus to deploy aws.greengrass.Cli component` if it created the deployment successfully.
+ If you specify `--setup-system-service true`, the installer prints `Successfully set up Nucleus as a system service` if it set up and ran the software as a service.
+ If you don't specify `--setup-system-service true`, the installer prints `Launched Nucleus successfully` if it succeeded and ran the software.
1. Skip this step if you installed [Greengrass nucleus](greengrass-nucleus-component.md) v2.0.4 or later. If you downloaded the latest version of the software, you installed v2.0.4 or later.
Run the following command to set the required file permissions for your AWS IoT Greengrass Core software root folder. Replace `/greengrass/v2` with the root folder that you specified in your installation command, and replace */greengrass* with the parent folder for your root folder.
```
sudo chmod 755 /greengrass/v2 && sudo chmod 755 /greengrass
```
If you installed the AWS IoT Greengrass Core software as a system service, the installer runs the software for you. Otherwise, you must run the software manually. For more information, see [Run the AWS IoT Greengrass Core software](run-greengrass-core-v2.md).
**Note**
By default, the IAM role that the installer creates doesn't allow access to component artifacts in S3 buckets. To deploy custom components that define artifacts in Amazon S3, you must add permissions to the role to allow your core device to retrieve component artifacts. For more information, see [Allow access to S3 buckets for component artifacts](device-service-role.md#device-service-role-access-s3-bucket).
If you don't yet have an S3 bucket for component artifacts, you can add these permissions later after you create a bucket.
**Note**
When the AWS IoT Greengrass Core software connects to the cloud, your device will be recognized as a Core device.
For more information about how to configure and use the software and AWS IoT Greengrass, see the following:
+ [Configure the AWS IoT Greengrass Core software](configure-greengrass-core-v2.md)
+ [Develop AWS IoT Greengrass components](develop-greengrass-components.md)
+ [Deploy AWS IoT Greengrass components to devices](manage-deployments.md)
+ [Greengrass Command Line Interface](gg-cli.md)
# Install AWS IoT Greengrass Core software with manual resource provisioning
The AWS IoT Greengrass Core software includes an installer that sets up your device as a Greengrass core device. To set up a device manually, you can create the required AWS IoT and IAM resources for the device to use. If you create these resources manually, you don't need to provide AWS credentials to the installer.
When you manually install the AWS IoT Greengrass Core software, you can also configure the device to use a network proxy or connect to AWS on port 443. You might need to specify these configuration options if your device runs behind a firewall or a network proxy, for example. For more information, see [Connect on port 443 or through a network proxy](configure-greengrass-core-v2.md#configure-alpn-network-proxy).
You can also configure the AWS IoT Greengrass Core software to use a hardware security module (HSM) through the [PKCS\$111 interface](https://en.wikipedia.org/wiki/PKCS_11). This feature enables you to securely store private key and certificate files so that they aren't exposed or duplicated in software. You can store private keys and certificates on a hardware module such as an HSM, a Trusted Platform Module (TPM), or another cryptographic element. This feature is available on Linux devices only. For more information about hardware security and requirements to use it, see [Hardware security integration](hardware-security.md).
**Important**
Before you download the AWS IoT Greengrass Core software, check that your core device meets the [requirements](greengrass-nucleus-component.md#greengrass-v2-requirements) to install and run the AWS IoT Greengrass Core software v2.0.
**Topics**
+ [Retrieve AWS IoT endpoints](#retrieve-iot-endpoints)
+ [Create an AWS IoT thing](#create-iot-thing)
+ [Create the thing certificate](#create-thing-certificate)
+ [Configure the thing certificate](#configure-thing-certificate)
+ [Create a token exchange role](#create-token-exchange-role)
+ [Download certificates to the device](#download-thing-certificates)
+ [Set up the device environment](#set-up-device-environment)
+ [Download the AWS IoT Greengrass Core software](#download-greengrass-core-v2)
+ [Install the AWS IoT Greengrass Core software](#run-greengrass-core-v2-installer-manual)
## Retrieve AWS IoT endpoints
Get the AWS IoT endpoints for your AWS account, and save them to use later. Your device uses these endpoints to connect to AWS IoT. Do the following:
1. Get the AWS IoT data endpoint for your AWS account.
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
The response looks similar to the following example, if the request succeeds.
```
{
"endpointAddress": "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
}
```
1. Get the AWS IoT credentials endpoint for your AWS account.
```
aws iot describe-endpoint --endpoint-type iot:CredentialProvider
```
The response looks similar to the following example, if the request succeeds.
```
{
"endpointAddress": "device-credentials-prefix.credentials.iot.us-west-2.amazonaws.com"
}
```
## Create an AWS IoT thing
AWS IoT *things* represent devices and logical entities that connect to AWS IoT. Greengrass core devices are AWS IoT things. When you register a device as an AWS IoT thing, that device can use a digital certificate to authenticate with AWS.
In this section, you create an AWS IoT thing that represents your device.
**To create an AWS IoT thing**
1. Create an AWS IoT thing for your device. On your development computer, run the following command.
+ Replace *MyGreengrassCore* with the thing name to use. This name is also the name of your Greengrass core device.
**Note**
The thing name can't contain colon (`:`) characters.
```
aws iot create-thing --thing-name MyGreengrassCore
```
The response looks similar to the following example, if the request succeeds.
```
{
"thingName": "MyGreengrassCore",
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore",
"thingId": "8cb4b6cd-268e-495d-b5b9-1713d71dbf42"
}
```
1. (Optional) Add the AWS IoT thing to a new or existing thing group. You use thing groups to manage fleets of Greengrass core devices. When you deploy software components to your devices, you can target individual devices or groups of devices. You can add a device to a thing group with an active Greengrass deployment to deploy that thing group's software components to the device. Do the following:
1. (Optional) Create an AWS IoT thing group.
+ Replace *MyGreengrassCoreGroup* with the name of the thing group to create.
**Note**
The thing group name can't contain colon (`:`) characters.
```
aws iot create-thing-group --thing-group-name MyGreengrassCoreGroup
```
The response looks similar to the following example, if the request succeeds.
```
{
"thingGroupName": "MyGreengrassCoreGroup",
"thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/MyGreengrassCoreGroup",
"thingGroupId": "4df721e1-ff9f-4f97-92dd-02db4e3f03aa"
}
```
1. Add the AWS IoT thing to a thing group.
+ Replace *MyGreengrassCore* with the name of your AWS IoT thing.
+ Replace *MyGreengrassCoreGroup* with the name of the thing group.
```
aws iot add-thing-to-thing-group --thing-name MyGreengrassCore --thing-group-name MyGreengrassCoreGroup
```
The command doesn't have any output if the request succeeds.
## Create the thing certificate
When you register a device as an AWS IoT thing, that device can use a digital certificate to authenticate with AWS. This certificate allows the device to communicate with AWS IoT and AWS IoT Greengrass.
In this section, you create and download certificates that your device can use to connect to AWS.
If you want to configure the AWS IoT Greengrass Core software to use a hardware security module (HSM) to securely store the private key and certificate, follow the steps to create the certificate from a private key in an HSM. Otherwise, follow the steps to create the certificate and private key in the AWS IoT service. The hardware security feature is available on Linux devices only. For more information about hardware security and requirements to use it, see [Hardware security integration](hardware-security.md).
### Create the certificate and private key in the AWS IoT service
**To create the thing certificate**
1. Create a folder where you download the certificates for the AWS IoT thing.
```
mkdir greengrass-v2-certs
```
1. Create and download the certificates for the AWS IoT thing.
```
aws iot create-keys-and-certificate --set-as-active --certificate-pem-outfile greengrass-v2-certs/device.pem.crt --public-key-outfile greengrass-v2-certs/public.pem.key --private-key-outfile greengrass-v2-certs/private.pem.key
```
The response looks similar to the following example, if the request succeeds.
```
{
"certificateArn": "arn:aws:iot:us-west-2:123456789012:cert/aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4",
"certificateId": "aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4",
"certificatePem": "-----BEGIN CERTIFICATE-----
MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w
0BAQUFADCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZ
WF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIw
EAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5
jb20wHhcNMTEwNDI1MjA0NTIxWhcNMTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBh
MCVVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBb
WF6b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMx
HzAdBgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wgZ8wDQYJKoZIhvcNAQE
BBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ21uUSfwfEvySWtC2XADZ4nB+BLYgVI
k60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9TrDHudUZg3qX4waLG5M43q7Wgc/MbQ
ITxOUSQv7c7ugFFDzQGBzZswY6786m86gpEIbb3OhjZnzcvQAaRHhdlQWIMm2nr
AgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4nUhVVxYUntneD9+h8Mg9q6q+auN
KyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0FkbFFBjvSfpJIlJ00zbhNYS5f6Guo
EDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTbNYiytVbZPQUQ5Yaxu2jXnimvw
3rrszlaEXAMPLE=
-----END CERTIFICATE-----",
"keyPair": {
"PublicKey": "-----BEGIN PUBLIC KEY-----\
MIIBIjANBgkqhkEXAMPLEQEFAAOCAQ8AMIIBCgKCAQEAEXAMPLE1nnyJwKSMHw4h\
MMEXAMPLEuuN/dMAS3fyce8DW/4+EXAMPLEyjmoF/YVF/gHr99VEEXAMPLE5VF13\
59VK7cEXAMPLE67GK+y+jikqXOgHh/xJTwo+sGpWEXAMPLEDz18xOd2ka4tCzuWEXAMPLEahJbYkCPUBSU8opVkR7qkEXAMPLE1DR6sx2HocliOOLtu6Fkw91swQWEXAMPLE\\GB3ZPrNh0PzQYvjUStZeccyNCx2EXAMPLEvp9mQOUXP6plfgxwKRX2fEXAMPLEDa\
hJLXkX3rHU2xbxJSq7D+XEXAMPLEcw+LyFhI5mgFRl88eGdsAEXAMPLElnI9EesG\
FQIDAQAB\
-----END PUBLIC KEY-----\
",
"PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\
key omitted for security reasons\
-----END RSA PRIVATE KEY-----\
"
}
}
```
Save the certificate's Amazon Resource Name (ARN) to use to configure the certificate later.
### Create the certificate from a private key in an HSM
**Note**
This feature is available for v2.5.3 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md). AWS IoT Greengrass doesn't currently support this feature on Windows core devices.
**To create the thing certificate**
1. On the core device, initialize a PKCS\$111 token in the HSM, and generate a private key. The private key must be an RSA key with an RSA-2048 key size (or larger) or an ECC key.
**Note**
To use a hardware security module with ECC keys, you must use [Greengrass nucleus](greengrass-nucleus-component.md) v2.5.6 or later.
To use a hardware security module and [secret manager](secret-manager-component.md), you must use a hardware security module with RSA keys.
Check the documentation for your HSM to learn how to initialize the token and generate the private key. If your HSM supports object IDs, specify an object ID when you generate the private key. Save the slot ID, user PIN, object label, object ID (if your HSM uses one) that you specify when you initialize the token and generate the private key. You use these values later when you import the thing certificate to the HSM and configure the AWS IoT Greengrass Core software.
1. Create a certificate signing request (CSR) from the private key. AWS IoT uses this CSR to create a thing certificate for the private key that you generated in the HSM. For information about how to create a CSR from the private key, see the documentation for your HSM. The CSR is a file, such as `iotdevicekey.csr`.
1. Copy the CSR from the device to your development computer. If SSH and SCP are enabled on the development computer and the device, you can use the `scp` command on your development computer to transfer the CSR. Replace *device-ip-address* with the IP address of your device, and replace *\$1/iotdevicekey.csr* with the path to the CSR file on the device.
```
scp device-ip-address:~/iotdevicekey.csr iotdevicekey.csr
```
1. On your development computer, create a folder where you download the certificate for the AWS IoT thing.
```
mkdir greengrass-v2-certs
```
1. Use the CSR file to create and download the certificate for the AWS IoT thing to your development computer.
```
aws iot create-certificate-from-csr --set-as-active --certificate-signing-request=file://iotdevicekey.csr --certificate-pem-outfile greengrass-v2-certs/device.pem.crt
```
The response looks similar to the following example, if the request succeeds.
```
{
"certificateArn": "arn:aws:iot:us-west-2:123456789012:cert/aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4",
"certificateId": "aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4",
"certificatePem": "-----BEGIN CERTIFICATE-----
MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w
0BAQUFADCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZ
WF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIw
EAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5
jb20wHhcNMTEwNDI1MjA0NTIxWhcNMTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBh
MCVVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBb
WF6b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMx
HzAdBgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wgZ8wDQYJKoZIhvcNAQE
BBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ21uUSfwfEvySWtC2XADZ4nB+BLYgVI
k60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9TrDHudUZg3qX4waLG5M43q7Wgc/MbQ
ITxOUSQv7c7ugFFDzQGBzZswY6786m86gpEIbb3OhjZnzcvQAaRHhdlQWIMm2nr
AgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4nUhVVxYUntneD9+h8Mg9q6q+auN
KyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0FkbFFBjvSfpJIlJ00zbhNYS5f6Guo
EDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTbNYiytVbZPQUQ5Yaxu2jXnimvw
3rrszlaEXAMPLE=
-----END CERTIFICATE-----"
}
```
Save the certificate's ARN to use to configure the certificate later.
## Configure the thing certificate
Attach the thing certificate to the AWS IoT thing that you created earlier, and add an AWS IoT policy to the certificate to define the AWS IoT permissions for the core device.
**To configure the thing's certificate**
1. Attach the certificate to the AWS IoT thing.
+ Replace *MyGreengrassCore* with the name of your AWS IoT thing.
+ Replace the certificate Amazon Resource Name (ARN) with the ARN of the certificate that you created in the previous step.
```
aws iot attach-thing-principal --thing-name MyGreengrassCore --principal arn:aws:iot:us-west-2:123456789012:cert/aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4
```
The command doesn't have any output if the request succeeds.
1. Create and attach an AWS IoT policy that defines the AWS IoT permissions for your Greengrass core device. The following policy allows access to all MQTT topics and Greengrass operations, so your device works with custom applications and future changes that require new Greengrass operations. You can restrict this policy down based on your 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).
If you have set up a Greengrass core device before, you can attach its AWS IoT policy instead of creating a new one.
Do the following:
1. Create a file that contains the AWS IoT policy document that Greengrass core devices require.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
```
nano greengrass-v2-iot-policy.json
```
Copy the following JSON into the file.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Subscribe",
"iot:Receive",
"iot:Connect",
"greengrass:*"
],
"Resource": [
"*"
]
}
]
}
```
1. Create an AWS IoT policy from the policy document.
+ Replace *GreengrassV2IoTThingPolicy* with the name of the policy to create.
```
aws iot create-policy --policy-name GreengrassV2IoTThingPolicy --policy-document file://greengrass-v2-iot-policy.json
```
The response looks similar to the following example, if the request succeeds.
```
{
"policyName": "GreengrassV2IoTThingPolicy",
"policyArn": "arn:aws:iot:us-west-2:123456789012:policy/GreengrassV2IoTThingPolicy",
"policyDocument": "{
\\"Version\\": \\"2012-10-17 \\",
\\"Statement\\": [
{
\\"Effect\\": \\"Allow\\",
\\"Action\\": [
\\"iot:Publish\\",
\\"iot:Subscribe\\",
\\"iot:Receive\\",
\\"iot:Connect\\",
\\"greengrass:*\\"
],
\\"Resource\\": [
\\"*\\"
]
}
]
}",
"policyVersionId": "1"
}
```
1. Attach the AWS IoT policy to the AWS IoT thing's certificate.
+ Replace *GreengrassV2IoTThingPolicy* with the name of the policy to attach.
+ Replace the target ARN with the ARN of the certificate for your AWS IoT thing.
```
aws iot attach-policy --policy-name GreengrassV2IoTThingPolicy --target arn:aws:iot:us-west-2:123456789012:cert/aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4
```
The command doesn't have any output if the request succeeds.
## Create a token exchange role
Greengrass core devices use an IAM service role, called the *token exchange role*, to authorize calls to AWS services. The device uses the AWS IoT credentials provider to get temporary AWS credentials for this role, which allows the device to interact with AWS IoT, send logs to Amazon CloudWatch Logs, and download custom component artifacts from Amazon S3. For more information, see [Authorize core devices to interact with AWS services](device-service-role.md).
You use an AWS IoT *role alias* to configure the token exchange role for Greengrass core devices. Role aliases enable you to change the token exchange role for a device but keep the device configuration the same. For more information, see [Authorizing direct calls to AWS services](https://docs.aws.amazon.com/iot/latest/developerguide/authorizing-direct-aws.html) in the *AWS IoT Core Developer Guide*.
In this section, you create a token exchange IAM role and an AWS IoT role alias that points to the role. If you have already set up a Greengrass core device, you can use its token exchange role and role alias instead of creating new ones. Then, you configure your device's AWS IoT thing to use that role and alias.
**To create a token exchange IAM role**
1. Create an IAM role that your device can use as a token exchange role. Do the following:
1. Create a file that contains the trust policy document that the token exchange role requires.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
```
nano device-role-trust-policy.json
```
Copy the following JSON into the file.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "credentials.iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
1. Create the token exchange role with the trust policy document.
+ Replace *GreengrassV2TokenExchangeRole* with the name of the IAM role to create.
```
aws iam create-role --role-name GreengrassV2TokenExchangeRole --assume-role-policy-document file://device-role-trust-policy.json
```
The response looks similar to the following example, if the request succeeds.
```
{
"Role": {
"Path": "/",
"RoleName": "GreengrassV2TokenExchangeRole",
"RoleId": "AROAZ2YMUHYHK5OKM77FB",
"Arn": "arn:aws:iam::123456789012:role/GreengrassV2TokenExchangeRole",
"CreateDate": "2021-02-06T00:13:29+00:00",
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "credentials.iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
}
```
1. Create a file that contains the access policy document that the token exchange role requires.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
```
nano device-role-access-policy.json
```
Copy the following JSON into the file.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogStreams",
"s3:GetBucketLocation"
],
"Resource": "*"
}
]
}
```
**Note**
This access policy doesn't allow access to component artifacts in S3 buckets. To deploy custom components that define artifacts in Amazon S3, you must add permissions to the role to allow your core device to retrieve component artifacts. For more information, see [Allow access to S3 buckets for component artifacts](device-service-role.md#device-service-role-access-s3-bucket).
If you don't yet have an S3 bucket for component artifacts, you can add these permissions later after you create a bucket.
1. Create the IAM policy from the policy document.
+ Replace *GreengrassV2TokenExchangeRoleAccess* with the name of the IAM policy to create.
```
aws iam create-policy --policy-name GreengrassV2TokenExchangeRoleAccess --policy-document file://device-role-access-policy.json
```
The response looks similar to the following example, if the request succeeds.
```
{
"Policy": {
"PolicyName": "GreengrassV2TokenExchangeRoleAccess",
"PolicyId": "ANPAZ2YMUHYHACI7C5Z66",
"Arn": "arn:aws:iam::123456789012:policy/GreengrassV2TokenExchangeRoleAccess",
"Path": "/",
"DefaultVersionId": "v1",
"AttachmentCount": 0,
"PermissionsBoundaryUsageCount": 0,
"IsAttachable": true,
"CreateDate": "2021-02-06T00:37:17+00:00",
"UpdateDate": "2021-02-06T00:37:17+00:00"
}
}
```
1. Attach the IAM policy to the token exchange role.
+ Replace *GreengrassV2TokenExchangeRole* with the name of the IAM role.
+ Replace the policy ARN with the ARN of the IAM policy that you created in the previous step.
```
aws iam attach-role-policy --role-name GreengrassV2TokenExchangeRole --policy-arn arn:aws:iam::123456789012:policy/GreengrassV2TokenExchangeRoleAccess
```
The command doesn't have any output if the request succeeds.
1. Create an AWS IoT role alias that points to the token exchange role.
+ Replace *GreengrassCoreTokenExchangeRoleAlias* with the name of the role alias to create.
+ Replace the role ARN with the ARN of the IAM role that you created in the previous step.
```
aws iot create-role-alias --role-alias GreengrassCoreTokenExchangeRoleAlias --role-arn arn:aws:iam::123456789012:role/GreengrassV2TokenExchangeRole
```
The response looks similar to the following example, if the request succeeds.
```
{
"roleAlias": "GreengrassCoreTokenExchangeRoleAlias",
"roleAliasArn": "arn:aws:iot:us-west-2:123456789012:rolealias/GreengrassCoreTokenExchangeRoleAlias"
}
```
**Note**
To create a role alias, you must have permission to pass the token exchange IAM role to AWS IoT. If you receive an error message when you try to create a role alias, check that your AWS user has this permission. For more information, see [Granting a user permissions to pass a role to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html) in the *AWS Identity and Access Management User Guide*.
1. Create and attach an AWS IoT policy that allows your Greengrass core device to use the role alias to assume the token exchange role. If you have set up a Greengrass core device before, you can attach its role alias AWS IoT policy instead of creating a new one. Do the following:
1. (Optional) Create a file that contains the AWS IoT policy document that the role alias requires.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
```
nano greengrass-v2-iot-role-alias-policy.json
```
Copy the following JSON into the file.
+ Replace the resource ARN with the ARN of your role alias.
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:AssumeRoleWithCertificate",
"Resource": "arn:aws:iot:us-west-2:123456789012:rolealias/GreengrassCoreTokenExchangeRoleAlias"
}
]
}
```
1. Create an AWS IoT policy from the policy document.
+ Replace *GreengrassCoreTokenExchangeRoleAliasPolicy* with the name of the AWS IoT policy to create.
```
aws iot create-policy --policy-name GreengrassCoreTokenExchangeRoleAliasPolicy --policy-document file://greengrass-v2-iot-role-alias-policy.json
```
The response looks similar to the following example, if the request succeeds.
```
{
"policyName": "GreengrassCoreTokenExchangeRoleAliasPolicy",
"policyArn": "arn:aws:iot:us-west-2:123456789012:policy/GreengrassCoreTokenExchangeRoleAliasPolicy",
"policyDocument": "{
\\"Version\\":\\"2012-10-17 \\",
\\"Statement\\": [
{
\\"Effect\\": \\"Allow\\",
\\"Action\\": \\"iot:AssumeRoleWithCertificate\\",
\\"Resource\\": \\"arn:aws:iot:us-west-2:123456789012:rolealias/GreengrassCoreTokenExchangeRoleAlias\\"
}
]
}",
"policyVersionId": "1"
}
```
1. Attach the AWS IoT policy to the AWS IoT thing's certificate.
+ Replace *GreengrassCoreTokenExchangeRoleAliasPolicy* with the name of the role alias AWS IoT policy.
+ Replace the target ARN with the ARN of the certificate for your AWS IoT thing.
```
aws iot attach-policy --policy-name GreengrassCoreTokenExchangeRoleAliasPolicy --target arn:aws:iot:us-west-2:123456789012:cert/aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4
```
The command doesn't have any output if the request succeeds.
## Download certificates to the device
Earlier, you downloaded your device's certificate to your development computer. In this section, you copy the certificate to your core device to set up the device with the certificates that it uses to connect to AWS IoT. You also download the Amazon root certificate authority (CA) certificate. If you use an HSM, you also import the certificate file into the HSM in this section.
+ If you created the thing certificate and private key in the AWS IoT service earlier, follow the steps to download the certificates with private key and certificate files.
+ If you created the thing certificate from a private key in a hardware security module (HSM) earlier, follow the steps to download the certificates with the private key and certificate in an HSM.
### Download certificates with private key and certificate files
**To download certificates to the device**
1. Copy the AWS IoT thing certificate from your development computer to the device. If SSH and SCP are enabled on the development computer and the device, you can use the `scp` command on your development computer to transfer the certificate. Replace *device-ip-address* with the IP address of your device.
```
scp -r greengrass-v2-certs/ device-ip-address:~
```
1. Create the Greengrass root folder on the device. You'll later install the AWS IoT Greengrass Core software to this folder.
**Note**
Windows has a path length limitation of 260 characters. If you are using Windows, use a root folder like `C:\greengrass\v2` or `D:\greengrass\v2` to keep the Greengrass components paths under the 260 character limit.
------
#### [ Linux or Unix ]
+ Replace `/greengrass/v2` with the folder to use.
```
sudo mkdir -p /greengrass/v2
```
------
#### [ Windows Command Prompt ]
+ Replace *C:\$1greengrass\$1v2* with the folder to use.
```
mkdir C:\greengrass\v2
```
------
#### [ PowerShell ]
+ Replace *C:\$1greengrass\$1v2* with the folder to use.
```
mkdir C:\greengrass\v2
```
------
1. (Linux only) Set the permissions of the parent of the Greengrass root folder.
+ Replace */greengrass* with the parent of the root folder.
```
sudo chmod 755 /greengrass
```
1. Copy the AWS IoT thing certificates to the Greengrass root folder.
------
#### [ Linux or Unix ]
+ Replace `/greengrass/v2` with the Greengrass root folder.
```
sudo cp -R ~/greengrass-v2-certs/* /greengrass/v2
```
------
#### [ Windows Command Prompt ]
+ Replace *C:\$1greengrass\$1v2* with the folder to use.
```
robocopy %USERPROFILE%\greengrass-v2-certs C:\greengrass\v2 /E
```
------
#### [ PowerShell ]
+ Replace *C:\$1greengrass\$1v2* with the folder to use.
```
cp -Path ~\greengrass-v2-certs\* -Destination C:\greengrass\v2
```
------
1. Download the Amazon root certificate authority (CA) certificate. AWS IoT certificates are associated with Amazon's root CA certificate by default.
------
#### [ Linux or Unix ]
```
sudo curl -o /greengrass/v2/AmazonRootCA1.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem
```
------
#### [ Windows Command Prompt (CMD) ]
```
curl -o C:\greengrass\v2\\AmazonRootCA1.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem
```
------
#### [ PowerShell ]
```
iwr -Uri https://www.amazontrust.com/repository/AmazonRootCA1.pem -OutFile C:\greengrass\v2\\AmazonRootCA1.pem
```
------
### Download certificates with the private key and certificate in an HSM
**Note**
This feature is available for v2.5.3 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md). AWS IoT Greengrass doesn't currently support this feature on Windows core devices.
**To download certificates to the device**
1. Copy the AWS IoT thing certificate from your development computer to the device. If SSH and SCP are enabled on the development computer and the device, you can use the `scp` command on your development computer to transfer the certificate. Replace *device-ip-address* with the IP address of your device.
```
scp -r greengrass-v2-certs/ device-ip-address:~
```
1. Create the Greengrass root folder on the device. You'll later install the AWS IoT Greengrass Core software to this folder.
**Note**
Windows has a path length limitation of 260 characters. If you are using Windows, use a root folder like `C:\greengrass\v2` or `D:\greengrass\v2` to keep the Greengrass components paths under the 260 character limit.
------
#### [ Linux or Unix ]
+ Replace `/greengrass/v2` with the folder to use.
```
sudo mkdir -p /greengrass/v2
```
------
#### [ Windows Command Prompt ]
+ Replace *C:\$1greengrass\$1v2* with the folder to use.
```
mkdir C:\greengrass\v2
```
------
#### [ PowerShell ]
+ Replace *C:\$1greengrass\$1v2* with the folder to use.
```
mkdir C:\greengrass\v2
```
------
1. (Linux only) Set the permissions of the parent of the Greengrass root folder.
+ Replace */greengrass* with the parent of the root folder.
```
sudo chmod 755 /greengrass
```
1. Import the thing certificate file, `~/greengrass-v2-certs/device.pem.crt`, into the HSM. Check the documentation for your HSM to learn how to import certificates into it. Import the certificate using the same token, slot ID, user PIN, object label, and object ID (if your HSM uses one) where you generated the private key in the HSM earlier.
**Note**
If you generated the private key earlier without an object ID, and the certificate has an object ID, set the private key's object ID to the same value as the certificate. Check the documentation for your HSM to learn how to set the object ID for the private key object.
1. (Optional) Delete the thing certificate file, so that it exists only in the HSM.
```
rm ~/greengrass-v2-certs/device.pem.crt
```
1. Download the Amazon root certificate authority (CA) certificate. AWS IoT certificates are associated with Amazon's root CA certificate by default.
------
#### [ Linux or Unix ]
```
sudo curl -o /greengrass/v2/AmazonRootCA1.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem
```
------
#### [ Windows Command Prompt (CMD) ]
```
curl -o C:\greengrass\v2\\AmazonRootCA1.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem
```
------
#### [ PowerShell ]
```
iwr -Uri https://www.amazontrust.com/repository/AmazonRootCA1.pem -OutFile C:\greengrass\v2\\AmazonRootCA1.pem
```
------
## Set up the device environment
Follow the steps in this section to set up a Linux or Windows device to use as your AWS IoT Greengrass core device.
### Set up a Linux device
**To set up a Linux device for AWS IoT Greengrass V2**
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend that you use [Amazon Corretto](https://aws.amazon.com/corretto/) or [OpenJDK](https://openjdk.java.net/) long-term support versions. Version 8 or higher is required. The following commands show you how to install OpenJDK on your device.
+ For Debian-based or Ubuntu-based distributions:
```
sudo apt install default-jdk
```
+ For Red Hat-based distributions:
```
sudo yum install java-11-openjdk-devel
```
+ For Amazon Linux 2:
```
sudo amazon-linux-extras install java-openjdk11
```
+ For Amazon Linux 2023:
```
sudo dnf install java-11-amazon-corretto -y
```
When the installation completes, run the following command to verify that Java runs on your Linux device.
```
java -version
```
The command prints the version of Java that runs on the device. For example, on a Debian-based distribution, the output might look similar to the following sample.
```
openjdk version "11.0.9.1" 2020-11-04
OpenJDK Runtime Environment (build 11.0.9.1+1-post-Debian-1deb10u2)
OpenJDK 64-Bit Server VM (build 11.0.9.1+1-post-Debian-1deb10u2, mixed mode)
```
1. (Optional) Create the default system user and group that runs components on the device. You can also choose to let the AWS IoT Greengrass Core software installer create this user and group during installation with the `--component-default-user` installer argument. For more information, see [Installer arguments](configure-installer.md).
```
sudo useradd --system --create-home ggc_user
sudo groupadd --system ggc_group
```
1. Verify that the user that runs the AWS IoT Greengrass Core software (typically `root`), has permission to run `sudo` with any user and any group.
1. Run the following command to open the `/etc/sudoers` file.
```
sudo visudo
```
1. Verify that the permission for the user looks like the following example.
```
root ALL=(ALL:ALL) ALL
```
1. (Optional) To [run containerized Lambda functions](run-lambda-functions.md), you must enable [cgroups](https://en.wikipedia.org/wiki/Cgroups) v1, and you must enable and mount the *memory* and *devices* cgroups. If you don't plan to run containerized Lambda functions, you can skip this step.
To enable these cgroups options, boot the device with the following Linux kernel parameters.
```
cgroup_enable=memory cgroup_memory=1 systemd.unified_cgroup_hierarchy=0
```
For information about viewing and setting kernel parameters for your device, see the documentation for your operating system and boot loader. Follow the instructions to permanently set the kernel parameters.
1. Install all other required dependencies on your device as indicated by the list of requirements in [Device requirements](greengrass-nucleus-component.md#greengrass-v2-requirements).
### Set up a Windows device
**Note**
This feature is available for v2.5.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md).
**To set up a Windows device for AWS IoT Greengrass V2**
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend that you use [Amazon Corretto](https://aws.amazon.com/corretto/) or [OpenJDK](https://openjdk.java.net/) long-term support versions. Version 8 or higher is required.
1. Check whether Java is available on the [PATH](https://en.wikipedia.org/wiki/PATH_(variable)) system variable, and add it if not. The LocalSystem account runs the AWS IoT Greengrass Core software, so you must add Java to the PATH system variable instead of the PATH user variable for your user. Do the following:
1. Press the Windows key to open the start menu.
1. Type **environment variables** to search for the system options from the start menu.
1. In the start menu search results, choose **Edit the system environment variables** to open the **System properties** window.
1. Choose **Environment variables...** to open the **Environment Variables** window.
1. Under **System variables**, select **Path**, and then choose **Edit**. In the **Edit environment variable** window, you can view each path on a separate line.
1. Check if the path to the Java installation's `bin` folder is present. The path might look similar to the following example.
```
C:\\Program Files\\Amazon Corretto\\jdk11.0.13_8\\bin
```
1. If the Java installation's `bin` folder is missing from **Path**, choose **New** to add it, and then choose **OK**.
1. Open the Windows Command Prompt (`cmd.exe`) as an administrator.
1. Create the default user in the LocalSystem account on the Windows device. Replace *password* with a secure password.
```
net user /add ggc_user password
```
**Tip**
Depending on your Windows configuration, the user's password might be set to expire at a date in the future. To ensure your Greengrass applications continue to operate, track when the password expires, and update it before it expires. You can also set the user's password to never expire.
To check when a user and its password expire, run the following command.
```
net user ggc_user | findstr /C:expires
```
To set a user's password to never expire, run the following command.
```
wmic UserAccount where "Name='ggc_user'" set PasswordExpires=False
```
If you’re using Windows 10 or later where the [`wmic` command is deprecated](https://learn.microsoft.com/en-us/windows/win32/wmisdk/wmic), run the following PowerShell command.
```
Get-CimInstance -Query "SELECT * from Win32_UserAccount WHERE name = 'ggc_user'" | Set-CimInstance -Property @{PasswordExpires="False"}
```
1. Download and install the [PsExec utility](https://docs.microsoft.com/en-us/sysinternals/downloads/psexec) from Microsoft on the device.
1. Use the PsExec utility to store the user name and password for the default user in the Credential Manager instance for the LocalSystem account. Replace *password* with the user's password that you set earlier.
```
psexec -s cmd /c cmdkey /generic:ggc_user /user:ggc_user /pass:password
```
If the **PsExec License Agreement** opens, choose **Accept** to agree to the license and run the command.
**Note**
On Windows devices, the LocalSystem account runs the Greengrass nucleus, and you must use the PsExec utility to store the default user information in the LocalSystem account. Using the Credential Manager application stores this information in the Windows account of the currently logged on user, instead of the LocalSystem account.
## Download the AWS IoT Greengrass Core software
You can download the latest version of the AWS IoT Greengrass Core software from the following location:
+ [https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip](https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip)
**Note**
You can download a specific version of the AWS IoT Greengrass Core software from the following location. Replace *version* with the version to download.
```
https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-version.zip
```
**To download the AWS IoT Greengrass Core software**
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. (Optional) To verify the Greengrass nucleus software signature
**Note**
This feature is available with Greengrass nucleus version 2.9.5 and later.
1. Use the following command to verify your Greengrass nucleus artifact's signature:
------
#### [ Linux or Unix ]
```
jarsigner -verify -certs -verbose greengrass-nucleus-latest.zip
```
------
#### [ Windows Command Prompt (CMD) ]
The file name might look different depending on the JDK version you install. Replace *`jdk17.0.6_10`* with the JDK version you installed.
```
"C:\\Program Files\\Amazon Corretto\\jdk17.0.6_10\\bin\\jarsigner.exe" -verify -certs -verbose greengrass-nucleus-latest.zip
```
------
#### [ PowerShell ]
The file name might look different depending on the JDK version you install. Replace *`jdk17.0.6_10`* with the JDK version you installed.
```
'C:\\Program Files\\Amazon Corretto\\jdk17.0.6_10\\bin\\jarsigner.exe' -verify -certs -verbose greengrass-nucleus-latest.zip
```
------
1. The `jarsigner` invocation yields output that indicates the results of the verification.
1. If the Greengrass nucleus zip file is signed, the output contains the following statement:
```
jar verified.
```
1. If the Greengrass nucleus zip file isn't signed, the output contains the following statement:
```
jar is unsigned.
```
1. If you provided the Jarsigner `-certs` option along with `-verify` and `-verbose` options, the output also includes detailed signer certificate information.
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. (Optional) Run the following command to see the version of the AWS IoT Greengrass Core software.
```
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
```
**Important**
If you install a version of the Greengrass nucleus earlier than v2.4.0, don't remove this folder after you install the AWS IoT Greengrass Core software. The AWS IoT Greengrass Core software uses the files in this folder to run.
If you downloaded the latest version of the software, you install v2.4.0 or later, and you can remove this folder after you install the AWS IoT Greengrass Core software.
## Install the AWS IoT Greengrass Core software
Run the installer with arguments that specify the following actions:
+ Install from a partial configuration file that specifies to use the AWS resources and certificates that you created earlier. The AWS IoT Greengrass Core software uses a configuration file that specifies the configuration of every Greengrass component on the device. The installer creates a complete configuration file from the partial configuration file that you provide.
+ 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.
+ 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.
For more information about the arguments that you can specify, see [Installer arguments](configure-installer.md).
**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).
+ If you created the thing certificate and private key in the AWS IoT service earlier, follow the steps to install the AWS IoT Greengrass Core software with private key and certificate files.
+ If you created the thing certificate from a private key in a hardware security module (HSM) earlier, follow the steps to install the AWS IoT Greengrass Core software with the private key and certificate in an HSM.
### Install the AWS IoT Greengrass Core software with private key and certificate files
**To install the AWS IoT Greengrass Core software**
1. Check the version of the AWS IoT Greengrass Core software.
+ Replace *GreengrassInstaller* with the path to the folder that contains the software.
```
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
```
1. Use a text editor to create a configuration file named `config.yaml` to provide to the installer.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
```
nano GreengrassInstaller/config.yaml
```
Copy the following YAML content into the file. This partial configuration file specifies system parameters and Greengrass nucleus parameters.
```
---
system:
certificateFilePath: "/greengrass/v2/device.pem.crt"
privateKeyPath: "/greengrass/v2/private.pem.key"
rootCaPath: "/greengrass/v2/AmazonRootCA1.pem"
rootpath: "/greengrass/v2"
thingName: "MyGreengrassCore"
services:
aws.greengrass.Nucleus:
componentType: "NUCLEUS"
version: "2.17.0"
configuration:
awsRegion: "us-west-2"
iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
iotDataEndpoint: "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
iotCredEndpoint: "device-credentials-prefix.credentials.iot.us-west-2.amazonaws.com"
```
Then, do the following:
+ Replace each instance of `/greengrass/v2` with the Greengrass root folder.
+ Replace *MyGreengrassCore* with the name of the AWS IoT thing.
+ Replace *2.17.0* with the version of the AWS IoT Greengrass Core software.
+ Replace *us-west-2* with the AWS Region where you created the resources.
+ Replace *GreengrassCoreTokenExchangeRoleAlias* with the name of the token exchange role alias.
+ Replace the `iotDataEndpoint` with your AWS IoT data endpoint.
+ Replace the `iotCredEndpoint` with your AWS IoT credentials endpoint.
**Note**
In this configuration file, you can customize other nucleus configuration options such as the ports and network proxy to use, as shown in the following example. For more information, see [Greengrass nucleus configuration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration).
```
---
system:
certificateFilePath: "/greengrass/v2/device.pem.crt"
privateKeyPath: "/greengrass/v2/private.pem.key"
rootCaPath: "/greengrass/v2/AmazonRootCA1.pem"
rootpath: "/greengrass/v2"
thingName: "MyGreengrassCore"
services:
aws.greengrass.Nucleus:
componentType: "NUCLEUS"
version: "2.17.0"
configuration:
awsRegion: "us-west-2"
iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
iotCredEndpoint: "device-credentials-prefix.credentials.iot.us-west-2.amazonaws.com"
iotDataEndpoint: "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
mqtt:
port: 443
greengrassDataPlanePort: 443
networkProxy:
noProxyAddresses: "http://192.168.0.1,www.example.com"
proxy:
url: "https://my-proxy-server:1100"
username: "Mary_Major"
password: "pass@word1357"
```
1. Run the installer, and specify `--init-config` to provide the configuration file.
+ Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the Greengrass root folder.
+ Replace each instance of *GreengrassInstaller* with the folder where you unpacked the installer.
------
#### [ Linux or Unix ]
```
sudo -E java -Droot="/greengrass/v2" -Dlog.store=FILE \
-jar ./GreengrassInstaller/lib/Greengrass.jar \
--init-config ./GreengrassInstaller/config.yaml \
--component-default-user ggc_user:ggc_group \
--setup-system-service true
```
------
#### [ Windows Command Prompt (CMD) ]
```
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" ^
-jar ./GreengrassInstaller/lib/Greengrass.jar ^
--init-config ./GreengrassInstaller/config.yaml ^
--component-default-user ggc_user ^
--setup-system-service true
```
------
#### [ PowerShell ]
```
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" `
-jar ./GreengrassInstaller/lib/Greengrass.jar `
--init-config ./GreengrassInstaller/config.yaml `
--component-default-user ggc_user `
--setup-system-service true
```
------
**Important**
On Windows core devices, you must specify `--setup-system-service true` to set up the AWS IoT Greengrass Core software as a system service.
If you specify `--setup-system-service true`, the installer prints `Successfully set up Nucleus as a system service` if it set up and ran the software as a system service. Otherwise, the installer doesn't output any message if it installs the software successfully.
**Note**
You can't use the `deploy-dev-tools` argument to deploy local development tools when you run the installer without the `--provision true` argument. For information about deploying the Greengrass CLI directly on your device, see [Greengrass Command Line Interface](gg-cli.md).
1. Verify the installation by viewing the files in the root folder.
------
#### [ Linux or Unix ]
```
ls /greengrass/v2
```
------
#### [ Windows Command Prompt (CMD) ]
```
dir C:\greengrass\v2
```
------
#### [ PowerShell ]
```
ls C:\greengrass\v2
```
------
If the installation succeeded, the root folder contains several folders, such as `config`, `packages`, and `logs`.
### Install the AWS IoT Greengrass Core software with the private key and certificate in an HSM
**Note**
This feature is available for v2.5.3 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md). AWS IoT Greengrass doesn't currently support this feature on Windows core devices.
**To install the AWS IoT Greengrass Core software**
1. Check the version of the AWS IoT Greengrass Core software.
+ Replace *GreengrassInstaller* with the path to the folder that contains the software.
```
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
```
1. To enable the AWS IoT Greengrass Core software to use the private key and certificate in the HSM, install the [PKCS\$111 provider component](pkcs11-provider-component.md) when you install the AWS IoT Greengrass Core software. The PKCS\$111 provider component is a plugin that you can configure during installation. You can download the latest version of the PKCS\$111 provider component from the following location:
+ [https://d2s8p88vqu9w66.cloudfront.net/releases/Pkcs11Provider/aws.greengrass.crypto.Pkcs11Provider-latest.jar](https://d2s8p88vqu9w66.cloudfront.net/releases/Pkcs11Provider/aws.greengrass.crypto.Pkcs11Provider-latest.jar)
Download the PKCS\$111 provider plugin to a file named `aws.greengrass.crypto.Pkcs11Provider.jar`. Replace *GreengrassInstaller* with the folder that you want to use.
```
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/Pkcs11Provider/aws.greengrass.crypto.Pkcs11Provider-latest.jar > GreengrassInstaller/aws.greengrass.crypto.Pkcs11Provider.jar
```
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. Use a text editor to create a configuration file named `config.yaml` to provide to the installer.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
```
nano GreengrassInstaller/config.yaml
```
Copy the following YAML content into the file. This partial configuration file specifies system parameters, Greengrass nucleus parameters, and PKCS\$111 provider parameters.
```
---
system:
certificateFilePath: "pkcs11:object=iotdevicekey;type=cert"
privateKeyPath: "pkcs11:object=iotdevicekey;type=private"
rootCaPath: "/greengrass/v2/AmazonRootCA1.pem"
rootpath: "/greengrass/v2"
thingName: "MyGreengrassCore"
services:
aws.greengrass.Nucleus:
componentType: "NUCLEUS"
version: "2.17.0"
configuration:
awsRegion: "us-west-2"
iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
iotDataEndpoint: "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
iotCredEndpoint: "device-credentials-prefix.credentials.iot.us-west-2.amazonaws.com"
aws.greengrass.crypto.Pkcs11Provider:
configuration:
name: "softhsm_pkcs11"
library: "/usr/local/Cellar/softhsm/2.6.1/lib/softhsm/libsofthsm2.so"
slot: 1
userPin: "1234"
```
Then, do the following:
+ Replace each instance of *iotdevicekey* in the PKCS\$111 URIs with the object label where you created the private key and imported the certificate.
+ Replace each instance of `/greengrass/v2` with the Greengrass root folder.
+ Replace *MyGreengrassCore* with the name of the AWS IoT thing.
+ Replace *2.17.0* with the version of the AWS IoT Greengrass Core software.
+ Replace *us-west-2* with the AWS Region where you created the resources.
+ Replace *GreengrassCoreTokenExchangeRoleAlias* with the name of the token exchange role alias.
+ Replace the `iotDataEndpoint` with your AWS IoT data endpoint.
+ Replace the `iotCredEndpoint` with your AWS IoT credentials endpoint.
+ Replace the configuration parameters for the `aws.greengrass.crypto.Pkcs11Provider` component with the values for the HSM configuration on the core device.
**Note**
In this configuration file, you can customize other nucleus configuration options such as the ports and network proxy to use, as shown in the following example. For more information, see [Greengrass nucleus configuration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration).
```
---
system:
certificateFilePath: "pkcs11:object=iotdevicekey;type=cert"
privateKeyPath: "pkcs11:object=iotdevicekey;type=private"
rootCaPath: "/greengrass/v2/AmazonRootCA1.pem"
rootpath: "/greengrass/v2"
thingName: "MyGreengrassCore"
services:
aws.greengrass.Nucleus:
componentType: "NUCLEUS"
version: "2.17.0"
configuration:
awsRegion: "us-west-2"
iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
iotDataEndpoint: "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
iotCredEndpoint: "device-credentials-prefix.credentials.iot.us-west-2.amazonaws.com"
mqtt:
port: 443
greengrassDataPlanePort: 443
networkProxy:
noProxyAddresses: "http://192.168.0.1,www.example.com"
proxy:
url: "https://my-proxy-server:1100"
username: "Mary_Major"
password: "pass@word1357"
aws.greengrass.crypto.Pkcs11Provider:
configuration:
name: "softhsm_pkcs11"
library: "/usr/local/Cellar/softhsm/2.6.1/lib/softhsm/libsofthsm2.so"
slot: 1
userPin: "1234"
```
1. Run the installer, and specify `--init-config` to provide the configuration file.
+ Replace `/greengrass/v2` with the Greengrass root folder.
+ Replace each instance of *GreengrassInstaller* with the folder where you unpacked the installer.
```
sudo -E java -Droot="/greengrass/v2" -Dlog.store=FILE \
-jar ./GreengrassInstaller/lib/Greengrass.jar \
--trusted-plugin ./GreengrassInstaller/aws.greengrass.crypto.Pkcs11Provider.jar \
--init-config ./GreengrassInstaller/config.yaml \
--component-default-user ggc_user:ggc_group \
--setup-system-service true
```
**Important**
On Windows core devices, you must specify `--setup-system-service true` to set up the AWS IoT Greengrass Core software as a system service.
If you specify `--setup-system-service true`, the installer prints `Successfully set up Nucleus as a system service` if it set up and ran the software as a system service. Otherwise, the installer doesn't output any message if it installs the software successfully.
**Note**
You can't use the `deploy-dev-tools` argument to deploy local development tools when you run the installer without the `--provision true` argument. For information about deploying the Greengrass CLI directly on your device, see [Greengrass Command Line Interface](gg-cli.md).
1. Verify the installation by viewing the files in the root folder.
------
#### [ Linux or Unix ]
```
ls /greengrass/v2
```
------
#### [ Windows Command Prompt (CMD) ]
```
dir C:\greengrass\v2
```
------
#### [ PowerShell ]
```
ls C:\greengrass\v2
```
------
If the installation succeeded, the root folder contains several folders, such as `config`, `packages`, and `logs`.
If you installed the AWS IoT Greengrass Core software as a system service, the installer runs the software for you. Otherwise, you must run the software manually. For more information, see [Run the AWS IoT Greengrass Core software](run-greengrass-core-v2.md).
**Note**
When the AWS IoT Greengrass Core software connects to the cloud, your device will be recognized as a Core device.
For more information about how to configure and use the software and AWS IoT Greengrass, see the following:
+ [Configure the AWS IoT Greengrass Core software](configure-greengrass-core-v2.md)
+ [Develop AWS IoT Greengrass components](develop-greengrass-components.md)
+ [Deploy AWS IoT Greengrass components to devices](manage-deployments.md)
+ [Greengrass Command Line Interface](gg-cli.md)
# Install AWS IoT Greengrass Core software with AWS IoT fleet provisioning
This feature is available for v2.4.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md).
With AWS IoT fleet provisioning, you can configure AWS IoT to generate and securely deliver X.509 device certificates and private keys to your devices when they connect to AWS IoT for the first time. AWS IoT provides client certificates that are signed by the Amazon Root certificate authority (CA). You can also configure AWS IoT to specify thing groups, thing types, and permissions for Greengrass core devices that you provision with fleet provisioning. You define a *provisioning template* to define how AWS IoT provisions each device. The provisioning template specifies the thing, policy, and certificate resources to create for a device when provisioning. For more information, see [Provisioning templates](https://docs.aws.amazon.com/iot/latest/developerguide/provision-template.html) in the *AWS IoT Core Developer Guide*.
AWS IoT Greengrass provides an AWS IoT fleet provisioning plugin that you can use to install the AWS IoT Greengrass Core software using AWS resources created by AWS IoT fleet provisioning. The fleet provisioning plugin uses *provisioning by claim*. Devices use a provisioning claim certificate and private key to obtain a unique X.509 device certificate and private key that they can use for regular operations. You can embed the claim certificate and private key in each device during manufacturing, so your customers can activate devices later when each device comes online. You can use the same claim certificate and private key for multiple devices. For more information, see [Provisioning by claim](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html#claim-based) in the *AWS IoT Core Developer Guide*.
**Note**
The fleet provisioning plugin for [Greengrass nucleus](greengrass-nucleus-component.md) doesn't currently support storing private key and certificate files in a hardware security module (HSM). To use an HSM with [Greengrass nucleus](greengrass-nucleus-component.md), [install the AWS IoT Greengrass Core software with manual provisioning](manual-installation.md). [Greengrass nucleus lite](greengrass-nucleus-lite-component.md) v2.5.0 and later support TPM with fleet provisioning natively.
To install the AWS IoT Greengrass Core software with AWS IoT fleet provisioning, you must set up resources in your AWS account that AWS IoT uses to provision Greengrass core devices. These resources include a provisioning template, claim certificates, and a [token exchange IAM role](device-service-role.md). After you create these resources, you can reuse them to provision multiple core devices in a fleet. For more information, see [Set up AWS IoT fleet provisioning for Greengrass core devices](fleet-provisioning-setup.md).
**Important**
Before you download the AWS IoT Greengrass Core software, check that your core device meets the [requirements](greengrass-nucleus-component.md#greengrass-v2-requirements) to install and run the AWS IoT Greengrass Core software v2.0.
**Topics**
+ [Prerequisites](#fleet-provisioning-prerequisites)
+ [Retrieve AWS IoT endpoints](#retrieve-iot-endpoints)
+ [Download certificates to the device](#download-claim-certificates)
+ [Set up the device environment](#set-up-device-environment)
+ [Download the AWS IoT Greengrass Core software](#download-greengrass-core-v2)
+ [Download the AWS IoT fleet provisioning plugin](#download-fleet-provisioning-plugin)
+ [Install the AWS IoT Greengrass Core software](#run-greengrass-core-v2-installer-fleet)
+ [Set up AWS IoT fleet provisioning for Greengrass core devices](fleet-provisioning-setup.md)
+ [Configure the AWS IoT fleet provisioning plugin](fleet-provisioning-configuration.md)
+ [AWS IoT fleet provisioning plugin changelog](fleet-provisioning-changelog.md)
## Prerequisites
To install the AWS IoT Greengrass Core software with AWS IoT fleet provisioning, you must first [set up AWS IoT fleet provisioning for Greengrass core devices](fleet-provisioning-setup.md). After you complete these steps once, you can use fleet provisioning to install the AWS IoT Greengrass Core software on any number of devices.
## Retrieve AWS IoT endpoints
Get the AWS IoT endpoints for your AWS account, and save them to use later. Your device uses these endpoints to connect to AWS IoT. Do the following:
1. Get the AWS IoT data endpoint for your AWS account.
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
The response looks similar to the following example, if the request succeeds.
```
{
"endpointAddress": "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
}
```
1. Get the AWS IoT credentials endpoint for your AWS account.
```
aws iot describe-endpoint --endpoint-type iot:CredentialProvider
```
The response looks similar to the following example, if the request succeeds.
```
{
"endpointAddress": "device-credentials-prefix.credentials.iot.us-west-2.amazonaws.com"
}
```
## Download certificates to the device
The device uses a claim certificate and private key to authenticate its request to provision AWS resources and acquire an X.509 device certificate. You can embed the claim certificate and private key into the device during manufacturing, or copy the certificate and key to the device during installation. In this section, you copy the claim certificate and private key to the device. You also download the Amazon Root certificate authority (CA) certificate to the device.
**Important**
Provisioning claim private keys should be secured at all times, including on Greengrass core devices. We recommend that you use Amazon CloudWatch metrics and logs to monitor for indications of misuse, such as unauthorized use of the claim certificate to provision devices. If you detect misuse, disable the provisioning claim certificate so that it can't be used for device provisioning. For more information, see [Monitoring AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/monitoring_overview.html) in the *AWS IoT Core Developer Guide*.
To help you better manage the number of devices, and which devices, that register themselves in your AWS account, you can specify a pre-provisioning hook when you create a fleet provisioning template. A pre-provisioning hook is an AWS Lambda function that validates template parameters that devices provide during registration. For example, you might create a pre-provisioning hook that checks a device ID against a database to verify that the device has permission to provision. For more information, see [Pre-provisioning hooks](https://docs.aws.amazon.com/iot/latest/developerguide/pre-provisioning-hook.html) in the *AWS IoT Core Developer Guide*.
**To download claim certificates to the device**
1. Copy the claim certificate and private key to the device. If SSH and SCP are enabled on the development computer and the device, you can use the `scp` command on your development computer to transfer the claim certificate and private key. The following example command transfers these files a folder named `claim-certs` on your development computer to the device. Replace *device-ip-address* with the IP address of your device.
```
scp -r claim-certs/ device-ip-address:~
```
1. Create the Greengrass root folder on the device. You'll later install the AWS IoT Greengrass Core software to this folder.
**Note**
Windows has a path length limitation of 260 characters. If you are using Windows, use a root folder like `C:\greengrass\v2` or `D:\greengrass\v2` to keep the Greengrass components paths under the 260 character limit.
------
#### [ Linux or Unix ]
+ Replace `/greengrass/v2` with the folder to use.
```
sudo mkdir -p /greengrass/v2
```
------
#### [ Windows Command Prompt ]
+ Replace *C:\$1greengrass\$1v2* with the folder to use.
```
mkdir C:\greengrass\v2
```
------
#### [ PowerShell ]
+ Replace *C:\$1greengrass\$1v2* with the folder to use.
```
mkdir C:\greengrass\v2
```
------
1. (Linux only) Set the permissions of the parent of the Greengrass root folder.
+ Replace */greengrass* with the parent of the root folder.
```
sudo chmod 755 /greengrass
```
1. Move the claim certificates to the Greengrass root folder.
+ Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the Greengrass root folder.
------
#### [ Linux or Unix ]
```
sudo mv ~/claim-certs /greengrass/v2
```
------
#### [ Windows Command Prompt (CMD) ]
```
move %USERPROFILE%\claim-certs C:\greengrass\v2
```
------
#### [ PowerShell ]
```
mv -Path ~\claim-certs -Destination C:\greengrass\v2
```
------
1. Download the Amazon root certificate authority (CA) certificate. AWS IoT certificates are associated with Amazon's root CA certificate by default.
------
#### [ Linux or Unix ]
```
sudo curl -o /greengrass/v2/AmazonRootCA1.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem
```
------
#### [ Windows Command Prompt (CMD) ]
```
curl -o C:\greengrass\v2\\AmazonRootCA1.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem
```
------
#### [ PowerShell ]
```
iwr -Uri https://www.amazontrust.com/repository/AmazonRootCA1.pem -OutFile C:\greengrass\v2\\AmazonRootCA1.pem
```
------
## Set up the device environment
Follow the steps in this section to set up a Linux or Windows device to use as your AWS IoT Greengrass core device.
### Set up a Linux device
**To set up a Linux device for AWS IoT Greengrass V2**
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend that you use [Amazon Corretto](https://aws.amazon.com/corretto/) or [OpenJDK](https://openjdk.java.net/) long-term support versions. Version 8 or higher is required. The following commands show you how to install OpenJDK on your device.
+ For Debian-based or Ubuntu-based distributions:
```
sudo apt install default-jdk
```
+ For Red Hat-based distributions:
```
sudo yum install java-11-openjdk-devel
```
+ For Amazon Linux 2:
```
sudo amazon-linux-extras install java-openjdk11
```
+ For Amazon Linux 2023:
```
sudo dnf install java-11-amazon-corretto -y
```
When the installation completes, run the following command to verify that Java runs on your Linux device.
```
java -version
```
The command prints the version of Java that runs on the device. For example, on a Debian-based distribution, the output might look similar to the following sample.
```
openjdk version "11.0.9.1" 2020-11-04
OpenJDK Runtime Environment (build 11.0.9.1+1-post-Debian-1deb10u2)
OpenJDK 64-Bit Server VM (build 11.0.9.1+1-post-Debian-1deb10u2, mixed mode)
```
1. (Optional) Create the default system user and group that runs components on the device. You can also choose to let the AWS IoT Greengrass Core software installer create this user and group during installation with the `--component-default-user` installer argument. For more information, see [Installer arguments](configure-installer.md).
```
sudo useradd --system --create-home ggc_user
sudo groupadd --system ggc_group
```
1. Verify that the user that runs the AWS IoT Greengrass Core software (typically `root`), has permission to run `sudo` with any user and any group.
1. Run the following command to open the `/etc/sudoers` file.
```
sudo visudo
```
1. Verify that the permission for the user looks like the following example.
```
root ALL=(ALL:ALL) ALL
```
1. (Optional) To [run containerized Lambda functions](run-lambda-functions.md), you must enable [cgroups](https://en.wikipedia.org/wiki/Cgroups) v1, and you must enable and mount the *memory* and *devices* cgroups. If you don't plan to run containerized Lambda functions, you can skip this step.
To enable these cgroups options, boot the device with the following Linux kernel parameters.
```
cgroup_enable=memory cgroup_memory=1 systemd.unified_cgroup_hierarchy=0
```
For information about viewing and setting kernel parameters for your device, see the documentation for your operating system and boot loader. Follow the instructions to permanently set the kernel parameters.
1. Install all other required dependencies on your device as indicated by the list of requirements in [Device requirements](greengrass-nucleus-component.md#greengrass-v2-requirements).
### Set up a Windows device
**Note**
This feature is available for v2.5.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md).
**To set up a Windows device for AWS IoT Greengrass V2**
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend that you use [Amazon Corretto](https://aws.amazon.com/corretto/) or [OpenJDK](https://openjdk.java.net/) long-term support versions. Version 8 or higher is required.
1. Check whether Java is available on the [PATH](https://en.wikipedia.org/wiki/PATH_(variable)) system variable, and add it if not. The LocalSystem account runs the AWS IoT Greengrass Core software, so you must add Java to the PATH system variable instead of the PATH user variable for your user. Do the following:
1. Press the Windows key to open the start menu.
1. Type **environment variables** to search for the system options from the start menu.
1. In the start menu search results, choose **Edit the system environment variables** to open the **System properties** window.
1. Choose **Environment variables...** to open the **Environment Variables** window.
1. Under **System variables**, select **Path**, and then choose **Edit**. In the **Edit environment variable** window, you can view each path on a separate line.
1. Check if the path to the Java installation's `bin` folder is present. The path might look similar to the following example.
```
C:\\Program Files\\Amazon Corretto\\jdk11.0.13_8\\bin
```
1. If the Java installation's `bin` folder is missing from **Path**, choose **New** to add it, and then choose **OK**.
1. Open the Windows Command Prompt (`cmd.exe`) as an administrator.
1. Create the default user in the LocalSystem account on the Windows device. Replace *password* with a secure password.
```
net user /add ggc_user password
```
**Tip**
Depending on your Windows configuration, the user's password might be set to expire at a date in the future. To ensure your Greengrass applications continue to operate, track when the password expires, and update it before it expires. You can also set the user's password to never expire.
To check when a user and its password expire, run the following command.
```
net user ggc_user | findstr /C:expires
```
To set a user's password to never expire, run the following command.
```
wmic UserAccount where "Name='ggc_user'" set PasswordExpires=False
```
If you’re using Windows 10 or later where the [`wmic` command is deprecated](https://learn.microsoft.com/en-us/windows/win32/wmisdk/wmic), run the following PowerShell command.
```
Get-CimInstance -Query "SELECT * from Win32_UserAccount WHERE name = 'ggc_user'" | Set-CimInstance -Property @{PasswordExpires="False"}
```
1. Download and install the [PsExec utility](https://docs.microsoft.com/en-us/sysinternals/downloads/psexec) from Microsoft on the device.
1. Use the PsExec utility to store the user name and password for the default user in the Credential Manager instance for the LocalSystem account. Replace *password* with the user's password that you set earlier.
```
psexec -s cmd /c cmdkey /generic:ggc_user /user:ggc_user /pass:password
```
If the **PsExec License Agreement** opens, choose **Accept** to agree to the license and run the command.
**Note**
On Windows devices, the LocalSystem account runs the Greengrass nucleus, and you must use the PsExec utility to store the default user information in the LocalSystem account. Using the Credential Manager application stores this information in the Windows account of the currently logged on user, instead of the LocalSystem account.
## Download the AWS IoT Greengrass Core software
You can download the latest version of the AWS IoT Greengrass Core software from the following location:
+ [https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip](https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip)
**Note**
You can download a specific version of the AWS IoT Greengrass Core software from the following location. Replace *version* with the version to download.
```
https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-version.zip
```
**To download the AWS IoT Greengrass Core software**
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. (Optional) To verify the Greengrass nucleus software signature
**Note**
This feature is available with Greengrass nucleus version 2.9.5 and later.
1. Use the following command to verify your Greengrass nucleus artifact's signature:
------
#### [ Linux or Unix ]
```
jarsigner -verify -certs -verbose greengrass-nucleus-latest.zip
```
------
#### [ Windows Command Prompt (CMD) ]
The file name might look different depending on the JDK version you install. Replace *`jdk17.0.6_10`* with the JDK version you installed.
```
"C:\\Program Files\\Amazon Corretto\\jdk17.0.6_10\\bin\\jarsigner.exe" -verify -certs -verbose greengrass-nucleus-latest.zip
```
------
#### [ PowerShell ]
The file name might look different depending on the JDK version you install. Replace *`jdk17.0.6_10`* with the JDK version you installed.
```
'C:\\Program Files\\Amazon Corretto\\jdk17.0.6_10\\bin\\jarsigner.exe' -verify -certs -verbose greengrass-nucleus-latest.zip
```
------
1. The `jarsigner` invocation yields output that indicates the results of the verification.
1. If the Greengrass nucleus zip file is signed, the output contains the following statement:
```
jar verified.
```
1. If the Greengrass nucleus zip file isn't signed, the output contains the following statement:
```
jar is unsigned.
```
1. If you provided the Jarsigner `-certs` option along with `-verify` and `-verbose` options, the output also includes detailed signer certificate information.
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. (Optional) Run the following command to see the version of the AWS IoT Greengrass Core software.
```
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
```
**Important**
If you install a version of the Greengrass nucleus earlier than v2.4.0, don't remove this folder after you install the AWS IoT Greengrass Core software. The AWS IoT Greengrass Core software uses the files in this folder to run.
If you downloaded the latest version of the software, you install v2.4.0 or later, and you can remove this folder after you install the AWS IoT Greengrass Core software.
## Download the AWS IoT fleet provisioning plugin
You can download the latest version of the AWS IoT fleet provisioning plugin from the following location:
+ [https://d2s8p88vqu9w66.cloudfront.net/releases/aws-greengrass-FleetProvisioningByClaim/fleetprovisioningbyclaim-latest.jar](https://d2s8p88vqu9w66.cloudfront.net/releases/aws-greengrass-FleetProvisioningByClaim/fleetprovisioningbyclaim-latest.jar)
**Note**
You can download a specific version of the AWS IoT fleet provisioning plugin from the following location. Replace *version* with the version to download. For more information about each version of the fleet provisioning plugin, see [AWS IoT fleet provisioning plugin changelog](fleet-provisioning-changelog.md).
```
https://d2s8p88vqu9w66.cloudfront.net/releases/aws-greengrass-FleetProvisioningByClaim/fleetprovisioningbyclaim-version.jar
```
The fleet provisioning plugin is open source. To view its source code, see the [AWS IoT fleet provisioning plugin](https://github.com/aws-greengrass/aws-greengrass-fleet-provisioning-by-claim) on GitHub.
**To download the AWS IoT fleet provisioning plugin**
+ On your device, download the AWS IoT fleet provisioning plugin to a file named `aws.greengrass.FleetProvisioningByClaim.jar`. Replace *GreengrassInstaller* with the folder that you want to use.
------
#### [ Linux or Unix ]
```
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/aws-greengrass-FleetProvisioningByClaim/fleetprovisioningbyclaim-latest.jar > GreengrassInstaller/aws.greengrass.FleetProvisioningByClaim.jar
```
------
#### [ Windows Command Prompt (CMD) ]
```
curl -s https://d2s8p88vqu9w66.cloudfront.net/releases/aws-greengrass-FleetProvisioningByClaim/fleetprovisioningbyclaim-latest.jar > GreengrassInstaller/aws.greengrass.FleetProvisioningByClaim.jar
```
------
#### [ PowerShell ]
```
iwr -Uri https://d2s8p88vqu9w66.cloudfront.net/releases/aws-greengrass-FleetProvisioningByClaim/fleetprovisioningbyclaim-latest.jar -OutFile GreengrassInstaller/aws.greengrass.FleetProvisioningByClaim.jar
```
------
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).
## Install the AWS IoT Greengrass Core software
Run the installer with arguments that specify the following actions:
+ Install from a partial configuration file that specifies to use the fleet provisioning plugin to provision AWS resources. The AWS IoT Greengrass Core software uses a configuration file that specifies the configuration of every Greengrass component on the device. The installer creates a complete configuration file from the partial configuration file that you provide and the AWS resources that the fleet provisioning plugin creates.
+ 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.
+ 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.
For more information about the arguments that you can specify, see [Installer arguments](configure-installer.md).
**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).
**To install the AWS IoT Greengrass Core software**
1. Check the version of the AWS IoT Greengrass Core software.
+ Replace *GreengrassInstaller* with the path to the folder that contains the software.
```
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
```
1. Use a text editor to create a configuration file named `config.yaml` to provide to the installer.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
```
nano GreengrassInstaller/config.yaml
```
Copy the following YAML content into the file. This partial configuration file specifies parameters for the fleet provisioning plugin. For more information about the options that you can specify, see [Configure the AWS IoT fleet provisioning plugin](fleet-provisioning-configuration.md).
------
#### [ Linux or Unix ]
```
---
services:
aws.greengrass.Nucleus:
version: "2.17.0"
aws.greengrass.FleetProvisioningByClaim:
configuration:
rootPath: "/greengrass/v2"
awsRegion: "us-west-2"
iotDataEndpoint: "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
iotCredentialEndpoint: "device-credentials-prefix.credentials.iot.us-west-2.amazonaws.com"
iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
provisioningTemplate: "GreengrassFleetProvisioningTemplate"
claimCertificatePath: "/greengrass/v2/claim-certs/claim.pem.crt"
claimCertificatePrivateKeyPath: "/greengrass/v2/claim-certs/claim.private.pem.key"
rootCaPath: "/greengrass/v2/AmazonRootCA1.pem"
templateParameters:
ThingName: "MyGreengrassCore"
ThingGroupName: "MyGreengrassCoreGroup"
```
------
#### [ Windows ]
```
---
services:
aws.greengrass.Nucleus:
version: "2.17.0"
aws.greengrass.FleetProvisioningByClaim:
configuration:
rootPath: "C:\\greengrass\\v2"
awsRegion: "us-west-2"
iotDataEndpoint: "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
iotCredentialEndpoint: "device-credentials-prefix.credentials.iot.us-west-2.amazonaws.com"
iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
provisioningTemplate: "GreengrassFleetProvisioningTemplate"
claimCertificatePath: "C:\\greengrass\\v2\\claim-certs\\claim.pem.crt"
claimCertificatePrivateKeyPath: "C:\\greengrass\\v2\\claim-certs\\claim.private.pem.key"
rootCaPath: "C:\\greengrass\\v2\\AmazonRootCA1.pem"
templateParameters:
ThingName: "MyGreengrassCore"
ThingGroupName: "MyGreengrassCoreGroup"
```
------
Then, do the following:
+ Replace *2.17.0* with the version of the AWS IoT Greengrass Core software.
+ Replace each instance of `/greengrass/v2` or *C:\$1greengrass\$1v2* with the Greengrass root folder.
**Note**
On Windows devices, you must specify path separators as double backslashes (`\\`), such as `C:\\greengrass\\v2`.
+ Replace *us-west-2* with the AWS Region where you created the provisioning template and other resources.
+ Replace the `iotDataEndpoint` with your AWS IoT data endpoint.
+ Replace the `iotCredentialEndpoint` with your AWS IoT credentials endpoint.
+ Replace *GreengrassCoreTokenExchangeRoleAlias* with the name of the token exchange role alias.
+ Replace *GreengrassFleetProvisioningTemplate* with the name of the fleet provisioning template.
+ Replace the `claimCertificatePath` with the path to the claim certificate on the device.
+ Replace the `claimCertificatePrivateKeyPath` with the path to the claim certificate private key on the device.
+ Replace the template parameters (`templateParameters`) with the values to use to provision the device. This example refers to the [example template](fleet-provisioning-setup.md#example-fleet-provisioning-template) that defines `ThingName` and `ThingGroupName` parameters.
**Note**
In this configuration file, you can customize other configuration options such as the ports and network proxy to use, as shown in the following example. For more information, see [Greengrass nucleus configuration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration).
```
---
services:
aws.greengrass.Nucleus:
version: "2.17.0"
configuration:
mqtt:
port: 443
greengrassDataPlanePort: 443
networkProxy:
noProxyAddresses: "http://192.168.0.1,www.example.com"
proxy:
url: "http://my-proxy-server:1100"
username: "Mary_Major"
password: "pass@word1357"
aws.greengrass.FleetProvisioningByClaim:
configuration:
rootPath: "/greengrass/v2"
awsRegion: "us-west-2"
iotDataEndpoint: "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
iotCredentialEndpoint: "device-credentials-prefix.credentials.iot.us-west-2.amazonaws.com"
iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
provisioningTemplate: "GreengrassFleetProvisioningTemplate"
claimCertificatePath: "/greengrass/v2/claim-certs/claim.pem.crt"
claimCertificatePrivateKeyPath: "/greengrass/v2/claim-certs/claim.private.pem.key"
rootCaPath: "/greengrass/v2/AmazonRootCA1.pem"
templateParameters:
ThingName: "MyGreengrassCore"
ThingGroupName: "MyGreengrassCoreGroup"
mqttPort: 443
proxyUrl: "http://my-proxy-server:1100"
proxyUserName: "Mary_Major"
proxyPassword: "pass@word1357"
```
```
---
services:
aws.greengrass.Nucleus:
version: "2.17.0"
configuration:
mqtt:
port: 443
greengrassDataPlanePort: 443
networkProxy:
noProxyAddresses: "http://192.168.0.1,www.example.com"
proxy:
url: "http://my-proxy-server:1100"
username: "Mary_Major"
password: "pass@word1357"
aws.greengrass.FleetProvisioningByClaim:
configuration:
rootPath: "C:\\greengrass\\v2"
awsRegion: "us-west-2"
iotDataEndpoint: "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
iotCredentialEndpoint: "device-credentials-prefix.credentials.iot.us-west-2.amazonaws.com"
iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
provisioningTemplate: "GreengrassFleetProvisioningTemplate"
claimCertificatePath: "C:\\greengrass\\v2\\claim-certs\\claim.pem.crt"
claimCertificatePrivateKeyPath: "C:\\greengrass\\v2\\claim-certs\\claim.private.pem.key"
rootCaPath: "C:\\greengrass\\v2\\AmazonRootCA1.pem"
templateParameters:
ThingName: "MyGreengrassCore"
ThingGroupName: "MyGreengrassCoreGroup"
mqttPort: 443
proxyUrl: "http://my-proxy-server:1100"
proxyUserName: "Mary_Major"
proxyPassword: "pass@word1357"
```
To use an HTTPS proxy, you must use version 1.1.0 or later of the fleet provisioning plugin. You must additionally specify the `rootCaPath` under `system`, as shown in the following example.
```
---
system:
rootCaPath: "/greengrass/v2/AmazonRootCA1.pem"
services:
...
```
```
---
system:
rootCaPath: "C:\\greengrass\\v2\\AmazonRootCA1.pem"
services:
...
```
1. Run the installer. Specify `--trusted-plugin` to provide the fleet provisioning plugin, and specify `--init-config` to provide the configuration file.
+ Replace `/greengrass/v2` with the Greengrass root folder.
+ Replace each instance of *GreengrassInstaller* with the folder where you unpacked the installer.
------
#### [ Linux or Unix ]
```
sudo -E java -Droot="/greengrass/v2" -Dlog.store=FILE \
-jar ./GreengrassInstaller/lib/Greengrass.jar \
--trusted-plugin ./GreengrassInstaller/aws.greengrass.FleetProvisioningByClaim.jar \
--init-config ./GreengrassInstaller/config.yaml \
--component-default-user ggc_user:ggc_group \
--setup-system-service true
```
------
#### [ Windows Command Prompt (CMD) ]
```
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" ^
-jar ./GreengrassInstaller/lib/Greengrass.jar ^
--trusted-plugin ./GreengrassInstaller/aws.greengrass.FleetProvisioningByClaim.jar ^
--init-config ./GreengrassInstaller/config.yaml ^
--component-default-user ggc_user ^
--setup-system-service true
```
------
#### [ PowerShell ]
```
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" `
-jar ./GreengrassInstaller/lib/Greengrass.jar `
--trusted-plugin ./GreengrassInstaller/aws.greengrass.FleetProvisioningByClaim.jar `
--init-config ./GreengrassInstaller/config.yaml `
--component-default-user ggc_user `
--setup-system-service true
```
------
**Important**
On Windows core devices, you must specify `--setup-system-service true` to set up the AWS IoT Greengrass Core software as a system service.
If you specify `--setup-system-service true`, the installer prints `Successfully set up Nucleus as a system service` if it set up and ran the software as a system service. Otherwise, the installer doesn't output any message if it installs the software successfully.
**Note**
You can't use the `deploy-dev-tools` argument to deploy local development tools when you run the installer without the `--provision true` argument. For information about deploying the Greengrass CLI directly on your device, see [Greengrass Command Line Interface](gg-cli.md).
1. Verify the installation by viewing the files in the root folder.
------
#### [ Linux or Unix ]
```
ls /greengrass/v2
```
------
#### [ Windows Command Prompt (CMD) ]
```
dir C:\greengrass\v2
```
------
#### [ PowerShell ]
```
ls C:\greengrass\v2
```
------
If the installation succeeded, the root folder contains several folders, such as `config`, `packages`, and `logs`.
If you installed the AWS IoT Greengrass Core software as a system service, the installer runs the software for you. Otherwise, you must run the software manually. For more information, see [Run the AWS IoT Greengrass Core software](run-greengrass-core-v2.md).
For more information about how to configure and use the software and AWS IoT Greengrass, see the following:
+ [Configure the AWS IoT Greengrass Core software](configure-greengrass-core-v2.md)
+ [Develop AWS IoT Greengrass components](develop-greengrass-components.md)
+ [Deploy AWS IoT Greengrass components to devices](manage-deployments.md)
+ [Greengrass Command Line Interface](gg-cli.md)
# Set up AWS IoT fleet provisioning for Greengrass core devices
To [install the AWS IoT Greengrass Core software with fleet provisioning](fleet-provisioning.md), you must first set up the following resources in your AWS account. These resources enable devices to register themselves with AWS IoT and operate as Greengrass core devices. Follow steps in this section once to create and configure these resources in your AWS account.
+ A token exchange IAM role, which core devices use to authorize calls to AWS services.
+ An AWS IoT role alias that points to the token exchange role.
+ (Optional) An AWS IoT policy, which core devices use to authorize calls to the AWS IoT and AWS IoT Greengrass services. This AWS IoT policy must allow the `iot:AssumeRoleWithCertificate` permission for the AWS IoT role alias that points to the token exchange role.
You can use a single AWS IoT policy for all core devices in your fleet, or you can configure your fleet provisioning template to create an AWS IoT policy for each core device.
+ An AWS IoT fleet provisioning template. This template must specify the following:
+ An AWS IoT thing resource. You can specify a list of existing thing groups to deploy components to each device when it comes online.
+ An AWS IoT policy resource. This resource can define one of the following properties:
+ The name of an existing AWS IoT policy. If you choose this option, the core devices that you create from this template use the same AWS IoT policy, and you can manage their permissions as a fleet.
+ An AWS IoT policy document. If you choose this option, each core device that you create from this template uses a unique AWS IoT policy, and you can manage permissions for each individual core device.
+ An AWS IoT certificate resource. This certificate resource must use the `AWS::IoT::Certificate::Id` parameter to attach the certificate to the core device. For more information, see [Just-in-time provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/jit-provisioning.html) in the *AWS IoT Developer Guide*.
+ An AWS IoT provisioning claim certificate and private key for the fleet provisioning template. You can embed this certificate and private key in devices during manufacturing, so the devices can register and provision themselves when they come online.
**Important**
Provisioning claim private keys should be secured at all times, including on Greengrass core devices. We recommend that you use Amazon CloudWatch metrics and logs to monitor for indications of misuse, such as unauthorized use of the claim certificate to provision devices. If you detect misuse, disable the provisioning claim certificate so that it can't be used for device provisioning. For more information, see [Monitoring AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/monitoring_overview.html) in the *AWS IoT Core Developer Guide*.
To help you better manage the number of devices, and which devices, that register themselves in your AWS account, you can specify a pre-provisioning hook when you create a fleet provisioning template. A pre-provisioning hook is an AWS Lambda function that validates template parameters that devices provide during registration. For example, you might create a pre-provisioning hook that checks a device ID against a database to verify that the device has permission to provision. For more information, see [Pre-provisioning hooks](https://docs.aws.amazon.com/iot/latest/developerguide/pre-provisioning-hook.html) in the *AWS IoT Core Developer Guide*.
+ An AWS IoT policy that you attach to the provisioning claim certificate to allow devices to register and use the fleet provisioning template.
**Topics**
+ [Create a token exchange role](#create-token-exchange-role)
+ [Create an AWS IoT policy](#create-iot-policy)
+ [Create a fleet provisioning template](#create-provisioning-template)
+ [Create a provisioning claim certificate and private key](#create-claim-certificates)
## Create a token exchange role
Greengrass core devices use an IAM service role, called the *token exchange role*, to authorize calls to AWS services. The device uses the AWS IoT credentials provider to get temporary AWS credentials for this role, which allows the device to interact with AWS IoT, send logs to Amazon CloudWatch Logs, and download custom component artifacts from Amazon S3. For more information, see [Authorize core devices to interact with AWS services](device-service-role.md).
You use an AWS IoT *role alias* to configure the token exchange role for Greengrass core devices. Role aliases enable you to change the token exchange role for a device but keep the device configuration the same. For more information, see [Authorizing direct calls to AWS services](https://docs.aws.amazon.com/iot/latest/developerguide/authorizing-direct-aws.html) in the *AWS IoT Core Developer Guide*.
In this section, you create a token exchange IAM role and an AWS IoT role alias that points to the role. If you have already set up a Greengrass core device, you can use its token exchange role and role alias instead of creating new ones.
**To create a token exchange IAM role**
1. Create an IAM role that your device can use as a token exchange role. Do the following:
1. Create a file that contains the trust policy document that the token exchange role requires.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
```
nano device-role-trust-policy.json
```
Copy the following JSON into the file.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "credentials.iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
1. Create the token exchange role with the trust policy document.
+ Replace *GreengrassV2TokenExchangeRole* with the name of the IAM role to create.
```
aws iam create-role --role-name GreengrassV2TokenExchangeRole --assume-role-policy-document file://device-role-trust-policy.json
```
The response looks similar to the following example, if the request succeeds.
```
{
"Role": {
"Path": "/",
"RoleName": "GreengrassV2TokenExchangeRole",
"RoleId": "AROAZ2YMUHYHK5OKM77FB",
"Arn": "arn:aws:iam::123456789012:role/GreengrassV2TokenExchangeRole",
"CreateDate": "2021-02-06T00:13:29+00:00",
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "credentials.iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
}
```
1. Create a file that contains the access policy document that the token exchange role requires.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
```
nano device-role-access-policy.json
```
Copy the following JSON into the file.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogStreams",
"s3:GetBucketLocation"
],
"Resource": "*"
}
]
}
```
**Note**
This access policy doesn't allow access to component artifacts in S3 buckets. To deploy custom components that define artifacts in Amazon S3, you must add permissions to the role to allow your core device to retrieve component artifacts. For more information, see [Allow access to S3 buckets for component artifacts](device-service-role.md#device-service-role-access-s3-bucket).
If you don't yet have an S3 bucket for component artifacts, you can add these permissions later after you create a bucket.
1. Create the IAM policy from the policy document.
+ Replace *GreengrassV2TokenExchangeRoleAccess* with the name of the IAM policy to create.
```
aws iam create-policy --policy-name GreengrassV2TokenExchangeRoleAccess --policy-document file://device-role-access-policy.json
```
The response looks similar to the following example, if the request succeeds.
```
{
"Policy": {
"PolicyName": "GreengrassV2TokenExchangeRoleAccess",
"PolicyId": "ANPAZ2YMUHYHACI7C5Z66",
"Arn": "arn:aws:iam::123456789012:policy/GreengrassV2TokenExchangeRoleAccess",
"Path": "/",
"DefaultVersionId": "v1",
"AttachmentCount": 0,
"PermissionsBoundaryUsageCount": 0,
"IsAttachable": true,
"CreateDate": "2021-02-06T00:37:17+00:00",
"UpdateDate": "2021-02-06T00:37:17+00:00"
}
}
```
1. Attach the IAM policy to the token exchange role.
+ Replace *GreengrassV2TokenExchangeRole* with the name of the IAM role.
+ Replace the policy ARN with the ARN of the IAM policy that you created in the previous step.
```
aws iam attach-role-policy --role-name GreengrassV2TokenExchangeRole --policy-arn arn:aws:iam::123456789012:policy/GreengrassV2TokenExchangeRoleAccess
```
The command doesn't have any output if the request succeeds.
1. Create an AWS IoT role alias that points to the token exchange role.
+ Replace *GreengrassCoreTokenExchangeRoleAlias* with the name of the role alias to create.
+ Replace the role ARN with the ARN of the IAM role that you created in the previous step.
```
aws iot create-role-alias --role-alias GreengrassCoreTokenExchangeRoleAlias --role-arn arn:aws:iam::123456789012:role/GreengrassV2TokenExchangeRole
```
The response looks similar to the following example, if the request succeeds.
```
{
"roleAlias": "GreengrassCoreTokenExchangeRoleAlias",
"roleAliasArn": "arn:aws:iot:us-west-2:123456789012:rolealias/GreengrassCoreTokenExchangeRoleAlias"
}
```
**Note**
To create a role alias, you must have permission to pass the token exchange IAM role to AWS IoT. If you receive an error message when you try to create a role alias, check that your AWS user has this permission. For more information, see [Granting a user permissions to pass a role to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html) in the *AWS Identity and Access Management User Guide*.
## Create an AWS IoT policy
After you register a device as an AWS IoT thing, that device can use a digital certificate to authenticate with AWS. This certificate includes one or more AWS IoT policies that define the permissions that a device can use with the certificate. These policies allow the device to communicate with AWS IoT and AWS IoT Greengrass.
With AWS IoT fleet provisioning, devices connect to AWS IoT to create and download a device certificate. In the fleet provisioning template that you create in the next section, you can specify whether AWS IoT attaches the same AWS IoT policy to all devices' certificates, or creates a new policy for each device.
In this section, you create an AWS IoT policy that AWS IoT attaches to all devices' certificates. With this approach, you can manage permissions for all devices as a fleet. If you would rather create a new AWS IoT policy for each device, you can skip this section, and refer to the policy in it when you define your fleet template.
**To create an AWS IoT policy**
+ Create an AWS IoT policy that defines the AWS IoT permissions for your fleet of Greengrass core devices. The following policy allows access to all MQTT topics and Greengrass operations, so your device works with custom applications and future changes that require new Greengrass operations. This policy also allows the `iot:AssumeRoleWithCertificate` permission, which allows your devices to use the token exchange role that you created in the previous section. You can restrict this policy down based on your 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).
Do the following:
1. Create a file that contains the AWS IoT policy document that Greengrass core devices require.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
```
nano greengrass-v2-iot-policy.json
```
Copy the following JSON into the file.
+ Replace the `iot:AssumeRoleWithCertificate` resource with the ARN of the AWS IoT role alias that you created in the previous section.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Subscribe",
"iot:Receive",
"iot:Connect",
"greengrass:*"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": "iot:AssumeRoleWithCertificate",
"Resource": "arn:aws:iot:us-east-1:123456789012:rolealias/GreengrassCoreTokenExchangeRoleAlias"
}
]
}
```
------
1. Create an AWS IoT policy from the policy document.
+ Replace *GreengrassV2IoTThingPolicy* with the name of the policy to create.
```
aws iot create-policy --policy-name GreengrassV2IoTThingPolicy --policy-document file://greengrass-v2-iot-policy.json
```
The response looks similar to the following example, if the request succeeds.
------
#### [ JSON ]
****
```
{
"policyName": "GreengrassV2IoTThingPolicy",
"policyArn": "arn:aws:iot:us-west-2:123456789012:policy/GreengrassV2IoTThingPolicy",
"policyDocument": "{
\"Version\": \"2012-10-17\",
\"Statement\": [
{
\"Effect\": \"Allow\",
\"Action\": [
\"iot:Publish\",
\"iot:Subscribe\",
\"iot:Receive\",
\"iot:Connect\",
\"greengrass:*\"
],
\"Resource\": [
\"*\"
]
},
{
\"Effect\": \"Allow\",
\"Action\": \"iot:AssumeRoleWithCertificate\",
\"Resource\": \"arn:aws:iot:us-west-2:123456789012:rolealias/GreengrassCoreTokenExchangeRoleAlias\"
}
]
}",
"policyVersionId": "1"
}
```
------
## Create a fleet provisioning template
AWS IoT fleet provisioning templates define how to provision AWS IoT things, policies, and certificates. To provision Greengrass core devices with the fleet provisioning plugin, you must create a template that specifies the following:
+ An AWS IoT thing resource. You can specify a list of existing thing groups to deploy components to each device when it comes online.
+ An AWS IoT policy resource. This resource can define one of the following properties:
+ The name of an existing AWS IoT policy. If you choose this option, the core devices that you create from this template use the same AWS IoT policy, and you can manage their permissions as a fleet.
+ An AWS IoT policy document. If you choose this option, each core device that you create from this template uses a unique AWS IoT policy, and you can manage permissions for each individual core device.
+ An AWS IoT certificate resource. This certificate resource must use the `AWS::IoT::Certificate::Id` parameter to attach the certificate to the core device. For more information, see [Just-in-time provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/jit-provisioning.html) in the *AWS IoT Developer Guide*.
In the template, you can specify to add the AWS IoT thing to a list of existing thing groups. When the core device connects to AWS IoT Greengrass for the first time, it receives Greengrass deployments for each thing group where it's a member. You can use thing groups to deploy the latest software to each device as soon as it comes online. For more information, see [Deploy AWS IoT Greengrass components to devices](manage-deployments.md).
The AWS IoT service requires permissions to create and update AWS IoT resources in your AWS account when provisioning devices. To give the AWS IoT service access, you create an IAM role and provide it when you create the template. AWS IoT provides an managed policy, [AWSIoTThingsRegistration](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/service-role/AWSIoTThingsRegistration), that allows access to all permissions that AWS IoT might use when provisioning devices. You can use this managed policy, or create a custom policy that scopes down the permissions in the managed policy for your use case.
In this section, you create an IAM role that allows AWS IoT to provision resources for devices, and you create a fleet provisioning template that uses that IAM role.
**To create a fleet provisioning template**
1. Create an IAM role that AWS IoT can assume to provision resources in your AWS account. Do the following:
1. Create a file that contains the trust policy document that allows AWS IoT to assume the role.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
```
nano aws-iot-trust-policy.json
```
Copy the following JSON into the file.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. Create an IAM role with the trust policy document.
+ Replace *GreengrassFleetProvisioningRole* with the name of the IAM role to create.
```
aws iam create-role --role-name GreengrassFleetProvisioningRole --assume-role-policy-document file://aws-iot-trust-policy.json
```
The response looks similar to the following example, if the request succeeds.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Connect",
"iot:Publish",
"iot:Subscribe",
"iot:Receive"
],
"Resource": "*"
}
]
}
```
------
1. Review the [AWSIoTThingsRegistration](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/service-role/AWSIoTThingsRegistration) policy, which allows access to all permissions that AWS IoT might use when provisioning devices. You can use this managed policy, or create a custom policy that defines scoped-down permissions for your use case. If you choose to create a custom policy, do so now.
1. Attach the IAM policy to the fleet provisioning role.
+ Replace *GreengrassFleetProvisioningRole* with the name of the IAM role.
+ If you created a custom policy in the previous step, replace the policy ARN with the ARN of the IAM policy to use.
```
aws iam attach-role-policy --role-name GreengrassFleetProvisioningRole --policy-arn arn:aws:iam::aws:policy/service-role/AWSIoTThingsRegistration
```
The command doesn't have any output if the request succeeds.
1. (Optional) Create a *pre-provisioning hook*, which is an AWS Lambda function that validates template parameters that devices provide during registration. You can use a pre-provisioning hook to gain more control over which and how many devices onboard in your AWS account. For more information, see [Pre-provisioning hooks](https://docs.aws.amazon.com/iot/latest/developerguide/pre-provisioning-hook.html) in the *AWS IoT Core Developer Guide*.
1. Create a fleet provisioning template. Do the following:
1. Create a file to contain the provisioning template document.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
```
nano greengrass-fleet-provisioning-template.json
```
Write the provisioning template document. You can start from the following example provisioning template, which specifies to create an AWS IoT thing with the following properties:
+ The thing's name is the value that you specify in the `ThingName` template parameter.
+ The thing is a member of the thing group that you specify in the `ThingGroupName` template parameter. The thing group must exist in your AWS account.
+ The thing's certificate has the AWS IoT policy named `GreengrassV2IoTThingPolicy` attached to it.
For more information, see [Provisioning templates](https://docs.aws.amazon.com/iot/latest/developerguide/provision-template.html) in the *AWS IoT Core Developer Guide*.
```
{
"Parameters": {
"ThingName": {
"Type": "String"
},
"ThingGroupName": {
"Type": "String"
},
"AWS::IoT::Certificate::Id": {
"Type": "String"
}
},
"Resources": {
"MyThing": {
"OverrideSettings": {
"AttributePayload": "REPLACE",
"ThingGroups": "REPLACE",
"ThingTypeName": "REPLACE"
},
"Properties": {
"AttributePayload": {},
"ThingGroups": [
{
"Ref": "ThingGroupName"
}
],
"ThingName": {
"Ref": "ThingName"
}
},
"Type": "AWS::IoT::Thing"
},
"MyPolicy": {
"Properties": {
"PolicyName": "GreengrassV2IoTThingPolicy"
},
"Type": "AWS::IoT::Policy"
},
"MyCertificate": {
"Properties": {
"CertificateId": {
"Ref": "AWS::IoT::Certificate::Id"
},
"Status": "Active"
},
"Type": "AWS::IoT::Certificate"
}
}
}
```
**Note**
*MyThing*, *MyPolicy*, and *MyCertificate* are arbitrary names that identify each resource specification in the fleet provisioning template. AWS IoT doesn't use these names in the resources that it creates from the template. You can use these names or replace them with values that help you identify each resource in the template.
1. Create the fleet provisioning template from the provisioning template document.
+ Replace *GreengrassFleetProvisioningTemplate* with the name of the template to create.
+ Replace the template description with a description for your template.
+ Replace the provisioning role ARN with the ARN of the role that you created earlier.
------
#### [ Linux or Unix ]
```
aws iot create-provisioning-template \
--template-name GreengrassFleetProvisioningTemplate \
--description "A provisioning template for Greengrass core devices." \
--provisioning-role-arn "arn:aws:iam::123456789012:role/GreengrassFleetProvisioningRole" \
--template-body file://greengrass-fleet-provisioning-template.json \
--enabled
```
------
#### [ Windows Command Prompt (CMD) ]
```
aws iot create-provisioning-template ^
--template-name GreengrassFleetProvisioningTemplate ^
--description "A provisioning template for Greengrass core devices." ^
--provisioning-role-arn "arn:aws:iam::123456789012:role/GreengrassFleetProvisioningRole" ^
--template-body file://greengrass-fleet-provisioning-template.json ^
--enabled
```
------
#### [ PowerShell ]
```
aws iot create-provisioning-template `
--template-name GreengrassFleetProvisioningTemplate `
--description "A provisioning template for Greengrass core devices." `
--provisioning-role-arn "arn:aws:iam::123456789012:role/GreengrassFleetProvisioningRole" `
--template-body file://greengrass-fleet-provisioning-template.json `
--enabled
```
------
**Note**
If you created a pre-provisioning hook, specify the ARN of the pre-provisioning hook's Lambda function with the `--pre-provisioning-hook` argument.
```
--pre-provisioning-hook targetArn=arn:aws:lambda:us-west-2:123456789012:function:GreengrassPreProvisioningHook
```
The response looks similar to the following example, if the request succeeds.
```
{
"templateArn": "arn:aws:iot:us-west-2:123456789012:provisioningtemplate/GreengrassFleetProvisioningTemplate",
"templateName": "GreengrassFleetProvisioningTemplate",
"defaultVersionId": 1
}
```
## Create a provisioning claim certificate and private key
Claim certificates are X.509 certificates that allow devices to register as AWS IoT things and retrieve a unique X.509 device certificate to use for regular operations. After you create a claim certificate, you attach an AWS IoT policy that allows devices to use it to create unique device certificates and provision with a fleet provisioning template. Devices with the claim certificate can provision using only the provisioning template that you allow in the AWS IoT policy.
In this section, you create the claim certificate and configure it for devices to use with the fleet provisioning template that you created in the previous section.
**Important**
Provisioning claim private keys should be secured at all times, including on Greengrass core devices. We recommend that you use Amazon CloudWatch metrics and logs to monitor for indications of misuse, such as unauthorized use of the claim certificate to provision devices. If you detect misuse, disable the provisioning claim certificate so that it can't be used for device provisioning. For more information, see [Monitoring AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/monitoring_overview.html) in the *AWS IoT Core Developer Guide*.
To help you better manage the number of devices, and which devices, that register themselves in your AWS account, you can specify a pre-provisioning hook when you create a fleet provisioning template. A pre-provisioning hook is an AWS Lambda function that validates template parameters that devices provide during registration. For example, you might create a pre-provisioning hook that checks a device ID against a database to verify that the device has permission to provision. For more information, see [Pre-provisioning hooks](https://docs.aws.amazon.com/iot/latest/developerguide/pre-provisioning-hook.html) in the *AWS IoT Core Developer Guide*.
**To create a provisioning claim certificate and private key**
1. Create a folder where you download the claim certificate and private key.
```
mkdir claim-certs
```
1. Create and save a certificate and private key to use for provisioning. AWS IoT provides client certificates that are signed by the Amazon Root certificate authority (CA).
------
#### [ Linux or Unix ]
```
aws iot create-keys-and-certificate \
--certificate-pem-outfile "claim-certs/claim.pem.crt" \
--public-key-outfile "claim-certs/claim.public.pem.key" \
--private-key-outfile "claim-certs/claim.private.pem.key" \
--set-as-active
```
------
#### [ Windows Command Prompt (CMD) ]
```
aws iot create-keys-and-certificate ^
--certificate-pem-outfile "claim-certs/claim.pem.crt" ^
--public-key-outfile "claim-certs/claim.public.pem.key" ^
--private-key-outfile "claim-certs/claim.private.pem.key" ^
--set-as-active
```
------
#### [ PowerShell ]
```
aws iot create-keys-and-certificate `
--certificate-pem-outfile "claim-certs/claim.pem.crt" `
--public-key-outfile "claim-certs/claim.public.pem.key" `
--private-key-outfile "claim-certs/claim.private.pem.key" `
--set-as-active
```
------
The response contains information about the certificate, if the request succeeds. Save the certificate's ARN to use later.
1. Create and attach an AWS IoT policy that allows devices to use the certificate to create unique device certificates and provision with the fleet provisioning template. The following policy allows access to the device provisioning MQTT API. For more information, see [Device provisioning MQTT API](https://docs.aws.amazon.com/iot/latest/developerguide/fleet-provision-api.html) in the *AWS IoT Core Developer Guide*.
Do the following:
1. Create a file that contains the AWS IoT policy document that Greengrass core devices require.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
```
nano greengrass-provisioning-claim-iot-policy.json
```
Copy the following JSON into the file.
+ Replace each instance of *region* with the AWS Region where you set up fleet provisioning.
+ Replace each instance of *account-id* with your AWS account ID.
+ Replace each instance of *GreengrassFleetProvisioningTemplate* with the name of the fleet provisioning template that you created in the previous section.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Receive"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/certificates/create/*",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/provisioning-templates/GreengrassFleetProvisioningTemplate/provision/*"
]
},
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/certificates/create/*",
"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/provisioning-templates/GreengrassFleetProvisioningTemplate/provision/*"
]
}
]
}
```
------
1. Create an AWS IoT policy from the policy document.
+ Replace *GreengrassProvisioningClaimPolicy* with the name of the policy to create.
```
aws iot create-policy --policy-name GreengrassProvisioningClaimPolicy --policy-document file://greengrass-provisioning-claim-iot-policy.json
```
The response looks similar to the following example, if the request succeeds.
------
#### [ JSON ]
****
```
{
"policyName": "GreengrassProvisioningClaimPolicy",
"policyArn": "arn:aws:iot:us-west-2:123456789012:policy/GreengrassProvisioningClaimPolicy",
"policyDocument": "{
\"Version\": \"2012-10-17\",
\"Statement\": [
{
\"Effect\": \"Allow\",
\"Action\": \"iot:Connect\",
\"Resource\": \"*\"
},
{
\"Effect\": \"Allow\",
\"Action\": [
\"iot:Publish\",
\"iot:Receive\"
],
\"Resource\": [
\"arn:aws:iot:us-east-1:123456789012:topic/$aws/certificates/create/*\",
\"arn:aws:iot:us-east-1:123456789012:topic/$aws/provisioning-templates/GreengrassFleetProvisioningTemplate/provision/*\"
]
},
{
\"Effect\": \"Allow\",
\"Action\": \"iot:Subscribe\",
\"Resource\": [
\"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/certificates/create/*\",
\"arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/provisioning-templates/GreengrassFleetProvisioningTemplate/provision/*\"
]
}
]
}",
"policyVersionId": "1"
}
```
------
1. Attach the AWS IoT policy to the provisioning claim certificate.
+ Replace *GreengrassProvisioningClaimPolicy* with the name of the policy to attach.
+ Replace the target ARN with the ARN of the provisioning claim certificate.
```
aws iot attach-policy --policy-name GreengrassProvisioningClaimPolicy --target arn:aws:iot:us-west-2:123456789012:cert/aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4
```
The command doesn't have any output if the request succeeds.
You now have a provisioning claim certificate and private key that devices can use to register with AWS IoT and provision themselves as Greengrass core devices. You can embed the claim certificate and private key in devices during manufacturing, or copy the certificate and key to devices before you install the AWS IoT Greengrass Core software. For more information, see [Install AWS IoT Greengrass Core software with AWS IoT fleet provisioning](fleet-provisioning.md).
# Configure the AWS IoT fleet provisioning plugin
The AWS IoT fleet provisioning plugin provides the following configuration parameters that you can customize when you [install the AWS IoT Greengrass Core software with fleet provisioning](fleet-provisioning.md).
`rootPath`
The path to the folder to use as the root for the AWS IoT Greengrass Core software.
`awsRegion`
The AWS Region that the fleet provisioning plugin uses to provision AWS resources.
`iotDataEndpoint`
The AWS IoT data endpoint for your AWS account.
`iotCredentialEndpoint`
The AWS IoT credentials endpoint for your AWS account.
`iotRoleAlias`
The AWS IoT role alias that points to a token exchange IAM role. The AWS IoT credentials provider assumes this role to allow the Greengrass core device to interact with AWS services. For more information, see [Authorize core devices to interact with AWS services](device-service-role.md).
`provisioningTemplate`
The AWS IoT fleet provisioning template to use to provision AWS resources. This template must specify the following:
+ An AWS IoT thing resource. You can specify a list of existing thing groups to deploy components to each device when it comes online.
+ An AWS IoT policy resource. This resource can define one of the following properties:
+ The name of an existing AWS IoT policy. If you choose this option, the core devices that you create from this template use the same AWS IoT policy, and you can manage their permissions as a fleet.
+ An AWS IoT policy document. If you choose this option, each core device that you create from this template uses a unique AWS IoT policy, and you can manage permissions for each individual core device.
+ An AWS IoT certificate resource. This certificate resource must use the `AWS::IoT::Certificate::Id` parameter to attach the certificate to the core device. For more information, see [Just-in-time provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/jit-provisioning.html) in the *AWS IoT Developer Guide*.
For more information, see [Provisioning templates](https://docs.aws.amazon.com/iot/latest/developerguide/provision-template.html) in the *AWS IoT Core Developer Guide*.
`claimCertificatePath`
The path to the provisioning claim certificate for the provisioning template that you specify in `provisioningTemplate`. For more information, see [CreateProvisioningClaim](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateProvisioningClaim.html) in the *AWS IoT Core API Reference*.
`claimCertificatePrivateKeyPath`
The path to the provisioning claim certificate private key for the provisioning template that you specify in `provisioningTemplate`. For more information, see [CreateProvisioningClaim](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateProvisioningClaim.html) in the *AWS IoT Core API Reference*.
Provisioning claim private keys should be secured at all times, including on Greengrass core devices. We recommend that you use Amazon CloudWatch metrics and logs to monitor for indications of misuse, such as unauthorized use of the claim certificate to provision devices. If you detect misuse, disable the provisioning claim certificate so that it can't be used for device provisioning. For more information, see [Monitoring AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/monitoring_overview.html) in the *AWS IoT Core Developer Guide*.
To help you better manage the number of devices, and which devices, that register themselves in your AWS account, you can specify a pre-provisioning hook when you create a fleet provisioning template. A pre-provisioning hook is an AWS Lambda function that validates template parameters that devices provide during registration. For example, you might create a pre-provisioning hook that checks a device ID against a database to verify that the device has permission to provision. For more information, see [Pre-provisioning hooks](https://docs.aws.amazon.com/iot/latest/developerguide/pre-provisioning-hook.html) in the *AWS IoT Core Developer Guide*.
`rootCaPath`
The path to the Amazon root certificate authority (CA) certificate.
`templateParameters`
(Optional) The map of parameters to provide to the fleet provisioning template. For more information, see [Provisioning templates' parameters section](https://docs.aws.amazon.com/iot/latest/developerguide/provision-template.html#parameters-section) in the *AWS IoT Core Developer Guide*.
`deviceId`
(Optional) The device identifier to use as the client ID when the fleet provisioning plugin creates an MQTT connection to AWS IoT.
Default: A random UUID.
`mqttPort`
(Optional) The port to use for MQTT connections.
Default: `8883`
`proxyUrl`
(Optional) The URL of the proxy server in the format `scheme://userinfo@host:port`. To use an HTTPS proxy, you must use version 1.1.0 or later of the fleet provisioning plugin.
+ `scheme` – The scheme, which must be `http` or `https`.
**Important**
Greengrass core devices must run [Greengrass nucleus ](greengrass-nucleus-component.md) v2.5.0 or later to use HTTPS proxies.
If you configure an HTTPS proxy, you must add the proxy server CA certificate to the core device's Amazon root CA certificate. For more information, see [Enable the core device to trust an HTTPS proxy](configure-greengrass-core-v2.md#https-proxy-certificate-trust).
+ `userinfo` – (Optional) The user name and password information. If you specify this information in the `url`, the Greengrass core device ignores the `username` and `password` fields.
+ `host` – The host name or IP address of the proxy server.
+ `port` – (Optional) The port number. If you don't specify the port, then the Greengrass core device uses the following default values:
+ `http` – 80
+ `https` – 443
`proxyUserName`
(Optional) The user name that authenticates the proxy server.
`proxyPassword`
(Optional) The user name that authenticates the proxy server.
csrPath
(Optional) The path to the certificate signing request (CSR) file to use to create the device certificate from a CSR. For more information, see [Provisioning by claim](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html#claim-based) in the * AWS IoT Core developer guide*.
csrPrivateKeyPath
(Optional, required if `csrPath` is declared) The path to the private key used to generate the CSR. The private key must have been used to generate the CSR. For more information, see [Provisioning by claim](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html#claim-based) in the *AWS IoT Core developer guide*.
certificatePath
(Optional) The path to use to save the downloaded device certificate.
privateKeyPath
(Optional) The path to use to save the downloaded device private key.
# AWS IoT fleet provisioning plugin changelog
The following table describes the changes in each version of the AWS IoT fleet provisioning by claim plugin (`aws.greengrass.FleetProvisioningByClaim`).
| Version | Changes |
| --- | --- |
| 1.2.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/fleet-provisioning-changelog.html) |
| 1.2.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/fleet-provisioning-changelog.html) |
| 1.2.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/fleet-provisioning-changelog.html) |
| 1.1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/fleet-provisioning-changelog.html) |
| 1.0.0 | Initial version. |
# Install AWS IoT Greengrass Core software with custom resource provisioning
This feature is available for v2.4.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md).
The AWS IoT Greengrass Core software installer provides a Java interface that you can implement in a custom plugin that provisions required AWS resources. You can develop a provisioning plugin to use custom X.509 client certificates or to run complex provisioning steps that other installation processes don't support. For more information, see [Create your own client certificates](https://docs.aws.amazon.com/iot/latest/developerguide/device-certs-your-own.html) in the *AWS IoT Core Developer Guide*.
To run a custom provisioning plugin when you install the AWS IoT Greengrass Core software, you create a JAR file that you provide to the installer. The installer runs the plugin, and the plugin returns a provisioning configuration that defines the AWS resources for the Greengrass core device. The installer uses this information to configure the AWS IoT Greengrass Core software on the device. For more information, see [Develop custom provisioning plugins](develop-custom-provisioning-plugins.md).
**Important**
Before you download the AWS IoT Greengrass Core software, check that your core device meets the [requirements](greengrass-nucleus-component.md#greengrass-v2-requirements) to install and run the AWS IoT Greengrass Core software v2.0.
**Topics**
+ [Prerequisites](#custom-provisioning-prerequisites)
+ [Set up the device environment](#set-up-device-environment)
+ [Download the AWS IoT Greengrass Core software](#download-greengrass-core-v2)
+ [Install the AWS IoT Greengrass Core software](#run-greengrass-core-v2-installer-custom)
+ [Develop custom provisioning plugins](develop-custom-provisioning-plugins.md)
## Prerequisites
To install the AWS IoT Greengrass Core software with custom provisioning, you must have the following:
+ A JAR file for a custom provisioning plugin that implements the `DeviceIdentityInterface`. The custom provisioning plugin must return values for each system and nucleus configuration parameter. Otherwise, you must provide those values in the configuration file during installation. For more information, see [Develop custom provisioning plugins](develop-custom-provisioning-plugins.md).
## Set up the device environment
Follow the steps in this section to set up a Linux or Windows device to use as your AWS IoT Greengrass core device.
### Set up a Linux device
**To set up a Linux device for AWS IoT Greengrass V2**
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend that you use [Amazon Corretto](https://aws.amazon.com/corretto/) or [OpenJDK](https://openjdk.java.net/) long-term support versions. Version 8 or higher is required. The following commands show you how to install OpenJDK on your device.
+ For Debian-based or Ubuntu-based distributions:
```
sudo apt install default-jdk
```
+ For Red Hat-based distributions:
```
sudo yum install java-11-openjdk-devel
```
+ For Amazon Linux 2:
```
sudo amazon-linux-extras install java-openjdk11
```
+ For Amazon Linux 2023:
```
sudo dnf install java-11-amazon-corretto -y
```
When the installation completes, run the following command to verify that Java runs on your Linux device.
```
java -version
```
The command prints the version of Java that runs on the device. For example, on a Debian-based distribution, the output might look similar to the following sample.
```
openjdk version "11.0.9.1" 2020-11-04
OpenJDK Runtime Environment (build 11.0.9.1+1-post-Debian-1deb10u2)
OpenJDK 64-Bit Server VM (build 11.0.9.1+1-post-Debian-1deb10u2, mixed mode)
```
1. (Optional) Create the default system user and group that runs components on the device. You can also choose to let the AWS IoT Greengrass Core software installer create this user and group during installation with the `--component-default-user` installer argument. For more information, see [Installer arguments](configure-installer.md).
```
sudo useradd --system --create-home ggc_user
sudo groupadd --system ggc_group
```
1. Verify that the user that runs the AWS IoT Greengrass Core software (typically `root`), has permission to run `sudo` with any user and any group.
1. Run the following command to open the `/etc/sudoers` file.
```
sudo visudo
```
1. Verify that the permission for the user looks like the following example.
```
root ALL=(ALL:ALL) ALL
```
1. (Optional) To [run containerized Lambda functions](run-lambda-functions.md), you must enable [cgroups](https://en.wikipedia.org/wiki/Cgroups) v1, and you must enable and mount the *memory* and *devices* cgroups. If you don't plan to run containerized Lambda functions, you can skip this step.
To enable these cgroups options, boot the device with the following Linux kernel parameters.
```
cgroup_enable=memory cgroup_memory=1 systemd.unified_cgroup_hierarchy=0
```
For information about viewing and setting kernel parameters for your device, see the documentation for your operating system and boot loader. Follow the instructions to permanently set the kernel parameters.
1. Install all other required dependencies on your device as indicated by the list of requirements in [Device requirements](greengrass-nucleus-component.md#greengrass-v2-requirements).
### Set up a Windows device
**Note**
This feature is available for v2.5.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md).
**To set up a Windows device for AWS IoT Greengrass V2**
1. Install the Java runtime, which AWS IoT Greengrass Core software requires to run. We recommend that you use [Amazon Corretto](https://aws.amazon.com/corretto/) or [OpenJDK](https://openjdk.java.net/) long-term support versions. Version 8 or higher is required.
1. Check whether Java is available on the [PATH](https://en.wikipedia.org/wiki/PATH_(variable)) system variable, and add it if not. The LocalSystem account runs the AWS IoT Greengrass Core software, so you must add Java to the PATH system variable instead of the PATH user variable for your user. Do the following:
1. Press the Windows key to open the start menu.
1. Type **environment variables** to search for the system options from the start menu.
1. In the start menu search results, choose **Edit the system environment variables** to open the **System properties** window.
1. Choose **Environment variables...** to open the **Environment Variables** window.
1. Under **System variables**, select **Path**, and then choose **Edit**. In the **Edit environment variable** window, you can view each path on a separate line.
1. Check if the path to the Java installation's `bin` folder is present. The path might look similar to the following example.
```
C:\\Program Files\\Amazon Corretto\\jdk11.0.13_8\\bin
```
1. If the Java installation's `bin` folder is missing from **Path**, choose **New** to add it, and then choose **OK**.
1. Open the Windows Command Prompt (`cmd.exe`) as an administrator.
1. Create the default user in the LocalSystem account on the Windows device. Replace *password* with a secure password.
```
net user /add ggc_user password
```
**Tip**
Depending on your Windows configuration, the user's password might be set to expire at a date in the future. To ensure your Greengrass applications continue to operate, track when the password expires, and update it before it expires. You can also set the user's password to never expire.
To check when a user and its password expire, run the following command.
```
net user ggc_user | findstr /C:expires
```
To set a user's password to never expire, run the following command.
```
wmic UserAccount where "Name='ggc_user'" set PasswordExpires=False
```
If you’re using Windows 10 or later where the [`wmic` command is deprecated](https://learn.microsoft.com/en-us/windows/win32/wmisdk/wmic), run the following PowerShell command.
```
Get-CimInstance -Query "SELECT * from Win32_UserAccount WHERE name = 'ggc_user'" | Set-CimInstance -Property @{PasswordExpires="False"}
```
1. Download and install the [PsExec utility](https://docs.microsoft.com/en-us/sysinternals/downloads/psexec) from Microsoft on the device.
1. Use the PsExec utility to store the user name and password for the default user in the Credential Manager instance for the LocalSystem account. Replace *password* with the user's password that you set earlier.
```
psexec -s cmd /c cmdkey /generic:ggc_user /user:ggc_user /pass:password
```
If the **PsExec License Agreement** opens, choose **Accept** to agree to the license and run the command.
**Note**
On Windows devices, the LocalSystem account runs the Greengrass nucleus, and you must use the PsExec utility to store the default user information in the LocalSystem account. Using the Credential Manager application stores this information in the Windows account of the currently logged on user, instead of the LocalSystem account.
## Download the AWS IoT Greengrass Core software
You can download the latest version of the AWS IoT Greengrass Core software from the following location:
+ [https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip](https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip)
**Note**
You can download a specific version of the AWS IoT Greengrass Core software from the following location. Replace *version* with the version to download.
```
https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-version.zip
```
**To download the AWS IoT Greengrass Core software**
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. (Optional) To verify the Greengrass nucleus software signature
**Note**
This feature is available with Greengrass nucleus version 2.9.5 and later.
1. Use the following command to verify your Greengrass nucleus artifact's signature:
------
#### [ Linux or Unix ]
```
jarsigner -verify -certs -verbose greengrass-nucleus-latest.zip
```
------
#### [ Windows Command Prompt (CMD) ]
The file name might look different depending on the JDK version you install. Replace *`jdk17.0.6_10`* with the JDK version you installed.
```
"C:\\Program Files\\Amazon Corretto\\jdk17.0.6_10\\bin\\jarsigner.exe" -verify -certs -verbose greengrass-nucleus-latest.zip
```
------
#### [ PowerShell ]
The file name might look different depending on the JDK version you install. Replace *`jdk17.0.6_10`* with the JDK version you installed.
```
'C:\\Program Files\\Amazon Corretto\\jdk17.0.6_10\\bin\\jarsigner.exe' -verify -certs -verbose greengrass-nucleus-latest.zip
```
------
1. The `jarsigner` invocation yields output that indicates the results of the verification.
1. If the Greengrass nucleus zip file is signed, the output contains the following statement:
```
jar verified.
```
1. If the Greengrass nucleus zip file isn't signed, the output contains the following statement:
```
jar is unsigned.
```
1. If you provided the Jarsigner `-certs` option along with `-verify` and `-verbose` options, the output also includes detailed signer certificate information.
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. (Optional) Run the following command to see the version of the AWS IoT Greengrass Core software.
```
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
```
**Important**
If you install a version of the Greengrass nucleus earlier than v2.4.0, don't remove this folder after you install the AWS IoT Greengrass Core software. The AWS IoT Greengrass Core software uses the files in this folder to run.
If you downloaded the latest version of the software, you install v2.4.0 or later, and you can remove this folder after you install the AWS IoT Greengrass Core software.
## Install the AWS IoT Greengrass Core software
Run the installer with arguments that specify the following actions:
+ Install from a partial configuration file that specifies to use your custom provisioning plugin to provision AWS resources. The AWS IoT Greengrass Core software uses a configuration file that specifies the configuration of every Greengrass component on the device. The installer creates a complete configuration file from the partial configuration file that you provide and the AWS resources that the custom provisioning plugin creates.
+ 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.
+ 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.
For more information about the arguments that you can specify, see [Installer arguments](configure-installer.md).
**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).
**To install the AWS IoT Greengrass Core software (Linux)**
1. Check the version of the AWS IoT Greengrass Core software.
+ Replace *GreengrassInstaller* with the path to the folder that contains the software.
```
java -jar ./GreengrassInstaller/lib/Greengrass.jar --version
```
1. Use a text editor to create a configuration file named `config.yaml` to provide to the installer.
For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.
```
nano GreengrassInstaller/config.yaml
```
Copy the following YAML content into the file.
```
---
system:
rootpath: "/greengrass/v2"
# The following values are optional. Return them from the provisioning plugin or set them here.
# certificateFilePath: ""
# privateKeyPath: ""
# rootCaPath: ""
# thingName: ""
services:
aws.greengrass.Nucleus:
version: "2.17.0"
configuration:
# The following values are optional. Return them from the provisioning plugin or set them here.
# awsRegion: ""
# iotRoleAlias: ""
# iotDataEndpoint: ""
# iotCredEndpoint: ""
com.example.CustomProvisioning:
configuration:
# You can specify configuration parameters to provide to your plugin.
# pluginParameter: ""
```
Then, do the following:
+ Replace *2.17.0* with the version of the AWS IoT Greengrass Core software.
+ Replace each instance of `/greengrass/v2` with the Greengrass root folder.
+ (Optional) Specify system and nucleus configuration values. You must set these values if your provisioning plugin doesn't provide them.
+ (Optional) Specify configuration parameters to provide to your provisioning plugin.
**Note**
In this configuration file, you can customize other configuration options, such as the ports and network proxy to use, as shown in the following example. For more information, see [Greengrass nucleus configuration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration).
```
---
system:
rootpath: "/greengrass/v2"
# The following values are optional. Return them from the provisioning plugin or set them here.
# certificateFilePath: ""
# privateKeyPath: ""
# rootCaPath: ""
# thingName: ""
services:
aws.greengrass.Nucleus:
version: "2.17.0"
configuration:
mqtt:
port: 443
greengrassDataPlanePort: 443
networkProxy:
noProxyAddresses: "http://192.168.0.1,www.example.com"
proxy:
url: "http://my-proxy-server:1100"
username: "Mary_Major"
password: "pass@word1357"
# The following values are optional. Return them from the provisioning plugin or set them here.
# awsRegion: ""
# iotRoleAlias: ""
# iotDataEndpoint: ""
# iotCredEndpoint: ""
com.example.CustomProvisioning:
configuration:
# You can specify configuration parameters to provide to your plugin.
# pluginParameter: ""
```
1. Run the installer. Specify `--trusted-plugin` to provide your custom provisioning plugin, and specify `--init-config` to provide the configuration file.
**Note**
Windows has a path length limitation of 260 characters. If you are using Windows, use a root folder like `C:\greengrass\v2` or `D:\greengrass\v2` to keep the Greengrass components paths under the 260 character limit.
+ Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the Greengrass root folder.
+ Replace each instance of *GreengrassInstaller* with the folder where you unpacked the installer.
+ Replace the path to the custom provisioning plugin JAR file with the path to your plugin's JAR file.
------
#### [ Linux or Unix ]
```
sudo -E java -Droot="/greengrass/v2" -Dlog.store=FILE \
-jar ./GreengrassInstaller/lib/Greengrass.jar \
--trusted-plugin /path/to/com.example.CustomProvisioning.jar \
--init-config ./GreengrassInstaller/config.yaml \
--component-default-user ggc_user:ggc_group \
--setup-system-service true
```
------
#### [ Windows Command Prompt (CMD) ]
```
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" ^
-jar ./GreengrassInstaller/lib/Greengrass.jar ^
--trusted-plugin /path/to/com.example.CustomProvisioning.jar ^
--init-config ./GreengrassInstaller/config.yaml ^
--component-default-user ggc_user ^
--setup-system-service true
```
------
#### [ PowerShell ]
```
java -Droot="C:\greengrass\v2" "-Dlog.store=FILE" `
-jar ./GreengrassInstaller/lib/Greengrass.jar `
--trusted-plugin /path/to/com.example.CustomProvisioning.jar `
--init-config ./GreengrassInstaller/config.yaml `
--component-default-user ggc_user `
--setup-system-service true
```
------
**Important**
On Windows core devices, you must specify `--setup-system-service true` to set up the AWS IoT Greengrass Core software as a system service.
If you specify `--setup-system-service true`, the installer prints `Successfully set up Nucleus as a system service` if it set up and ran the software as a system service. Otherwise, the installer doesn't output any message if it installs the software successfully.
**Note**
You can't use the `deploy-dev-tools` argument to deploy local development tools when you run the installer without the `--provision true` argument. For information about deploying the Greengrass CLI directly on your device, see [Greengrass Command Line Interface](gg-cli.md).
1. Verify the installation by viewing the files in the root folder.
------
#### [ Linux or Unix ]
```
ls /greengrass/v2
```
------
#### [ Windows Command Prompt (CMD) ]
```
dir C:\greengrass\v2
```
------
#### [ PowerShell ]
```
ls C:\greengrass\v2
```
------
If the installation succeeded, the root folder contains several folders, such as `config`, `packages`, and `logs`.
If you installed the AWS IoT Greengrass Core software as a system service, the installer runs the software for you. Otherwise, you must run the software manually. For more information, see [Run the AWS IoT Greengrass Core software](run-greengrass-core-v2.md).
For more information about how to configure and use the software and AWS IoT Greengrass, see the following:
+ [Configure the AWS IoT Greengrass Core software](configure-greengrass-core-v2.md)
+ [Develop AWS IoT Greengrass components](develop-greengrass-components.md)
+ [Deploy AWS IoT Greengrass components to devices](manage-deployments.md)
+ [Greengrass Command Line Interface](gg-cli.md)
# Develop custom provisioning plugins
To develop a custom provisioning plugin, create a Java class that implements the `com.aws.greengrass.provisioning.DeviceIdentityInterface` interface. You can include the Greengrass nucleus JAR file in your project to access this interface and its classes. This interface defines a method that inputs a plugin configuration and outputs a provisioning configuration. The provisioning configuration defines configurations for the system and the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software installer uses this provisioning configuration to configure the AWS IoT Greengrass Core software on a device.
After you develop a custom provisioning plugin, build it as a JAR file that you can provide to the AWS IoT Greengrass Core software installer to run your plugin during installation. The installer runs your custom provisioning plugin in the same JVM that the installer uses, so you can create a JAR that contains only your plugin code.
**Note**
The [AWS IoT fleet provisioning plugin](fleet-provisioning.md) implements the `DeviceIdentityInterface` to use fleet provisioning during installation. The fleet provisioning plugin is open source, so you can explore its source code to see an example of how to use the provisioning plugin interface. For more information, see the [AWS IoT fleet provisioning plugin](https://github.com/aws-greengrass/aws-greengrass-fleet-provisioning-by-claim) on GitHub.
**Topics**
+ [Requirements](#custom-provisioning-plugin-requirements)
+ [Implement the DeviceIdentityInterface interface](#implement-device-identity-interface)
## Requirements
To develop a custom provisioning plugin, you must create a Java class that meets the following requirements:
+ Uses the `com.aws.greengrass` package, or a package within the `com.aws.greengrass` package.
+ Has a constructor without any arguments.
+ Implements the `DeviceIdentityInterface` interface. For more information, see [Implement the DeviceIdentityInterface interface](#implement-device-identity-interface).
## Implement the DeviceIdentityInterface interface
To use the `com.aws.greengrass.provisioning.DeviceIdentityInterface` interface in your custom plugin, add the Greengrass nucleus as a dependency to your project.
**To use the DeviceIdentityInterface in a custom provisioning plugin project**
+ You can add the Greengrass nucleus JAR file as a library, or add the Greengrass nucleus as a Maven dependency. Do one of the following:
+ To add the Greengrass nucleus JAR file as a library, download the AWS IoT Greengrass Core software, which contains the Greengrass nucleus JAR. You can download the latest version of the AWS IoT Greengrass Core software from the following location:
+ [https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip](https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-nucleus-latest.zip)
You can find the Greengrass nucleus JAR file (`Greengrass.jar`) in the `lib` folder in the ZIP file. Add this JAR file to your project.
+ To consume the Greengrass nucleus in a Maven project, add a dependency the on the `nucleus` artifact in the `com.aws.greengrass` group. You must also add the `greengrass-common` repository, because the Greengrass nucleus isn't available in the Maven Central Repository.
```
...
greengrass-common
greengrass common
https://d2jrmugq4soldf.cloudfront.net/snapshots
...
com.aws.greengrass
nucleus
2.5.0-SNAPSHOT
provided
```
### The DeviceIdentityInterface interface
The `com.aws.greengrass.provisioning.DeviceIdentityInterface` interface has the following shape.
**Note**
You can also explore these classes in the [com.aws.greengrass.provisioning package](https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/provisioning) of the [Greengrass nucleus source code](https://github.com/aws-greengrass/aws-greengrass-nucleus) on GitHub.
```
public interface com.aws.greengrass.provisioning.DeviceIdentityInterface {
ProvisionConfiguration updateIdentityConfiguration(ProvisionContext context)
throws RetryableProvisioningException, InterruptedException;
// Return the name of the plugin.
String name();
}
com.aws.greengrass.provisioning.ProvisionConfiguration {
SystemConfiguration systemConfiguration;
NucleusConfiguration nucleusConfiguration
}
com.aws.greengrass.provisioning.ProvisionConfiguration.SystemConfiguration {
String certificateFilePath;
String privateKeyPath;
String rootCAPath;
String thingName;
}
com.aws.greengrass.provisioning.ProvisionConfiguration.NucleusConfiguration {
String awsRegion;
String iotCredentialsEndpoint;
String iotDataEndpoint;
String iotRoleAlias;
}
com.aws.greengrass.provisioning.ProvisioningContext {
Map parameterMap;
String provisioningPolicy; // The policy is always "PROVISION_IF_NOT_PROVISIONED".
}
com.aws.greengrass.provisioning.exceptions.RetryableProvisioningException {}
```
Each configuration value in the `SystemConfiguration` and `NucleusConfiguration` is required to install the AWS IoT Greengrass Core software, but you can return `null`. If your custom provisioning plugin returns `null` for any configuration value, you must provide that value in the system or nucleus configuration when you create the `config.yaml` file to provide to the AWS IoT Greengrass Core software installer. If your custom provisioning plugin returns a non-null value for an option that you also define in `config.yaml`, then the installer replaces the value in `config.yaml` with the value returned by the plugin.
# Installer arguments
The AWS IoT Greengrass Core software includes an installer that sets up the software and provisions the required AWS resources for the Greengrass core device to run. The installer includes the following arguments that you can specify to configure the installation:
`-h`, `--help`
(Optional) Show the installer's help information.
`--version`
(Optional) Show the version of the AWS IoT Greengrass Core software.
`-Droot`
(Optional) The path to the folder to use as the root for the AWS IoT Greengrass Core software.
This argument sets a JVM property, so you must specify it before `-jar` when you run the installer. For example, specify `java -Droot="/greengrass/v2" -jar /path/to/Greengrass.jar`.
Default:
+ Linux: `~/.greengrass`
+ Windows: `%USERPROFILE%/.greengrass`
`-ar`, `--aws-region`
The AWS Region that the AWS IoT Greengrass Core software uses to retrieve or create its required AWS resources.
`-p`, `--provision`
(Optional) You can register this device as an AWS IoT thing and provision the AWS resources that the core device requires. If you specify `true`, the AWS IoT Greengrass Core software provisions an AWS IoT thing, (optional) an AWS IoT thing group, an IAM role, and an AWS IoT role alias.
Default: `false`
`-tn`, `--thing-name`
(Optional) The name of the AWS IoT thing that you register as this core device. If the thing with the name doesn't exist in your AWS account, the AWS IoT Greengrass Core software creates it.
The thing name can't contain colon (`:`) characters.
You must specify `--provision true` to apply this argument.
Default: `GreengrassV2IotThing_` plus a random UUID.
`-tgn`, `--thing-group-name`
(Optional) The name of the AWS IoT thing group where you add this core device's AWS IoT thing. If a deployment targets this thing group, this core device receives that deployment when it connects to AWS IoT Greengrass. If the thing group with this name doesn't exist in your AWS account, the AWS IoT Greengrass Core software creates it.
The thing group name can't contain colon (`:`) characters.
You must specify `--provision true` to apply this argument.
`-tpn`, `--thing-policy-name`
This feature is available for v2.4.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md).
(Optional) The name of the AWS IoT policy to attach to this core device's AWS IoT thing certificate. If the AWS IoT policy with this name doesn't exist in your AWS account, the AWS IoT Greengrass Core software creates it.
The AWS IoT Greengrass Core software creates a permissive AWS IoT policy by default. You can scope down this policy, or create a custom policy where you restrict permissions for your 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).
You must specify `--provision true` to apply this argument.
Default: `GreengrassV2IoTThingPolicy`
`-trn`, `--tes-role-name`
(Optional) The name of the IAM role to use to acquire AWS credentials that let the core device interact with AWS services. If the role with this name doesn't exist in your AWS account, the AWS IoT Greengrass Core software creates it with the `GreengrassV2TokenExchangeRoleAccess` policy. This role doesn't have access to your S3 buckets where you host component artifacts. So, you must add permissions to your artifacts' S3 buckets and objects when you create a component. For more information, see [Authorize core devices to interact with AWS services](device-service-role.md).
You must specify `--provision true` to apply this argument.
Default: `GreengrassV2TokenExchangeRole`
`-tra`, `--tes-role-alias-name`
(Optional) The name of the AWS IoT role alias that points to the IAM role that provides AWS credentials for this core device. If the role alias with this name doesn't exist in your AWS account, the AWS IoT Greengrass Core software creates it and points it to the IAM role that you specify.
You must specify `--provision true` to apply this argument.
Default: `GreengrassV2TokenExchangeRoleAlias`
`-ss`, `--setup-system-service`
(Optional) You can set up the AWS IoT Greengrass Core software as a system service that runs when this device boots. The system service name is `greengrass`. For more information, see [Configure the Greengrass nucleus as a system service](configure-greengrass-core-v2.md#configure-system-service).
On Linux operating systems, this argument requires that the systemd init system is available on the device.
On Windows core devices, you must set up the AWS IoT Greengrass Core software as a system service.
Default: `false`
`-u`, `--component-default-user`
The name or ID of the user that the AWS IoT Greengrass Core software uses to run components. For example, you can specify **ggc\$1user**. This value is required when you run the installer on Windows operating systems.
On Linux operating systems, you can also optionally specify the group. Specify the user and group separated by a colon. For example, **ggc\$1user:ggc\$1group**.
The following additional considerations apply for Linux operating systems:
+ If you run as root, the default component user is the user that is defined in the configuration file. If the configuration file doesn't define a user, this defaults to `ggc_user:ggc_group`. If `ggc_user` or `ggc_group` don't exist, the software creates them.
+ If you run as a non-root user, the AWS IoT Greengrass Core software uses that user to run components.
+ If you don't specify a group, the AWS IoT Greengrass Core software uses the primary group of the system user.
For more information, see [Configure the user that runs components](configure-greengrass-core-v2.md#configure-component-user).
`-d`, `--deploy-dev-tools`
(Optional) You can download and deploy the [Greengrass CLI](greengrass-cli-component.md) component to this core device. You can use this tool to develop and debug components on this core device.
We recommend that you use this component in only development environments, not production environments. This component provides access to information and operations that you typically won't need in a production environment. Follow the principle of least privilege by deploying this component to only core devices where you need it.
You must specify `--provision true` to apply this argument.
Default: `false`
`-init`, `--init-config`
(Optional) The path to the configuration file to use to install the AWS IoT Greengrass Core software. You can use this option to set up new core devices with a specific nucleus configuration, for example.
The configuration file that you specify merges with the existing configuration file on the core device. This includes the components and component configurations on the core device. We recommend the configuration file only lists the configurations that you are trying to change.
`-tp`, `--trusted-plugin`
(Optional) The path to a JAR file to load as a trusted plugin. Use this option to provide provisioning plugin JAR files, such as to install with [fleet provisioning](fleet-provisioning.md) or [custom provisioning](custom-provisioning.md), or to install with the private key and certificate in a [hardware security module](hardware-security.md).
`-s`, `--start`
(Optional) You can start the AWS IoT Greengrass Core software after it installs and, optionally, provisions resources.
Default: `true`