# 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. |